@everystack/cli 0.4.69 → 0.4.70

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

@@ -31,10 +31,28 @@
 
 import fs from 'node:fs/promises';
 import { type QueryRunner } from '../authz-contract';
-import { currentGitRef } from '../state-apply';
-import { planHash, PLAN_VERSION, type EdgePlan } from '../edge-plan';
-import { verifyDescent, type DescentVerdict, type LiveState } from '../git-descent';
+import { currentGitRef, worktreeDirty } from '../state-apply';
+import { planHash, PLAN_VERSION, APPLY_CONTRACT_VERSION, type EdgePlan } from '../edge-plan';
+import {
+  proveDescent,
+  decideDescentApply,
+  attestationNote,
+  proveLineageLost,
+  realLineageProbe,
+  type DescentLedgerRow,
+  type LiveState,
+} from '../git-descent';
 import { checkDestructiveAuthority, readApproverParam, resolveCallerIdentity, type AuthorityVerdict } from '../apply-authority';
+import { decideSnapshotMode, type SnapshotModeRequest } from '../swap-snapshot';
+import { confirmRollbackPoint, type RollbackPoint } from '../rollback-point';
+import { stageConfirmDeps } from '../stage-rollback-deps';
+import { verifySnapshotRef, SNAPSHOT_FRESHNESS_MS, utcStamp } from '../backup';
+import { fetchBackupManifest } from '../backup-resolve';
+import { confirmLocalDump } from '../local-rollback';
+import { destructiveConfirmRefusal, snapshotMovedRefusal, formatApplyRefusal } from '../apply-refusals';
+import { decideStageLane, checkStageApplyContract } from '../apply-lane';
+import { promptYesNo } from '../prompt';
+import path from 'node:path';
 import { resolveModelsPath } from '../models-path';
 import { loadModels } from './db-generate';
 import { loadDeclaredDerived } from '../declared-derived';
@@ -45,11 +63,11 @@ import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '
 import { borrowedSessionRunner, type SessionRunner } from '../session';
 import { resolveConfig, opsFunction } from '../config';
 import { invokeAction, lambdaQueryRunner, lambdaSessionRunner } from '../aws';
-import { executeApplyPlan, type ApplyPlanResult } from '../apply-execute';
+import { executeApplyPlan, readDescentLedger, type ApplyPlanResult } from '../apply-execute';
 import { estimateOpsRuntimeFit } from '../ops-fit';
 import { resolveOperatorUrlViaStage } from '../direct-venue';
 import { withMutationLease, MutationLeaseError } from '../mutation-lease';
-import { readStageStateTwice, stageDestructiveRefusal } from '../stage-read-consistency';
+import { readStageStateTwice } from '../stage-read-consistency';
 import { step, success, fail, info, warn } from '../output';
 
 // The apply core lives in apply-execute.ts (shared with the ops Lambda's
@@ -62,60 +80,31 @@ export type { ApplyPlanOptions, ApplyPlanResult } from '../apply-execute';
 // The CLI shell.
 // ---------------------------------------------------------------------------
 
-/**
- * Collapse a DescentVerdict into the ok/reason shape the apply core (and the
- * ops Lambda's db:apply action) enforce. `no-git` / `fresh-target` pass — the
- * rule can't be verified there — matching the direct-URL path's callback.
- */
-export function descentVerdictForApply(verdict: DescentVerdict): { ok: true } | { ok: false; reason: string } {
-  switch (verdict.status) {
-    case 'ok':
-    case 'fresh-target':
-    case 'no-git':
-      return { ok: true };
-    case 'diverged':
-    case 'drift':
-    // `indeterminate` refuses like the others, and must: the search was not exhaustive, so
-    // the fast-forward rule is unproven. Its REASON is the difference — it points at this
-    // run, not at the database. Never fold it into `drift`.
-    case 'indeterminate':
-      return { ok: false, reason: verdict.reason };
-  }
-}
-
 /**
  * Render an ApplyPlanResult — shared by the direct (`--database-url`) and the
  * credential-free staged (`--stage`) paths, so the two report identically.
  * Every refusal and the verify-fault exit non-zero.
+ *
+ * Exported so a test can drive the EXIT path directly — the layer the
+ * silent-exit-0 bug actually lived (a refusal status with no case printed
+ * nothing and exited 0). formatApplyRefusal owns the string; this owns the
+ * process.exit(1).
  */
