@everystack/cli 0.4.85 → 0.4.86

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

@@ -0,0 +1,170 @@
+/**
+ * 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 — it starts with `!`, the same mark and the same
+ * severity tier the ownership report's findings use — so the caller prints 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. 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/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})`);
   }

package/src/cli/schema-compile.ts

@@ -187,6 +187,12 @@ function refActions(spec: { onDelete?: string; onUpdate?: string }): { onDelete?
  * disagree. Single-column FKs come from each field's `.references()`; composite FKs come from
  * the table-level `foreignKey([...], () => Other, [...])` constraint. Both name themselves the
  * way drizzle does — `<table>_<cols>_<target>_<refcols>_fk` — so a brownfield FK round-trips.
+ *
+ * `validate: false` on either surface compiles to `notValid: true`. That is the DECLARED half of
+ * a field introspection also sets (see {@link ForeignKey.notValid}): the author is saying this
+ * key's permanent state is installed-and-unproven, so the differ must never emit a `VALIDATE`
+ * for it and the from-scratch build must land it `NOT VALID` — otherwise the declared state and
+ * the state a build of that declaration produces would be two different states.
  */
 export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
   const out: ForeignKey[] = [];
@@ -207,6 +213,7 @@ export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
       refTable: refTableName(target),
       refColumns: [targetPk],
       ...refActions(field.spec),
+      ...(field.spec.referencesValidate === false ? { notValid: true } : {}),
     });
   }
 
@@ -222,6 +229,7 @@ export function modelForeignKeys(model: ModelDescriptor): ForeignKey[] {
       refTable: refTableName(target),
       refColumns: refCols,
       ...refActions(con),
+      ...(con.validate === false ? { notValid: true } : {}),
     });
   }
 
