@everystack/cli 0.4.69 → 0.4.71

package/CHANGELOG.md

@@ -4,12 +4,84 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
-## [Unreleased]
+## [0.4.71] - 2026-09-04
+
+### Added
+
+- wire declared ownership into db:provision (B6, CLI half)
+- reconcile refusals point at db:provision, not hand-SQL (B8)
+
+### Fixed
+
+- BLOCKER A — reorder ownership convergence AFTER the secret write
+- round-2 BLOCKER-1 — run ownership convergence on the credentials no-op path too
+- align diag header assertion with the current source
+
+### Documentation
+
+- brownfield ownership convergence — db:provision ENACT + ADOPT (B10)
+
+## [0.4.70] - 2026-09-02
+
+### Added
+
+- proveDescent — ledger-first fast-forward proof + retained-canon registry
+- wire proveDescent into db:apply — ledger read shares the lock session
+- db:apply takes its own durable rollback point (shared db:swap ceremony)
+- db:apply fp-verifies an attested --snapshot-ref before it counts (resolve-else-take)
+- bare --database-url db:apply takes+verifies its own local pg_dump rollback point
+- db:apply infers the lane from the plan — no --direct for a destructive or too-large plan
+- retire --force-descent for the git-native escape + a proven-lineage-lost attestation
+- db:apply refusals print an action, not a check name (p3-action-refusals)
+- the stage lane's fast-forward rule is structurally non-droppable (q1-fail-closed)
+- version the db:apply wire contract, both directions (q1-contract-version)
+- a stage read-disagreement escalates to the direct lane, not a dead-end (q2-escalate)
+
+### Fixed
+
+- address closing-gate review (F1-F4) — db:plan agrees with apply, defensive ordering
+- proveLineageLost refuses when `git remote` fails (close the fail-open)
+- proveLineageLost refuses an absent commit when there are no remotes (R2)
+- split-brain belt + correct the version-skew remedy (closing gate)
+
+### Changed
+
+- db:apply destructive refusals as two named classes (intent vs staleness)
+- delete the orphaned recompile-descent helpers, rewire the illusion of coverage (F1)
+
+### Documentation
+
+- rollback-point identity rests on stage-scoped manifest resolution, not the fingerprint (R5)
+- the two-class refusal doctrine for db:apply (p3-doctrine)
+- the db:apply version-skew refusal and read-disagreement escalation
+
+## [0.4.69] - 2026-08-24
+
+### Fixed
+
+- explain paren-only predicate churn instead of leaving it a mystery
+- hedge the paren-only note — it cannot prove "not a change"
+
+## [0.4.68] - 2026-08-24
+
+### Fixed
+
+- round-trip a text_col = 'literal' predicate — strip the implicit ::text cast
+- harden the ::text strip — whitespace-tolerant array guard, stacked-cast fixpoint
+
+## [0.4.67] - 2026-08-22
+
+### Added
+
+- auto-generated changelogs from conventional commits
 
 ### Fixed
 
 - secrets test expected .js extension stripped by Metro compat
 - async RSA key generation — unblocks the event loop in parallel test runs
+- db:provision is additive-only — never reset an existing role's password
+- address closing-gate review — pin ordering, guard half-done recovery
+- address Fable red-team — rotated-stage guard, safe polarity
 
 ## [0.4.66] - 2026-08-15
 

package/README.md

@@ -230,7 +230,8 @@ everystack db:fork                      # fork a deployed stage's DB into a feat
 
 # Security
 everystack db:doctor                    # is the DB least-privilege + RLS-subject?
-everystack db:provision                 # create the least-privilege role chain (idempotent)
+everystack db:provision                 # role chain + converge declared ownership (ENACT grants, ADOPT plain objects)
+everystack db:provision --confirm       # + ADOPT SECURITY DEFINER functions / views / matviews (runtime change)
 everystack db:authz:pull|diff|test|owner|report   # the authorization contract + red-team
 
 # Backups (see docs/backups.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.69",
+  "version": "0.4.71",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -178,7 +178,7 @@
     "jest": "29.7.0",
     "react": "19.2.0",
     "ts-jest": "29.4.9",
