@everystack/cli 0.4.84 → 0.4.86

package/CHANGELOG.md

@@ -4,11 +4,28 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
-## [Unreleased]
+## [0.4.86] - 2026-09-16
+
+### Added
+
+- validate: false on a foreign key, and a per-key apply preflight
+
+### Fixed
+
+- non-blocking validation-pending was blind to real anomalies, and its receipt overstated what ran
+- bump APPLY_CONTRACT_VERSION for the client-side exit-code field, close a sibling overstatement bug, prove the producer side
+
+## [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.86",
   "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.18"
+    "@everystack/model": "0.4.19"
   },
   "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,16 @@ import {
 import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog';
 import { fingerprintLive, FINGERPRINT_VERSION } from './schema-fingerprint';
 import { applyGeneratedStatements } from './state-apply';
+import {
+  fkOrphanChecks,
+  fkOrphanSql,
+  fkOrphanFindings,
+  withheldValidations,
+  fkPreflightUnavailableRefusal,
+  checkOrphanRowShape,
+  type FkOrphanFinding,
+} from './fk-preflight';
+import { validationPendingReason, pendingValidationsAreSafe } 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,10 +150,57 @@ 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'
+    /**
+     * The foreign-key row check itself could not RUN — no privilege, a lock timeout, a dropped
+     * connection. Nothing ran: a check that did not run has not passed.
+     *
+     * It is no longer what "some rows do not satisfy a key" produces. That is a per-key finding
+     * now: the offending key's `VALIDATE` is withheld and the rest of the edge commits as
+     * `validation-pending`. Refusing a whole edge — unrelated grants, unrelated clean keys —
+     * over legacy rows nobody was changing was the defect, not the safety.
+     */
+    | 'preflight-refused'
+    /**
+     * The edge COMMITTED and at least one `VALIDATE CONSTRAINT` is outstanding — because it
+     * failed, or because the row check counted the offenders first and it was withheld. Not a
+     * rollback, in either case.
+     */
+    | 'validation-pending'
+    | 'verify-failed';
   liveFingerprint: string;
   reason?: string;
   logId?: number;
