@everystack/cli 0.4.45 → 0.4.47

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/exec-digest.ts

@@ -24,24 +24,63 @@
 import { escapeLiteral } from './derived-apply.js';
 
 /**
- * Build the digest query for `schemas`. Returns SQL selecting a single `digest` column (md5 hex,
- * or md5('') for an empty catalog). The schemas are embedded as a quoted `text[]` literal — they
- * come from the deploy's declared schema set, never user input, but they are escaped regardless.
+ * Build the digest query. Returns SQL selecting a single `digest` column (md5 hex, or md5('')
+ * for an empty catalog).
+ *
+ * `schemas` IS ACCEPTED AND NO LONGER SCOPES THE DIGEST. It was the design error that made this
+ * guard fail in the field: a consumer ran 21 `CREATE OR REPLACE FUNCTION` in `auth` through
+ * db:exec and the guard stayed silent, because the deploy's schema set was `['public']` and the
+ * functions were simply outside the projection. **A guard that can be scoped can be scoped to
+ * blindness**, and the question db:exec asks is not "did the app's schemas move?" but "did the
+ * schema move AT ALL?". So the projection now covers every non-system schema, and no
+ * configuration — or missing configuration — can narrow it.
+ *
+ * The parameter stays in the signature deliberately: `@everystack/server` calls this through
+ * `@everystack/cli/exec`, so removing it would break every deployed ops Lambda that has not
+ * upgraded in lockstep. An old server passing `['public']` now gets full coverage.
+ *
+ * System schemas are excluded because they move for reasons that are not the caller's doing:
+ * `pg_toast` gains relations as tables acquire toastable columns, `pg_temp_*` appears and
+ * vanishes with sessions, and `pg_catalog`/`information_schema` are not the caller's to change.
  */
 export function catalogDigestQuery(schemas: string[]): string {
   if (schemas.length === 0) {
     throw new Error('catalogDigestQuery needs at least one schema to digest — pass the app schemas.');
   }
-  const arr = `ARRAY[${schemas.map(escapeLiteral).join(', ')}]::text[]`;
+  // Retained so the argument is not silently meaningless to a reader diffing this file: the
+  // value is validated exactly as before, then deliberately not used as a filter.
+  void schemas.map(escapeLiteral);
+  // A predicate, not an array: `= ANY(array_agg(nspname))` compares name to name[] and
+  // PostgreSQL has no such operator. Every branch below aliases pg_namespace as `n`.
+  const NS = `n.nspname NOT IN ('pg_catalog', 'information_schema', 'pg_toast')
+      AND n.nspname NOT LIKE 'pg_temp%' AND n.nspname NOT LIKE 'pg_toast_temp%'`;
   return `
 SELECT md5(coalesce(string_agg(line, E'\\n' ORDER BY line), '')) AS digest
 FROM (
   -- Relations: kind + persistence ONLY, never the volatile planner-stats columns (row-count,
   -- page-count, freeze-horizon) — those move under INSERT/UPDATE/DELETE and autovacuum, and
   -- would make the digest lie about pure DML.
-  SELECT format('rel:%s.%s:%s:%s', n.nspname, c.relname, c.relkind, c.relpersistence) AS line
+  -- relacl carries the GRANTs, and relrowsecurity/relforcerowsecurity the RLS posture. Both
+  -- were missing, so GRANT SELECT ON t TO anon, and ALTER TABLE t ENABLE ROW LEVEL SECURITY,
+  -- passed a gate advertising "rejects ANY schema change". A lane that cannot change the schema
+  -- but CAN change who may read it is not a DML-only lane. None of the three move under DML.
+  SELECT format('rel:%s.%s:%s:%s:%s:%s:%s', n.nspname, c.relname, c.relkind, c.relpersistence,
+                coalesce(c.relacl::text, ''), c.relrowsecurity, c.relforcerowsecurity) AS line
     FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
-    WHERE n.nspname = ANY(${arr}) AND c.relkind IN ('r', 'p', 'v', 'm', 'S', 'f')
+    WHERE ${NS} AND c.relkind IN ('r', 'p', 'v', 'm', 'S', 'f')
+  UNION ALL
+  -- Row policies: a CREATE/ALTER/DROP POLICY rewrites who sees which rows and touches no other
+  -- catalog this projection reads, so without this it was invisible.
+  SELECT format('pol:%s.%s.%s:%s:%s:%s:%s:%s', n.nspname, c.relname, pol.polname, pol.polcmd,
+                pol.polpermissive,
+                coalesce((SELECT string_agg(r.rolname, ',' ORDER BY r.rolname)
+                          FROM pg_roles r WHERE r.oid = ANY(pol.polroles)), 'PUBLIC'),
+                coalesce(pg_get_expr(pol.polqual, pol.polrelid), ''),
+                coalesce(pg_get_expr(pol.polwithcheck, pol.polrelid), ''))
+    FROM pg_policy pol
+    JOIN pg_class c ON c.oid = pol.polrelid
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE ${NS}
   UNION ALL
   -- Columns: number, type, typmod, not-null — the shape ALTER TABLE moves, DML never.
   SELECT format('att:%s.%s.%s:%s:%s:%s:%s',
@@ -49,31 +88,34 @@ FROM (
     FROM pg_attribute a
     JOIN pg_class c ON c.oid = a.attrelid
     JOIN pg_namespace n ON n.oid = c.relnamespace
-    WHERE n.nspname = ANY(${arr}) AND a.attnum > 0 AND NOT a.attisdropped
+    WHERE ${NS} AND a.attnum > 0 AND NOT a.attisdropped
   UNION ALL
   -- Constraints: the full textual definition (PK/FK/unique/check predicate).
   SELECT format('con:%s.%s:%s', n.nspname, con.conname, pg_get_constraintdef(con.oid))
     FROM pg_constraint con JOIN pg_namespace n ON n.oid = con.connamespace
-    WHERE n.nspname = ANY(${arr})
+    WHERE ${NS}
   UNION ALL
   -- Indexes: the full textual definition (columns, uniqueness, partial WHERE).
   SELECT format('idx:%s.%s:%s', n.nspname, ic.relname, pg_get_indexdef(i.indexrelid))
     FROM pg_index i
     JOIN pg_class ic ON ic.oid = i.indexrelid
     JOIN pg_namespace n ON n.oid = ic.relnamespace
-    WHERE n.nspname = ANY(${arr})
+    WHERE ${NS}
   UNION ALL
-  -- Routines: name + arg types + a hash of the body. CREATE/REPLACE/DROP FUNCTION all move it.
-  SELECT format('proc:%s.%s:%s:%s', n.nspname, p.proname, p.proargtypes::text, md5(coalesce(p.prosrc, '')))
+  -- Routines: name + arg types + a hash of the body, PLUS proacl (the EXECUTE grants) and
+  -- prosecdef. A REVOKE that leaves a SECURITY DEFINER function PUBLIC-executable, or a GRANT
+  -- that opens one, is a privilege change and must trip the guard like any other.
+  SELECT format('proc:%s.%s:%s:%s:%s:%s', n.nspname, p.proname, p.proargtypes::text,
+                md5(coalesce(p.prosrc, '')), coalesce(p.proacl::text, ''), p.prosecdef)
     FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
-    WHERE n.nspname = ANY(${arr})
+    WHERE ${NS}
   UNION ALL
   -- Types: kind + ordered enum labels. CREATE TYPE / ALTER TYPE ADD VALUE move it.
   SELECT format('type:%s.%s:%s:%s', n.nspname, t.typname, t.typtype,
                 coalesce((SELECT string_agg(e.enumlabel, ',' ORDER BY e.enumsortorder)
                           FROM pg_enum e WHERE e.enumtypid = t.oid), ''))
     FROM pg_type t JOIN pg_namespace n ON n.oid = t.typnamespace
-    WHERE n.nspname = ANY(${arr})
+    WHERE ${NS}
 ) s
 `.trim();
 }

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

