@everystack/cli 0.4.84 → 0.4.86

package/src/cli/edge-plan.ts

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

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;
+}