@everystack/cli 0.4.98 → 0.4.100

package/src/cli/model-render.ts

@@ -24,7 +24,7 @@ import { generatedIndexName, generatedForeignKeyName } from './schema-compile';
 // The soft-delete RULE itself — one boolean combination, shared with `defineModel`'s refusal.
 // Only the FACT EXTRACTION is duplicated here (this renderer holds text, not descriptors);
 // the rule is not, so the two surfaces cannot drift on when a declaration is required.
-import { needsSoftDeleteDeclaration, privilegesGrantDelete } from '@everystack/model';
+import { needsSoftDeleteDeclaration, privilegesGrantDelete, positionalCheckName } from '@everystack/model';
 
 /**
  * Reverse a CHECK predicate back into the `.validate(z…)` that produced it — the inverse of
@@ -599,8 +599,18 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
   for (const u of table.uniques) {
     if (u.columns.length > 1) items.push(`unique(${u.columns.map((c) => tsLiteral(toCamelCase(c))).join(', ')})`);
   }
+  // R9 — a check keeps the name the database has. Said only when it is NOT the positional name
+  // the compiler would give it: position counts only the checks rendered bare, exactly as the
+  // compiler counts only unnamed ones, so every pulled check compiles back to its live name.
+  let position = 0;
   for (const ck of checks) {
-    items.push(`check(sql\`${normalizeCheck(ck.expr)}\`)`);
+    const predicate = `sql\`${normalizeCheck(ck.expr)}\``;
+    if (ck.name === positionalCheckName(bareName(table.table), position)) {
+      items.push(`check(${predicate})`);
+      position++;
+    } else {
+      items.push(`check(${predicate}, { name: ${tsLiteral(ck.name)} })`);
+    }
   }
   for (const ix of table.indexes) {
     // Plain entries render as field keys; canonical-text entries (expressions, DESC,
@@ -655,9 +665,15 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
   const validates = new Map<string, string>();
   const columnNames = new Set(table.columns.map((c) => c.name));
   const tableChecks: CheckConstraint[] = [];
+  // A `.validate()` compiles to a CHECK named `<table>_<column>_check`. When a DIFFERENT live
+  // check already holds that name, folding this one into the field would give the model two
+  // constraints under one name, so it stays a table-level check and keeps its own.
+  const liveCheckNames = new Set(table.checks.map((ck) => ck.name));
   for (const ck of table.checks) {
     const v = checkToValidate(ck.expr);
-    if (v && columnNames.has(v.column) && !validates.has(v.column)) validates.set(v.column, v.zod);
+    const fieldCheckName = v ? `${bareName(table.table)}_${v.column}_check` : '';
+    const nameFree = ck.name === fieldCheckName || !liveCheckNames.has(fieldCheckName);
+    if (v && columnNames.has(v.column) && !validates.has(v.column) && nameFree) validates.set(v.column, v.zod);
     else tableChecks.push(ck);
   }
 

package/src/cli/mutation-lease.ts

@@ -179,6 +179,11 @@ export function leaseSession(): string {
  * write of the verb. A verb that opens a SECOND connection mid-body has a writer the lease
  * does not cover.
  *
+ * That connection must fail CLOSED when its backend dies: hand this a fenced runner
+ * (connection-fence.ts — `createUrlRunner` and the server's mutation connection both are).
+ * An unfenced postgres.js pool reconnects onto a new backend after a loss, so the rest of the
+ * body would run without the lease; the lease's own release below would too.
+ *
  * HONEST LIMITATION (do not overstate): this is CONVENTIONALLY enforced, not runtime-enforced.
  * A PostgreSQL connection carries no read/write intent the connection layer can inspect, so
  * "reject a second connection" is unrealizable in-process. The counterexample is already in the

package/src/cli/plain-output.ts

@@ -77,6 +77,16 @@ function head(statement: string): string {
   return body === '' ? statement.replace(/\s+/g, ' ').trim() : body;
 }
 
+/**
+ * Match report marks by the whole statement with ONLY outer whitespace removed, on both sides.
+ * `head` is a description, not an identity: collapsing whitespace can change literals and
+ * function bodies. Internal formatting, comments, case and terminators must still match exactly.
+ * This key never replaces the original SQL passed to descriptions or returned to callers.
+ */
+function statementKey(statement: string): string {
+  return statement.trim();
+}
+
 /** The whole statement as one line, comments stripped and truncated — for the fallback description. */
 function oneLine(statement: string): string {
   const body = head(statement).replace(/;$/, '');
@@ -339,7 +349,8 @@ function objectKey(s: string): { verb: 'drop' | 'create'; key: string } | null {
  * definition edit. So the drop is removed and its create is marked `rebuilt`, which renders as
  * the update line it always was.
  *
- * Statements this does not recognise pass through untouched, in order.
+ * Statements this does not recognise pass through untouched, in order. Returned statements keep
+ * their original text; `rebuilt` holds statementKey values (outer whitespace removed).
  */
 export function collapseRebuilds(statements: readonly string[]): {
   statements: string[];
@@ -355,7 +366,7 @@ export function collapseRebuilds(statements: readonly string[]): {
   for (const s of statements) {
     const k = objectKey(head(s));
     if (k?.verb === 'drop' && created.has(k.key)) {
-      rebuilt.add(created.get(k.key)!);
+      rebuilt.add(statementKey(created.get(k.key)!));
       continue;
     }
     kept.push(s);
@@ -378,8 +389,9 @@ const plural = (n: number, one: string, many: string): string => (n === 1 ? one
 
 /** One change line, indented, already carrying its mark. */
 function changeLine(statement: string, destructive: ReadonlySet<string>, rebuilt?: ReadonlySet<string>): string {
-  if (destructive.has(statement)) return `  ${DESTRUCTIVE_MARK} — ${describeDestructive(statement)}`;
-  const { symbol, text } = describeChange(statement, { rebuilt: rebuilt?.has(statement) === true });
+  const key = statementKey(statement);
+  if (destructive.has(key)) return `  ${DESTRUCTIVE_MARK} — ${describeDestructive(statement)}`;
+  const { symbol, text } = describeChange(statement, { rebuilt: rebuilt?.has(key) === true });
   return `  ${symbol} ${text}`;
 }
 
@@ -398,7 +410,7 @@ function changeLines(
 export interface PlanReportInput {
   /** The real DDL the plan will run — notices and held drops are not changes. */
   executable: readonly string[];
-  /** The destructive subset, as the apply gate classifies it. Must be members of `executable`. */
+  /** The apply gate's destructive subset. Must match `executable` apart from outer whitespace. */
   destructive: readonly string[];
   /** What the plan is aimed at, in the reader's words: a stage name, or `local`. */
   target: string;
@@ -415,7 +427,7 @@ export function renderPlanReport(input: PlanReportInput): string[] {
   const { executable, target, stage, planPath, verbose = false } = input;
   if (executable.length === 0) return ['Up to date. Nothing to plan.'];
 
-  const destructive = new Set(input.destructive);
+  const destructive = new Set(input.destructive.map(statementKey));
   const lines: string[] = [
     `Plan: ${executable.length} ${plural(executable.length, 'change', 'changes')} (${target})`,
     '',
@@ -440,6 +452,7 @@ export function renderPlanReport(input: PlanReportInput): string[] {
 
 export interface ApplyReceiptInput {
   executable: readonly string[];
+  /** The apply gate's destructive subset. Must match `executable` apart from outer whitespace. */
   destructive: readonly string[];
   /** The target was already where the plan ends — an idempotent re-apply. */
   alreadyApplied?: boolean;
@@ -461,7 +474,7 @@ export function renderApplyReceipt(input: ApplyReceiptInput): string[] {
   const n = executable.length;
   const tally = `Applied ${n} ${plural(n, 'change', 'changes')}.`;
   if (n === 0 || n > MAX_RECEIPT_CHANGES) return [tally];
-  return [...changeLines(executable, new Set(input.destructive), MAX_RECEIPT_CHANGES, rebuilt), '', tally];
+  return [...changeLines(executable, new Set(input.destructive.map(statementKey)), MAX_RECEIPT_CHANGES, rebuilt), '', tally];
 }
 
 export interface CatchUpFailureInput {
@@ -529,7 +542,16 @@ function sentence(text: string): string {
 }
 
 /** db:check's default output: one line, always. */
-export function renderCheckVerdict(pending: number): string[] {
-  if (pending === 0) return ['Up to date.'];
-  return [`${pending} ${plural(pending, 'change', 'changes')} pending. Run db:plan to review.`];
+export function renderCheckVerdict(pending: number, warnings = 0): string[] {
+  if (warnings === 0) {
+    if (pending === 0) return ['Up to date.'];
+    return [`${pending} ${plural(pending, 'change', 'changes')} pending. Run db:plan to review.`];
+  }
+  // Warnings never fail the gate, but a clean-looking line would hide them.
+  const warned = `${warnings} ${plural(warnings, 'warning', 'warnings')}`;
+  const readThem = `db:check --verbose to read ${warnings === 1 ? 'it' : 'them'}`;
+  if (pending === 0) return [`Up to date, ${warned}. Run ${readThem}.`];
+  return [
+    `${pending} ${plural(pending, 'change', 'changes')} pending, ${warned}. Run db:plan to review, db:check --verbose to read the ${plural(warnings, 'warning', 'warnings')}.`,
+  ];
 }

package/src/cli/runbook/model-section.ts

@@ -7,6 +7,7 @@
  * have — and an ability change shows up as runbook drift (`runbook --check`).
  */
 
+import { ModelLinkError } from '@everystack/model';
 import type { Ability, FieldSpec, ModelDescriptor, Relation } from '@everystack/model';
 
 function typeLabel(spec: FieldSpec): string {
@@ -35,7 +36,8 @@ function referenceTarget(spec: FieldSpec): string | null {
   try {
     const target = spec.references() as { table?: string } | undefined;
     return target?.table ?? 'unknown';
-  } catch {
+  } catch (err) {
+    if (err instanceof ModelLinkError) throw err;
     return 'unknown';
   }
 }
@@ -73,7 +75,8 @@ function relationLine(name: string, rel: Relation): string {
   let target = 'unknown';
   try {
     target = rel.target().table;
-  } catch {
+  } catch (err) {
+    if (err instanceof ModelLinkError) throw err;
     /* forward reference that can't resolve here — label stays unknown */
   }
   const shape = rel.kind === 'belongsTo' ? 'belongs to' : 'has many';

package/src/cli/schema-compile.ts

@@ -20,6 +20,7 @@
  */
 
 import type { ModelDescriptor, FieldSpec, SequenceDescriptor } from '@everystack/model';
+import { positionalCheckName } from '@everystack/model';
 import type { TableSchema, EnumType, SequenceSchema, UniqueConstraint, CheckConstraint, IndexSchema, ForeignKey } from './schema-introspect';
 import { nextvalSequence, identityClause, type RenameMap } from './schema-diff';
 import { normalizeDeparsedExpr } from './deparse-normal';
@@ -59,6 +60,13 @@ export function modelConstraintSpecs(model: ModelDescriptor): { uniques: UniqueC
   const indexes: IndexSchema[] = [];
   let checkIndex = 0;
   const usedIndexNames = new Set<string>();
+  // A field's `.validate()` CHECK is named `<table>_<column>_check`; a declared table check may
+  // not take that name, or CREATE TABLE fails with two constraints under one name.
+  const fieldCheckNames = new Map<string, string>();
+  for (const [key, field] of Object.entries(model.fields)) {
+    const col = toSnakeCase(key);
+    if (fieldCheckPredicate(col, field.spec)) fieldCheckNames.set(`${model.table}_${col}_check`, key);
+  }
   for (const con of model.constraints) {
     if (con.kind === 'unique') {
       const cols = con.columns.map(toSnakeCase);
@@ -67,7 +75,20 @@ export function modelConstraintSpecs(model: ModelDescriptor): { uniques: UniqueC
       // Normalized like the live producer (schema-introspect): a model that transcribes a
       // pulled predicate must compare equal to the database it came from, whichever of the
       // two equivalent deparse spellings each side happens to hold. See deparse-normal.ts.
-      checks.push({ name: `${model.table}_check_${checkIndex++}`, expr: normalizeDeparsedExpr(con.predicate) });
+      //
+      // A DECLARED name is used verbatim and takes no position, so naming one check never
+      // renames its unnamed siblings; defineModel already refused duplicates and collisions
+      // with a positional name.
+      if (con.name !== undefined && fieldCheckNames.has(con.name)) {
+        throw new Error(
+          `model '${model.table}': check(sql\`${con.predicate}\`) is named '${con.name}', the name of the CHECK that field '${fieldCheckNames.get(con.name)}'.validate() compiles to. Choose another name.`,
+        );
+      }
+      checks.push({
+        name: con.name ?? positionalCheckName(model.table, checkIndex++),
+        expr: normalizeDeparsedExpr(con.predicate),
+        ...(con.name !== undefined ? { nameDeclared: true } : {}),
+      });
     } else if (con.kind === 'index') {
       // Plain entries are field keys → snake_cased; raw sql`` entries (expressions,
       // DESC, opclass) pass verbatim — they are already SQL (Brick E).

package/src/cli/schema-diff.ts

@@ -33,6 +33,7 @@ import type {
   IndexSchema,
   SequenceSchema,
 } from './schema-introspect';
+import { renderConstraintRename, renderIndexRename } from './catalog-rename';
 
 // ---------------------------------------------------------------------------
 // The change set.
@@ -849,8 +850,12 @@ export function foreignKeyContentKey(
  * same predicate is the same check no matter what it's called, so a pulled check (whose DB
  * name we didn't choose) re-generates clean. A changed predicate drops the old (by its real
  * name) and adds the new.
+ *
+ * R9, the CHECK half of B3/A8: a predicate match whose DECLARED name disagrees with the live
+ * one is the same check under another name — `RENAME CONSTRAINT`, catalog-only, no re-scan.
+ * An undeclared (positional) name never renames the database.
  */
-function diffChecks(d: TableSchema, c: TableSchema, dropConstraints: SchemaChange[], addConstraints: SchemaChange[]): void {
+function diffChecks(d: TableSchema, c: TableSchema, dropConstraints: SchemaChange[], addConstraints: SchemaChange[], renames: SchemaChange[]): void {
   const desiredByPred = new Map(d.checks.map((ck) => [normalizeCheck(ck.expr), ck]));
   const currentByPred = new Map(c.checks.map((ck) => [normalizeCheck(ck.expr), ck]));
   // Paren-blind lookup, diagnostic only (see diffIndexes): a compound CHECK churns for the
@@ -860,7 +865,11 @@ function diffChecks(d: TableSchema, c: TableSchema, dropConstraints: SchemaChang
     if (!desiredByPred.has(pred)) dropConstraints.push({ kind: 'dropConstraint', table: d.table, name: ck.name });
   }
   for (const [pred, ck] of desiredByPred) {
-    if (currentByPred.has(pred)) continue;
+    const live = currentByPred.get(pred);
+    if (live) {
+      if (ck.nameDeclared && live.name !== ck.name) renames.push({ kind: 'renameConstraint', table: d.table, from: live.name, to: ck.name });
+      continue;
+    }
     const twin = currentByParenBlind.get(stripAllParens(ck.expr));
     // Annotate only a twin that is itself being dropped (no exact desired match) — a real churn.
     const churning = twin && !desiredByPred.has(normalizeCheck(twin.expr));
@@ -921,7 +930,7 @@ function diffConstraints(d: TableSchema, c: TableSchema, dropConstraints: Schema
     for (const cur of bucket) dropConstraints.push({ kind: 'dropConstraint', table: d.table, name: cur.name });
   }
 
-  diffChecks(d, c, dropConstraints, addConstraints);
+  diffChecks(d, c, dropConstraints, addConstraints, renames);
 
   // Primary key: a first-time add is safe; any other change needs the existing
   // constraint's name to drop it (which the snapshot discards), so it is surfaced.
@@ -1170,18 +1179,17 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string | string[] {
     }
     case 'renameConstraint':
       // Catalog-only and instant — the constraint and its backing index keep their identity.
-      return `ALTER TABLE ${change.table} RENAME CONSTRAINT ${quote(change.from)} TO ${quote(change.to)};`;
+      // Rendered beside its parser: db:apply reads this exact text back (catalog-rename).
+      return renderConstraintRename(change);
     case 'redefineIndex': {
       // Same statement as a removal; a DIFFERENT decision, which is why it is a different kind.
       const schema = change.table.includes('.') ? `${change.table.split('.')[0]}.` : '';
       return `DROP INDEX ${schema}${quote(change.name)};`;
     }
-    case 'renameIndex': {
-      // Non-destructive and instant — a catalog rename, no rebuild. The schema qualifier comes
-      // from the table; ALTER INDEX takes it on the OLD name only.
-      const schema = change.table.includes('.') ? `${change.table.split('.')[0]}.` : '';
-      return `ALTER INDEX ${schema}${quote(change.from)} RENAME TO ${quote(change.to)};`;
-    }
+    case 'renameIndex':
+      // Non-destructive and instant — a catalog rename, no rebuild. Rendered beside its parser:
+      // db:apply reads this exact text back (catalog-rename).
+      return renderIndexRename(change);
     case 'enumValuesChanged':
       return `-- NOTICE: enum ${quote(change.name)} values changed ([${change.from.join(', ')}] → [${change.to.join(', ')}]) in a way Postgres can't apply in place (a removal, reorder, or rename). ADD VALUE only appends; reshaping an enum needs a manual type swap (create new type, ALTER COLUMN ... TYPE using a cast, drop old).`;
     case 'createSequence':

package/src/cli/schema-introspect.ts

@@ -88,6 +88,8 @@ export interface CheckConstraint {
   name: string;
   /** The predicate text, as `pg_get_constraintdef` deparses it. */
   expr: string;
+  /** The name was DECLARED (`check(sql, { name })`), not positional — same rule as {@link IndexSchema.nameDeclared}. */
+  nameDeclared?: boolean;
 }
 
 /** A standalone index (NOT one backing a PK or UNIQUE constraint — those are excluded). */

package/src/cli/select-grant-advisory.ts

@@ -0,0 +1,132 @@
+/**
+ * A role that can write a table but holds no SELECT grant on it.
+ *
+ * `can('update', { role: 'moderator' })` alone compiles `GRANT UPDATE` and an UPDATE policy for
+ * moderator, but no SELECT grant. PostgreSQL needs SELECT to read the columns a WHERE or RETURNING
+ * names, so every `UPDATE t ... WHERE id = $1` by moderator fails with "permission denied for
+ * table t". The ability reads as working and is dead. The same holds for DELETE ... WHERE and
+ * INSERT ... RETURNING (measured: __tests__/integration/select-grant-advisory.test.ts).
+ *
+ * The rule reads the COMPILED grants (compileTableContract), not the abilities, so it judges what
+ * the database will hold: `manage` carries its SELECT, a bare `can('read')` covers anon and
+ * authenticated only, an owner read is authenticated's table SELECT, and a column-scoped SELECT
+ * counts. Two exceptions: a role with any ability carrying a raw `sql:` condition is skipped (a
+ * hand-written predicate is outside what this rule judges), and a write granted only through the
+ * model's `privileges:` is left to findNakedGrants, which owns that case.
+ *
+ * The rule cannot see role membership: a role that inherits SELECT from another role it is a
+ * member of is still reported, since no model declares memberships.
+ *
+ * The advice is a read SCOPED to the rows the write touches, never broader than the write: for an
+ * owner write a role-wide `can('read', { role })` would be a USING (true) policy for every
+ * signed-in user. A role-wide read is offered only for a role-wide write.
+ *
+ * Known limits: a table with `rls: false` whose `privileges:` grant a write but no SELECT is
+ * skipped here (findNakedGrants owns `privileges:` grants and does not name the missing SELECT);
+ * and a write scoped by `where:` alone gets the generic advice, which can be wider than the write.
+ *
+ * Advisory only — db:check reports it as a warning and never fails on it.
+ */
+
+import type { Ability, ModelDescriptor } from '@everystack/model';
+import { compileTableContract } from './authz-compile';
+import type { TableContract } from './authz-contract';
+
+export type WriteVerb = 'create' | 'delete' | 'update';
+
+export interface SelectGrantGap {
+  /** `schema.table`. */
+  table: string;
+  role: string;
+  /** The ability verb whose grant is unusable without SELECT. */
+  verb: WriteVerb;
+  message: string;
+}
+
+/** Ability verb -> the privilege it compiles to, in report order. */
+const WRITE_PRIVILEGES: ReadonlyArray<[WriteVerb, string]> = [
+  ['create', 'INSERT'],
+  ['delete', 'DELETE'],
+  ['update', 'UPDATE'],
+];
+
+/** The statement shape that needs SELECT, per privilege. INSERT has no WHERE. */
+const NEEDS_SELECT: Record<string, string> = {
+  INSERT: 'INSERT ... RETURNING',
+  DELETE: 'DELETE ... WHERE/RETURNING',
+  UPDATE: 'UPDATE ... WHERE/RETURNING',
+};
+
+/** Does the role hold this privilege on the table, table-wide or on any column? */
+function holds(contract: TableContract, role: string, privilege: string): boolean {
+  return (contract.grants[role] ?? []).includes(privilege)
+    || Boolean(contract.columnGrants?.[role]?.[privilege]?.length);
+}
+
+/** The grantee an ability lands on — what compileGrants keys it under. */
+function granteeOf(role: string | undefined): string {
+  if (!role) return 'authenticated';
+  return role.toLowerCase() === 'public' ? 'PUBLIC' : role;
+}
+
+/** The table privileges an ability compiles to (`manage` is all four). */
+function privilegesOf(action: Ability['action']): string[] {
+  switch (action) {
+    case 'manage': return ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
+    case 'read': return ['SELECT'];
+    case 'create': return ['INSERT'];
+    case 'update': return ['UPDATE'];
+    case 'delete': return ['DELETE'];
+    default: return [];
+  }
+}
+
+/** The abilities whose grant puts `privilege` on `role` — none means it came from `privileges:`. */
+function sources(model: ModelDescriptor, role: string, privilege: string): Ability[] {
+  return model.abilities.filter((a) => granteeOf(a.condition.role) === role && privilegesOf(a.action).includes(privilege));
+}
+
+/** The read to suggest: scoped like the write when the write is owner/via-scoped, else generic. */
+function remedy(role: string, from: readonly Ability[]): string {
+  const scoped = from.find((a) => a.condition.owner || a.condition.via);
+  const lead = `Add a read ability for ${role} scoped to the rows it may touch`;
+  if (!scoped) {
+    return `${lead} (for example can('read', { owner: '<column>' }) for an owner write, `
+      + `or can('read', { role: '${role}' }) for a role-wide one).`;
+  }
+  const keys = [
+    ...(scoped.condition.role ? [`role: '${scoped.condition.role}'`] : []),
+    scoped.condition.owner ? `owner: '${scoped.condition.owner}'` : `via: '${scoped.condition.via}'`,
+  ];
+  return `${lead}, for example can('read', { ${keys.join(', ')} }).`;
+}
+
+export function findSelectGrantGaps(models: readonly ModelDescriptor[]): SelectGrantGap[] {
+  const out: SelectGrantGap[] = [];
+  for (const model of models) {
+    const contract = compileTableContract(model);
+    const suppressed = new Set(
+      model.abilities.filter((a) => a.condition.sql != null).map((a) => granteeOf(a.condition.role)),
+    );
+    const roles = new Set([...Object.keys(contract.grants), ...Object.keys(contract.columnGrants ?? {})]);
+    for (const role of [...roles].sort()) {
+      if (suppressed.has(role)) continue;
+      // A PUBLIC SELECT reaches every role, so it satisfies any of them.
+      if (holds(contract, role, 'SELECT') || holds(contract, 'PUBLIC', 'SELECT')) continue;
+      for (const [verb, privilege] of WRITE_PRIVILEGES) {
+        if (!holds(contract, role, privilege)) continue;
+        const from = sources(model, role, privilege);
+        if (from.length === 0) continue;
+        out.push({
+          table: contract.table,
+          role,
+          verb,
+          message: `${contract.table}: ${role} can ${privilege} but has no SELECT grant; `
+            + `${NEEDS_SELECT[privilege]} by ${role} fails with "permission denied for table ${model.table}". `
+            + remedy(role, from),
+        });
+      }
+    }
+  }
+  return out;
+}

package/src/cli/stage-backup.ts

@@ -24,6 +24,8 @@
 
 import { invokeAction, lambdaSessionRunner } from './aws';
 import { pollTaskUntilStopped } from './task-poll';
+import type { BackupLiveRead } from './apply-execute';
+import type { AuthzManifest } from './authz-manifest';
 
 /** The verdict on a completed dump's fingerprint pair. Pure — the heart of the sandwich. */
 export type SandwichVerdict = { ok: true } | { ok: false; reason: string };
@@ -46,10 +48,14 @@ export function judgeSandwich(fpBefore: string, fpAfter: string): SandwichVerdic
 }
 
 export interface StageBackupDeps {
-  /** Read the live base-schema fingerprint. Called twice, bracketing the dump. */
-  readFingerprint: () => Promise<string>;
-  /** Dispatch `db:backup` with the operator-computed fingerprint. */
-  dispatch: (fingerprint: string) => Promise<{ runId: string; taskArn: string; id: string; key: string; warning?: string }>;
+  /**
+   * Read the live base-schema fingerprint and the target's origin commit, in one session. Called
+   * twice, bracketing the dump; the sandwich judges the fingerprints, and the OPENING read is what
+   * the dispatch carries.
+   */
+  readLive: () => Promise<BackupLiveRead>;
+  /** Dispatch `db:backup` with the operator-computed fingerprint and origin commit. */
+  dispatch: (live: BackupLiveRead) => Promise<{ runId: string; taskArn: string; id: string; key: string; warning?: string }>;
   /**
    * Wait for the task to stop; resolve ok, or a human reason it did not.
    *
@@ -59,6 +65,13 @@ export interface StageBackupDeps {
   awaitTask: (ids: { runId: string; taskArn: string; id: string }) => Promise<{ ok: true; bytes?: number; stampedFingerprint?: string } | { ok: false; reason: string }>;
   /** Delete a retracted artifact (the ops Lambda's db:backup:retract). */
   retract: (key: string) => Promise<void>;
+  /**
+   * Stamp the declared-authz manifest onto the finished backup (the ops Lambda's
+   * db:backup:stamp-authz). Optional: only a caller that rendered a manifest supplies it. Runs only
+   * on a PROVEN backup, and its failure is a warning, never a failed backup — the dump is valid, the
+   * manifest is metadata layered on top, and a restore treats a missing one as "no manifest".
+   */
+  stampAuthz?: (key: string) => Promise<void>;
   /** Progress output. Optional so tests stay quiet. */
   onStep?: (message: string) => void;
 }
@@ -78,18 +91,19 @@ export async function runStageBackup(deps: StageBackupDeps): Promise<StageBackup
   const step = deps.onStep ?? (() => {});
 
   step('Reading the live schema fingerprint (before the dump)...');
-  let fpBefore: string;
+  let before: BackupLiveRead;
   try {
-    fpBefore = await deps.readFingerprint();
+    before = await deps.readLive();
   } catch (err: any) {
     // Refuse BEFORE dispatching: a dump whose fingerprint cannot be proven is not a safety net, and
     // taking one anyway would burn the dump window and still leave nothing trustworthy.
     return { ok: false, reason: `the schema fingerprint could not be read, so no backup was dispatched: ${err?.message ?? String(err)}` };
   }
+  const fpBefore = before.fingerprint;
 
   let dispatched: { runId: string; taskArn: string; id: string; key: string; warning?: string };
   try {
-    dispatched = await deps.dispatch(fpBefore);
+    dispatched = await deps.dispatch(before);
   } catch (err: any) {
     return { ok: false, reason: `the backup would not dispatch: ${err?.message ?? String(err)}` };
   }
@@ -127,7 +141,7 @@ export async function runStageBackup(deps: StageBackupDeps): Promise<StageBackup
   step('Re-reading the schema fingerprint (after the dump)...');
   let fpAfter: string;
   try {
-    fpAfter = await deps.readFingerprint();
+    fpAfter = (await deps.readLive()).fingerprint;
   } catch (err: any) {
     // The dump exists but is unproven. Do NOT retract — an unreadable fingerprint is not evidence
     // the schema moved, and silently destroying a good backup is the worse error.
@@ -146,7 +160,16 @@ export async function runStageBackup(deps: StageBackupDeps): Promise<StageBackup
     const unverified = finished.stampedFingerprint === undefined
       ? 'the task did not report the fingerprint it stamped, so the artifact could not be verified against what the operator sent (the result-ledger write is best-effort)'
       : undefined;
-    const warning = [dispatched.warning, unverified].filter(Boolean).join('; ') || undefined;
+    let unstamped: string | undefined;
+    if (deps.stampAuthz) {
+      step('Recording the declared authz manifest on the backup...');
+      try {
+        await deps.stampAuthz(dispatched.key);
+      } catch (err: any) {
+        unstamped = `the backup is valid, but its authz manifest was NOT recorded (${err?.message ?? String(err)}) — a restore from it cannot converge authz from the manifest; take another backup if you need one`;
+      }
+    }
+    const warning = [dispatched.warning, unverified, unstamped].filter(Boolean).join('; ') || undefined;
     return { ok: true, id: dispatched.id, key: dispatched.key, bytes: finished.bytes, fingerprint: fpBefore, warning };
   }
 
@@ -178,22 +201,31 @@ export function stageBackupDeps(
   config: { region: string },
   opsFn: string,
   stage: string | undefined,
-  hooks: { onStep?: (message: string) => void; onDispatch?: (d: { runId: string; taskArn: string; id: string; warning?: string }) => void } = {},
+  hooks: {
+    onStep?: (message: string) => void;
+    onDispatch?: (d: { runId: string; taskArn: string; id: string; warning?: string }) => void;
+    /** The declared-authz manifest to stamp onto the finished backup (db:backup renders it). */
+    authzManifest?: AuthzManifest;
+  } = {},
 ): StageBackupDeps {
+  const { authzManifest } = hooks;
   return {
     // BOTH ends of the sandwich read over this ONE closure, so they cannot land on different lanes.
     // That matters: a before-read over a direct session and an after-read over the two-invoke
     // ops-Lambda blend could manufacture a false mismatch — or, worse, a false match. The symmetry
     // is structural here rather than asserted; if a caller ever needs to override one end, it has to
     // override both.
-    readFingerprint: async () => {
-      // The SAME helper db:apply's concurrency lock uses — that shared definition is the point.
-      const { liveBaseFingerprint } = await import('./apply-execute');
-      return (await liveBaseFingerprint(lambdaSessionRunner(config.region, opsFn))).hash;
+    readLive: async () => {
+      // The SAME one-session read db:apply's concurrency lock and descent proof use — the
+      // fingerprint and the ledger anchor come from one snapshot, one round trip.
+      const { readBackupLive } = await import('./apply-execute');
+      return readBackupLive(lambdaSessionRunner(config.region, opsFn));
     },
-    dispatch: async (fingerprint) => {
+    dispatch: async ({ fingerprint, originCommit }) => {
+      // `originCommit` is sent as read: a string, `null` (proven none), or left out when the ledger
+      // read failed (JSON drops undefined), so the artifact never claims what the read did not prove.
       const dispatched: any = await invokeAction(config.region, opsFn, 'db:backup', {
-        stage, actor: process.env.USER ?? null, fingerprint,
+        stage, actor: process.env.USER ?? null, fingerprint, originCommit,
       });
       if (dispatched?.error) throw new Error(dispatched.error);
       hooks.onDispatch?.(dispatched);
@@ -224,6 +256,15 @@ export function stageBackupDeps(
       if (res?.error) throw new Error(res.error);
       if (!res?.retracted) throw new Error(`the ops function did not confirm the retraction (returned ${JSON.stringify(res)})`);
     },
+    // Sent AFTER the dump, never in the dispatch: the task job is one ECS env override capped at
+    // 8192 chars, which a real manifest outgrows. Scoped server-side like the retraction.
+    ...(authzManifest ? {
+      stampAuthz: async (key: string) => {
+        const res: any = await invokeAction(config.region, opsFn, 'db:backup:stamp-authz', { key, stage, authzManifest });
+        if (res?.error) throw new Error(res.error);
+        if (!res?.stamped) throw new Error(`the ops function did not confirm the stamp (returned ${JSON.stringify(res)}) — deploy a server build that ships db:backup:stamp-authz`);
+      },
+    } : {}),
     onStep: hooks.onStep,
   };
 }