@everystack/cli 0.4.43 → 0.4.45

package/src/cli/authz-derive.ts

@@ -25,12 +25,24 @@
  * comment: the comment costs a human five minutes, the ability costs them a privilege.
  */
 
+import { EXTRA_PRIVILEGES } from '@everystack/model';
+import { holdsPrivilege, holdsTablePrivilege } from './authz-contract.js';
 import type { TableContract, PolicyContract } from './authz-contract.js';
 
 /** One rendered decision: either an ability line, or a comment explaining the omission. */
 export interface DerivedAbilities {
   /** `can(...)` lines, ready to sit inside `abilities: [ ... ]`. */
   abilities: string[];
+  /**
+   * The beyond-CRUD privileges (REFERENCES/TRIGGER/TRUNCATE) a GOVERNED role holds live —
+   * rendered as the model's `privileges` key.
+   *
+   * `can()` has no verb for these, so before they were rendered the model could not say a
+   * live admin held them, and the first plan revoked all three on every table. Present only
+   * when the live database actually has some; empty means the key is omitted entirely, so a
+   * greenfield model is byte-identical to what it was.
+   */
+  privileges: Record<string, string[]>;
   /** `//` comment lines naming what could not be rendered, and why. */
   notes: string[];
   /**
@@ -55,6 +67,28 @@ const DML: Record<string, 'read' | 'create' | 'update' | 'delete'> = {
 /** The roles the compiler itself emits policies for; anything else is app-specific. */
 const KNOWN_ROLES = new Set(['anon', 'authenticated', 'admin']);
 
+/**
+ * The grantees a rendered model GOVERNS — the three vocabulary roles plus PUBLIC, which is
+ * always governed because a grant to PUBLIC is the broadest privilege the database can express.
+ *
+ * The beyond-CRUD privileges of anyone else are deliberately not rendered: the reconciler leaves
+ * an ungoverned grantee alone, so there is no REVOKE to prevent, and naming the role in a model
+ * would GOVERN it — turning a rendering decision into an access decision for every table.
+ */
+const GOVERNED_VOCABULARY = new Set([...KNOWN_ROLES, 'PUBLIC', 'public']);
+
+/** The beyond-CRUD privileges a governed role holds live — what `can()` cannot say. */
+function deriveExtraPrivileges(contract: TableContract): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  const extra = EXTRA_PRIVILEGES as readonly string[];
+  for (const grantee of Object.keys(contract.grants).sort()) {
+    if (!GOVERNED_VOCABULARY.has(grantee)) continue;
+    const held = (contract.grants[grantee] ?? []).filter((p) => extra.includes(p)).sort();
+    if (held.length) out[grantee] = held;
+  }
+  return out;
+}
+
 /**
  * The deparsed owner predicate the compiler produces, in both its casts:
  *   (col = (((current_setting('request.jwt.claims'::text, true))::jsonb ->> 'sub'::text)))
@@ -65,20 +99,132 @@ const KNOWN_ROLES = new Set(['anon', 'authenticated', 'admin']);
 const OWNER_RE =
   /^\(?([a-z_][a-z0-9_]*)\s*=\s*\(*\(current_setting\('request\.jwt\.claims'::text,\s*true\)\)::jsonb\s*->>\s*'([a-z_]+)'::text\)*(?:::[a-z]+)?\)?$/i;
 
-/** Does this predicate say "the row is mine"? Returns the column and the claim if so. */
-export function parseOwnerPredicate(pred: string | null): { column: string; claim: string } | null {
+/**
+ * The OTHER owner shape: the database's own accessor, `(<col> = auth.user_id())`.
+ *
+ * A brownfield schema almost always has one — a STABLE SECURITY DEFINER function wrapping
+ * the same claim read — and every owner policy in it is written against that function, not
+ * against the claim inline. Rendering those as the inline claim would be a semantically
+ * similar but TEXTUALLY different predicate, and predicates are diffed as text: it would
+ * plan a DROP + CREATE on every owner policy in the schema.
+ *
+ * Deliberately narrow: the right side must be a zero-argument function call. That is what
+ * an "who am I" accessor looks like, and it is what a column-to-column comparison
+ * (`(user_id = reviewer_id)`) is not — so the matcher cannot mistake a join predicate for
+ * a statement of ownership.
+ */
+const OWNER_FN_RE = /^\(?([a-z_][a-z0-9_]*)\s*=\s*((?:[a-z_][a-z0-9_]*\.)?[a-z_][a-z0-9_]*\(\))\)?$/i;
+
+/**
+ * Does this predicate say "the row is mine"? Returns the column, the claim, and the
+ * accessor expression when the schema uses one (null = the claim read inline).
+ */
+export function parseOwnerPredicate(
+  pred: string | null,
+): { column: string; claim: string; expr: string | null } | null {
   if (!pred) return null;
-  const m = OWNER_RE.exec(pred.trim());
-  return m ? { column: m[1], claim: m[2] } : null;
+  const t = pred.trim();
+  const m = OWNER_RE.exec(t);
+  if (m) return { column: m[1], claim: m[2], expr: null };
+  const f = OWNER_FN_RE.exec(t);
+  return f ? { column: f[1], claim: 'sub', expr: f[2] } : null;
 }
 
-/** Is a privilege EFFECTIVE for a role — i.e. actually granted, not merely policed? */
-function granted(contract: TableContract, role: string, privilege: string): boolean {
-  const direct = contract.grants[role] ?? [];
-  const publicGrant = contract.grants.PUBLIC ?? contract.grants.public ?? [];
-  return direct.includes(privilege) || publicGrant.includes(privilege);
+/**
+ * Split a predicate on a top-level operator, respecting parens and string literals.
+ *
+ * Needed because the shapes worth recognising are compositional — `(public) OR (mine AND
+ * guard)` — and a naive `.split(' OR ')` cuts inside a nested disjunction, which is how a
+ * template matcher silently mis-reads `((state <> 'deleted') AND ((user_id = …) OR (…)))`
+ * as a top-level OR it is not.
+ */
+function splitTopLevel(pred: string, op: 'OR' | 'AND'): string[] {
+  const needle = ` ${op} `;
+  const parts: string[] = [];
+  let depth = 0;
+  let quoted = false;
+  let start = 0;
+  // Strip one enclosing paren pair so the operator we want is genuinely at depth 0.
+  const s = unwrapOnce(pred.trim());
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === "'") { quoted = !quoted; continue; }
+    if (quoted) continue;
+    if (c === '(') depth++;
+    else if (c === ')') depth--;
+    else if (depth === 0 && s.startsWith(needle, i)) {
+      parts.push(s.slice(start, i));
+      i += needle.length - 1;
+      start = i + 1;
+    }
+  }
+  parts.push(s.slice(start));
+  return parts.map((p) => p.trim()).filter(Boolean);
+}
+
+/** Drop one enclosing paren pair, but only when it spans the WHOLE expression. */
+function unwrapOnce(s: string): string {
+  if (!s.startsWith('(') || !s.endsWith(')')) return s;
+  let depth = 0;
+  let quoted = false;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === "'") { quoted = !quoted; continue; }
+    if (quoted) continue;
+    if (c === '(') depth++;
+    else if (c === ')') {
+      depth--;
+      if (depth === 0 && i < s.length - 1) return s; // the pair closed early — not enclosing
+    }
+  }
+  return depth === 0 ? s.slice(1, -1).trim() : s;
 }
 
