@everystack/cli 0.4.68 → 0.4.70

package/src/cli/index.ts

@@ -372,7 +372,7 @@ Usage:
   everystack db:sync           [--database-url <url>] [--models <barrel>] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against the declared descriptors, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
   everystack db:diff           --from-models <barrel> [--to-models db/models/index.ts] [--allow-drops] [--check] [--json]  The state edge between two declared states, NO database: the SQL db:generate would produce, computed purely — CI plan previews (--check exits 1 on a non-empty edge) and computed rollbacks (swap the flags)
   everystack db:plan           [--stage <name> [--direct] | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only; plans are ephemeral, never committed. VENUES: --stage runs via the ops Lambda, which reads TWICE and refuses on disagreement — agreement there is a DETECTOR, not a verification. --stage --direct resolves the stage's operator connection from its IAM-gated ops Lambda, holds it in memory only, and reads ONCE over one session: the lane for a fingerprint you intend to trust, with the credential never on argv. --database-url is the local-dev venue (same read guarantee, but against a deployed stage it puts a privileged DSN on the command line)
-  everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--snapshot-ref <ref>] [--force-descent <snapshot-ref> --confirm]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule, else refuse — "rebase first"), and for DESTRUCTIVE plans require --confirm always + an attested --snapshot-ref + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there
+  everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--snapshot-ref <ref>] [--attest-lineage-lost <sha>]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule, else refuse — a descent refusal is escaped git-natively: git revert the declaring commit → db:generate → db:plan → db:apply, so the rollback is a recorded forward move; --attest-lineage-lost <sha> waives the rule ONLY for a declaring commit proven gone from every ref), and for DESTRUCTIVE plans require --confirm always + a confirmed rollback point + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there
   everystack db:build          --database-url <url> [--models <barrel>]  Build a database FROM the models and KEEP it — the fresh-database bootstrap a deleted migration folder is replaced BY. Runs the same compose db:check proves buildability with (extensions -> schemas -> contract roles -> declared functions -> state -> derived layer), against a real target, then reports MATCH. Venue is EXPLICIT: --database-url only, never the ambient environment, because this writes a whole schema. REFUSES a database that already holds objects — evolving an existing one is db:sync (dev) or db:plan -> db:apply (a stage). Contract roles are created NOLOGIN if absent, and roles are cluster-level
   everystack db:check          [--models <barrel>] [--schema-out <file.ts>] [--database-url <url>] [--json]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, descriptors compile), every exposed RLS-enabled table must declare a read path (no force-RLS-with-no-read landmine that goes dark on the superuser drop), and generated artifacts must MATCH regeneration byte-for-byte; with a scratch PostgreSQL it builds the state from scratch on an ephemeral database (created + dropped) and requires fingerprint MATCH. Exit 1 on any failure; never touches a real target
   everystack db:approvers      --stage <name> [--set "cto,arn:..."] [--remove]  Declare who can DESTROY: the stage's destructive-approver set (SSM parameter, admin-writable). Destructive db:apply runs are then identity-verified (STS) against it; --set '' disables destructive applies; --remove returns the stage to ceremony-only

package/src/cli/local-rollback.ts

