@everystack/cli 0.4.72 → 0.4.74

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.74] - 2026-09-06
+
+### BREAKING CHANGES
+
+- P1.6 — bump fingerprint format to v11 (command fan + membership deadness + sequence ACLs)
+
+### Added
+
+- P2a (core) — proveAdoption, the prove-don't-attest heart of db:adopt
+- P2a-shell — db:adopt command (prove-don't-attest first adoption)
+
+### Fixed
+
+- P1.1 — canonical authz fans the command dimension
+- P1.3 — reconciler and drift gate agree with the fingerprint on the command fan
+- P1.2 — deadness folds role membership on the live side (Condition A)
+- P1.5 — serial-sequence ACLs enter the fingerprint (Bug 3)
+- P1.4 — reconcile fallback orders narrowing before widening (Condition C)
+- P2b — an ancestor with no models barrel declares nothing, not a compile failure
+- P2c/P2d — drift refusal becomes the adopt runbook; base fingerprint excludes everystack schema
+
+## [0.4.73] - 2026-09-04
+
+### Fixed
+
+- db:reconcile converges an owned relation's self-grant
+
 ## [0.4.72] - 2026-09-04
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.72",
+  "version": "0.4.74",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/cli/adopt.ts

@@ -0,0 +1,58 @@
+/**
+ * adopt — the PROVE core of `db:adopt` (P2a). Pure: live introspection + compiled Models in, a
+ * verdict out. The command shell (commands/db-adopt.ts) does the IO — introspect, render, load,
+ * write files, print the commit.
+ *
+ * The doctrine (Fable-ruled 2026-09-05): PROVE, not attest. There is no bypass flag. db:adopt
+ * renders Models from a live database and may finalize them ONLY when the compiled Models declare
+ * that database EXACTLY — the same declares-test descent and db:check use (predicted == governed
+ * live). A commit that carries such Models legitimately declares the live state, so a later
+ * db:apply descends for real (proveDescent finds the adopt commit) instead of being forced past a
+ * drift refusal. When the round-trip is not exact, adoption REFUSES and names what diverged —
+ * because a baseline that silently papered over a difference is the bypass under another name.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import type { SchemaSnapshot } from './schema-introspect';
+import type { AuthzContract } from './authz-contract';
+import { governedRolesForModels, fingerprintState, fingerprintLive, divergentSurfaces } from './schema-fingerprint';
+import { predictLiveState, governedLiveFingerprint } from './edge-plan';
+
+export interface AdoptionProof {
+  /** True when the compiled Models declare the live state exactly — safe to finalize the baseline. */
+  clean: boolean;
+  /** The RAW live fingerprint — the baseline id that names the adopt commit (`adopt live baseline <fp>`). */
+  fingerprint: string;
+  /** When not clean, the surfaces that still diverge (base schema / authorization / sequence ACLs,
+   *  with the tables named), so the refusal says exactly what the render could not capture. Empty when clean. */
+  divergentSurfaces: string[];
+}
+
+/**
+ * Does this compiled Models set declare the live state exactly? The declares-test, governed on
+ * both sides through the SAME set the Models imply — a governed prediction against a raw live
+ * hash can never converge on a brownfield database with foreign roles. Reuses the very functions
+ * descent (`evaluateTree`) and db:fingerprint compare with, so "adoption is clean" and "the plan
+ * is empty" are one answer, not two that can disagree.
+ */
+export function proveAdoption(
+  models: ModelDescriptor[],
+  snapshot: SchemaSnapshot,
+  contract: AuthzContract,
+  opts: { schema?: string } = {},
+): AdoptionProof {
+  const governedRoles = governedRolesForModels(models);
+  const predicted = predictLiveState(models, snapshot, contract, { schema: opts.schema, governedRoles });
+  const governedLiveHash = governedLiveFingerprint(snapshot, contract, governedRoles);
+  const clean = predicted.hash === governedLiveHash;
+  return {
+    clean,
+    fingerprint: fingerprintLive(snapshot, contract).hash,
+    divergentSurfaces: clean
+      ? []
+      : divergentSurfaces(
+          predicted.canonical,
+          fingerprintState(snapshot, contract.tables, { governedRoles, sequenceGrants: contract.sequenceGrants }).canonical,
+        ),
+  };
+}

