Guardrails, tenancy & deletion

The gate

Publishability is a join key, not a check you remember to run

Four things have to be true before a block reaches a child: it passed the rubric, a human with the right role approved it, every asset in it has usable rights, and its alignment claim is one the district accepts. Model those as four checks and you have four things to forget. Model them as an inner join and there is no code path that produces a publishable lesson without them.

• You could write this with outer joins and predicates in the WHERE clause. The result set would be identical and the design would be far worse. A WHERE clause is a line someone deletes at six on a Friday while chasing an empty-lesson bug, and the query keeps running and returns more rows, which looks like the fix. An inner join to a required table cannot be edited out without the query failing loudly.
• The accepted alignment classes come from district config, not the query. Post 2’s classes become a policy parameter: a district that refuses inferred alignment gets fewer lessons, visibly, rather than the same lessons with a different label.
• Asset rights have an expiry, and expiry is a join predicate. A licensed image whose term ended last month must stop being publishable without anyone running a job.
• Review receipts are keyed by version. Approving version 3 does not approve version 4. That single line is what makes the editor safe.

SELECT v.lesson_id, v.version, b.block_hash
  FROM lesson_versions       AS v
  JOIN lesson_version_blocks AS vb ON vb.lesson_id = v.lesson_id AND vb.version = v.version
  JOIN blocks                AS b  ON b.block_hash = vb.block_hash
  -- Every join below is a requirement. None of them is a WHERE clause.
  JOIN gate_decisions        AS g  ON g.block_hash = b.block_hash
                                  AND g.rubric_version = $3
                                  AND g.result = 'pass'
  JOIN review_receipts       AS r  ON r.lesson_id = v.lesson_id
                                  AND r.version   = v.version
                                  AND r.role IN ('curriculum_reviewer', 'safety_reviewer')
  JOIN asset_rights          AS ar ON ar.asset_id = ANY (b.asset_ids)
                                  AND ar.usable_in_district = $1
                                  AND ar.expires_at > now()
  JOIN alignment_edges       AS ae ON ae.source_node = 'lesson:' || v.lesson_id
                                  AND ae.edge_class = ANY ($5)   -- district's accepted classes
                                  AND ae.revoked_at IS NULL
 WHERE v.district_id = $1 AND v.env = $2;

The corollary is an interface requirement rather than a backend one: because approval is keyed to a version, editing an approved lesson must visibly return it to review. A product that lets a teacher edit after approval without changing its state is not saving her a step; it is silently publishing unreviewed content under someone else’s signature.

The editor

Every edit is an observation, and observations are the product

The editor is where the real work happens, and the architectural decision is whether an edit is a mutation or an event. Make it a mutation and you get a simple interface and lose everything. Make it an event and post 3’s entire feedback corpus falls out for free.

• An edit produces a new version, never a modified one. Blocks are content-addressed and immutable, so an edit is: hash the new text, write a new block, write a new version whose block list differs in one position. Undo is selecting an earlier version.
• The operation is recorded, not just the outcome. Replace, delete, insert, swap-asset and regenerate are different signals about your generator, and a diff between two block lists cannot tell them apart.
• Ask why, cheaply, once. A row of reason chips — too hard, wrong for my class, inaccurate, style — attached to a delete or a large rewrite converts an unlabelled signal into a labelled one at the cost of one click.
• Regeneration is an edit with a prompt attached. When a teacher regenerates one block, the request, the objective and the surrounding blocks all go into the provenance, because “regenerate this in the context of that” is the most informative thing she ever does.

export type EditOp =
  | { kind: "replace";     position: number; newBlockHash: string }
  | { kind: "delete";      position: number }
  | { kind: "insert";      position: number; newBlockHash: string }
  | { kind: "swap_asset";  position: number; assetId: string; newAssetId: string }
  | { kind: "regenerate";  position: number; instruction: string | null };

