@everystack/cli 0.4.85 → 0.4.86

package/CHANGELOG.md

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

package/package.json

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

package/src/cli/apply-execute.ts

@@ -57,8 +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, fkOrphanRefusal, fkPreflightUnavailableRefusal, checkOrphanRowShape } from './fk-preflight';
-import { validationPendingReason } from './apply-refusals';
+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';
@@ -150,14 +158,49 @@ export interface ApplyPlanResult {
     | 'authority-refused'
     | 'snapshot-refused'
     | 'authz-refused'
-    /** Rows already in the table do not satisfy a foreign key this plan installs — nothing ran. */
+    /**
+     * 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; a post-commit `VALIDATE CONSTRAINT` did not pass. Not a rollback. */
+    /**
+     * 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[];
 }
 
 /**
@@ -373,32 +416,45 @@ 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.
+  // 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) {
-    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.
+      // missing answer is not "clean" — it is the gate not having run.
       checkOrphanRowShape(rows, orphanChecks.length);
-      refusal = fkOrphanRefusal(rows);
+      orphans = fkOrphanFindings(rows);
     } catch (err: any) {
-      // Fail CLOSED: a check that could not run has not passed.
-      refusal = fkPreflightUnavailableRefusal(String(err?.message ?? err));
-    }
-    if (refusal) {
+      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 };
+      return { status: 'preflight-refused', liveFingerprint: live, reason: refusal, fkOrphans: [] };
     }
   }
 
-  const result = await applyGeneratedStatements(runner, plan.statements, {
+  // 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),
@@ -434,6 +490,9 @@ export async function executeApplyPlan(
       // 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),
     };
   }
 
@@ -444,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

@@ -31,10 +31,13 @@ export function snapshotMovedRefusal(ref: string, captured: string, planFrom: st
 }
 
 /**
- * VALIDATION PENDING: the edge committed and a post-commit `VALIDATE CONSTRAINT` did not pass.
+ * 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 did not pass:
+ * 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.
@@ -47,10 +50,16 @@ export function snapshotMovedRefusal(ref: string, captured: string, planFrom: st
  * the rest of this file follows about guessing.
  */
 export interface PendingValidationRecord {
-  /** The exact `VALIDATE CONSTRAINT` statement that did not pass. */
+  /** The exact `VALIDATE CONSTRAINT` statement that did not pass, or was never attempted. */
   sql: string;
-  /** PostgreSQL's (or the driver's) message. */
+  /** 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. */
@@ -60,17 +69,45 @@ const CUT_OFF = /timeout|canceling statement|terminat(ed|ing)|connection (closed
 
 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';
+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((p) => causeOf(p.error)));
+  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 '
@@ -87,6 +124,7 @@ export function validationPendingReason(pending: readonly PendingValidationRecor
   }
   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 `
@@ -140,7 +178,7 @@ 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
+    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

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);
   }
@@ -262,9 +315,12 @@ async function catchUpAfterApply(
 ): Promise<CatchUpReport> {
   if (!LANDED.has(result.status)) return { ok: true, statements: [] };
   if (flags['state-only'] === 'true') return { ok: true, statements: [] };
+  // 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 ?? []).executable.length;
+    : classifyGeneratedStatements((plan.statements ?? []).filter((s) => !unapplied.has(s))).executable.length;
   return runCatchUp(venue, flags, applied, 'throw');
 }
 
@@ -299,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.
  *
@@ -563,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 } : {}),
   });
 }
 
@@ -1065,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.

package/src/cli/edge-plan.ts

@@ -26,9 +26,9 @@
 
 import { createHash } from 'node:crypto';
 import type { ModelDescriptor } from '@everystack/model';
-import type { SchemaSnapshot } from './schema-introspect';
+import type { SchemaSnapshot, TableSchema } from './schema-introspect';
 import type { AuthzContract, SequenceGrantContract, DefaultAclScope } from './authz-contract';
-import { ownSequenceName } from './schema-diff';
+import { ownSequenceName, foreignKeyContentKey } from './schema-diff';
 import { generateMigrationSql, unmodeledTables } from './migration-generate';
 import { compileTableContract } from './authz-compile';
 import { carryUngovernedAuthz, inheritedSequenceGrants, type GrantExemption } from './authz-reconcile';
@@ -73,8 +73,19 @@ export const PLAN_VERSION = 2;
  * 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.
+ *
+ * v5 (validation-pending stops refusing the whole edge): `ApplyPlanResult` gained `pendingIsSafe`
+ * and `unappliedStatements` — the CLIENT now decides, from `pendingIsSafe`, whether a
+ * `validation-pending` result exits 0 (a withheld or ordinary-orphan cause) or 1 (a cut-off or
+ * unrecognised cause, a real anomaly). A v4 ops Lambda's `executeApplyPlan` never sets
+ * `pendingIsSafe` at all, so a v5 client reading its response would see it absent, treat every
+ * pending result as UNSAFE by the same fail-closed rule that protects the in-version case, and
+ * exit 1 on a perfectly safe withheld key — the exact false CI failure this whole feature exists
+ * to remove, reintroduced silently across a version skew instead of refused cleanly. The BUMP
+ * RULE covers exactly this: a field the CLIENT now depends on to decide something is part of the
+ * contract. Peers refuse until the stage is redeployed.
  */
-export const APPLY_CONTRACT_VERSION = 4;
+export const APPLY_CONTRACT_VERSION = 5;
 
 /** Classification counts (brick 9, decision 11): destructive = drops + narrowings + strips. */
 export interface PlanClassification {
@@ -225,6 +236,36 @@ export function predictLiveFingerprint(
   return predictLiveState(models, snapshot, contract, opts).hash;
 }
 
+/**
+ * One declared table with its `validate: false` foreign keys' VALIDITY taken from live.
+ *
+ * A key the model declared `validate: false` compiles to `notValid: true`, and that is right for
+ * a from-scratch build: nothing validates it, so the built key really is NOT VALID. But the
+ * PREDICTED endpoint is not a build, it is "the live database after this edge" — and the edge
+ * emits nothing at all for such a key when the live one already content-matches (see
+ * `diffConstraints`: a live NOT VALID key needs no statement, and a live FULLY-VALID key is the
+ * accept-either case). Predicting NOT VALID over a key the database has already validated would
+ * make the plan's own verify-after fail on an edge that touched nothing, on every apply, forever.
+ *
+ * So the prediction copies what the key IS. Untouched for every other key: absent live table,
+ * absent live counterpart, or a declaration that never said `validate: false` — those predict
+ * exactly what they always did.
+ */
+function carryFkValidityThrough(declared: TableSchema, live: TableSchema | undefined): TableSchema {
+  if (!live || !declared.foreignKeys.some((fk) => fk.notValid)) return declared;
+  const liveByContent = new Map(live.foreignKeys.map((fk) => [foreignKeyContentKey(fk), fk]));
+  return {
+    ...declared,
+    foreignKeys: declared.foreignKeys.map((fk) => {
+      if (!fk.notValid) return fk;
+      const counterpart = liveByContent.get(foreignKeyContentKey(fk));
+      if (!counterpart || counterpart.notValid) return fk;
+      const { notValid: _dropped, ...rest } = fk;
+      return rest;
+    }),
+  };
+}
+
 /**
  * The predicted endpoint as a full {@link Fingerprint} (hash AND canonical form). The hash is
  * the plan's `to` and the declares-test; the canonical form lets a MISMATCH report name WHICH
@@ -268,16 +309,6 @@ export function predictLiveState(
     !declaredTables.has(table) && !pendingRenameSources.has(table) && !pendingMoveSources.has(table);
   const declaredEnumList = declared.snapshot.enums ?? [];
   const declaredEnums = new Set(declaredEnumList.map((e) => e.name));
-  const mergedSnapshot: SchemaSnapshot = {
-    tables: [
-      ...declared.snapshot.tables,
-      ...snapshot.tables.filter((t) => ridesThrough(t.table)),
-    ],
-    enums: [
-      ...declaredEnumList,
-      ...(snapshot.enums ?? []).filter((e) => !declaredEnums.has(e.name)),
-    ],
-  };
   // The live counterpart of a declared table: its rename or move source when the edge brings it
   // in under a new name, else its own name. Grants, policies and owned sequences survive RENAME
   // TABLE and SET SCHEMA alike (they attach by OID), so the foreign authz carries across both.
@@ -290,6 +321,17 @@ export function predictLiveState(
     !currentNames.has(declaredTable) && currentNames.has(priorNameOf[declaredTable] ?? '')
       ? priorNameOf[declaredTable]
       : declaredTable;
+  const liveSnapshotByTable = new Map(snapshot.tables.map((t) => [t.table, t]));
+  const mergedSnapshot: SchemaSnapshot = {
+    tables: [
+      ...declared.snapshot.tables.map((t) => carryFkValidityThrough(t, liveSnapshotByTable.get(liveNameFor(t.table)))),
+      ...snapshot.tables.filter((t) => ridesThrough(t.table)),
+    ],
+    enums: [
+      ...declaredEnumList,
+      ...(snapshot.enums ?? []).filter((e) => !declaredEnums.has(e.name)),
+    ],
+  };
   const liveByTable = new Map(contract.tables.map((t) => [t.table, t]));
   const declaredColumnsByTable = new Map(
     declared.snapshot.tables.map((t) => [t.table, new Set(t.columns.map((c) => c.name))]),