@@ -0,0 +1,146 @@
+/**
+ * confirmLocalDump — the bare `--database-url` rollback point for a destructive db:apply.
+ *
+ * Ratified 2026-08-26 (REVERSAL 1) and Fable-adjudicated 2026-08-26 (Option A): over a bare
+ * --database-url the tool takes its OWN `pg_dump -Fc` to a local file and VERIFIES it with
+ * `pg_restore --list` before the first destructive statement. The dump is the rollback point; the
+ * operator restores it by hand with standard tooling if the apply goes wrong
+ * (`pg_restore --clean --if-exists -d <url> <file>`) — there is no first-class restore verb here on
+ * purpose, because a bare --database-url is the local-dev venue where the operator owns the DB.
+ *
+ * FAIL CLOSED — a local .dump becomes theater two ways: a truncated file and a missing binary. The
+ * verdict is a total, pure function (`interpretLocalDumpVerdict`) so every failure mode refuses
+ * WITHOUT a database. `pg_restore --list` exiting 0 is not enough on its own: an empty or truncated
+ * archive can still exit 0 with no table of contents, so a non-empty TOC is required too. (The
+ * "is this the right database" worry that dogs an attested --snapshot-ref does not arise here: the
+ * dump is taken from the SAME url the apply will run against.)
+ *
+ * The dump carries no fingerprint stamp of its own — like a physical RDS snapshot it is taken fresh
+ * and the caller's concurrency lock (live == plan.from, re-read after this returns) is its coverage.
+ */
+
+import { spawn } from 'node:child_process';
+import { stat } from 'node:fs/promises';
+import { pgEnvFromUrl, pgKeepaliveConninfo } from './commands/db';
+
+/**
+ * pg_dump args for a rollback dump to `file`: a custom-format (-Fc) archive of the app schemas.
+ * Excludes the everystack ops schema — restoring it would rewind the target's own audit history, and
+ * pg_restore --clean would fail dropping it (its ledger tables depend on the schema). Ownership- and
+ * privilege-neutral so the restore lands on a dev DB the operator owns without role juggling.
+ */
+export function pgDumpToFileArgs(file: string): string[] {
+  return ['-d', pgKeepaliveConninfo(), '-Fc', '--no-owner', '--no-privileges', '--exclude-schema=everystack', '-f', file];
+}
+
+export interface LocalDumpVerdictInput {
+  /** Did pg_dump exit 0? (A missing pg_dump binary is a spawn error ⇒ false.) */
+  dumpOk: boolean;
+  dumpError?: string;
+  /** Size of the written archive. Zero means pg_dump produced nothing usable. */
+  fileBytes: number;
+  /** Did `pg_restore --list` read the archive? (A missing pg_restore, or a truncated archive ⇒ false.) */
+  listOk: boolean;
+  listError?: string;
+  /** Non-comment entries in the archive's table of contents. Zero ⇒ an empty archive that lists clean. */
+  tocEntries: number;
+}
+
+/**
+ * The rollback point is durable ONLY when every stage of the take+verify succeeded. Any failure is a
+ * REFUSAL the caller must obey — no destructive statement runs. Ordered so the operator reads the
+ * FIRST thing that broke.
+ */
+export function interpretLocalDumpVerdict(i: LocalDumpVerdictInput): { ok: true } | { ok: false; reason: string } {
+  const takeOne =
+    'A destructive apply over a bare --database-url needs a rollback point it can prove is restorable. '
+    + 'Fix the tool (pg_dump/pg_restore must be on PATH and no older major than the server), or attest a '
+    + 'rollback point you took yourself with --snapshot-ref <id>, or accept the risk explicitly with --snapshot none.';
+  if (!i.dumpOk) {
+    return { ok: false, reason: `pg_dump could not take the local rollback point: ${i.dumpError ?? 'unknown error'}. ${takeOne}` };
+  }
+  if (!(i.fileBytes > 0)) {
+    return { ok: false, reason: `the local rollback dump is empty (0 bytes) — pg_dump produced nothing usable. ${takeOne}` };
+  }
+  if (!i.listOk) {
+    return { ok: false, reason: `pg_restore --list could not read the rollback dump (it may be truncated, or pg_restore is missing): ${i.listError ?? 'unknown error'}. ${takeOne}` };
+  }
+  if (!(i.tocEntries > 0)) {
+    return { ok: false, reason: `the rollback dump lists no objects — an empty archive is not a rollback point. ${takeOne}` };
+  }
+  return { ok: true };
+}
+
+/** Count table-of-contents ENTRIES in `pg_restore --list` output: non-empty lines that are not the ';'-prefixed header/comment lines. */
+export function countTocEntries(listOutput: string): number {
+  return listOutput
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0 && !l.startsWith(';')).length;
+}
+
+async function runToExit(
+  bin: string,
+  args: string[],
+  env: NodeJS.ProcessEnv,
+): Promise<{ ok: boolean; error?: string; stdout: string }> {
+  return new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let child;
+    try {
+      child = spawn(bin, args, { env, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err: any) {
+      resolve({ ok: false, error: err?.message ?? String(err), stdout: '' });
+      return;
+    }
+    child.stdout?.on('data', (d) => { stdout += d.toString(); });
+    child.stderr?.on('data', (d) => { stderr += d.toString(); });
+    // ENOENT (binary not on PATH) arrives as an 'error' event, not a non-zero exit.
+    child.on('error', (err: any) => resolve({ ok: false, error: err?.message ?? String(err), stdout }));
+    child.on('close', (code) =>
+      resolve(code === 0 ? { ok: true, stdout } : { ok: false, error: `exited ${code}: ${stderr.trim()}`, stdout }));
+  });
+}
+
+export interface LocalDumpDeps {
+  /** The bare --database-url the apply targets — the same DB the rollback dump captures. */
+  url: string;
+  /** Absolute path to write the .dump to. */
+  file: string;
+  /** Binaries, injectable so the fail-closed paths (missing binary) are testable without unstubbing PATH. */
+  pgDumpBin?: string;
+  pgRestoreBin?: string;
+  /** Seam: report the written file's size. Defaults to fs.stat. */
+  fileBytes?: (file: string) => Promise<number>;
+}
+
+/**
+ * Take the local rollback dump and verify it, returning the file path as the rollback ref on success
+ * or a refusal on any failure. Never throws into the caller — every failure is a verdict.
+ */
+export async function confirmLocalDump(
+  deps: LocalDumpDeps,
+): Promise<{ ok: true; ref: string } | { ok: false; reason: string }> {
+  const env = { ...process.env, ...pgEnvFromUrl(deps.url) };
+  const dumpBin = deps.pgDumpBin ?? 'pg_dump';
+  const restoreBin = deps.pgRestoreBin ?? 'pg_restore';
+
+  const dump = await runToExit(dumpBin, pgDumpToFileArgs(deps.file), env);
+  const fileBytes = dump.ok
+    ? await (deps.fileBytes ?? (async (f: string) => (await stat(f)).size.valueOf()))(deps.file).catch(() => 0)
+    : 0;
+  const list = dump.ok && fileBytes > 0
+    ? await runToExit(restoreBin, ['--list', deps.file], env)
+    : { ok: false as const, error: 'skipped (pg_dump did not produce a usable archive)', stdout: '' };
+
+  const verdict = interpretLocalDumpVerdict({
+    dumpOk: dump.ok,
+    ...(dump.error ? { dumpError: dump.error } : {}),
+    fileBytes,
+    listOk: list.ok,
+    ...(list.error ? { listError: list.error } : {}),
+    tocEntries: list.ok ? countTocEntries(list.stdout) : 0,
+  });
+  return verdict.ok ? { ok: true, ref: deps.file } : { ok: false, reason: verdict.reason };
+}