+  /**
+   * The keys the row check found orphans on, if any — data, for the caller's advisory (see
+   * fk-orphan-advisory). Present on the paths that got as far as running the check, empty
+   * otherwise. Crosses the ops-Lambda wire with the rest of the result.
+   */
+  fkOrphans?: FkOrphanFinding[];
+  /**
+   * Only present when `status` is `'validation-pending'`. True iff every outstanding key's cause
+   * is understood to be the data (withheld by the preflight, or a live failure with the ordinary
+   * orphan-row error) — never a check that was cut off or failed for an unrecognised reason. The
+   * CLI reports the safe case as a non-blocking success (the whole point of this status) and the
+   * unsafe case exactly like any other refusal, exit code included — a real operational anomaly
+   * must still reach automation gating on this command's exit status.
+   */
+  pendingIsSafe?: boolean;
+  /**
+   * Only present when `status` is `'validation-pending'`. The exact statement text of every
+   * `VALIDATE CONSTRAINT` that did not land — withheld before it ran, or attempted and failed —
+   * so a receipt built from `plan.statements` (which is never rewritten; see below) can exclude
+   * them. Without this, a receipt naively re-derived from the full plan reports a withheld or
+   * failed VALIDATE as an applied change, which it never was.
+   */
+  unappliedStatements?: string[];
 }
 
 /**
@@ -359,7 +416,45 @@ export async function executeApplyPlan(
     }
   }
 
-  const result = await applyGeneratedStatements(runner, plan.statements, {
+  // The LAST step before any DDL, and the only one that asks about DATA. A foreign key this plan
+  // asks to be VALIDATED can only be validated 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 an exact count and a sample. The snapshot is the
+  // one the lock was just computed from, so the question and the lock describe one instant.
+  //
+  // WHAT THE ANSWER DOES, and this is the fix. It used to REFUSE the whole edge if any key had
+  // one orphan — the unrelated grants, the clean keys, everything, held behind a data audit of
+  // rows nobody was touching. Now the answer is read PER KEY: the offending key's `VALIDATE` is
+  // withheld (the key is still installed by the batch, NOT VALID, enforced on every new write),
+  // recorded as a pending validation, and the rest of the edge commits. The apply's outcome is
+  // `validation-pending`, which already means exactly this.
+  //
+  // TWO THINGS STILL REFUSE, and only these two: the check could not RUN, and the read answered
+  // in a shape nobody can read. Both are the gate not having run, which is not the same as
+  // passing, so both fail closed with nothing applied.
+  const orphanChecks = fkOrphanChecks(plan.statements, before);
+  let orphans: FkOrphanFinding[] = [];
+  if (orphanChecks.length > 0) {
+    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.
+      checkOrphanRowShape(rows, orphanChecks.length);
+      orphans = fkOrphanFindings(rows);
+    } catch (err: any) {
+      const refusal = fkPreflightUnavailableRefusal(String(err?.message ?? err));
+      await recordRefusal(runner, plan, live, 'foreign key preflight', refusal, options);
+      return { status: 'preflight-refused', liveFingerprint: live, reason: refusal, fkOrphans: [] };
+    }
+  }
+
+  // The edge minus the checks whose answer is already known. `plan.statements` itself is never
+  // rewritten — the plan is an artifact under a content hash, and `planHash(plan)` below has to
+  // keep naming the file the operator reviewed.
+  const { statements: toRun, withheld } = withheldValidations(plan.statements, orphans);
+
+  const result = await applyGeneratedStatements(runner, toRun, {
+    ...(withheld.length > 0 ? { skippedValidations: withheld } : {}),
     actor: options.actor,
     gitRef: options.gitRef ?? plan.gitRef,
     planRef: planHash(plan),
@@ -367,6 +462,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 +477,25 @@ 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 } : {}),
+      fkOrphans: orphans,
+      pendingIsSafe: pendingValidationsAreSafe(result.pendingValidations),
+      unappliedStatements: result.pendingValidations.map((p) => p.sql),
+    };
+  }
+
   // The full `to` equals the post-apply raw live hash, so verify-after compares them directly.
   if (landed !== plan.toFingerprint) {
     return {
@@ -384,12 +503,14 @@ export async function executeApplyPlan(
       liveFingerprint: landed,
       reason: `applied, but the target landed on ${landed.slice(0, 12)} — the plan predicted ${plan.toFingerprint.slice(0, 12)}. Investigate before touching this database again (db:fingerprint, db:generate).`,
       ...(result.logId !== undefined ? { logId: result.logId } : {}),
+      fkOrphans: orphans,
     };
   }
   return {
     status: 'applied',
     liveFingerprint: landed,
     ...(result.logId !== undefined ? { logId: result.logId } : {}),
+    fkOrphans: orphans,
   };
 }
 

package/src/cli/apply-refusals.ts

@@ -30,6 +30,110 @@ 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` is outstanding.
+ * 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 has not passed:
+ *
+ *   WITHHELD     — the row preflight counted the offending rows BEFORE any DDL, so the check was
+ *                  never attempted and the rest of the edge committed around it. The rows are the
+ *                  known cause, so this is the ORPHAN DATA move with no guessing involved.
+ *   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, or was never attempted. */
+  sql: string;
+  /** PostgreSQL's (or the driver's) message — or why the check was withheld. */
+  error: string;
+  /**
+   * The check was WITHHELD by the row preflight, never run. A structural flag rather than one
+   * more regex, because the text it would be matched against is text this CLI wrote itself: a
+   * pattern over our own message is a pattern that breaks the next time somebody rewords it.
+   */
+  skipped?: boolean;
+}
+
+/** 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(pending: PendingValidationRecord): PendingCause {
+  // A withheld check is the ONE case where the cause is known rather than inferred: the
+  // preflight counted the rows itself. No pattern is consulted.
+  if (pending.skipped === true) return 'data';
+  if (ORPHAN_DATA.test(pending.error)) return 'data';
+  if (CUT_OFF.test(pending.error)) return 'cut-off';
+  return 'unknown';
+}
+
+/**
+ * True iff every outstanding key's cause is the DATA — withheld by the preflight, or a live
+ * `VALIDATE` that failed with the ordinary orphan-row error. False the moment any cause is CUT
+ * OFF or UNKNOWN: a check that did not answer, or failed for a reason this command does not
+ * recognise, is a real operational anomaly, not the known, harmless fact this status otherwise
+ * describes — the caller must not report the two the same way (a non-blocking success either
+ * way would swallow a race condition or an infra hiccup from any automation gating on exit code).
+ */
+export function pendingValidationsAreSafe(pending: readonly PendingValidationRecord[]): boolean {
+  return pending.every((p) => causeOf(p) === 'data');
+}
+
+export function validationPendingReason(pending: readonly PendingValidationRecord[]): string {
+  const causes = new Set(pending.map(causeOf));
+  const unknown = causes.has('unknown');
+  const withheld = pending.filter((p) => p.skipped === true).length;
+
+  const moves: string[] = [];
+  if (withheld > 0) {
+    moves.push(
+      `${withheld} of them ${withheld === 1 ? 'was' : 'were'} never attempted: the row check counted the `
+      + 'offending rows before any DDL ran, so the apply skipped that scan and committed everything '
+      + 'else in the edge. Declare `validate: false` on the reference to keep the key enforced '
+      + 'forward and stop being asked.',
+    );
+  }
+  // Named for BOTH a withheld key and one that ran and failed with the ordinary orphan-row error
+  // — deliberately, not a duplicate of the withheld move above: they are two DIFFERENT valid
+  // resolutions (accept it forever vs. clean the data and re-plan), not two descriptions of one
+  // fact, so an operator choosing between them is owed both options in the same message.
+  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 +159,8 @@ export type ApplyRefusalStatus =
   | 'authority-refused'
   | 'snapshot-refused'
   | 'authz-refused'
+  | 'preflight-refused'
+  | 'validation-pending'
   | 'verify-failed';
 
 /**
@@ -72,7 +178,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': // the foreign-key row check could not RUN — nothing ran (orphaned rows no longer come here)
       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

@@ -30,6 +30,7 @@
  */
 
 import fs from 'node:fs/promises';
+import type { ModelDescriptor } from '@everystack/model';
 import { type QueryRunner } from '../authz-contract';
 import { currentGitRef, worktreeDirty, classifyGeneratedStatements, classifyDestructive } from '../state-apply';
 import { planHash, PLAN_VERSION, APPLY_CONTRACT_VERSION, declaredGranteesOf, type EdgePlan } from '../edge-plan';
@@ -73,6 +74,7 @@ import { resolveOperatorUrlViaStage } from '../direct-venue';
 import { withMutationLease, MutationLeaseError } from '../mutation-lease';
 import { readStageStateTwice } from '../stage-read-consistency';
 import { renderApplyReceipt, renderCatchUpFailure } from '../plain-output';
+import { renderFkOrphanAdvisory, ownershipColumns } from '../fk-orphan-advisory';
 import { catchUpDerived, type CatchUpVenue } from '../derived-catchup';
 import { buildReconcileReport } from './db-reconcile';
 import { step, success, fail, info, warn, line as printLine } from '../output';
@@ -110,12 +112,27 @@ export function reportApplyResult(
      * the lesser evil against guessing, and the gate that actually decides already ran.
      */
     declaredGrantees?: ReadonlySet<string>;
+    /**
+     * The models, for the advisory's row-security cross-reference. Absent means the barrel could
+     * not be read — the notice then prints without the escalation heading rather than not at all.
+     */
+    models?: readonly ModelDescriptor[];
   } = {},
 ): void {
   // What the function/view catch-up ran on the same target. It joins the receipt's own change
   // list — one command, one list, one count — so a caught-up view is never a second report the
   // reader has to reconcile with the first.
   const catchUp = opts.catchUp ?? [];
+
+  // The recurring notice about keys that stay unproven — BEFORE the outcome, at every verbosity,
+  // on every status that got as far as running the row check. It blocks nothing and it never
+  // proposes a row change; it is the debt this apply committed around, stated out loud. Printed
+  // here, in the one place both the stage lane and the direct lane converge.
+  for (const line of renderFkOrphanAdvisory(
+    result.fkOrphans ?? [],
+    ownershipColumns(opts.models ?? []),
+    { verbose: opts.verbose === true },
+  )) warn(line);
   switch (result.status) {
     case 'already-applied':
       if (opts.verbose) success(`Already at ${plan.toFingerprint.slice(0, 12)} — nothing to do (idempotent re-apply).`);
@@ -149,11 +166,47 @@ export function reportApplyResult(
       success(lines[lines.length - 1]);
       return;
     }
+    case 'validation-pending': {
+      // NOT every validation-pending outcome is safe to treat as a success. `pendingIsSafe` is
+      // false the moment any outstanding key's cause is a check that was cut off or failed for a
+      // reason this command does not recognise — a real operational anomaly, not the withheld-
+      // by-design case this status otherwise describes. That still exits non-zero, exactly like
+      // any other refusal: a CI pipeline gating a release on this command's exit code must see it.
+      if (result.pendingIsSafe !== true) {
+        fail(formatApplyRefusal(result.status, result.reason ?? ''));
+        process.exit(1);
+      }
+      // LANDED, not refused: the table and column changes are committed (see the LANDED set
+      // below) — only a VALIDATE CONSTRAINT is outstanding on keys the preflight already
+      // withheld. Exiting non-zero here would tell a CI pipeline gating on this command's exit
+      // code that the apply FAILED, when nothing did: the grant, the clean FKs, everything else
+      // landed exactly as planned. That false failure is the whole reason this status exists —
+      // undoing it with a non-zero exit here would silently reintroduce the block this feature
+      // was built to remove. The receipt below is the same one `applied` prints, minus every
+      // statement `unappliedStatements` names — a withheld or failed VALIDATE never ran, so
+      // `plan.statements` (still the full, un-rewritten plan) must not be classified as-is or
+      // it reads as an applied change that never happened. The pending notice rode in already,
+      // via renderFkOrphanAdvisory above.
+      if (opts.verbose) {
+        success(`Applied, validation PENDING — the target is at ${result.liveFingerprint.slice(0, 12)}. ${formatApplyRefusal(result.status, result.reason ?? '')}`);
+        return;
+      }
+      const unapplied = new Set(result.unappliedStatements ?? []);
+      const executable = classifyGeneratedStatements((plan.statements ?? []).filter((s) => !unapplied.has(s))).executable;
+      const { drops, narrowings, strips } = classifyDestructive(executable, {
+        ...(opts.declaredGrantees ? { declaredGrantees: opts.declaredGrantees } : {}),
+      });
+      const lines = renderApplyReceipt({ executable, destructive: [...drops, ...narrowings, ...strips], catchUp });
+      for (const text of lines.slice(0, -1)) printLine(text);
+      success(lines[lines.length - 1]);
+      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.
+      // exactly ApplyRefusalStatus minus 'validation-pending', so a future status that is
+      // neither success, pending, 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);
   }
@@ -227,11 +280,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 +313,14 @@ 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;
+  // Same exclusion the receipt applies (reportApplyResult): a withheld or failed VALIDATE never
+  // ran, so it must not inflate the count a catch-up FAILURE report names as already safe.
+  const unapplied = new Set(result.unappliedStatements ?? []);
+  const applied = result.status === 'already-applied'
+    ? 0
+    : classifyGeneratedStatements((plan.statements ?? []).filter((s) => !unapplied.has(s))).executable.length;
   return runCatchUp(venue, flags, applied, 'throw');
 }
 
@@ -283,6 +355,27 @@ async function declaredGranteesForReceipt(
   }
 }
 
