@everystack/cli 0.4.85 → 0.4.87

package/src/cli/fk-orphan-advisory.ts

@@ -0,0 +1,172 @@
+/**
+ * fk-orphan-advisory — the RECURRING NOTICE about foreign keys that stay unproven.
+ *
+ * Its sibling, fk-preflight, owns the fail-closed REFUSAL (the row check could not run) and the
+ * data the read produces. This owns the other half: what `db:plan` and `db:apply` say, at the
+ * DEFAULT verbosity, about keys that are installed, enforced on every new write, and carrying
+ * rows nobody has ever checked.
+ *
+ * THREE RULES, and each one is a decision somebody could get wrong:
+ *
+ *   IT NEVER BLOCKS. Not db:plan, not db:apply, not db:check. There is no refusal here and no
+ *   flag to get past one. Unproven legacy rows are DEBT, and a gate that stops work over debt
+ *   gets disabled — which is how the whole edge came to be refused for one orphaned key.
+ *
+ *   IT NEVER PROPOSES A DELETE. It names rows; a human decides. No DML is emitted, suggested,
+ *   or implied, ever. The samples are KEY VALUES only — three of them, enough to recognise a
+ *   row, never its contents.
+ *
+ *   IT RECURS. This prints on every run while the condition holds, because the condition is
+ *   durable: the keys really are unproven, today and next month. A one-time alert on a
+ *   permanent fact is a fact nobody ever sees again. The escape is not acknowledgement, it is
+ *   one of the two real answers — fix the rows, or declare `validate: false` and mean it.
+ *
+ * WHAT IS ABSENT FROM IT, deliberately: any key the Model declared `validate: false`. That
+ * declaration IS the decision this notice is asking for, so continuing to nag about it would
+ * make the flag worthless. The mechanism is structural rather than a filter — the differ emits
+ * no `VALIDATE` for such a key, so fk-preflight never scans it and it can never reach here.
+ * What is left is exactly the UNDECIDED set: keys whose model has said nothing either way.
+ *
+ * NONE OF IT RIDES IN THE PLAN FILE. The plan is a deterministic DDL list under a content hash,
+ * and live row counts go stale between minting and applying. A file that asserted "9,412 rows"
+ * would be asserting something that need not still be true when someone reads it.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import type { FkOrphanFinding } from './fk-preflight';
+import { toSnakeCase } from './schema-compile';
+
+/**
+ * The columns a model reads to decide WHO MAY SEE OR WRITE A ROW, per schema-qualified table.
+ *
+ * Two shapes qualify, and they fail differently:
+ *
+ *   `can(…, { owner: 'userId' })`  — the column IS the row's owner. `rowOwnership` in the
+ *                                    derived handler config is the same column (derive.ts takes
+ *                                    the first owner-shaped ability), so covering the ability
+ *                                    covers both surfaces.
+ *   `can(…, { via: 'uploadId' })`  — the column is the LINK to the owner: the policy compiles to
+ *                                    `<col> IN (SELECT id FROM <parent> WHERE <owner> = <claim>)`.
+ *                                    An orphan here is the sharper case — the parent row is
+ *                                    gone, so the subquery matches nothing and the row answers
+ *                                    "belongs to nobody".
+ *
+ * Column-scoped abilities (`columns: [...]`) are covered by the same `owner`/`via` read; the
+ * column list narrows what is exposed, not what decides access.
+ */
+export function ownershipColumns(models: readonly ModelDescriptor[]): Map<string, Set<string>> {
+  const out = new Map<string, Set<string>>();
+  for (const model of models) {
+    const table = `${model.schema ?? 'public'}.${model.table}`;
+    for (const ability of model.abilities) {
+      for (const key of [ability.condition.owner, ability.condition.via]) {
+        if (!key) continue;
+        // Field KEYS are camelCase in the model, columns are snake_case in the database —
+        // through the compiler's own conversion, so this and `.references()` can never disagree
+        // about which column an ability names.
+        const set = out.get(table) ?? out.set(table, new Set()).get(table)!;
+        set.add(toSnakeCase(key));
+      }
+    }
+  }
+  return out;
+}
+
+/** A thousands-separated count — `11500` is read wrong at a glance, `11,500` is not. */
+const count = (n: number): string => n.toLocaleString('en-US');
+
+const plural = (n: number, one: string, many: string): string => (n === 1 ? one : many);
+
+/** Which of a finding's own columns decide access on its table. Empty for the ordinary case. */
+function gatingColumns(finding: FkOrphanFinding, ownership: ReadonlyMap<string, Set<string>>): string[] {
+  const gated = ownership.get(finding.table);
+  return gated ? finding.columns.filter((c) => gated.has(c)) : [];
+}
+
+/** The per-key detail — counts, the columns, and KEY VALUES only. Behind --verbose. */
+function detailLines(findings: readonly FkOrphanFinding[]): string[] {
+  const lines: string[] = [];
+  for (const f of findings) {
+    lines.push(
+      `      ${f.table}.${f.constraint}: ${count(f.orphans)} ${plural(f.orphans, 'row', 'rows')} `
+      + `hold a value in (${f.columns.join(', ')}) with no matching row in ${f.refTable}.`,
+    );
+    if (f.samples.length > 0) {
+      lines.push(`          sample key value(s): ${f.samples.join(', ')}${f.orphans > f.samples.length ? ', …' : ''}`);
+    }
+    // A read, never a write. This module has no DELETE to offer and never will. The parent's
+    // key columns are a PLACEHOLDER — the read that produced these counts knows them, this
+    // report does not carry them, and inventing a name would hand over a query that errors.
+    const predicate = f.columns.length === 1
+      ? `p.<key> = c.${f.columns[0]}`
+      : `(p.<keys>) = (${f.columns.map((c) => `c.${c}`).join(', ')})`;
+    lines.push(
+      `          the rows:  SELECT * FROM ${f.table} c WHERE NOT EXISTS `
+      + `(SELECT 1 FROM ${f.refTable} p WHERE ${predicate});`,
+    );
+  }
+  return lines;
+}
+
+export interface FkOrphanAdvisoryOptions {
+  /** --verbose: add the per-key counts and key-value samples under each headline. */
+  verbose?: boolean;
+}
+
+/**
+ * The advisory, as lines. Empty when nothing is unproven.
+ *
+ * Every HEADLINE it returns is a problem line, the same severity tier the ownership report's
+ * findings use — so the caller `warn()`s whatever comes back without having to classify it: at
+ * the default verbosity that is headlines only, and `verbose` adds the indented detail under
+ * each one. `warn()` (output.ts) already prepends the `!` mark, so these strings carry none of
+ * their own — a caller that printed one with `line()`/`info()` instead of `warn()` would be the
+ * bug, not this module doubling the mark on top of it. The headline states the CONSEQUENCE —
+ * enforced forward, N rows unchecked — because a bare count reads as an error nobody can size.
+ *
+ * Findings whose column also decides row access get their OWN headline. Same severity, same
+ * non-blocking behaviour: what changes is that the reader is told this is not only a data
+ * consistency question, because a row that points at a deleted parent through an ownership link
+ * answers "who owns me" with nothing.
+ */
+export function renderFkOrphanAdvisory(
+  findings: readonly FkOrphanFinding[],
+  ownership: ReadonlyMap<string, Set<string>> = new Map(),
+  opts: FkOrphanAdvisoryOptions = {},
+): string[] {
+  if (findings.length === 0) return [];
+  const verbose = opts.verbose === true;
+
+  const gating = findings.filter((f) => gatingColumns(f, ownership).length > 0);
+  const plain = findings.filter((f) => gatingColumns(f, ownership).length === 0);
+
+  const lines: string[] = [];
+  const declareIt = 'declare `validate: false` on the reference if that is intentional';
+
+  if (plain.length > 0) {
+    const rows = plain.reduce((sum, f) => sum + f.orphans, 0);
+    lines.push(
+      `${plain.length} foreign ${plural(plain.length, 'key stays', 'keys stay')} NOT VALID: new writes enforced, `
+      + `${count(rows)} existing ${plural(rows, 'row', 'rows')} unchecked `
+      + `(--verbose for detail; ${declareIt}).`,
+    );
+    if (verbose) lines.push(...detailLines(plain));
+  }
+
+  if (gating.length > 0) {
+    const rows = gating.reduce((sum, f) => sum + f.orphans, 0);
+    const where = gating
+      .map((f) => `${f.table}.${gatingColumns(f, ownership).join('/')}`)
+      .join(', ');
+    lines.push(
+      `ROW SECURITY — ${gating.length} unproven foreign ${plural(gating.length, 'key also decides', 'keys also decide')} `
+      + `who may read or write the row (${where}): `
+      + `${count(rows)} existing ${plural(rows, 'row', 'rows')} point at a parent that is gone, so the owner check `
+      + `on ${plural(gating.length, 'it', 'them')} matches nobody `
+      + `(--verbose for detail; ${declareIt}).`,
+    );
+    if (verbose) lines.push(...detailLines(gating));
+  }
+
+  return lines;
+}

