@everystack/server 0.4.34 → 0.4.35

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to `@everystack/server` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.35] - 2026-10-14
+
+### Added
+
+- stamp originCommit and authzManifest into the backup meta
+- db:backup:stamp-authz merges the manifest into a finished backup
+- db:restore and db:fork write a restore witness from the backup's origin (#15)
+- db:doctor fails when an app role bypasses RLS
+
+### Fixed
+
+- lease the ops-Lambda write path, no driver fork
+- never recycle the leased mutation connection
+- import the lease inside db:apply's try
+- three fold-ins from the bounded re-review
+- an _action name resolves only to an own key of actions
+- db:doctor probes the app's own request roles
+- db:doctor prints each fix once and an accurate closing line
+
 ## [0.4.34] - 2026-09-27
 
 ### Added

package/README.md

@@ -147,7 +147,7 @@ Actions contributed (each is an `everystack db:*` command):
 |---|---|
 | `migrate` / `seed` / `db:reset` | run migrations, seed (dev), drop+remigrate (dev) |
 | `db:psql` / `db:query` | connection info / read-only SQL via Lambda |
-| `db:doctor` | audit: is the API connection least-privilege + RLS-subject? Flags BYPASSRLS, un-FORCEd RLS, and **app-reachable tables without RLS** |
+| `db:doctor` | audit: is the API connection least-privilege + RLS-subject? Flags BYPASSRLS, un-FORCEd RLS, **app-reachable tables without RLS**, and **an app role (anon/authenticated/admin) that is SUPERUSER or BYPASSRLS** |
 | `db:provision` | create the least-privilege role chain on an existing DB (idempotent; roles only) |
 | `db:backup` | dispatched to the Fargate Task lane: `pg_dump -Fc` → gzip → S3 (streamed), fingerprint-stamped; awaits the child exit code, deletes the partial on failure |
 | `db:backups` | list a stage's backups |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.4.34",
+  "version": "0.4.35",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -120,6 +120,11 @@
       "source": "./src/backup-run.ts",
       "types": "./src/backup-run.ts",
       "default": "./src/backup-run.ts"