@@ -363,11 +363,11 @@ Usage:
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
   everystack db:fingerprint    [--stage <name> | --database-url <url>] [--models <barrel>] [--json]  Content-address the live base schema (tables+constraints+authz) and compare against the models — MATCH/MISMATCH (exit 1), plus the unfingerprinted-objects report
   everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--only a,b] [--json]  Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (atomic — DDL + provenance in one transaction) and records provenance + schema_log; --apply --stage runs credential-free in the ops Lambda (no admin URL on the deployer, the db:apply twin), --apply --database-url runs direct. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive. --only <schema.name,…> restricts the run to the named objects (surgical); with --rebuild it FORCES those to rebuild from source even when the hashes show no diff — the recovery exit when a mistaken --rebaseline left a self-consistent-but-wrong provenance row (the dependency cascade rebuilds their live dependents).
-  everystack db:refresh        [--stage <name> | --database-url <url> | --direct] [--only a,b] [--verify-nonempty] [--list]  Refresh the declared materialized views in dependency order, credential-free. --stage runs the whole refresh in the ops Lambda on the operator connection (no URL on the operator's machine — the data-lane twin of the reconcile lane); --database-url/--direct refresh over a direct connection (dev); --only refreshes a named subset (full identity or bare name); --verify-nonempty gates on populated-but-zero-rows matviews (the dark-panel check — a scoped EXISTS on just what was refreshed, so a promotion script gets the gate with no read authority) and FAILS naming any empty; --list previews the order without connecting. Plain REFRESH (ACCESS EXCLUSIVE); fail-fast, idempotent to re-run.
+  everystack db:refresh        [--stage <name> | --database-url <url> | --direct] [--only a,b] [--verify-nonempty] [--list]  Refresh the declared materialized views in dependency order, credential-free. --stage runs the whole refresh in the ops Lambda on the operator connection (no URL on the operator's machine — the data-lane twin of the reconcile lane); --database-url refreshes over a local connection (dev); --stage <name> --direct resolves the stage's operator connection from its ops Lambda (credential never on argv) and refreshes CLI-side on an UNBOUNDED clock, for a matview set that exceeds the ops-Lambda 900s limit; --only refreshes a named subset (full identity or bare name); --verify-nonempty gates on populated-but-zero-rows matviews (the dark-panel check — a scoped EXISTS on just what was refreshed, so a promotion script gets the gate with no read authority) and FAILS naming any empty; --list previews the order without connecting. Plain REFRESH (ACCESS EXCLUSIVE); fail-fast, idempotent to re-run.
   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:plan           [--stage <name> [--direct] | --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; plans are ephemeral, never committed. VENUES: --stage runs via the ops Lambda, which reads TWICE and refuses on disagreement — agreement there is a DETECTOR, not a verification. --stage --direct resolves the stage's operator connection from its IAM-gated ops Lambda, holds it in memory only, and reads ONCE over one session: the lane for a fingerprint you intend to trust, with the credential never on argv. --database-url is the local-dev venue (same read guarantee, but against a deployed stage it puts a privileged DSN on the command line)
+  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