@@ -614,6 +622,10 @@ export { sequenceCreateSql } from './schema-diff';
  * are emitted *after* every `CREATE TABLE` (a FK's target table must already exist), so they
  * are separate from the table DDL — which is why FKs are not rendered inline by
  * compileCreateTable. Named the way drizzle names them: `<table>_<cols>_<target>_<refcols>_fk`.
+ *
+ * A key declared `validate: false` is rendered `… NOT VALID` here too. The declared state IS
+ * unproven-against-old-rows, so a migration artifact that installed it validated would build a
+ * database that does not match the models it was generated from.
  */
 export function foreignKeySql(model: ModelDescriptor): string[] {
   return modelForeignKeys(model).map((fk) => {
@@ -624,7 +636,8 @@ export function foreignKeySql(model: ModelDescriptor): string[] {
     // stays bare-but-quoted (`"uploads"`), preserving the proven output.
     return (
       `ALTER TABLE ${qualifiedTable(model)} ADD CONSTRAINT "${fk.name}" ` +
-      `FOREIGN KEY (${cols}) REFERENCES ${quoteParts(fk.refTable)}(${refCols})${refActionSql(fk)};`
+      `FOREIGN KEY (${cols}) REFERENCES ${quoteParts(fk.refTable)}(${refCols})${refActionSql(fk)}`
+      + `${fk.notValid ? ' NOT VALID' : ''};`
     );
   });
 }

package/src/cli/schema-diff.ts

@@ -29,6 +29,7 @@ import type {
   TableSchema,
   ColumnSchema,
   EnumType,
+  ForeignKey,
   IndexSchema,
   SequenceSchema,
 } from './schema-introspect';
@@ -42,9 +43,16 @@ export type ConstraintSpec =
   | { type: 'unique'; name: string; columns: string[] }
   | { type: 'check'; name: string; expr: string }
   | { type: 'foreignKey'; name: string; columns: string[]; refTable: string; refColumns: string[]; onDelete?: string; onUpdate?: string; nameDeclared?: boolean;
-      /** LIVE-SIDE ONLY: the key is installed but unchecked (see {@link ForeignKey.notValid}).
-       *  It is never part of {@link constraintContentKey} — a NOT VALID key IS the declared key,
-       *  one step short — and the emitter ignores it, because an ADD is always emitted NOT VALID. */
+      /**
+       * The key is installed but unchecked — on the LIVE side an observation, on the DESIRED
+       * side the author's `validate: false` (see {@link ForeignKey.notValid}).
+       *
+       * It is never part of {@link constraintContentKey}: a NOT VALID key IS the declared key,
+       * one step short, so validity can never make a key match a DIFFERENT key. What it decides
+       * is the SECOND statement — a desired `notValid` key emits `ADD … NOT VALID` alone, and a
+       * live `notValid` key is finished with a `VALIDATE` only when the desired side asked for
+       * one.
+       */
       notValid?: boolean };
 
 export type SchemaChange =
@@ -512,7 +520,7 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
         addConstraints.push({
           kind: 'addConstraint',
           table: d.table,
-          constraint: { type: 'foreignKey', name: fk.name, columns: fk.columns, refTable: fk.refTable, refColumns: fk.refColumns, onDelete: fk.onDelete, onUpdate: fk.onUpdate },
+          constraint: { type: 'foreignKey', name: fk.name, columns: fk.columns, refTable: fk.refTable, refColumns: fk.refColumns, onDelete: fk.onDelete, onUpdate: fk.onUpdate, ...(fk.notValid ? { notValid: true } : {}) },
         });
       }
       for (const ix of d.indexes) createIndexes.push(createIndexChange(d.table, ix));
@@ -817,10 +825,25 @@ function tableConstraintSpecs(t: TableSchema): ConstraintSpec[] {
  */
 function constraintContentKey(c: ConstraintSpec): string {
   if (c.type === 'unique') return `u|${c.columns.join(',')}`;
-  if (c.type === 'foreignKey') return `f|${c.columns.join(',')}|${c.refTable}|${c.refColumns.join(',')}|${c.onDelete ?? ''}|${c.onUpdate ?? ''}`;
+  if (c.type === 'foreignKey') return foreignKeyContentKey(c);
   return `c|${normalizeCheck(c.expr)}`; // checks take their own predicate-matched path (diffChecks)
 }
 
+/**
+ * A foreign key's content identity — columns, target, target columns, referential actions.
+ * VALIDITY IS NOT IN IT (see {@link ConstraintSpec}), and neither is the name.
+ *
+ * Exported because a second surface asks the same question: the plan's predicted endpoint has to
+ * find the live counterpart of a declared key to carry its validity through. Two spellings of
+ * "are these the same key" is how the differ and the prediction end up disagreeing about whether
+ * an edge changed anything.
+ */
+export function foreignKeyContentKey(
+  fk: Pick<ForeignKey, 'columns' | 'refTable' | 'refColumns' | 'onDelete' | 'onUpdate'>,
+): string {
+  return `f|${fk.columns.join(',')}|${fk.refTable}|${fk.refColumns.join(',')}|${fk.onDelete ?? ''}|${fk.onUpdate ?? ''}`;
+}
+
 /**
  * Diff CHECK constraints by their normalized predicate, not their name: a check with the
  * same predicate is the same check no matter what it's called, so a pulled check (whose DB
@@ -871,13 +894,22 @@ function diffConstraints(d: TableSchema, c: TableSchema, dropConstraints: Schema
         renames.push({ kind: 'renameConstraint', table: d.table, from: matched.name, to: des.name });
       }
       // The live key is there but was never checked against the rows already in the table —
-      // the state an interrupted two-step add leaves behind, and the state a hand-run
-      // `ADD CONSTRAINT … NOT VALID` leaves behind. The declared side is a VALIDATED key, so
-      // this is a real difference and the edge finishes it: VALIDATE alone, never a second
+      // what an interrupted two-step add leaves behind, and what a hand-run
+      // `ADD CONSTRAINT … NOT VALID` leaves behind. When the declared side is a VALIDATED key
+      // that is a real difference and the edge finishes it: VALIDATE alone, never a second
       // ADD (which would fail on the name that is already taken). Under the live name, which
       // may not be the declared one — a rename emitted just above lands FIRST, so the
       // validate must speak the name the constraint will have by then.
-      if (matched.type === 'foreignKey' && matched.notValid) {
+      //
+      // …UNLESS the declared side ASKED for NOT VALID (`validate: false`). Then live and
+      // declared agree and there is nothing to emit: validating would be the edge doing the
+      // one thing the author declared it must never do. Note the direction — a live key that
+      // is fully VALID under a `validate: false` declaration also falls through here with no
+      // statement, because `matched.notValid` is absent. That is the accept-either rule: there
+      // is no `ALTER TABLE … INVALIDATE CONSTRAINT`, so a key proven MORE than the model asked
+      // for is not a difference anyone could act on.
+      const desiredNotValid = des.type === 'foreignKey' && des.notValid === true;
+      if (matched.type === 'foreignKey' && matched.notValid && !desiredNotValid) {
         const name = des.type === 'foreignKey' && des.nameDeclared ? des.name : matched.name;
         addConstraints.push({ kind: 'validateConstraint', table: d.table, name });
       }
@@ -985,6 +1017,10 @@ export function validateConstraintSql(table: string, name: string): string {
  * commit), which is why the apply path runs every VALIDATE after the edge's batch commits — see
  * `splitValidations` in state-apply. The text is produced HERE for both `db:diff` (no database)
  * and `db:plan` (against a live one), so the two can never render the same edge differently.
+ *
+ * ONE statement again for a key the model declared `validate: false`: step 1 alone IS the whole
+ * declared state there, so step 2 is not deferred, it does not exist. See
+ * `FieldSpec.referencesValidate` for why a schema needs to be able to say that.
  */
 function addConstraintSql(table: string, c: ConstraintSpec): string[] {
   const head = `ALTER TABLE ${table} ADD CONSTRAINT ${quote(c.name)}`;
@@ -998,7 +1034,8 @@ function addConstraintSql(table: string, c: ConstraintSpec): string[] {
       let s = `${head} FOREIGN KEY (${colList(c.columns)}) REFERENCES ${refTable}(${colList(c.refColumns)})`;
       if (c.onDelete) s += ` ON DELETE ${c.onDelete.toUpperCase()}`;
       if (c.onUpdate) s += ` ON UPDATE ${c.onUpdate.toUpperCase()}`;
-      return [`${s} NOT VALID;`, validateConstraintSql(table, c.name)];
+      const add = `${s} NOT VALID;`;
+      return c.notValid === true ? [add] : [add, validateConstraintSql(table, c.name)];
     }
   }
 }

package/src/cli/schema-fingerprint.ts

@@ -155,6 +155,27 @@ import { fingerprintV12 } from './schema-fingerprint-v12';
 // re-baselined (db:reconcile --rebaseline) — no DDL, the fingerprint is a content address. The
 // v12 canon is frozen in schema-fingerprint-v12 and registered in RETAINED_CANONS so a schema_log
 // row recorded under it still descends.
+//
+// NO v14 FOR `validate: false` — worked out here so the next reader does not ask again.
+// The Model can now DECLARE a foreign key permanently NOT VALID (`references(…, { validate:
+// false })` → `ForeignKey.notValid` on the COMPILED side, which v13 said only introspection ever
+// set). A bump is required when the CANONICAL FORM changes — when the same database would hash
+// differently before and after. Neither half of that happens here:
+//
+//   1. The form is byte-identical. `canonicalTable` below already reads `f.notValid` and already
+//      writes it only when true. No key is added, removed, or normalized differently; the shape
+//      that hashes a live snapshot is untouched.
+//   2. Every hash anyone RECORDED is a live hash. `RETAINED_CANONS`/`fingerprintLiveAtVersion`
+//      recompute from a SchemaSnapshot read out of the database, and this feature does not change
+//      what introspection reports about any existing key. So every schema_log row still descends.
+//
+// What moves is the DECLARED hash of a model that newly writes `validate: false` — which is a
+// state change the author made on purpose, exactly like adding a column. That is the format
+// working, not the format changing. (Deliberately kept in step: the from-scratch build emits
+// `ADD … NOT VALID` for such a key too — schema-diff's `addConstraintSql` and schema-compile's
+// `foreignKeySql` — so building a database FROM that declaration lands on the declared hash
+// rather than one step past it. Without that half the declared side would hash a state no build
+// of it could produce, and `db:check` could never reach MATCH.)
 export const FINGERPRINT_VERSION = 13;
 
 // ---------------------------------------------------------------------------
@@ -198,6 +219,11 @@ function canonicalTable(table: TableSchema): Record<string, unknown> {
     // hashed identically to a validated one, so `db:fingerprint` reported MATCH on a database
     // whose data no constraint had ever been proved against. Written only when true, so every
     // fully-valid database keeps the hash it had.
+    //
+    // The flag now arrives from EITHER side — introspection's observation, or a Model's
+    // `validate: false` (see the FINGERPRINT_VERSION note above for why that needed no bump).
+    // The canonical form does not care which: one bit, one meaning — this key has never been
+    // checked against the rows that were already there.
     foreignKeys: byKey(
       table.foreignKeys.map((f) => ({
         columns: f.columns, refTable: f.refTable, refColumns: f.refColumns,