@everystack/cli 0.4.83 → 0.4.85

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.85] - 2026-09-16
+
+### Added
+
+- automate the version-drift check — a manual note is not a gate
+- add foreign keys in two steps, and check the rows before the DDL
+
+### Fixed
+
+- the two-step FK add's gate could OOM the database, and its record could go missing
+- db:plan --verbose actually expands the truncated change list
+
+## [0.4.84] - 2026-09-16
+
+_Internal changes only._
+
 ## [0.4.83] - 2026-09-16
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.83",
+  "version": "0.4.85",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -135,7 +135,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.4.17"
+    "@everystack/model": "0.4.18"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.4.0",
@@ -182,7 +182,7 @@
     "react": "19.2.0",
     "ts-jest": "29.4.9",
     "zod": "3.25.67",
-    "@everystack/server": "0.4.30"
+    "@everystack/server": "0.4.31"
   },
   "scripts": {
     "test": "jest",

package/src/cli/apply-execute.ts

@@ -57,6 +57,8 @@ import {
 import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog';
 import { fingerprintLive, FINGERPRINT_VERSION } from './schema-fingerprint';
 import { applyGeneratedStatements } from './state-apply';
+import { fkOrphanChecks, fkOrphanSql, fkOrphanRefusal, fkPreflightUnavailableRefusal, checkOrphanRowShape } from './fk-preflight';
+import { validationPendingReason } from './apply-refusals';
 import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply';
 import { checkPlanPrecondition, planHash, defaultAclHash, type EdgePlan } from './edge-plan';
 import type { DescentLedgerRow } from './git-descent';
@@ -140,7 +142,19 @@ export interface ApplyPlanOptions {
 }
 
 export interface ApplyPlanResult {
-  status: 'applied' | 'already-applied' | 'refused' | 'descent-refused' | 'authority-refused' | 'snapshot-refused' | 'authz-refused' | 'verify-failed';
+  status:
+    | 'applied'
+    | 'already-applied'
+    | 'refused'
+    | 'descent-refused'
+    | 'authority-refused'
+    | 'snapshot-refused'
+    | 'authz-refused'
+    /** Rows already in the table do not satisfy a foreign key this plan installs — nothing ran. */
+    | 'preflight-refused'
+    /** The edge COMMITTED; a post-commit `VALIDATE CONSTRAINT` did not pass. Not a rollback. */
+    | 'validation-pending'
+    | 'verify-failed';
   liveFingerprint: string;
   reason?: string;
   logId?: number;
@@ -359,6 +373,31 @@ export async function executeApplyPlan(
     }
   }
 
+  // The LAST gate before any DDL, and the only one that asks about DATA. A foreign key this plan
+  // installs is only installable if the rows already in the table satisfy it; PostgreSQL would
+  // answer that during the VALIDATE, one row at a time, with the lock already taken. Asked here,
+  // the answer arrives with a count and a sample and nothing has run. The snapshot is the one the
+  // lock was just computed from, so the question and the lock describe one instant.
+  const orphanChecks = fkOrphanChecks(plan.statements, before);
+  if (orphanChecks.length > 0) {
+    let refusal: string | null;
+    try {
+      const rows = (await runner(fkOrphanSql(orphanChecks))) as unknown;
+      // The read answers with exactly one row per key, zero orphans included. A short or
+      // missing answer is not "clean" — it is the gate not having run, and it goes down the
+      // same fail-closed path as a read that could not run at all.
+      checkOrphanRowShape(rows, orphanChecks.length);
+      refusal = fkOrphanRefusal(rows);
+    } catch (err: any) {
+      // Fail CLOSED: a check that could not run has not passed.
+      refusal = fkPreflightUnavailableRefusal(String(err?.message ?? err));
+    }
+    if (refusal) {
+      await recordRefusal(runner, plan, live, 'foreign key preflight', refusal, options);
+      return { status: 'preflight-refused', liveFingerprint: live, reason: refusal };
+    }
+  }
+
   const result = await applyGeneratedStatements(runner, plan.statements, {
     actor: options.actor,
     gitRef: options.gitRef ?? plan.gitRef,
@@ -367,6 +406,11 @@ export async function executeApplyPlan(
     fpVersion: FINGERPRINT_VERSION,
     dirty: options.dirty ?? false,
     now: options.now,
+    // The hash to stamp on the record written the moment the batch commits — the live state as
+    // it is THEN, with any new key installed and not yet proven. The plan's own endpoint is
+    // stamped below, after the last check has actually passed; predicting it here would put a
+    // state the database is not in onto the row every later apply descends from.
+    readFingerprint: async () => (await liveBaseFingerprint(session)).hash,
     ...(options.descentNote ? { descentNote: options.descentNote } : {}),
   });
 
@@ -377,6 +421,22 @@ export async function executeApplyPlan(
     await runner(renderSchemaLogFingerprintUpdate(result.logId, landed));
   }
 
+  // A key left NOT VALID is reported as ITSELF, before the endpoint comparison it would otherwise
+  // fail. The edge committed and the schema is correct; what is missing is the proof that the
+  // existing rows satisfy the key, and the fix is a data fix plus a re-plan (which will emit the
+  // VALIDATE alone). Reporting that as `verify-failed` would tell the operator to stop touching a
+  // database that is in a perfectly well-defined state.
+  if (result.pendingValidations.length > 0) {
+    return {
+      status: 'validation-pending',
+      liveFingerprint: landed,
+      // The next move follows the CAUSE: bad rows are a data fix, a check that was cut off by a
+      // clock is a lane change. See validationPendingReason.
+      reason: validationPendingReason(result.pendingValidations),
+      ...(result.logId !== undefined ? { logId: result.logId } : {}),
+    };
+  }
+
   // The full `to` equals the post-apply raw live hash, so verify-after compares them directly.
   if (landed !== plan.toFingerprint) {
     return {

package/src/cli/apply-refusals.ts

@@ -30,6 +30,72 @@ export function snapshotMovedRefusal(ref: string, captured: string, planFrom: st
   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.`;
 }
 
+/**
+ * VALIDATION PENDING: the edge committed and a post-commit `VALIDATE CONSTRAINT` did not pass.
+ * Neither class above — nothing was refused and nothing is in an unknown state — but it still has
+ * to name a next move, and WHICH move depends on why the check did not pass:
+ *
+ *   ORPHAN DATA  — the rows genuinely do not satisfy the key. The key is the truth and the data
+ *                  is wrong, so the fix is the DATA (db:exec), then re-plan; the next plan emits
+ *                  the VALIDATE alone.
+ *   CUT OFF      — a wall clock or a dropped connection ended the check before it answered.
+ *                  NOTHING is known about the rows. Sending that operator to go fix data is a
+ *                  wild goose chase; the move is to run the same check where no clock ends it,
+ *                  which is the direct lane.
+ *
+ * An error neither pattern recognises names BOTH moves rather than picking one — the same rule
+ * the rest of this file follows about guessing.
+ */
+export interface PendingValidationRecord {
+  /** The exact `VALIDATE CONSTRAINT` statement that did not pass. */
+  sql: string;
+  /** PostgreSQL's (or the driver's) message. */
+  error: string;
+}
+
+/** The rows really do violate the key: SQLSTATE 23503 and the message pg renders for it. */
+const ORPHAN_DATA = /violates foreign key constraint|is violated by some row|\b23503\b/i;
+/** The check never answered: a statement timeout, a lock timeout, or a connection that died. */
+const CUT_OFF = /timeout|canceling statement|terminat(ed|ing)|connection (closed|reset|refused|lost)|socket|ECONNRESET|EPIPE|\b(57014|55P03|08006|08003)\b/i;
+
+type PendingCause = 'data' | 'cut-off' | 'unknown';
+
+function causeOf(error: string): PendingCause {
+  if (ORPHAN_DATA.test(error)) return 'data';
+  if (CUT_OFF.test(error)) return 'cut-off';
+  return 'unknown';
+}
+
+export function validationPendingReason(pending: readonly PendingValidationRecord[]): string {
+  const causes = new Set(pending.map((p) => causeOf(p.error)));
+  const unknown = causes.has('unknown');
+
+  const moves: string[] = [];
+  if (causes.has('data') || unknown) {
+    moves.push(
+      'Rows already in the table do not satisfy the key: fix the data (everystack db:exec runs a '
+      + 'DML-only file against the target, credential-free), then db:plan and db:apply, which will '
+      + 'emit the VALIDATE alone.',
+    );
+  }
+  if (causes.has('cut-off') || unknown) {
+    moves.push(
+      'The check was cut off rather than answered (a timeout or a dropped connection), so nothing '
+      + 'is yet known about the rows: re-plan and apply again naming the direct lane '
+      + '(--stage <name> --direct), which runs with no wall clock over it.',
+    );
+  }
+  if (unknown) moves.unshift('The error below is not one this command recognises, so both moves are named:');
+
+  const names = pending.map((p) => p.sql.replace(/\s+/g, ' ').trim()).join('  |  ');
+  return [
+    `the edge applied, but ${pending.length} constraint(s) could not be validated against the rows `
+    + 'already in the table — they are installed and enforced on new writes, but unproven.',
+    ...moves,
+    `The check(s) still to pass: ${names}`,
+  ].join(' ');
+}
+
 // ---------------------------------------------------------------------------
 // The USER-FACING refusal message (apply-legibility Phase 3, p3-action-refusals).
 //
@@ -55,6 +121,8 @@ export type ApplyRefusalStatus =
   | 'authority-refused'
   | 'snapshot-refused'
   | 'authz-refused'
+  | 'preflight-refused'
+  | 'validation-pending'
   | 'verify-failed';
 
 /**
@@ -72,7 +140,13 @@ export function formatApplyRefusal(status: ApplyRefusalStatus, reason: string):
     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
+    case 'preflight-refused': // rows already in the table do not satisfy a foreign key — nothing ran
       return `REFUSED: ${reason}`;
+    case 'validation-pending':
+      // NOT a refusal and NOT a fault: the edge committed, and a constraint is installed but
+      // unproven against the rows that were already there. Its own word, because "refused" would
+      // say nothing ran and "verify failed" would say the database is in an unknown state.
+      return `Applied, validation PENDING: ${reason}`;
     case 'verify-failed':
       return `Verify FAILED: ${reason}`;
     default: {

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

@@ -227,11 +227,27 @@ async function runCatchUp(
   }
 }
 
+/**
+ * The statuses where the table and column state is COMMITTED on the target. Everything else
+ * either refused before any write or ended in a state nothing may be built on.
+ */
+const LANDED: ReadonlySet<ApplyPlanResult['status']> = new Set<ApplyPlanResult['status']>([
+  'applied',
+  'already-applied',
+  'validation-pending',
+]);
+
 /**
  * The chain: a plan that LANDED is followed by the catch-up, on the same target, always —
  * unless --state-only asked for the tables alone. A refusal or a verify fault chains nothing
  * (there is no applied state to build on); reportApplyResult renders those and exits.
  *
+ * `validation-pending` LANDED. It is not a refusal: the tables and columns committed and only a
+ * `VALIDATE CONSTRAINT` is outstanding. Functions, views, matviews and triggers do not depend on
+ * whether a foreign key has been PROVEN against the old rows — they compile and run identically
+ * either way — so skipping the catch-up there deployed half the checkout and said nothing about
+ * it, which is the exact incident this whole chain was built to end.
+ *
  * THE POST-WRITE CALLER, and the only reason `'throw'` exists: the table and column changes are
  * committed by the time this runs. Nothing downstream may end the process on its own, because
  * the operator is owed one sentence first — your changes are safe, here is what to rerun. So a
@@ -244,11 +260,11 @@ async function catchUpAfterApply(
   venue: CatchUpVenue,
   flags: Record<string, string>,
 ): Promise<CatchUpReport> {
-  if (result.status !== 'applied' && result.status !== 'already-applied') return { ok: true, statements: [] };
+  if (!LANDED.has(result.status)) return { ok: true, statements: [] };
   if (flags['state-only'] === 'true') return { ok: true, statements: [] };
-  const applied = result.status === 'applied'
-    ? classifyGeneratedStatements(plan.statements ?? []).executable.length
-    : 0;
+  const applied = result.status === 'already-applied'
+    ? 0
+    : classifyGeneratedStatements(plan.statements ?? []).executable.length;
   return runCatchUp(venue, flags, applied, 'throw');
 }
 

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

@@ -445,6 +445,7 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       target: stageName,
       stage: flags.stage ?? null,
       planPath: out === '-' ? null : out,
+      verbose,
     })) printLine(text);
 
     if (out !== '-') {

package/src/cli/derived-apply.ts

@@ -586,3 +586,20 @@ RETURNING id`;
 export function renderSchemaLogFingerprintUpdate(id: number, toFingerprint: string): string {
   return `UPDATE everystack.schema_log SET to_fingerprint = ${escapeLiteral(toFingerprint)} WHERE id = ${Math.floor(id)}`;
 }
+
+/**
+ * Finish a row that was written BEFORE the work it describes had finished.
+ *
+ * The `state apply` row goes in the moment the batch commits, so a death during the post-commit
+ * `VALIDATE CONSTRAINT` pass cannot leave committed DDL with nothing on the record. That means
+ * the row exists while its own outcome is still open — and when the pass ends, what changes is
+ * the outcome and the statement text, not the identity of the apply. So it is AMENDED. A second
+ * row would put two applies in a ledger the descent witness reads as a series of live states.
+ */
+export function renderSchemaLogCompletionUpdate(
+  id: number,
+  entry: { outcome: string; sql: string; durationMs?: number },
+): string {
+  const duration = entry.durationMs === undefined ? '' : `, duration_ms = ${Math.round(entry.durationMs)}`;
+  return `UPDATE everystack.schema_log SET outcome = ${escapeLiteral(entry.outcome)}, sql = ${escapeLiteral(entry.sql)}${duration} WHERE id = ${Math.floor(id)}`;
+}

package/src/cli/edge-plan.ts

@@ -64,8 +64,17 @@ export const PLAN_VERSION = 2;
  * the gate — not a false pass of the apply (it degrades to the post-DDL verify failure), but a
  * silently dropped gate the operator was told is in force. The BUMP RULE says a gate the server
  * runs is part of the contract, so the peers refuse until the stage is redeployed.
+ *
+ * v4 (the two-step foreign key): the server runs a NEW gate — the foreign-key orphan preflight,
+ * which counts the rows that would fail each key the plan installs or validates and refuses
+ * BEFORE any DDL — and the write path changed shape: `VALIDATE CONSTRAINT` is held out of the
+ * edge's transaction and run after it commits, so a failed check is a PENDING constraint rather
+ * than a rolled-back edge (`validation-pending`, a status a v3 ops Lambda cannot return). A v3
+ * stage would skip the preflight and run the VALIDATE inside the edge — a silently dropped gate
+ * and a different failure mode, both of which the BUMP RULE covers. Peers refuse until the stage
+ * is redeployed.
  */
-export const APPLY_CONTRACT_VERSION = 3;
+export const APPLY_CONTRACT_VERSION = 4;
 
 /** Classification counts (brick 9, decision 11): destructive = drops + narrowings + strips. */
 export interface PlanClassification {