package/src/cli/prompt.ts

@@ -0,0 +1,18 @@
+/**
+ * promptYesNo — one line of interactive consent, default NO. Used where the tool is about to do
+ * something the operator did not explicitly ask for on the command line (db:apply's lane escalation).
+ * Callers MUST gate on `process.stdin.isTTY` first: a non-interactive session has no one to answer, so
+ * the safe path there is to refuse and name the explicit flag, not to call this.
+ */
+
+import * as readline from 'node:readline';
+
+export async function promptYesNo(question: string): Promise<boolean> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer: string = await new Promise((resolve) => rl.question(question, resolve));
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}

package/src/cli/rollback-point.ts

@@ -0,0 +1,141 @@
+/**
+ * confirmRollbackPoint — take (or account for) a durable rollback point before a destructive
+ * database operation, and do not return success until it EXISTS.
+ *
+ * This is the ceremony db:swap proved and db:apply now shares (apply-legibility Phase 2, Ty
+ * ratified 2026-08-26). The property both verbs need is identical: no destructive statement
+ * runs before a confirmed-durable rollback point. The old apply design took its OWN async
+ * snapshot and did not wait — destroyed data before the snapshot existed — and was removed
+ * (26ea947b) for exactly that. The fix is db:swap's pattern: decide the mode, take it, and
+ * WAIT for durability. This module is that pattern, verb-neutral, with its executors injected
+ * so the wait is provable without AWS.
+ *
+ * It confirms the point exists; it does NOT re-verify the live fingerprint after the wait —
+ * that is the CALLER's concurrency lock (the snapshot wait is a window, and the apply's own
+ * `live == plan.from` re-check after this returns is what closes it). Keeping the two separate
+ * is deliberate: this module answers "is there a rollback point", the lock answers "is the
+ * database still where the plan started".
+ */
+
+import type { SnapshotDecision } from './swap-snapshot';
+
+/** A confirmed, durable rollback point. */
+export interface RollbackPoint {
+  mode: 'physical' | 'logical' | 'attested' | 'local' | 'none';
+  /** The snapshot/backup id, the attested ref, or the local dump's file path. Absent for `none`. */
+  ref?: string;
+  /** A logical backup stamps the live fingerprint at dump time — the caller checks it covers plan.from. */
+  stampedFingerprint?: string;
+}
+
+/**
+ * The executors, injected. Each wraps an already-tested primitive:
+ *  - `confirmPhysical` wraps `confirmPhysicalSnapshot` (takes an RDS snapshot, waits for
+ *    'available', throws on failure/timeout naming the id).
+ *  - `confirmLogical` wraps `runStageBackup` + `interpretBackupPoll` (dispatches db:backup and
+ *    WAITS for the task to stop, verifying the artifact).
+ */
+export interface ConfirmRollbackDeps {
+  confirmPhysical: (instanceId: string) => Promise<{ id: string }>;
+  confirmLogical: () => Promise<
+    | { ok: true; id: string; stampedFingerprint?: string; warning?: string }
+    | { ok: false; reason: string }
+  >;
+  /**
+   * Optional: fingerprint-verify an ATTESTED `--snapshot-ref` before it counts as the rollback point
+   * ("resolve-else-take" — reuse an existing backup only when it stamps plan.from). db:apply injects
+   * this to resolve the ref's backup manifest and run `verifySnapshotRef`; on success it returns the
+   * stamped fingerprint so the post-lock re-check ties the backup to live-at-lock too. When ABSENT
+   * (db:swap, whose attested ref may be a stampless physical RDS snapshot) an attested ref stays
+   * operator-trusted and the concurrency lock is its coverage.
+   */
+  verifyAttested?: (
+    ref: string,
+  ) => Promise<{ ok: true; stampedFingerprint?: string } | { ok: false; reason: string }>;
+  /**
+   * Optional: take our OWN local `pg_dump -Fc` and verify it (bare --database-url, db:apply only).
+   * Present only where `decideSnapshotMode` can return mode 'local' (db:apply passes localDump:true),
+   * so its absence when a 'local' decision arrives is a wiring bug and refuses rather than proceeding.
+   */
+  confirmLocal?: () => Promise<{ ok: true; ref: string } | { ok: false; reason: string }>;
+  log: (msg: string) => void;
+  warn: (msg: string) => void;
+}
+
+/**
+ * Produce a confirmed rollback point from a non-refusing SnapshotDecision, or return a refusal
+ * whose meaning is "there is no usable rollback point, so the caller must NOT proceed". Every
+ * branch either confirms durability or refuses; nothing returns a point that is merely in
+ * flight — that conflation is the defect this whole module exists to remove.
+ */
+export async function confirmRollbackPoint(
+  decision: Exclude<SnapshotDecision, { mode: 'refuse' }>,
+  deps: ConfirmRollbackDeps,
+): Promise<{ ok: true; point: RollbackPoint } | { ok: false; reason: string }> {
+  switch (decision.mode) {
+    case 'attested': {
+      // An attested ref is a CLAIM until it is verified. Where a verifier is injected (db:apply), the
+      // claim must prove out — the backup exists, covers this stage, is fresh, and stamps plan.from —
+      // before it counts. A failure is a REFUSAL, not a fallback to trusting the operator's word: the
+      // escape is a fresh backup or a re-plan, never "proceed over an unverified snapshot".
+      if (deps.verifyAttested) {
+        const verified = await deps.verifyAttested(decision.ref);
+        if (!verified.ok) return { ok: false, reason: verified.reason };
+        deps.log(`rollback point: ${decision.ref} (attested via --snapshot-ref, fingerprint verified — no new snapshot taken).`);
+        return {
+          ok: true,
+          point: {
+            mode: 'attested',
+            ref: decision.ref,
+            ...(verified.stampedFingerprint ? { stampedFingerprint: verified.stampedFingerprint } : {}),
+          },
+        };
+      }
+      deps.log(`rollback point: ${decision.ref} (attested via --snapshot-ref — no new snapshot taken).`);
+      return { ok: true, point: { mode: 'attested', ref: decision.ref } };
+    }
+
+    case 'none':
+      deps.warn(
+        'NO snapshot (--snapshot none) — there is no rollback point. If this operation lands bad ' +
+        'data it cannot be undone from a snapshot.',
+      );
+      return { ok: true, point: { mode: 'none' } };
+
+    case 'physical': {
+      deps.log(`Taking a physical RDS snapshot of ${decision.instanceId} and waiting for it to become available...`);
+      try {
+        const { id } = await deps.confirmPhysical(decision.instanceId);
+        deps.log(`rollback point CONFIRMED: RDS snapshot ${id} is available.`);
+        return { ok: true, point: { mode: 'physical', ref: id } };
+      } catch (err: any) {
+        return { ok: false, reason: err?.message ?? String(err) };
+      }
+    }
+
+    case 'logical': {
+      deps.log('Taking a logical backup (db:backup) and waiting for the dump to finish...');
+      const backup = await deps.confirmLogical();
+      if (!backup.ok) return { ok: false, reason: backup.reason };
+      if (backup.warning) deps.warn(backup.warning);
+      deps.log(`rollback point CONFIRMED: backup ${backup.id} complete.`);
+      return {
+        ok: true,
+        point: { mode: 'logical', ref: backup.id, ...(backup.stampedFingerprint ? { stampedFingerprint: backup.stampedFingerprint } : {}) },
+      };
+    }
+
+    case 'local': {
+      if (!deps.confirmLocal) {
+        // A 'local' decision with no executor to run it is a wiring bug, not a rollback point. Refuse
+        // — the whole module exists so "no executor" never reads as "point on record".
+        return { ok: false, reason: 'a local dump rollback point was chosen but no executor was wired to take it (internal error).' };
+      }
+      deps.log('Taking a local pg_dump rollback point and verifying it (pg_restore --list)...');
+      const local = await deps.confirmLocal();
+      if (!local.ok) return { ok: false, reason: local.reason };
+      deps.log(`rollback point CONFIRMED: local dump ${local.ref} (restore with: pg_restore --clean --if-exists -d <url> ${local.ref}).`);
+      return { ok: true, point: { mode: 'local', ref: local.ref } };
+    }
+  }
+}

