@everystack/cli 0.4.97 → 0.4.99

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.99] - 2026-10-14
+
+### Added
+
+- db:backup reads the origin commit in the fingerprint session
+- render the declared-authz manifest from the checkout's models
+- mirror originCommit and authzManifest into the CLI BackupManifest
+- stamp the authz manifest after a proven stage backup
+- db:backup renders the authz manifest and stamps it post-dump
+- db:restore and db:fork write a restore witness from the backup's origin (#15)
+- link table name references through model thunks
+- db:check warns when a role can write a table but not read it
+- the db:check one-line summary counts warnings
+
+### Fixed
+
+- normalize statement keys in plain reports
+- lease the ops-Lambda write path, no driver fork
+- link names before manifest and runbook rendering
+- the select-grant warning no longer suggests a blanket read
+- probe UPDATE per role in the authz red-team
+- probe red-team UPDATE with SET col = DEFAULT
+- db:doctor prints each fix once and an accurate closing line
+
+### Documentation
+
+- the select-grant advice is never broader than the write
+
+## [0.4.98] - 2026-09-27
+
+### Added
+
+- mint state function prerequisites
+- apply state prerequisites atomically
+
+### Fixed
+
+- version state prerequisites in plans
+- govern state prerequisites
+- defer state prerequisite body checks
+- verify prerequisite grants before commit
+- preserve prerequisite search paths
+
 ## [0.4.97] - 2026-09-26
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.97",
+  "version": "0.4.99",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -58,6 +58,16 @@
       "types": "./src/reconcile.ts",
       "default": "./src/reconcile.ts"
     },