package/src/cli/fk-preflight.ts

@@ -1,20 +1,35 @@
 /**
  * fk-preflight — the orphan check that runs BEFORE a foreign key's DDL, not during it.
  *
- * A foreign key is only installable if the rows already in the table satisfy it. PostgreSQL
+ * A foreign key is only VALIDATABLE if the rows already in the table satisfy it. PostgreSQL
  * finds that out DURING `VALIDATE CONSTRAINT`, by raising on the first row that does not — one
  * row, no count, no second offender, and (before the two-step split) after the apply had already
  * taken an ACCESS EXCLUSIVE lock and scanned most of the table. The operator learned "there is a
  * problem" at the worst possible moment and learned nothing else.
  *
  * So the apply asks the question first, the same way the declared-owner preflight in
- * derived-apply does: ONE read that answers it for EVERY key the edge touches, so the refusal
- * can name the COMPLETE list — how many rows, on which key, and what a few of them look like —
- * and NOTHING has run when it is raised. Fix the data (`db:exec` is the credential-free lane for
- * exactly that), re-plan, apply.
+ * derived-apply does: ONE read that answers it for EVERY key the edge would validate, so the
+ * report can name the COMPLETE list — how many rows, on which key, and what a few of them look
+ * like — before anything runs.
  *
- * WHICH KEYS NEED THE QUESTION ASKED. Only the ones where an existing row could already violate
- * the constraint, which is a property of the LIVE database, not of the statement:
+ * WHAT THE ANSWER IS FOR, and this is the part that changed. It used to refuse the WHOLE apply
+ * if any key had one orphan: unrelated grants, unrelated clean keys, the entire edge, held
+ * behind a data audit. On a long-lived database that is the wrong trade — ~11,500 legitimately
+ * orphaned rows across 12 of 23 keys is ordinary decay, not a broken deploy. Now the answer is
+ * PER KEY: the offending key's `VALIDATE` is withheld (the key stays installed and NOT VALID,
+ * enforced on every new write), it is recorded as a pending validation, and everything else in
+ * the edge commits. Fix the data when you choose (`db:exec` is the credential-free lane) and the
+ * next plan emits that one `VALIDATE` alone — or declare `validate: false` on the reference and
+ * the question is never asked about that key again.
+ *
+ * THE UNIT IS A `VALIDATE` STATEMENT, not a foreign key add. That is the whole rule, and it is
+ * why a key declared `validate: false` is never scanned: the differ emits no `VALIDATE` for it,
+ * so there is nothing here to ask about. An `ADD … NOT VALID` and the `VALIDATE` that follows it
+ * in the same edge are ONE question — the key is the unit, not the statement — and an
+ * `ADD … NOT VALID` with NO `VALIDATE` behind it is not a question at all.
+ *
+ * WHICH VALIDATED KEYS NEED THE QUESTION ASKED. Only the ones where an existing row could
+ * already violate the constraint, which is a property of the LIVE database, not of the statement:
  *
  *   - a key on a table this edge CREATES         → no. The table has no rows yet, and it does
  *                                                  not exist to be queried before the edge runs.
@@ -31,13 +46,11 @@
  *                                                  exactly what VALIDATE is about to scan.
  *   - a key on an existing table and columns     → YES.
  *
- * An `ADD … NOT VALID` and the `VALIDATE` that follows it in the same edge are ONE question, not
- * two — the key is the unit, not the statement.
- *
- * Pure: the parsing, the SQL, and the refusal text. The caller runs the query.
+ * Pure: the parsing, the SQL, the findings, and the text. The caller runs the query.
  */
 
 import type { SchemaSnapshot, TableSchema, ForeignKey } from './schema-introspect';
