@everystack/cli 0.4.69 → 0.4.71

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-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 };
+    },
+  };
+}

package/src/cli/state-apply.ts

@@ -17,7 +17,7 @@
  * named state at both ends" — but nothing here needs a folder.
  */
 
-import { execSync } from 'node:child_process';
+import { execSync, execFileSync } from 'node:child_process';
 import type { ModelDescriptor } from '@everystack/model';
 import { introspectContract, type AuthzContract, type QueryRunner } from './authz-contract';
 import type { SessionRunner } from './session';
@@ -25,7 +25,7 @@ import { introspectSchema, type SchemaSnapshot } from './schema-introspect';
 import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog';
 import { generateMigrationSql, HELD_DROP_PREFIX } from './migration-generate';
 import type { SequenceDescriptor } from '@everystack/model';
-import { fingerprintLive } from './schema-fingerprint';
+import { fingerprintLive, FINGERPRINT_VERSION } from './schema-fingerprint';
 import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply';
 
 const NOTICE_PREFIX = '-- NOTICE';
@@ -276,14 +276,49 @@ export function currentGitRef(): string | null {
   }
 }
 
+/**
+ * True when the models the apply ran against differ from HEAD — a dirty mint.
+ *
+ * schema_log records HEAD (`currentGitRef`) as the commit that declares the applied state. That
+ * pointer is only honest if HEAD's committed models ARE what was applied. If the operator
+ * applied from a worktree with uncommitted model changes, HEAD does not declare plan.to — so
+ * the fast-forward proof must ignore the row (it treats a dirty row like a null git_ref).
+ * Scoped to the models path, so an unrelated dirty file (a README) does not disqualify the row.
+ * Not a git checkout → not dirty (git_ref is null there anyway).
+ */
+export function worktreeDirty(modelsPath: string, cwd: string = process.cwd()): boolean {
+  try {
+    const out = execFileSync('git', ['status', '--porcelain', '--', modelsPath], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString();
+    return out.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
 export interface StateApplyOptions {
   actor?: string | null;
   gitRef?: string | null;
   planRef?: string | null;
   /** The live base fingerprint before this apply (schema_log's from-side). */
   fromFingerprint?: string | null;
+  /** The canon the fingerprints were computed under. Defaults to the current FINGERPRINT_VERSION
+   *  — the hashes this writer records are always current-canon — so the descent witness carries
+   *  the version needed to recompute across a later bump. */
+  fpVersion?: number | null;
+  /** The apply ran from a dirty worktree (models differed from HEAD). The recorded git_ref then
+   *  does not declare what was applied, so descent ignores the row. */
+  dirty?: boolean;
   /** Injectable clock for tests. */
   now?: () => number;
+  /**
+   * When the fast-forward rule was waived by a `--attest-lineage-lost` attestation, a short note read
+   * at WRITE time (a getter, because the attestation is decided in the descent step that runs before
+   * this) and folded into the `applied` schema_log outcome — the durable audit of a deliberate waiver.
+   */
+  descentNote?: () => string | undefined;
 }
 
 export interface StateApplyResult {
@@ -327,16 +362,19 @@ export async function applyGeneratedStatements(
         outcome: `failed: ${String(err?.message ?? err).slice(0, 500)}`,
         actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
         fromFingerprint: options.fromFingerprint,
+        fpVersion: options.fpVersion ?? FINGERPRINT_VERSION, dirty: options.dirty ?? false,
         durationMs: now() - started,
       }));
     } catch { /* the memoir is best-effort on failure */ }
     throw err;
   }
 
+  const note = options.descentNote?.();
   const logRows = await runner(renderSchemaLogInsert({
-    kind: 'state apply', sql: batchSql, outcome: 'applied',
+    kind: 'state apply', sql: batchSql, outcome: note ? `applied — ${note}` : 'applied',
     actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
     fromFingerprint: options.fromFingerprint,
+    fpVersion: options.fpVersion ?? FINGERPRINT_VERSION, dirty: options.dirty ?? false,
     durationMs: now() - started,
   }));
   const logId = logRows?.[0]?.id !== undefined ? Number(logRows[0].id) : undefined;

package/src/cli/swap-snapshot.ts

@@ -33,6 +33,8 @@ export type SnapshotDecision =
   | { mode: 'logical' }
   /** The operator already took one and named it — nothing to do but record it. */
   | { mode: 'attested'; ref: string }
+  /** Take our OWN local `pg_dump -Fc` and verify it (bare --database-url, db:apply only). */
+  | { mode: 'local' }
   /** The operator explicitly accepted no rollback point. */
   | { mode: 'none' }
   /** Nothing safe is available and no consent was given — refuse before anything moves. */
@@ -51,6 +53,13 @@ export interface SnapshotDecisionInput {
   snapshotRef?: string;
   /** `--snapshot <physical|logical|none>`. */
   requested?: SnapshotModeRequest;
+  /**
+   * Bare-URL only: may the tool take its OWN local `pg_dump -Fc` as the rollback point? db:apply
+   * passes true (REVERSAL 1 — bare-URL apply takes+verifies a local dump); db:swap leaves it false, so
+   * a bare-URL swap still REFUSES without an attested ref (a multi-GB schema restore is not a local
+   * pg_dump's job). Default false keeps the shared decision unchanged for db:swap.
+   */
+  localDump?: boolean;
 }
 
 /** Is this instance id something we can actually snapshot, or an absent/placeholder output? */
@@ -73,7 +82,7 @@ function usableInstanceId(id?: string): id is string {
  * is optional in practice.
  */
 export function decideSnapshotMode(input: SnapshotDecisionInput): SnapshotDecision {
-  const { venue, instanceId, snapshotRef, requested } = input;
+  const { venue, instanceId, snapshotRef, requested, localDump } = input;
 
   if (requested !== undefined && !SNAPSHOT_MODES.includes(requested)) {
     return {
@@ -113,6 +122,11 @@ export function decideSnapshotMode(input: SnapshotDecisionInput): SnapshotDecisi
 
   if (requested === 'logical') {
     if (venue === 'url') {
+      // On the venue that CAN take its own local dump (db:apply), an explicit `--snapshot logical`
+      // means exactly that — a pg_dump rollback point — so honour it as the local dump. Where the
+      // local dump is not offered (db:swap), the stage's Task lane is the only logical backup and a
+      // bare URL has no stage, so refuse.
+      if (localDump) return { mode: 'local' };
       return {
         mode: 'refuse',
         reason: 'A logical snapshot runs in the stage\'s Task lane via the ops Lambda, and a bare --database-url has no stage behind it. '
@@ -127,6 +141,9 @@ export function decideSnapshotMode(input: SnapshotDecisionInput): SnapshotDecisi
   if (venue === 'stage') {
     return usableInstanceId(instanceId) ? { mode: 'physical', instanceId } : { mode: 'logical' };
   }
+  // Bare --database-url. Where the tool takes its own local dump (db:apply), that is the default; where
+  // it does not (db:swap), a destructive run over a bare URL still refuses without an attested ref.
+  if (localDump) return { mode: 'local' };
   return {
     mode: 'refuse',
     reason: 'db:swap over a bare --database-url does not take a snapshot for you, and it will not run destructively without one. '