@everystack/cli 0.4.98 → 0.4.100

package/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.100] - 2026-10-16
+
+### Added
+
+- check() takes an explicit constraint name; db:pull keeps a live name
+
+### Fixed
+
+- db:apply runs a rename-only plan
+
+### Documentation
+
+- a check folded into .validate() takes the field check name
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.98",
+  "version": "0.4.100",
   "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.22"
   },
   "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.34"
+    "@everystack/server": "0.4.35"
   },
   "scripts": {
     "test": "jest",

package/src/cli/apply-execute.ts

@@ -73,6 +73,7 @@ import {
 import { validationPendingReason, pendingValidationsAreSafe } from './apply-refusals';
 import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply';
 import { checkPlanPrecondition, planHash, defaultAclHash, type EdgePlan } from './edge-plan';
+import { renameEdgeVerdict } from './catalog-rename';
 import type { DescentLedgerRow, LedgerRead } from './git-descent';
 
 /**
@@ -416,6 +417,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,
@@ -436,7 +478,20 @@ export async function executeApplyPlan(
   }
 
   if (live === plan.toFingerprint) {
-    return { status: 'already-applied', liveFingerprint: live };
+    // The hash is blind to a catalog rename (a check is keyed by predicate, an index or key by
+    // content), so a plan of renames alone has from == to == live whether or not it ran. Only
+    // then do the names decide, read from the same snapshot as the lock. Not landed: fall
+    // through, and every gate below runs. Half landed, or in a shape the plan never predicted:
+    // stale. Everything else is today's idempotent re-apply.
+    const verdict = plan.fromFingerprint === plan.toFingerprint
+      ? renameEdgeVerdict(plan.statements, before)
+      : { verdict: 'not-renames' as const };
+    if (verdict.verdict === 'stale') {
+      const reason = `this plan is stale: ${verdict.reason}. Re-mint with db:plan.`;
+      await recordRefusal(runner, plan, live, 'rename edge', reason, options);
+      return { status: 'refused', liveFingerprint: live, reason };
+    }
+    if (verdict.verdict !== 'unsettled') return { status: 'already-applied', liveFingerprint: live };
   }
   const pre = checkPlanPrecondition(plan, live);
   if (!pre.ok) {
@@ -622,3 +677,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/catalog-rename.ts

@@ -0,0 +1,115 @@
+/**
+ * catalog-rename — the catalog-only renames the planner emits, their parser, and the verdict
+ * db:apply reads from them.
+ *
+ * A rename of a check, a foreign key or an index changes no fingerprint: a check is hashed by its
+ * predicate and an index or key by its content. So a plan whose ONLY change is such a rename has
+ * from == to == live, and the endpoint cannot tell a rename that ran from one that did not. The
+ * live names can. The renderer and the parser live side by side here so they cannot drift; the
+ * parser accepts exactly what the renderer writes and nothing else.
+ */
+
+import type { SchemaSnapshot } from './schema-introspect';
+import { isPureComment } from './sql-statement';
+
+/** The same quoting schema-diff uses for every identifier it emits. */
+const quote = (name: string): string => `"${name}"`;
+
+/** `public.orders` → `public.`; an unqualified table carries no qualifier. */
+const schemaPrefix = (table: string): string => (table.includes('.') ? `${table.split('.')[0]}.` : '');
+
+export interface RenameChange {
+  /** Schema-qualified, as the snapshot spells it (`public.orders`). */
+  table: string;
+  from: string;
+  to: string;
+}
+
+/** `ALTER TABLE … RENAME CONSTRAINT` — catalog-only and instant; the constraint keeps its identity. */
+export function renderConstraintRename(change: RenameChange): string {
+  return `ALTER TABLE ${change.table} RENAME CONSTRAINT ${quote(change.from)} TO ${quote(change.to)};`;
+}
+
+/** `ALTER INDEX … RENAME TO` — no rebuild. The schema qualifies the OLD name only. */
+export function renderIndexRename(change: RenameChange): string {
+  return `ALTER INDEX ${schemaPrefix(change.table)}${quote(change.from)} RENAME TO ${quote(change.to)};`;
+}
+
+export type CatalogRename =
+  | { kind: 'constraint'; table: string; from: string; to: string }
+  /** ALTER INDEX names no table — an index name is unique within its schema, so the schema is the scope. */
+  | { kind: 'index'; schema: string; from: string; to: string };
+
+const IDENT = '"([^"]*)"';
+const CONSTRAINT_RE = new RegExp(`^ALTER TABLE (\\S+) RENAME CONSTRAINT ${IDENT} TO ${IDENT};$`);
+const INDEX_RE = new RegExp(`^ALTER INDEX (?:([^\\s."]+)\\.)?${IDENT} RENAME TO ${IDENT};$`);
+
+/** The rename a statement is, if it is exactly one the renderers above produce; otherwise null. */
+export function parseCatalogRename(sql: string): CatalogRename | null {
+  const c = CONSTRAINT_RE.exec(sql);
+  if (c) return { kind: 'constraint', table: c[1], from: c[2], to: c[3] };
+  const i = INDEX_RE.exec(sql);
+  // An unqualified ALTER INDEX resolves through search_path; the renderer only writes one for an
+  // unqualified table, which the snapshot spells as `public`.
+  if (i) return { kind: 'index', schema: i[1] ?? 'public', from: i[2], to: i[3] };
+  return null;
+}
+
+export type RenameEdgeVerdict =
+  /** Empty, or some statement is not a recognized rename — the names have nothing to say. */
+  | { verdict: 'not-renames' }
+  /** Every rename already landed: `to` present, `from` absent. */
+  | { verdict: 'settled' }
+  /** No rename has landed: `from` present, `to` absent. The edge still has to run. */
+  | { verdict: 'unsettled' }
+  /** Anything else — the plan describes neither the database before it nor after it. */
+  | { verdict: 'stale'; reason: string };
+
+/**
+ * Where each rename in the edge stands in the BEFORE snapshot (the one the lock was computed
+ * from). Only an edge made entirely of recognized renames gets a verdict other than
+ * `not-renames`; one rename in an odd state, or a mix of landed and not, makes the plan stale.
+ */
+export function renameEdgeVerdict(statements: readonly string[], before: SchemaSnapshot): RenameEdgeVerdict {
+  // A comment is never run, and the planner writes them beside real changes (an inert
+  // renamedFrom notice, a held drop). They must not hide a rename edge from the names.
+  const real = statements.filter((sql) => !isPureComment(sql));
+  if (real.length === 0) return { verdict: 'not-renames' };
+  const renames: CatalogRename[] = [];
+  for (const sql of real) {
+    const rename = parseCatalogRename(sql);
+    if (!rename) return { verdict: 'not-renames' };
+    renames.push(rename);
+  }
+
+  const settled: string[] = [];
+  const unsettled: string[] = [];
+  for (const rename of renames) {
+    let present: Set<string>;
+    let where: string;
+    if (rename.kind === 'constraint') {
+      const table = before.tables.find((t) => t.table === rename.table);
+      if (!table) return { verdict: 'stale', reason: `table ${rename.table} does not exist` };
+      present = new Set([...table.checks, ...table.foreignKeys, ...table.uniques].map((c) => c.name));
+      where = `on ${rename.table}`;
+    } else {
+      present = new Set(before.tables
+        .filter((t) => t.table.startsWith(`${rename.schema}.`))
+        .flatMap((t) => t.indexes.map((ix) => ix.name)));
+      where = `in schema ${rename.schema}`;
+    }
+    const hasFrom = present.has(rename.from);
+    const hasTo = present.has(rename.to);
+    const label = `"${rename.from}" → "${rename.to}"`;
+    if (hasTo && !hasFrom) settled.push(label);
+    else if (hasFrom && !hasTo) unsettled.push(label);
+    else if (hasFrom && hasTo) return { verdict: 'stale', reason: `both "${rename.from}" and "${rename.to}" exist ${where}` };
+    else return { verdict: 'stale', reason: `neither "${rename.from}" nor "${rename.to}" exists ${where}` };
+  }
+  if (unsettled.length === 0) return { verdict: 'settled' };
+  if (settled.length === 0) return { verdict: 'unsettled' };
+  return {
+    verdict: 'stale',
+    reason: `some of its renames are already applied (${settled.join(', ')}) and some are not (${unsettled.join(', ')})`,
+  };
+}

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)...`);