@everystack/cli 0.4.84 → 0.4.85

package/CHANGELOG.md

@@ -4,11 +4,17 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
-## [Unreleased]
+## [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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.84",
+  "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>",
@@ -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 {

package/src/cli/fk-preflight.ts

@@ -0,0 +1,331 @@
+/**
+ * fk-preflight — the orphan check that runs BEFORE a foreign key's DDL, not during it.
+ *
+ * A foreign key is only installable if the rows already in the table satisfy it. PostgreSQL
+ * finds that out DURING `VALIDATE CONSTRAINT`, by raising on the first row that does not — one
+ * row, no count, no second offender, and (before the two-step split) after the apply had already
+ * taken an ACCESS EXCLUSIVE lock and scanned most of the table. The operator learned "there is a
+ * problem" at the worst possible moment and learned nothing else.
+ *
+ * So the apply asks the question first, the same way the declared-owner preflight in
+ * derived-apply does: ONE read that answers it for EVERY key the edge touches, so the refusal
+ * can name the COMPLETE list — how many rows, on which key, and what a few of them look like —
+ * and NOTHING has run when it is raised. Fix the data (`db:exec` is the credential-free lane for
+ * exactly that), re-plan, apply.
+ *
+ * WHICH KEYS NEED THE QUESTION ASKED. Only the ones where an existing row could already violate
+ * the constraint, which is a property of the LIVE database, not of the statement:
+ *
+ *   - a key on a table this edge CREATES         → no. The table has no rows yet, and it does
+ *                                                  not exist to be queried before the edge runs.
+ *   - a key on a column this edge ADDS           → no. Every existing row's value is NULL, which
+ *                                                  satisfies a foreign key (MATCH SIMPLE), and
+ *                                                  the column cannot be queried yet either.
+ *   - a key whose TARGET this edge creates       → no, and this one is a deliberate gap: the
+ *                                                  parent is empty until the edge runs, so the
+ *                                                  answer cannot be read beforehand. The VALIDATE
+ *                                                  then fails and the key stays NOT VALID — a
+ *                                                  pending state, not a rolled-back apply.
+ *   - a key already live but NOT VALID           → YES. This is the interrupted two-step add, and
+ *                                                  the rows it was never checked against are
+ *                                                  exactly what VALIDATE is about to scan.
+ *   - a key on an existing table and columns     → YES.
+ *
+ * An `ADD … NOT VALID` and the `VALIDATE` that follows it in the same edge are ONE question, not
+ * two — the key is the unit, not the statement.
+ *
+ * Pure: the parsing, the SQL, and the refusal text. The caller runs the query.
+ */
+
+import type { SchemaSnapshot, TableSchema, ForeignKey } from './schema-introspect';
+import { statementBody } from './sql-statement';
+import { quoteIdent, quoteQualified } from './pg-ident';
+import { escapeLiteral } from './derived-apply';
+
+/** One foreign key whose orphans must be counted before any DDL runs. */
+export interface FkOrphanCheck {
+  /** Schema-qualified, as the live snapshot spells it (`public.posts`). */
+  table: string;
+  /** The constraint name as it will exist when the VALIDATE runs. */
+  constraint: string;
+  columns: string[];
+  /** Schema-qualified target table. */
+  refTable: string;
+  refColumns: string[];
+}
+
+/** Strip quoting from one identifier token. */
+const unquote = (id: string): string => (/^".*"$/.test(id) ? id.slice(1, -1).replace(/""/g, '"') : id);
+
+/** `"public"."posts"` / `posts` / `public.posts` → `public.posts` (the snapshot's spelling). */
+export function normalizeTableName(raw: string): string {
+  const parts = raw.trim().replace(/;$/, '').match(/("(?:[^"]|"")*"|[^.\s]+)/g) ?? [];
+  const names = parts.map(unquote);
+  if (names.length === 0) return raw;
+  return names.length === 1 ? `public.${names[0]}` : names.slice(-2).join('.');
+}
+
+/** `("a", "b")` → `['a','b']`. */
+const parseColumns = (list: string): string[] =>
+  (list.replace(/^\(|\)$/g, '').match(/("(?:[^"]|"")*"|[^,\s]+)/g) ?? []).map(unquote);
+
+const CREATE_TABLE_RE = /^CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?((?:"(?:[^"]|"")*"|[A-Za-z_][\w$]*)(?:\.(?:"(?:[^"]|"")*"|[A-Za-z_][\w$]*))?)/i;
+const ADD_COLUMN_RE = /^ALTER\s+TABLE\s+(?:ONLY\s+)?(\S+)\s+ADD\s+COLUMN\s+(?:IF\s+NOT\s+EXISTS\s+)?("(?:[^"]|"")*"|[A-Za-z_][\w$]*)/i;
+const ADD_FK_RE = /^ALTER\s+TABLE\s+(?:ONLY\s+)?(\S+)\s+ADD\s+CONSTRAINT\s+("(?:[^"]|"")*"|[A-Za-z_][\w$]*)\s+FOREIGN\s+KEY\s*(\([^)]*\))\s*REFERENCES\s+((?:"(?:[^"]|"")*"|[^\s(]+)(?:\.(?:"(?:[^"]|"")*"|[^\s(]+))?)\s*(\([^)]*\))/i;
+const VALIDATE_RE = /^ALTER\s+TABLE\s+(?:ONLY\s+)?(\S+)\s+VALIDATE\s+CONSTRAINT\s+("(?:[^"]|"")*"|[A-Za-z_][\w$]*)/i;
+const RENAME_CONSTRAINT_RE = /^ALTER\s+TABLE\s+(?:ONLY\s+)?(\S+)\s+RENAME\s+CONSTRAINT\s+("(?:[^"]|"")*"|[A-Za-z_][\w$]*)\s+TO\s+("(?:[^"]|"")*"|[A-Za-z_][\w$]*)/i;
+
+/** The live table under its qualified name, or undefined. */
+const liveTable = (live: SchemaSnapshot, table: string): TableSchema | undefined =>
+  live.tables.find((t) => t.table === table);
+
+/**
+ * The foreign keys an edge is about to install or validate that could ALREADY be violated by
+ * rows in the live database — see the rules in the module docblock.
+ *
+ * `statements` is the edge exactly as it will execute (held drops and notices included; they are
+ * comments and match nothing). `live` is the target's state as the apply just read it — the same
+ * snapshot the concurrency lock was computed from, so the two cannot describe different databases.
+ */
+export function fkOrphanChecks(statements: readonly string[], live: SchemaSnapshot): FkOrphanCheck[] {
+  const bodies = statements.map(statementBody);
+
+  // Tables this edge creates: their rows do not exist yet, and neither do they.
+  const created = new Set<string>();
+  for (const body of bodies) {
+    const m = CREATE_TABLE_RE.exec(body);
+    if (m) created.add(normalizeTableName(m[1]));
+  }
+
+  // Columns this edge adds: every existing row holds NULL there, which satisfies the key.
+  const addedColumns = new Set<string>();
+  for (const body of bodies) {
+    const m = ADD_COLUMN_RE.exec(body);
+    if (m) addedColumns.add(`${normalizeTableName(m[1])}.${unquote(m[2])}`);
+  }
+
+  // A constraint renamed by this edge is validated under its NEW name, but it is LIVE under the
+  // old one — so the live lookup has to walk back through the rename.
+  const renamedFrom = new Map<string, string>();
+  for (const body of bodies) {
+    const m = RENAME_CONSTRAINT_RE.exec(body);
+    if (m) renamedFrom.set(`${normalizeTableName(m[1])}::${unquote(m[3])}`, unquote(m[2]));
+  }
+
+  const checks: FkOrphanCheck[] = [];
+  const seen = new Set<string>();
+
+  const push = (check: FkOrphanCheck): void => {
+    const key = `${check.table}::${check.constraint}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    checks.push(check);
+  };
+
+  for (const body of bodies) {
+    const add = ADD_FK_RE.exec(body);
+    if (add) {
+      const table = normalizeTableName(add[1]);
+      const columns = parseColumns(add[3]);
+      const target = liveTable(live, table);
+      // Not live yet, or one of its columns is not: nothing to scan, and nothing to scan it with.
+      if (!target) continue;
+      const liveColumns = new Set(target.columns.map((c) => c.name));
+      if (columns.some((c) => !liveColumns.has(c) || addedColumns.has(`${table}.${c}`))) continue;
+      const refTable = normalizeTableName(add[4]);
+      if (created.has(refTable) || !liveTable(live, refTable)) continue;
+      push({ table, constraint: unquote(add[2]), columns, refTable, refColumns: parseColumns(add[5]) });
+      continue;
+    }
+
+    const validate = VALIDATE_RE.exec(body);
+    if (validate) {
+      const table = normalizeTableName(validate[1]);
+      const constraint = unquote(validate[2]);
+      // Already covered when this edge also ADDs it — one key, one question.
+      if (seen.has(`${table}::${constraint}`)) continue;
+      const target = liveTable(live, table);
+      if (!target) continue;
+      const liveName = renamedFrom.get(`${table}::${constraint}`) ?? constraint;
+      const fk: ForeignKey | undefined = target.foreignKeys.find((f) => f.name === liveName);
+      // A VALIDATE naming a key the live database does not have is not a question this preflight
+      // can ask — it would be guessing at columns. The statement's own failure is the answer.
+      if (!fk) continue;
+      push({ table, constraint, columns: fk.columns, refTable: normalizeTableName(fk.refTable), refColumns: fk.refColumns });
+    }
+  }
+
+  return checks;
+}
+
+/** One row of {@link fkOrphanSql}'s result. */
+export interface FkOrphanRow {
+  constraint_name: unknown;
+  table_name: unknown;
+  columns: unknown;
+  ref_table: unknown;
+  orphans: unknown;
+  samples: unknown;
+}
+
+/**
+ * ONE read answering the question for every key at once — a first-failure refusal would make the
+ * operator fix one table, re-run, and discover the next.
+ *
+ * The scan is a real anti-join over the child table, which costs about what the VALIDATE it is
+ * protecting would cost. That is the price of knowing BEFORE the lock instead of during it, and
+ * it buys an exact count rather than pg's one-row-and-stop.
+ *
+ * NULLs are excluded, not counted: under MATCH SIMPLE (the only mode everystack emits) a row with
+ * a NULL in any key column satisfies the constraint. Counting them would refuse an apply that
+ * PostgreSQL would have accepted, which is the worse failure — a gate nobody can pass gets
+ * disabled.
+ *
+ * THE COUNT IS UNBOUNDED AND THE SAMPLE IS NOT, and the asymmetry is deliberate. The count is
+ * the full scan, which is the price of the answer and is paid either way. The SAMPLE is three
+ * values for the operator to recognise a row by — so it is taken from a `LIMIT 3` subquery and
+ * aggregated over those three rows alone. Aggregating the whole set and slicing it afterwards
+ * (`(array_agg(…))[1:3]`) builds the ENTIRE array in work memory first, which array_agg cannot
+ * spill to disk: on a table with millions of orphans the gate that exists to protect the
+ * database is the thing that takes it down.
+ */
+export function fkOrphanSql(checks: readonly FkOrphanCheck[]): string {
+  if (checks.length === 0) throw new Error('fkOrphanSql: no checks — the caller must skip the read');
+  return checks
+    .map((c) => {
+      // The columns come out of a REGEX over the ADD CONSTRAINT text. A short or empty parse is
+      // not a shape this read can paper over: joining the child's own column name against the
+      // parent errors on most schemas but SUCCEEDS on a parent that happens to carry the same
+      // name — and then counts zero, reporting a clean pass on a key nobody actually checked.
+      // Refuse, exactly as an empty check list is refused; the caller fails closed on the throw.
+      if (c.columns.length === 0) {
+        throw new Error(`fkOrphanSql: ${c.table}.${c.constraint} has no columns — the read cannot be built`);
+      }
+      if (c.refColumns.length !== c.columns.length) {
+        throw new Error(
+          `fkOrphanSql: ${c.table}.${c.constraint} names ${c.columns.length} column(s) but `
+          + `${c.refColumns.length} reference column(s) in ${c.refTable} — the read cannot be built `
+          + 'without guessing the join, and a guessed join can report a false clean.',
+        );
+      }
+      const child = quoteQualified(c.table);
+      const parent = quoteQualified(c.refTable);
+      const notNull = c.columns.map((col) => `c.${quoteIdent(col)} IS NOT NULL`).join(' AND ');
+      const join = c.columns.map((col, i) => `p.${quoteIdent(c.refColumns[i]!)} = c.${quoteIdent(col)}`).join(' AND ');
+      const where = (pad: string): string =>
+        `WHERE ${notNull}\n${pad}  AND NOT EXISTS (SELECT 1 FROM ${parent} p WHERE ${join})`;
+      // One printable value per offending row: a single-column key prints the value, a composite
+      // one prints the tuple. Capped, because a sample is for recognising the row, not for
+      // reading its contents into a refusal message.
+      const sample = c.columns.length === 1
+        ? `left(c.${quoteIdent(c.columns[0]!)}::text, 80)`
+        : `left(concat_ws(', ', ${c.columns.map((col) => `c.${quoteIdent(col)}::text`).join(', ')}), 80)`;
+      // Two scalar subqueries over no FROM: exactly ONE row per arm, at any orphan count —
+      // zero orphans gives 0 and a NULL sample array rather than no row at all. The caller
+      // asserts that shape (checkOrphanRowShape) and fails closed if it does not hold.
+      return `SELECT ${escapeLiteral(c.constraint)} AS constraint_name,
+       ${escapeLiteral(c.table)} AS table_name,
+       ${escapeLiteral(c.columns.join(', '))} AS columns,
+       ${escapeLiteral(c.refTable)} AS ref_table,
+       (SELECT count(*)::bigint
+          FROM ${child} c
+          ${where('          ')}) AS orphans,
+       (SELECT array_agg(s.sample)
+          FROM (SELECT ${sample} AS sample
+                  FROM ${child} c
+                  ${where('                  ')}
+                  ORDER BY 1
+                  LIMIT 3) s) AS samples`;
+    })
+    .join('\nUNION ALL\n');
+}
+
+/**
+ * The read returns exactly one row per key — see {@link fkOrphanSql}. Anything else is an answer
+ * nobody can read, and an unreadable answer is not "no orphans": it is the gate not running.
+ *
+ * FAIL CLOSED. A driver that hands back `[]` (a shape quirk, a transport that dropped the rows,
+ * a future change to the read) would otherwise walk straight through `fkOrphanRefusal`, which
+ * reports null — "every key is satisfied" — for an empty list. Asserted here, in the module that
+ * owns the read's shape, so the assertion cannot drift from the SQL it is about.
+ */
+export function checkOrphanRowShape(rows: unknown, expected: number): asserts rows is FkOrphanRow[] {
+  const got = Array.isArray(rows) ? rows.length : null;
+  if (got === expected) return;
+  throw new Error(
+    `the foreign-key row check answered with ${got === null ? 'something that is not a row set' : `${got} row(s)`} `
+    + `for ${expected} key(s) — the read produces exactly one row per key, so this answer cannot be read.`,
+  );
+}
+
+/**
+ * The orphan count as a number, or a THROW.
+ *
+ * It used to coerce null / unreadable text to 0, which is the answer "this key is satisfied" —
+ * the single most dangerous default in this module. `0` is a finding; `null` is a missing
+ * answer, and the two must never be spelled the same way. The caller turns the throw into the
+ * fail-closed refusal an unreachable database gets.
+ */
+const toCount = (v: unknown, where: string): number => {
+  if (v === null || v === undefined) throw new Error(`the orphan count for ${where} could not be read (it came back empty).`);
+  if (typeof v === 'object') throw new Error(`the orphan count for ${where} could not be read (unexpected shape).`);
+  if (typeof v === 'string' && v.trim() === '') throw new Error(`the orphan count for ${where} could not be read (it came back blank).`);
+  const n = typeof v === 'bigint' ? Number(v) : Number(v);
+  if (!Number.isFinite(n)) throw new Error(`the orphan count for ${where} could not be read (got ${JSON.stringify(String(v))}).`);
+  return n;
+};
+
+const toSamples = (v: unknown): string[] =>
+  Array.isArray(v) ? v.filter((s) => s != null).map((s) => String(s)) : [];
+
+/**
+ * The refusal when the read itself could not run (no privilege on a referenced table, a lock
+ * timeout, a dropped connection).
+ *
+ * FAIL CLOSED, the same rule the reconciler applies to grants it cannot see: a gate that did not
+ * run has not passed, and an apply that proceeds on an unanswered question is exactly the
+ * mid-VALIDATE surprise this preflight exists to remove. Nothing has run when this is raised.
+ */
+export function fkPreflightUnavailableRefusal(error: string): string {
+  return [
+    `the foreign-key row check could not run against this target — refused before any DDL, because a check that did not run has not passed.`,
+    `  ${error}`,
+    `Grant the applying role SELECT on the tables the keys join, or run the apply from a role that has it, then re-plan and apply.`,
+  ].join('\n');
+}
+
+/**
+ * The refusal text, or null when every key's rows already satisfy it.
+ *
+ * It names the COUNT and a SAMPLE per key, because those are the two things the operator needs
+ * and neither is in PostgreSQL's own error: how much work the fix is, and what the broken rows
+ * look like. The fix is data, so the escape is a data fix and a re-plan — never a flag. There is
+ * deliberately no `--force`: an unsatisfiable foreign key is not an intent someone can attest to.
+ *
+ * THROWS when a row's count cannot be read — see {@link toCount}. `null` returned from here means
+ * "asked and satisfied", so an unreadable count must not be able to produce it.
+ */
+export function fkOrphanRefusal(rows: readonly FkOrphanRow[]): string | null {
+  const where = (r: FkOrphanRow): string => `${String(r.table_name)}.${String(r.constraint_name)}`;
+  const counted = rows.map((r) => ({ row: r, count: toCount(r.orphans, where(r)) }));
+  const offenders = counted.filter((c) => c.count > 0);
+  if (offenders.length === 0) return null;
+
+  const lines = [
+    `${offenders.length} foreign key(s) cannot be validated — rows already in the table do not satisfy them. Refused before any DDL, so nothing is half-applied.`,
+    `Fix the data first (everystack db:exec runs a DML-only file against the target, credential-free), then re-plan and apply.`,
+  ];
+  for (const { row, count } of offenders) {
+    const samples = toSamples(row.samples);
+    lines.push(
+      `  ORPHANED ROWS  ${String(row.table_name)}.${String(row.constraint_name)}: ${count} row(s) hold a value in (${String(row.columns)}) with no matching row in ${String(row.ref_table)}.`,
+    );
+    if (samples.length > 0) {
+      lines.push(`      sample value(s): ${samples.join(', ')}${count > samples.length ? ', …' : ''}`);
+    }
+    lines.push(
+      `      the rows:  SELECT * FROM ${row.table_name} c WHERE NOT EXISTS (SELECT 1 FROM ${row.ref_table} p WHERE p.<key> = c.<fk>);`,
+    );
+  }
+  return lines.join('\n');
+}