package/src/cli/apply-execute.ts

@@ -36,6 +36,7 @@ import {
   POLICIES_SQL,
   GRANTS_SQL,
   COLUMN_GRANTS_SQL,
+  EFFECTIVE_PRIVILEGES_SQL,
   SCHEMA_ACL_SQL,
   SEQUENCE_ACLS_SQL,
   type QueryRunner,
@@ -245,7 +246,7 @@ export async function liveBaseAndLedger(session: SessionRunner): Promise<LiveBas
   const results = await session(
     [
       COLUMNS_SQL, CONSTRAINTS_SQL, ENUMS_SQL, INDEXES_SQL, SEQUENCES_SQL, EXTENSIONS_SQL,
-      RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, SCHEMA_ACL_SQL, SEQUENCE_ACLS_SQL, FUNCTIONS_SQL,
+      RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, EFFECTIVE_PRIVILEGES_SQL, SCHEMA_ACL_SQL, SEQUENCE_ACLS_SQL, FUNCTIONS_SQL,
       { sql: SCHEMA_LOG_WITNESS_SQL, allowFailure: true },
     ],
     INTROSPECTION_SESSION,
@@ -254,12 +255,15 @@ export async function liveBaseAndLedger(session: SessionRunner): Promise<LiveBas
     columns: results[0] as any[], constraints: results[1] as any[], enums: results[2] as any[],
     indexes: results[3] as any[], sequences: results[4] as any[], extensions: results[5] as any[],
   });
+  // The authz block gained EFFECTIVE_PRIVILEGES_SQL (index 10) so this fingerprint uses the SAME
+  // membership-folded deadness the plan's endpoints do — the concurrency lock compares them.
   const contract = assembleContract({
     rls: results[6] as any[], policies: results[7] as any[], grants: results[8] as any[],
-    columnGrants: results[9] as any[], schemaAcls: results[10] as any[], sequenceAcls: results[11] as any[],
-    functions: (results[12] as any[]).map(contractFunctionRow),
+    columnGrants: results[9] as any[], effectivePrivileges: results[10] as any[],
+    schemaAcls: results[11] as any[], sequenceAcls: results[12] as any[],
+    functions: (results[13] as any[]).map(contractFunctionRow),
   });
-  const ledger = mapLedgerRows(rowsOrEmpty(results[13]));
+  const ledger = mapLedgerRows(rowsOrEmpty(results[14]));
   return { hash: fingerprintLive(snapshot, contract).hash, snapshot, contract, ledger };
 }
 

package/src/cli/authz-canonical.ts

@@ -32,41 +32,61 @@
  */
 
 import type { PolicyContract, TableContract } from './authz-contract';
-import { effectivePolicyCheck, isPolicyDead, isPolicySubsumed } from './authz-contract';
+import { holdsPrivilegeEffective, policyCommands } from './authz-contract';
 
 /** PostgreSQL's open role set, kept whole. */
 const PUBLIC_ROLE = 'public';
 
 /**
- * One policy as (role, rule) entries — the form in which two equivalent states look equal.
- * A PUBLIC policy yields exactly one entry; every other policy yields one per named role.
+ * One (role, command) arm of a policy — the grain the canonical form compares at.
+ *
+ * A single `FOR ALL` policy governs four commands; the compiler that pulls it back writes one
+ * granular policy per command the role can exercise. Comparing the `command` field verbatim
+ * made those two states — the same authorization, written two ways — read as different, so a
+ * pulled brownfield table never round-tripped. Fanning the command dimension the way roles are
+ * already fanned is what makes them converge.
  */