+/**
+ * Decompose an authenticated read of the form `(public) OR (mine [AND guard])`, given the
+ * public predicate the anon policy already states.
+ *
+ * Keyed on the ANON PREDICATE APPEARING VERBATIM as one of two top-level disjuncts, and an
+ * owner predicate appearing in the other — not on a shape template. The alternative,
+ * matching a `X OR (Y AND Z)` template, both over- and under-fires: it claims predicates it
+ * has not proven are a public branch, and it misses the schema whose OR is nested inside an
+ * AND. Anything that does not decompose EXACTLY returns null, and the caller says so.
+ */
+export function parsePublicOrOwn(
+  authedPred: string | null,
+  anonPred: string | null,
+): { owner: { column: string; claim: string; expr: string | null }; ownerSql: string | null } | null {
+  if (!authedPred || !anonPred) return null;
+  const branches = splitTopLevel(authedPred, 'OR');
+  if (branches.length !== 2) return null;
+
+  const anonNorm = unwrapOnce(anonPred.trim());
+  const publicIdx = branches.findIndex((b) => unwrapOnce(b) === anonNorm);
+  if (publicIdx === -1) return null;
+
+  const ownBranch = branches[1 - publicIdx];
+  const conjuncts = splitTopLevel(ownBranch, 'AND');
+  const ownerIdx = conjuncts.findIndex((c) => parseOwnerPredicate(c));
+  if (ownerIdx === -1) return null;
+
+  const owner = parseOwnerPredicate(conjuncts[ownerIdx])!;
+  const rest = conjuncts.filter((_, i) => i !== ownerIdx);
+  // More than one leftover conjunct would have to be re-ANDed, and the text the compiler
+  // then emits is not guaranteed to be the text that was read. Refuse rather than guess.
+  if (rest.length > 1) return null;
+  return { owner, ownerSql: rest[0] ?? null };
+}
+
+/**
+ * May we EMIT an ability for this privilege? Table-level only.
+ *
+ * `can('update')` compiles to a policy plus a table-wide `GRANT UPDATE`, so a role holding
+ * UPDATE on three columns must not satisfy this — rendering the ability would widen a column
+ * grant into a whole-table one. Whether the privilege is held AT ALL is a different question,
+ * answered by `holdsPrivilege`; both live in authz-contract so they cannot drift apart.
+ */
+const granted = holdsTablePrivilege;
+
 /** The policies that apply to a role for a command (an `ALL` policy covers every command). */
 function policiesFor(contract: TableContract, role: string, command: string): PolicyContract[] {
   return contract.policies.filter(
@@ -110,21 +256,36 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
   const adminAll = ['SELECT', 'INSERT', 'UPDATE', 'DELETE'].every((p) => granted(contract, 'admin', p));
   if (adminAll) abilities.push(`can('manage', { role: 'admin' })`);
 
-  // --- dead policies: policed but never granted ----------------------------------------
-  // The trap. Rendering one of these would ADD a privilege that does not exist today.
+  // --- policed but not granted at the table level ---------------------------------------
+  //
+  // Two different findings wear the same shape here, and calling both "dead" was a lie the
+  // adopter read beside the model they were about to trust:
+  //
+  //   - NOTHING holds the privilege → the policy really is dead code, and rendering it as an
+  //     ability would ADD a privilege the database does not give. That is the trap.
+  //   - a COLUMN grant holds it → the policy is doing live work on those columns. Rendering
+  //     the ability would still be wrong (it grants the whole table), but the privilege is
+  //     real, and the plan that drops the policy is taking away access that exists.
   for (const p of contract.policies) {
     const commands = p.command === 'ALL' ? ['SELECT', 'INSERT', 'UPDATE', 'DELETE'] : [p.command];
     for (const cmd of commands) {
       const priv = cmd;
       const live = p.roles.filter((r) => r !== 'public' && r !== 'admin' && !granted(contract, r, priv));
-      if (live.length && p.roles.some((r) => r !== 'admin')) {
-        notes.push(
-          `policy "${p.name}" (${cmd}) applies to ${live.join(', ')} but no ${priv} grant exists —`,
-        );
+      if (!live.length || !p.roles.some((r) => r !== 'admin')) continue;
+      const viaColumns = live.filter((r) => holdsPrivilege(contract, r, priv));
+      if (viaColumns.length) {
         notes.push(
-          `  it is dead code today. Declaring it would ADD a privilege the database does not give.`,
+          `policy "${p.name}" (${cmd}) is live through the ${viaColumns.join(', ')} COLUMN grant below, not a table grant.`,
         );
+        notes.push(`  NOT dead. Not rendered either: an ability would grant ${priv} on the whole table.`);
+        continue;
       }
+      notes.push(
+        `policy "${p.name}" (${cmd}) applies to ${live.join(', ')} but no ${priv} grant exists —`,
+      );
+      notes.push(
+        `  it is dead code today. Declaring it would ADD a privilege the database does not give.`,
+      );
     }
   }
 
@@ -135,15 +296,48 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
   if (anonRead) {
     // Public read. If the live policy narrows it (a soft-delete guard, a published flag),
     // carry that predicate — a public read with a filter is still a public read.
-    const pol = policiesFor(contract, 'anon', 'SELECT')[0];
-    const frag = sqlFragment(pol?.using ?? null);
+    const anonPol = policiesFor(contract, 'anon', 'SELECT')[0];
+    const anonPred = anonPol?.using ?? null;
+    const frag = sqlFragment(anonPred);
     abilities.push(frag ? `can('read', { sql: ${frag} })` : `can('read')`);
+
+    // The authenticated SELECT is a SEPARATE policy and routinely says MORE than the anon
+    // one — `(public) OR (mine)`, so an author sees their own not-yet-public rows. Reading
+    // only the anon policy dropped that branch and rendered a model that meant strictly
+    // less than the database did, with nothing said. On a real schema it hid ~13,184
+    // legacy rows from the people who wrote them.
+    const authedPol = authedRead
+      ? policiesFor(contract, 'authenticated', 'SELECT').find((p) => p.name !== anonPol?.name)
+      : undefined;
+    const authedPred = authedPol?.using ?? null;
+    if (authedPol && (authedPred ?? 'true') !== (anonPred ?? 'true')) {
+      const own = parsePublicOrOwn(authedPred, anonPred);
+      if (own) {
+        const parts = [`owner: '${own.owner.column}'`];
+        if (own.owner.claim !== 'sub') parts.push(`userField: '${own.owner.claim}'`);
+        if (own.owner.expr) parts.push(`ownerExpr: sql\`${own.owner.expr}\``);
+        const guard = sqlFragment(own.ownerSql);
+        if (guard) parts.push(`sql: ${guard}`);
+        abilities.push(`can('read', { ${parts.join(', ')} })`);
+      } else {
+        // P6: it must SAY SO. An unexpressible predicate becomes a comment naming the
+        // policy and its text, never a model that quietly means less.
+        notes.push(
+          `policy "${authedPol.name}" (SELECT) grants authenticated MORE than the anon read,`,
+        );
+        notes.push(`  and its shape is not expressible as abilities. Live USING:`);
+        notes.push(`    ${authedPred}`);
+        notes.push(`  Declare it by hand, or leave the table adopted. NOT rendered above.`);
+      }
+    }
   } else if (authedRead) {
     const pol = policiesFor(contract, 'authenticated', 'SELECT')[0];
     const owner = parseOwnerPredicate(pol?.using ?? null);
     if (owner) {
-      const claim = owner.claim === 'sub' ? '' : `, userField: '${owner.claim}'`;
-      abilities.push(`can('read', { owner: '${owner.column}'${claim} })`);
+      const parts = [`owner: '${owner.column}'`];
+      if (owner.claim !== 'sub') parts.push(`userField: '${owner.claim}'`);
+      if (owner.expr) parts.push(`ownerExpr: sql\`${owner.expr}\``);
+      abilities.push(`can('read', { ${parts.join(', ')} })`);
     } else {
       const frag = sqlFragment(pol?.using ?? null);
       abilities.push(frag ? `can('read', { role: 'authenticated', sql: ${frag} })` : `can('read', { role: 'authenticated' })`);
@@ -165,6 +359,7 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
     if (owner) {
       parts.push(`owner: '${owner.column}'`);
       if (owner.claim !== 'sub') parts.push(`userField: '${owner.claim}'`);
+      if (owner.expr) parts.push(`ownerExpr: sql\`${owner.expr}\``);
     }
     // A predicate beyond the owner gate (a state guard, a tenant filter) rides as `sql`.
     const usingFrag = owner && parseOwnerPredicate(using) ? null : sqlFragment(using);
@@ -185,6 +380,27 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
     abilities.push(`can('${action}'${parts.length ? `, { ${parts.join(', ')} }` : ''})`);
   }
 
+  // --- the column grants, which nothing above renders -----------------------------------
+  //
+  // The model expresses column scoping for READ only (`can('read', { owner, columns })`), and
+  // even that pairs with an owner policy this deriver does not attempt to reconstruct. So
+  // every live column grant is a privilege the rendered model does not carry, and the first
+  // plan REVOKES it — 11 statements on the reference schema, none of which had a word beside
+  // the model the adopter reviews.
+  //
+  // Named exactly: grantee, privilege, and the columns. A count is not auditable, and "some
+  // column grants were not captured" is the shape of silence this note exists to break.
+  for (const grantee of Object.keys(contract.columnGrants ?? {}).sort()) {
+    if (!GOVERNED_VOCABULARY.has(grantee)) continue; // ungoverned: left alone, never revoked
+    const byPriv = contract.columnGrants![grantee];
+    for (const priv of Object.keys(byPriv).sort()) {
+      const cols = byPriv[priv] ?? [];
+      if (!cols.length) continue;
+      notes.push(`${grantee} holds a COLUMN-scoped ${priv} on ${cols.length} column(s): ${cols.join(', ')}.`);
+      notes.push(`  NOT rendered — the model has no way to declare it. The next plan REVOKES it.`);
+    }
+  }
+
   // --- roles the compiler has no vocabulary for ----------------------------------------
   const unmappedRoles = Object.keys(contract.grants).filter(
     (r) => !KNOWN_ROLES.has(r) && r !== 'PUBLIC' && r !== 'public',
@@ -194,17 +410,33 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
     notes.push(`no grants found — this table is internal (nothing reaches it through the data API).`);
   }
 
-  return { abilities, notes, unmappedRoles };
+  return { abilities, notes, unmappedRoles, privileges: deriveExtraPrivileges(contract) };
+}
+
+/** An object key, quoted only when the role name is not a bare JS identifier. */
+function identKey(name: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
 }
 
 /** Render one table's derived stanza as the lines that sit inside a model literal. */
 export function renderDerivedAbilities(d: DerivedAbilities): string {
   const out: string[] = [];
-  for (const n of d.notes) out.push(`  // ${n}`);
+  // Split on newlines: a note may carry a live predicate verbatim, and `pg_get_expr`
+  // deparses a subquery across several lines. One `//` for the first line left the rest
+  // as bare SQL in the middle of a TypeScript object — a generated file that would not
+  // parse. Commenting per line here means no note, present or future, can do that.
+  for (const n of d.notes) for (const line of String(n).split('\n')) out.push(`  // ${line}`);
   if (d.abilities.length) {
     out.push(`  abilities: [${d.abilities.join(', ')}],`);
   } else {
     out.push(`  private: true,   // no effective privilege found — not part of the data API`);
   }
+  // The beyond-CRUD grants, transcribed. Omitted entirely when there are none, so a database
+  // without them renders exactly the model it rendered before this key existed.
+  const roles = Object.keys(d.privileges ?? {});
+  if (roles.length) {
+    const entries = roles.map((r) => `${identKey(r)}: [${d.privileges[r].map((p) => `'${p}'`).join(', ')}]`);
+    out.push(`  privileges: { ${entries.join(', ')} },   // live grants can() has no verb for`);
+  }
   return out.join('\n');
 }

package/src/cli/authz-identity.ts

@@ -0,0 +1,222 @@
+/**
+ * authz-identity — policy identity by RULE, not by name. The shared matcher.
+ *
+ * ONE module, called by BOTH the emitter (`authz-reconcile`) and the differ
+ * (`authz-contract`). They must never hold separate implementations: two hand-mirrored
+ * bipartite matchers will disagree on tie-breaks, and then `db:check` reports drift the plan
+ * does not carry — the two surfaces contradicting each other about the same database.
+ *
+ * WHY THIS EXISTS. A brownfield database names its policies whatever its previous migration
+ * tool named them. `reconcilePolicies` matched by NAME, so a live policy with the same
+ * command, roles, USING and CHECK but a different name was reported twice — "declared but
+ * missing" and "live but undeclared" — which the emitter turned into DROP + CREATE. On a real
+ * adopter's schema that was ~25 statements of pure spelling.
+ *
+ * THE SAFETY PROPERTY, which every rule below serves:
+ *
+ *   **Identity by rule must be NARROWER than identity by name, never wider.**
+ *
+ * A false match leaves a live policy in place while the model believes it declared it. That is
+ * the one direction no review catches. So matching requires FULL field equality — the same
+ * predicate that already decides "unchanged" now also decides "same rule". The matcher is
+ * therefore MONOTONE: it can only turn a would-be DROP + CREATE pair into a no-op, never emit
+ * different DDL. Anything short of equality falls through to the previous behaviour.
+ *
+ * Two known limits, stated rather than hidden:
+ *
+ *  - Predicates compare as TEXT. Postgres normalizes `pg_get_expr` output, so a semantically
+ *    identical predicate written differently is a MISS (drop + create, the status quo), never
+ *    a false match. Misses are the expected failure mode and they are safe.
+ *  - Text equality is only false-match-proof if introspection renders references fully
+ *    qualified. A live policy created under a different `search_path` could deparse `f(x)`
+ *    meaning `legacy.f` identically to a declared `f(x)` meaning `app.f`. Adoption never
+ *    re-executes DDL so it cannot emit wrong SQL, but it could falsely ADOPT. Pinning
+ *    introspection's search_path is what closes that hole.
+ */
+
+import { effectivePolicyCheck, type PolicyContract } from './authz-contract.js';
+
+/**
+ * Do two role lists name the same set?
+ *
+ * Compared as SETS. The previous `roles.join(',')` comparison had a false-match seam: a role
+ * name may legally contain a comma (`CREATE ROLE "a,b"`), which made `['a,b']` compare equal
+ * to `['a','b']` — two different authorizations reported as one.
+ *
+ * Nothing folds case here, and that is load-bearing. PUBLIC (`pg_policy.polroles = {0}`,
+ * rendered by `pg_policies` as the literal `public`) is an OPEN set: every role that exists or
+ * ever will, including ones created after the model was written. It can equal PUBLIC and
+ * nothing else — no enumerated set can account for roles that do not exist yet. Plain set
+ * equality gives that sentinel property for free, so long as no caller case-folds a grantee
+ * into it (`CREATE ROLE "Public"` is legal and distinct).
+ */
+export function roleSetEqual(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false;
+  const sa = new Set(a);
+  if (sa.size !== new Set(b).size) return false;
+  return b.every((r) => sa.has(r));
+}
+
+/**
+ * Are these the same authorization, ignoring only the NAME?
+ *
+ * The check compares through {@link effectivePolicyCheck} — the server's own defaulting rule
+ * — so a live `FOR ALL USING (true)` and a compiled `FOR ALL USING (true) WITH CHECK (true)`
+ * are recognized as identical rather than reconciled into a DROP + CREATE that changes
+ * nothing. That defaulting applies to `ALL` and `UPDATE` only; on a `SELECT` an omitted check
+ * is genuinely no check.
+ *
+ * Command equality is exact and always. A live `FOR ALL` must never satisfy a declared
+ * SELECT/INSERT/UPDATE/DELETE quartet: USING and WITH CHECK applicability differ per command,
+ * and that is precisely where false-equivalence reasoning breeds.
+ */
+export function policyRuleEqual(a: PolicyContract, b: PolicyContract): boolean {
+  return a.command === b.command
+    && a.permissive === b.permissive
+    && roleSetEqual(a.roles, b.roles)
+    && (a.using ?? '') === (b.using ?? '')
+    && (effectivePolicyCheck(a) ?? '') === (effectivePolicyCheck(b) ?? '');
+}
+
+/**
+ * Same authorization on every axis EXCEPT which roles it names. Used only by the role-union
+ * pass; the command is still compared exactly, because USING and WITH CHECK applicability
+ * differ per command and a live `FOR ALL` must never satisfy a declared per-command set.
+ */
+function sameRuleIgnoringRoles(a: PolicyContract, b: PolicyContract): boolean {
+  return a.command === b.command
+    && a.permissive === b.permissive
+    && (a.using ?? '') === (b.using ?? '')
+    && (effectivePolicyCheck(a) ?? '') === (effectivePolicyCheck(b) ?? '');
+}
+
+/** One declared policy satisfied by a live policy of the same rule under a different name. */
+export interface AdoptedPolicy {
+  /** The name the model would have created. */
+  declared: string;
+  /** The name the database already uses, and keeps. */
+  live: string;
+}
+
+/** One live multi-role policy that satisfies a GROUP of declared per-role policies. */
+export interface AdoptedGroup {
+  /** The per-role policies the model would have created, sorted. */
+  declared: string[];
+  /** The single live policy that already authorizes exactly the same thing. */
+  live: string;
+}
+
+export interface PolicyMatch {
+  /**
+   * Rule-identical pairs whose NAMES differ. These emit nothing: the live policy already IS
+   * the declared authorization, and renaming it would be DDL that buys spelling.
+   */
+  adopted: AdoptedPolicy[];
+  /**
+   * Live multi-role policies satisfying a declared per-role group. Postgres applies a policy
+   * per session role by membership, so one policy `TO a, b` and two identical-predicate
+   * policies `TO a` and `TO b` are applicable to exactly the same sessions.
+   */
+  adoptedGroups: AdoptedGroup[];
+  /** Declared policies with no live counterpart — emit `CREATE POLICY`. */
+  toCreate: PolicyContract[];
+  /** Live policy NAMES with no declared counterpart — emit `DROP POLICY`. */
+  toDrop: string[];
+}
+
+/**
+ * Match declared policies to live ones, deterministically and ONE-TO-ONE in both directions.
+ *
+ * Three passes, in order. The order is part of the contract, not an implementation detail —
+ * the emitter and the differ must reach the same answer or they contradict each other:
+ *
+ *   1. **Name AND rule agree** — already reconciled, nothing to do, no adoption recorded.
+ *   2. **Rule agrees among the leftovers** — adopt: keep the live name, emit nothing. Ties
+ *      (two live policies of the same rule competing for one declared policy) break
+ *      lexicographically by LIVE name, so both surfaces pick the same survivor.
+ *   3. **Everything still unmatched** — declared → CREATE, live → DROP. This includes a name
+ *      match whose rule differs, which is a real change and must still be re-created.
+ *
+ * One-to-one runs both directions: a declared policy is consumed at most once, so it can never
+ * "satisfy" two overlapping live policies and leave the second silently in place.
+ */
+export function matchPolicies(
+  declared: readonly PolicyContract[],
+  live: readonly PolicyContract[],
+): PolicyMatch {
+  const adopted: AdoptedPolicy[] = [];
+  const declaredLeft = new Map(declared.map((p) => [p.name, p]));
+  const liveLeft = new Map(live.map((p) => [p.name, p]));
+
+  // Pass 1 — name and rule both agree. Sorted so the walk order cannot depend on input order.
+  for (const name of [...declaredLeft.keys()].sort()) {
+    const d = declaredLeft.get(name)!;
+    const l = liveLeft.get(name);
+    if (l && policyRuleEqual(d, l)) {
+      declaredLeft.delete(name);
+      liveLeft.delete(name);
+    }
+  }
+
+  // Pass 2 — same rule, different name. The live name wins and the pair emits nothing.
+  // Declared side walked in sorted order, live candidates chosen by sorted name, so the
+  // result is a pure function of the two sets and never of their input order.
+  for (const dName of [...declaredLeft.keys()].sort()) {
+    const d = declaredLeft.get(dName)!;
+    const candidate = [...liveLeft.keys()].sort().find((lName) => policyRuleEqual(d, liveLeft.get(lName)!));
+    if (candidate !== undefined) {
+      adopted.push({ declared: dName, live: candidate });
+      declaredLeft.delete(dName);
+      liveLeft.delete(candidate);
+    }
+  }
+
+  // Pass 2b — the ROLE AXIS, and only the role axis.
+  //
+  // A live policy `TO a, b` and two declared policies `TO a` / `TO b` with the same predicate
+  // are applicable to precisely the same sessions: Postgres selects policies per session role
+  // by membership. So the live one already authorizes what the group declares.
+  //
+  // Three conditions, all required, and each closes a way to be wrong:
+  //   - every field but the roles is identical (never the command axis — USING/CHECK
+  //     applicability differs per command, and that is where false equivalence breeds);
+  //   - each member's roles are a SUBSET of the live policy's, so a member can never smuggle
+  //     in a role the live policy did not cover;
+  //   - the members are pairwise DISJOINT and their union EQUALS the live role set exactly.
+  //     Subset never matches: a live `TO anon, authenticated` must not be satisfied by a
+  //     declared anon policy alone, which would leave `authenticated` reading rows the model
+  //     believes it no longer grants.
+  //
+  // PUBLIC cannot be reached from here. It is an open set, and no union of enumerated roles
+  // can equal it — `roleSetEqual` decides that, and nothing folds case into it.
+  const adoptedGroups: AdoptedGroup[] = [];
+  for (const lName of [...liveLeft.keys()].sort()) {
+    const live = liveLeft.get(lName)!;
+    if (live.roles.length < 2) continue; // a single-role live policy is pass 2's job
+
+    const members: PolicyContract[] = [];
+    const seen = new Set<string>();
+    for (const dName of [...declaredLeft.keys()].sort()) {
+      const d = declaredLeft.get(dName)!;
+      if (!sameRuleIgnoringRoles(d, live)) continue;
+      if (!d.roles.every((r) => live.roles.includes(r))) continue; // subset only
+      if (d.roles.some((r) => seen.has(r))) continue;              // pairwise disjoint
+      d.roles.forEach((r) => seen.add(r));
+      members.push(d);
+    }
+    if (!members.length) continue;
+    if (!roleSetEqual([...seen], live.roles)) continue; // exact union, never a subset
+
+    adoptedGroups.push({ declared: members.map((m) => m.name).sort(), live: lName });
+    liveLeft.delete(lName);
+    for (const m of members) declaredLeft.delete(m.name);
+  }
+
+  // Pass 3 — no counterpart, or a name match whose rule changed.
+  return {
+    adopted,
+    adoptedGroups,
+    toCreate: [...declaredLeft.keys()].sort().map((n) => declaredLeft.get(n)!),
+    toDrop: [...liveLeft.keys()].sort(),
+  };
+}