package/src/cli/schema-diff.ts

@@ -63,7 +63,7 @@ export type SchemaChange =
   | { kind: 'setIdentity'; table: string; column: string; identity: 'always' | 'byDefault' | null; from: 'always' | 'byDefault' | null }
   /** A type change → real `ALTER COLUMN ... TYPE`. `risk` decides USING + a data-loss warning. */
   | { kind: 'alterType'; table: string; column: string; from: string; to: string; risk: TypeChangeRisk }
-  | { kind: 'addConstraint'; table: string; constraint: ConstraintSpec }
+  | { kind: 'addConstraint'; table: string; constraint: ConstraintSpec; note?: string }
   | { kind: 'dropConstraint'; table: string; name: string }
   | { kind: 'addPrimaryKey'; table: string; columns: string[] }
   /** A PK change other than first-time add — a notice (the drop needs its constraint name). */
@@ -97,7 +97,7 @@ export type SchemaChange =
   /** An enum value the DB has but the Model dropped/renamed — Postgres can't drop one in place (a notice). */
   | { kind: 'enumValuesChanged'; name: string; from: string[]; to: string[] }
   /** A standalone index to create → `CREATE [UNIQUE] INDEX … [USING …] (…) [INCLUDE …] [WHERE …]`. */
-  | { kind: 'createIndex'; table: string; name: string; columns: string[]; unique: boolean; where?: string; using?: string; include?: string[] }
+  | { kind: 'createIndex'; table: string; name: string; columns: string[]; unique: boolean; where?: string; using?: string; include?: string[]; note?: string }
   /** A standalone index present in the DB but no longer declared → `DROP INDEX` (a removal — gated). */
   | { kind: 'dropIndex'; table: string; name: string }
   /** A content-identical index the model names differently → `ALTER INDEX … RENAME TO` (B3). */
