@everystack/cli 0.4.45 → 0.4.46

package/src/cli/stage-read-consistency.ts

@@ -0,0 +1,128 @@
+/**
+ * The stage lane's read-consistency DETECTOR.
+ *
+ * WHAT CHANGED. Each introspection is now ONE `db:session` invoke — one container, one
+ * connection, one REPEATABLE READ transaction, one pinned `search_path`. The original
+ * defect (five catalog queries fanned across five ops-Lambda containers, assembling a
+ * snapshot out of two renderings of one schema) is gone at the source.
+ *
+ * WHAT REMAINS. A full read is TWO sessions: the state introspection, then the authz
+ * introspection. Each is internally consistent; the PAIR is not. Two sessions can be
+ * answered by two containers at two moments, so a schema that moves between them yields a
+ * fingerprint whose two halves describe different instants. Smaller than the defect it
+ * replaced — and still not a guarantee.
+ *
+ * So the stage lane reads TWICE and compares. What that buys, precisely:
+ *
+ * - Two DIFFERENT fingerprints prove the target moved under at least one read. That is a
+ *   refusal: the read is known bad, so nothing is minted and nothing is applied.
+ * - Two IDENTICAL fingerprints prove NOTHING. Both reads can be wrong the same way
+ *   whenever the thing that differs differs deterministically. The stage lane cannot
+ *   verify read consistency. It can only fail to detect its absence.
+ *
+ * The wording below is written to that distinction and must stay written to it.
+ * "fingerprint verified" is a claim this lane is not able to make.
+ *
+ * Refusals here are CLI-side and pre-dispatch — no ops-Lambda action runs, so
+ * there is no live connection to record them on. They match the other
+ * pre-dispatch refusals in db:apply (`--confirm` missing, `estimateOpsRuntimeFit`),
+ * which likewise print and exit; `everystack.schema_log` is written by the ops
+ * Lambda's db:apply action, for refusals that reach it.
+ */
+
+import type { AuthzContract } from './authz-contract.js';
+import type { SessionRunner } from './session.js';
+import { introspectContract } from './authz-contract.js';
+import { introspectSchema, type SchemaSnapshot } from './schema-introspect.js';
+import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog.js';
+import { fingerprintLive } from './schema-fingerprint.js';
+
+/** One complete read of a target's base state, with its content address. */
+export interface StageReadPair {
+  snapshot: SchemaSnapshot;
+  contract: AuthzContract;
+  /** sha256 of the canonical state — the same address db:plan / db:apply gate on. */
+  fingerprint: string;
+}
+
+export type StageReadResult =
+  /** The two reads agreed. `warning` is the honest caveat; print it. */
+  | { ok: true; state: StageReadPair; warning: string }
+  /** The two reads disagreed. `reason` is the refusal; print it and exit non-zero. */
+  | { ok: false; reason: string; first: string; second: string };
+
+/** One full read: state + authz, fingerprinted the way every gate fingerprints it. */
+async function readOnce(session: SessionRunner): Promise<StageReadPair> {
+  const snapshot = await introspectSchema(session);
+  const contract = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
+  return { snapshot, contract, fingerprint: fingerprintLive(snapshot, contract).hash };
+}
+
+/**
+ * The refusal: the two reads disagree, so at least one of them was assembled
+ * from more than one database. Names the cause, because "fingerprint mismatch"
+ * would send the operator hunting for schema drift that is not there.
+ */
+export function inconsistentContainersRefusal(first: string, second: string): string {
+  return [
+    `REFUSED (stage lane): the stage was read twice and the two reads disagree — ${first.slice(0, 12)} then ${second.slice(0, 12)}.`,
+    'Cause: on the stage lane the state read and the authz read are separate ops-Lambda invokes, so they can be answered by different containers at different moments. Either the target changed between the two reads, or inconsistent containers answered them, and the fingerprint computed from the pair describes no single real state.',
+    'Nothing was minted and nothing was applied. Re-run. If it repeats, the stage\'s ops Lambda is not serving one database — fix that before you plan or apply against it.',
+  ].join(' ');
+}
+
+/**
+ * The agreement case. NOT a pass — a non-detection. Every clause here is load
+ * bearing: this lane must never report that a fingerprint was verified, or that
+ * the read was consistent.
+ */
+export function inconsistentContainersNotDetected(): string {
+  return [
+    'stage lane: read twice, inconsistent containers not detected.',
+    'This is a DETECTOR, not a verification — the stage lane cannot verify read consistency.',
+    'Two agreeing reads can both be wrong: anything that differs deterministically between containers produces the same wrong answer both times.',
+    'Treat this fingerprint as UNVERIFIED; the direct lane (--database-url, one session) is the only lane that reads a single database.',
+  ].join(' ');
+}
+
+/**
+ * The refusal a DESTRUCTIVE plan gets on the stage lane, before anything runs.
+ * The double read cannot lift this: a detector that can miss is not a basis for
+ * dropping data. The destructive ceremony lives on the direct lane.
+ */
+export function stageDestructiveRefusal(
+  shape: string,
+  planPath: string,
+  stage: string | undefined,
+): string {
+  const takeIt = `everystack db:backup${stage ? ` --stage ${stage}` : ''}`;
+  return [
+    `REFUSED (stage lane, DESTRUCTIVE plan — ${shape}): the stage lane cannot guarantee read consistency.`,
+    'A full read is two ops-Lambda invokes (state, then authz), so the fingerprint the concurrency lock gates on can still be assembled from two containers at two moments. A plan that loses data may not ride a read that cannot be verified.',
+    `Run destructive applies over a direct connection with the full ceremony: ${takeIt}, then everystack db:apply --plan ${planPath} --database-url <url> --confirm --snapshot-ref <id>.`,
+  ].join(' ');
+}
+
+/**
+ * Read the target twice, sequentially, and compare the two fingerprints.
+ *
+ * Sequential on purpose — two reads issued concurrently would interleave their
+ * invokes across the same container pool and could land the SAME collage twice,
+ * which is the one outcome the detector must not manufacture for itself.
+ *
+ * Callers: the STAGE lane only. The direct lane reads once, over one session,
+ * and must not pay this.
+ */
+export async function readStageStateTwice(session: SessionRunner): Promise<StageReadResult> {
+  const first = await readOnce(session);
+  const second = await readOnce(session);
+  if (first.fingerprint !== second.fingerprint) {
+    return {
+      ok: false,
+      reason: inconsistentContainersRefusal(first.fingerprint, second.fingerprint),
+      first: first.fingerprint,
+      second: second.fingerprint,
+    };
+  }
+  return { ok: true, state: second, warning: inconsistentContainersNotDetected() };
+}

