@everystack/cli 0.4.97 → 0.4.99

package/src/cli/derived-plan.ts

@@ -155,7 +155,7 @@ export interface ReconcileOptions {
 
 const isRelation = (kind: DerivedKind): boolean => kind !== 'function';
 
-const ownerContext = (src: SourceObject, liveObj: LiveObject): GrantOwnerContext => ({
+const ownerContext = (src: Pick<SourceObject, 'owner'>, liveObj: LiveObject): GrantOwnerContext => ({
   ...(src.owner !== undefined ? { declared: src.owner } : {}),
   ...(liveObj.owner !== undefined ? { live: liveObj.owner } : {}),
 });
@@ -178,7 +178,7 @@ const ownerContext = (src: SourceObject, liveObj: LiveObject): GrantOwnerContext
  * failure to ADD access (availability), never to remove it.
  */
 export function objectGrantDelta(
-  src: SourceObject,
+  src: Pick<SourceObject, 'kind' | 'identity' | 'attachments' | 'owner'>,
   liveObj: LiveObject,
   liveGrants: Record<string, string[]> | undefined = liveObj.grants,
 ): (ObjectGrantDiff & { columnScoped: boolean }) | null {

package/src/cli/edge-plan.ts

@@ -25,6 +25,8 @@
  */
 
 import { createHash } from 'node:crypto';
+import type { Attachment } from './derived-source';
+import type { OwnerApplyMode } from './derived-apply';
 import type { ModelDescriptor } from '@everystack/model';
 import type { SchemaSnapshot, TableSchema } from './schema-introspect';
 import type { AuthzContract, SequenceGrantContract, DefaultAclScope } from './authz-contract';
@@ -39,7 +41,19 @@ import { fingerprintLive, fingerprintState, fingerprintModels, governedRolesForM
 import { compileDeclaredState } from './declared-diff';
 import { compileTableRenames, compileTableMoves, compileRenames } from './schema-compile';
 
-export const PLAN_VERSION = 2;
+/**
+ * v3 adds `statePrerequisites`: SQL definitions db:apply must establish before the state edge.
+ * v4 makes each prerequisite a complete, governed derived-object create and carries the source
+ * metadata needed to record canonical catalog provenance in the same transaction as the edge.
+ * v5 adds the declared grant contract and owner mode for post-create ACL settlement and
+ * verification. A v4 reader skips those checks and must not apply this artifact.
+ * v6 records each prerequisite's declared search path, restored before state DDL. A v5 reader
+ * can bind argument defaults to the wrong function and must not apply this artifact.
+ * A v3 reader does not know how to enact or record those prerequisites, so the file formats are
+ * not compatible. The existing db:apply version refusal makes the mismatch a re-mint before any
+ * write, rather than letting a peer silently omit part of the reviewed artifact.
+ */
+export const PLAN_VERSION = 6;
 
 /**
  * The db:apply WIRE CONTRACT between the CLI and the ops Lambda — distinct from PLAN_VERSION,
@@ -84,8 +98,28 @@ export const PLAN_VERSION = 2;
  * to remove, reintroduced silently across a version skew instead of refused cleanly. The BUMP
  * RULE covers exactly this: a field the CLIENT now depends on to decide something is part of the
  * contract. Peers refuse until the stage is redeployed.
+ *
+ * v6 (milestone plan-state-prerequisites-format): the plan in the payload gained
+ * `statePrerequisites`, definitions the server must establish before it applies the state edge.
+ * A v5 ops Lambda would not know to execute them and would silently skip a reviewed prerequisite
+ * before applying the rest of the plan. The BUMP RULE says that changed server work is part of
+ * the contract, so the peers refuse until the stage is redeployed.
+ *
+ * v7 (milestone atomic-state-prerequisites): the payload gained `stateOnly` and the ops Lambda
+ * refuses a prerequisite-bearing plan when it is true. A v6 Lambda would accept the request and
+ * create the prerequisite, contradicting `--state-only`'s promise to skip function writes.
+ *
+ * v8 (milestone governed-state-prerequisites): prerequisite application now records derived
+ * provenance before its transaction commits. A v7 ops Lambda could create a governed function
+ * without its provenance row, leaving the next catch-up to require a baseline.
+ *
+ * v9 settles and verifies prerequisite grants before commit. A v8 stage could leave an
+ * undeclared default EXECUTE grantee live while reporting a successful governed create.
+ *
+ * v10 applies the reviewed prerequisite search path and restores the transaction's original
+ * path before state DDL and grant verification. A v9 stage could bind defaults to other schemas.
  */
-export const APPLY_CONTRACT_VERSION = 5;
+export const APPLY_CONTRACT_VERSION = 10;
 
 /** Classification counts (brick 9, decision 11): destructive = drops + narrowings + strips. */
 export interface PlanClassification {
@@ -107,6 +141,31 @@ export interface PlanClassification {
   unclassified?: number;
 }
 
+/** A definition that db:apply must establish before it applies the state edge. */
+export type StatePrerequisite = {
+  /** The function's full PostgreSQL identity: `schema.name(argtypes)`. */
+  identity: string;
+  /** The exact schema preparation, CREATE, ownership, grant, and comment SQL db:apply runs. */
+  sql: string;
+  /** The catalog condition db:apply must prove before it runs `sql`. */
+  expected: 'absent';
+  /** Full declared derived path, with quoted identifiers; null preserves the ambient all-public path. */
+  searchPath: string | null;
+  /** Reviewed grant declarations and the owner mechanism selected at mint. No source reload at apply. */
+  grantContract: {
+    attachments: Attachment[];
+    owner?: string;
+    ownerMode: OwnerApplyMode;
+  };
+  /** Source facts needed to record the catalog-derived provenance hash after this transaction creates it. */
+  provenance: {
+    srcHash: string;
+    bodyHash?: string;
+    kind: 'function';
+    dropSql?: string;
+  };
+};
+
 export interface EdgePlan {
   v: number;
   /** The target's exact live fingerprint at mint time — the lock. */
@@ -169,6 +228,11 @@ export interface EdgePlan {
   declaredFingerprint: string;
   /** The edge, in db:generate's statement grammar (no held drops — mint refuses them). */
   statements: string[];
+  /**
+   * Definitions that must exist before the state edge can land. Optional because plans minted
+   * before this field existed have none; an absent field means no prerequisite was recorded.
+   */
+  statePrerequisites?: readonly StatePrerequisite[];
   executable: number;
   /** Executable statements that LOSE DATA (drops + narrowing type changes) — red, gated at apply. */
   destructive: number;

package/src/cli/index.ts

@@ -317,7 +317,7 @@ Usage:
   everystack db:provision      --rotate --stage <name> [--slot api|ops|both] [--grace 60]  Rotate credentials live (A/B role swap, no deploy, no downtime)
   everystack db:snapshot       [--stage <name>] [--instance <id>]  Take a physical RDS snapshot (instant DR point; RDS only — use db:backup for portable logical backups)
   everystack db:snapshots      [--stage <name>] [--instance <id>]  List manual RDS snapshots for the instance
-  everystack db:backup         [--stage <name>]  Logical pg_dump of the DB → private S3 backups bucket (prints the backup id). Add --database-url <local> --stage <target> to dump a LOCAL database and upload it into the target stage's bucket as a restorable backup — the credential-free break-glass local→stage full replace (then: db:restore --from <id> --stage <target>)
+  everystack db:backup         [--stage <name>]  Logical pg_dump of the DB → private S3 backups bucket (prints the backup id). Add --database-url <local> --stage <target> to dump a LOCAL database and upload it into the target stage's bucket. Such a backup records no origin commit, so db:restore refuses it: restoring a local backup into a stage is closed until local backups can record a verified origin
   everystack db:backups        [--stage <name>]  List logical backups (id, size, created)
   everystack db:restore        --from <id> [--stage <name>] --confirm  Restore a backup INTO the stage's DB (DESTRUCTIVE)
   everystack db:backup:download <id> [--stage <name>]  Presigned URL to download a backup's dump (valid 1h)

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/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,
   };
 }