@@ -339,6 +339,34 @@ export function normalizeCheck(expr: string): string {
   return s.replace(/\s+/g, ' ');
 }
 
+/**
+ * Strip EVERY parenthesis and collapse whitespace. DIAGNOSTIC-ONLY — never an identity or
+ * matcher input. Blind paren removal is UNSAFE for identity: it crosses operator precedence,
+ * so `(a OR b) AND c` and `a OR (b AND c)` collapse to the same text (a false match, the one
+ * disaster the matcher must avoid). It is safe HERE because it only recognizes that a diff is
+ * paren-only, to explain the churn — a wrong guess at worst suggests adopting the live text,
+ * which always converges. Quote-naive for the same reason (see docs; adjudicated 2026-08-24).
+ */
+export function stripAllParens(expr: string): string {
+  return expr.replace(/[()]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * When a predicate diff is PAREN-ONLY, the churn is not a real change — Postgres stores
+ * predicates fully parenthesized while the model author writes minimal parens. The fix is to
+ * declare the live form; this note hands the operator the exact text to paste. `kind` is
+ * "index"/"check", `name` the declared object, `liveName` the live object, `liveExpr` the
+ * predicate to adopt.
+ */
+function parenOnlyNote(kind: string, name: string, liveName: string, liveExpr: string): string {
+  // Hedged deliberately. The paren-blind match cannot tell redundant parens from a real
+  // PRECEDENCE edit — `a OR (b AND c)` and `(a OR b) AND c` strip to the same text. So the
+  // note must NOT assert "this is not a change": if the operator DID intend a logic change,
+  // adopting the live form would silently revert it. The "if you did not intend" clause is
+  // true in both cases and points the common (redundant-paren) case at the converging fix.
+  return `-- NOTE: ${kind} "${name}" differs from the live ${kind} "${liveName}" by parenthesization. If you did NOT intend a change to the predicate's logic, this is churn — Postgres stores predicates fully parenthesized, so declare the live form to converge:  ${liveExpr}`;
+}
+
 // ---------------------------------------------------------------------------
 // Diff.
 // ---------------------------------------------------------------------------
@@ -532,13 +560,19 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
   ];
 }
 
