@everystack/cli 0.4.98 → 0.4.99

package/CHANGELOG.md

@@ -4,6 +4,34 @@ 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

package/package.json

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

package/src/cli/apply-execute.ts

@@ -416,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,
@@ -622,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-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)...`);

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

@@ -44,6 +44,7 @@ import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, t
 import type { SequenceDescriptor } from '@everystack/model';
 import type { SourceObject } from '../derived-source';
 import { findReadAuthzGaps, findNakedGrants } from '../authz-lint';
+import { findSelectGrantGaps } from '../select-grant-advisory';
 import { parseBaseline, renderBaseline, BASELINE_FILE } from '../authz-baseline';
 import {
   findDerivedReadGaps, findSecdefExecuteGaps, findMatviewSnapshotWarnings, findPublicExecutableSecdef,
@@ -69,6 +70,14 @@ export interface CheckFinding {
   message: string;
 }
 
+/** The quiet default's one line: failing findings are "pending", warnings ride along and never fail the gate. */
+export function checkVerdictLines(findings: readonly CheckFinding[], ephemeralFailed: boolean): string[] {
+  return renderCheckVerdict(
+    findings.filter((f) => f.level === 'fail').length + (ephemeralFailed ? 1 : 0),
+    findings.filter((f) => f.level === 'warn').length,
+  );
+}
+
 export interface StaticCheckInput {
   modelsPath: string;
   /** Barrel siblings and what each declares — the "on disk but ungoverned" scan. */
@@ -197,6 +206,12 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
     findings.push({ level: 'warn', area: 'authz', message: naked.message });
   }
 
+  // A write grant with no SELECT beside it: every UPDATE/DELETE ... WHERE (and any RETURNING) by
+  // that role is "permission denied". WARN: the grant set is legal, only its use is broken.
+  for (const gap of findSelectGrantGaps(input.models)) {
+    findings.push({ level: 'warn', area: 'authz', message: gap.message });
+  }
+
   // The adoption baseline, ARTIFACT ONLY.
   //
   // This check cannot see the threat and must not pretend to. The foreign grantees it
@@ -494,9 +509,7 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
     // every failing finding, plus the from-scratch build when it did not land where the models
     // say it should. `db:plan` is the verb that shows each one against a real target, so it is
     // the only command the line names. Re-run with --verbose to read the findings themselves.
-    for (const text of renderCheckVerdict(
-      findings.filter((f) => f.level === 'fail').length + (ephemeralFailed ? 1 : 0),
-    )) printLine(text);
+    for (const text of checkVerdictLines(findings, ephemeralFailed)) printLine(text);
   }
 
   if (failed) process.exit(1);

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

@@ -21,9 +21,10 @@
 
 import { resolveConfig, opsFunction, type CliConfig } from '../config';
 import { invokeAction, presignGet } from '../aws';
-import { keyForId, parseBackupRef, isProductionTier, crossStageGuard } from '../backup';
+import { keyForId, metaKey, parseBackupRef, isProductionTier, crossStageGuard } from '../backup';
 import { pollTaskUntilStopped } from '../task-poll';
 import { runStageBackup, stageBackupDeps } from '../stage-backup';
+import { printRestoreWitness } from './db-backup';
 import { step, success, fail, info, warn } from '../output';
 
 export type ForkGuardVerdict =
@@ -109,11 +110,16 @@ export async function dbForkCommand(flags: Record<string, string>): Promise<void
     info(`Backup ${backupId}.`);
   }
 
-  // Move 2: the presigned hand-off — the operator's credentials ARE the authorization.
-  step('Presigning the dump (1 hour)...');
+  // Move 2: the presigned hand-off — the operator's credentials ARE the authorization. The meta
+  // travels beside the dump: the target's Lambda reads the backup's origin commit from it (the
+  // restore witness), since it cannot read the source stage's bucket itself.
+  step('Presigning the dump and its meta (1 hour)...');
   let url: string;
+  let metaUrl: string;
   try {
-    url = await presignGet(source.region, source.backupsBucket, keyForId(backupId)!, 3600);
+    const key = keyForId(backupId)!;
+    url = await presignGet(source.region, source.backupsBucket, key, 3600);
+    metaUrl = await presignGet(source.region, source.backupsBucket, metaKey(key), 3600);
   } catch (err: any) {
     fail(`Presign failed: ${err.message}`);
     process.exit(1);
@@ -131,6 +137,7 @@ export async function dbForkCommand(flags: Record<string, string>): Promise<void
   step(`Restoring into ${target} (pg_restore in the Task; replaces its database)...`);
   const restored: any = await invokeAction(targetConfig.region, opsFunction(targetConfig), 'db:restore', {
     url,
+    metaUrl,
     confirm: true,
     actor: process.env.USER ?? null,
   });
@@ -138,6 +145,7 @@ export async function dbForkCommand(flags: Record<string, string>): Promise<void
     fail(`Restore failed: ${restored.error}`);
     process.exit(1);
   }
+  printRestoreWitness(restored, target);
   const rPoll = await pollTaskUntilStopped(targetConfig.region, opsFunction(targetConfig), { runId: restored.runId, taskArn: restored.taskArn });
   if (rPoll.outcome !== 'stopped' || rPoll.status.exitCode !== 0) {
     const why = rPoll.outcome === 'stopped' ? `exit ${rPoll.status.exitCode}${rPoll.status.stoppedReason ? ` — ${rPoll.status.stoppedReason}` : ''}` : rPoll.outcome;

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

@@ -23,6 +23,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import type { ModelDescriptor, Module } from '@everystack/model';
+import { linkModels } from '@everystack/model';
 import { introspectSchema } from '../schema-introspect';
 import { compileDrizzleSource } from '../schema-source';
 import { compileModuleMigration } from '../migration-compile';
@@ -60,7 +61,7 @@ export async function loadModels(modelsPath: string): Promise<ModelDescriptor[]>
     const models = mod.models ?? mod.default;
     if (!Array.isArray(models)) throw new Error(`${modelsPath} must export a \`models\` array (got ${typeof models}).`);
     assertNoHoles(modelsPath, 'models', models);