+    "./mutation-lease": {
+      "source": "./src/cli/mutation-lease.ts",
+      "types": "./src/cli/mutation-lease.ts",
+      "default": "./src/cli/mutation-lease.ts"
+    },
+    "./connection-fence": {
+      "source": "./src/cli/connection-fence.ts",
+      "types": "./src/cli/connection-fence.ts",
+      "default": "./src/cli/connection-fence.ts"
+    },
     "./refresh": {
       "source": "./src/refresh.ts",
       "types": "./src/refresh.ts",
@@ -135,7 +145,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.4.20"
+    "@everystack/model": "0.4.21"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.4.0",
@@ -182,7 +192,7 @@
     "react": "19.2.0",
     "ts-jest": "29.4.9",
     "zod": "3.25.67",
-    "@everystack/server": "0.4.33"
+    "@everystack/server": "0.4.35"
   },
   "scripts": {
     "test": "jest",

package/src/cli/apply-execute.ts

@@ -56,7 +56,11 @@ import {
 } from './schema-introspect';
 import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog';
 import { fingerprintLive, FINGERPRINT_VERSION } from './schema-fingerprint';
-import { applyGeneratedStatements } from './state-apply';
+import {
+  applyGeneratedStatements,
+  STATE_PREREQUISITE_DRIFT_PREFIX,
+  type StateApplyResult,
+} from './state-apply';
 import {
   fkOrphanChecks,
   fkOrphanSql,
@@ -88,6 +92,8 @@ import type { DescentLedgerRow, LedgerRead } from './git-descent';
  */
 export interface ApplyPlanOptions {
   actor?: string | null;
+  /** Pinned write transaction for prerequisite DDL + state DDL + provenance. */
+  transaction?: <T>(work: (runner: QueryRunner) => Promise<T>) => Promise<T>;
   /** Defaults to the plan's own gitRef (the intent that minted it). */
   gitRef?: string | null;
   /**
@@ -149,15 +155,8 @@ export interface ApplyPlanOptions {
    * (which runs before the write) — the getter reads it at write time.
    */
   descentNote?: () => string | undefined;
-  /**
-   * Called with the statements about to run, AFTER every gate above has passed and BEFORE the
-   * batch — so a refused apply writes nothing through it. db:apply's direct lane uses it to
-   * create the declared functions a policy in the plan calls (state-function-deps.ts), which on
-   * a fresh target do not exist until the derived catch-up. Functions are not in the base
-   * fingerprint, so this moves neither the lock nor the verify-after endpoint. Omitted, the
-   * apply is unchanged (the ops-Lambda lane does not pass it).
-   */
-  beforeStateBatch?: (statements: readonly string[]) => Promise<unknown>;
+  /** State-only deliberately skips function writes, including plan prerequisites. */
+  stateOnly?: boolean;
 }
 
 export interface ApplyPlanResult {
@@ -417,6 +416,47 @@ export async function liveBaseAndLedger(session: SessionRunner): Promise<LiveBas
   return { hash: fingerprintLive(snapshot, contract).hash, snapshot, contract, ledger, ledgerRead };
 }
 
+/**
+ * The commit that last deployed this target — the `git_ref` SCHEMA_LOG_ANCHOR_SQL answers, i.e.
+ * the newest successful apply that RECORDED a commit. An app-only apply without one never shadows
+ * it, exactly as it never shadows descent's anchor.
+ *
+ * Three answers, because the ledger read has three outcomes:
+ *   - a string  — the anchor's commit;
+ *   - `null`    — a CLEAN read proved there is none (no schema_log, or no commit-carrying apply);
+ *   - undefined — the read failed, so nothing is known. Never `null`: that would claim "this
+ *     target has no deploying commit" on the strength of a read that did not happen.
+ */
+export function originCommitFromLedger(ledger: DescentLedgerRow[], ledgerRead: LedgerRead): string | null | undefined {
+  if (ledgerRead.kind === 'unreadable') return undefined;
+  if (ledgerRead.kind === 'absent' || !ledgerRead.anchored) return null;
+  // ledgerFromSlots folds the anchor row into the ledger, so the anchor is the newest row (by id,
+  // never by clock — the anchor query's own order) that carries a commit.
+  let anchor: DescentLedgerRow | undefined;
+  for (const row of ledger) {
+    if (row.gitRef == null) continue;
+    if (anchor === undefined || BigInt(row.id) > BigInt(anchor.id)) anchor = row;
+  }
+  return anchor?.gitRef ?? null;
+}
+
+/** What a stage backup records about the live target at dump time. */
+export interface BackupLiveRead {
+  fingerprint: string;
+  /** See originCommitFromLedger — undefined means the ledger read failed. */
+  originCommit: string | null | undefined;
+}
+
+/**
+ * The backup's live read: the base fingerprint AND the origin commit, in the ONE repeatable-read
+ * session liveBaseAndLedger already runs — the same fingerprint db:apply's lock computes, and the
+ * same anchor its descent proof reads. No second round trip.
+ */
+export async function readBackupLive(session: SessionRunner): Promise<BackupLiveRead> {
+  const { hash, ledger, ledgerRead } = await liveBaseAndLedger(session);
+  return { fingerprint: hash, originCommit: originCommitFromLedger(ledger, ledgerRead) };
+}
+
 /** Verify → apply → verify. Pure orchestration over an injected QueryRunner. */
 export async function executeApplyPlan(
   runner: QueryRunner,
@@ -542,25 +582,38 @@ export async function executeApplyPlan(
   // rewritten — the plan is an artifact under a content hash, and `planHash(plan)` below has to
   // keep naming the file the operator reviewed.
   const { statements: toRun, withheld } = withheldValidations(plan.statements, orphans);
+  if (options.stateOnly && plan.statePrerequisites?.length) {
+    const reason = 'this plan needs state prerequisites, but --state-only skips function writes. Apply the reviewed plan without --state-only, or satisfy the prerequisites and re-mint.';
+    await recordRefusal(runner, plan, live, 'state prerequisites', reason, options);
+    return { status: 'refused', liveFingerprint: live, reason };
+  }
 
-  if (options.beforeStateBatch) await options.beforeStateBatch(toRun);
-
-  const result = await applyGeneratedStatements(runner, toRun, {
-    ...(withheld.length > 0 ? { skippedValidations: withheld } : {}),
-    actor: options.actor,
-    gitRef: options.gitRef ?? plan.gitRef,
-    planRef: planHash(plan),
-    fromFingerprint: live,
-    fpVersion: FINGERPRINT_VERSION,
-    dirty: options.dirty ?? false,
-    now: options.now,
+  let result: StateApplyResult;
+  try {
+    result = await applyGeneratedStatements(runner, toRun, {
+      statePrerequisites: plan.statePrerequisites,
+      transaction: options.transaction,
+      ...(withheld.length > 0 ? { skippedValidations: withheld } : {}),
+      actor: options.actor,
+      gitRef: options.gitRef ?? plan.gitRef,
+      planRef: planHash(plan),
+      fromFingerprint: live,
+      fpVersion: FINGERPRINT_VERSION,
+      dirty: options.dirty ?? false,
+      now: options.now,
     // The hash to stamp on the record written the moment the batch commits — the live state as
     // it is THEN, with any new key installed and not yet proven. The plan's own endpoint is
     // stamped below, after the last check has actually passed; predicting it here would put a
     // state the database is not in onto the row every later apply descends from.
     readFingerprint: async () => (await liveBaseFingerprint(session)).hash,
-    ...(options.descentNote ? { descentNote: options.descentNote } : {}),
-  });
+      ...(options.descentNote ? { descentNote: options.descentNote } : {}),
+    });
+  } catch (err: any) {
+    const message = String(err?.message ?? err);
+    if (!message.includes(STATE_PREREQUISITE_DRIFT_PREFIX)) throw err;
+    await recordRefusal(runner, plan, live, 'state prerequisites', message, options);
+    return { status: 'refused', liveFingerprint: live, reason: message };
+  }
 
   const { hash: landed } = await liveBaseFingerprint(session);
   if (result.logId !== undefined) {
@@ -610,3 +663,7 @@ export async function executeApplyPlan(
 // notably the ops Lambda's db:apply action — everything it needs to validate
 // and run a plan without reaching into the CLI's internal module layout.
 export { PLAN_VERSION, APPLY_CONTRACT_VERSION, planHash, checkPlanPrecondition, type EdgePlan } from './edge-plan';
+
+// The ledger DDL, so the ops Lambda's restore dispatcher can create `everystack.schema_log` on a
+// fresh target from the one copy every apply already runs — never a second copy of the DDL.
+export { ENSURE_RECONCILER_SQL } from './derived-apply';

package/src/cli/authz-manifest.ts

@@ -0,0 +1,93 @@
+/**
+ * The declared-authz manifest a backup records (restore-converges-authz R1).
+ *
+ * A restore lands the dump's data AND its privileges-free schema; converging authz afterwards needs
+ * to know what the Models declared. Compiling a HISTORICAL models tree to learn that was rejected —
+ * an old tree can fail to compile under the current CLI — so the backup records the answer at dump
+ * time instead, rendered from the models checked out when `db:backup` runs.
+ *
+ * Pure and a composition only. Every section is the output of the renderer that already owns it:
+ *   - tables  — compileTableContract, per model (what db:plan / db:check converge tables to);
+ *   - derived — parseGrantAttachments per view/matview/function, plus the schema USAGE rule
+ *               renderEnsureObjectSchemas applies (declaredObjectSchemaUsage);
+ *   - owners  — extractDeclaredOwnership (what db:provision's ownership convergence enacts/adopts).
+ * No logic is re-derived here: a second copy would drift from what the verbs actually converge to.
+ */
+
+import { ModelLinkError } from '@everystack/model';
+import type { TableContract } from './authz-contract';
+import { compileTableContract } from './authz-compile';
+import { parseGrantAttachments } from './derived-grants';
+import { declaredObjectSchemaUsage } from './derived-apply';
+import { extractDeclaredOwnership } from './commands/db';
+import type { DeclaredDerived } from './declared-derived';
+import type { DeclaredOwner, Adoptee } from '../wire';
+import type { BackupAuthzManifest } from './backup';
+
+/** One view / matview / function's declared grant contract, as parseGrantAttachments reads it. */
+export interface DerivedGrantEntry {
+  identity: string;
+  kind: string;
+  schema: string;
+  /** The `ON …` target as the declared statements spell it, or null when none was declared. */
+  target: string | null;
+  /** grantee → sorted privileges. PUBLIC present-with-[] means explicitly revoked. */
+  grants: Record<string, string[]>;
+  /** A column-scoped grant is declared (not drift-checked by the reconciler). */
+  hasColumnGrants: boolean;
+}
+
+/** Narrows the mirrored BackupManifest envelope, so a rendered manifest is assignable to the field. */
+export interface AuthzManifest extends BackupAuthzManifest {
+  version: 1;
+  /** compileTableContract(model) for every declared model, in declaration order. */
+  tables: TableContract[];
+  derived: {
+    /** Every derived object that carries grants — triggers and `sql` escape hatches do not. */
+    objects: DerivedGrantEntry[];
+    /** non-public schema → the roles granted USAGE on it (sorted; [] = the schema, no grant). */
+    schemaUsage: Record<string, string[]>;
+  };
+  /** The ENACT pairs and ADOPT objects db:provision converges ownership to. */
+  owners: { declaredOwners: DeclaredOwner[]; declaredObjects: Adoptee[] };
+}
+
+/** Render the declared-authz manifest from the checkout's models and derived descriptors. */
+export function renderAuthzManifest(declared: Pick<DeclaredDerived, 'models' | 'objects'>): AuthzManifest {
+  const objects: DerivedGrantEntry[] = declared.objects
+    // The kinds the reconciler grant-checks (objectGrantDelta): triggers have no ACL, and an
+    // opaque `sql` object's grants are its own business.
+    .filter((o) => o.kind !== 'trigger' && o.kind !== 'sql')
+    .map((o) => {
+      const parsed = parseGrantAttachments(o.attachments);
+      return {
+        identity: o.identity, kind: o.kind, schema: o.schema,
+        target: parsed.target, grants: parsed.grants, hasColumnGrants: parsed.hasColumnGrants,
+      };
+    });
+  return {
+    version: 1,
+    tables: declared.models.map((m) => compileTableContract(m)),
+    derived: { objects, schemaUsage: declaredObjectSchemaUsage(declared.objects) },
+    owners: extractDeclaredOwnership(declared.objects),
+  };
+}
+
+/**
+ * What `db:backup` sends: the manifest rendered from the checkout, loaded through `load`
+ * (loadDeclaredDerived in the command). A models-less project has nothing declared, so it sends
+ * nothing and says nothing. A name-link failure refuses the backup. Other load failures warn —
+ * the dump is the safety net — so that is a warning and the backup proceeds without a manifest.
+ */
+export async function loadBackupAuthzManifest(
+  load: () => Promise<Pick<DeclaredDerived, 'models' | 'objects'> | null>,
+): Promise<{ manifest?: AuthzManifest; warning?: string }> {
+  try {
+    const declared = await load();
+    return declared ? { manifest: renderAuthzManifest(declared) } : {};
+  } catch (err: unknown) {
+    if (err instanceof ModelLinkError) throw err;
+    const message = err instanceof Error ? err.message : String(err);
+    return { warning: `the authz manifest could not be rendered from your models (${message}), so this backup will not carry one` };
+  }
+}

package/src/cli/authz-redteam.ts

@@ -84,7 +84,7 @@ function pgArrayLiteral(values: string[]): string {
  * transaction it always rolls back. Probe statements are privilege-isolated:
  *   SELECT 1 FROM t WHERE false      — SELECT privilege, reads no rows
  *   INSERT INTO t DEFAULT VALUES     — INSERT privilege (rolled back; NOT NULL = allowed)
- *   UPDATE t SET col = col WHERE false — UPDATE privilege, touches no rows
+ *   UPDATE t SET col = DEFAULT WHERE false — UPDATE privilege on col only, touches no rows
  *   DELETE FROM t WHERE false        — DELETE privilege, touches no rows
  * "permission denied" -> denied-privilege; "row-level security" -> denied-rls.
  *
@@ -93,8 +93,9 @@ function pgArrayLiteral(values: string[]): string {
  * privilege was present -> allowed. But a statement rejected at parse/analysis time never
  * reached the permission check at all and proves NOTHING -> inconclusive. Classifying the
  * second kind as `allowed` is what reported `anon` as able to UPDATE a table it cannot
- * touch: the probe's `SET pk = pk` hit 428C9 ("can only be updated to DEFAULT") on an
- * identity PK, and a non-grant then read as "enforcement exceeds declaration".
+ * touch: the probe's old `SET pk = pk` hit 428C9 ("can only be updated to DEFAULT") on an
+ * identity PK, and a non-grant then read as "enforcement exceeds declaration". The probe
+ * now SETs DEFAULT, which identity and generated columns accept.
  */
 export function buildProbeSql(roles: string[], tables: string[]): string {
   return `
@@ -119,21 +120,29 @@ BEGIN
           WHEN 'UPDATE' THEN NULL
         END;
         IF v_cmd = 'UPDATE' THEN
-          -- Prefer a column the statement can actually SET. An identity or generated
-          -- column rejects "SET col = col" at analysis time (428C9), before the permission
-          -- check — which makes the probe prove nothing. Fall back to the first column
-          -- only when every column is generated; that run reports inconclusive.
+          -- The probe is "SET col = DEFAULT", which needs the UPDATE privilege on col and
+          -- nothing else. "SET col = col" READS col, so it also needs SELECT on col: a role
+          -- granted UPDATE (b) without SELECT on b probed as denied. DEFAULT is also legal on
+          -- identity (GENERATED ALWAYS too) and generated columns, so any column can be SET
+          -- and the statement always reaches the permission check.
+          --
+          -- The column is chosen PER ROLE. The contract grants UPDATE on the table privilege
+          -- OR any column privilege, so the probe must SET a column this role may update —
+          -- a per-table pick (the first column) reports a column-scoped grant as denied.
+          -- has_column_privilege is true for a table-wide grant too, and resolves
+          -- inheritance and PUBLIC. A role with no UPDATE on any column falls through to
+          -- the first column and is denied.
           SELECT quote_ident(attname) INTO v_col FROM pg_attribute
             WHERE attrelid = format('%I.%I', split_part(v_tbl,'.',1), split_part(v_tbl,'.',2))::regclass
               AND attnum > 0 AND NOT attisdropped
-              AND attidentity = '' AND attgenerated = ''
+              AND has_column_privilege(v_role, attrelid, attnum, 'UPDATE')
             ORDER BY attnum LIMIT 1;
           IF v_col IS NULL THEN
             SELECT quote_ident(attname) INTO v_col FROM pg_attribute
               WHERE attrelid = format('%I.%I', split_part(v_tbl,'.',1), split_part(v_tbl,'.',2))::regclass
                 AND attnum > 0 AND NOT attisdropped ORDER BY attnum LIMIT 1;
           END IF;
-          v_stmt := format('UPDATE %I.%I SET %s = %s WHERE false', split_part(v_tbl,'.',1), split_part(v_tbl,'.',2), v_col, v_col);
+          v_stmt := format('UPDATE %I.%I SET %s = DEFAULT WHERE false', split_part(v_tbl,'.',1), split_part(v_tbl,'.',2), v_col);
         END IF;
 
         BEGIN
@@ -150,7 +159,7 @@ BEGIN
               -- After (data/constraint): the privilege was present.
               v_outcome := CASE
                 WHEN SQLSTATE IN (
-                  '428C9',  -- generated_always: identity/generated column (the probe's own SET pk = pk)
+                  '428C9',  -- generated_always: identity/generated column (no longer hit by SET col = DEFAULT)
                   '42703',  -- undefined_column
                   '42P01',  -- undefined_table
                   '42601',  -- syntax_error

package/src/cli/backfill.ts

@@ -27,6 +27,7 @@ import { createHash } from 'node:crypto';
 import { lex, normalizeSql, splitSqlStatements, type SourceFile } from './derived-source';
 import { escapeLiteral } from './derived-apply';
 import type { QueryRunner } from './authz-contract';
+import { ConnectionLostError } from './connection-fence';
 
 // ---------------------------------------------------------------------------
 // Identity + advisories (pure).
@@ -204,10 +205,15 @@ export async function executeBackfills(
       }));
       result.ran.push({ file: job.file, identity: job.identity, durationMs });
     } catch (err: any) {
-      await runner(renderBackfillLogInsert({
-        identity: job.identity, name, sql: `-- FAILED: ${err.message}\n${job.sql}`, outcome: 'failed',
-        actor: options.actor, gitRef: options.gitRef, durationMs: now() - started,
-      }));
+      try {
+        await runner(renderBackfillLogInsert({
+          identity: job.identity, name, sql: `-- FAILED: ${err.message}\n${job.sql}`, outcome: 'failed',
+          actor: options.actor, gitRef: options.gitRef, durationMs: now() - started,
+        }));
+      } catch { /* the memoir is best-effort on failure; it must never replace the job's own error */ }
+      // A lost connection is not a job that failed and rolled back: a job lost IN FLIGHT may
+      // have committed with no log row. Surface the loss itself, which says so.
+      if (err instanceof ConnectionLostError) throw err;
       result.failed = { file: job.file, identity: job.identity, error: err.message };
       return result;
     }

package/src/cli/backup.ts

@@ -81,6 +81,27 @@ export interface BackupManifest {
   fingerprintSource?: string;
   bytes?: number;
   key: string;
+  /**
+   * The commit that last deployed the dumped database — schema_log's anchor (the newest successful
+   * apply that recorded a commit), read by the operator in the same session as `fingerprint`.
+   * `null` = a clean read proved there is none; absent = unknown (pre-R1, or the read failed).
+   */
+  originCommit?: string | null;
+  /** What the Models declared for authz when the backup was taken — see BackupAuthzManifest. */
+  authzManifest?: BackupAuthzManifest;
+}
+
+/**
+ * The declared-authz manifest a backup records: rendered by the OPERATOR's CLI from the models
+ * checked out at dump time (@everystack/cli authz-manifest.ts, which narrows each section to its
+ * real type), so a later restore can converge authz without compiling a historical models tree.
+ * The sections are opaque on this side of the mirror: they ride into the `.meta.json` unchanged.
+ */
+export interface BackupAuthzManifest {
+  version: number;
+  tables: unknown[];
+  derived: unknown;
+  owners: unknown;
 }
 
 export interface SnapshotVerifyInput {

package/src/cli/commands/db-apply.ts

@@ -62,7 +62,6 @@ import path from 'node:path';
 import { resolveModelsPath } from '../models-path';
 import { loadModels } from './db-generate';
 import { loadDeclaredDerived } from '../declared-derived';
-import { createStateReferencedFunctions } from '../state-function-deps';
 import { compileTableContract } from '../authz-compile';
 import { governedRoleSet, ungovernedGrants } from '../authz-reconcile';
 import { readBaselineFile, checkAgainstBaseline, baselineRefusal } from '../authz-baseline';
@@ -620,6 +619,7 @@ async function applyPlanViaStage(
       actor: process.env.USER ?? null,
       gitRef: currentGitRef() ?? plan.gitRef,
       dirty: worktreeDirty(resolveModelsPath(flags.models)),
+      stateOnly: flags['state-only'] === 'true',
       descentVerdict,
       ...(descentAttested ? { descentAttested } : {}),
       ...(authorityVerdict ? { authorityVerdict } : {}),
@@ -1052,7 +1052,7 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
   }
 
   step(connectingVia(dbSource));
-  const { runner, session, end } = await createUrlRunner(dbSource.url);
+  const { runner, session, transaction, end } = await createUrlRunner(dbSource.url);
 
   let landed: ApplyPlanResult | undefined;
   let catchUp: CatchUpReport = { ok: true, statements: [] };
@@ -1091,6 +1091,7 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
       { verb: 'db:apply', actor: process.env.USER ?? 'unknown' },
       async () => {
         const result = await executeApplyPlan(runner, session, plan, {
+          transaction,
           actor: process.env.USER ?? null,
           gitRef: currentGitRef() ?? plan.gitRef,
           ...(verifyAuthority ? { verifyAuthority } : {}),
@@ -1125,18 +1126,7 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
           },
           dirty: worktreeDirty(resolveModelsPath(flags.models)),
           descentNote: () => descentAttested,
-          // A declared function a policy in this plan calls must exist before the policy — on a
-          // fresh target it would otherwise arrive only with the catch-up below. Only the called,
-          // missing ones; --state-only asked for no derived writes, so it is skipped there.
-          ...(flags['state-only'] === 'true' ? {} : {
-            beforeStateBatch: async (statements: readonly string[]) => {
-              const declared = await declaredDb();
-              const created = await createStateReferencedFunctions(runner, session, statements, declared?.objects ?? [], {
-                actor: process.env.USER ?? null, gitRef: currentGitRef() ?? plan.gitRef,
-              });
-              if (created.length > 0) info(`created ${created.length} declared function(s) the plan's policies call, before the plan: ${created.join(', ')}`);
-            },
-          }),
+          stateOnly: flags['state-only'] === 'true',
           checkDescent: async (live: LiveState & { fingerprint: string; ledger: DescentLedgerRow[]; ledgerRead: LedgerRead }) => {
             step('Descent: proving the fast-forward rule against the schema_log ledger...');
             const result = await proveDescentForApply({

package/src/cli/commands/db-backup.ts

@@ -5,14 +5,15 @@
  * dispatches and polls. db:backups/db:restore/download are thin invokeAction wrappers. The image's
  * version handshake is the compatibility gate — verify a deploy with `everystack task:probe`.
  *
- * db:backup has a SECOND venue for break-glass: `--database-url <local> --stage <target>` dumps a
- * LOCAL database and uploads it into the target stage's backups bucket as a db:backup-shaped object
- * (same key scheme + .meta.json + dump flags as a server backup). The standard credential-free
- * `db:restore --from <id> --stage <target>` then lands it via the Task lane (pg_restore runs as the
- * privileged `migrator` role, which can CREATE SCHEMA + own objects). The local dump is the only
- * held connection; the upload rides the operator's AWS credentials — the same trust boundary as
- * db:fork's cross-stage presign. This is the sanctioned local→stage full replace on a role-managed
- * stage (raw pg_restore can't: the operator/api role can't CREATE SCHEMA, and only the master could).
+ * db:backup has a SECOND venue: `--database-url <local> --stage <target>` dumps a LOCAL database and
+ * uploads it into the target stage's backups bucket as a db:backup-shaped object (same key scheme +
+ * .meta.json + dump flags as a server backup). The local dump is the only held connection; the
+ * upload rides the operator's AWS credentials.
+ *
+ * Restoring such a backup into a stage is CLOSED. A restore must record the commit the restored
+ * state descends from (the witness), and a local database has no verified origin: nothing proves
+ * it matches any commit. So the local meta carries no originCommit and db:restore refuses it. It
+ * reopens only when a local backup can record an origin it has verified against the models.
  */
 
 import { spawn } from 'node:child_process';
@@ -43,7 +44,7 @@ export function resolveBackupVenue(flags: Record<string, string>): BackupVenue {
     if (!flags.stage) {
       throw new Error(
         'db:backup --database-url <local> also needs --stage <target> — the local dump uploads into '
-        + "that stage's backups bucket, and the stage names the backup id `db:restore --from` consumes.",
+        + "that stage's backups bucket, and the stage names the backup id.",
       );
     }
     return { kind: 'local', url, stage: flags.stage };
@@ -177,7 +178,7 @@ export async function dbBackupCommand(flags: Record<string, string>): Promise<vo
   }
 
   // Local venue: dump a reachable database here and upload it into the target stage's backups bucket
-  // as a db:backup-shaped object, so `db:restore --from <id> --stage <target>` lands it credential-free.
+  // as a db:backup-shaped object. It carries no origin, so db:restore refuses it (see the header).
   if (venue.kind === 'local') {
     step('Resolving deployed config...');
     let config: CliConfig;
@@ -192,22 +193,24 @@ export async function dbBackupCommand(flags: Record<string, string>): Promise<vo
       process.exit(1);
     }
     info(`Region: ${config.region}, Bucket: ${config.backupsBucket}`);
-    // Version gate for the local venue: unlike the stage venue (whose pg binaries are the Task image),
-    // this dumps with the OPERATOR's pg_dump. pg_restore refuses an archive from a NEWER pg_dump major,
-    // so a mismatch surfaces only at restore time ("unsupported version in file header") — loud and
-    // lossless (it fails before --clean drops anything), but discovered exactly when you need the
-    // backup. Surface the local major up front so the operator can match it to the target's PG major.
+    // Unlike the stage venue (whose pg binaries are the Task image), this dumps with the OPERATOR's
+    // pg_dump. pg_restore refuses an archive from a NEWER pg_dump major ("unsupported version in file
+    // header"), so surface the local major for whoever pg_restores the downloaded dump by hand.
     try {
       const { execFileSync } = await import('node:child_process');
       const v = execFileSync('pg_dump', ['--version']).toString().trim();
-      info(`Local ${v} — must be ≤ the target stage's PostgreSQL major, or db:restore will reject the dump.`);
+      info(`Local ${v} — a manual pg_restore of this dump needs pg_restore of the same major or newer.`);
     } catch { /* a missing pg_dump surfaces loudly in the dump step below */ }
     step(`Running pg_dump (full, --exclude-schema=everystack) against --database-url → S3 (this may take a while for large databases)...`);
     try {
       const res = await runLocalBackupUpload({
         region: config.region, bucket: config.backupsBucket, url: venue.url, stage: venue.stage,
       });
-      success(`Backup ${res.id} (${fmtBytes(res.bytes)}). Restore with: everystack db:restore --from ${res.id} --stage ${venue.stage} --confirm`);
+      success(`Backup ${res.id} (${fmtBytes(res.bytes)}).`);
+      warn(
+        'A local 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. It stays downloadable: everystack db:backup:download ${res.id} --stage ${venue.stage}`,
+      );
     } catch (err: any) {
       fail(`Backup failed: ${err.message}`);
       process.exit(1);
@@ -227,7 +230,16 @@ export async function dbBackupCommand(flags: Record<string, string>): Promise<vo
   info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
   const fn = opsFunction(config);
 
+  // The declared authz at dump time, rendered from THIS checkout's models (never a historical
+  // tree) and stamped onto the backup once the dump is proven — so a later restore can converge
+  // authz to it. Best-effort: a failure here is a warning, never a lost backup.
+  const { loadDeclaredDerived } = await import('../declared-derived');
+  const { loadBackupAuthzManifest } = await import('../authz-manifest');
+  const authz = await loadBackupAuthzManifest(() => loadDeclaredDerived(flags.models));
+  if (authz.warning) warn(authz.warning);
+
   const result = await runStageBackup(stageBackupDeps(config, fn, flags.stage, {
+    ...(authz.manifest ? { authzManifest: authz.manifest } : {}),
     onDispatch: (d) => {
       info(`backup ${d.id} — task ${d.taskArn}`);
       info(`run id: ${d.runId} (everystack.task_log)`);
@@ -284,6 +296,32 @@ export async function dbBackupsCommand(flags: Record<string, string>): Promise<v
   success(`${backups.length} backup${backups.length === 1 ? '' : 's'}.`);
 }
 
+/**
+ * What the dispatcher recorded in the target before the task started: the schema_log witness row
+ * and the commit it names (the backup's own origin), plus whether the declared roles were checked.
+ *
+ * A successful dispatch with no witnessId came from an ops Lambda that predates restore witnesses:
+ * it ignored the origin checks and recorded nothing. The restore is already running, so this warns
+ * rather than refuses.
+ */
+export function printRestoreWitness(
+  dispatched: { witnessId?: string; origin?: string; rolesUnchecked?: boolean },
+  stage: string,
+): void {
+  if (dispatched.witnessId) {
+    info(`witness ${dispatched.witnessId} in everystack.schema_log — origin ${dispatched.origin ?? '(none)'} (the commit the backup recorded)`);
+  } else {
+    warn(
+      `WARNING: the ops Lambda recorded no restore witness. It predates restore witnesses, so it did not check the backup's ` +
+      `origin or roles, and nothing in ${stage}'s everystack.schema_log marks this restore. The restore is already running. ` +
+      `Fix: redeploy the ops Lambda (sst deploy --stage ${stage}) so restores record the witness.`,
+    );
+  }
+  if (dispatched.rolesUnchecked) {
+    warn('declared roles were not checked: this backup carries no authz manifest.');
+  }
+}
+
 /**
  * db:restore — pg_restore a backup INTO a stage's existing DB. Destructive (drops + replaces), so
  * it requires --confirm; restoring production-tier data downward or into a production target raises
@@ -340,6 +378,7 @@ export async function dbRestoreCommand(flags: Record<string, string>): Promise<v
   const { runId, taskArn, intentKey, warning } = dispatched as { runId: string; taskArn: string; intentKey: string; warning?: string };
   info(`restore of ${id} → ${toStage} — task ${taskArn}`);
   info(`intent: ${intentKey} (durable S3 record — survives the restore)`);
+  printRestoreWitness(dispatched, toStage);
   if (warning) info(`note: ${warning}`);
 
   step(`Restoring ${id} into ${toStage} (pg_restore in the Task; this may take a while)...`);