-function expandPolicy(p: PolicyContract): string[] {
-  const rule = stableRule(p);
-  if (p.roles.includes(PUBLIC_ROLE)) return [`${PUBLIC_ROLE}|${rule}`];
-  return [...p.roles].sort().map((r) => `${r}|${rule}`);
+interface PolicyArm {
+  /** Expanded role name, or the `public` sentinel. */
+  role: string;
+  /** The single command this arm governs — never `ALL`; `FOR ALL` fans to four arms. */
+  command: string;
+  permissive: boolean;
+  /** The USING predicate PG enforces FOR THIS COMMAND (`''` where the command has none). */
+  using: string;
+  /** The WITH CHECK predicate PG enforces FOR THIS COMMAND (`''` where the command has none). */
+  check: string;
 }
 
 /**
- * The rule, with the NAME deliberately absent.
- *
- * Names were the policy's identity in the v3 format, on the reasoning that the compiler emits
- * them deterministically. That is true of a greenfield database and false of every brownfield
- * one, where the previous migration tool chose the names. Hashing them made a live policy that
- * carries the declared authorization under its own name read as a different state — so an
- * adopter could reach zero statements and never reach MATCH.
+ * Fan one policy into its (role, command) arms, each carrying the predicate in exactly the slot
+ * PostgreSQL enforces for that command — the NAME deliberately absent (a brownfield tool chose
+ * it, so hashing it made a live policy carrying the declared authorization read as a different
+ * state) and `ALL` expanded across the four row-level commands (so a live `FOR ALL` and the
+ * granular per-command policies a pull produces look equal).
  *
- * The check goes through the server's own defaulting rule, so a live `FOR ALL USING (true)`
- * and a compiled `FOR ALL USING (true) WITH CHECK (true)` — the same authorization, written
- * two ways — hash the same.
+ * The per-command slots, and why each is what it is:
+ *   - SELECT / DELETE have NO `WITH CHECK` — check is `''`.
+ *   - INSERT has NO `USING` — using is `''`; its check reuses `USING` when the source is a
+ *     `FOR ALL` with no explicit check (`p.check ?? p.using`), the server's own defaulting rule.
+ *   - UPDATE carries both, its check defaulting to `USING` the same way.
+ * This makes a `FOR ALL USING (pred)` fan to an INSERT arm whose check is `pred` — identical to
+ * the granular `INSERT ... WITH CHECK (pred)` a pull emits.
  */
-function stableRule(p: PolicyContract): string {
-  return JSON.stringify([
-    p.command,
-    p.permissive,
-    p.using ?? '',
-    effectivePolicyCheck(p) ?? '',
-  ]);
+function policyArms(p: PolicyContract): PolicyArm[] {
+  const roles = p.roles.includes(PUBLIC_ROLE) ? [PUBLIC_ROLE] : [...p.roles].sort();
+  const arms: PolicyArm[] = [];
+  for (const command of policyCommands(p)) {
+    const using = command === 'INSERT' ? '' : (p.using ?? '');
+    const check = command === 'SELECT' || command === 'DELETE' ? '' : ((p.check ?? p.using) ?? '');
+    for (const role of roles) arms.push({ role, command, permissive: p.permissive, using, check });
+  }
+  return arms;
+}
+
+/** The arm's canonical string — `role|[command,permissive,using,check]`, name and roles absent. */
+function armKey(a: PolicyArm): string {
+  return `${a.role}|${JSON.stringify([a.command, a.permissive, a.using, a.check])}`;
 }
 
 /** Sorted multiset: every entry kept, duplicates counted, order irrelevant. */
@@ -76,28 +96,86 @@ function multiset(entries: string[]): Array<[string, number]> {
   return [...counts.entries()].sort(([a], [b]) => (a < b ? -1 : 1));
 }
 
+/** Keep only the arms whose role the models govern; PUBLIC is a governed sentinel, always kept. */
+function governedArm(governed: ReadonlySet<string>, role: string): boolean {
+  return governed.has(role) || role === PUBLIC_ROLE || (role.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'));
+}
+
 /**
- * The canonical policy form: every policy expanded across its roles, as a sorted multiset.
- *
- * When a governed set is supplied (hashing a LIVE contract), per-role entries for roles the
- * models do not govern are dropped — the SAME choice the reconciler makes when it leaves an
- * ungoverned role's policy alone (the `reconcilePolicies` ungoverned escape). Hashing them
- * would keep MATCH unreachable on any brownfield database whose previous stack left a policy
- * TO a migrator/resolver role: zero statements, mismatched hash, forever. PUBLIC is a
- * governed sentinel and always kept.
+ * The canonical policy form: every policy fanned into its (role, command) arms, as a sorted
+ * multiset. NO deadness or subsumption is applied here — this is the pure fan, used where the
+ * grants are not in hand (predicate-normalization equivalence). {@link canonicalAuthz} carries
+ * the contract and does the per-arm deadness and subsumption the state needs.
+ *
+ * When a governed set is supplied (hashing a LIVE contract), arms for roles the models do not
+ * govern are dropped — the SAME choice the reconciler makes when it leaves an ungoverned role's
+ * policy alone (the `reconcilePolicies` ungoverned escape). Hashing them would keep MATCH
+ * unreachable on any brownfield database whose previous stack left a policy TO a migrator role:
+ * zero statements, mismatched hash, forever. PUBLIC is a governed sentinel and always kept.
  */
 export function canonicalPolicies(
   policies: readonly PolicyContract[],
   governed?: ReadonlySet<string>,
 ): Array<[string, number]> {
-  const entries = policies.flatMap(expandPolicy);
-  const kept = governed
-    ? entries.filter((e) => {
-        const role = e.slice(0, e.indexOf('|'));
-        return governed.has(role) || role === PUBLIC_ROLE || (role.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'));
-      })
-    : entries;
-  return multiset(kept);
+  const arms = policies.flatMap(policyArms);
+  const kept = governed ? arms.filter((a) => governedArm(governed, a.role)) : arms;
+  return multiset(kept.map(armKey));
+}
+
+/**
+ * Is this arm DEAD — does its (role, command) pair authorize nothing?
+ *
+ * PostgreSQL checks the GRANT before the policy, so an arm governing a command the role does not
+ * hold is inert. Per ARM, not per policy: a `FOR ALL` on a role holding SELECT/INSERT/UPDATE but
+ * not DELETE keeps three live arms and drops the dead DELETE one — which is exactly what makes it
+ * converge with a 3-granular pull, while a role that DOES hold DELETE keeps four and stays
+ * distinct. A PUBLIC arm applies to every grantee, so it is dead only when NO grantee holds the
+ * command. `holdsPrivilegeEffective` folds role membership + PUBLIC + column grants on the live
+ * side (and the direct grants on a declared one), the same oracle the reconciler uses.
+ */
+function armDead(t: TableContract, a: PolicyArm): boolean {
+  if (a.role === PUBLIC_ROLE || a.role.toUpperCase() === 'PUBLIC') {
+    const grantees = t.effectivePrivileges
+      ? Object.keys(t.effectivePrivileges)
+      : [...new Set([...Object.keys(t.grants), ...Object.keys(t.columnGrants ?? {})])];
+    return !grantees.some((r) => holdsPrivilegeEffective(t, r, a.command));
+  }
+  return !holdsPrivilegeEffective(t, a.role, a.command);
+}
+
+/**
+ * Is this arm SUBSUMED — does an identical PUBLIC arm already reach its role?
+ *
+ * Permissive arms OR together and a PUBLIC arm applies to every role, so a role-scoped arm whose
+ * (command, using, check) is character-for-character a live PUBLIC arm's admits no session the
+ * other does not. Only among ALIVE arms — a dead PUBLIC arm covers nothing. Restrictive arms
+ * are never subsumed (they AND, so removing one would WIDEN); a PUBLIC arm is never subsumed
+ * (it is the coverer).
+ */
+function armSubsumed(a: PolicyArm, alive: readonly PolicyArm[]): boolean {
+  if (!a.permissive || a.role === PUBLIC_ROLE || a.role.toUpperCase() === 'PUBLIC') return false;
+  return alive.some((o) =>
+    (o.role === PUBLIC_ROLE || o.role.toUpperCase() === 'PUBLIC')
+    && o.permissive && o.command === a.command && o.using === a.using && o.check === a.check);
+}
+
+/**
+ * The canonical policy form WITH the state exclusions: fan to arms, drop the dead ones (an arm
+ * whose grant does not exist), drop the subsumed ones (a role-scoped arm a PUBLIC arm already
+ * covers), then filter to the governed roles. Both exclusions are the same idea the reconciler
+ * makes in lockstep — an arm that changes no access is not part of the state — now made per
+ * (role, command) instead of per whole policy, so a `FOR ALL` with one dead command arm and the
+ * granular pull that omits that command hash equal.
+ */
+function canonicalPolicyArms(
+  contract: TableContract,
+  governed?: ReadonlySet<string>,
+): Array<[string, number]> {
+  const alive = contract.policies.flatMap(policyArms).filter((a) => !armDead(contract, a));
+  const kept = alive
+    .filter((a) => !armSubsumed(a, alive))
+    .filter((a) => (governed ? governedArm(governed, a.role) : true));
+  return multiset(kept.map(armKey));
 }
 
 /**
@@ -124,6 +202,25 @@ function governedOnly<T>(
   );
 }
 
+/**
+ * Are two tables' policies the SAME authorization under the canonical fan?
+ *
+ * The equivalence relation the fingerprint hashes, exposed as a boolean for the reconciler and
+ * the drift gate. Gating those two on THIS — rather than a per-command field compare — is what
+ * keeps all three surfaces from ever contradicting each other about the same database: a live
+ * `FOR ALL` with a dead DELETE arm and the granular pull that omits DELETE are equal here, so
+ * the reconciler emits nothing and the differ reports no drift, exactly as the fingerprint says
+ * MATCH. When it is false the callers fall back to the per-policy matcher, which can only ever
+ * over-emit (churn), never under-emit (a silent authorization difference).
+ */
+export function tablePoliciesEquivalent(
+  a: TableContract,
+  b: TableContract,
+  governed?: ReadonlySet<string>,
+): boolean {
+  return JSON.stringify(canonicalPolicyArms(a, governed)) === JSON.stringify(canonicalPolicyArms(b, governed));
+}
+
 /**
  * The canonical authorization form for one table.
  *
@@ -160,19 +257,14 @@ export function canonicalAuthz(
           ),
         }
       : {}),
-    // A DEAD policy is not part of the state. It authorizes nothing (Postgres refuses at the
-    // GRANT before consulting it), and the reconciler now leaves it alone — so counting it
-    // here would keep MATCH unreachable on exactly the databases that have them: brownfield
-    // ones, where a previous stack left policies behind after its grants were revoked. Both
-    // surfaces make the same choice, from the same function. Deadness is recomputed against
-    // these grants every time, so the policy re-enters the state the moment a grant revives it.
-    // …and neither is a SUBSUMED one: a permissive policy whose rule an identical PUBLIC
-    // policy already applies to every role admits no session the other does not. Both
-    // exclusions are the same idea — a policy that changes no access is not part of the
-    // state — and both are made in lockstep with the reconciler, from the same functions.
-    policies: canonicalPolicies(
-      contract.policies.filter((p) => !isPolicyDead(contract, p) && !isPolicySubsumed(contract, p)),
-      governed,
-    ),
+    // Policies fan to (role, command) ARMS; a DEAD arm (its grant does not exist) and a
+    // SUBSUMED arm (a PUBLIC arm already covers it) are not part of the state, so both are
+    // dropped before hashing — the same choices the reconciler makes, now made per command
+    // instead of per whole policy. That per-command grain is what makes a live `FOR ALL` with
+    // one dead command arm hash equal to the granular pull that omits that command, while a
+    // `FOR ALL` whose every arm is alive stays distinct from a set that denies one command.
+    // Deadness is recomputed against these grants every time, so an arm re-enters the state the
+    // moment a grant revives it.
+    policies: canonicalPolicyArms(contract, governed),
   };
 }

package/src/cli/authz-contract.ts

@@ -25,6 +25,11 @@ import { parsePgArray } from './security-catalog';
 import { INTROSPECTION_SESSION, type SessionRunner } from './session';
 import { matchPolicies, roleSetEqual } from './authz-identity';
 import { normalizeDeparsedExpr } from './deparse-normal';
+// A function-scoped cycle: authz-canonical imports the small pure helpers below, and this module
+// imports its equivalence relation. Both cross-references live inside function bodies, never at
+// module-init, so CJS resolves them at call time. The alternative — a second copy of the
+// equivalence relation here — is the exact drift this module system exists to prevent.
+import { tablePoliciesEquivalent } from './authz-canonical';
 
 // ---------------------------------------------------------------------------
 // The contract format — the frozen, reviewable, version-controlled shape.
@@ -50,6 +55,21 @@ export interface TableContract {
    * it is first-class in the contract — a table-level grant view alone would miss it.
    */
   columnGrants?: Record<string, Record<string, string[]>>;
+  /**
+   * EFFECTIVE privileges per role — the folded, membership-and-PUBLIC-aware truth, measured on
+   * the LIVE database (`has_table_privilege` OR `has_any_column_privilege`, which Postgres
+   * evaluates through role membership and PUBLIC). Consulted by DEADNESS only; `grants` stays
+   * the DIRECT ACL because that is what the grant diff reconciles.
+   *
+   * Present ONLY on an introspected live contract. A declared contract (compiled from the Model)
+   * has none, and deadness falls back to its `grants` — which ARE its effective set, since the
+   * model grants to the same role it polices. That absence is the signal: "no measurement, use
+   * the direct grants", exactly as an older recorder that never ran the effective read behaves.
+   *
+   * `role -> the commands (SELECT/INSERT/UPDATE/DELETE) the role effectively holds`. A role that
+   * holds nothing is omitted, not stored empty.
+   */
+  effectivePrivileges?: Record<string, string[]>;
   policies: PolicyContract[];
   /**
    * Column exposure (hiddenColumns / `.private()`, protectedFields / `.readonly()`).
@@ -138,6 +158,24 @@ export function holdsPrivilege(t: TableContract, role: string, privilege: string
     || Boolean(cols.public?.[privilege]?.length);
 }
 
+/**
+ * Does a role EFFECTIVELY hold a privilege? — the deadness question, folding role membership.
+ *
+ * The direct-ACL {@link holdsPrivilege} answers "does the catalog name this role as a grantee?"
+ * A brownfield role chain breaks that question: a role that is a MEMBER of a role holding the
+ * grant, or that holds it through PUBLIC, effectively has the privilege while the direct ACL
+ * never names it. Deadness computed from the direct ACL then calls a live, working policy dead.
+ *
+ * When a live contract carries {@link TableContract.effectivePrivileges} — the measured
+ * `has_table_privilege`/`has_any_column_privilege` matrix, which Postgres folds through
+ * membership and PUBLIC — this reads it. Absent (a declared contract, or an older recorder), it
+ * falls back to the direct grants, which for a declared contract ARE the effective set.
+ */
+export function holdsPrivilegeEffective(t: TableContract, role: string, privilege: string): boolean {
+  if (t.effectivePrivileges) return (t.effectivePrivileges[role] ?? []).includes(privilege);
+  return holdsPrivilege(t, role, privilege);
+}
+
 /** The four row-level commands a policy can govern. `FOR ALL` fans out across them. */
 export const POLICY_COMMANDS = ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
 
@@ -162,13 +200,17 @@ export function policyCommands(p: PolicyContract): string[] {
  * policy RESURRECTS the moment a grant makes it effective.
  */
 export function isPolicyDead(t: TableContract, p: PolicyContract): boolean {
+  // A PUBLIC policy applies to every grantee, so it is dead only when NO grantee holds any of
+  // its commands. Which grantees to test: the effective matrix's roles when measured (it names
+  // every role a membership could reach), else the direct grantees. Folding PUBLIC across the
+  // effective roles is what lets `has_table_privilege` decide a PUBLIC-arm's aliveness.
   const roles = p.roles.includes('public') || p.roles.includes('PUBLIC')
-    ? Object.keys(t.grants)
+    ? Object.keys(t.effectivePrivileges ?? t.grants)
     : p.roles;
   if (!roles.length) return true;
-  // `holdsPrivilege`, not the table-level one: a column-scoped grant is real access, so a
-  // policy governing it is doing live work. See the two-predicate note above.
-  return !policyCommands(p).some((cmd) => roles.some((r) => holdsPrivilege(t, r, cmd)));
+  // `holdsPrivilegeEffective`, not the direct one: a column-scoped grant is real access AND a
+  // membership-held privilege is real access, so a policy governing either is doing live work.
+  return !policyCommands(p).some((cmd) => roles.some((r) => holdsPrivilegeEffective(t, r, cmd)));
 }
 
 /** Does this policy name PostgreSQL's PUBLIC pseudo-role — the open set of every role? */
@@ -448,6 +490,79 @@ WHERE a.attacl IS NOT NULL
 ORDER BY n.nspname, c.relname, grantee, privilege, a.attname;
 `.trim();
 
+/**
+ * The EFFECTIVE per-(table, role) privilege matrix — what a role can actually do, folding role
+ * membership and PUBLIC, which the direct `aclexplode(relacl)` of GRANTS_SQL cannot see.
+ *
+ * `has_table_privilege` / `has_any_column_privilege` answer the folded question Postgres itself
+ * enforces: a role inherits the grants of every role it is a (INHERIT) member of, and every
+ * PUBLIC grant. This feeds DEADNESS only — a policy governing a command its role holds only
+ * through a parent role is doing live work, and dropping it is a real authorization change.
+ *
+ * Scoped to the roles that matter: a role NAMED IN A POLICY (its deadness is the question) or a
+ * direct grantee (needed to answer a PUBLIC arm's "does anyone hold this?"). Probing every role
+ * in the cluster would be needless work and would name roles no policy ever consults. Column
+ * privileges fold in via `has_any_column_privilege` (SELECT/INSERT/UPDATE only — DELETE is never
+ * column-scoped). Extension tables excluded to match the other reads.
+ */
+export const EFFECTIVE_PRIVILEGES_SQL = `
+WITH candidate AS (
+  SELECT DISTINCT r.oid, r.rolname
+  FROM pg_roles r
+  WHERE EXISTS (SELECT 1 FROM pg_policy p WHERE r.oid = ANY (p.polroles))
+     OR EXISTS (
+       SELECT 1 FROM pg_class c2
+       CROSS JOIN LATERAL aclexplode(c2.relacl) a2
+       WHERE a2.grantee = r.oid AND c2.relkind IN ('r', 'v', 'm')
+     )
+     OR EXISTS (
+       SELECT 1 FROM pg_attribute at2
+       CROSS JOIN LATERAL aclexplode(at2.attacl) a3
+       WHERE a3.grantee = r.oid AND at2.attnum > 0 AND NOT at2.attisdropped
+     )
+)
+SELECT
+  n.nspname AS schema,
+  c.relname AS "table",
+  cr.rolname AS role,
+  ARRAY(
+    SELECT p FROM unnest(ARRAY['SELECT', 'INSERT', 'UPDATE', 'DELETE']) AS p
+    WHERE has_table_privilege(cr.oid, c.oid, p)
+       OR (p <> 'DELETE' AND has_any_column_privilege(cr.oid, c.oid, p))
+  ) AS privileges
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+CROSS JOIN candidate cr
+WHERE c.relkind = 'r'
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend d
+    WHERE d.objid = c.oid AND d.deptype = 'e'
+  )
+ORDER BY n.nspname, c.relname, cr.rolname;
+`.trim();
+
+export interface EffectivePrivilegeRow {
+  schema: string;
+  table: string;
+  role: unknown;
+  privileges: unknown;
+}
+
+/** Map one effective-privilege row to its schema-qualified table + role + folded privileges. */
+export function effectivePrivilegeRowToDescriptor(row: EffectivePrivilegeRow): {
+  table: string;
+  role: string;
+  privileges: string[];
+} {
+  return {
+    table: `${row.schema}.${row.table}`,
+    role: String(row.role),
+    privileges: (parsePgArray(row.privileges) ?? []).map((p) => p.toUpperCase()),
+  };
+}
+
 /**
  * Every base table with its RLS posture — the table enumerator for the contract.
  * `relrowsecurity` / `relforcerowsecurity` give enabled/forced. A table absent from
@@ -750,6 +865,9 @@ export interface ContractRows {
   policies: PolicyRow[];
   grants: GrantRow[];
   columnGrants?: ColumnGrantRow[];
+  /** EFFECTIVE_PRIVILEGES_SQL rows — the membership-folded matrix deadness reads. Optional:
+   *  absent means the effective read never ran, and deadness stays on the direct grants. */
+  effectivePrivileges?: EffectivePrivilegeRow[];
   /** pg_namespace ACL rows (SCHEMA_ACL_SQL) — optional; absent means schema ACLs unknown. */
   schemaAcls?: SchemaAclRow[];
   /** SEQUENCE_ACLS_SQL. Optional — absent means not measured, never "no sequences". */
@@ -798,6 +916,19 @@ export function assembleContract(rows: ContractRows): AuthzContract {
     (byPriv[privilege] ??= []).push(column);
   }
 
+  // The effective matrix (membership + PUBLIC folded) — deadness only. A role holding nothing is
+  // omitted, so absence reads as "no effective privileges", never as "unmeasured". The map is
+  // attached to a table ONLY when the effective read ran, so a declared/older contract keeps
+  // deadness on its direct grants.
+  if (rows.effectivePrivileges) {
+    for (const row of rows.effectivePrivileges) {
+      const { table, role, privileges } = effectivePrivilegeRowToDescriptor(row);
+      const t = tables.get(table);
+      if (!t || privileges.length === 0) continue;
+      (t.effectivePrivileges ??= {})[role] = [...privileges].sort();
+    }
+  }
+
   for (const t of tables.values()) {
     t.policies.sort((a, b) => a.name.localeCompare(b.name));
     for (const byPriv of Object.values(t.columnGrants ?? {})) {
@@ -844,11 +975,11 @@ export async function introspectContract(
   mapFunctionRow: (row: any) => { schema: string; name: string; securityDefiner: boolean; hasSearchPath: boolean },
   functionsSql: string,
 ): Promise<AuthzContract> {
-  // ONE session: the six queries describe one moment under one pinned search_path.
+  // ONE session: the queries describe one moment under one pinned search_path.
   // Policy USING / WITH CHECK expressions deparse relative to that path, so a read spread
   // across connections can report authz drift that does not exist.
-  const [rls, policies, grants, columnGrants, schemaAcls, sequenceAcls, fnRows] = await session(
-    [RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, SCHEMA_ACL_SQL, SEQUENCE_ACLS_SQL, functionsSql],
+  const [rls, policies, grants, columnGrants, effectivePrivileges, schemaAcls, sequenceAcls, fnRows] = await session(
+    [RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, EFFECTIVE_PRIVILEGES_SQL, SCHEMA_ACL_SQL, SEQUENCE_ACLS_SQL, functionsSql],
     INTROSPECTION_SESSION,
   );
   return assembleContract({
@@ -856,6 +987,7 @@ export async function introspectContract(
     policies: policies as PolicyRow[],
     grants: grants as GrantRow[],
     columnGrants: columnGrants as ColumnGrantRow[],
+    effectivePrivileges: effectivePrivileges as EffectivePrivilegeRow[],
     schemaAcls: schemaAcls as SchemaAclRow[],
     sequenceAcls: sequenceAcls as SequenceAclRow[],
     functions: (fnRows as any[]).map(mapFunctionRow),
@@ -1029,6 +1161,8 @@ function diffPolicies(
 ): void {
   const m = matchPolicies(d.policies, l.policies);
 
+  // Adoptions are recorded whether or not the states are canonically equal \u2014 a name divergence
+  // is agreement, not drift, and its mapping must stay visible even on an equivalent table.
   for (const a of m.adopted) {
     adoptions.push({ subject: table, declared: [a.declared], live: a.live, reason: 'same rule, different name' });
   }
@@ -1036,6 +1170,16 @@ function diffPolicies(
     adoptions.push({ subject: table, declared: g.declared, live: g.live, reason: 'one live policy covers the declared per-role group' });
   }
 
+  // Condition B \u2014 gate drift on the SAME canonical equivalence the reconciler and the fingerprint
+  // use, so no surface can report drift the plan does not carry. A live `FOR ALL` with a dead
+  // DELETE arm equals the granular pull that omits DELETE; the per-command matcher below would
+  // call it "undeclared policy" + "declared but missing". No governed set is threaded through the
+  // differ, so this compares ALL arms \u2014 a strictly HARDER equality than the reconciler's
+  // governed-filtered one, which means the differ can only ever be MORE willing to report drift,
+  // never silent where the reconciler emits. Only when the states genuinely differ do the
+  // per-policy findings run.
+  if (tablePoliciesEquivalent(d, l)) return;
+
   // A name on BOTH sides whose rule moved is a CHANGE, not a remove-and-add. Saying which
   // field moved is the difference between a finding an operator can act on and one they have
   // to go read the catalog to understand.