@everystack/cli 0.4.44 → 0.4.46

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)))
@@ -181,12 +215,15 @@ export function parsePublicOrOwn(
   return { owner, ownerSql: rest[0] ?? 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);
-}
+/**
+ * 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[] {
@@ -203,6 +240,58 @@ function sqlFragment(pred: string | null): string | null {
   return `sql\`${t.replace(/`/g, '\\`')}\``;
 }
 
+/** The policy catalog spells the PUBLIC pseudo-role lower-case; grants spell it upper-case. */
+function policyRoleForGrantee(grantee: string): string {
+  return grantee === 'PUBLIC' ? 'public' : grantee;
+}
+
+/** `db:pull` renders fields camel-cased; abilities must name those same model keys. */
+function modelFieldKey(column: string): string {
+  return column.replace(/_([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+/** One column grant is renderable only when exactly one declared-style policy gates it. */
+function columnPolicyFor(contract: TableContract, grantee: string, command: string): PolicyContract | null {
+  const role = policyRoleForGrantee(grantee);
+  const matches = contract.policies.filter((p) =>
+    p.command === command && p.permissive && p.roles.length === 1 && p.roles[0] === role,
+  );
+  return matches.length === 1 ? matches[0] : null;
+}
+
+/** Render one precise column grant plus its exactly-paired policy as one ability. */
+function renderColumnAbility(
+  action: 'read' | 'update',
+  grantee: string,
+  columns: readonly string[],
+  policy: PolicyContract,
+): string | null {
+  const using = policy.using ?? null;
+  const owner = parseOwnerPredicate(using);
+  const parts: string[] = [];
+  const role = policyRoleForGrantee(grantee);
+
+  // Owner-only uses the model's authenticated default. Every other grantee must be named so
+  // the compiler emits the policy TO the live role, rather than a role-less public ability.
+  if (!owner || role !== 'authenticated') parts.push(`role: '${role}'`);
+  if (owner) {
+    parts.push(`owner: '${modelFieldKey(owner.column)}'`);
+    if (owner.claim !== 'sub') parts.push(`userField: '${owner.claim}'`);
+    if (owner.expr) parts.push(`ownerExpr: sql\`${owner.expr}\``);
+  } else {
+    const fragment = sqlFragment(using);
+    if (fragment) parts.push(`sql: ${fragment}`);
+  }
+
+  if (action === 'update' && policy.check && policy.check !== using) {
+    const fragment = sqlFragment(policy.check);
+    if (!fragment) return null;
+    parts.push(`check: ${fragment}`);
+  }
+  parts.push(`columns: [${columns.map((column) => `'${modelFieldKey(column)}'`).join(', ')}]`);
+  return `can('${action}', { ${parts.join(', ')} })`;
+}
+
 /**
  * Derive the ability stanza for ONE table from its live contract.
  *
@@ -219,21 +308,34 @@ 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 —`,
-        );
-        notes.push(
-          `  it is dead code today. Declaring it would ADD a privilege the database does not give.`,
-        );
+      if (!live.length || !p.roles.some((r) => r !== 'admin')) continue;
+      const viaColumns = live.filter((r) => holdsPrivilege(contract, r, priv));
+      if (viaColumns.length) {
+        // The column-grant pass below carries this pair into a column ability, or names the
+        // exact missing pairing. Do not pre-judge it here as dead or unrenderable.
+        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.`,
+      );
     }
   }
 
@@ -247,7 +349,6 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
     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
@@ -258,25 +359,94 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
       ? 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.
+    const diverges = !!authedPol && (authedPred ?? 'true') !== (anonPred ?? 'true');
+    const own = diverges ? parsePublicOrOwn(authedPred, anonPred) : null;
+
+    // A role-less `can('read')` fans out to anon AND authenticated — one ability, two policies
+    // and two GRANTS. That is only honest when both roles genuinely hold a table-level SELECT
+    // and the same rule. Two separate ways it was not:
+    //
+    //   - WIDENING: `authedRead` is a TABLE-level check, so a live authenticated SELECT held
+    //     only through COLUMN grants reads as false. The fan-out then granted authenticated
+    //     SELECT on the WHOLE table — the model meaning MORE than the database, which is the
+    //     one thing this project never does. Now the read is scoped to anon alone.
+    //   - NARROWING: when the authenticated rule diverges and cannot be decomposed, the
+    //     fan-out pushed the ANON predicate onto authenticated, silently replacing a live
+    //     owner-admitting read with a public-only one. Now each role carries its own rule.
+    // The fan-out is honest in exactly two cases, and both need authenticated to hold a real
+    // table-level SELECT:
+    //   - the two roles carry the SAME rule, so one ability states it once; or
+    //   - the rule DECOMPOSES, and the `owner:` ability below ADDS the owner branch on top of
+    //     this public one. Scoping this read to anon there would strip authenticated of the
+    //     public half — a narrowing introduced by the fix itself.
+    const fanOutIsHonest = authedRead && (!diverges || !!own);
+
+    // The live read is ONE policy TO PUBLIC — the ordinary Postgres idiom, and an OPEN
+    // audience. Rendering it as the role-scoped pair would mean strictly less than the
+    // database does: every role outside {anon, authenticated} loses the read. `policyRoles`
+    // says the audience without touching the grants, so this transcribes rather than narrows
+    // (B1). Only when PUBLIC is the whole audience — a policy naming public ALONGSIDE a
+    // named role is a different shape and is left to the branches below.
+    const publicAudience = !!anonPol && anonPol.roles.length === 1 && anonPol.roles[0] === 'public';
+
+    if (publicAudience) {
+      abilities.push(frag ? `can('read', { policyRoles: 'public', sql: ${frag} })` : `can('read', { policyRoles: 'public' })`);
+
+      // An OPEN audience must say who it actually opens to, ON THIS TABLE.
+      //
+      // `policyRoles: 'public'` reads like "anyone", and the model vocabulary only names
+      // anon/authenticated/admin — so a reviewer has no way to know that a migrator or an ETL
+      // role also holds SELECT here and therefore reads rows through this very policy. The
+      // pull already names ungoverned grantees once, globally, on stdout; that is the wrong
+      // place and the wrong granularity for a decision recorded per table in a committed file.
+      // Adopting an open audience without seeing its real membership is exactly "inert must
+      // never mean blind".
+      const openTo = Object.keys(contract.grants)
+        .filter((r) => !GOVERNED_VOCABULARY.has(r) && holdsPrivilege(contract, r, 'SELECT'))
+        .sort();
+      if (openTo.length) {
         notes.push(
-          `policy "${authedPol.name}" (SELECT) grants authenticated MORE than the anon read,`,
+          `policyRoles: 'public' is an OPEN audience — it also admits ${openTo.join(', ')}, which hold`,
         );
-        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.`);
+        notes.push(`  SELECT on this table. The grants are unchanged; this names who the policy reaches.`);
       }
+    } else if (fanOutIsHonest) {
+      abilities.push(frag ? `can('read', { sql: ${frag} })` : `can('read')`);
+    } else {
+      abilities.push(frag ? `can('read', { role: 'anon', sql: ${frag} })` : `can('read', { role: 'anon' })`);
+    }
+
+    if (diverges && 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 if (diverges && authedRead) {
+      // TRANSCRIBE, never synthesize. The structured parse failed, so the live predicate is
+      // carried VERBATIM and scoped to exactly the role that holds it — meaning preserved
+      // bit for bit, at the cost of a model that expresses little. The note below is
+      // DISCLOSURE, not refusal: `verbatim-sql:` is a stable marker so an adoption that
+      // reached zero through escape hatches can be counted apart from one that reached zero
+      // through vocabulary. Fidelity achieved is not expressiveness achieved.
+      abilities.push(`can('read', { role: 'authenticated', sql: sql\`${authedPred!.replace(/`/g, '\\`')}\` })`);
+      notes.push(
+        `verbatim-sql: policy "${authedPol!.name}" (SELECT) grants authenticated MORE than the anon read.`,
+      );
+      notes.push(`  Its shape does not decompose, so it is transcribed VERBATIM above, scoped to`);
+      notes.push(`  authenticated. The model does not interpret it. Restructure by hand into`);
+      notes.push(`  owner:/via: when you can — until then this table is adopted, not expressed.`);
+    } else if (diverges) {
+      // Diverges, and authenticated does NOT hold a table-level SELECT — a column-scoped grant,
+      // or none. Rendering the read either way would widen it to the whole table, so we refuse
+      // and say so. The residual statements in db:plan ARE the visibility here.
+      notes.push(
+        `policy "${authedPol!.name}" (SELECT) grants authenticated MORE than the anon read,`,
+      );
+      notes.push(`  but authenticated holds no TABLE-level SELECT — rendering it would widen a`);
+      notes.push(`  column-scoped grant to the whole table. NOT rendered. Live USING:`);
+      notes.push(`    ${authedPred}`);
     }
   } else if (authedRead) {
     const pol = policiesFor(contract, 'authenticated', 'SELECT')[0];
@@ -328,16 +498,49 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
     abilities.push(`can('${action}'${parts.length ? `, { ${parts.join(', ')} }` : ''})`);
   }
 
+  // --- column grants ---------------------------------------------------------------------
+  //
+  // A column grant is live access, not a lesser table grant. Render SELECT and UPDATE when
+  // exactly one permissive policy TO the same role proves the row gate. Anything else stays a
+  // note: guessing the pairing could grant the right columns under the wrong row policy.
+  const renderedColumnRoles = new Set<string>();
+  for (const grantee of Object.keys(contract.columnGrants ?? {}).sort()) {
+    const byPriv = contract.columnGrants![grantee];
+    for (const priv of Object.keys(byPriv).sort()) {
+      const cols = byPriv[priv] ?? [];
+      if (!cols.length) continue;
+      const action = priv === 'SELECT' ? 'read' : priv === 'UPDATE' ? 'update' : null;
+      const policy = action ? columnPolicyFor(contract, grantee, priv) : null;
+      const ability = action && policy ? renderColumnAbility(action, grantee, cols, policy) : null;
+      if (ability) {
+        abilities.push(ability);
+        renderedColumnRoles.add(grantee);
+        continue;
+      }
+      notes.push(`${grantee} holds a COLUMN-scoped ${priv} on ${cols.length} column(s): ${cols.join(', ')}.`);
+      notes.push(
+        action
+          ? `  NOT rendered — it needs exactly one permissive ${priv} policy TO ${policyRoleForGrantee(grantee)}.`
+          : `  NOT rendered — the model supports column-scoped SELECT and UPDATE only.`,
+      );
+    }
+  }
+
   // --- roles the compiler has no vocabulary for ----------------------------------------
   const unmappedRoles = Object.keys(contract.grants).filter(
-    (r) => !KNOWN_ROLES.has(r) && r !== 'PUBLIC' && r !== 'public',
+    (r) => !KNOWN_ROLES.has(r) && r !== 'PUBLIC' && r !== 'public' && !renderedColumnRoles.has(r),
   );
 
   if (!abilities.length && !notes.length && !unmappedRoles.length) {
     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. */
@@ -353,5 +556,12 @@ export function renderDerivedAbilities(d: DerivedAbilities): string {
   } 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(),
+  };
+}