@everystack/cli 0.4.45 → 0.4.46

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, compareStoredFingerprint, formatChangedMessage, FINGERPRINT_VERSION } 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';
 
@@ -67,8 +67,21 @@ export interface EdgePlan {
    * drift that no edit could explain. Absent on plans minted before v4.
    */
   fpVersion?: number;
-  /** The predicted live fingerprint after apply — exact, unmodeled-aware. */
+  /**
+   * 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). */
@@ -78,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;
@@ -114,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));
@@ -150,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;
 }
 
 /**
@@ -193,12 +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,
     fpVersion: FINGERPRINT_VERSION,
-    toFingerprint: predictLiveFingerprint(models, snapshot, contract, { schema: opts.schema }),
+    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,
@@ -213,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,
@@ -227,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. */
@@ -299,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) {

package/src/cli/git-descent.ts

@@ -32,7 +32,8 @@ import type { ModelDescriptor } from '@everystack/model';
 import type { SchemaSnapshot } from './schema-introspect.js';
 import type { AuthzContract } from './authz-contract.js';
 import { fingerprintLive } from './schema-fingerprint.js';
-import { predictLiveFingerprint } from './edge-plan.js';
+import { predictLiveFingerprint, governedLiveFingerprint } from './edge-plan.js';
+import { governedRolesForModels } from './schema-fingerprint.js';
 
 /** Compile a models barrel on disk. The default rides the CLI's runtime (tsx). */
 export type ModelsLoader = (barrel: string) => Promise<ModelDescriptor[]>;
@@ -174,7 +175,6 @@ export async function verifyDescent(
   const barrel = path.basename(modelsAbs);
 
   const candidates = enumerateModelTrees(modelsDir, repoRoot);
-  const liveFingerprint = fingerprintLive(live.snapshot, live.contract).hash;
 
   const nodeModules = path.join(repoRoot, 'node_modules');
   const materializeRoot = opts.materializeRoot
@@ -187,29 +187,36 @@ export async function verifyDescent(
   try {
     for (const candidate of candidates) {
       const dest = path.join(materializeRoot, candidate.tree);
-      let predicted: string;
+      let declares: boolean;
       // A swallowed error here skips the candidate — and if it was the DECLARING tree, the
       // verdict silently falls through to 'drift'. Real compile failures are deterministic;
       // a transient materialize/import failure (fd pressure, module-loader contention under
       // a parallel test run or a busy CI box) is not — so a failed candidate gets exactly
       // one retry, from a clean materialization, before it is recorded as a compile failure.
-      const attempt = async (): Promise<string> => {
+      //
+      // The declares-test is GOVERNED on both sides, per candidate: the commit's
+      // models define the governed set, and the live hash is filtered through the
+      // SAME set as the prediction — comparing a governed prediction against the
+      // raw live hash can never match on a brownfield target with foreign roles.
+      const attempt = async (): Promise<boolean> => {
         if (!fs.existsSync(dest)) materializeTree(candidate.tree, dest, repoRoot);
         const models = await loader(path.join(dest, barrel));
-        return predictLiveFingerprint(models, live.snapshot, live.contract, { schema: opts.schema });
+        const governedRoles = governedRolesForModels(models);
+        const predicted = predictLiveFingerprint(models, live.snapshot, live.contract, { schema: opts.schema, governedRoles });
+        return predicted === governedLiveFingerprint(live.snapshot, live.contract, governedRoles);
       };
       try {
         try {
-          predicted = await attempt();
+          declares = await attempt();
         } catch {
           fs.rmSync(dest, { recursive: true, force: true });
-          predicted = await attempt();
+          declares = await attempt();
         }
       } catch (err: any) {
         compileFailures.push(`${short(candidate.tree)} (at ${short(candidate.commits[0])}): ${err.message}`);
         continue;
       }
-      if (predicted !== liveFingerprint) continue;
+      if (!declares) continue;
 
       for (const commit of candidate.commits) {
         try {
@@ -255,7 +262,7 @@ export async function verifyDescent(
     scannedTrees: candidates.length,
     compileFailures,
     reason:
-      `no committed models state declares the target's live fingerprint ${short(liveFingerprint)} — ` +
+      `no committed models state declares the target's live fingerprint ${short(fingerprintLive(live.snapshot, live.contract).hash)} — ` +
       `scanned ${candidates.length} historical tree(s) across all refs${failureNote}. ` +
       'Either the database was hand-edited (drift) or the declaring history was rewritten. ' +
       'Align the models with the live database first (db:pull, commit), ' +

package/src/cli/index.ts

@@ -367,7 +367,7 @@ Usage:
   everystack db:sync           [--database-url <url>] [--models <barrel>] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against the declared descriptors, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
   everystack db:diff           --from-models <barrel> [--to-models db/models/index.ts] [--allow-drops] [--check] [--json]  The state edge between two declared states, NO database: the SQL db:generate would produce, computed purely — CI plan previews (--check exits 1 on a non-empty edge) and computed rollbacks (swap the flags)
   everystack db:plan           [--stage <name> | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only — works via the ops Lambda; plans are ephemeral, never committed
-  everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--snapshot-ref <ref>] [--force-descent <snapshot-ref> --confirm]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule, else refuse — "rebase first"), and for DESTRUCTIVE plans require --confirm always + a snapshot (automatic via db:backup with --stage, else --snapshot-ref) + the stage's approver set when declared (STS identity-verified). Every refusal is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there; direct connection required
+  everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--snapshot-ref <ref>] [--force-descent <snapshot-ref> --confirm]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule, else refuse — "rebase first"), and for DESTRUCTIVE plans require --confirm always + an attested --snapshot-ref + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there
   everystack db:check          [--models <barrel>] [--schema-out <file.ts>] [--database-url <url>] [--json]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, descriptors compile), every exposed RLS-enabled table must declare a read path (no force-RLS-with-no-read landmine that goes dark on the superuser drop), and generated artifacts must MATCH regeneration byte-for-byte; with a scratch PostgreSQL it builds the state from scratch on an ephemeral database (created + dropped) and requires fingerprint MATCH. Exit 1 on any failure; never touches a real target
   everystack db:approvers      --stage <name> [--set "cto,arn:..."] [--remove]  Declare who can DESTROY: the stage's destructive-approver set (SSM parameter, admin-writable). Destructive db:apply runs are then identity-verified (STS) against it; --set '' disables destructive applies; --remove returns the stage to ceremony-only
   everystack db:backfill       [--database-url <url>] [--dir db/backfills] [--apply] [--mark-applied <file.sql>] [--json]  One-shot data jobs in their own lane: plan shows applied (by CONTENT identity — renames/comment edits are no-ops) / pending (in order, unbounded-pass advisories) / blocked (a name that already ran in a different form — one-shot jobs are immutable). --apply runs each pending job as its own transaction, recorded in everystack.backfill_log (a failure rolls back alone, is recorded, stops the run); --mark-applied records without running. Never runs as a schema side effect; direct connection required