+import type { PendingValidation } from './state-apply';
 import { statementBody } from './sql-statement';
 import { quoteIdent, quoteQualified } from './pg-ident';
 import { escapeLiteral } from './derived-apply';
@@ -80,12 +93,18 @@ const liveTable = (live: SchemaSnapshot, table: string): TableSchema | undefined
   live.tables.find((t) => t.table === table);
 
 /**
- * The foreign keys an edge is about to install or validate that could ALREADY be violated by
- * rows in the live database — see the rules in the module docblock.
+ * The foreign keys an edge is about to VALIDATE that could ALREADY be violated by rows in the
+ * live database — see the rules in the module docblock.
  *
  * `statements` is the edge exactly as it will execute (held drops and notices included; they are
  * comments and match nothing). `live` is the target's state as the apply just read it — the same
  * snapshot the concurrency lock was computed from, so the two cannot describe different databases.
+ *
+ * Driven by the `VALIDATE` statements, never by the `ADD`s. An `ADD … NOT VALID` used to imply
+ * the question because the emitter always paired the two; a key declared `validate: false` is
+ * emitted with no pair, and scanning for it would be scanning a table to answer a question
+ * nobody asked. The ADD is still read — it is where a NEW key's columns and target come from,
+ * which the live snapshot cannot supply.
  */
 export function fkOrphanChecks(statements: readonly string[], live: SchemaSnapshot): FkOrphanCheck[] {
   const bodies = statements.map(statementBody);
@@ -112,6 +131,14 @@ export function fkOrphanChecks(statements: readonly string[], live: SchemaSnapsh
     if (m) renamedFrom.set(`${normalizeTableName(m[1])}::${unquote(m[3])}`, unquote(m[2]));
   }
 
+  // The keys this edge actually asks to be PROVEN. Everything below is about them and only
+  // them: a key whose `ADD … NOT VALID` stands alone is the declared state, not a pending step.
+  const validated = new Set<string>();
+  for (const body of bodies) {
+    const m = VALIDATE_RE.exec(body);
+    if (m) validated.add(`${normalizeTableName(m[1])}::${unquote(m[2])}`);
+  }
+
   const checks: FkOrphanCheck[] = [];
   const seen = new Set<string>();
 
@@ -126,6 +153,8 @@ export function fkOrphanChecks(statements: readonly string[], live: SchemaSnapsh
     const add = ADD_FK_RE.exec(body);
     if (add) {
       const table = normalizeTableName(add[1]);
+      // No `VALIDATE` behind this ADD — `validate: false`. Nothing to prove, nothing to scan.
+      if (!validated.has(`${table}::${unquote(add[2])}`)) continue;
       const columns = parseColumns(add[3]);
       const target = liveTable(live, table);
       // Not live yet, or one of its columns is not: nothing to scan, and nothing to scan it with.
@@ -245,9 +274,9 @@ export function fkOrphanSql(checks: readonly FkOrphanCheck[]): string {
  * nobody can read, and an unreadable answer is not "no orphans": it is the gate not running.
  *
  * FAIL CLOSED. A driver that hands back `[]` (a shape quirk, a transport that dropped the rows,
- * a future change to the read) would otherwise walk straight through `fkOrphanRefusal`, which
- * reports null — "every key is satisfied" — for an empty list. Asserted here, in the module that
- * owns the read's shape, so the assertion cannot drift from the SQL it is about.
+ * a future change to the read) would otherwise walk straight through {@link fkOrphanFindings},
+ * which reports an empty list — "every key is satisfied" — for an empty answer. Asserted here, in
+ * the module that owns the read's shape, so the assertion cannot drift from the SQL it is about.
  */
 export function checkOrphanRowShape(rows: unknown, expected: number): asserts rows is FkOrphanRow[] {
   const got = Array.isArray(rows) ? rows.length : null;
@@ -295,37 +324,91 @@ export function fkPreflightUnavailableRefusal(error: string): string {
 }
 
 /**
- * The refusal text, or null when every key's rows already satisfy it.
+ * One key the read found orphaned rows for.
  *
- * It names the COUNT and a SAMPLE per key, because those are the two things the operator needs
- * and neither is in PostgreSQL's own error: how much work the fix is, and what the broken rows
- * look like. The fix is data, so the escape is a data fix and a re-plan — never a flag. There is
- * deliberately no `--force`: an unsatisfiable foreign key is not an intent someone can attest to.
+ * This, not the prose, is what the apply and the plan report from: the apply has to decide PER
+ * KEY which `VALIDATE` to withhold, and the plan has to cross-reference the column against the
+ * row-ownership declarations. Neither can be done by parsing a message.
+ */
+export interface FkOrphanFinding {
+  /** Schema-qualified child table (`public.posts`). */
+  table: string;
+  /** The constraint name the withheld `VALIDATE` would have named. */
+  constraint: string;
+  /** The key's own columns, in order. */
+  columns: string[];
+  /** Schema-qualified target table. */
+  refTable: string;
+  /** How many rows hold a value with no matching parent. Exact — the read counts, it does not sample. */
+  orphans: number;
+  /** At most three KEY VALUES, for recognising a row. Never row contents. */
+  samples: string[];
+}
+
+/**
+ * The keys with orphaned rows, as data. Empty when every key's rows already satisfy it.
  *
- * THROWS when a row's count cannot be read — see {@link toCount}. `null` returned from here means
- * "asked and satisfied", so an unreadable count must not be able to produce it.
+ * THROWS on a count it cannot read, for exactly the reason {@link toCount} does: an empty
+ * findings list means "asked and satisfied", so an unreadable answer must never be able to
+ * produce one.
  */
-export function fkOrphanRefusal(rows: readonly FkOrphanRow[]): string | null {
-  const where = (r: FkOrphanRow): string => `${String(r.table_name)}.${String(r.constraint_name)}`;
-  const counted = rows.map((r) => ({ row: r, count: toCount(r.orphans, where(r)) }));
-  const offenders = counted.filter((c) => c.count > 0);
-  if (offenders.length === 0) return null;
+export function fkOrphanFindings(rows: readonly FkOrphanRow[]): FkOrphanFinding[] {
+  const out: FkOrphanFinding[] = [];
+  for (const r of rows) {
+    const table = String(r.table_name);
+    const constraint = String(r.constraint_name);
+    const orphans = toCount(r.orphans, `${table}.${constraint}`);
+    if (orphans <= 0) continue;
+    out.push({
+      table,
+      constraint,
+      columns: String(r.columns).split(', ').filter((c) => c.length > 0),
+      refTable: String(r.ref_table),
+      orphans,
+      samples: toSamples(r.samples),
+    });
+  }
+  return out;
+}
 
-  const lines = [
-    `${offenders.length} foreign key(s) cannot be validated — rows already in the table do not satisfy them. Refused before any DDL, so nothing is half-applied.`,
-    `Fix the data first (everystack db:exec runs a DML-only file against the target, credential-free), then re-plan and apply.`,
-  ];
-  for (const { row, count } of offenders) {
-    const samples = toSamples(row.samples);
-    lines.push(
-      `  ORPHANED ROWS  ${String(row.table_name)}.${String(row.constraint_name)}: ${count} row(s) hold a value in (${String(row.columns)}) with no matching row in ${String(row.ref_table)}.`,
-    );
-    if (samples.length > 0) {
-      lines.push(`      sample value(s): ${samples.join(', ')}${count > samples.length ? ', …' : ''}`);
+/**
+ * Split an edge into the statements to RUN and the `VALIDATE`s to WITHHOLD, one per orphaned key.
+ *
+ * The withheld statement is not a failure and not a refusal — it is a check whose answer is
+ * already known, so running it would take a lock and a full scan to be told what the preflight
+ * just counted. It goes into the SAME `pendingValidations` record a check that ran and failed
+ * goes into: the operator's situation is identical (key installed, enforced forward, unproven
+ * against the old rows) and so is the next move.
+ *
+ * Matching is by table + constraint name, which is the name the `VALIDATE` will speak — a rename
+ * in the same edge lands first, and {@link fkOrphanChecks} already keys the check on the NEW
+ * name, so the two agree.
+ */
+export function withheldValidations(
+  statements: readonly string[],
+  findings: readonly FkOrphanFinding[],
+): { statements: string[]; withheld: PendingValidation[] } {
+  if (findings.length === 0) return { statements: [...statements], withheld: [] };
+  const byKey = new Map(findings.map((f) => [`${f.table}::${f.constraint}`, f]));
+  const kept: string[] = [];
+  const withheld: PendingValidation[] = [];
+  for (const statement of statements) {
+    const m = VALIDATE_RE.exec(statementBody(statement));
+    const finding = m ? byKey.get(`${normalizeTableName(m[1])}::${unquote(m[2])}`) : undefined;
+    if (!finding) {
+      kept.push(statement);
+      continue;
     }
-    lines.push(
-      `      the rows:  SELECT * FROM ${row.table_name} c WHERE NOT EXISTS (SELECT 1 FROM ${row.ref_table} p WHERE p.<key> = c.<fk>);`,
-    );
+    withheld.push({
+      sql: statement,
+      // Phrased so it reads as the orphan-data cause it IS — `validationPendingReason` sends
+      // the operator to the data fix, which is the right move here.
+      error:
+        `not attempted: ${finding.orphans} row(s) already in ${finding.table} hold a value in `
+        + `(${finding.columns.join(', ')}) with no matching row in ${finding.refTable}, counted by the foreign-key `
+        + 'row check before any DDL ran. The key is installed and enforced on new writes; the rest of the edge applied.',
+      skipped: true,
+    });
   }
-  return lines.join('\n');
+  return { statements: kept, withheld };
 }

package/src/cli/host-url.ts

@@ -0,0 +1,127 @@
+/**
+ * Auto-detect HOST_URL from SST outputs.
+ * SST writes .sst/outputs.json after every deploy with { routerUrl, apiUrl, ... }.
+ * If HOST_URL isn't already set, use the routerUrl from the last deploy.
+ *
+ * When a stage is specified, checks the stage-specific cached config first.
+ * .sst/outputs.json reflects the last deploy (any stage), so with --stage it is used only when
+ * its apiFunctionName says that deploy WAS this stage (outputsDescribeStage). Otherwise HOST_URL
+ * stays unset: a wrong-stage URL would be baked into the OTA bundle by `update`.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+export async function loadSstOutputs(stage?: string): Promise<void> {
+  if (process.env.HOST_URL) return;
+
+  // When --stage is provided, try stage-specific cache first
+  if (stage) {
+    const stagePath = path.resolve('.sst', `outputs.${stage}.json`);
+    try {
+      const raw = await fs.readFile(stagePath, 'utf8');
+      const cached = JSON.parse(raw);
+      if (cached.routerUrl) {
+        process.env.HOST_URL = cached.routerUrl;
+        return;
+      }
+    } catch {
+      // No cached config for this stage — fall through to default
+    }
+  }
+
+  const outputsPath = path.resolve('.sst', 'outputs.json');
+  try {
+    const raw = await fs.readFile(outputsPath, 'utf8');
+    const outputs = JSON.parse(raw);
+    if (stage && !(await outputsBelongToStage(outputs, stage))) return;
+    if (outputs.routerUrl) {
+      process.env.HOST_URL = outputs.routerUrl;
+    }
+  } catch {
+    // No .sst/outputs.json — user must set HOST_URL manually or use app.config.js defaults
+  }
+}
+
+/** Provenance gate for the --stage fall-through; an unreadable app name means unknown, so no. */
+async function outputsBelongToStage(outputs: { apiFunctionName?: string }, stage: string): Promise<boolean> {
+  try {
+    const { parseAppName, outputsDescribeStage } = await import('./discover');
+    return outputsDescribeStage(outputs, await parseAppName(), stage);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The @expo/env `expo export` will load, found the way it finds it: expo -> @expo/cli -> @expo/env
+ * from the project (a package manager that does not hoist still resolves it), else a direct
+ * @expo/env. Undefined when the project has no Expo.
+ */
+function resolveExpoEnv(from: string): string | undefined {
+  const at = (dir: string, id: string) => createRequire(path.join(dir, 'noop.js')).resolve(id);
+  try {
+    const cli = at(path.dirname(at(from, 'expo/package.json')), '@expo/cli/package.json');
+    return at(path.dirname(cli), '@expo/env');
+  } catch {
+    // fall through
+  }
+  try {
+    return at(from, '@expo/env');
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Does the dotenv loading `expo export` will run set a non-empty HOST_URL? It runs Expo's own
+ * loader (@expo/env parseProjectEnv), not a copy of it: file set, precedence,
+ * EXPO_NO_DOTENV and variable expansion are Expo's (the mode is fixed to production, as in export), so this sees what the bundle will bake.
+ * Non-mutating. Only a boolean escapes; no value is kept or printed. Fails closed: no Expo, or
+ * a loader that throws, means no.
+ */
+async function dotenvSetsHostUrl(
+  cwd: string,
+  env: Record<string, string | undefined>,
+  resolveFrom: string,
+): Promise<boolean> {
+  const resolved = resolveExpoEnv(resolveFrom);
+  if (!resolved) return false;
+  try {
+    const expoEnv = createRequire(resolved)(resolved) as {
+      parseProjectEnv(
+        root: string,
+        options: { mode?: string; silent?: boolean; systemEnv?: Record<string, string | undefined> },
+      ): { env: Record<string, string | undefined> };
+    };
+    // Upstream behaviour, re-verify on every Expo upgrade: @expo/cli build/src/export/exportApp.js
+    // exportAppAsync sets `process.env.NODE_ENV = dev ? 'development' : 'production'`
+    // unconditionally, and everystack never passes --dev. So the mode is production, not env.NODE_ENV.
+    const parsed = expoEnv.parseProjectEnv(cwd, { mode: 'production', silent: true, systemEnv: env });
+    return Boolean(parsed.env.HOST_URL);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Why `update --stage` must stop: nothing supplied a HOST_URL, so the OTA bundle would bake the
+ * app's default (often localhost) as updates.url. Devices could then never fetch the recovery
+ * publish. Undefined when HOST_URL is set (env or dotenv) or no stage was given. The message
+ * names the ways out, including the stage's own site URL when discovery found one.
+ */
+export async function missingHostUrlError(
+  stage: string | undefined,
+  opts: { env?: Record<string, string | undefined>; cwd?: string; siteUrl?: string; resolveFrom?: string } = {},
+): Promise<string | undefined> {
+  const { env = process.env, cwd = process.cwd(), siteUrl, resolveFrom = cwd } = opts;
+  if (!stage || env.HOST_URL || (await dotenvSetsHostUrl(cwd, env, resolveFrom))) return undefined;
+  const offer = siteUrl ? ` This stage's site URL is ${siteUrl}; export it as HOST_URL if that is its public URL.` : '';
+  return (
+    `No HOST_URL for stage "${stage}", so the bundle would ship the app's default URL as updates.url.${offer} ` +
+    'Otherwise export HOST_URL=<the stage\'s public URL>, or set CDN_URL on the API function and re-run with --refresh. ' +
+    '(A HOST_URL in a dotenv file counts only when the project\'s Expo can be found to read it the way `expo export` does.) ' +
+    `(.sst/outputs.json is used only when its apiFunctionName is "<app>-${stage}-ApiFunction-...".)`
+  );
+}

package/src/cli/index.ts

@@ -1,7 +1,6 @@
 #!/usr/bin/env tsx
 
-import fs from 'node:fs/promises';
-import path from 'node:path';
+import { loadSstOutputs } from './host-url';
 import { updateCommand } from './commands/update';
 import { deployCommand } from './commands/deploy';
 import { certsCommand } from './commands/certs';
@@ -51,45 +50,6 @@ import { parseFlags } from './parse-flags';
 const args = process.argv.slice(2);
 const command = args[0];
 
-/**
- * Auto-detect HOST_URL from SST outputs.
- * SST writes .sst/outputs.json after every deploy with { routerUrl, apiUrl, ... }.
- * If HOST_URL isn't already set, use the routerUrl from the last deploy.
- *
- * When a stage is specified, checks the stage-specific cached config first.
- * .sst/outputs.json reflects the last deploy (any stage) and may be wrong
- * when publishing to a different stage.
- */
-async function loadSstOutputs(stage?: string): Promise<void> {
-  if (process.env.HOST_URL) return;
-
-  // When --stage is provided, try stage-specific cache first
-  if (stage) {
-    const stagePath = path.resolve('.sst', `outputs.${stage}.json`);
-    try {
-      const raw = await fs.readFile(stagePath, 'utf8');
-      const cached = JSON.parse(raw);
-      if (cached.routerUrl) {
-        process.env.HOST_URL = cached.routerUrl;
-        return;
-      }
-    } catch {
-      // No cached config for this stage — fall through to default
-    }
-  }
-
-  const outputsPath = path.resolve('.sst', 'outputs.json');
-  try {
-    const raw = await fs.readFile(outputsPath, 'utf8');
-    const outputs = JSON.parse(raw);
-    if (outputs.routerUrl) {
-      process.env.HOST_URL = outputs.routerUrl;
-    }
-  } catch {
-    // No .sst/outputs.json — user must set HOST_URL manually or use app.config.js defaults
-  }
-}
-
 async function main() {
   if (!command || command === '--help' || command === '-h') {
     printHelp();

package/src/cli/model-render.ts

@@ -549,6 +549,14 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
     if (fk.name && fk.name !== generatedForeignKeyName(bareName(table.table), fk.columns, bareName(fk.refTable), fk.refColumns)) {
       actions.push(`name: ${tsLiteral(fk.name)}`);
     }
+    // The key is live and has NEVER been checked against the rows already in the table. Rendering
+    // it as an ordinary reference would declare a state this database is not in — and the FIRST
+    // plan after the pull would then emit a `VALIDATE` the legacy rows cannot pass. On the schema
+    // this was measured against that was 12 of 23 keys, every one of them deliberately NOT VALID
+    // in the app's own migration ("enforce forward, grandfather legacy"). So the pull SAYS what it
+    // found, the adoption plan comes out empty, and removing the flag later is how an operator
+    // opts into the scan. Same rule as the index and constraint names one line up: be faithful.
+    if (fk.notValid) actions.push('validate: false');
     const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
       expr += `.references(() => ${modelVarName(fk.refTable)}${opts})`;
     } else comment += ` // FK → ${fk.refTable} (not in the pulled set)`;
@@ -631,6 +639,8 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
     if (fk.name && fk.name !== generatedForeignKeyName(bareName(table.table), fk.columns, bareName(fk.refTable), fk.refColumns)) {
       actions.push(`name: ${tsLiteral(fk.name)}`);
     }
+    // Faithful about validity, exactly as the single-column case above is — see there for why.
+    if (fk.notValid) actions.push('validate: false');
     const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
     items.push(`foreignKey(${cols}, () => ${modelVarName(fk.refTable)}, ${refCols}${opts})`);
   }