@everystack/cli 0.4.85 → 0.4.87

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.87] - 2026-09-21
+
+### BREAKING CHANGES
+
+- cache:purge --stage works without CDN_URL on the API Lambda; update --stage now refuses when no HOST_URL is found, export HOST_URL to override
+
+### Fixed
+
+- the FK-orphan advisory doubled its own '!' on top of warn()'s
+- db:provision detects PUBLIC's CREATE on schema public, revokes it under --confirm
+- the db:provision pointer swallowed every other grantee's revoke line
+
+## [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.87",
   "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.31"
+    "@everystack/server": "0.4.32"
   },
   "scripts": {
     "test": "jest",

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/audit.ts

@@ -8,7 +8,7 @@
  * the heavier `audit:lighthouse` stay separate commands (run them explicitly).
  */
 
-import { resolveConfig, opsFunction } from '../config';
+import { resolveConfig, opsFunction, probeUrl } from '../config';
 import { runBundleAudit, runBundleWeightAudit, reportBundleAudit } from './bundle';
 import { runUiAudit, reportUiAudit } from './ui-audit';
 import { checkRunbook } from './runbook';
@@ -28,7 +28,7 @@ export async function auditCommand(flags: Record<string, string>): Promise<void>
     fail(err.message);
     process.exit(1);
   }
-  const base = (flags.host || config.baseUrl || '').replace(/\/+$/, '');
+  const base = (flags.host || probeUrl(config)).replace(/\/+$/, '');
   if (!base) {
     fail('No router URL to audit. Pass --host or ensure the stage has a deployed URL.');
     process.exit(1);

package/src/cli/commands/bundle.ts

@@ -48,7 +48,7 @@ import {
   DEFAULT_UI_BLOAT_BUDGET,
   type UiBloatBudget,
 } from '../ui-bloat';
-import { resolveConfig } from '../config';
+import { resolveConfig, probeUrl } from '../config';
 import { fail, info, step, success, warn } from '../output';
 
 // Expo Router web export puts client chunks under client/_expo/...; a plain
@@ -430,7 +430,7 @@ export async function bundleAuditCommand(
   let target = positional || flags.url;
   if (!target) {
     try {
-      target = (await resolveConfig(flags.stage)).baseUrl;
+      target = probeUrl(await resolveConfig(flags.stage));
     } catch (err: any) {
       fail(err.message);
       info('Pass a URL positionally or use --stage <name>.');

package/src/cli/commands/cache.ts

@@ -9,7 +9,7 @@
  * Writes directly to CloudFront KVS — no Lambda invoke.
  */
 
-import { resolveConfig } from '../config';
+import { resolveConfig, probeUrl } from '../config';
 import { putKvsKey, createInvalidation, getDistributionStatus, getFromS3 } from '../aws';
 import { step, success, warn, fail, info } from '../output';
 
@@ -37,7 +37,7 @@ export async function cachePurgeCommand(flags: Record<string, string>): Promise<
   // Safety gate: verify the origin is serving the expected release and the distribution is stable.
   if (!force) {
     const channel = flags.channel || flags.stage || 'production';
-    const blocked = await preflight(config.region, config.baseUrl, config.updatesBucket, channel, config.distributionId);
+    const blocked = await preflight(config.region, probeUrl(config), config.updatesBucket, channel, config.distributionId);
     if (blocked) {
       fail(blocked);
       info('Pass --force to override this check.');
@@ -111,7 +111,7 @@ export async function cachePurgeCommand(flags: Record<string, string>): Promise<
  */
 export async function preflight(
   region: string,
-  baseUrl: string,
+  siteUrl: string,
   updatesBucket: string,
   channel: string,
   distributionId?: string,
@@ -134,19 +134,26 @@ export async function preflight(
   }
 
   // 2. Probe the origin for the serving release.
+  if (!siteUrl) {
+    return (
+      'No site URL for this stage, so the origin cannot be probed. ' +
+      'Set CDN_URL on the API function and redeploy, or tag the distribution sst:app/sst:stage; ' +
+      'then re-run with --refresh to discover the stage again. Or pass --force to skip this check.'
+    );
+  }
   try {
-    const probe = `${baseUrl}?_probe=${Date.now()}`;
+    const probe = `${siteUrl}?_probe=${Date.now()}`;
     const res = await fetch(probe, { redirect: 'follow' });
     const serving = res.headers.get('x-everystack-release');
     if (serving !== expectedUpdateId) {
       return (
         `Origin is serving release ${serving ? serving.slice(0, 12) + '...' : '(none)'} ` +
-        `but the channel pointer is ${expectedUpdateId.slice(0, 12)}.... ` +
+        `but the channel pointer is ${expectedUpdateId.slice(0, 12)}.... Probed ${siteUrl}. ` +
         `Purging now would expose stale containers to uncached traffic.`
       );
     }
   } catch (err: any) {
-    return `Could not reach origin at ${baseUrl}: ${err.message}`;
+    return `Could not reach origin at ${siteUrl}: ${err.message}`;
   }
 
   // 3. Check distribution status (if discoverable).

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/commands/db-snapshot.ts

@@ -26,6 +26,8 @@ function resolveInstanceId(config: CliConfig, flags: Record<string, string>): st
       '  - If your DB is RDS: add `databaseInstanceId: database.id` to the outputs return block in\n' +
       '    sst.config.ts and redeploy (run db:snapshot from the app directory so .sst/outputs.json is\n' +
       '    readable), or pass --instance <id>.\n' +
+      '  - .sst/outputs.json is used only when it is THIS stage\'s deploy (its apiFunctionName names the\n' +
+      '    stage). If the last `sst deploy` was another stage, redeploy this one, or pass --instance <id>.\n' +
       '  - If your DB is not RDS (Aurora, a container, self-hosted): use `everystack db:backup` for a portable logical backup.',
     );
     process.exit(1);