-    "@everystack/server": "0.4.27"
+    "@everystack/server": "0.4.29"
   },
   "scripts": {
     "test": "jest",

package/src/cli/apply-execute.ts

@@ -29,16 +29,53 @@
  * and the memoir stay here, atomic with the connection.
  */
 
-import { introspectContract, type QueryRunner, type AuthzContract } from './authz-contract';
-import type { SessionRunner } from './session';
-import { introspectSchema, type SchemaSnapshot } from './schema-introspect';
+import {
+  introspectContract,
+  assembleContract,
+  RLS_SQL,
+  POLICIES_SQL,
+  GRANTS_SQL,
+  COLUMN_GRANTS_SQL,
+  SCHEMA_ACL_SQL,
+  SEQUENCE_ACLS_SQL,
+  type QueryRunner,
+  type AuthzContract,
+} from './authz-contract';
+import { INTROSPECTION_SESSION, rowsOrEmpty, type SessionRunner } from './session';
+import {
+  introspectSchema,
+  assembleSchema,
+  COLUMNS_SQL,
+  CONSTRAINTS_SQL,
+  ENUMS_SQL,
+  INDEXES_SQL,
+  SEQUENCES_SQL,
+  EXTENSIONS_SQL,
+  type SchemaSnapshot,
+} from './schema-introspect';
 import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog';
-import { fingerprintLive } from './schema-fingerprint';
+import { fingerprintLive, FINGERPRINT_VERSION } from './schema-fingerprint';
 import { governedLiveFingerprint } from './edge-plan';
 import { applyGeneratedStatements } from './state-apply';
 import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply';
 import { checkPlanPrecondition, planHash, type EdgePlan } from './edge-plan';
+import type { DescentLedgerRow } from './git-descent';
 
+/**
+ * CALLER CONTRACT (fail-closed protection lives here, not inside executeApplyPlan):
+ *
+ * - The fast-forward rule (`checkDescent`) is optional in THIS type — the direct lane and tests
+ *   construct it in-process — but on the STAGE lane it is REQUIRED by a narrower `StageApplyOptions`
+ *   type in the server plugin, so a wire payload can never drop it. Absence here is a legitimate
+ *   in-process state, never a dropped gate.
+ * - A DESTRUCTIVE caller MUST confirm a durable rollback point BEFORE calling (the CLI shell runs
+ *   `confirmRollbackPoint` and hard-refuses if it cannot). executeApplyPlan does not police that —
+ *   the protection is structural in the caller. `verifySnapshot` here is the STAMPED-LOGICAL variant
+ *   only (a physical snapshot carries no stamp; its coverage is the concurrency lock below), so its
+ *   absence on a destructive plan is by design, not a skipped gate.
+ * - `verifyAuthority` is present whenever a STAGE is in play (approvers are a stage-side SSM concept);
+ *   a bare `--database-url` has no stage and legitimately omits it.
+ */
 export interface ApplyPlanOptions {
   actor?: string | null;
   /** Defaults to the plan's own gitRef (the intent that minted it). */
@@ -50,10 +87,17 @@ export interface ApplyPlanOptions {
    * declaring the target's state. Omitted = no descent enforcement (tests,
    * or an explicit, confirmed, snapshotted force).
    */
-  verifyDescent?: (live: {
+  checkDescent?: (live: {
     snapshot: SchemaSnapshot;
     contract: AuthzContract;
     fingerprint: string;
+    /** The schema_log witness rows, newest-first. On the direct/server path these are read in
+     *  the SAME session as `fingerprint` (liveBaseAndLedger), so the fast-forward proof and the
+     *  concurrency lock cannot describe two instants. The stage lane's CLI-side descent reads
+     *  the ledger in a separate ops-Lambda invoke, ordered AFTER the state read so a race
+     *  degrades toward REVERT/refusal, never a false pass — and the server re-verifies the lock
+     *  in its own one-session read. */
+    ledger: DescentLedgerRow[];
   }) => Promise<{ ok: true } | { ok: false; reason: string }>;
   /**
    * Destructive authority (brick 9, decisions 11+12): called only when the
@@ -80,8 +124,17 @@ export interface ApplyPlanOptions {
    * schema_log. Omitted = no gate (callers with no baseline to check against).
    */
   verifyAuthzBaseline?: (ctx: { contract: AuthzContract }) => Promise<{ ok: true } | { ok: false; reason: string }>;
+  /** The apply ran from a dirty worktree (models differed from HEAD) — recorded on the
+   *  schema_log row so a later descent ignores this witness. */
+  dirty?: boolean;
   /** Injectable clock for tests. */
   now?: () => number;
+  /**
+   * A note for the schema_log outcome when the fast-forward rule was waived by a
+   * `--attest-lineage-lost` attestation. A getter, because the attestation is decided inside
+   * `checkDescent` (which runs before the write) — the getter reads that decision at write time.
+   */
+  descentNote?: () => string | undefined;
 }
 
 export interface ApplyPlanResult {
@@ -142,6 +195,74 @@ export async function liveBaseFingerprint(session: SessionRunner): Promise<LiveB
   return { hash: fingerprintLive(snapshot, contract).hash, snapshot, contract };
 }
 
+/** The live base fingerprint AND the descent ledger, read in ONE session. */
+export interface LiveBaseAndLedger extends LiveBaseFingerprint {
+  ledger: DescentLedgerRow[];
+}
+
+/**
+ * The newest successful state applies — the descent witnesses. Read alongside the live state
+ * (allowFailure, because a database that never applied through this CLI has no schema_log
+ * yet). Newest-first, capped: the proof consults the newest usable row and stops.
+ */
+export const SCHEMA_LOG_WITNESS_SQL = `SELECT id, to_fingerprint, git_ref, fp_version, dirty, applied_at, outcome
+FROM everystack.schema_log
+WHERE kind = 'state apply' AND outcome = 'applied' AND to_fingerprint IS NOT NULL
+ORDER BY id DESC
+LIMIT 200`;
+
+function mapLedgerRows(rows: any[]): DescentLedgerRow[] {
+  return rows.map((r) => ({
+    id: String(r.id),
+    toFingerprint: r.to_fingerprint == null ? null : String(r.to_fingerprint),
+    gitRef: r.git_ref == null ? null : String(r.git_ref),
+    fpVersion: r.fp_version == null ? null : Number(r.fp_version),
+    dirty: r.dirty === true,
+    appliedAt: r.applied_at instanceof Date ? r.applied_at.toISOString() : String(r.applied_at ?? ''),
+    outcome: String(r.outcome ?? ''),
+  }));
+}
+
+/**
+ * Just the descent ledger, over one session — the stage lane already has the live state from
+ * its double read, and needs only the witness rows to prove the fast-forward CLI-side.
+ */
+export async function readDescentLedger(session: SessionRunner): Promise<DescentLedgerRow[]> {
+  const [rows] = await session([{ sql: SCHEMA_LOG_WITNESS_SQL, allowFailure: true }], INTROSPECTION_SESSION);
+  return mapLedgerRows(rowsOrEmpty(rows));
+}
+
+/**
+ * The live base fingerprint and the descent ledger in ONE repeatable-read session.
+ *
+ * This is the "reads share one session" guarantee the fast-forward proof needs. The
+ * concurrency lock compares this `hash` against plan.from; the descent proof recomputes the
+ * live fingerprint from this `snapshot`/`contract` and joins it against this `ledger`. Reading
+ * them in separate sessions could land on two instants (on the ops Lambda, two containers) —
+ * a fingerprint whose halves describe different databases. One session, one snapshot.
+ */
+export async function liveBaseAndLedger(session: SessionRunner): Promise<LiveBaseAndLedger> {
+  const results = await session(
+    [
+      COLUMNS_SQL, CONSTRAINTS_SQL, ENUMS_SQL, INDEXES_SQL, SEQUENCES_SQL, EXTENSIONS_SQL,
+      RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, SCHEMA_ACL_SQL, SEQUENCE_ACLS_SQL, FUNCTIONS_SQL,
+      { sql: SCHEMA_LOG_WITNESS_SQL, allowFailure: true },
+    ],
+    INTROSPECTION_SESSION,
+  );
+  const snapshot = assembleSchema({
+    columns: results[0] as any[], constraints: results[1] as any[], enums: results[2] as any[],
+    indexes: results[3] as any[], sequences: results[4] as any[], extensions: results[5] as any[],
+  });
+  const contract = assembleContract({
+    rls: results[6] as any[], policies: results[7] as any[], grants: results[8] as any[],
+    columnGrants: results[9] as any[], schemaAcls: results[10] as any[], sequenceAcls: results[11] as any[],
+    functions: (results[12] as any[]).map(contractFunctionRow),
+  });
+  const ledger = mapLedgerRows(rowsOrEmpty(results[13]));
+  return { hash: fingerprintLive(snapshot, contract).hash, snapshot, contract, ledger };
+}
+
 /** Verify → apply → verify. Pure orchestration over an injected QueryRunner. */
 export async function executeApplyPlan(
   runner: QueryRunner,
@@ -149,7 +270,7 @@ export async function executeApplyPlan(
   plan: EdgePlan,
   options: ApplyPlanOptions = {},
 ): Promise<ApplyPlanResult> {
-  const { hash: live, snapshot: before, contract: beforeAuthz } = await liveBaseFingerprint(session);
+  const { hash: live, snapshot: before, contract: beforeAuthz, ledger } = await liveBaseAndLedger(session);
 
   // Two flavors, matched to what each check compares (see EdgePlan): the RAW
   // hash for live-vs-live (the lock, the backup chain), the GOVERNED hash for
@@ -168,8 +289,8 @@ export async function executeApplyPlan(
     return { status: 'refused', liveFingerprint: live, reason: pre.reason };
   }
 
-  if (options.verifyDescent) {
-    const descent = await options.verifyDescent({ snapshot: before, contract: beforeAuthz, fingerprint: live });
+  if (options.checkDescent) {
+    const descent = await options.checkDescent({ snapshot: before, contract: beforeAuthz, fingerprint: live, ledger });
     if (!descent.ok) {
       await recordRefusal(runner, plan, live, 'fast-forward rule', descent.reason, options);
       return { status: 'descent-refused', liveFingerprint: live, reason: descent.reason };
@@ -208,7 +329,10 @@ export async function executeApplyPlan(
     gitRef: options.gitRef ?? plan.gitRef,
     planRef: planHash(plan),
     fromFingerprint: live,
+    fpVersion: FINGERPRINT_VERSION,
+    dirty: options.dirty ?? false,
     now: options.now,
+    ...(options.descentNote ? { descentNote: options.descentNote } : {}),
   });
 
   const { hash: landed, snapshot: after, contract: afterAuthz } = await liveBaseFingerprint(session);
@@ -237,4 +361,4 @@ export async function executeApplyPlan(
 // Re-exported so a single import (`@everystack/cli/apply`) gives a consumer —
 // notably the ops Lambda's db:apply action — everything it needs to validate
 // and run a plan without reaching into the CLI's internal module layout.
-export { PLAN_VERSION, planHash, checkPlanPrecondition, type EdgePlan } from './edge-plan';
+export { PLAN_VERSION, APPLY_CONTRACT_VERSION, planHash, checkPlanPrecondition, type EdgePlan } from './edge-plan';

package/src/cli/apply-lane.ts

@@ -0,0 +1,102 @@
+/**
+ * decideStageLane — when the target is a deployed stage and the operator did NOT name a lane, choose
+ * one from the PLAN (apply-legibility Phase 2, p2-infer-lane). The user should type `db:apply --stage
+ * <s>` and have the right lane happen; naming `--direct` is an advanced override, not a prerequisite.
+ *
+ * The ops-Lambda lane is credential-free but bounded: it cannot run a DESTRUCTIVE plan (its fingerprint
+ * can be assembled from several containers, so the concurrency lock cannot be trusted for data loss),
+ * and it cannot outlast the 900-second Lambda clock. When the plan needs neither, the ops lane runs it.
+ * When it needs either, the DIRECT lane is required — it resolves the operator connection FROM the stage
+ * into memory only (property 4 holds: the operator never holds a URL) and runs CLI-side unbounded.
+ *
+ * Reaching for that connection is not something to do behind the operator's back. So:
+ *   - a DESTRUCTIVE plan still needs --confirm, always and up front (intent stays explicit — a lane
+ *     choice never substitutes for it);
+ *   - a NON-INTERACTIVE session refuses and names --direct, because auto-escalation must never widen
+ *     what an unattended run does (Fable B4);
+ *   - an INTERACTIVE session escalates after the shell announces why and gets one line of consent,
+ *     BEFORE any credential is resolved.
+ *
+ * This function is pure — it decides and phrases; the shell announces, prompts, and resolves.
+ */
+
+import { destructiveConfirmRefusal } from './apply-refusals';
+import { APPLY_CONTRACT_VERSION } from './edge-plan';
+
+/**
+ * q1-contract-version direction B: verify the deployed stage speaks THIS CLI's db:apply wire contract
+ * BEFORE dispatching a write. The `_health` action of a current ops Lambda advertises its
+ * `applyContract`; an older one omits it. Exact equality (never `>=`): a bump means the payload keys or
+ * a gate's meaning changed, so an off-by-any peer must refuse, not guess. Prevention over a post-write
+ * alarm — a mismatched server would silently under-enforce a gate the CLI is relying on it to run.
+ */
+export function checkStageApplyContract(health: unknown): { ok: true } | { ok: false; reason: string } {
+  const advertised = (health as { applyContract?: unknown } | null | undefined)?.applyContract;
+  if (advertised === APPLY_CONTRACT_VERSION) return { ok: true };
+  if (advertised === undefined) {
+    return {
+      ok: false,
+      reason: `the deployed stage does not advertise a db:apply contract version — its ops Lambda predates the apply-contract handshake and could silently under-enforce a safety gate. Redeploy the stage so its server matches this CLI (apply-contract v${APPLY_CONTRACT_VERSION}); nothing was applied.`,
+    };
+  }
+  return {
+    ok: false,
+    reason: `the deployed stage speaks apply-contract v${String(advertised)} but this CLI speaks v${APPLY_CONTRACT_VERSION} — the CLI and the stage are on mismatched versions. Redeploy the stage (or align the CLI) so they match; nothing was applied.`,
+  };
+}
+
+export type StageLaneDecision =
+  /** Additive and within the clock — run credential-free in the ops Lambda. */
+  | { action: 'ops' }
+  /** Needs the direct lane and the session can consent — the shell announces, prompts, then resolves. */
+  | { action: 'escalate'; reason: string }
+  /** Needs the direct lane but cannot proceed here — the shell prints this and exits non-zero. */
+  | { action: 'refuse'; reason: string };
+
+export interface StageLaneInput {
+  destructive: boolean;
+  /** "N drop(s), M narrowing type change(s)" — for the announcement/refusal. */
+  destructiveShape: string;
+  destructiveCount: number;
+  /** estimateOpsRuntimeFit: does the edge fit the 900s ops-Lambda clock? */
+  fits: boolean;
+  fitReason?: string;
+  /** process.stdin.isTTY — is there an operator present to consent? */
+  interactive: boolean;
+  /** --confirm present? (Destructive intent, always explicit.) */
+  confirmed: boolean;
+  planPath: string;
+  stage: string;
+}
+
+export function decideStageLane(input: StageLaneInput): StageLaneDecision {
+  const needsDirect = input.destructive || !input.fits;
+  if (!needsDirect) return { action: 'ops' };
+
+  const directHint = `everystack db:apply --plan ${input.planPath} --stage ${input.stage} --direct${input.destructive ? ' --confirm' : ''}`;
+
+  // INTENT first, and up front: a destructive plan needs --confirm before any lane work. Refusing here
+  // (rather than after resolving a credential) keeps the intent attestation the first thing the
+  // operator must supply, and names the lane it will run on once they do.
+  if (input.destructive && !input.confirmed) {
+    return {
+      action: 'refuse',
+      reason: `${destructiveConfirmRefusal(input.destructiveCount, input.destructiveShape)} It runs on the direct lane (the credential-free lane cannot run destructive plans): ${directHint}.`,
+    };
+  }
+
+  const why = input.destructive
+    ? `This plan is DESTRUCTIVE (${input.destructiveShape}); the credential-free lane cannot run destructive plans.`
+    : `This plan is too large to finish inside the credential-free lane's 900-second limit${input.fitReason ? ` (${input.fitReason})` : ''}.`;
+
+  // Never widen an unattended run: auto-escalation resolves a privileged operator connection, so it
+  // happens only where a person can consent. A non-interactive run names the lane explicitly instead.
+  if (!input.interactive) {
+    return {
+      action: 'refuse',
+      reason: `${why} It needs the direct lane, but this is a non-interactive session — name the lane explicitly: ${directHint}.`,
+    };
+  }
+
+  return { action: 'escalate', reason: why };
+}

package/src/cli/apply-refusals.ts

@@ -0,0 +1,83 @@
+/**
+ * db:apply's DESTRUCTIVE-path refusals, as the TWO classes the DX north star names
+ * (apply-legibility Phase 2, Ty-ratified 2026-08-26). Kept together, and pure, so the two classes
+ * cannot drift into each other — a regression test asserts each names the right escape and only that.
+ *
+ *   INTENT    — the operator is asserting something a re-plan cannot express ("yes, destroy data").
+ *               The escape is a NAMED ATTESTATION (--confirm here), never re-plan.
+ *   STALENESS — the database moved out from under the plan (or the plan was minted against old live).
+ *               The escape is ALWAYS re-plan + apply, and NEVER a flag.
+ *
+ * A new safety check adds a REFUSAL, never a FLAG; and a refusal is one class or the other. This is
+ * the seam Phase 3's p3-action-refusals rewrites the surrounding wording over — the classes stay.
+ */
+
+/**
+ * INTENT: a destructive plan requires explicit confirmation, every time. Re-planning cannot assert
+ * "yes, destroy" for the operator, so the attestation (--confirm) is irreducible — do NOT reword this
+ * toward "re-plan".
+ */
+export function destructiveConfirmRefusal(destructiveCount: number, shape: string): string {
+  return `This plan is DESTRUCTIVE — ${destructiveCount} statement(s) lose data (${shape}). Explicit confirmation is required, always: re-run with --confirm.`;
+}
+
+/**
+ * STALENESS: the rollback point captured a different schema than the plan starts from, which means the
+ * database moved since the plan was minted. Restoring it would not return the DB to where the plan
+ * began, so refuse — and the escape is re-plan, NOT a flag. Do NOT add a flag to this path.
+ */
+export function snapshotMovedRefusal(ref: string, captured: string, planFrom: string): string {
+  return `the rollback point ${ref} captures ${captured.slice(0, 12)}, not the plan's start ${planFrom.slice(0, 12)} — the database moved since the plan was minted. Re-plan (db:plan) and apply again.`;
+}
+
+// ---------------------------------------------------------------------------
+// The USER-FACING refusal message (apply-legibility Phase 3, p3-action-refusals).
+//
+// Every refusal db:apply reaches from executeApplyPlan prints an ACTION, never a check name. The
+// reason string is already action-phrased at its source (checkPlanPrecondition, proveVerdictForApply,
+// checkDestructiveAuthority, the snapshot gate, the baseline gate). This layer only marks the OUTCOME
+// and forwards that reason — it does NOT re-label the check the way the old
+// `REFUSED (fast-forward rule):` / `(snapshot gate)` / `(destructive authority)` wording did.
+//
+// The internal cause code (`descent-refused`, `snapshot-refused`, `ungoverned grantee`, …) stays where
+// it belongs: recorded in everystack.schema_log by recordRefusal, the audit trail. It never reaches
+// user text.
+//
+// The switch is EXHAUSTIVE by construction: the `assertNever` default is the gate that stops a new
+// refusal status from ever again reaching the display with no case — the bug that let `authz-refused`
+// print nothing and exit 0. Add a status to ApplyPlanResult and this stops compiling until it has a line.
+// ---------------------------------------------------------------------------
+
+/** The failure statuses executeApplyPlan can return — everything that is not `applied`/`already-applied`. */
+export type ApplyRefusalStatus =
+  | 'refused'
+  | 'descent-refused'
+  | 'authority-refused'
+  | 'snapshot-refused'
+  | 'authz-refused'
+  | 'verify-failed';
+
+/**
+ * Render the user-facing line for a refused or faulted apply. Pure, so the message-snapshot test can
+ * assert every path prints an action and no path prints check-name jargon. Returns the full line
+ * (the caller adds the ✗ marker and exits non-zero).
+ *
+ * `verify-failed` is NOT a refusal — the apply RAN and the result did not match the plan, so it keeps
+ * its own outcome word. Its reason already says what to do (investigate).
+ */
+export function formatApplyRefusal(status: ApplyRefusalStatus, reason: string): string {
+  switch (status) {
+    case 'refused': // the concurrency lock — the database moved since minting
+    case 'descent-refused': // the fast-forward rule — the checkout is behind the deploying branch
+    case 'authority-refused': // the destructive-approver set — hand the plan to an approver
+    case 'snapshot-refused': // no confirmed rollback point before a destructive statement
+    case 'authz-refused': // a foreign grantee arrived after the plan was minted
+      return `REFUSED: ${reason}`;
+    case 'verify-failed':
+      return `Verify FAILED: ${reason}`;
+    default: {
+      const never: never = status;
+      throw new Error(`unhandled apply refusal status: ${String(never)}`);
+    }
+  }
+}

package/src/cli/backup-resolve.ts

@@ -0,0 +1,31 @@
+/**
+ * fetchBackupManifest — resolve a backup's `.meta.json` manifest from the stage's backups bucket,
+ * CLI-side. This is the IO half of the destructive-apply rollback-point gate; the pure verifier is
+ * `verifySnapshotRef` in backup.ts. MIRRORS @everystack/server/src/backup-run.ts fetchBackupManifest
+ * (the CLI does not import the server — see backup.ts's mirror note), reading over the CLI's own S3
+ * helper instead of the server's.
+ *
+ * Returns null when the id is malformed OR the manifest object is absent. A manifest exists ONLY on a
+ * successful dump, so absence == "no completed backup with that id" — and `verifySnapshotRef` treats
+ * null as a refusal. Every failure (NoSuchKey, a truncated read, unparseable JSON) collapses to null:
+ * an unreadable manifest is not a rollback point, and refusing is the safe answer.
+ */
+
+import { getFromS3 } from './aws';
+import { keyForId, metaKey, type BackupManifest } from './backup';
+
+export async function fetchBackupManifest(
+  region: string,
+  bucket: string,
+  id: string,
+): Promise<BackupManifest | null> {
+  const key = keyForId(id);
+  if (!key) return null;
+  try {
+    const body = await getFromS3(region, bucket, metaKey(key));
+    if (!body) return null;
+    return JSON.parse(body.toString('utf8')) as BackupManifest;
+  } catch {
+    return null; // NoSuchKey / parse failure → no valid manifest
+  }
+}

package/src/cli/backup.ts

@@ -49,6 +49,110 @@ export function keyForId(id: string): string | null {
   return ref ? `${backupPrefix(ref.stage)}/${ref.name}.dump.gz` : null;
 }
 
+// --- The destructive-apply rollback-point gate — MIRRORS @everystack/server/src/backup.ts --------
+// db:apply's destructive lane runs CLI-side (--stage --direct), so the safety gate that server-side
+// db:apply used (verifySnapshotRef against a backup's `.meta.json`) has to exist CLI-side too. The
+// server is a peer dependency the CLI deliberately does NOT import from — server/plugin.ts imports
+// `@everystack/cli/reconcile`, so a runtime import back would close a cycle. The house rule (see the
+// plugin-type mirrors in src/plugin.ts) is to MIRROR the pure core and guard the two copies with a
+// parity test. BackupManifest, SnapshotVerifyInput, SnapshotVerdict, SNAPSHOT_FRESHNESS_MS and
+// verifySnapshotRef below are byte-for-byte the server's — a matrix parity test (verify-snapshot-ref
+// parity) runs BOTH over the same inputs so a divergence fails CI, not a consumer's rollback.
+
+/** A backup's `.meta.json` sidecar — written on a SUCCESSFUL dump, so its presence means "succeeded". */
+export interface BackupManifest {
+  id: string;
+  stage: string;
+  /** ISO 8601. */
+  createdAt: string;
+  /** The base-schema fingerprint captured at dump time (absent on pre-B3 backups). */
+  fingerprint?: string;
+  /**
+   * Who computed `fingerprint`.
+   *
+   * Absent or 1: the TASK IMAGE computed it, from a copy of the CLI frozen into a digest-pinned
+   * image at publish time. That copy could disagree with the CLI now doing the comparing, so such a
+   * fingerprint cannot be trusted as the safety gate's tie.
+   *
+   * 2: the OPERATOR computed it, with the same code `db:apply` uses, and the CLI verified the task
+   * stamped exactly what it sent.
+   */
+  metaVersion?: number;
+  fingerprintSource?: string;
+  bytes?: number;
+  key: string;
+}
+
+export interface SnapshotVerifyInput {
+  /** The resolved backup manifest, or null when none could be resolved. */
+  manifest: BackupManifest | null;
+  /** plan.fromFingerprint — the schema state the apply expects to change. */
+  planFrom: string;
+  /** The stage being changed — the backup must cover THIS database. */
+  targetStage: string;
+  now: Date;
+  /** How old a backup may be and still qualify (data-rollback bound; fp already proves schema). */
+  freshnessWindowMs: number;
+}
+
+export type SnapshotVerdict = { ok: true; id: string } | { ok: false; reason: string };
+
+/** How old a `--snapshot-ref` backup may be and still count as a rollback point (mirrors server). */
+export const SNAPSHOT_FRESHNESS_MS = 60 * 60_000;
+
+/**
+ * Verify a resolved backup is a valid safety net for a destructive apply.
+ *
+ * IDENTITY vs STATE — the rollback point's IDENTITY (which backup, for which database) rests on the
+ * STAGE-SCOPED MANIFEST RESOLUTION, not on the fingerprint. The ref was resolved against THIS stage's
+ * backupsBucket (backup-resolve.ts), and the `manifest.stage === targetStage` tie below confirms the
+ * backup was taken FOR this database. The fingerprint is a STATE check on top of that identity: it
+ * proves the backup captured the same SCHEMA the plan starts from (plan.from) — a value a DIFFERENT
+ * database could match by coincidence, so it can never stand in for the stage-scoped resolution. Do
+ * not read `fingerprint == plan.from` as "this is the right backup"; the bucket + stage tie is that.
+ *
+ * So a valid rollback point: exists (⇒ succeeded), covers this stage (identity), carries a fingerprint
+ * equal to plan.from (⇒ restores the exact schema state being changed), and is fresh. Every refusal
+ * names the fix (db:backup). Pure; the resolution IO lives in backup-resolve.ts and the enforcement in
+ * db:apply's destructive lane.
+ */
+export function verifySnapshotRef(input: SnapshotVerifyInput): SnapshotVerdict {
+  const { manifest, planFrom, targetStage, now, freshnessWindowMs } = input;
+  const takeFresh = `take a fresh backup: everystack db:backup --stage ${targetStage}, then re-run.`;
+  if (!manifest) {
+    return { ok: false, reason: `no backup found for stage ${targetStage} — ${takeFresh}` };
+  }
+  if (manifest.stage !== targetStage) {
+    return { ok: false, reason: `snapshot ${manifest.id} is for stage ${manifest.stage}, not ${targetStage} — a snapshot must cover the database being changed. ${takeFresh}` };
+  }
+  if (!manifest.fingerprint) {
+    return { ok: false, reason: `snapshot ${manifest.id} predates fingerprint stamping — ${takeFresh}` };
+  }
+  // Freshness first among the remaining checks: it is independent of everything below and is by far
+  // the most common reason a snapshot is rejected, so it should be what the operator reads.
+  const ageMs = now.getTime() - Date.parse(manifest.createdAt);
+  if (!(ageMs >= 0) || ageMs > freshnessWindowMs) {
+    const mins = Math.round(ageMs / 60_000);
+    return { ok: false, reason: `snapshot ${manifest.id} is ${mins} min old (freshness window ${Math.round(freshnessWindowMs / 60_000)} min) — ${takeFresh}` };
+  }
+  // Provenance BEFORE the tie: a pre-v2 manifest's fingerprint was computed INSIDE the task image,
+  // by a copy of the CLI frozen at publish time, so comparing it against this plan's fingerprint
+  // compares two things that were not necessarily produced the same way. Checking the tie first
+  // would report a mismatch as if the schema differed, sending the operator after the wrong thing.
+  // With an hour-long freshness window this only ever refuses a backup taken in the last hour by a
+  // pre-upgrade CLI — and the remedy is the backup they were going to take anyway.
+  if (!(manifest.metaVersion && manifest.metaVersion >= 2)) {
+    return {
+      ok: false,
+      reason: `snapshot ${manifest.id} carries a fingerprint computed inside the task image, which can disagree with this CLI — ${takeFresh}`,
+    };
+  }
+  if (manifest.fingerprint !== planFrom) {
+    return { ok: false, reason: `snapshot ${manifest.id} captured schema ${manifest.fingerprint.slice(0, 12)}, but this plan starts from ${planFrom.slice(0, 12)} — it would not restore the state being changed. ${takeFresh}` };
+  }
+  return { ok: true, id: manifest.id };
+}
+
 // --- Artifact key scheme (schema-scoped exports for the hot-swap) — mirrors server/backup.ts ----
 // A backup is the whole database; an ARTIFACT is one schema, content-addressed, carrying the schema
 // fingerprint it was built against. Separate prefix so the two never collide. db:swap --stage --direct