-function reportApplyResult(result: ApplyPlanResult, plan: EdgePlan): void {
+export function reportApplyResult(result: ApplyPlanResult, plan: EdgePlan): void {
   switch (result.status) {
     case 'already-applied':
       success(`Already at ${plan.toFingerprint.slice(0, 12)} — nothing to do (idempotent re-apply).`);
-      break;
-    case 'refused':
-      fail(`REFUSED: ${result.reason}`);
-      process.exit(1);
-      break;
-    case 'descent-refused':
-      fail(`REFUSED (fast-forward rule): ${result.reason}`);
-      process.exit(1);
-      break;
-    case 'authority-refused':
-      fail(`REFUSED (destructive authority): ${result.reason}`);
-      process.exit(1);
-      break;
-    case 'snapshot-refused':
-      fail(`REFUSED (snapshot gate): ${result.reason}`);
-      process.exit(1);
-      break;
-    case 'verify-failed':
-      fail(`Verify FAILED: ${result.reason}`);
-      process.exit(1);
-      break;
+      return;
     case 'applied':
       success(`Applied and verified — the target is at ${result.liveFingerprint.slice(0, 12)}, exactly as the plan predicted. Recorded in everystack.schema_log (plan_ref ${planHash(plan).slice(0, 12)}).`);
-      break;
+      return;
+    default:
+      // Every remaining status is a refusal or a verify fault. TS narrows result.status here to
+      // exactly ApplyRefusalStatus, so a future status that is neither success nor a known refusal
+      // stops this compiling — the fallthrough that let `authz-refused` print nothing and exit 0
+      // cannot come back. The message is an action; the internal cause code stays in schema_log.
+      fail(formatApplyRefusal(result.status, result.reason ?? ''));
+      process.exit(1);
   }
 }
 
@@ -127,15 +116,20 @@ function reportApplyResult(result: ApplyPlanResult, plan: EdgePlan): void {
  * destructive-approver check. The Lambda re-verifies the concurrency lock,
  * applies the DDL in one transaction, stamps schema_log, and verifies plan.to.
  */
+/** applyPlanViaStage runs the credential-free ops-lane write, OR asks to escalate to the direct
+ *  lane (a read-disagreement it cannot resolve on this lane). It never returns after a successful
+ *  apply — reportApplyResult exits — so a returned value is always the escalate request. */
+type StageOutcome = { escalate: true; reason: string } | void;
+
 async function applyPlanViaStage(
   plan: EdgePlan,
   flags: Record<string, string>,
-  forceDescent: string | undefined,
-): Promise<void> {
+): Promise<StageOutcome> {
   step('Resolving deployed config...');
   const config = await resolveConfig(flags.stage);
   const { region } = config;
   const fn = opsFunction(config);
+  const attestLineageLost = flags['attest-lineage-lost']; // validated (not bare 'true') in dbApplyCommand
 
   info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
 
@@ -151,45 +145,66 @@ async function applyPlanViaStage(
     process.exit(1);
   });
   if (!readPair.ok) {
+    // q2-escalate: a read-disagreement no longer dead-ends. INTERACTIVELY, ask to escalate to the
+    // direct lane — ONE session against one database, the lane that CAN read consistently (and the
+    // apply's concurrency lock still refuses if the state truly moved, so escalation bypasses no
+    // safety). NON-interactively, keep the actionable refusal: never auto-escalate an unattended run
+    // (it resolves a privileged credential), and the refusal already names --direct.
+    if (process.stdin.isTTY) {
+      return {
+        escalate: true,
+        reason: `The stage was read twice and the two reads disagree (${readPair.first.slice(0, 12)} then ${readPair.second.slice(0, 12)}) — the state may be changing, or inconsistent ops-Lambda containers answered. The direct lane reads over ONE session against one database, which resolves this.`,
+      };
+    }
     fail(readPair.reason);
     process.exit(1);
   }
   warn(readPair.warning);
 
+  // q1-contract-version direction B: the reads passed — now verify the deployed stage speaks THIS
+  // CLI's db:apply wire contract BEFORE dispatching the write. An older ops Lambda would silently
+  // under-enforce a gate the CLI relies on it to run; catch it with a redeploy message, not after a
+  // write. Pre-dispatch, so it opens no connection and writes no schema_log row.
+  step("Verifying the deployed stage speaks this CLI's apply contract...");
+  const contract = checkStageApplyContract(await invokeAction(region, fn, '_health', {}));
+  if (!contract.ok) {
+    fail(`REFUSED: ${contract.reason}`);
+    process.exit(1);
+  }
+
   try {
     // Descent — the fast-forward rule needs the git checkout, so the CLI
     // decides it (the Lambda has no checkout). It runs against the state the
     // double read already produced (no third trip), and the verdict goes to the
-    // write action, which enforces + records it in order.
+    // write action, which enforces + records it in order. A refusal's escape is
+    // git-native (git revert / db:generate / fetch); the one attestation
+    // (--attest-lineage-lost) is honoured only when the CLI proves the declaring
+    // commit is gone from every ref.
     let descentVerdict: { ok: true } | { ok: false; reason: string };
-    if (forceDescent !== undefined) {
-      warn(`DESCENT FORCED — the fast-forward rule is bypassed for this apply. Snapshot on record: ${forceDescent}.`);
-      descentVerdict = { ok: true };
-    } else {
+    let descentAttested: string | undefined;
+    {
       const { snapshot, contract } = readPair.state;
-      step("Descent: searching git for the commit that declares the stage's state...");
-      const verdict = await verifyDescent(resolveModelsPath(flags.models), { snapshot, contract }, {});
-      switch (verdict.status) {
-        case 'ok':
-          info(`descent: ${verdict.commit.slice(0, 12)} declares the stage's state and is an ancestor of HEAD — fast-forward.`);
-          break;
-        case 'fresh-target':
-          info('descent: fresh target (no tables) — nothing to protect, bootstrapping.');
-          break;
-        case 'no-git':
-          warn('descent: not a git checkout — the fast-forward rule cannot be verified here.');
-          break;
-        case 'diverged':
-        case 'drift':
-          break; // the reason travels to the action's refusal + the memoir
-        case 'indeterminate':
-          // Said out loud here because the operator's next move is "run it again", not
-          // "reconcile your models" — and a refusal that reads like drift sends them the
-          // wrong way. The reason still travels to the refusal.
-          warn(`descent: ${verdict.unevaluated.length} historical tree(s) could not be extracted — the search was not exhaustive.`);
-          break;
+      step("Descent: reading the stage's schema_log ledger...");
+      const ledger = await readDescentLedger(lambdaSessionRunner(region, fn));
+      step("Descent: proving the fast-forward rule against the ledger...");
+      const verdict = await proveDescent(resolveModelsPath(flags.models), { snapshot, contract }, ledger, {});
+      if (verdict.status === 'proven') {
+        info(`descent: proven via ${verdict.via} — ${verdict.commit.slice(0, 12)} is an ancestor of HEAD, fast-forward.`);
+      } else if (verdict.status === 'fresh-target') {
+        info('descent: fresh target (no tables) — nothing to protect, bootstrapping.');
+      } else if (verdict.status === 'no-git') {
+        warn('descent: not a git checkout — the fast-forward rule cannot be verified here.');
+      }
+      const decision = decideDescentApply(verdict, {
+        ...(attestLineageLost ? { attestation: attestLineageLost } : {}),
+        destructive: plan.destructive > 0,
+        proveLineage: (sha) => proveLineageLost(sha, realLineageProbe(process.cwd())),
+      });
+      if (decision.ok && decision.attested) {
+        descentAttested = attestationNote(decision.attested);
+        warn(`DESCENT ATTESTED — ${descentAttested}. The declaring commit is proven gone from every ref; the fast-forward rule is waived for this apply and the waiver is recorded.`);
       }
-      descentVerdict = descentVerdictForApply(verdict);
+      descentVerdict = decision.ok ? { ok: true } : { ok: false, reason: decision.reason };
     }
 
     // Destructive ceremony — the approver check is against the caller's REAL
@@ -206,7 +221,7 @@ async function applyPlanViaStage(
     if (plan.destructive > 0) {
       const shape = `${plan.classification.drops} drop(s), ${plan.classification.narrowings} narrowing type change(s)`;
       if (flags.confirm !== 'true') {
-        fail(`This plan is DESTRUCTIVE — ${plan.destructive} statement(s) lose data (${shape}). Explicit confirmation is required, always: re-run with --confirm.`);
+        fail(destructiveConfirmRefusal(plan.destructive, shape));
         process.exit(1);
       }
       step(`Destructive authority: checking the approver set for stage ${flags.stage}...`);
@@ -226,9 +241,14 @@ async function applyPlanViaStage(
     step('Applying in the ops Lambda (credential-free — the operator never holds a database URL)...');
     const result: any = await invokeAction(region, fn, 'db:apply', {
       plan,
+      // q1-contract-version direction A: the server refuses on exact mismatch, so a payload-key or
+      // gate-semantics skew is a hard refusal, never a silently dropped gate.
+      contractVersion: APPLY_CONTRACT_VERSION,
       actor: process.env.USER ?? null,
       gitRef: currentGitRef() ?? plan.gitRef,
+      dirty: worktreeDirty(resolveModelsPath(flags.models)),
       descentVerdict,
+      ...(descentAttested ? { descentAttested } : {}),
       ...(authorityVerdict ? { authorityVerdict } : {}),
       ...(flags['snapshot-ref'] ? { snapshotRef: flags['snapshot-ref'] } : {}),
       stage: flags.stage,
@@ -237,6 +257,19 @@ async function applyPlanViaStage(
       fail(`Apply failed: ${result.error}`);
       process.exit(1);
     }
+    // The probe/dispatch split-brain belt (q1-contract-version, Fable red team). Direction B's _health
+    // handshake and this write are SEPARATE invokes; mid-deploy they can land on two container
+    // versions, so the health check can pass on a new container while the WRITE runs on an old one
+    // that ignores the contract and silently skips the fast-forward rule — the two-invokes-two-
+    // containers blend, reproduced inside its own fix. It cannot be prevented (the write already
+    // committed), so surface it LOUDLY post-write: a current server stamps every applied result with
+    // the contract it ran under, so an applied result missing that stamp means an older container
+    // served the write. A refused result is not affected (nothing landed).
+    const landed = result?.status === 'applied' || result?.status === 'already-applied';
+    if (landed && result?.contractVersion !== APPLY_CONTRACT_VERSION) {
+      fail(`APPLIED, BUT UNVERIFIED: the write landed, but the ops Lambda did not stamp the apply contract (got v${result?.contractVersion ?? '(none)'}, expected v${APPLY_CONTRACT_VERSION}). A mid-deploy split-brain can route the health check and the write to different code versions — an older container silently skips the fast-forward rule, so this apply MAY have reverted merged work. Verify NOW: everystack db:fingerprint --stage ${flags.stage}, and inspect everystack.schema_log. Once the deploy has fully rolled out, re-plan and re-apply.`);
+      process.exit(1);
+    }
     if (result?.snapshotId) {
       info(`snapshot on record: ${result.snapshotId} — restore with db:restore --from ${result.snapshotId} --confirm.`);
     }
@@ -247,6 +280,36 @@ async function applyPlanViaStage(
   }
 }
 
+/**
+ * Escalate a stage apply to the direct lane. Announce WHY, get one line of consent BEFORE any
+ * credential is resolved, then resolve the operator connection from the stage into memory (property
+ * 4: the operator never holds a URL) and return it as the db source. Shared by the two escalation
+ * triggers — a plan the ops lane cannot run (destructive/too-large), and a read-disagreement the ops
+ * lane cannot resolve (q2-escalate). On decline or resolve-failure it exits non-zero, never falls
+ * through. Reached only where a person can consent — the callers gate on interactivity first.
+ */
+async function escalateStageToDirect(
+  reason: string,
+  plan: EdgePlan,
+  planPath: string,
+  stage: string,
+): Promise<Extract<DbSource, { kind: 'url' }>> {
+  info(reason);
+  info('It needs the direct lane, which resolves the operator connection FROM the stage itself (you never hold a URL) and runs CLI-side over ONE session with an unbounded clock.');
+  const consented = await promptYesNo(`Resolve the operator connection and run this apply on the direct lane for stage ${stage}? [y/N] `);
+  if (!consented) {
+    fail(`Aborted — no lane chosen. Re-run with --direct to name the lane (everystack db:apply --plan ${planPath} --stage ${stage} --direct${plan.destructive > 0 ? ' --confirm' : ''}), or make the plan additive.`);
+    process.exit(1);
+  }
+  step('Resolving the operator connection from the stage...');
+  const op = await resolveOperatorUrlViaStage(stage).catch((err: any) => {
+    fail(err.message);
+    process.exit(1);
+  });
+  info(`operator credential resolved (${op.source}) — executing CLI-side, unbounded clock.`);
+  return { kind: 'url', url: op.url, from: 'operator' };
+}
+
 export async function dbApplyCommand(flags: Record<string, string>): Promise<void> {
   const planPath = flags.plan;
   if (!planPath) {
@@ -274,19 +337,15 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     process.exit(1);
   }
 
-  // The fast-forward rule's force ceremony (design decision 9): explicit
-  // (--force-descent), snapshotted (its value NAMES the snapshot you took),
-  // and confirmed (--confirm). All three or no bypass.
-  const forceDescent = flags['force-descent'];
-  if (forceDescent !== undefined) {
-    if (forceDescent === 'true') {
-      fail('--force-descent needs the snapshot you took as its value: --force-descent <snapshot-ref> (take one first: db:snapshot or db:backup).');
-      process.exit(1);
-    }
-    if (flags.confirm !== 'true') {
-      fail('--force-descent bypasses the fast-forward rule — confirm explicitly with --confirm.');
-      process.exit(1);
-    }
+  // The narrow descent attestation (replaces the retired --force-descent, Ty-ratified 2026-08-26).
+  // `--attest-lineage-lost <sha>` waives the fast-forward rule for the ONE case no re-plan can express:
+  // the declaring commit is proven unreachable from every ref. It NAMES the commit (must equal the one
+  // the refusal reports) and is honoured only when the CLI's own git proof concurs — every other
+  // descent refusal has a flagless git-native escape. `true` (a bare flag) is a usage error.
+  const attestLineageLost = flags['attest-lineage-lost'];
+  if (attestLineageLost === 'true') {
+    fail('--attest-lineage-lost needs the declaring commit as its value: --attest-lineage-lost <sha> (the commit the descent refusal names). It is honoured only when that commit is proven gone from every ref.');
+    process.exit(1);
   }
 
   // `--stage --direct` (lane 1): resolve the stage's OPERATOR connection from its ops
@@ -305,75 +364,149 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
     }
   }
 
-  // Deployed stage, no direct URL: the write runs in the ops Lambda — the
-  // operator never holds a database URL. --database-url stays local-only.
+  // Deployed stage, no explicit --direct: INFER the lane from the plan (p2-infer-lane). The ops-Lambda
+  // lane is credential-free but cannot run a destructive plan (its fingerprint can be a container
+  // collage) and cannot outlast the 900s clock. When the plan needs neither, it runs there. When it
+  // needs the direct lane, the tool reaches for the operator connection ITSELF — announcing why,
+  // getting one line of consent, and only then resolving the credential (into memory only, property 4).
   if (dbSource.kind === 'stage') {
-    // A DESTRUCTIVE plan does not run on this lane at all — no ceremony lifts it.
-    // The stage lane's fingerprint (the concurrency lock) can be assembled from
-    // several ops-Lambda containers, and the double read below only DETECTS that;
-    // it cannot rule it out. Dropping data on a read that may be a collage is the
-    // one trade never worth making, so the destructive path is the direct lane's.
-    if (plan.destructive > 0) {
-      const shape = `${plan.classification.drops} drop(s), ${plan.classification.narrowings} narrowing type change(s)`;
-      fail(stageDestructiveRefusal(shape, planPath, flags.stage));
-      process.exit(1);
-    }
-    // Will this edge fit the ops-Lambda's 900-second clock? If not, refuse up front and
-    // name --direct (credential-free, unbounded) instead of burning 15 minutes to learn it.
+    const shape = `${plan.classification.drops} drop(s), ${plan.classification.narrowings} narrowing type change(s)`;
     const fit = estimateOpsRuntimeFit(plan);
-    if (!fit.fits) {
-      fail(`REFUSED (ops-Lambda runtime): ${fit.reason}`);
+    const lane = decideStageLane({
+      destructive: plan.destructive > 0,
+      destructiveShape: shape,
+      destructiveCount: plan.destructive,
+      fits: fit.fits,
+      ...(fit.fits ? {} : { fitReason: fit.reason }),
+      interactive: !!process.stdin.isTTY,
+      confirmed: flags.confirm === 'true',
+      planPath,
+      stage: flags.stage,
+    });
+
+    if (lane.action === 'refuse') {
+      fail(`REFUSED: ${lane.reason}`);
       process.exit(1);
     }
-    await applyPlanViaStage(plan, flags, forceDescent);
-    return;
+    if (lane.action === 'ops') {
+      // Run credential-free in the ops Lambda. A void return = applied (or an internal refusal already
+      // exited). A returned escalate request = a read-disagreement this lane could not resolve; take
+      // it to the direct lane with the same announce→consent→resolve machinery (q2-escalate).
+      const outcome = await applyPlanViaStage(plan, flags);
+      if (!outcome) return;
+      dbSource = await escalateStageToDirect(outcome.reason, plan, planPath, flags.stage);
+    } else {
+      // escalate — the plan needs the direct lane (destructive / too-large). flags.stage stays set, so
+      // the direct path below runs the full stage-aware ceremony (approvers, the stage's snapshot lane).
+      dbSource = await escalateStageToDirect(lane.reason, plan, planPath, flags.stage);
+    }
   }
 
   // Losing data should be hard (decision 11): a destructive plan applies
-  // only confirmed (--confirm, always), snapshotted (automatic with --stage,
-  // named over a bare connection), and — when the stage declares an approver
-  // set — identity-approved (decision 12).
+  // only confirmed (--confirm, always), with a durable rollback point, and —
+  // when the stage declares an approver set — identity-approved (decision 12).
   const isDestructive = plan.destructive > 0;
   let verifyAuthority: (() => Promise<{ ok: true } | { ok: false; reason: string }>) | undefined;
+  let rollbackPoint: RollbackPoint | undefined;
   if (isDestructive) {
     const shape = `${plan.classification.drops} drop(s), ${plan.classification.narrowings} narrowing type change(s)`;
     if (flags.confirm !== 'true') {
-      fail(`This plan is DESTRUCTIVE — ${plan.destructive} statement(s) lose data (${shape}). Explicit confirmation is required, always: re-run with --confirm.`);
+      fail(destructiveConfirmRefusal(plan.destructive, shape));
       process.exit(1);
     }
-    // A DIRECT apply is operator-attested: the safety net is a backup the operator took and
-    // NAMES here, because this lane has no ops Lambda verifying one server-side.
-    //
-    // This used to end by offering "or drop --direct and let the credential-free --stage apply
-    // auto-verify your latest backup". THAT ADVICE CANNOT BE FOLLOWED. Auto-verification is
-    // real, but only for NON-destructive stage applies — and every plan reaching this block is
-    // destructive, so dropping --direct lands on the outright refusal above (the `--stage`
-    // destructive gate). It sent operators from a lane that works to one that refuses, and the
-    // refusal's own text then pointed them at --database-url. Two wrong signposts in a row are
-    // how a consumer ended up printing a privileged DSN to do something --direct already did.
-    //
-    // For a destructive plan there is exactly one remedy: take a safety point and name it.
-    if (!flags['snapshot-ref']) {
-      const stageArg = flags.stage ? ` --stage ${flags.stage}` : '';
-      const takeIt = `everystack db:backup${stageArg}`;
-      const lane = flags.stage
-        ? `${stageArg.trim()} --direct`
-        : '--database-url <url>';
-      fail(
-        `This plan is DESTRUCTIVE (${shape}) over a direct connection — the apply does not snapshot for you. `
-        + `Take a safety point (${takeIt}) and name it: everystack db:apply --plan ${planPath} ${lane} --confirm --snapshot-ref <id>. `
-        + 'A destructive plan always requires an attested --snapshot-ref; there is no lane that takes one for you.',
-      );
+
+    // The rollback point, CONFIRMED durable BEFORE the first destructive statement (Ty-ratified
+    // 2026-08-26 — the apply takes it and waits, reusing db:swap's ceremony). On --stage --direct
+    // the tool takes it for you (RDS physical snapshot by default, logical backup fallback) and
+    // waits until it exists — no --snapshot-ref dance. Over a bare --database-url the tool cannot
+    // take one, so it refuses unless you attest one (--snapshot-ref) or opt out (--snapshot none).
+    // The check that the database did not MOVE under the snapshot wait is executeApplyPlan's
+    // concurrency lock below: it re-reads live and refuses unless live == plan.from, AFTER this.
+    const venue: 'stage' | 'url' = flags.stage ? 'stage' : 'url';
+    const stageConfig = flags.stage ? await resolveConfig(flags.stage) : undefined;
+    // Captured here where dbSource is narrowed to the url variant (the stage lane returned above), so
+    // the bare-URL confirmLocal closure below can read it without re-narrowing a reassigned `let`.
+    const targetUrl = dbSource.url;
+    const decision = decideSnapshotMode({
+      venue,
+      instanceId: stageConfig?.databaseInstanceId,
+      snapshotRef: flags['snapshot-ref'],
+      requested: flags.snapshot as SnapshotModeRequest | undefined,
+      // Bare --database-url takes its OWN pg_dump -Fc rollback point (REVERSAL 1). The stage lane
+      // never needs it — it has physical/logical — so scope it to the url venue.
+      localDump: venue === 'url',
+    });
+    if (decision.mode === 'refuse') {
+      fail(`REFUSED: ${decision.reason}`);
       process.exit(1);
     }
-    if (flags.stage) {
-      const config = await resolveConfig(flags.stage);
-      const { parseAppName } = await import('../discover');
-      const appName = await parseAppName();
+    const confirmed = await confirmRollbackPoint(decision, {
+      // Resolve-else-take: an attested --snapshot-ref is only a rollback point once it fingerprint-
+      // verifies against plan.from. On a stage the CLI resolves the ref's backup manifest from the
+      // stage's backups bucket and runs the same gate the server used (verifySnapshotRef). Over a
+      // bare --database-url there is no bucket to resolve against, so no verifier is injected and the
+      // attested ref stays operator-trusted + lock-guarded (its own fp gate is sub-step 3's work).
+      ...(stageConfig
+        ? {
+            verifyAttested: async (ref: string) => {
+              if (!stageConfig.backupsBucket) {
+                return {
+                  ok: false as const,
+                  reason: `stage ${flags.stage} has no backupsBucket in its deployed config, so --snapshot-ref ${ref} cannot be verified. Add \`backupsBucket: backups.name\` to the sst.config outputs and redeploy, or let db:apply take a fresh snapshot (drop --snapshot-ref).`,
+                };
+              }
+              const manifest = await fetchBackupManifest(stageConfig.region, stageConfig.backupsBucket, ref);
+              const verdict = verifySnapshotRef({
+                manifest,
+                planFrom: plan.fromFingerprint,
+                targetStage: flags.stage,
+                now: new Date(),
+                freshnessWindowMs: SNAPSHOT_FRESHNESS_MS,
+              });
+              return verdict.ok
+                ? { ok: true as const, stampedFingerprint: manifest!.fingerprint }
+                : { ok: false as const, reason: verdict.reason };
+            },
+          }
+        : {}),
+      ...(stageConfig
+        ? stageConfirmDeps({
+            region: stageConfig.region,
+            instanceId: stageConfig.databaseInstanceId,
+            opsFn: opsFunction(stageConfig),
+            stage: flags.stage,
+            verb: 'apply',
+            log: info,
+            step,
+          })
+        : {
+            // Bare --database-url. physical/logical are unreachable here (decideSnapshotMode refuses
+            // them on this venue) — present and loud so a future routing change cannot fail silently.
+            // What this venue DOES take is its own local dump (mode 'local'): pg_dump -Fc to a file in
+            // the working directory, verified with pg_restore --list before any destructive statement.
+            confirmPhysical: async () => { throw new Error('a physical snapshot needs a stage; a bare --database-url cannot take one'); },
+            confirmLogical: async () => ({ ok: false as const, reason: 'a logical snapshot needs a stage; a bare --database-url cannot take one' }),
+            confirmLocal: () => confirmLocalDump({
+              url: targetUrl,
+              file: path.resolve(process.cwd(), `everystack-rollback-${utcStamp(new Date())}.dump`),
+            }),
+          }),
+      log: info,
+      warn,
+    });
+    if (!confirmed.ok) {
+      fail(`REFUSED: ${confirmed.reason} — nothing was applied.`);
+      process.exit(1);
+    }
+    rollbackPoint = confirmed.point;
+
+    if (stageConfig) {
       verifyAuthority = async () => {
         step(`Destructive authority: checking the approver set for stage ${flags.stage}...`);
-        const approvers = await readApproverParam(config.region, appName, flags.stage);
-        const identity = approvers === null ? null : await resolveCallerIdentity(config.region);
+        const { parseAppName } = await import('../discover');
+        const appName = await parseAppName();
+        const approvers = await readApproverParam(stageConfig.region, appName, flags.stage);
+        const identity = approvers === null ? null : await resolveCallerIdentity(stageConfig.region);
         const verdict = checkDestructiveAuthority({ approvers, identity });
         if (!verdict.ok) return verdict;
         if (verdict.reason === 'approved') {
@@ -383,9 +516,6 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
         }
         return { ok: true };
       };
-      warn(`DESTRUCTIVE direct apply — proceeding on ceremony: --confirm + attested snapshot ${flags['snapshot-ref']}.`);
-    } else {
-      warn(`DESTRUCTIVE apply over a bare connection — approver gating unavailable (no --stage), proceeding on ceremony: --confirm + attested snapshot ${flags['snapshot-ref']}.`);
     }
   }
 
@@ -394,9 +524,9 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
 
   try {
     info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
-    if (forceDescent !== undefined) {
-      warn(`DESCENT FORCED — the fast-forward rule is bypassed for this apply. Snapshot on record: ${forceDescent}.`);
-    }
+    // Set inside checkDescent when --attest-lineage-lost is honoured; read at write time so the
+    // waiver lands in the schema_log outcome (the descent decision runs before the apply writes).
+    let descentAttested: string | undefined;
     step('Verifying the target is where the plan started...');
     // The mutation lease: one operator mutates a database at a time. Acquired on this apply's
     // own session (the max:1 createUrlRunner) before any write; a second operator is refused
@@ -408,6 +538,22 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
       actor: process.env.USER ?? null,
       gitRef: currentGitRef() ?? plan.gitRef,
       ...(verifyAuthority ? { verifyAuthority } : {}),
+      // The rollback point must capture the state this plan STARTS from. A logical backup stamps
+      // the live fingerprint at dump time; if it does not equal plan.from, restoring it would not
+      // return the database to where the plan began — so refuse (the escape is re-plan, not a
+      // flag). A physical snapshot carries no stamp: it is fresh and the concurrency lock below
+      // proves live == plan.from, so temporal ordering is its coverage. `none` opted out.
+      ...(rollbackPoint?.stampedFingerprint
+        ? {
+            verifySnapshot: async ({ planFrom }: { planFrom: string }) =>
+              rollbackPoint!.stampedFingerprint === planFrom
+                ? { ok: true as const }
+                : {
+                    ok: false as const,
+                    reason: snapshotMovedRefusal(rollbackPoint!.ref!, rollbackPoint!.stampedFingerprint!, planFrom),
+                  },
+          }
+        : {}),
       // Re-verified here, not just at mint: a plan is an artifact with a lifetime, and a
       // foreign role granted between minting and applying would otherwise ride through.
       verifyAuthzBaseline: async ({ contract }) => {
@@ -421,37 +567,29 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
           ? { ok: true as const }
           : { ok: false as const, reason: baselineRefusal(stageName, violations) };
       },
-      ...(forceDescent === undefined ? {
-        verifyDescent: async (live: LiveState & { fingerprint: string }) => {
-          step('Descent: searching git for the commit that declares the target\'s state...');
-          const verdict = await verifyDescent(resolveModelsPath(flags.models), live, {});
-          switch (verdict.status) {
-            case 'ok':
-              info(`descent: ${verdict.commit.slice(0, 12)} declares the target's state and is an ancestor of HEAD — fast-forward.`);
-              return { ok: true };
-            case 'fresh-target':
-              info('descent: fresh target (no tables) — nothing to protect, bootstrapping.');
-              return { ok: true };
-            case 'no-git':
-              // A DESTRUCTIVE plan may not ride an accidental waiver: the fast-forward
-              // rule's verdict must never depend on which directory the operator ran
-              // from. Unverifiable + destructive ⇒ the waiver must be the deliberate
-              // ceremony (--force-descent <snapshot-ref> --confirm), not a warning.
-              if (plan.destructive > 0) {
-                return {
-                  ok: false,
-                  reason: 'descent: not a git checkout, and this plan is DESTRUCTIVE — the fast-forward rule cannot be verified here, so waive it deliberately: re-run with --force-descent <snapshot-ref> --confirm.',
-                };
-              }
-              warn('descent: not a git checkout — the fast-forward rule cannot be verified here.');
-              return { ok: true };
-            case 'diverged':
-            case 'drift':
-            case 'indeterminate':
-              return { ok: false, reason: verdict.reason };
-          }
-        },
-      } : {}),
+      dirty: worktreeDirty(resolveModelsPath(flags.models)),
+      descentNote: () => descentAttested,
+      checkDescent: async (live: LiveState & { fingerprint: string; ledger: DescentLedgerRow[] }) => {
+        step('Descent: proving the fast-forward rule against the schema_log ledger...');
+        const verdict = await proveDescent(resolveModelsPath(flags.models), live, live.ledger, {});
+        if (verdict.status === 'proven') {
+          info(`descent: proven via ${verdict.via} — ${verdict.commit.slice(0, 12)} is an ancestor of HEAD, fast-forward.`);
+        } else if (verdict.status === 'fresh-target') {
+          info('descent: fresh target (no tables) — nothing to protect, bootstrapping.');
+        } else if (verdict.status === 'no-git' && plan.destructive === 0) {
+          warn('descent: not a git checkout — the fast-forward rule cannot be verified here.');
+        }
+        const decision = decideDescentApply(verdict, {
+          ...(attestLineageLost ? { attestation: attestLineageLost } : {}),
+          destructive: plan.destructive > 0,
+          proveLineage: (sha) => proveLineageLost(sha, realLineageProbe(process.cwd())),
+        });
+        if (decision.ok && decision.attested) {
+          descentAttested = attestationNote(decision.attested);
+          warn(`DESCENT ATTESTED — ${descentAttested}. The declaring commit is proven gone from every ref; the fast-forward rule is waived for this apply and the waiver is recorded.`);
+        }
+        return decision.ok ? { ok: true } : { ok: false, reason: decision.reason };
+      },
       }),
     );