export interface EditEvent {
  lessonId: string;          // "lsn_4c19"
  fromVersion: number;       // 3
  toVersion: number;         // 4 — always a new version, never a mutation
  op: EditOp;
  replacedBlockHash: string | null;
  actor: string;             // "usr_2210"
  reason: "too_hard" | "wrong_for_class" | "inaccurate" | "style" | null;   // one click, optional
  at: string;
}

/** Applying an edit is pure: old block list + op -> new block list. The event is the record. */
export function apply(blocks: readonly string[], op: EditOp): string[] {
  switch (op.kind) {
    case "replace":    return blocks.map((b, i) => (i === op.position ? op.newBlockHash : b));
    case "delete":     return blocks.filter((_, i) => i !== op.position);
    case "insert":     return [...blocks.slice(0, op.position), op.newBlockHash, ...blocks.slice(op.position)];
    case "swap_asset":
    case "regenerate": return blocks;   // both mint a new block hash upstream; the list is rewritten there
  }
}

/** A swapped-in image is a new asset with its own rights record. No exceptions for uploads. */
export interface AssetRights {
  assetId: string;
  source: "generated" | "licensed" | "uploaded" | "public_domain";
  licenceId: string | null;      // null is only valid for public_domain
  usableInDistricts: string[];   // an explicit list; "all" is not a value
  expiresAt: string | null;
  attributionRequired: boolean;
  reviewedBy: string | null;     // uploads require a human; generated images require a classifier pass
}

The uploaded case is the one teams get wrong. A teacher uploading her own photograph is the most natural action in the editor and the one with the least clear provenance — it may contain a child, it may be someone else’s work, it may be perfectly fine. It cannot be treated as pre-approved because a human chose it; that is precisely the assumption that puts a photograph of a real classroom into a package bound for another district.

Isolation

District and environment are partition keys, and the contractor login is why

Every row and query carries a district and an environment, and storage is namespaced by both. Post 1 defined that type and threaded it through; this post adds the layer underneath it, for when the application is not the thing making the query.

• Partition by district, always. Content tables, property tables and the publish ledger. Cross-district reads are not merely filtered, they are physically separate.
• Row-level security sits below the application. Application filters protect you from application bugs. A policy on the executing database role protects you from the SQL console, the reporting tool and the notebook someone ran on a Sunday.
• Roles are teacher, curriculum reviewer, safety reviewer, contractor and admin. Only a safety reviewer may clear a sensitivity hold; only a curriculum reviewer or an admin may approve a version for publish; a contractor is scoped to one district and cannot read student data at all.
• The contractor role is the honest reason. It is a login you do not administer, held by a freelance instructional designer who is also building units for a competing publisher next Tuesday. Design for that user and the internal cases take care of themselves.

ALTER TABLE lesson_versions ENABLE ROW LEVEL SECURITY;

CREATE POLICY district_scope ON lesson_versions
  FOR SELECT
  USING (district_id = current_setting('app.district_id', true)
     AND env         = current_setting('app.env', true));

-- Student interaction data is not merely scoped; contractors cannot see it at all.
ALTER TABLE student_interactions ENABLE ROW LEVEL SECURITY;
CREATE POLICY no_contractor_student_data ON student_interactions
  FOR SELECT
  USING (district_id = current_setting('app.district_id', true)
     AND current_setting('app.role', true) <> 'contractor');

export function scopeFromClaims(claims: JwtClaims): TenantScope & { role: Role; userId: string } {
  const roles = claims.roles ?? [];
  if (roles.length === 0) throw new ForbiddenError("no roles in token");     // fail closed
  if (!claims.district_id || !claims.env) throw new ForbiddenError("unscoped token");
  return {
    districtId: claims.district_id,
    env: claims.env as "dev" | "prod",
    role: pickHighest(roles),
    userId: claims.sub,
  };
}

An empty role list is a rejection, not a default. The failure you are avoiding is the one where a district’s identity provider stops emitting a claim after a routine upgrade and every token quietly becomes an unscoped one.

Deletion

A deletion that stops at your database is not a deletion

A records request, a parental opt-out, or a district offboarding lands as a tombstone. Deleting the rows is the easy part and the least of it — and one of the six steps below is different in kind from the others.