package/src/cli/state-apply.ts

@@ -20,6 +20,7 @@
 import { execSync } from 'node:child_process';
 import type { ModelDescriptor } from '@everystack/model';
 import { introspectContract, type AuthzContract, type QueryRunner } from './authz-contract.js';
+import type { SessionRunner } from './session.js';
 import { introspectSchema, type SchemaSnapshot } from './schema-introspect.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog.js';
 import { generateMigrationSql, HELD_DROP_PREFIX } from './migration-generate.js';
@@ -377,6 +378,7 @@ export interface StateSyncOutcome {
  */
 export async function applyStateAndVerify(
   runner: QueryRunner,
+  session: SessionRunner,
   models: ModelDescriptor[],
   statements: string[],
   current: SchemaSnapshot,
@@ -396,8 +398,8 @@ export async function applyStateAndVerify(
 
   const result = await applyGeneratedStatements(runner, statements, { ...options, fromFingerprint });
 
-  const snapshot = await introspectSchema(runner);
-  const contract = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+  const snapshot = await introspectSchema(session);
+  const contract = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
   const toFingerprint = fingerprintLive(snapshot, contract).hash;
   if (result.logId !== undefined) {
     await runner(renderSchemaLogFingerprintUpdate(result.logId, toFingerprint));

package/src/cli/swap-execute.ts

@@ -21,6 +21,7 @@
 
 import type { ModelDescriptor } from '@everystack/model';
 import type { QueryRunner } from './authz-contract.js';
+import type { SessionRunner } from './session.js';
 import { renderSchemaSwap, dropRetiringSql } from './schema-swap.js';
 
 /** One validator's result. A `fatal` (default) failure rolls back; a `warn` failure is surfaced only. */
@@ -105,7 +106,7 @@ export interface ExecuteSwapOptions {
    * identities. Without it the next db:reconcile sees the whole layer as drift and rebuilds it —
    * an expensive, ACCESS EXCLUSIVE no-op that surfaces days later on an unrelated run.
    */
-  recordProvenance?: (runner: QueryRunner) => Promise<void>;
+  recordProvenance?: (runner: QueryRunner, session: SessionRunner) => Promise<void>;
 }
 
 /** One table's landed-vs-live count, the intrinsic post-swap assertion's unit. */
@@ -417,7 +418,7 @@ async function countRows(runner: QueryRunner, schema: string, table: string): Pr
   return Number(rows[0]?.n ?? 0);
 }
 
-export async function executeSwap(runner: QueryRunner, opts: ExecuteSwapOptions): Promise<SwapResult> {
+export async function executeSwap(runner: QueryRunner, session: SessionRunner, opts: ExecuteSwapOptions): Promise<SwapResult> {
   const log = opts.log ?? (() => {});
   // 1. Fingerprint gate — declared-vs-declared: does the artifact and the target agree on the shape.
   if (opts.artifactFingerprint !== opts.declaredFingerprint) {
@@ -639,7 +640,7 @@ export async function executeSwap(runner: QueryRunner, opts: ExecuteSwapOptions)
   //    prevents rather than something it can break.
   if (opts.recordProvenance) {
     try {
-      await opts.recordProvenance(runner);
+      await opts.recordProvenance(runner, session);
     } catch (err: any) {
       log(`WARNING: the swap succeeded but recording provenance failed: ${String(err?.message ?? err)}. `
         + `The derived layer is live and correct; the next db:reconcile will rebuild it needlessly. `

package/src/cli/search-path.ts

@@ -1,51 +0,0 @@
-/**
- * search-path — the canonical introspection baseline.
- *
- * Every expression PostgreSQL deparses on introspection — column defaults
- * (`pg_get_expr`), CHECK constraints, index expressions, generated columns,
- * view/matview bodies (`pg_get_viewdef`), function bodies — renders its schema
- * qualification RELATIVE to the session `search_path`. So the SAME schema reads
- * differently depending on the ambient path: with a non-public schema on the
- * path a reference to it renders BARE (`nextval('x_seq')`), off the path it
- * renders QUALIFIED (`nextval('stats.x_seq')`). The declared state is always
- * canonical (public bare, non-public qualified), so a non-default session or
- * DB-level `search_path` makes every deparsed expression read as false drift.
- *
- * The fix is to CAPTURE under a fixed canonical path, once, at the introspection
- * boundary — one guard for the whole class (defaults, checks, indexes, bodies),
- * present and future. The baseline is `public`: it renders public-bare and
- * non-public-qualified, matching the declared compile exactly (verified against
- * PostgreSQL 16). It must be an EXPLICIT value — `RESET` / `SET … TO DEFAULT`
- * inherit an `ALTER DATABASE/ROLE … SET search_path` override (the very thing
- * that triggers the bug), so they are NOT canonical baselines.
- */
-
-import type { QueryRunner } from './authz-contract.js';
-
-/** The canonical introspection search_path — explicit, override-proof, declared-matching. */
-export const CANONICAL_SEARCH_PATH_SQL = 'SET search_path = public';
-
-/**
- * Run `fn` with the connection's search_path pinned to the canonical baseline, so every
- * expression it deparses is captured in the declared-matching form regardless of the
- * ambient path, then RESET to the connection's default afterward. RESET restores the
- * database/role default — which for the case this fixes (an `ALTER DATABASE … SET
- * search_path` override) is exactly the override, so a fresh connection sees no change.
- * It deliberately does NOT preserve a caller's transient session/transaction-local SET:
- * restoring a captured `SET LOCAL` value session-wide would leak it (e.g. the reconcile
- * apply's create-time wide path), and no everystack caller relies on a hand-set path
- * surviving introspection.
- *
- * Effective on a persistent single connection (the direct `createUrlRunner`, `max: 1`);
- * over a per-call pooled runner the SET does not persist, but that path already renders
- * canonically unless the database itself carries a search_path override.
- */
-export async function withCanonicalSearchPath<T>(run: QueryRunner, fn: () => Promise<T>): Promise<T> {
-  await run(CANONICAL_SEARCH_PATH_SQL);
-  try {
-    return await fn();
-  } finally {
-    // Best-effort: a failure here must not mask fn's result.
-    try { await run('RESET search_path'); } catch { /* connection may be gone */ }
-  }
-}