@everystack/cli 0.4.69 → 0.4.70

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

@@ -50,7 +50,8 @@ import { introspectSchema, type SchemaSnapshot } from '../schema-introspect';
 import { readStageStateTwice } from '../stage-read-consistency';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
 import { mintEdgePlan, planHash, buildPlanSummary } from '../edge-plan';
-import { verifyDescent } from '../git-descent';
+import { proveDescent } from '../git-descent';
+import { readDescentLedger } from '../apply-execute';
 import { planBackfills, readBackfillLog } from '../backfill';
 import { readSqlDirIfPresent } from './db-sync';
 import { currentGitRef } from '../state-apply';
@@ -277,25 +278,35 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     // The fast-forward rule, warn-only at mint time (db:apply enforces it):
     // a stale checkout mints a legal-looking plan whose edge REVERTS merged
     // work — say so on the review surface, where a human still reads it.
+    //
+    // Ledger-first, SYMMETRIC with db:apply — it must warn about exactly what apply will do.
+    // The old whole-history recompile warned "rebase first, will refuse" for
+    // the very strand apply now PROVES via the ledger and applies, telling the operator the
+    // opposite of what happens. proveDescent over the same ledger apply reads keeps them agreed.
     if (plan.statements.length > 0) {
-      const verdict = await verifyDescent(modelsPath, { snapshot, contract }, {});
-      // A switch, not an `if (diverged || drift)`. That form silently ignored every verdict
-      // it did not name, so `indeterminate` would have minted a plan with no warning at all
-      // and then been refused at apply time with no hint of why. Exhaustive here means a new
-      // verdict cannot be forgotten.
+      const ledger = await readDescentLedger(session);
+      const verdict = await proveDescent(modelsPath, { snapshot, contract }, ledger, {});
+      // A switch, not an `if (revert || drift)`. That form silently ignored every verdict it
+      // did not name, so a new one would mint a plan with no warning and then be refused at
+      // apply time with no hint of why. Exhaustive here means a new verdict cannot be forgotten.
       switch (verdict.status) {
-        case 'ok':
+        case 'proven':
         case 'fresh-target':
         case 'no-git':
           break;
-        case 'diverged':
+        case 'revert':
         case 'drift':
           warn(`descent: ${verdict.reason}`);
           warn('db:apply from this checkout will refuse this plan — rebase first, then re-mint.');
           break;
-        case 'indeterminate':
+        case 'unknown-commit':
+          // NOT "rebase first" — the checkout is fine, it is just missing the deploying commit.
+          warn(`descent: ${verdict.reason}`);
+          warn('db:apply from this checkout will refuse this plan until you fetch that commit — fetch, then re-mint.');
+          break;
+        case 'unverifiable':
           // NOT "rebase first" — nothing is wrong with the checkout or the database. The
-          // search failed, so the rule is unproven either way.
+          // search could not read an ancestor state, so the rule is unproven either way.
           warn(`descent: ${verdict.reason}`);
           warn('db:apply from this checkout will refuse this plan until that search completes — re-mint and try again.');
           break;

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

@@ -40,12 +40,11 @@ import { rewriteStatementLine, opensCopyData, closesCopyData } from '../schema-r
 import { resolveOperatorUrlViaStage } from '../direct-venue';
 import { withMutationLease, MutationLeaseError } from '../mutation-lease';
 import { resolveConfig, opsFunction, type CliConfig } from '../config';
-import { invokeAction, presignGet, createRdsSnapshot, describeRdsSnapshots } from '../aws';
-import { keyForArtifactId, metaKey, utcStamp } from '../backup';
-import { rdsSnapshotIdentifier } from '../rds-snapshot';
-import { pollTaskUntilStopped } from '../task-poll';
-import { decideSnapshotMode, confirmPhysicalSnapshot, interpretBackupPoll, type SnapshotModeRequest } from '../swap-snapshot';
-import { runStageBackup, stageBackupDeps } from '../stage-backup';
+import { invokeAction, presignGet } from '../aws';
+import { keyForArtifactId, metaKey } from '../backup';
+import { decideSnapshotMode, type SnapshotModeRequest } from '../swap-snapshot';
+import { confirmRollbackPoint } from '../rollback-point';
+import { stageConfirmDeps } from '../stage-rollback-deps';
 import { pgEnvFromUrl, pgKeepaliveConninfo } from './db';
 import { step, success, fail, warn, info } from '../output';
 
@@ -448,58 +447,32 @@ async function takePreSwapSnapshot(
   plan: Exclude<ReturnType<typeof decideSnapshotMode>, { mode: 'refuse' }>,
   ctx: { stage?: string; region?: string; opsFn?: string },
 ): Promise<void> {
-  if (plan.mode === 'attested') {
-    info(`pre-swap rollback point: ${plan.ref} (attested via --snapshot-ref — no new snapshot taken).`);
-    return;
-  }
-
-  if (plan.mode === 'none') {
-    warn('NO pre-swap snapshot (--snapshot none). If this swap lands bad data there is no rollback point — the retiring schema is dropped once verify passes.');
-    return;
-  }
-
-  if (plan.mode === 'physical') {
-    step(`Snapshotting the instance before the swap (RDS physical snapshot of ${plan.instanceId})...`);
-    const snapshotId = rdsSnapshotIdentifier(`${ctx.stage ?? 'swap'}-swap`, utcStamp(new Date()));
-    const region = ctx.region!;
-    const { id } = await confirmPhysicalSnapshot({
-      create: (sid) => createRdsSnapshot(region, plan.instanceId, sid),
-      describe: () => describeRdsSnapshots(region, plan.instanceId),
+  // The confirm ceremony is now shared with db:apply (rollback-point.ts) — one definition of
+  // "no destructive statement before a durable rollback point", two verbs. Swap keeps only its
+  // OWN wording: the restore-from advice, and the "swap was NOT applied, live is untouched"
+  // framing on a refusal.
+  const result = await confirmRollbackPoint(plan, {
+    ...stageConfirmDeps({
+      region: ctx.region!,
+      instanceId: plan.mode === 'physical' ? plan.instanceId : undefined,
+      opsFn: ctx.opsFn!,
+      stage: ctx.stage,
+      verb: 'swap',
       log: (m) => info(m),
-      sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
-      now: () => Date.now(),
-    }, { instanceId: plan.instanceId, snapshotId });
-    info(`rollback point CONFIRMED: RDS snapshot ${id} is available — restore the instance from it if this swap goes wrong.`);
-    return;
-  }
-
-  // Logical: dispatch the Task and WAIT. The dispatch returning is not the backup existing — that
-  // conflation is what let a pg_dump run concurrently with the restore it was supposed to precede.
-  step('Snapshotting the stage before the swap (db:backup — waiting for the dump to finish)...');
-  // The shared sandwich. A rollback point taken across a concurrent migration holds a schema that
-  // matches neither endpoint — restoring from it would not return the stage to where it was, which
-  // is the one thing a pre-swap snapshot has to guarantee. An unproven artifact fails the swap.
-  const backup = await runStageBackup({
-    ...stageBackupDeps({ region: ctx.region! }, ctx.opsFn!, ctx.stage, {
-      onStep: step,
-      onDispatch: (d: { id: string; runId: string }) => info(`backup ${d.id} dispatched (run ${d.runId}) — waiting for the task to stop before the restore starts.`),
+      step,
     }),
-    // Swap keeps its OWN reading of a finished poll: it is the only caller that can tell the
-    // operator to re-run with `--snapshot-ref <id>` once the dump lands, and each outcome needs
-    // different advice. The shared helper takes injected deps for exactly this.
-    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;
-      // Carry the stamp through, or this caller silently opts out of the image-skew check.
-      return { ok: true, stampedFingerprint: (poll as any).status?.result?.fingerprint as string | undefined };
-    },
+    log: (m) => info(m),
+    warn: (m) => warn(m),
   });
-  if (!backup.ok) {
-    throw new Error(`the pre-swap backup is not a usable rollback point, so the swap was NOT applied and live is untouched: ${backup.reason}`);
+
+  if (!result.ok) {
+    throw new Error(`the pre-swap rollback point could not be confirmed, so the swap was NOT applied and live is untouched: ${result.reason}`);
   }
-  if (backup.warning) warn(backup.warning);
-  info(`rollback point CONFIRMED: backup ${backup.id} complete — restore with db:restore --from ${backup.id} --confirm.`);
+  // Swap-specific restore advice on top of the shared confirmation.
+  const p = result.point;
+  if (p.mode === 'physical') info(`restore the instance from RDS snapshot ${p.ref} if this swap goes wrong.`);
+  else if (p.mode === 'logical') info(`restore with db:restore --from ${p.ref} --confirm if this swap goes wrong.`);
+  else if (p.mode === 'none') warn('the retiring schema is dropped once verify passes — there is no rollback point.');
 }
 
 export async function dbSwapCommand(flags: Record<string, string>): Promise<void> {

package/src/cli/derived-apply.ts

@@ -59,6 +59,15 @@ export const ENSURE_RECONCILER_SQL: string[] = [
   duration_ms integer,
   outcome text NOT NULL
 )`,
+  // The descent witness columns (apply-legibility Phase 1). Idempotent — legacy databases
+  // upgrade in place; their old rows read fp_version = NULL (descent skips them) and
+  // dirty = false (harmless, since a NULL fp_version already skips them).
+  //  - fp_version: the FINGERPRINT_VERSION a row's to_fingerprint was computed under, so the
+  //    fast-forward proof can recompute the live side under the ROW'S canon across a bump.
+  //  - dirty: the apply ran from a worktree whose models differed from HEAD, so its git_ref
+  //    does not declare what was applied — descent must ignore the row (like git_ref = NULL).
+  `ALTER TABLE everystack.schema_log ADD COLUMN IF NOT EXISTS fp_version integer`,
+  `ALTER TABLE everystack.schema_log ADD COLUMN IF NOT EXISTS dirty boolean NOT NULL DEFAULT false`,
 ];
 
 export interface RenderedReconcile {
@@ -555,12 +564,18 @@ export interface SchemaLogEntry {
   durationMs?: number;
   fromFingerprint?: string | null;
   toFingerprint?: string | null;
+  /** The FINGERPRINT_VERSION the fingerprints were computed under — the descent witness's canon. */
+  fpVersion?: number | null;
+  /** The apply ran from a dirty worktree (models differed from HEAD) — descent ignores such a row. */
+  dirty?: boolean;
 }
 
 export function renderSchemaLogInsert(entry: SchemaLogEntry): string {
   const duration = entry.durationMs === undefined ? 'NULL' : String(Math.round(entry.durationMs));
-  return `INSERT INTO everystack.schema_log (kind, actor, git_ref, plan_ref, from_fingerprint, to_fingerprint, sql, duration_ms, outcome)
-VALUES (${escapeLiteral(entry.kind)}, ${nullable(entry.actor)}, ${nullable(entry.gitRef)}, ${nullable(entry.planRef)}, ${nullable(entry.fromFingerprint)}, ${nullable(entry.toFingerprint)}, ${escapeLiteral(entry.sql)}, ${duration}, ${escapeLiteral(entry.outcome)})
+  const fpVersion = entry.fpVersion == null ? 'NULL' : String(Math.floor(entry.fpVersion));
+  const dirty = entry.dirty ? 'true' : 'false';
+  return `INSERT INTO everystack.schema_log (kind, actor, git_ref, plan_ref, from_fingerprint, to_fingerprint, sql, duration_ms, outcome, fp_version, dirty)
+VALUES (${escapeLiteral(entry.kind)}, ${nullable(entry.actor)}, ${nullable(entry.gitRef)}, ${nullable(entry.planRef)}, ${nullable(entry.fromFingerprint)}, ${nullable(entry.toFingerprint)}, ${escapeLiteral(entry.sql)}, ${duration}, ${escapeLiteral(entry.outcome)}, ${fpVersion}, ${dirty})
 RETURNING id`;
 }
 

package/src/cli/edge-plan.ts

@@ -37,6 +37,20 @@ import { compileTableRenames, compileTableMoves } from './schema-compile';
 
 export const PLAN_VERSION = 2;
 
+/**
+ * The db:apply WIRE CONTRACT between the CLI and the ops Lambda — distinct from PLAN_VERSION,
+ * which versions the plan ARTIFACT. This versions the invoke PAYLOAD (its keys) and the ops
+ * Lambda's enforcement of them: the descent/authority/snapshot verdicts the CLI computes and the
+ * gates the server runs from them. PLAN_VERSION can hold while this moves — a payload key added or
+ * a hook's meaning changed leaves the plan file identical but breaks a mismatched peer silently.
+ *
+ * BUMP RULE: increment on ANY change to the db:apply payload keys, the set of gates the server
+ * runs, or a gate's semantics. Both packages import THIS binding (the server from the cli it
+ * bundles), so a version skew is a hard, exact-equality refusal in both directions — never a
+ * silently dropped gate.
+ */
+export const APPLY_CONTRACT_VERSION = 1;
+
 /** Classification counts (brick 9, decision 11): destructive = drops + narrowings + strips. */
 export interface PlanClassification {
   /** Statements that positively ADD. Counted from a matcher, never `total - destructive` —