-    return models;
+    return linkModels(models);
   } catch (err) {
     throw asModelComposeError(modelsPath, err);
   }
@@ -80,9 +81,12 @@ export async function loadModules(modelsPath: string): Promise<Module[]> {
   } catch (err: any) {
     throw new Error(`Could not load modules from ${modelsPath}: ${err.message}`);
   }
-  if (Array.isArray(mod.modules)) return mod.modules;
+  if (Array.isArray(mod.modules)) {
+    linkModels(mod.modules.flatMap((module: Module) => module.models));
+    return mod.modules;
+  }
   const models = mod.models ?? mod.default;
-  if (Array.isArray(models)) return [{ models, extensions: [], sequences: [], derived: [], governedRoles: [], functions: [] }];
+  if (Array.isArray(models)) return [{ models: linkModels(models), extensions: [], sequences: [], derived: [], governedRoles: [], functions: [] }];
   throw new Error(`${modelsPath} must export a \`modules\` (or \`models\`) array.`);
 }
 

package/src/cli/commands/db.ts

@@ -1344,7 +1344,7 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
 }
 
 /** Render a doctor report — identical output whichever venue produced it. */
-function printDoctorReport(report: any): void {
+export function printDoctorReport(report: any): void {
   console.log('');
   info(`api connection (DATABASE_URL):    role=${report.api.role}  superuser=${report.api.isSuperuser}  bypassrls=${report.api.bypassRls}`);
   info(`operator connection (ADMIN_URL):  role=${report.admin.role}  superuser=${report.admin.isSuperuser}  bypassrls=${report.admin.bypassRls}`);
@@ -1361,7 +1361,8 @@ function printDoctorReport(report: any): void {
   if (report.ok) {
     success('db:doctor — database is least-privilege and RLS-subject');
   } else {
-    fail('db:doctor — the api connection is NOT correctly least-privilege (see failures above)');
+    const failed = (report.checks as Array<{ status: string }>).filter((c) => c.status === 'fail').length;
+    fail(`db:doctor — ${failed} check(s) failed (see failures above)`);
     // Probing a local database as your own superuser makes these fail by construction:
     // the checks describe the credential the API serves with, not the schema. A developer
     // reading them as defects in their app will go hunting for a bug that is not there.