+/**
+ * The models, for the orphan advisory's row-security cross-reference — and ONLY when there is
+ * something to cross-reference, so a clean apply never pays to load a barrel.
+ *
+ * Silently best-effort, unlike its sibling above. The advisory's own lines are complete without
+ * it (the generic heading, the counts, the samples); what is missing is the escalation to the
+ * row-security heading. Warning about a degraded sub-heading, next to a notice that is itself
+ * advisory, would be noise about noise.
+ */
+async function modelsForAdvisory(
+  result: ApplyPlanResult,
+  flags: Record<string, string>,
+): Promise<readonly ModelDescriptor[] | undefined> {
+  if (!result.fkOrphans?.length) return undefined;
+  try {
+    return await loadModels(resolveModelsPath(flags.models));
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Print a failed catch-up and exit: the report line, then the cause as it was written.
  *
@@ -547,10 +640,12 @@ async function applyPlanViaStage(
   const catchUp = await catchUpAfterApply(landedResult!, plan, { kind: 'stage', stage: flags.stage }, flags);
   exitOnCatchUpFailure(catchUp);
   const declaredGrantees = await declaredGranteesForReceipt(plan, flags);
+  const advisoryModels = await modelsForAdvisory(landedResult!, flags);
   reportApplyResult(landedResult!, plan, {
     verbose: flags.verbose === 'true',
     catchUp: catchUp.statements,
     ...(declaredGrantees ? { declaredGrantees } : {}),
+    ...(advisoryModels ? { models: advisoryModels } : {}),
   });
 }
 
@@ -1049,9 +1144,11 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
 
   exitOnCatchUpFailure(catchUp);
   const declaredGrantees = await declaredGranteesForReceipt(plan, flags);
+  const advisoryModels = await modelsForAdvisory(landed!, flags);
   reportApplyResult(landed!, plan, {
     verbose: flags.verbose === 'true',
     catchUp: catchUp.statements,
     ...(declaredGrantees ? { declaredGrantees } : {}),
+    ...(advisoryModels ? { models: advisoryModels } : {}),
   });
 }

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

@@ -71,6 +71,8 @@ import { alterTypeStatementTargets, findAlterTypeDependents, renderAlterTypeRefu
 import { compileTableContract } from '../authz-compile';
 import { reportPipelineLastRun } from './pipeline-run';
 import { renderPlanReport } from '../plain-output';
+import { fkOrphanChecks, fkOrphanSql, fkOrphanFindings, checkOrphanRowShape } from '../fk-preflight';
+import { renderFkOrphanAdvisory, ownershipColumns } from '../fk-orphan-advisory';
 import { step, success, fail, info, warn, line as printLine, reserveStdoutForData } from '../output';
 
 /**
@@ -389,6 +391,33 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       else if (verbose) info(line);
     }
 
+    // WHICH foreign keys this plan would ask to be PROVEN, and whether the rows can prove them.
+    //
+    // db:plan asks now so the review surface carries it: an operator reading the plan learns
+    // that N keys will stay NOT VALID BEFORE they apply, rather than from the apply's outcome.
+    // It is the same read the apply runs (one anti-join per key), against the same snapshot the
+    // fingerprint was taken from.
+    //
+    // IT NEVER BLOCKS, and a read that fails costs the plan nothing: minting is read-only, the
+    // plan file is already written, and the apply asks the question again with the answer that
+    // actually decides anything. A failure here is one line, not an exit.
+    //
+    // NONE OF IT IS IN THE PLAN FILE. Row counts go stale between minting and applying, and a
+    // plan is a content-addressed artifact that must not assert something it cannot still be
+    // true days later.
+    const orphanChecks = fkOrphanChecks(plan.statements, snapshot);
+    if (orphanChecks.length > 0) {
+      try {
+        const rows = (await runner(fkOrphanSql(orphanChecks))) as unknown;
+        checkOrphanRowShape(rows, orphanChecks.length);
+        for (const text of renderFkOrphanAdvisory(fkOrphanFindings(rows), ownershipColumns(models), { verbose })) {
+          warn(text);
+        }
+      } catch (err: any) {
+        warn(`the foreign-key row check could not run against this target (${err?.message ?? err}) — the plan is unaffected, but it cannot say here whether ${orphanChecks.length} key(s) will validate. db:apply asks again and fails closed if it still cannot.`);
+      }
+    }
+
     // 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.
@@ -445,6 +474,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)}`;
+}