@everystack/cli 0.4.44 → 0.4.46

package/src/cli/commands/db-reconcile.ts

@@ -46,12 +46,13 @@ import {
   ENSURE_RECONCILER_SQL,
 } from '../derived-apply.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
+import { borrowedSessionRunner, type SessionRunner } from '../session.js';
 import { resolveOperatorUrlViaStage } from '../direct-venue.js';
 import { withMutationLease, MutationLeaseError } from '../mutation-lease.js';
 import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived.js';
 import { currentGitRef } from '../state-apply.js';
 import { resolveConfig, opsFunction } from '../config.js';
-import { invokeAction } from '../aws.js';
+import { invokeAction, lambdaQueryRunner, lambdaSessionRunner } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
 
 // ---------------------------------------------------------------------------
@@ -111,9 +112,10 @@ export function isTransactionalBatch(statements: string[]): boolean {
 
 export async function executeReconcile(
   runner: QueryRunner,
+  session: SessionRunner,
   options: ExecuteOptions = {},
 ): Promise<ReconcileRun> {
-  const live = await introspectDerived(runner);
+  const live = await introspectDerived(session);
   const parsed = { objects: options.declared ?? [], warnings: [] as string[] };
   const plan = planReconcile(parsed, live, options);
   const rendered = renderReconcileSql(plan, parsed.objects);
@@ -189,11 +191,14 @@ export async function executeReconcile(
       }
     }
 
-    // Re-read the catalog so provenance records the def hashes of what NOW exists, not what we hoped
-    // would exist. Inside the transaction this reads the batch's own not-yet-committed writes.
-    // introspectDerived pins the canonical search_path itself, so the defHash it records is stable
-    // regardless of the create-time wide path above (or any ambient override) — no manual reset here.
-    const after = await introspectDerived(runner);
+    // Re-read the catalog so provenance records the def hashes of what NOW exists, not what we
+    // hoped would exist. Inside the transaction this reads the batch's own not-yet-committed
+    // writes, so the read must BORROW that transaction: a session of its own would open a nested
+    // BEGIN and COMMIT this one out from under the bookkeeping below. The borrowed session pins
+    // the canonical search_path inside a savepoint it always rolls back, so the def hashes are
+    // stable regardless of the create-time wide path above — and that wide path survives the read.
+    // The unwrapped path has no transaction to borrow, so it takes a session of its own.
+    const after = await introspectDerived(atomic ? borrowedSessionRunner(runner) : session);
     const liveById = new Map(after.objects.map((o) => [o.identity, o]));
     const srcById = new Map(parsed.objects.map((o) => [o.identity, o]));
 
@@ -347,15 +352,6 @@ export function checkFails(plan: ReconcilePlan): boolean {
 // The CLI shell.
 // ---------------------------------------------------------------------------
 
-/** A QueryRunner backed by the ops Lambda `db:query` action (read-only). */
-function lambdaRunner(region: string, fn: string): QueryRunner {
-  return async (sql: string) => {
-    const result: any = await invokeAction(region, fn, 'db:query', { sql });
-    if (result?.error) throw new Error(`Query failed: ${result.error}`);
-    return result?.rows ?? [];
-  };
-}
-
 export async function dbReconcileCommand(flags: Record<string, string>): Promise<void> {
   const apply = flags.apply === 'true';
   const check = flags.check === 'true';
@@ -493,25 +489,27 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
       run = { plan: result.plan, applied: result.applied, statements: result.statements ?? [], refusal: result.refusal ?? undefined };
     } else {
       let runner: QueryRunner;
+      let session: SessionRunner;
       // A write over a direct connection (--database-url or --direct) takes the mutation
       // lease; a read-only stage dry-run over the ops Lambda does not (reads never lease).
       let leased = false;
       if (dbSource.kind === 'url') {
         step(connectingVia(dbSource));
-        ({ runner, end } = await createUrlRunner(dbSource.url));
+        ({ runner, session, end } = await createUrlRunner(dbSource.url));
         leased = apply;
       } else {
         step('Resolving deployed config...');
         const config = await resolveConfig(flags.stage);
-        runner = lambdaRunner(config.region, opsFunction(config));
+        runner = lambdaQueryRunner(config.region, opsFunction(config));
+        session = lambdaSessionRunner(config.region, opsFunction(config));
       }
       run = leased
         ? await withMutationLease(
             runner,
             { verb: 'db:reconcile', actor: process.env.USER ?? 'unknown' },
-            () => executeReconcile(runner, reconcileOptions),
+            () => executeReconcile(runner, session, reconcileOptions),
           )
-        : await executeReconcile(runner, reconcileOptions);
+        : await executeReconcile(runner, session, reconcileOptions);
     }
 
     if (flags.json === 'true') {

package/src/cli/commands/db-swap.ts

@@ -31,6 +31,7 @@ import { pairedDerivedSchemas, renderPairedDerivedBuild, renderSwapSchemaUsage,
 import { introspectDerived } from '../derived-introspect.js';
 import { legacyFunctionIdentity } from '../pg-argtypes.js';
 import { createUrlRunner } from '../db-source.js';
+import { borrowedSessionRunner, type SessionRunner } from '../session.js';
 import type { QueryRunner } from '../authz-contract.js';
 import { executeSwap, type SwapVerdict } from '../swap-execute.js';
 import { startHeartbeat, humanElapsed } from '../swap-heartbeat.js';
@@ -626,14 +627,14 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
   }
   const artifactFingerprint = artifact.fingerprint;
 
-  const { runner, end } = await createUrlRunner(url);
+  const { runner, session, end } = await createUrlRunner(url);
   try {
     step(`Swapping ${schema} — gate, land incoming, atomic swap, verify...`);
     // One operator mutates a database at a time — the swap is a whole-schema replacement.
     const res = await withMutationLease(
       runner,
       { verb: 'db:swap', actor: process.env.USER ?? 'unknown' },
-      () => executeSwap(runner, {
+      () => executeSwap(runner, session, {
         models, schema,
         artifactFingerprint,
         declaredFingerprint,
@@ -659,8 +660,8 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
         // later, for an unrelated edit — sees the whole layer as drift and rebuilds it under
         // ACCESS EXCLUSIVE. The objects are correct; only the bookkeeping was missing.
         recordProvenance: paired.length
-          ? async (r) => {
-              const live = await introspectDerived(r);
+          ? async (r, s) => {
+              const live = await introspectDerived(s);
               const prov = renderPairedProvenance(declaredDerivedObjects, live.objects, schema, paired);
               for (const st of prov.statements) await r(st);
               if (prov.recorded.length === 0) {

package/src/cli/commands/db-sync.ts

@@ -48,6 +48,7 @@ import { fingerprintModels } from '../schema-fingerprint.js';
 import { compileDrizzleSource } from '../schema-source.js';
 import type { SourceFile } from '../derived-source.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
+import { borrowedSessionRunner, type SessionRunner } from '../session.js';
 import { planBackfills, readBackfillLog } from '../backfill.js';
 import { resolveModelsPath } from '../models-path.js';
 import { executeReconcile, buildReconcileReport, type ReconcileRun } from './db-reconcile.js';
@@ -113,26 +114,27 @@ export interface SyncRun {
  */
 export async function executeSync(
   runner: QueryRunner,
+  session: SessionRunner,
   models: ModelDescriptor[],
   options: SyncOptions = {},
   hooks: SyncHooks = {},
 ): Promise<SyncRun> {
-  const current = await introspectSchema(runner);
-  const liveAuthz = await introspectContract(runner, contractFunctionRow, FUNCTIONS_SQL);
+  const current = await introspectSchema(session);
+  const liveAuthz = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
   const statements = generateMigrationSql(models, current, {
     allowDrops: options.allowDrops, liveAuthz, sequences: options.sequences,
     governedRoles: options.governedRoles,
   });
   hooks.onStatePlan?.(statements, classifyGeneratedStatements(statements));
 
-  const state = await applyStateAndVerify(runner, models, statements, current, liveAuthz, {
+  const state = await applyStateAndVerify(runner, session, models, statements, current, liveAuthz, {
     allowDrops: options.allowDrops, sequences: options.sequences,
     actor: options.actor, gitRef: options.gitRef, now: options.now,
   });
   hooks.onStateDone?.(state);
 
   // The declared derived layer is the one compute stream; nothing declared = skipped.
-  const compute = !options.declared?.length ? null : await executeReconcile(runner, {
+  const compute = !options.declared?.length ? null : await executeReconcile(runner, session, {
     apply: true,
     baseline: options.baseline,
     rebaseline: options.rebaseline,
@@ -303,11 +305,12 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
   }
 
   step(connectingVia(dbSource));
-  const { runner, end } = await createUrlRunner(dbSource.url);
+  const { runner, session, end } = await createUrlRunner(dbSource.url);
 
   try {
     const run = await executeSync(
       runner,
+      session,
       models,
       {
         declared: declaredDb?.objects,

package/src/cli/db-build.ts

@@ -107,10 +107,10 @@ export async function buildIntoDatabase(
   models: ModelDescriptor[],
   options: BuildOptions = {},
 ): Promise<BuildResult> {
-  const { runner, end } = await createUrlRunner(url);
+  const { runner, session, end } = await createUrlRunner(url);
   try {
     const createdRoles = await ensureContractRoles(runner, models);
-    const run = await executeSync(runner, models, {
+    const run = await executeSync(runner, session, models, {
       declared: options.declared,
       sequences: options.sequences,
       actor: options.actor ?? 'db-build',

package/src/cli/db-source.ts

@@ -25,6 +25,7 @@
  */
 
 import type { QueryRunner } from './authz-contract.js';
+import { buildSearchPathSql, type SessionRunner, type SessionResult } from './session.js';
 
 export type DbSource =
   | { kind: 'url'; url: string; from: 'flag' | 'env' | 'admin-env' | 'operator' }
@@ -65,10 +66,61 @@ export function connectingVia(source: Extract<DbSource, { kind: 'url' }>): strin
 
 export interface UrlRunner {
   runner: QueryRunner;
+  /**
+   * The direct lane's `SessionRunner` — N statements in ONE postgres.js transaction on
+   * the single connection. The stage lane's twin is `lambdaSessionRunner` (one invoke,
+   * one container); both honor the same ordering, `SET LOCAL` and `allowFailure` rules,
+   * so a caller typed against `SessionRunner` reads identically on either venue.
+   */
+  session: SessionRunner;
   /** Close the client so the process can exit cleanly. */
   end: () => Promise<void>;
 }
 
+/**
+ * Build a `SessionRunner` over a postgres.js client whose pool is a single connection.
+ *
+ * `sql.begin` holds that one connection for the whole callback, so every statement here
+ * shares a session by construction. The `searchPath` pin is `SET LOCAL` (it reverts with
+ * the transaction, never outliving its command) and consumes no result slot.
+ *
+ * An `allowFailure` statement rides `tx.savepoint`, the DRIVER's savepoint — not a
+ * hand-issued `SAVEPOINT` / `ROLLBACK TO SAVEPOINT` pair. postgres.js records any query
+ * error raised inside a transaction scope and re-throws it after the callback returns, so
+ * catching the error ourselves recovers the database and still loses the session. Its
+ * savepoint opens a nested scope with its own error bookkeeping, which is the only shape
+ * that survives. (Proven on a live PostgreSQL: the hand-rolled version passed against a
+ * fake and failed against the driver.)
+ */
+export function sessionRunnerOver(sql: any): SessionRunner {
+  return async (statements, opts) => {
+    const stmts = statements.map((s) => (typeof s === 'string' ? { sql: s } : s));
+    const results: SessionResult[] = [];
+    await sql.begin(async (tx: any) => {
+      if (opts?.isolation) await tx.unsafe(`SET TRANSACTION ISOLATION LEVEL ${opts.isolation}`);
+      if (opts?.readOnly) await tx.unsafe('SET TRANSACTION READ ONLY');
+      if (opts?.searchPath !== undefined) {
+        await tx.unsafe(buildSearchPathSql(String(opts.searchPath)));
+      }
+      for (const stmt of stmts) {
+        if (!stmt.allowFailure) {
+          results.push(Array.from(await tx.unsafe(stmt.sql)));
+          continue;
+        }
+        try {
+          results.push(
+            await tx.savepoint(async (sp: any) => Array.from(await sp.unsafe(stmt.sql))),
+          );
+        } catch (err: any) {
+          results.push({ everystackSessionError: true, message: err?.message || String(err) });
+        }
+      }
+    });
+    return results;
+  };
+}
+
+
 /**
  * Load the postgres.js driver, or explain how to get it. Shared by every direct-connection
  * runner below so the missing-driver instructions can never drift between them.
@@ -101,6 +153,7 @@ export async function createUrlRunner(
   const sql = postgres(url, { max: 1, max_lifetime: null, onnotice: () => {}, ...sslDefaults(url) });
   return {
     runner: async (query: string) => Array.from(await sql.unsafe(query)),
+    session: sessionRunnerOver(sql),
     end: () => sql.end({ timeout: 5 }),
   };
 }
@@ -135,6 +188,8 @@ export async function createUrlPipelineRunner(
 export interface UrlProbeRunner {
   /** Read-only introspection, for the contract pull/diff. */
   runner: QueryRunner;
+  /** N statements on this one connection in one transaction — see sessionRunnerOver. */
+  session: SessionRunner;
   /** The self-reverting red-team probe. See `probe` below. */
   probe: (setup: string, read: string) => Promise<any[]>;
   /** Close the client so the process can exit cleanly. */
@@ -166,6 +221,7 @@ export async function createUrlProbeRunner(
   const sql = postgres(url, { max: 1, max_lifetime: null, onnotice: () => {}, ...sslDefaults(url) });
   return {
     runner: async (query: string) => Array.from(await sql.unsafe(query)),
+    session: sessionRunnerOver(sql),
     probe: async (setup: string, read: string) => {
       let rows: any[] = [];
       try {

package/src/cli/derived-introspect.ts

@@ -20,7 +20,7 @@
 import { createHash } from 'node:crypto';
 import { IGNORED_SCHEMAS, type QueryRunner } from './authz-contract.js';
 import { normalizeSql, type DerivedKind } from './derived-source.js';
-import { withCanonicalSearchPath } from './search-path.js';
+import { INTROSPECTION_SESSION, rowsOrEmpty, type SessionRunner } from './session.js';
 
 export interface LiveObject {
   kind: DerivedKind;
@@ -591,30 +591,31 @@ export function assembleDerivedCatalog(rows: DerivedRows): DerivedCatalog {
  * injected runner; a missing provenance table (first run against a database
  * the reconciler has never touched) folds to an empty claims list.
  */
-export async function introspectDerived(run: QueryRunner): Promise<DerivedCatalog> {
-  // View/matview/function bodies deparse relative to the search_path (`pg_get_viewdef`
-  // renders a ref bare while its schema is in scope, qualified once off). Pin the
-  // canonical baseline so the recorded def hash is stable across runs and paths — this
-  // also subsumes the reconcile apply's pre-introspection reset. See search-path.ts.
-  return withCanonicalSearchPath(run, async () => {
-    const [relations, functions, indexes, depends, triggers, grants] = await Promise.all([
-      run(DERIVED_RELATIONS_SQL), run(DERIVED_FUNCTIONS_SQL), run(MATVIEW_INDEXES_SQL), run(DERIVED_DEPENDS_SQL),
-      run(DERIVED_TRIGGERS_SQL), run(DERIVED_GRANTS_SQL),
-    ]);
-    let provenance: ProvenanceRawRow[] = [];
-    try {
-      provenance = (await run(PROVENANCE_SQL)) as ProvenanceRawRow[];
-    } catch {
-      // everystack.derived_provenance does not exist yet — nothing has been reconciled.
-    }
-    return assembleDerivedCatalog({
-      relations: relations as RelationRow[],
-      functions: functions as FunctionRow[],
-      indexes: indexes as IndexDefRow[],
-      depends: depends as DependsRow[],
-      triggers: triggers as TriggerRow[],
-      grants: grants as GrantAclRow[],
-      provenance,
-    });
+export async function introspectDerived(session: SessionRunner): Promise<DerivedCatalog> {
+  // ONE session: view/matview/function bodies deparse relative to the search_path
+  // (`pg_get_viewdef` renders a ref bare while its schema is in scope, qualified once off),
+  // so the recorded def hash is only stable if every body is captured under one pinned path
+  // at one moment.
+  //
+  // The provenance read is `allowFailure`: `everystack.derived_provenance` does not exist
+  // until something has been reconciled, and its absence is an ANSWER (no claims), not a
+  // failure. Before the session it was a try/catch, which is the same intent expressed the
+  // only way a one-statement-at-a-time runner could — by being willing to lose the session.
+  const [relations, functions, indexes, depends, triggers, grants, provenance] = await session(
+    [
+      DERIVED_RELATIONS_SQL, DERIVED_FUNCTIONS_SQL, MATVIEW_INDEXES_SQL, DERIVED_DEPENDS_SQL,
+      DERIVED_TRIGGERS_SQL, DERIVED_GRANTS_SQL,
+      { sql: PROVENANCE_SQL, allowFailure: true },
+    ],
+    INTROSPECTION_SESSION,
+  );
+  return assembleDerivedCatalog({
+    relations: relations as RelationRow[],
+    functions: functions as FunctionRow[],
+    indexes: indexes as IndexDefRow[],
+    depends: depends as DependsRow[],
+    triggers: triggers as TriggerRow[],
+    grants: grants as GrantAclRow[],
+    provenance: rowsOrEmpty(provenance) as ProvenanceRawRow[],
   });
 }

package/src/cli/derived-lint.ts

@@ -26,9 +26,10 @@
  * grant.
  */
 
+import { isColumnAbility } from '@everystack/model';
 import type {
   ModelDescriptor, DerivedDescriptor, ViewDescriptor, MaterializedViewDescriptor,
-  FunctionDescriptor, DependsOnRef, Ability,
+  FunctionDescriptor, DependsOnRef,
 } from '@everystack/model';
 import { parseQualified } from './derived-source.js';
 
@@ -47,11 +48,6 @@ function isModelRef(ref: DependsOnRef): ref is ModelDescriptor {
   return 'table' in ref;
 }
 
-/** The column-scoped self read — same predicate as the table grant compiler. */
-function isColumnRead(a: Ability): boolean {
-  return a.action === 'read' && Boolean(a.condition.owner) && Boolean(a.condition.columns?.length);
-}
-
 /**
  * Does the table's grant compile give `role` SELECT (full or column-scoped)?
  *
@@ -65,8 +61,11 @@ function isColumnRead(a: Ability): boolean {
  */
 export function tableReaches(m: ModelDescriptor, role: string): boolean {
   for (const a of m.abilities) {
-    if (isColumnRead(a)) {
-      if ((a.condition.role ?? 'authenticated') === role) return true;
+    if (isColumnAbility(a)) {
+      // Only the READ half reaches: a column-scoped update compiles to `UPDATE (cols)`
+      // and no SELECT, so counting it as reach would pass an invoker view the database
+      // then refuses at runtime — the false-negative this gate's docstring warns about.
+      if (a.action === 'read' && (a.condition.role ?? 'authenticated') === role) return true;
       continue;
     }
     if (a.action !== 'read' && a.action !== 'manage') continue;

package/src/cli/edge-plan.ts

@@ -31,7 +31,7 @@ import type { AuthzContract } from './authz-contract.js';
 import { generateMigrationSql, unmodeledTables } from './migration-generate.js';
 import { compileTableContract } from './authz-compile.js';
 import { classifyGeneratedStatements, classifyDestructive, partitionStatements, renderStatementHistogram } from './state-apply.js';
-import { fingerprintLive, fingerprintState, fingerprintModels, stableStringify } from './schema-fingerprint.js';
+import { fingerprintLive, fingerprintState, fingerprintModels, governedRolesForModels, stableStringify, compareStoredFingerprint, formatChangedMessage, FINGERPRINT_VERSION } from './schema-fingerprint.js';
 import { compileDeclaredState } from './declared-diff.js';
 import { compileTableRenames, compileTableMoves } from './schema-compile.js';
 
@@ -61,8 +61,27 @@ export interface EdgePlan {
   v: number;
   /** The target's exact live fingerprint at mint time — the lock. */
   fromFingerprint: string;
-  /** The predicted live fingerprint after apply — exact, unmodeled-aware. */
+  /**
+   * The FINGERPRINT_VERSION the endpoints were computed under. Stored beside the hashes so a
+   * plan minted under an older canonical form REFUSES as a format change rather than reporting
+   * drift that no edit could explain. Absent on plans minted before v4.
+   */
+  fpVersion?: number;
+  /**
+   * The predicted live fingerprint after apply — exact, unmodeled-aware, and
+   * GOVERNED: hashed through the models' governed-role set (`governedRoles`
+   * below), because it is a declared-vs-live claim. Compare it only against
+   * `governedLiveFingerprint` computed with the same set — never against the
+   * raw `from` flavor.
+   */
   toFingerprint: string;
+  /**
+   * The governed-role set `to` was hashed under, sorted — carried on the plan
+   * so every apply venue verifies with the exact set the mint used. Absent on
+   * plans minted before this field existed (those predate the governed `to`
+   * and verify raw, as they were minted).
+   */
+  governedRoles?: string[];
   /** The models-only fingerprint — context for the strong claim. Equals `to` when nothing is unmodeled. */
   declaredFingerprint: string;
   /** The edge, in db:generate's statement grammar (no held drops — mint refuses them). */
@@ -72,6 +91,21 @@ export interface EdgePlan {
   destructive: number;
   classification: PlanClassification;
   notices: number;
+  /**
+   * WHY each authorization statement exists, one entry per statement — the per-statement half
+   * of the aggregate the summary prints.
+   *
+   * Optional because it is re-derived against LIVE at mint time, so a plan minted without a
+   * reachable database (or before this field existed) simply has none. Never trusted as a
+   * stored claim: like the counts, it describes the target as it was when the plan was cut.
+   */
+  adoption?: { table: string; subject: string; cls: string; why: string }[];
+  /**
+   * Tables this plan leaves with no surviving read path — resolved at mint against the LIVE
+   * contract, which is the only moment both halves of that question are in hand. Absent on
+   * plans minted before this field existed; the summary falls back to the text-only reading.
+   */
+  dark?: string[];
   /** Live tables no model declares — untouched by the edge, riding into `to` as-is. */
   unmodeled: string[];
   gitRef: string | null;
@@ -108,8 +142,14 @@ export function predictLiveFingerprint(
   models: ModelDescriptor[],
   snapshot: SchemaSnapshot,
   contract: AuthzContract,
-  opts: { schema?: string } = {},
+  opts: { schema?: string; governedRoles?: ReadonlySet<string> } = {},
 ): string {
+  // The prediction is a DECLARED-vs-live comparison, so it must hash through the
+  // models' governed set — the live side of any comparison against it must use
+  // the same set (see governedLiveFingerprint). Unfiltered, every ride-through
+  // table's foreign grants poison the endpoint and verify-after can never pass
+  // on a brownfield target.
+  const governedRoles = opts.governedRoles ?? governedRolesForModels(models);
   const declared = compileDeclaredState(models, { schema: opts.schema });
   const declaredTables = new Set(declared.snapshot.tables.map((t) => t.table));
   const currentNames = new Set(snapshot.tables.map((t) => t.table));
@@ -144,7 +184,21 @@ export function predictLiveFingerprint(
     ...declared.contract.tables,
     ...contract.tables.filter((t) => ridesThrough(t.table)),
   ];
-  return fingerprintState(mergedSnapshot, mergedAuthz).hash;
+  return fingerprintState(mergedSnapshot, mergedAuthz, { governedRoles }).hash;
+}
+
+/**
+ * The live half of every declared-vs-live comparison: the target's state hashed
+ * through the SAME governed set as the prediction. `predicted === governedLive`
+ * is the declares-test; comparing a prediction against an UNFILTERED live hash
+ * is a category error that can never converge on a brownfield database.
+ */
+export function governedLiveFingerprint(
+  snapshot: SchemaSnapshot,
+  contract: AuthzContract,
+  governedRoles: ReadonlySet<string>,
+): string {
+  return fingerprintState(snapshot, contract.tables, { governedRoles }).hash;
 }
 
 /**
@@ -187,11 +241,21 @@ export function mintEdgePlan(
   const breakdown = partitionStatements(classified.executable, { declaredGrantees });
   const destructive = breakdown.drops.length + breakdown.narrowings.length + breakdown.strips.length;
 
+  // The plan's two endpoints are two different FLAVORS, deliberately:
+  //  - `from` is the RAW live hash (everything introspected) — the concurrency
+  //    lock and the backup-stamp chain (backup.fp == plan.from) compare
+  //    live-vs-live and must stay computable with no models in hand.
+  //  - `to` is the GOVERNED hash — a declared-vs-live claim, filtered through
+  //    the models' governed set, which rides ON the plan so every venue
+  //    (direct, ops Lambda) verifies with the set the mint used.
+  const governedRoles = governedRolesForModels(models, opts.governedRoles);
   return {
     v: PLAN_VERSION,
     fromFingerprint: fingerprintLive(snapshot, contract).hash,
-    toFingerprint: predictLiveFingerprint(models, snapshot, contract, { schema: opts.schema }),
+    fpVersion: FINGERPRINT_VERSION,
+    toFingerprint: predictLiveFingerprint(models, snapshot, contract, { schema: opts.schema, governedRoles }),
     declaredFingerprint: fingerprintModels(models, { schema: opts.schema }).hash,
+    governedRoles: [...governedRoles].sort(),
     statements,
     executable: classified.executable.length,
     destructive,
@@ -206,6 +270,10 @@ export function mintEdgePlan(
       ...(breakdown.unclassified.length > 0 ? { unclassified: breakdown.unclassified.length } : {}),
     },
     notices: classified.notices.length,
+    // Resolved HERE because this is the only place that holds both the edge and the live
+    // contract. The summary is rendered later from the plan alone, and answering "does a read
+    // survive?" from statement text is what produced three false positives on a real plan.
+    dark: tablesLeftWithoutARead(statements, contract),
     unmodeled: unmodeledTables(models, snapshot),
     gitRef: opts.gitRef ?? null,
     mintedBy: opts.actor ?? null,
@@ -220,25 +288,58 @@ export function mintEdgePlan(
  * enabled and the grant is still there, so the table returns ZERO rows to that role. On a real
  * adoption plan that was 11 tables, including the users table, and it printed no notice at all.
  *
- * Deliberately conservative: it only names a table when the plan drops a read-admitting policy
- * and adds none back for that table. It cannot know what other policies exist live, so it
- * under-reports rather than crying wolf.
+ * Deliberately conservative: it names a table only when NO read path survives the plan for any
+ * role, so it under-reports rather than crying wolf. Pass the LIVE contract to get that
+ * question answered properly — without it, a `DROP POLICY` statement does not say which
+ * command it policed and the fallback can only count drops.
  */
-export function tablesLeftWithoutARead(statements: readonly string[]): string[] {
-  const dropped = new Map<string, number>();
-  const created = new Set<string>();
+export function tablesLeftWithoutARead(statements: readonly string[], live?: AuthzContract): string[] {
+  const droppedByTable = new Map<string, Set<string>>();
+  const createdRead = new Set<string>();
+  const touched = new Set<string>();
+
   for (const statement of statements) {
     const head = (statement.split('\n').find((l) => l.trim() !== '' && !l.trim().startsWith('--')) ?? '').trim();
-    let m = /^DROP\s+POLICY\s+(?:IF\s+EXISTS\s+)?\S+\s+ON\s+(\S+?);?$/i.exec(head);
+    let m = /^DROP\s+POLICY\s+(?:IF\s+EXISTS\s+)?(\S+)\s+ON\s+(\S+?);?$/i.exec(head);
     if (m) {
-      dropped.set(m[1], (dropped.get(m[1]) ?? 0) + 1);
+      touched.add(m[2]);
+      const names = droppedByTable.get(m[2]) ?? new Set<string>();
+      names.add(m[1]);
+      droppedByTable.set(m[2], names);
       continue;
     }
     m = /^CREATE\s+POLICY\s+\S+\s+ON\s+(\S+)/i.exec(head);
     // Only a SELECT-admitting policy restores a read; an INSERT-only policy does not.
-    if (m && /\bFOR\s+(SELECT|ALL)\b/i.test(head)) created.add(m[1]);
+    if (m && /\bFOR\s+(SELECT|ALL)\b/i.test(head)) createdRead.add(m[1]);
+  }
+
+  // Without the live contract this can only count drops, and a DROP POLICY statement does not
+  // carry the command it policed. That is the old behaviour, kept for plans minted before the
+  // contract was threaded through: it OVER-reports, naming a table whose dropped policy was an
+  // UPDATE and whose reads were never touched.
+  if (!live) return [...droppedByTable.keys()].filter((t) => !createdRead.has(t)).sort();
+
+  // With it, ask the real question: does ANY policy admitting SELECT survive this plan? A
+  // table is dark only when none does — not merely because some policy on it was dropped.
+  //
+  // Three false positives on a real adoption plan came from the cheaper question: two tables
+  // lost only an UPDATE policy, and one lost a single role-scoped read while anon and
+  // authenticated reads survived untouched. A safety detector that cries wolf spends the
+  // credibility of its true positives, so this deliberately under-reports instead.
+  const byTable = new Map(live.tables.map((t) => [t.table, t]));
+  const dark: string[] = [];
+  for (const table of touched) {
+    if (createdRead.has(table)) continue;
+    const contract = byTable.get(table);
+    if (!contract) continue;              // not a live table — nothing to go dark
+    if (!contract.rls?.enabled) continue; // RLS off: policies do not gate the read at all
+    const dropped = droppedByTable.get(table) ?? new Set<string>();
+    const readSurvives = contract.policies.some(
+      (p) => (p.command === 'SELECT' || p.command === 'ALL') && !dropped.has(p.name),
+    );
+    if (!readSurvives) dark.push(table);
   }
-  return [...dropped.keys()].filter((t) => !created.has(t)).sort();
+  return dark.sort();
 }
 
 /** The plan's content address — recorded as `plan_ref` on the schema_log row. */
@@ -250,7 +351,12 @@ export type PlanPrecondition = { ok: true } | { ok: false; reason: string };
 
 /** The lock: apply only when the target is exactly where the plan started. */
 export function checkPlanPrecondition(plan: EdgePlan, liveFingerprint: string): PlanPrecondition {
-  if (liveFingerprint === plan.fromFingerprint) return { ok: true };
+  const cmp = compareStoredFingerprint({ hash: plan.fromFingerprint, v: plan.fpVersion }, liveFingerprint);
+  if (cmp.kind === 'match') return { ok: true };
+  // A plan minted under an older canonical form cannot be compared at all. Saying "the state
+  // moved (a concurrent apply or a hand edit)" would send the operator hunting a change that
+  // never happened — plans are ephemeral by design, so the honest answer is re-mint.
+  if (cmp.kind === 'format-changed') return { ok: false, reason: formatChangedMessage(cmp) };
   return {
     ok: false,
     reason:
@@ -287,7 +393,9 @@ export function buildPlanSummary(plan: EdgePlan): string[] {
   // rows, and a plan that drops a table's only read policy leaves that table returning nothing.
   // 11 tables went dark in a real adoption plan that printed "0 notice(s)".
   const { authzRemovals, unclassified } = partitionStatements(classifyGeneratedStatements(plan.statements).executable);
-  const dark = tablesLeftWithoutARead(plan.statements);
+  // Prefer what the mint resolved against live. Recomputing here would have only the statement
+  // text and would re-introduce the false positives the mint-time answer exists to avoid.
+  const dark = plan.dark ?? tablesLeftWithoutARead(plan.statements);
   if (authzRemovals.length > 0) {
     lines.push(`! ${authzRemovals.length} statement(s) REMOVE authorization (policies, grants, RLS). No data is lost; who can read it changes.`);
     if (dark.length > 0) {