• The content side is straightforward. Blocks a teacher authored, lesson versions, edit events, review receipts — scoped, partitioned, deletable, with the mutation recorded as a receipt.
• The student side reaches outside. Interaction telemetry, but also the grade a passback wrote into a gradebook you do not own, and any free-text response cached anywhere in the scoring path.
• The publish ledger answers the question that matters. Which courses, in which platform instances, did this content reach, and under which publish id. Without it you cannot un-publish, and post 2’s alignment retractions cannot fan out either.
• And one destination cannot be reached at all. Which is the next section, and it is why the design decision comes before the first model.

export async function runDeletion(scope: TenantScope, subject: DeletionSubject): Promise<DsrResult> {
  const receipts: StepReceipt[] = [];
  for (const step of STEPS) {   // ordered: content, telemetry, ledger, LMS, gradebook, corpora
    try {
      receipts.push(await step.run(scope, subject));
    } catch (err) {
      // Do not swallow. The request stays open and visible until every step has a receipt.
      receipts.push({ step: step.id, status: "failed", error: String(err), at: nowIso() });
      await dsrStore.markIncomplete(scope, subject, receipts);
      throw new DeletionIncompleteError(subject.id, step.id);
    }
  }
  await dsrStore.markComplete(scope, subject, receipts);
  return { subject, status: "complete", receipts };
}

When a removal call fails — an expired token, a maintenance window, a course an administrator has locked — you retry with backoff, and until it succeeds the request is not complete. That state has to be visible: an open-request gauge with an age, alerting against your statutory clock, not a swallowed exception in a log nobody reads. A half-finished deletion looks exactly like a finished one from the inside.

Some destinations also accept a removal and give you no way to verify it landed. You cannot prove content is gone from someone else’s system; you can prove you asked. Record the request payload hash, the response status and the response body as the receipt, and describe it in exactly those terms in your own documentation. Overclaiming here is how a compliance answer becomes a false statement.

Audit

A trail, not a second copy of the content

One append-only line per publish, per gate-decision batch and per deletion. It is deliberately boring.

{"ts":"2026-08-25T14:22:07Z","district":"riverbend","env":"prod","actor":"publish-engine",
 "lessonId":"lsn_4c19","version":4,"courseId":"crs_88214","publishId":"pub_7f31",
 "blocksSent":14,"blocksRendered":12,"fidelity":0.857,"rubricVersion":"g3.2026-08",
 "approvedBy":"usr_2210","approvalRole":"curriculum_reviewer",
 "alignmentClasses":["authored","crosswalked"],
 "holdoutSections":2,"experimentId":"exp_fractions_pilot_q1"}

• Ids, counts and hashes only. No block bodies, no student text, no teacher free-text. An audit log containing the content is a second breach surface with worse retention rules than the first.
• The approver and their role are the reconstruction key. A year later, “who authorised this content reaching third graders in this district” has an answer that is a query rather than a meeting.
• Deletion lines carry the same shape. Actor, subject, and one receipt per step — enough to show a fan-out happened without restating what was deleted.
• Append-only, or it is not evidence. Object storage with versioning and a retention lock; a log you can edit proves nothing.

git clone https://github.com/xaviramirezcom/open-lesson-pipeline
cd open-lesson-pipeline
git checkout v4-guardrails
pnpm install && uv sync
pnpm lesson up
pnpm lesson seed

pnpm lesson approve lsn_4c19 --version 3 --as curriculum_reviewer
pnpm lesson publish lsn_4c19 --course crs_88214          # 14 blocks published

pnpm lesson edit lsn_4c19 --op replace --position 2 --text "$(cat fixtures/teacher_rewrite.md)"
pnpm lesson publish lsn_4c19 --course crs_88214          # refused: no receipt for version 4

pnpm lesson edit lsn_4c19 --op swap-asset --position 5 --upload fixtures/classroom_photo.jpg
pnpm lesson publish lsn_4c19 --course crs_88214          # refused: asset has no rights record

pnpm lesson dsr --subject student:stu_5512 --district riverbend --print-receipts

Explain it back