@everystack/cli 0.4.85 → 0.4.86

package/src/cli/schema-introspect.ts

@@ -53,14 +53,27 @@ export interface ForeignKey {
   onDelete?: string;
   onUpdate?: string;
   /**
-   * The constraint exists but has NOT been checked against the rows already in the table
-   * (`convalidated = false`; `pg_get_constraintdef` spells it `… NOT VALID`).
+   * The key is enforced on every new write but has NOT been checked against the rows already
+   * in the table (`convalidated = false`; `pg_get_constraintdef` spells it `… NOT VALID`).
    *
-   * LIVE-SIDE ONLY. A Model declares a foreign key, never a half-installed one, so the
-   * compiled side never sets this — which is exactly what makes it visible as drift: a live
-   * NOT VALID key is a DIFFERENT state from the declared (validated) one. It rides the
-   * canonical fingerprint form for the same reason, so a half-applied key can never report
-   * MATCH. Omitted (not `false`) when the constraint is validated, so every already-recorded
+   * BOTH SIDES SET THIS, and they mean two different things by it:
+   *
+   *   LIVE-OBSERVED      — introspection read `convalidated = false`. It says nothing about
+   *                        WHY: an interrupted two-step add, a hand-run `ADD … NOT VALID`, or
+   *                        a key someone deliberately left unproven years ago.
+   *   DECLARED-INTENTIONAL — the Model said `validate: false` on the reference, which is the
+   *                        author declaring "enforce forward, grandfather legacy" as the
+   *                        PERMANENT state of this key (see `FieldSpec.referencesValidate`).
+   *                        The differ then emits `ADD CONSTRAINT … NOT VALID` and NEVER the
+   *                        paired `VALIDATE`.
+   *
+   * HOW THE TWO MEET. A declared-intentional key is satisfied by EITHER a live NOT VALID key
+   * or a live FULLY-VALID one: PostgreSQL has no "un-validate", so "more proven than you asked
+   * for" is not a difference anybody can act on and must not read as drift. The asymmetry only
+   * runs the other way — a live NOT VALID key under a declaration that did NOT say
+   * `validate: false` IS a real difference, and the edge closes it with a `VALIDATE` alone.
+   *
+   * Omitted (not `false`) when the key is validated, on both sides, so every already-recorded
    * hash for a fully-valid database is untouched.
    */
   notValid?: boolean;

package/src/cli/state-apply.ts

@@ -393,14 +393,31 @@ export interface StateApplyOptions {
    * run — with none there is no window between the commit and the record to protect.
    */
   readFingerprint?: () => Promise<string>;
+  /**
+   * `VALIDATE CONSTRAINT`s the caller REMOVED from `statements` before calling, because the row
+   * check it ran first already counted the offending rows (see fk-preflight's `withheldValidations`).
+   *
+   * They are pending validations that were never attempted, and they are recorded and reported
+   * exactly like ones that ran and failed — the key is installed, enforced forward and unproven
+   * either way, so giving the operator two vocabularies for one situation would only make them
+   * work out that it is the same situation. Running them instead would take a lock and a full
+   * scan to be told what is already known.
+   */
+  skippedValidations?: readonly PendingValidation[];
 }
 
 /** A `VALIDATE CONSTRAINT` that did not pass — the key is installed but still unproven. */
 export interface PendingValidation {
   /** The exact statement to re-run once the data satisfies the key. */
   sql: string;
-  /** PostgreSQL's message, trimmed for the record. */
+  /** PostgreSQL's message, trimmed for the record — or why the check was never attempted. */
   error: string;
+  /**
+   * The check was WITHHELD, not run: the row preflight had already counted the offending rows.
+   * Set only on that path, so `validationPendingReason` can name the data fix without having to
+   * pattern-match an error string it wrote itself.
+   */
+  skipped?: boolean;
 }
 
 export interface StateApplyResult {
@@ -431,14 +448,76 @@ export interface StateApplyResult {
  * So the row is written as soon as the batch has committed, describing exactly what is true then
  * (the key installed, none of the checks run yet), and amended when the checks are over.
  */
+/** The subset of StateApplyOptions the schema_log memoir writes need — nothing execution-only. */
+type SchemaLogFields = Pick<StateApplyOptions, 'actor' | 'gitRef' | 'planRef' | 'fromFingerprint' | 'fpVersion' | 'dirty'>;
+
+/**
+ * One row per unproven key, carrying the exact statement to re-run. Best-effort, like every
+ * other memoir write: failing to record why a key is pending must not mask that it is. Shared by
+ * both the normal path (checks run here) and the all-withheld early return (no checks run here,
+ * but the withheld ones are just as real a pending state and owe the same rows).
+ */
+async function recordPendingValidations(
+  runner: QueryRunner,
+  pendingValidations: readonly PendingValidation[],
+  options: SchemaLogFields,
+): Promise<void> {
+  for (const pending of pendingValidations) {
+    try {
+      await runner(renderSchemaLogInsert({
+        kind: 'state validate', sql: pending.sql,
+        outcome: `pending: ${pending.error}`,
+        actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
+        fromFingerprint: options.fromFingerprint,
+        fpVersion: options.fpVersion ?? FINGERPRINT_VERSION, dirty: options.dirty ?? false,
+      }));
+    } catch { /* the memoir is best-effort; the row already says what committed */ }
+  }
+}
+
 export async function applyGeneratedStatements(
   runner: QueryRunner,
   statements: string[],
   options: StateApplyOptions = {},
 ): Promise<StateApplyResult> {
   const classified = classifyGeneratedStatements(statements);
+  // Checks the caller withheld before calling. They are outstanding from the first line of this
+  // function: the outcome written before the batch already counts them, and they come back in the
+  // result whether or not any check actually ran here.
+  const skipped: PendingValidation[] = [...(options.skippedValidations ?? [])];
   if (classified.executable.length === 0) {
-    return { applied: false, classified, batchSql: '', pendingValidations: [] };
+    // No DDL to run — but a re-plan against keys a PREVIOUS apply already withheld still owes
+    // the audit trail a row: the promise (docs/cli.md) is every apply lands in schema_log, and
+    // an apply whose only content is "these keys are still unproven" is a real apply, not a
+    // no-op. Without this, re-running db:apply/db:plan against nothing but a withheld VALIDATE
+    // produces a `validation-pending` result the operator sees and a database that remembers
+    // nothing about it.
+    if (skipped.length > 0) {
+      const now = options.now ?? Date.now;
+      const started = now();
+      let logId: number | undefined;
+      // Same annotation the normal path folds in (a honoured lineage waiver, a proven drift
+      // origin) — an all-withheld apply is still the row a LATER apply's fast-forward proof
+      // reads, so it must carry the same note or that proof silently loses the annotation.
+      const note = options.descentNote?.();
+      const outcome = ['applied', note, `no schema change; ${skipped.length} constraint(s) still PENDING validation`]
+        .filter(Boolean).join(' — ');
+      try {
+        await runner(ENSURE_RECONCILER_SQL.join(';\n'));
+        const logRows = await runner(renderSchemaLogInsert({
+          kind: 'state apply', sql: '',
+          outcome,
+          actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
+          fromFingerprint: options.fromFingerprint,
+          fpVersion: options.fpVersion ?? FINGERPRINT_VERSION, dirty: options.dirty ?? false,
+          durationMs: now() - started,
+        }));
+        logId = logRows?.[0]?.id !== undefined ? Number(logRows[0].id) : undefined;
+      } catch { /* the memoir is best-effort — the caller's own result still names the debt */ }
+      await recordPendingValidations(runner, skipped, options);
+      return { applied: false, classified, batchSql: '', pendingValidations: skipped, ...(logId !== undefined ? { logId } : {}) };
+    }
+    return { applied: false, classified, batchSql: '', pendingValidations: skipped };
   }
 
   const now = options.now ?? Date.now;
@@ -499,7 +578,7 @@ export async function applyGeneratedStatements(
   // outcome says exactly that — this row is true at the instant it is written, not a prediction
   // of how the checks will go.
   const logRows = await runner(renderSchemaLogInsert({
-    kind: 'state apply', sql: batchSql, outcome: outcomeWith(validations.length),
+    kind: 'state apply', sql: batchSql, outcome: outcomeWith(validations.length + skipped.length),
     actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
     fromFingerprint: options.fromFingerprint,
     ...(landedAfterBatch ? { toFingerprint: landedAfterBatch } : {}),
@@ -511,7 +590,7 @@ export async function applyGeneratedStatements(
   // Every check is attempted, even after one fails: the operator is owed the COMPLETE list of
   // keys still unproven, not the first one. Each runs on its own, so one failure cannot take a
   // sibling's successful validation down with it.
-  const pendingValidations: PendingValidation[] = [];
+  const pendingValidations: PendingValidation[] = [...skipped];
   for (const statement of validations) {
     try {
       await runner(statement);
@@ -533,19 +612,7 @@ export async function applyGeneratedStatements(
     } catch { /* the memoir is best-effort; the row already says what committed */ }
   }
 
-  // One row per unproven key, carrying the exact statement to re-run. Best-effort, like every
-  // other memoir write: failing to record why a key is pending must not mask that it is.
-  for (const pending of pendingValidations) {
-    try {
-      await runner(renderSchemaLogInsert({
-        kind: 'state validate', sql: pending.sql,
-        outcome: `pending: ${pending.error}`,
-        actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,
-        fromFingerprint: options.fromFingerprint,
-        fpVersion: options.fpVersion ?? FINGERPRINT_VERSION, dirty: options.dirty ?? false,
-      }));
-    } catch { /* see above */ }
-  }
+  await recordPendingValidations(runner, pendingValidations, options);
 
   return { applied: true, classified, batchSql, pendingValidations, ...(logId !== undefined ? { logId } : {}) };
 }