@everystack/cli 0.4.44 → 0.4.45

package/src/cli/authz-contract.ts

@@ -23,6 +23,7 @@
 
 import { parsePgArray } from './security-catalog.js';
 import { withCanonicalSearchPath } from './search-path.js';
+import { matchPolicies, roleSetEqual } from './authz-identity.js';
 
 // ---------------------------------------------------------------------------
 // The contract format — the frozen, reviewable, version-controlled shape.
@@ -100,6 +101,42 @@ export function effectivePolicyCheck(p: PolicyContract): string | null {
   return p.check;
 }
 
+/**
+ * Does a role hold a privilege at the TABLE level? — the question "may we emit an ability?"
+ *
+ * `can('update')` compiles to a policy PLUS a table-wide `GRANT UPDATE`. So a role that holds
+ * UPDATE only on three columns does NOT satisfy this: rendering the ability would widen a
+ * column grant into a whole-table one. PUBLIC counts, in both catalog spellings, because a
+ * grant to PUBLIC really is held by every role.
+ */
+export function holdsTablePrivilege(t: TableContract, role: string, privilege: string): boolean {
+  const direct = t.grants[role] ?? [];
+  const pub = t.grants.PUBLIC ?? t.grants.public ?? [];
+  return direct.includes(privilege) || pub.includes(privilege);
+}
+
+/**
+ * Does a role hold a privilege AT ALL? — the question "does this policy authorize anything?"
+ *
+ * The same question one layer wider: a COLUMN-scoped grant counts. `GRANT UPDATE (body) ON t
+ * TO authenticated` really does let that role update, so a policy governing UPDATE is doing
+ * live work even though the role holds no table-level UPDATE.
+ *
+ * TWO PREDICATES ON PURPOSE, and they answer different questions — that is why they are here
+ * together rather than one being written twice. `db:pull` used the narrow one to answer the
+ * wide question and told adopters a live, column-granted UPDATE policy was "dead code today,
+ * declaring it would ADD a privilege the database does not give". Both halves were false, and
+ * it was printed beside the model they were about to trust. Use {@link holdsTablePrivilege} to
+ * decide what to EMIT; use this to decide what is DEAD.
+ */
+export function holdsPrivilege(t: TableContract, role: string, privilege: string): boolean {
+  if (holdsTablePrivilege(t, role, privilege)) return true;
+  const cols = t.columnGrants ?? {};
+  return Boolean(cols[role]?.[privilege]?.length)
+    || Boolean(cols.PUBLIC?.[privilege]?.length)
+    || Boolean(cols.public?.[privilege]?.length);
+}
+
 /** True when `s`'s outer parens already wrap the whole expression (redundant to add more). */
 export function isWrappedExpression(s: string): boolean {
   if (!s.startsWith('(') || !s.endsWith(')')) return false;
@@ -509,6 +546,24 @@ export async function introspectContract(
 
 export type DriftSeverity = 'drift';
 
+/** A live policy kept under its own name because it already carries the declared rule. */
+export interface PolicyAdoption {
+  /** Schema-qualified table. */
+  subject: string;
+  /** The policy name(s) the model would have created. */
+  declared: string[];
+  /** The name the database uses, and keeps. */
+  live: string;
+  /** Why it was accepted, in plain words. */
+  reason: string;
+}
+
+/** Drift, plus the adoptions that are deliberately NOT drift. */
+export interface ContractComparison {
+  findings: DriftFinding[];
+  adoptions: PolicyAdoption[];
+}
+
 export interface DriftFinding {
   /** Schema-qualified table, or `fn:<name>` for a function finding. */
   subject: string;
@@ -528,7 +583,20 @@ function tableMap(c: AuthzContract): Map<string, TableContract> {
  * Returns every discrepancy; an empty list means the live DB matches the declaration.
  */
 export function diffContracts(declared: AuthzContract, live: AuthzContract): DriftFinding[] {
+  return compareContracts(declared, live).findings;
+}
+
+/**
+ * The full comparison: drift AND the name divergences accepted by rule.
+ *
+ * `diffContracts` returns only the findings, because every caller treats a finding as drift
+ * and exits non-zero. An adoption is the opposite of drift, so it cannot travel in that list —
+ * but it must still be SHOWN, or the mapping between the model's name and the database's name
+ * becomes tribal knowledge.
+ */
+export function compareContracts(declared: AuthzContract, live: AuthzContract): ContractComparison {
   const findings: DriftFinding[] = [];
+  const adoptions: PolicyAdoption[] = [];
   const dTables = tableMap(declared);
   const lTables = tableMap(live);
 
@@ -546,7 +614,7 @@ export function diffContracts(declared: AuthzContract, live: AuthzContract): Dri
     }
     diffGrants(name, d, l, findings);
     diffColumnGrants(name, d, l, findings);
-    diffPolicies(name, d, l, findings);
+    diffPolicies(name, d, l, findings, adoptions);
   }
   for (const name of lTables.keys()) {
     if (!dTables.has(name)) {
@@ -575,7 +643,7 @@ export function diffContracts(declared: AuthzContract, live: AuthzContract): Dri
     }
   }
 
-  return findings;
+  return { findings, adoptions };
 }
 
 function diffGrants(table: string, d: TableContract, l: TableContract, out: DriftFinding[]): void {
@@ -612,31 +680,58 @@ function diffColumnGrants(table: string, d: TableContract, l: TableContract, out
   }
 }
 
-function diffPolicies(table: string, d: TableContract, l: TableContract, out: DriftFinding[]): void {
-  const dPol = new Map(d.policies.map((p) => [p.name, p]));
-  const lPol = new Map(l.policies.map((p) => [p.name, p]));
-  for (const [name, dp] of dPol) {
-    const lp = lPol.get(name);
-    if (!lp) {
-      out.push({ subject: table, kind: 'policy', detail: `policy "${name}" declared but missing from the live database` });
-      continue;
-    }
+/**
+ * Diff policies through the SHARED matcher — the same equivalence `emitReconcileSql` and the
+ * fingerprint use. A rule-identical live policy under a different name is not drift: the
+ * database already authorizes exactly what the model declares.
+ *
+ * Adoptions travel on their own channel, not as findings. A finding means drift and drift
+ * means exit 1, while an adoption is agreement. It is never SILENT though — once a live policy
+ * keeps its own name, the name the model shows and the name a human greps for have diverged,
+ * and that mapping has to stay machine-derived and visible.
+ */
+function diffPolicies(
+  table: string,
+  d: TableContract,
+  l: TableContract,
+  out: DriftFinding[],
+  adoptions: PolicyAdoption[],
+): void {
+  const m = matchPolicies(d.policies, l.policies);
+
+  for (const a of m.adopted) {
+    adoptions.push({ subject: table, declared: [a.declared], live: a.live, reason: 'same rule, different name' });
+  }
+  for (const g of m.adoptedGroups) {
+    adoptions.push({ subject: table, declared: g.declared, live: g.live, reason: 'one live policy covers the declared per-role group' });
+  }
+
+  // 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.
+  const createdByName = new Map(m.toCreate.map((p) => [p.name, p]));
+  const changed = new Set<string>();
+  for (const name of m.toDrop) {
+    const dp = createdByName.get(name);
+    if (!dp) continue;
+    const lp = l.policies.find((p) => p.name === name)!;
+    changed.add(name);
     const changes: string[] = [];
-    if (dp.command !== lp.command) changes.push(`command ${dp.command}→${lp.command}`);
-    if (dp.permissive !== lp.permissive) changes.push(`permissive ${dp.permissive}→${lp.permissive}`);
-    if (dp.roles.join(',') !== lp.roles.join(',')) changes.push(`roles [${dp.roles}]→[${lp.roles}]`);
-    if ((dp.using ?? '') !== (lp.using ?? '')) changes.push(`USING changed`);
-    // Compared through the server's own defaulting rule, so this agrees with
-    // emitReconcileSql — otherwise db:check reports drift the plan does not carry.
-    if ((effectivePolicyCheck(dp) ?? '') !== (effectivePolicyCheck(lp) ?? '')) changes.push(`WITH CHECK changed`);
-    if (changes.length) {
-      out.push({ subject: table, kind: 'policy', detail: `policy "${name}": ${changes.join(', ')}` });
-    }
+    if (dp.command !== lp.command) changes.push(`command ${dp.command}\u2192${lp.command}`);
+    if (dp.permissive !== lp.permissive) changes.push(`permissive ${dp.permissive}\u2192${lp.permissive}`);
+    if (!roleSetEqual(dp.roles, lp.roles)) changes.push(`roles [${dp.roles}]\u2192[${lp.roles}]`);
+    if ((dp.using ?? '') !== (lp.using ?? '')) changes.push('USING changed');
+    if ((effectivePolicyCheck(dp) ?? '') !== (effectivePolicyCheck(lp) ?? '')) changes.push('WITH CHECK changed');
+    out.push({ subject: table, kind: 'policy', detail: `policy "${name}": ${changes.join(', ')}` });
   }
-  for (const name of lPol.keys()) {
-    if (!dPol.has(name)) {
-      out.push({ subject: table, kind: 'policy', detail: `policy "${name}" exists live but is not declared (undeclared policy)` });
-    }
+
+  for (const p of m.toCreate) {
+    if (changed.has(p.name)) continue;
+    out.push({ subject: table, kind: 'policy', detail: `policy "${p.name}" declared but missing from the live database` });
+  }
+  for (const name of m.toDrop) {
+    if (changed.has(name)) continue;
+    out.push({ subject: table, kind: 'policy', detail: `policy "${name}" exists live but is not declared (undeclared policy)` });
   }
 }
 

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[] {
@@ -219,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')) {
+      if (!live.length || !p.roles.some((r) => r !== 'admin')) continue;
+      const viaColumns = live.filter((r) => holdsPrivilege(contract, r, priv));
+      if (viaColumns.length) {
         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.`,
+          `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.`,
+      );
     }
   }
 
@@ -328,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',
@@ -337,7 +410,12 @@ 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. */
@@ -353,5 +431,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(),
+  };
+}