+    },
+    "./restore-witness": {
+      "source": "./src/restore-witness.ts",
+      "types": "./src/restore-witness.ts",
+      "default": "./src/restore-witness.ts"
     }
   },
   "peerDependencies": {
@@ -130,7 +135,7 @@
     "@aws-sdk/s3-request-presigner": "3.1053.0",
     "@aws-sdk/signature-v4a": ">=3.1048.0",
     "@everystack/auth": ">=0.1.0",
-    "@everystack/cli": ">=0.1.0",
+    "@everystack/cli": ">=0.4.99",
     "drizzle-orm": "0.41.0",
     "heic-decode": "2.1.0",
     "postgres": "3.4.9",
@@ -187,8 +192,8 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/cli": "0.4.98",
-    "@everystack/auth": "0.4.8"
+    "@everystack/auth": "0.4.9",
+    "@everystack/cli": "0.4.99"
   },
   "scripts": {
     "test": "jest",

package/src/backup-run.ts

@@ -20,7 +20,7 @@ import {
   backupPrefix, metaKey, idForKey, keyForId,
   pgEnvFromUrl, dbNameFromUrl, pgDumpArgs, pgRestoreArgs,
   restoreIntentPrefix,
-  type BackupManifest, type RestoreIntent,
+  type BackupManifest, type BackupAuthzManifest, type RestoreIntent,
 } from './backup';
 
 /** Where backups live + the operator connection pg_dump/pg_restore use. */
@@ -91,6 +91,8 @@ export interface BackupTarget {
    * pre-B3 or fp-less backup can't be a verified net).
    */
   fingerprint?: string;
+  /** The operator-read origin commit (BackupManifest.originCommit) — stamped as sent, never read here. */
+  originCommit?: string | null;
 }
 
 /**
@@ -121,23 +123,86 @@ export function buildBackupMeta(input: {
   fingerprint?: string;
   /** Who computed it. Defaults to 'operator' — the only producer today. */
   fingerprintSource?: string;
+  /** The operator-read origin commit. `null` is a value (proven none) and is stamped; undefined is not. */
+  originCommit?: string | null;
+  /** The operator-rendered declared-authz manifest, stamped as sent. */
+  authzManifest?: BackupAuthzManifest;
   // Returns the CONSUMER's type, not Record<string, unknown>: that is what makes producer/consumer
   // drift a compile error instead of a runtime surprise the gate discovers.
 }): BackupManifest {
-  const { id, stage, key, createdAt, bytes, fingerprint, fingerprintSource } = input;
-  return {
+  const { id, stage, key, createdAt, bytes, fingerprint, fingerprintSource, originCommit, authzManifest } = input;
+  const meta: BackupManifest = {
     id, stage, createdAt, bytes, key,
     // `fingerprintSource` records HOW the value was obtained, not just that it exists. The gate
     // accepts an operator-computed fingerprint by design, so that decision should be auditable
     // after the fact rather than reconstructed from version archaeology — and a future gate can
     // tighten on it without guessing.
     ...(fingerprint ? { fingerprint, metaVersion: 2, fingerprintSource: fingerprintSource ?? 'operator' } : {}),
+    // Appended AFTER every pre-existing key, and only when present, so a caller passing neither
+    // writes byte-identical JSON to before these fields existed.
+    ...(originCommit !== undefined ? { originCommit } : {}),
   };
+  return authzManifest !== undefined ? withAuthzManifest(meta, authzManifest) : meta;
+}
+
+/**
+ * Stamp the declared-authz manifest onto a backup manifest — the ONE place that field is written,
+ * whether at build time or by the post-dump stamp. Appended after every existing key; nothing else
+ * is touched. In particular provenance is never re-stamped: running an already-written manifest back
+ * through buildBackupMeta would mark any fingerprint `metaVersion: 2`, upgrading a task-computed
+ * fingerprint into one the destructive-apply gate trusts.
+ */
+export function withAuthzManifest(meta: BackupManifest, authzManifest: BackupAuthzManifest): BackupManifest {
+  const { authzManifest: _replaced, ...rest } = meta;
+  return { ...rest, authzManifest };
+}
+
+/**
+ * The post-dump stamp: read the `.meta.json` the task wrote for `key`, merge the operator-rendered
+ * authz manifest in (withAuthzManifest), write it back. The manifest cannot ride the task job — the
+ * job is one ECS env override capped at 8192 chars — so the CLI sends it here once the dump has
+ * succeeded. A backup this never reaches simply lacks the field, which a restore treats as "no
+ * manifest", never as an empty one.
+ *
+ * Refuses rather than invents: no stored manifest (the dump failed or was retracted) or one that
+ * describes a different dump is an error, and nothing is written.
+ */
+export async function stampBackupAuthz(
+  deps: Pick<BackupRunDeps, 'bucket' | 'region'> & {
+    /** Injected S3 client — the seam that lets the read/merge/write be tested. */
+    s3?: { send: (command: unknown) => Promise<unknown> };
+  },
+  key: string,
+  authzManifest: BackupAuthzManifest,
+): Promise<BackupManifest> {
+  const s3 = deps.s3 ?? (await getS3(deps.region));
+  const { GetObjectCommand, PutObjectCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-s3'),
+    '@aws-sdk/client-s3',
+    'db:backup',
+  );
+  const mkey = metaKey(key);
+  let existing: BackupManifest;
+  try {
+    const obj: any = await s3.send(new GetObjectCommand({ Bucket: deps.bucket, Key: mkey }));
+    existing = JSON.parse(await obj.Body.transformToString()) as BackupManifest;
+  } catch (err: any) {
+    throw new Error(`no manifest to stamp at ${mkey} (${err?.name ?? 'error'}: ${err?.message ?? String(err)}) — the dump may have failed or been retracted.`);
+  }
+  if (existing.key !== key) {
+    throw new Error(`the manifest at ${mkey} describes ${existing.key}, not ${key} — refusing to stamp it.`);
+  }
+  const merged = withAuthzManifest(existing, authzManifest);
+  await s3.send(new PutObjectCommand({
+    Bucket: deps.bucket, Key: mkey, Body: JSON.stringify(merged),
+    ContentType: 'application/json', ServerSideEncryption: 'AES256',
+  }));
+  return merged;
 }
 
 export async function runBackup(deps: BackupRunDeps, target: BackupTarget): Promise<BackupSummary> {
   const { bucket, region, adminUrl } = deps;
-  const { stage, id, key, fingerprint } = target;
+  const { stage, id, key, fingerprint, originCommit } = target;
   const env = { ...process.env, ...pgEnvFromUrl(adminUrl) };
   const mkey = metaKey(key);
 
@@ -189,7 +254,7 @@ export async function runBackup(deps: BackupRunDeps, target: BackupTarget): Prom
     bytes = head.ContentLength;
   } catch { /* size is best-effort */ }
 
-  const meta = buildBackupMeta({ id, stage, key, bytes, fingerprint, createdAt: new Date().toISOString() });
+  const meta = buildBackupMeta({ id, stage, key, bytes, fingerprint, originCommit, createdAt: new Date().toISOString() });
   await s3.send(new PutObjectCommand({
     Bucket: bucket, Key: mkey, Body: JSON.stringify(meta),
     ContentType: 'application/json', ServerSideEncryption: 'AES256',
@@ -271,7 +336,7 @@ export async function runExport(
  * ONLY on a successful dump, so absence == "no completed backup with that id"). The verify treats
  * null as a refusal.
  */
-export async function fetchBackupManifest(deps: BackupRunDeps, id: string): Promise<BackupManifest | null> {
+export async function fetchBackupManifest(deps: Pick<BackupRunDeps, 'bucket' | 'region'>, id: string): Promise<BackupManifest | null> {
   const key = keyForId(id);
   if (!key) return null;
   const s3 = await getS3(deps.region);

package/src/backup.ts

@@ -165,6 +165,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 {
@@ -265,6 +286,10 @@ export interface RestoreIntent {
   taskArn?: string;
   status?: 'started' | 'running' | 'succeeded' | 'failed';
   finishedAt?: string;
+  /** The schema_log witness row the dispatcher wrote in the target (restore-witness.ts). */
+  witnessId?: string;
+  /** The commit the restored state descends from — the backup meta's `originCommit`. */
+  origin?: string;
 }
 
 /** Format a Date as the UTC `YYYYMMDDTHHMMSSZ` stamp (caller's clock; pure). */

package/src/db-doctor.ts

@@ -87,6 +87,21 @@ export interface DoctorProbe {
    * an older probe (the check is then skipped). B4.
    */
   darkRelations?: DarkRelation[];
+  /**
+   * The app roles the handler SET ROLEs into (anon/authenticated/admin), with their own
+   * SUPERUSER and BYPASSRLS attributes. Either one skips every policy, so RLS on every table
+   * enforces nothing for that role. Membership does not pass these attributes on, so no
+   * transitive check is needed. A configured role missing from the database is simply absent
+   * here. Absent on an older probe (the check is then skipped).
+   */
+  appRoleAttrs?: AppRoleAttrs[];
+}
+
+/** An app role's own RLS-relevant attributes, read from pg_roles. */
+export interface AppRoleAttrs {
+  role: string;
+  isSuperuser: boolean;
+  bypassRls: boolean;
 }
 
 /** A function PUBLIC can EXECUTE, and whether it runs as its owner (the dangerous half). */
@@ -259,6 +274,18 @@ function pgTextArray(v: unknown): string[] {
 
 const ROLE_IDENT = /^[a-z_][a-z0-9_]*$/;
 
+/** The role-chain request roles db:doctor probes when the app names none of its own. */
+export const DEFAULT_APP_ROLES: readonly string[] = ['anon', 'authenticated', 'admin'];
+
+/** Validate app-role names as plain idents, then quote each as a SQL literal: `'a', 'b'`. */
+function appRoleLiterals(appRoles: readonly string[]): string {
+  if (appRoles.length === 0) throw new Error('Invalid app roles: empty list');
+  for (const r of appRoles) {
+    if (!ROLE_IDENT.test(r)) throw new Error(`Invalid app role: ${JSON.stringify(r)}`);
+  }
+  return appRoles.map((r) => `'${r}'`).join(', ');
+}
+
 /**
  * Every base table an app role can reach — a table-level grant (`relacl`) OR a column-level
  * grant (`attacl`, the "revoke the table, grant safe columns" shape) — with its RLS flags.
@@ -267,11 +294,8 @@ const ROLE_IDENT = /^[a-z_][a-z0-9_]*$/;
  * (it only inspects tables that already have RLS on). App-role names are validated idents
  * (they're interpolated); they default to the role-chain set. Extension tables are excluded.
  */
-export function appGrantsRlsSql(appRoles: string[] = ['anon', 'authenticated', 'admin']): string {
-  for (const r of appRoles) {
-    if (!ROLE_IDENT.test(r)) throw new Error(`Invalid app role: ${JSON.stringify(r)}`);
-  }
-  const roleList = appRoles.map((r) => `'${r}'`).join(', ');
+export function appGrantsRlsSql(appRoles: readonly string[] = DEFAULT_APP_ROLES): string {
+  const roleList = appRoleLiterals(appRoles);
   return `
 WITH app_granted AS (
   SELECT c.oid, r.rolname
@@ -304,6 +328,29 @@ ORDER BY n.nspname, c.relname;
 `.trim();
 }
 
+/**
+ * The app roles' own SUPERUSER and BYPASSRLS attributes. The runner takes plain SQL text (no
+ * bind parameters), so the role names are validated the same way appGrantsRlsSql does it:
+ * each must match ROLE_IDENT before it is quoted into a literal, and anything else throws.
+ */
+export function appRoleAttrsSql(appRoles: readonly string[] = DEFAULT_APP_ROLES): string {
+  return `
+SELECT rolname, rolsuper, rolbypassrls
+FROM pg_roles
+WHERE rolname = ANY (ARRAY[${appRoleLiterals(appRoles)}]::text[])
+ORDER BY rolname
+`.trim();
+}
+
+/** Map an appRoleAttrsSql row to AppRoleAttrs (tolerant of pg driver boolean encodings). */
+export function rowToAppRoleAttrs(row: any): AppRoleAttrs {
+  return {
+    role: String(row.rolname),
+    isSuperuser: pgBool(row.rolsuper),
+    bypassRls: pgBool(row.rolbypassrls),
+  };
+}
+
 /** Options for the report builder. */
 export interface DoctorReportOptions {
   /**
@@ -368,6 +415,36 @@ export function buildDoctorReport(probe: DoctorProbe, options: DoctorReportOptio
     detail: api.bypassRls ? `"${api.role}" has the BYPASSRLS attribute — every policy is skipped` : `"${api.role}" is subject to RLS`,
   });
 
+  // The roles the handler SET ROLEs into. The api role above can be clean and every table can
+  // have RLS + FORCE, yet a superuser or BYPASSRLS app role still skips every policy. A role
+  // missing from the database is not this check's failure: SET ROLE into it errors (fails closed).
+  if (probe.appRoleAttrs) {
+    const lines: string[] = [];
+    const fixes: string[] = [];
+    for (const r of probe.appRoleAttrs) {
+      if (r.isSuperuser) {
+        lines.push(`app role ${r.role} is a superuser; every policy is skipped.`);
+        fixes.push(`ALTER ROLE ${r.role} NOSUPERUSER;`);
+      }
+      if (r.bypassRls) {
+        lines.push(`app role ${r.role} is BYPASSRLS; every policy is skipped.`);
+        fixes.push(`ALTER ROLE ${r.role} NOBYPASSRLS;`);
+      }
+    }
+    const names = probe.appRoleAttrs.map((r) => r.role).sort();
+    checks.push(
+      lines.length > 0
+        ? { name: 'App roles are subject to RLS', status: 'fail', detail: lines.join(' '), remediation: fixes.join(' ') }
+        : {
+            name: 'App roles are subject to RLS',
+            status: 'pass',
+            detail: names.length > 0
+              ? `app role(s) ${names.join(', ')} are neither superuser nor BYPASSRLS`
+              : 'no app role found on this database; nothing to check',
+          },
+    );
+  }
+
   // The definitive least-privilege test: can the api connection read an RLS table with no
   // SET ROLE? A role can pass "not superuser / no bypassrls / FORCE on" and still see every
   // row through INHERITed membership in a USING(true) role (the master's leak path). Only a
@@ -632,6 +709,10 @@ export interface DoctorProbeRunners {
 export interface RunDoctorProbeOptions extends DoctorReportOptions {
   /** Names the api credential source in the connect-failure message (e.g. 'DATABASE_URL'). */
   apiSourceLabel?: string;
+  /** The app's request roles (the ones the handler SET ROLEs into), probed for RLS-off grants
+   *  and SUPERUSER/BYPASSRLS. Default: DEFAULT_APP_ROLES (anon/authenticated/admin). Each must
+   *  be a plain ident; a bad name or an empty list throws. */
+  appRoles?: string[];
 }
 
 const quoteDoctorIdent = (s: string): string => '"' + String(s).replace(/"/g, '""') + '"';
@@ -656,6 +737,9 @@ export async function runDoctorProbe(
 ): Promise<DoctorReport> {
   const { api: apiRun, ops: opsRun } = runners;
   const sourceLabel = options.apiSourceLabel ?? 'DATABASE_URL';
+  // Built before any query so a bad role name throws before a connection is touched.
+  const grantsSql = appGrantsRlsSql(options.appRoles);
+  const roleAttrsSql = appRoleAttrsSql(options.appRoles);
 
   let api: ConnInfo;
   try {
@@ -666,10 +750,11 @@ export async function runDoctorProbe(
 
   const admin = rowToConnInfo((await opsRun(CONN_SQL))[0]);
   const forceRls = (await opsRun(FORCE_RLS_SQL)).map(rowToForceRls);
-  const appGrantedRls = (await opsRun(appGrantsRlsSql())).map(rowToAppGranted);
+  const appGrantedRls = (await opsRun(grantsSql)).map(rowToAppGranted);
   const secdefFunctions = (await opsRun(SECDEF_FUNCTIONS_SQL)).map(rowToSecdefFn);
   const publicExecutableFunctions = (await opsRun(PUBLIC_EXECUTABLE_FUNCTIONS_SQL)).map(rowToPublicExecutableFn);
   const darkRelations = (await opsRun(DARK_RELATIONS_SQL)).map(rowToDarkRelation);
+  const appRoleAttrs = (await opsRun(roleAttrsSql)).map(rowToAppRoleAttrs);
 
   // Ambient-access probe: can the api connection read an RLS table WITHOUT SET ROLE? A
   // least-privilege role must fail closed here; a role that returns rows carries ambient
@@ -687,7 +772,7 @@ export async function runDoctorProbe(
   }
 
   return buildDoctorReport(
-    { api, admin, forceRls, appGrantedRls, apiAmbientRead, secdefFunctions, publicExecutableFunctions, darkRelations },
+    { api, admin, forceRls, appGrantedRls, apiAmbientRead, secdefFunctions, publicExecutableFunctions, darkRelations, appRoleAttrs },
     { forceRlsCarveouts: options.forceRlsCarveouts, functionSchemas: options.functionSchemas },
   );
 }

package/src/db.ts

@@ -198,7 +198,7 @@ export function sslOptionForUrl(url: string): 'require' | undefined {
 }
 
 /** postgres.js options shared by every connection — ssl derived from the URL. */
-function connectionOptions(url: string, maxConnections?: number): Parameters<typeof postgres>[1] {
+export function connectionOptions(url: string, maxConnections?: number): Parameters<typeof postgres>[1] {
   const ssl = sslOptionForUrl(url);
   return {
     max: maxConnections ?? 1,
@@ -209,6 +209,17 @@ function connectionOptions(url: string, maxConnections?: number): Parameters<typ
   };
 }
 
+/**
+ * Options for the disposable connection a mutating ops action leases for its whole duration.
+ * It holds a session advisory lock (the mutation lease), so the driver must never recycle it:
+ * a `max_lifetime` or `idle_timeout` close mid-action silently swaps in a new backend and the
+ * lock is gone with the old one. Both are off; the caller always `.end()`s it in a `finally`.
+ * Same reasoning as the CLI's `createUrlRunner` (packages/cli/src/cli/db-source.ts).
+ */
+export function mutationConnectionOptions(url: string): Parameters<typeof postgres>[1] {
+  return { ...connectionOptions(url, 1), max_lifetime: null, idle_timeout: 0 };
+}
+
 // Lazy singleton DB connection
 let dbInstance: ReturnType<typeof drizzle> | null = null;
 let sqlClient: ReturnType<typeof postgres> | null = null;

package/src/index.ts

@@ -233,6 +233,8 @@ export function createLambdaHandler(
     // Events with _action are NOT HTTP events (no requestContext.http).
     if ('_action' in event && typeof event._action === 'string' && options.onAction) {
       const { handlers } = await ensureInitialized();
+      // The app's `onAction` owns the name lookup. A map lookup there should read own keys only
+      // (`Object.hasOwn`), or `constructor` and the other Object.prototype members resolve.
       log('info', 'CLI action invoked', { action: event._action });
       try {
         return await options.onAction(event._action, event._payload, handlers);

package/src/mutation-connection.ts

@@ -0,0 +1,33 @@
+/**
+ * The disposable operator connection a mutating ops action leases for its own duration: its
+ * own dedicated socket, never the shared opsDb. opsDb is long-lived per warm container and
+ * reused across unrelated invocations; pinning a session advisory lock (the mutation lease)
+ * or a multi-statement DDL session onto it would leak the lock, or leftover session state,
+ * into whatever unrelated action this container serves next. This connection starts clean,
+ * is used for exactly one write, and is always closed when that write ends.
+ *
+ * It is FENCED (@everystack/cli/connection-fence): if its backend dies mid-action, the next
+ * statement fails with a named ConnectionLostError. It never reconnects onto a new, unleased
+ * backend, and it never reaches the driver's uncaught write on a closed socket. So this
+ * connection carries no drizzle `transaction`: transactions and sessions are plain
+ * statements through the fence.
+ */
+
+import type { FencedConnection } from '@everystack/cli/connection-fence';
+import * as db from './db';
+
+export async function openMutationConnection(): Promise<FencedConnection> {
+  const op = db.getOperatorDatabaseUrl();
+  if (!op) {
+    throw new Error('no operator database connection configured (ADMIN_DATABASE_URL / Postgres master)');
+  }
+  const postgres = (await import('postgres')).default;
+  const { createConnectionFence, fencedConnection } = await import('@everystack/cli/connection-fence');
+  const fence = createConnectionFence();
+  const options = db.mutationConnectionOptions(op.url) as Record<string, unknown>;
+  const client = postgres(op.url, {
+    ...options,
+    onclose: fence.onclose(options.onclose as ((id: number) => void) | undefined),
+  });
+  return fencedConnection(client as unknown as Parameters<typeof fencedConnection>[0], fence);
+}

package/src/plugin.ts

@@ -13,6 +13,7 @@ import type {
   APIGatewayProxyStructuredResultV2,
 } from 'aws-lambda';
 import type { ApplyPlanOptions } from '@everystack/cli/apply';
+import type { FencedConnection } from '@everystack/cli/connection-fence';
 // The Model-derived wire payloads, declared once in @everystack/model/wire and re-exported by
 // @everystack/cli/wire (the CLI is the only @everystack/* package this bundle can resolve the
 // declaration through — see packages/cli/src/wire.ts). Type-only, so nothing new is bundled.
@@ -230,7 +231,9 @@ export function createPluginLambdaHandler(
       }
       const { ctx, actions } = await ensureInitialized();
       const actionName = event._action;
-      const actionHandler = actions[actionName];
+      // Own keys only: `actions` is a plain object, so a bare index would also resolve the members
+      // it inherits from Object.prototype (`constructor`, `toString`, ...) and call one as a handler.
+      const actionHandler = Object.hasOwn(actions, actionName) ? actions[actionName] : undefined;
       if (!actionHandler) {
         return { error: `Unknown action: ${actionName}` };
       }
@@ -608,6 +611,12 @@ export interface DbPluginOptions {
    * notification tables), so the list can't drift from the contract.
    */
   forceRlsCarveouts?: string[];
+  /**
+   * The app's request roles, if it has its own (a `roleHierarchy`, or a role like 'member').
+   * db:doctor probes these for RLS-off grants and SUPERUSER/BYPASSRLS. Default: anon,
+   * authenticated, admin. Names are lowercase letters, digits and underscores; a bad name or an empty list fails the probe.
+   */
+  appRoles?: string[];
   /**
    * Schemas that own a `writtenBy: 'functions'` table (e.g. `['auth']`). Pass
    * `deriveFunctionSchemas(models)`. db:doctor's `functions` teeth assert each such schema has
@@ -961,14 +970,22 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       return { rows };
     };
 
-    // A SessionRunner over THIS container's operator connection, for the in-Lambda verbs
-    // (db:apply's fingerprint endpoints, db:reconcile's catalog read). Same core the
-    // db:session action serves over the wire, so both mean the same thing by "one session".
-    const sessionOverOpsDb = (sql: { raw: (q: string) => any }) =>
+    // A SessionRunner over a given drizzle db — the in-Lambda verbs (db:apply's fingerprint
+    // endpoints, db:reconcile's catalog read) share this core with the db:session action, so
+    // both mean the same thing by "one session".
+    const sessionOverDb = (db: any, sql: { raw: (q: string) => any }) =>
       async (statements: any, opts?: any) => {
         const { runSessionStatements } = await import('./db-session');
-        return runSessionStatements(opsDb as any, statements, opts, (q: string) => sql.raw(q));
+        return runSessionStatements(db, statements, opts, (q: string) => sql.raw(q));
       };
+    // THIS container's long-lived operator connection — for reads only (db:apply's
+    // fingerprint endpoints, db:reconcile's catalog read when it isn't also writing).
+    const sessionOverOpsDb = (sql: { raw: (q: string) => any }) => sessionOverDb(opsDb, sql);
+
+    // The disposable, fenced connection a mutating action leases for its own duration: see
+    // mutation-connection.ts. Never opsDb.
+    const openMutationConnection = async () =>
+      (await import('./mutation-connection')).openMutationConnection();
 
     // --- db:session — N statements, ONE connection, ONE transaction ---
     // The primitive that makes a multi-statement remote read describe ONE moment.
@@ -1016,6 +1033,7 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
             apiSourceLabel: 'DATABASE_URL',
             forceRlsCarveouts: options.forceRlsCarveouts,
             functionSchemas: options.functionSchemas,
+            appRoles: options.appRoles,
           },
         );
       } catch (err: any) {
@@ -1293,77 +1311,88 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
         return { error: 'this db:apply payload carries no descent verdict — the fast-forward rule cannot be waived by omission. Upgrade the everystack CLI (an older CLI omits it), or this is a client bug.' };
       }
 
-      const { sql } = await import('drizzle-orm');
-      const runner = async (query: string): Promise<any[]> => {
-        const result: any = await opsDb.execute(sql.raw(query));
-        return Array.isArray(result) ? result : result?.rows ?? [];
-      };
-      const transaction = async <T>(work: (transactionRunner: (query: string) => Promise<any[]>) => Promise<T>): Promise<T> =>
-        opsDb.transaction(async (tx: any) => work(async (query: string) => {
-          const result: any = await tx.execute(sql.raw(query));
-          return Array.isArray(result) ? result : result?.rows ?? [];
-        }));
-      // The fingerprint endpoints this apply gates on are multi-statement reads, so they
-      // run as ONE session on this container's operator connection. Server-side that was
-      // always one connection; saying so in the type is what stops a future caller from
-      // quietly reintroducing a per-statement read.
-      const session = sessionOverOpsDb(sql);
-
       const destructive = Number(plan.destructive) > 0;
       const snapStage = stage ?? ctx.environment ?? 'default';
       // How old a backup may be and still auto-qualify as the safety net (the fp match already proves
       // schema identity; this only bounds how much data a restore would roll back).
       const SNAPSHOT_FRESHNESS_MS = 60 * 60_000;
       let snapshotId: string | undefined;
+      let endLease: (() => Promise<void>) | undefined;
       try {
-        // checkDescent is REQUIRED by StageApplyOptions — no conditional spread can drop it. The
-        // verdict is guaranteed well-formed by the guard above; the hook enforces + records it here,
-        // in order, atomic with the lock. Authority/snapshot stay conditional (destructive-only, and
-        // the stage lane refuses destructive outright, so they never light up on this lane).
-        const applyOptions: StageApplyOptions = {
-          transaction,
-          actor: actor ?? null,
-          gitRef: gitRef ?? null,
-          dirty: dirty === true,
-          stateOnly: stateOnly === true,
-          checkDescent: async () => (descentVerdict.ok ? { ok: true as const } : { ok: false as const, reason: descentVerdict.reason ?? 'descent refused' }),
-          // The CLI's descent record (a honoured waiver, or a proven-drift origin) lands in the
-          // schema_log outcome; the witness query matches `applied%`, so the row stays a witness.
-          ...(descentAttested ? { descentNote: () => descentAttested } : {}),
-          ...(destructive && authorityVerdict
-            ? { verifyAuthority: async () => (authorityVerdict.ok ? { ok: true as const } : { ok: false as const, reason: authorityVerdict.reason ?? 'authority refused' }) }
-            : {}),
-          // The B3 safety gate: a destructive apply must be covered by a VERIFIED backup — the apply
-          // no longer takes its own. Resolve the ref (explicit id, else the stage's newest) and verify
-          // it SERVER-SIDE (never a CLI-attested boolean): succeeded, this stage, fresh, and
-          // fingerprint == plan.from. A miss is recorded in schema_log by executeApplyPlan.
-          ...(destructive
-            ? {
-                verifySnapshot: async ({ planFrom }: { planFrom: string }) => {
-                  const r = await resolveBackupDeps();
-                  if ('error' in r) return { ok: false as const, reason: `snapshot gate: ${r.error}` };
-                  const { fetchBackupManifest, latestBackupManifest } = await import('./backup-run');
-                  const { verifySnapshotRef } = await import('./backup');
-                  const manifest = snapshotRef
-                    ? await fetchBackupManifest(r.deps, snapshotRef)
-                    : await latestBackupManifest(r.deps, snapStage);
-                  const verdict = verifySnapshotRef({
-                    manifest, planFrom, targetStage: snapStage,
-                    now: new Date(), freshnessWindowMs: SNAPSHOT_FRESHNESS_MS,
-                  });
-                  if (!verdict.ok) return { ok: false as const, reason: verdict.reason };
-                  snapshotId = verdict.id;
-                  return { ok: true as const };
-                },
-              }
-            : {}),
-        };
-        const result = await executeApplyPlan(runner, session, plan, applyOptions);
-        // Echo the contract version the write ran under (SHOULD, legibility — the safety mechanism is
-        // the pre-transaction refusal above, not this field).
-        return { ...result, contractVersion: APPLY_CONTRACT_VERSION, ...(snapshotId ? { snapshotId } : {}) };
+        // db:apply always writes (a reviewed plan is only ever sent here to be executed), so
+        // the lease and every statement below — fingerprint reads included — run on ONE
+        // disposable connection, never the shared opsDb. See openMutationConnection. Inside the
+        // try: a resolution failure (no operator connection configured) must come back as a
+        // clean { error }, not an uncaught rejection. The lease import too: a server paired with
+        // an older @everystack/cli lacking it must refuse cleanly, same as db:reconcile.
+        const { withMutationLease } = await import('@everystack/cli/mutation-lease');
+        // Runner, transaction and session all ride the ONE fenced connection: the fingerprint
+        // endpoints this apply gates on are multi-statement reads, and they run on the same
+        // connection the DDL runs on, so the lease covers the whole thing. A backend that dies
+        // mid-apply is a named ConnectionLostError, never a reconnect onto an unleased backend.
+        const leased = await openMutationConnection();
+        endLease = leased.end;
+        const { runner, transaction, session } = leased;
+
+        // The universal mutation lease (mutation-lease.ts): one operator mutates a stage at a
+        // time. Acquired on the SAME leased connection the DDL below runs on, held for the
+        // whole write, released (or dropped with the connection) when it ends.
+        return await withMutationLease(
+          runner,
+          { verb: 'db:apply', actor: actor ?? 'ops-lambda' },
+          async () => {
+            // checkDescent is REQUIRED by StageApplyOptions — no conditional spread can drop it. The
+            // verdict is guaranteed well-formed by the guard above; the hook enforces + records it here,
+            // in order, atomic with the lock. Authority/snapshot stay conditional (destructive-only, and
+            // the stage lane refuses destructive outright, so they never light up on this lane).
+            const applyOptions: StageApplyOptions = {
+              transaction,
+              actor: actor ?? null,
+              gitRef: gitRef ?? null,
+              dirty: dirty === true,
+              stateOnly: stateOnly === true,
+              checkDescent: async () => (descentVerdict.ok ? { ok: true as const } : { ok: false as const, reason: descentVerdict.reason ?? 'descent refused' }),
+              // The CLI's descent record (a honoured waiver, or a proven-drift origin) lands in the
+              // schema_log outcome; the witness query matches `applied%`, so the row stays a witness.
+              ...(descentAttested ? { descentNote: () => descentAttested } : {}),
+              ...(destructive && authorityVerdict
+                ? { verifyAuthority: async () => (authorityVerdict.ok ? { ok: true as const } : { ok: false as const, reason: authorityVerdict.reason ?? 'authority refused' }) }
+                : {}),
+              // The B3 safety gate: a destructive apply must be covered by a VERIFIED backup — the apply
+              // no longer takes its own. Resolve the ref (explicit id, else the stage's newest) and verify
+              // it SERVER-SIDE (never a CLI-attested boolean): succeeded, this stage, fresh, and
+              // fingerprint == plan.from. A miss is recorded in schema_log by executeApplyPlan.
+              ...(destructive
+                ? {
+                    verifySnapshot: async ({ planFrom }: { planFrom: string }) => {
+                      const r = await resolveBackupDeps();
+                      if ('error' in r) return { ok: false as const, reason: `snapshot gate: ${r.error}` };
+                      const { fetchBackupManifest, latestBackupManifest } = await import('./backup-run');
+                      const { verifySnapshotRef } = await import('./backup');
+                      const manifest = snapshotRef
+                        ? await fetchBackupManifest(r.deps, snapshotRef)
+                        : await latestBackupManifest(r.deps, snapStage);
+                      const verdict = verifySnapshotRef({
+                        manifest, planFrom, targetStage: snapStage,
+                        now: new Date(), freshnessWindowMs: SNAPSHOT_FRESHNESS_MS,
+                      });
+                      if (!verdict.ok) return { ok: false as const, reason: verdict.reason };
+                      snapshotId = verdict.id;
+                      return { ok: true as const };
+                    },
+                  }
+                : {}),
+            };
+            const result = await executeApplyPlan(runner, session, plan, applyOptions);
+            // Echo the contract version the write ran under (SHOULD, legibility — the safety mechanism is
+            // the pre-transaction refusal above, not this field).
+            return { ...result, contractVersion: APPLY_CONTRACT_VERSION, ...(snapshotId ? { snapshotId } : {}) };
+          },
+        );
       } catch (err: any) {
         return { error: err?.message || String(err) };
+      } finally {
+        if (endLease) await endLease();
       }
     };
 
@@ -1386,18 +1415,34 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       // @everystack/cli/wire) — the same type the CLI builds this payload against, so the two
       // sides no longer agree by convention alone.
       const p = (payload ?? {}) as ReconcileWirePayload;
+      // Only the WRITE path (p.apply === true) needs the lease and the disposable connection:
+      // a plan-only call is a read, and reads never race a mutation. When mutating, the whole
+      // introspect → plan → apply — not just the final DDL — runs on the leased connection, so
+      // the plan it applies is never read on one session and written on another.
+      const mutating = p.apply === true;
+      let endLease: (() => Promise<void>) | undefined;
       try {
         const { executeReconcile } = await import('@everystack/cli/reconcile');
         const { sql } = await import('drizzle-orm');
-        const runner = async (query: string): Promise<any[]> => {
+        const { withMutationLease } = await import('@everystack/cli/mutation-lease');
+
+        // A write runs every statement on the fenced leased connection; a read stays on opsDb.
+        let runner = async (query: string): Promise<any[]> => {
           const result: any = await opsDb.execute(sql.raw(query));
           return Array.isArray(result) ? result : result?.rows ?? [];
         };
+        let session: FencedConnection['session'] = sessionOverOpsDb(sql);
+        if (mutating) {
+          const leased = await openMutationConnection();
+          endLease = leased.end;
+          runner = leased.runner;
+          session = leased.session;
+        }
         // No `as any` on this call any more: `p.declared` is DerivedDescriptor[], which IS the
         // CLI's SourceObject[] (one declaration, in @everystack/model/wire), so the reconcile
         // core's options type accepts it directly. The cast used to hide exactly the kind of
         // mismatch this whole contract exists to catch.
-        const run = await executeReconcile(runner, sessionOverOpsDb(sql), {
+        const runReconcile = () => executeReconcile(runner, session, {
           declared: p.declared,
           renamedTables: p.renamedTables,
           apply: p.apply,
@@ -1409,9 +1454,16 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
           actor: p.actor ?? null,
           gitRef: p.gitRef ?? null,
         });
+        // The universal mutation lease: one operator mutates a stage at a time. Acquired on the
+        // SAME leased connection the reconcile runs on, held for the whole call.
+        const run = mutating
+          ? await withMutationLease(runner, { verb: 'db:reconcile', actor: p.actor ?? 'ops-lambda' }, runReconcile)
+          : await runReconcile();
         return { plan: run.plan, applied: run.applied, statements: run.statements, refusal: run.refusal ?? null };
       } catch (err: any) {
         return { error: err?.message || String(err) };
+      } finally {
+        if (endLease) await endLease();
       }
     };
 

package/src/restore-witness.ts

@@ -0,0 +1,353 @@
+/**
+ * restore-witness — what a restore leaves in the restored database's own ledger, and the refusals
+ * the ops Lambda's db:restore dispatcher runs before anything is written.
+ *
+ * pg_restore runs with --no-owner --no-privileges --no-comments (the dump must land in any stage),
+ * so every restored object comes back with PostgreSQL's DEFAULT privileges. The live authz then
+ * matches no commit. The witness is a schema_log row naming the commit the RESTORED state descends
+ * from, so a later converge can descend from it.
+ *
+ * That commit is the BACKUP's origin (`originCommit` in its .meta.json, recorded by db:backup),
+ * never the target's own last deploy. A DR restore of an older backup, or a fork into another
+ * stage, lands a state the target's ledger never deployed — its anchor would name the wrong commit.
+ * A backup with no recorded origin is refused: there is nothing honest to write.
+ *
+ * The ledger survives the restore (the dump excludes the `everystack` schema), so the dispatcher
+ * writes the witness BEFORE the task starts; a restore that dies half-way still leaves it standing.
+ * On a fresh target (a first fork) the ledger does not exist yet, so the witness creates it from
+ * the CLI's own ledger DDL.
+ */
+
+import type { BackupAuthzManifest, BackupManifest } from './backup';
+
+/** A query over the stage's operator connection (raw SQL — the ops runner binds no parameters). */
+export type WitnessQuery = (sql: string) => Promise<any[]>;
+
+const lit = (v: string | null): string => (v === null ? 'NULL' : `'${v.replace(/'/g, "''")}'`);
+
+export const RESTORE_WITNESS_KIND = 'restore';
+export const RESTORED_OUTCOME = 'restored';
+
+/** Who the restore connection is — read before pg_restore runs. */
+export interface RestoreRole {
+  role: string;
+  superuser: boolean;
+  /** RDS's master is NOSUPERUSER but a member of rds_superuser. */
+  rdsSuperuser: boolean;
+}
+
+export const RESTORE_ROLE_SQL = `
+SELECT CURRENT_USER::text AS role,
+       b.rolsuper AS superuser,
+       EXISTS (
+         SELECT 1 FROM pg_auth_members m JOIN pg_roles g ON g.oid = m.roleid
+         WHERE m.member = b.oid AND g.rolname = 'rds_superuser'
+       ) AS rds_superuser
+FROM pg_roles b WHERE b.rolname = CURRENT_USER`.trim();
+
+const truthy = (v: unknown): boolean => v === true || v === 't' || v === 'true';
+
+/**
+ * The refusal for restoring as the master, or null for the operator.
+ *
+ * Every object pg_restore creates is owned by the connecting role. Restored by the master, the
+ * operator can neither replace them nor revoke the PUBLIC grants they come back with.
+ */
+export function restoreRoleRefusal(r: RestoreRole): string | null {
+  if (!r.superuser && !r.rdsSuperuser) return null;
+  return (
+    `refusing to restore as '${r.role}', the ${r.superuser ? 'superuser' : 'RDS master (rds_superuser member)'}: every restored ` +
+    `object would be owned by it, and the operator could not converge their grants afterwards. Run ` +
+    `\`everystack db:provision --stage <stage>\` so the restore runs as the operator, then restore again.`
+  );
+}
+
+export async function readRestoreRole(query: WitnessQuery): Promise<RestoreRole> {
+  const [r] = await query(RESTORE_ROLE_SQL);
+  return { role: String(r?.role ?? ''), superuser: truthy(r?.superuser), rdsSuperuser: truthy(r?.rds_superuser) };
+}
+
+export type OriginVerdict = { ok: true; origin: string } | { ok: false; reason: string };
+
+/** A full git commit id: SHA-1 (40 hex) or SHA-256 (64 hex), lowercase, nothing else. */
+export const COMMIT_SHA = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+
+/**
+ * The restore's origin commit, read from the backup's own meta. Pure.
+ *
+ * `expected` is the dump actually being restored: a meta that describes another dump is refused,
+ * so an origin can never be borrowed from a different backup.
+ */
+export function restoreOriginFromMeta(
+  meta: BackupManifest | null,
+  expected: { id: string; key: string },
+): OriginVerdict {
+  const fresh = `take a fresh db:backup of the source stage and restore that`;
+  const predates = `backup ${expected.id} predates origin recording (its meta has no originCommit), so the restore cannot name the commit it lands — ${fresh}.`;
+  // A local-venue backup (db:backup --database-url) writes no fingerprint and no origin; so did a
+  // stage backup from before fingerprints. Only a fingerprint proves a stage backup, so without one
+  // the refusal names both causes rather than guessing.
+  const localOrPredates =
+    `backup ${expected.id} has no originCommit in its meta, so the restore cannot name the commit it lands. Either it is a ` +
+    `local backup (db:backup --database-url), which carries no origin — restoring a local backup into a stage is closed ` +
+    `until local backups can record a verified origin — or it is a stage backup that predates origin recording — ${fresh}.`;
+  if (!meta) {
+    return { ok: false, reason: `backup ${expected.id} has no readable meta, so it predates origin recording or its .meta.json could not be read — ${fresh}.` };
+  }
+  if (meta.key !== expected.key) {
+    return { ok: false, reason: `the meta for backup ${expected.id} describes ${String(meta.key)}, not ${expected.key} — refusing to take a restore's origin from another dump.` };
+  }
+  if (meta.originCommit === undefined) return { ok: false, reason: meta.fingerprint ? predates : localOrPredates };
+  if (meta.originCommit === null) {
+    return {
+      ok: false,
+      reason: `no commit deployed the backed-up database (backup ${expected.id} recorded originCommit: null), so the restore has no origin to descend from — deploy the source with db:apply, then ${fresh}.`,
+    };
+  }
+  if (typeof meta.originCommit !== 'string' || meta.originCommit.length === 0) {
+    return { ok: false, reason: `backup ${expected.id} records an unreadable originCommit (${JSON.stringify(meta.originCommit)}) — ${fresh}.` };
+  }
+  if (!COMMIT_SHA.test(meta.originCommit)) {
+    return { ok: false, reason: `backup ${expected.id} records originCommit ${JSON.stringify(meta.originCommit)}, which is not a commit sha (40 or 64 lowercase hex) — ${fresh}.` };
+  }
+  return { ok: true, origin: meta.originCommit };
+}
+
+/** How the fork meta is fetched: never following a redirect, and bounded in time. */
+export interface MetaFetchInit {
+  redirect: 'error';
+  signal: AbortSignal;
+}
+
+/** The part of a fetch Response the fork meta read uses. `body` is read with a size cap. */
+export interface MetaResponse {
+  ok: boolean;
+  status: number;
+  body?: ReadableStream<Uint8Array> | null;
+  text?: () => Promise<string>;
+}
+
+/** The minimal fetch the fork meta read needs (injectable for tests; the global fetch fits it). */
+export type MetaFetch = (url: string, init: MetaFetchInit) => Promise<MetaResponse>;
+
+/** A backup meta is a few KB even with its authz manifest. Anything past this is not one. */
+export const META_MAX_BYTES = 1024 * 1024;
+const META_TIMEOUT_MS = 10_000;
+
+/** The body as text, or null when it exceeds `max` bytes (read no further than that). */
+async function readCapped(res: MetaResponse, max: number): Promise<string | null> {
+  if (res.body && typeof res.body.getReader === 'function') {
+    const reader = res.body.getReader();
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > max) {
+        await reader.cancel().catch(() => {});
+        return null;
+      }
+      chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+  }
+  if (!res.text) throw new Error('the response has no body');
+  const text = await res.text();
+  return Buffer.byteLength(text, 'utf8') > max ? null : text;
+}
+
+const errText = (err: unknown): string => {
+  if (!(err instanceof Error)) return String(err);
+  const cause = (err as { cause?: unknown }).cause;
+  return cause instanceof Error ? `${err.message} (${cause.message})` : err.message;
+};
+
+export type ForkMetaVerdict =
+  | { ok: true; meta: BackupManifest; id: string; key: string }
+  | { ok: false; reason: string };
+
+/** The S3 object key a presigned URL points at (virtual-hosted or path-style), or null. */
+function keyOfPresigned(url: string, suffix: RegExp): string | null {
+  let path: string;
+  try {
+    path = decodeURIComponent(new URL(url).pathname);
+  } catch {
+    return null;
+  }
+  const m = path.match(new RegExp(`(backups/[^/]+/[^/]+${suffix.source})$`));
+  return m ? m[1] : null;
+}
+
+/**
+ * A fork's source meta, read by the dispatcher itself from the presigned `metaUrl` db:fork sends
+ * beside the dump `url`. Never taken from the payload: a gitRef in the payload is ignored. Refuses
+ * when the metaUrl is missing, is not the dump's own `.meta.json`, cannot be fetched, or is not JSON.
+ * Whether the meta describes this dump, and whether it records an origin, is restoreOriginFromMeta's.
+ */
+export async function readForkMeta(
+  fetchFn: MetaFetch,
+  url: string,
+  metaUrl: string | undefined,
+  opts: { timeoutMs?: number } = {},
+): Promise<ForkMetaVerdict> {
+  const key = keyOfPresigned(url, /\.dump\.gz/);
+  if (!key) return { ok: false, reason: `db:restore {url} does not name a backup dump (backups/<stage>/<name>.dump.gz) — mint it with db:fork.` };
+  const id = key.replace(/^backups\//, '').replace(/\.dump\.gz$/, '');
+  if (!metaUrl) {
+    return { ok: false, reason: `db:restore {url} requires {metaUrl} — the presigned .meta.json of backup ${id}, which records its origin commit. Upgrade @everystack/cli and re-run db:fork.` };
+  }
+  // The Lambda fetches metaUrl itself, so it must be the presigned object beside the dump: https,
+  // on the dump's own host, never redirected, bounded in time and size.
+  const parsed = (u: string): URL | null => { try { return new URL(u); } catch { return null; } };
+  const dump = parsed(url);
+  const metaAt = parsed(metaUrl);
+  if (dump?.protocol !== 'https:') return { ok: false, reason: `db:restore {url} must be https (backup ${id}) — a presigned S3 URL always is.` };
+  if (metaAt?.protocol !== 'https:') return { ok: false, reason: `db:restore {metaUrl} must be https (backup ${id}) — a presigned S3 URL always is.` };
+  if (metaAt.host !== dump.host) {
+    return { ok: false, reason: `db:restore {metaUrl} (${metaAt.host}) is not on the same host as the dump {url} (${dump.host}) — a fork's meta must sit beside its dump.` };
+  }
+  if (keyOfPresigned(metaUrl, /\.meta\.json/) !== key.replace(/\.dump\.gz$/, '.meta.json')) {
+    return { ok: false, reason: `db:restore {metaUrl} is not the .meta.json of backup ${id} — a fork's meta must be the dump's own.` };
+  }
+  const timeoutMs = opts.timeoutMs ?? META_TIMEOUT_MS;
+  const signal = AbortSignal.timeout(timeoutMs);
+  let text: string | null;
+  try {
+    const res = await fetchFn(metaUrl, { redirect: 'error', signal });
+    if (!res.ok) return { ok: false, reason: `fetching the meta of backup ${id} failed: HTTP ${res.status} — presigned URLs expire in an hour; re-run db:fork.` };
+    text = await readCapped(res, META_MAX_BYTES);
+  } catch (err: unknown) {
+    if (signal.aborted) return { ok: false, reason: `fetching the meta of backup ${id} timed out after ${timeoutMs / 1000}s — re-run db:fork.` };
+    return { ok: false, reason: `fetching the meta of backup ${id} failed: ${errText(err)}` };
+  }
+  if (text === null) {
+    return { ok: false, reason: `the meta of backup ${id} is larger than 1 MiB — that is not a backup manifest; refusing to restore.` };
+  }
+  let meta: unknown;
+  try {
+    meta = JSON.parse(text);
+  } catch {
+    return { ok: false, reason: `the meta of backup ${id} is not valid JSON — refusing to restore without its recorded origin.` };
+  }
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta)) {
+    return { ok: false, reason: `the meta of backup ${id} is not a backup manifest — refusing to restore without its recorded origin.` };
+  }
+  return { ok: true, meta: meta as BackupManifest, id, key };
+}
+
+const PUBLIC = /^public$/i;
+
+const isRecord = (o: unknown): o is Record<string, unknown> => !!o && typeof o === 'object' && !Array.isArray(o);
+
+/**
+ * Every role the backup's authz manifest names: grantees (tables, columns, policies, derived
+ * objects, schema USAGE) and declared owners, minus PUBLIC. `null` when there is no manifest —
+ * "unchecked", never "no roles". The manifest is opaque on this side of the mirror, so every
+ * section is read defensively.
+ */
+export function declaredRoles(manifest: BackupAuthzManifest | null | undefined): string[] | null {
+  if (!isRecord(manifest)) return null;
+  const roles = new Set<string>();
+  const add = (r: unknown): void => {
+    if (typeof r === 'string' && r.length > 0 && !PUBLIC.test(r)) roles.add(r);
+  };
+  // A section that should be a { role: … } map but is an array would yield its indexes ('0', '1').
+  const keys = (o: unknown): string[] => (isRecord(o) ? Object.keys(o) : []);
+  const list = (a: unknown): unknown[] => (Array.isArray(a) ? a : []);
+
+  for (const t of list(manifest.tables) as any[]) {
+    keys(t?.grants).forEach(add);
+    keys(t?.columnGrants).forEach(add);
+    for (const p of list(t?.policies) as any[]) list(p?.roles).forEach(add);
+  }
+  const derived = manifest.derived as any;
+  for (const o of list(derived?.objects) as any[]) keys(o?.grants).forEach(add);
+  const usage: unknown = derived?.schemaUsage;
+  for (const grantees of isRecord(usage) ? Object.values(usage) : []) list(grantees).forEach(add);
+  const owners = manifest.owners as any;
+  for (const o of list(owners?.declaredOwners) as any[]) add(o?.owner);
+  // declaredObjects[].currentOwner is what the live database said at dump time, not a declaration.
+  for (const o of list(owners?.declaredObjects) as any[]) add(o?.declaredOwner);
+  return [...roles].sort();
+}
+
+/** The roles in `roles` that pg_roles does not have, sorted. */
+export async function readMissingRoles(query: WitnessQuery, roles: string[]): Promise<string[]> {
+  if (roles.length === 0) return [];
+  const rows = await query(
+    `SELECT r AS role FROM unnest(ARRAY[${roles.map(lit).join(', ')}]::text[]) AS r ` +
+      `WHERE NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = r) ORDER BY r`,
+  );
+  return rows.map((row) => String(row.role));
+}
+
+/**
+ * The refusal for role names PostgreSQL cannot hold, or null. A NUL byte cannot appear in any
+ * PostgreSQL string, so asking pg_roles about one would throw instead of refusing.
+ */
+export function unnameableRolesRefusal(roles: string[], ctx: { backupId: string }): string | null {
+  const bad = roles.filter((r) => r.includes('\u0000'));
+  if (bad.length === 0) return null;
+  return (
+    `refusing to restore backup ${ctx.backupId}: its authz manifest names role(s) containing a NUL byte ` +
+    `(${bad.map((r) => JSON.stringify(r)).join(', ')}), which no PostgreSQL role can have — the manifest is malformed.`
+  );
+}
+
+/** The refusal for a target missing roles the backup declares grants to, or null. */
+export function missingRolesRefusal(missing: string[], ctx: { stage: string; backupId: string }): string | null {
+  if (missing.length === 0) return null;
+  return (
+    `refusing to restore backup ${ctx.backupId}: it declares grants to role(s) this database does not have (${missing.join(', ')}). ` +
+    `Restored objects would come back without them and the grants could not converge. Run ` +
+    `\`everystack db:provision --stage ${ctx.stage}\` to create the role chain, then restore again.`
+  );
+}
+
+/** Create the ledger if absent, from the CLI's own DDL (one source, idempotent). */
+export async function ensureLedger(query: WitnessQuery): Promise<void> {
+  const { ENSURE_RECONCILER_SQL } = await import('@everystack/cli/apply');
+  for (const ddl of ENSURE_RECONCILER_SQL) await query(ddl);
+}
+
+export interface RestoreWitnessInput {
+  /** The S3 intent key — stored as the row's plan_ref so the two records name each other. */
+  intentKey: string;
+  /** What was restored, for the reader: a backup id, or "<id> (fork)". */
+  source: string;
+  actor: string | null;
+  /** The backup's origin commit (restoreOriginFromMeta). Required: there is no fallback. */
+  origin: string;
+}
+
+export interface RestoreWitness {
+  witnessId: string;
+  origin: string;
+}
+
+export async function writeRestoreWitness(query: WitnessQuery, input: RestoreWitnessInput): Promise<RestoreWitness> {
+  if (typeof input.origin !== 'string' || input.origin.length === 0) {
+    throw new Error('writeRestoreWitness requires the backup\'s origin commit');
+  }
+  await ensureLedger(query);
+  const note = `-- restore of ${input.source} (intent ${input.intentKey}): objects come back with default privileges; converge before the next apply`;
+  const [inserted] = await query(
+    `INSERT INTO everystack.schema_log (kind, actor, git_ref, plan_ref, sql, outcome) VALUES (` +
+      [RESTORE_WITNESS_KIND, input.actor, input.origin, input.intentKey, note, RESTORED_OUTCOME].map(lit).join(', ') +
+      `) RETURNING id`,
+  );
+  return { witnessId: String(inserted.id), origin: input.origin };
+}
+
+/**
+ * Void a witness whose restore never started (RunTask failed). A `failed…` outcome is not a
+ * witness to anything: a restore that never ran must not hold the stage.
+ */
+export async function voidRestoreWitness(query: WitnessQuery, witnessId: string, reason: string): Promise<void> {
+  if (!/^\d+$/.test(witnessId)) throw new Error(`not a schema_log id: ${witnessId}`);
+  await query(
+    `UPDATE everystack.schema_log SET outcome = ${lit(`failed: restore did not start — ${reason}`.slice(0, 500))} ` +
+      `WHERE id = ${witnessId} AND kind = '${RESTORE_WITNESS_KIND}'`,
+  );
+}