-/** A `createIndex` change from an index spec (the new-table path and the per-table diff share it). */
-function createIndexChange(table: string, ix: IndexSchema): SchemaChange {
+/** A `createIndex` change from an index spec (the new-table path and the per-table diff share it).
+ *  `parenTwin` is a live index that matches this one on everything but parenthesization — when
+ *  present, the create carries an advisory note pointing at the live form to adopt. */
+function createIndexChange(table: string, ix: IndexSchema, parenTwin?: IndexSchema): SchemaChange {
+  const note = parenTwin?.where
+    ? parenOnlyNote('index', ix.name, parenTwin.name, `WHERE ${parenTwin.where}`)
+    : undefined;
   return {
     kind: 'createIndex', table, name: ix.name, columns: ix.columns, unique: ix.unique,
     ...(ix.where ? { where: ix.where } : {}),
     ...(ix.using ? { using: ix.using } : {}),
     ...(ix.include?.length ? { include: ix.include } : {}),
+    ...(note ? { note } : {}),
   };
 }
 
@@ -554,6 +588,14 @@ export function indexKey(ix: IndexSchema): string {
   return `${ix.unique ? 'u' : ''}|${entries}|${normalizeCheck(ix.where ?? '')}|${ix.using ?? 'btree'}|${(ix.include ?? []).join(',')}`;
 }
 
+/** The same key with EVERY paren stripped — DIAGNOSTIC-ONLY (see {@link stripAllParens}).
+ *  Two indexes with the same paren-blind key but different {@link indexKey} differ by
+ *  parenthesization alone, which is churn, not a change. Never used for matching/identity. */
+function parenBlindIndexKey(ix: IndexSchema): string {
+  const entries = ix.columns.map((c) => stripAllParens(c)).join(',');
+  return `${ix.unique ? 'u' : ''}|${entries}|${stripAllParens(ix.where ?? '')}|${ix.using ?? 'btree'}|${(ix.include ?? []).join(',')}`;
+}
+
 /**
  * Diff standalone indexes by CONTENT — an index with the same key entries, uniqueness, predicate,
  * method and INCLUDE is the same index whatever it is called, so a pulled index re-generates
@@ -580,6 +622,11 @@ function diffIndexes(
 ): void {
   const desiredByKey = new Map(d.indexes.map((ix) => [indexKey(ix), ix]));
   const currentByKey = new Map(c.indexes.map((ix) => [indexKey(ix), ix]));
+  // Paren-blind lookup: a desired index with no exact match may still have a live twin that
+  // differs only by parenthesization (Postgres deparses predicates fully parenthesized). That
+  // is churn, not a change; the create carries a note pointing at the live form. Diagnostic
+  // only — this map never decides identity.
+  const currentByParenBlind = new Map(c.indexes.map((ix) => [parenBlindIndexKey(ix), ix]));
   // A same-NAME index whose CONTENT changed is a redefinition, not a removal, and PostgreSQL has
   // no CREATE OR REPLACE INDEX — it must drop first. Reported by GridironDB: a full unique index
   // became two partial ones, the new partial index derived the SAME generated name as the live
@@ -597,7 +644,11 @@ function diffIndexes(
   for (const [k, ix] of desiredByKey) {
     const live = currentByKey.get(k);
     if (!live) {
-      creates.push(createIndexChange(d.table, ix));
+      const twin = currentByParenBlind.get(parenBlindIndexKey(ix));
+      // Only annotate a twin that is actually being dropped (no exact desired match), so the
+      // note names a live index that is really churning, not one that also round-trips.
+      const churning = twin && !desiredByKey.has(indexKey(twin));
+      creates.push(createIndexChange(d.table, ix, churning ? twin : undefined));
     } else if (ix.nameDeclared && live.name !== ix.name) {
       renames.push({ kind: 'renameIndex', table: d.table, from: live.name, to: ix.name });
     }
@@ -749,11 +800,19 @@ function constraintContentKey(c: ConstraintSpec): string {
 function diffChecks(d: TableSchema, c: TableSchema, dropConstraints: SchemaChange[], addConstraints: SchemaChange[]): void {
   const desiredByPred = new Map(d.checks.map((ck) => [normalizeCheck(ck.expr), ck]));
   const currentByPred = new Map(c.checks.map((ck) => [normalizeCheck(ck.expr), ck]));
+  // Paren-blind lookup, diagnostic only (see diffIndexes): a compound CHECK churns for the
+  // same reason — pg stores `((a) AND (b))`, the model writes `a AND b`.
+  const currentByParenBlind = new Map(c.checks.map((ck) => [stripAllParens(ck.expr), ck]));
   for (const [pred, ck] of currentByPred) {
     if (!desiredByPred.has(pred)) dropConstraints.push({ kind: 'dropConstraint', table: d.table, name: ck.name });
   }
   for (const [pred, ck] of desiredByPred) {
-    if (!currentByPred.has(pred)) addConstraints.push({ kind: 'addConstraint', table: d.table, constraint: { type: 'check', name: ck.name, expr: ck.expr } });
+    if (currentByPred.has(pred)) continue;
+    const twin = currentByParenBlind.get(stripAllParens(ck.expr));
+    // Annotate only a twin that is itself being dropped (no exact desired match) — a real churn.
+    const churning = twin && !desiredByPred.has(normalizeCheck(twin.expr));
+    const note = churning ? parenOnlyNote('check', ck.name, twin.name, twin.expr) : undefined;
+    addConstraints.push({ kind: 'addConstraint', table: d.table, constraint: { type: 'check', name: ck.name, expr: ck.expr }, ...(note ? { note } : {}) });
   }
 }
 
@@ -937,7 +996,7 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string {
       return `${warn}\n${ddl}`;
     }
     case 'addConstraint':
-      return addConstraintSql(change.table, change.constraint);
+      return (change.note ? `${change.note}\n` : '') + addConstraintSql(change.table, change.constraint);
     case 'dropConstraint':
       return `ALTER TABLE ${change.table} DROP CONSTRAINT IF EXISTS ${quote(change.name)};`;
     case 'addPrimaryKey':
@@ -983,7 +1042,8 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string {
       const entry = (c: string): string => (/^[a-z_][a-z0-9_$]*$/i.test(c) ? quote(c) : c);
       const include = change.include?.length ? ` INCLUDE (${colList(change.include)})` : '';
       const where = change.where ? ` WHERE ${change.where}` : '';
-      return `CREATE ${unique}INDEX ${quote(change.name)} ON ${change.table}${using} (${change.columns.map(entry).join(', ')})${include}${where};`;
+      const stmt = `CREATE ${unique}INDEX ${quote(change.name)} ON ${change.table}${using} (${change.columns.map(entry).join(', ')})${include}${where};`;
+      return change.note ? `${change.note}\n${stmt}` : stmt;
     }
     case 'dropIndex': {
       const schema = change.table.includes('.') ? `${change.table.split('.')[0]}.` : '';

package/src/cli/schema-fingerprint.ts

@@ -324,6 +324,66 @@ export function fingerprintLive(
   return fingerprintState(snapshot, contract.tables, opts);
 }
 
+// ---------------------------------------------------------------------------
+// The retained-canon registry — recompute a live hash under a RECORDED version.
+// ---------------------------------------------------------------------------
+
+/**
+ * A frozen canonicalizer: the exact live-side hash produced by ONE historical
+ * FINGERPRINT_VERSION. `fingerprintState` above always emits the CURRENT form, so it is the
+ * retained entry for the current version only. When the canon bumps, the outgoing form does
+ * NOT disappear — it is frozen as its own function and registered under its number here.
+ */
+export type CanonHasher = (
+  snapshot: SchemaSnapshot,
+  tables: TableContract[],
+  opts: CanonicalizeOptions,
+) => string;
+
+/**
+ * Every canon this CLI can still recompute, keyed by its FINGERPRINT_VERSION.
+ *
+ * WHY THIS EXISTS — the descent strand. `db:apply`'s fast-forward proof reads the
+ * `schema_log` ledger and compares each row's recorded `to_fingerprint` against the live
+ * state. A row's hash was computed under whatever canon was current at that apply, recorded
+ * as its `fp_version`. When the CLI later bumps the canon, comparing that old-format hash
+ * against a current-format live hash reports a phantom mismatch — the very kind of false
+ * refusal the ledger exists to prevent. So descent recomputes the LIVE side under the ROW'S
+ * canon, through this registry.
+ *
+ * THE STANDING RULE, so the strand cannot recur one bump later: when you increment
+ * FINGERPRINT_VERSION in this file, you MUST freeze the outgoing canon as a pure function and
+ * register it here under its (now retired) number, alongside the new current one. The frozen
+ * function is a self-contained copy of the canonicalization logic as it stood — it can never
+ * call back into the live `canonicalizeState`, which always emits the new form. A version
+ * absent from this map is unrecomputable: `fingerprintLiveAtVersion` returns null and descent
+ * SKIPS that row (fails closed), never guesses a hash.
+ *
+ * Today the map holds exactly the current version — there is nothing retired yet. It is the
+ * mechanism and the rule that ship now; the first retired entry lands with the first bump.
+ */
+export const RETAINED_CANONS: Readonly<Record<number, CanonHasher>> = {
+  [FINGERPRINT_VERSION]: (snapshot, tables, opts) => fingerprintState(snapshot, tables, opts).hash,
+};
+
+/**
+ * The raw live fingerprint recomputed under a RECORDED canon version, or null when that
+ * version is not retained (unknown, future, or pre-fp_version). Null is the fail-closed
+ * answer: a descent row whose canon we cannot reproduce is skipped, never matched on a hash
+ * computed under the wrong form.
+ */
+export function fingerprintLiveAtVersion(
+  version: number | null | undefined,
+  snapshot: SchemaSnapshot,
+  contract: AuthzContract,
+  opts: CanonicalizeOptions = {},
+  canons: Readonly<Record<number, CanonHasher>> = RETAINED_CANONS,
+): string | null {
+  if (version == null) return null;
+  const canon = canons[version];
+  return canon ? canon(snapshot, contract.tables, opts) : null;
+}
+
 // ---------------------------------------------------------------------------
 // The honesty report: what the base fingerprint does NOT see.
 // ---------------------------------------------------------------------------

package/src/cli/stage-rollback-deps.ts

@@ -0,0 +1,70 @@
+/**
+ * stageConfirmDeps — the AWS-glue executors confirmRollbackPoint needs on a STAGE venue, built
+ * once and shared by db:swap and db:apply (apply-legibility Phase 2).
+ *
+ * rollback-point.ts stays pure — it takes `confirmPhysical` / `confirmLogical` injected so its
+ * wait logic is provable without AWS. This is where those two are wired to the real calls
+ * (RDS snapshot + the db:backup Task), so neither destructive verb hand-rolls its own copy.
+ * `verb` only tunes the log wording ('swap' vs 'apply').
+ */
+
+import { createRdsSnapshot, describeRdsSnapshots } from './aws';
+import { rdsSnapshotIdentifier } from './rds-snapshot';
+import { utcStamp } from './backup';
+import { pollTaskUntilStopped } from './task-poll';
+import { confirmPhysicalSnapshot, interpretBackupPoll } from './swap-snapshot';
+import { runStageBackup, stageBackupDeps } from './stage-backup';
+import type { ConfirmRollbackDeps } from './rollback-point';
+
+export interface StageConfirmContext {
+  region: string;
+  /** `config.databaseInstanceId` — 'placeholder'/undefined means no physical snapshot is possible. */
+  instanceId?: string;
+  opsFn: string;
+  stage?: string;
+  /** The verb, for log wording only. */
+  verb: 'swap' | 'apply';
+  log: (msg: string) => void;
+  step: (msg: string) => void;
+}
+
+/** The `confirmPhysical` / `confirmLogical` half of ConfirmRollbackDeps for a stage venue. */
+export function stageConfirmDeps(ctx: StageConfirmContext): Pick<ConfirmRollbackDeps, 'confirmPhysical' | 'confirmLogical'> {
+  return {
+    confirmPhysical: async (instanceId) => {
+      ctx.step(`Snapshotting the instance before the ${ctx.verb} (RDS physical snapshot of ${instanceId})...`);
+      const snapshotId = rdsSnapshotIdentifier(`${ctx.stage ?? ctx.verb}-${ctx.verb}`, utcStamp(new Date()));
+      return confirmPhysicalSnapshot(
+        {
+          create: (sid) => createRdsSnapshot(ctx.region, instanceId, sid),
+          describe: () => describeRdsSnapshots(ctx.region, instanceId),
+          log: (m) => ctx.log(m),
+          sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+          now: () => Date.now(),
+        },
+        { instanceId, snapshotId },
+      );
+    },
+    // Logical: dispatch the db:backup Task and WAIT. The dispatch returning is not the backup
+    // existing — that conflation is what let a pg_dump run concurrently with the operation it
+    // was meant to precede.
+    confirmLogical: async () => {
+      ctx.step(`Snapshotting the stage before the ${ctx.verb} (db:backup — waiting for the dump to finish)...`);
+      const backup = await runStageBackup({
+        ...stageBackupDeps({ region: ctx.region }, ctx.opsFn, ctx.stage, {
+          onStep: ctx.step,
+          onDispatch: (d: { id: string; runId: string }) =>
+            ctx.log(`backup ${d.id} dispatched (run ${d.runId}) — waiting for the task to stop before the ${ctx.verb} starts.`),
+        }),
+        awaitTask: async (ids) => {
+          const poll = await pollTaskUntilStopped(ctx.region, ctx.opsFn, { runId: ids.runId, taskArn: ids.taskArn });
+          const verdict = interpretBackupPoll(poll, { runId: ids.runId, id: ids.id });
+          if (!verdict.ok) return verdict;
+          return { ok: true, stampedFingerprint: (poll as any).status?.result?.fingerprint as string | undefined };
+        },
+      });
+      if (!backup.ok) return backup;
+      return { ok: true, id: backup.id, stampedFingerprint: backup.fingerprint, warning: backup.warning };
+    },
+  };
+}