@everystack/cli 0.4.44 → 0.4.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.44",
+  "version": "0.4.45",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -109,7 +109,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.4.9"
+    "@everystack/model": "0.4.10"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.4.0",

package/src/cli/authz-adoption-class.ts

@@ -0,0 +1,265 @@
+/**
+ * authz-adoption-class — WHY does this statement exist?
+ *
+ * A brownfield adopter's first plan is long, and the length is not the problem. The problem is
+ * that nobody can tell which statements are the tool imposing its own spelling and which are
+ * real differences between the model and the database. This classifier answers that, per
+ * statement, mechanically.
+ *
+ * FOUR CLASSES, and the whole point is that the first one should reach zero:
+ *
+ *  - `convention`  — exists ONLY because we spell a semantically identical rule differently.
+ *                    Every one of these is our bug. Phase A's success criterion is zero.
+ *  - `capability`  — the model cannot express what is live, so the plan would remove it.
+ *                    Real, and a gap in everystack, not in their schema.
+ *  - `narrowing`   — a genuine reduction of access. Must ship, labeled, and be approved by a
+ *                    human before it is applied.
+ *  - `dead`        — the live object is dead code: policed but never granted, so it authorizes
+ *                    nothing today.
+ *
+ * NAME COLLISION, stated once so nobody conflates them. `edge-plan.ts` already has
+ * `PlanClassification.narrowings`, which means a DATA-LOSSY `ALTER COLUMN … TYPE`. This
+ * `narrowing` means an ACCESS reduction. They are two orthogonal axes on the same statement —
+ * one asks "what does it cost?", the other asks "why is it here?" — and both are correct in
+ * their own frame. This module deliberately does NOT extend `PlanClassification`.
+ *
+ * READ-ONLY. Nothing here changes what is emitted. It reasons over the same declared and live
+ * contracts the emitter does, and a test pins its statement list to the emitter's actual
+ * output so the two can never drift apart.
+ */
+
+import { matchPolicies, roleSetEqual } from './authz-identity.js';
+import { governedRoleSet } from './authz-reconcile.js';
+import { effectivePolicyCheck, holdsPrivilege } from './authz-contract.js';
+import type { AuthzContract, PolicyContract, TableContract } from './authz-contract.js';
+
+export type AdoptionClass = 'convention' | 'capability' | 'narrowing' | 'dead' | 'unclassified';
+
+export interface ClassifiedStatement {
+  table: string;
+  /** The statement's subject — a policy name, or `grantee` for a privilege change. */
+  subject: string;
+  cls: AdoptionClass;
+  /** One line, in plain words, for the plan's report. */
+  why: string;
+}
+
+export interface AdoptionCounts {
+  convention: number;
+  capability: number;
+  narrowing: number;
+  dead: number;
+  unclassified: number;
+}
+
+/**
+ * The reconciler's own exemption rule, mirrored: a grantee the declared authz does not govern
+ * is left alone. `PUBLIC` compares case-insensitively because it is a pseudo-role with two
+ * catalog spellings; every other name compares exactly.
+ */
+function isGovernedGrantee(governed: ReadonlySet<string>, grantee: string): boolean {
+  return governed.has(grantee) || (grantee.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'));
+}
+
+const CRUD = ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
+
+/**
+ * Does `outer` cover every role in `inner`?
+ *
+ * PUBLIC (`['public']`) covers everything — it is an open set. That fact is used HERE ONLY, to
+ * decide whether a live policy's replacement is narrower (a label). It is deliberately NOT
+ * available to the matcher: letting PUBLIC compare equal to an enumerated set there would be
+ * the false match the whole phase exists to prevent. Labeling cannot widen access; matching
+ * can.
+ */
+function covers(outer: readonly string[], inner: readonly string[]): boolean {
+  if (outer.includes('public')) return true;
+  const o = new Set(outer);
+  return inner.every((r) => o.has(r));
+}
+
+/** Same authorization on every axis EXCEPT which roles it names — the role-split test. */
+function sameRule(a: PolicyContract, b: PolicyContract): boolean {
+  return a.command === b.command
+    && a.permissive === b.permissive
+    && (a.using ?? '') === (b.using ?? '')
+    && (effectivePolicyCheck(a) ?? '') === (effectivePolicyCheck(b) ?? '');
+}
+
+/** Every command a policy governs — `ALL` fans out, so a live `FOR ALL` is compared per command. */
+function commandsOf(p: PolicyContract): string[] {
+  return p.command === 'ALL' ? [...CRUD] : [p.command];
+}
+
+/**
+ * A policy is DEAD when no role it applies to holds the privilege it polices. Postgres checks
+ * the GRANT before the policy, so such a policy authorizes nothing — removing it takes away
+ * access that was never there. A PUBLIC policy applies to every grantee, so it is dead only if
+ * NO grantee holds the privilege at all.
+ */
+function isDead(t: TableContract, p: PolicyContract): boolean {
+  const roles = p.roles.includes('public') ? Object.keys(t.grants) : p.roles;
+  if (!roles.length) return true;
+  // `holdsPrivilege`, not the table-level one: a column-scoped grant is real access, and
+  // "dead" tells an operator the drop takes away nothing. Shared with db:pull so the two can
+  // never answer this differently about one database.
+  return !commandsOf(p).some((cmd) => roles.some((r) => holdsPrivilege(t, r, cmd)));
+}
+
+/** Classify the policy statements one table would emit. */
+function classifyPolicies(d: TableContract, l: TableContract, out: ClassifiedStatement[]): void {
+  const table = d.table;
+  const m = matchPolicies(d.policies, l.policies);
+
+  // Adopted shapes — a rule-identical policy under another name, or a live multi-role policy
+  // covering the declared per-role group — emit NOTHING, so there is nothing here to classify.
+  // This is what driving `convention` toward zero looks like: the statements stop existing
+  // rather than getting a nicer label.
+
+  const declaredByName = new Map(m.toCreate.map((p) => [p.name, p]));
+  const consumed = new Set<string>();
+
+  for (const name of m.toDrop) {
+    const live = l.policies.find((p) => p.name === name)!;
+
+    if (isDead(l, live)) {
+      out.push({ table, subject: name, cls: 'dead', why: `policed but never granted — it authorizes nothing today` });
+      continue;
+    }
+
+    // A replacement exists when some declared policy governs the same command. If those
+    // replacements together cover FEWER roles than the live policy did, the plan is reducing
+    // access — a narrowing, which must be approved rather than merely applied.
+    const replacements = m.toCreate.filter(
+      (c) => commandsOf(c).some((cmd) => commandsOf(live).includes(cmd)),
+    );
+    if (!replacements.length) {
+      out.push({ table, subject: name, cls: 'capability', why: `no declared policy governs ${commandsOf(live).join('/')} — the model cannot express this rule` });
+      continue;
+    }
+
+    const replacementRoles = [...new Set(replacements.flatMap((r) => r.roles))];
+
+    // The role split: one live policy covering several roles, against the per-role policies the
+    // compiler emits. Same predicate, and the declared roles union to EXACTLY the live role set,
+    // so the two authorize identically for every session. Pure spelling — ours to fix (A5).
+    // Note this is recognized here for LABELING before the matcher can act on it; the two must
+    // agree once A5 lands, which is what the emitter-parity test pins.
+    if (roleSetEqual(live.roles, replacementRoles) && replacements.every((r) => sameRule(r, live))) {
+      out.push({ table, subject: name, cls: 'convention', why: `live covers ${live.roles.join(' + ')} in one policy; we split it per role with the same predicate` });
+      for (const r of replacements) {
+        if (consumed.has(r.name)) continue;
+        consumed.add(r.name);
+        out.push({ table, subject: r.name, cls: 'convention', why: `the per-role half of "${name}"` });
+      }
+      continue;
+    }
+
+    if (covers(live.roles, replacementRoles) && !roleSetEqual(live.roles, replacementRoles)) {
+      out.push({ table, subject: name, cls: 'narrowing', why: `live applies to ${live.roles.join(', ')}; the declared replacement covers only ${replacementRoles.join(', ')}` });
+      for (const r of replacements) {
+        if (consumed.has(r.name)) continue;
+        consumed.add(r.name);
+        out.push({ table, subject: r.name, cls: 'narrowing', why: `the narrower replacement for "${name}"` });
+      }
+      continue;
+    }
+
+    out.push({ table, subject: name, cls: 'unclassified', why: `dropped with a replacement that is neither the same rule nor narrower` });
+  }
+
+  for (const [name] of declaredByName) {
+    if (consumed.has(name)) continue;
+    out.push({ table, subject: name, cls: 'unclassified', why: `created with no live counterpart` });
+  }
+}
+
+/** Classify the privilege statements one table would emit. */
+function classifyGrants(
+  d: TableContract,
+  l: TableContract,
+  governed: ReadonlySet<string>,
+  out: ClassifiedStatement[],
+): void {
+  const table = d.table;
+
+  for (const grantee of Object.keys(l.grants).sort()) {
+    // The reconciler LEAVES ungoverned grantees alone — a migrator or BI reader the model
+    // vocabulary cannot name keeps its access, reported instead of revoked. It emits nothing
+    // for them, so neither may we: counting statements that are never emitted would describe
+    // a plan nobody is going to apply.
+    if (!isGovernedGrantee(governed, grantee)) continue;
+    const declared = new Set(d.grants[grantee] ?? []);
+    const live = l.grants[grantee] ?? [];
+    const revoked = live.filter((p) => !declared.has(p));
+    if (!revoked.length) continue;
+
+    // Every revoke here is now a NARROWING, including the beyond-CRUD trio.
+    //
+    // It used to be `convention` for REFERENCES/TRIGGER/TRUNCATE: `manage` means exactly CRUD,
+    // so live admin holding those three read as drift and the plan revoked them — 28 statements
+    // on the reference schema, none of which anybody asked for. The model has a word for them
+    // now (`privileges`), and `db:pull` transcribes what is live, so a pulled model emits
+    // nothing. A model that does NOT declare them is choosing to remove them, which is a real
+    // access reduction and gets labeled as one. The fix is at the source, not in the label.
+    out.push({ table, subject: grantee, cls: 'narrowing', why: `revokes ${revoked.join(', ')} from ${grantee}` });
+  }
+
+  // Column grants: the model expresses column scoping for READ only, so a live column-scoped
+  // UPDATE has no declaration and the plan revokes it. That is a gap in everystack.
+  const lcg = l.columnGrants ?? {};
+  const dcg = d.columnGrants ?? {};
+  for (const grantee of Object.keys(lcg).sort()) {
+    if (!isGovernedGrantee(governed, grantee)) continue;
+    for (const priv of Object.keys(lcg[grantee]).sort()) {
+      const declaredCols = new Set(dcg[grantee]?.[priv] ?? []);
+      const revoked = (lcg[grantee][priv] ?? []).filter((c) => !declaredCols.has(c));
+      if (!revoked.length) continue;
+      out.push({ table, subject: `${grantee}/${priv}`, cls: 'capability', why: `column-scoped ${priv} on ${revoked.length} column(s) — the model declares columns for read only` });
+    }
+  }
+}
+
+/**
+ * Classify every authorization statement the plan would emit, per table.
+ *
+ * Live tables no model declares are skipped: the plan does not touch them, so they contribute
+ * no statements to classify.
+ */
+export function classifyAdoption(
+  declared: AuthzContract,
+  live: AuthzContract,
+  opts: { governedRoles?: ReadonlySet<string> } = {},
+): {
+  statements: ClassifiedStatement[];
+  counts: AdoptionCounts;
+} {
+  const governed = opts.governedRoles ?? governedRoleSet(declared);
+  const liveByTable = new Map(live.tables.map((t) => [t.table, t]));
+  const statements: ClassifiedStatement[] = [];
+
+  for (const d of declared.tables) {
+    const l = liveByTable.get(d.table);
+    if (!l) continue; // a brand-new table adds; nothing here is an adoption decision
+    classifyPolicies(d, l, statements);
+    classifyGrants(d, l, governed, statements);
+  }
+
+  const counts: AdoptionCounts = { convention: 0, capability: 0, narrowing: 0, dead: 0, unclassified: 0 };
+  for (const s of statements) counts[s.cls]++;
+  return { statements, counts };
+}
+
+/** The report block for the plan surface. Terse: one line per class, then the offenders. */
+export function renderAdoptionReport(counts: AdoptionCounts): string[] {
+  const lines = [
+    `  convention   ${counts.convention}  — our spelling, not their schema (this must reach 0)`,
+    `  capability   ${counts.capability}  — the model cannot express what is live`,
+    `  narrowing    ${counts.narrowing}  — real access reduction, approve before applying`,
+    `  dead         ${counts.dead}  — policed but never granted`,
+  ];
+  if (counts.unclassified) {
+    lines.push(`  unclassified ${counts.unclassified}  — NOT described; read these before applying`);
+  }
+  return lines;
+}

package/src/cli/authz-baseline.ts

@@ -36,6 +36,7 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { FINGERPRINT_VERSION } from './schema-fingerprint.js';
 import type { GrantExemption } from './authz-reconcile.js';
 
 /** The repo-relative artifact. Generated — regenerating it must reproduce it byte for byte. */
@@ -58,6 +59,15 @@ export interface BaselineStage {
   observedAt: string;
   /** The live base fingerprint at observation time — what the claim was true OF. */
   fingerprint: string;
+  /**
+   * The FINGERPRINT_VERSION that hash was computed under.
+   *
+   * Stored beside the hash rather than only mixed into it, because a bare hash cannot say WHY
+   * it differs. Without this a baseline recorded under an older canonical form reads as drift,
+   * and an operator goes looking for a change nobody made instead of running one re-baseline.
+   * Absent on baselines written before v4.
+   */
+  fpVersion?: number;
   grantees: Record<string, BaselineGrantee>;
 }
 
@@ -71,7 +81,7 @@ export const EMPTY_BASELINE: AuthzBaseline = { version: 1, stages: {} };
 /** Fold the observed exemptions into one entry per grantee. */
 export function buildStageBaseline(
   exemptions: readonly GrantExemption[],
-  meta: { observedAt: string; fingerprint: string },
+  meta: { observedAt: string; fingerprint: string; fpVersion?: number },
 ): BaselineStage {
   const grantees: Record<string, BaselineGrantee> = {};
   for (const e of exemptions) {
@@ -83,7 +93,12 @@ export function buildStageBaseline(
     const all = [...e.privileges, ...Object.keys(e.columnPrivileges ?? {})];
     g.write ||= all.some((p) => WRITE_PRIVILEGES.has(p.toUpperCase()));
   }
-  return { observedAt: meta.observedAt, fingerprint: meta.fingerprint, grantees };
+  return {
+    observedAt: meta.observedAt,
+    fingerprint: meta.fingerprint,
+    fpVersion: meta.fpVersion ?? FINGERPRINT_VERSION,
+    grantees,
+  };
 }
 
 /** Write one stage's entry into the file, leaving every other stage untouched. */
@@ -105,7 +120,14 @@ export function renderBaseline(baseline: AuthzBaseline): string {
       const { privileges, tables, write } = s.grantees[g];
       grantees[g] = { privileges: [...privileges].sort(), tables: [...tables].sort(), write };
     }
-    stages[stage] = { observedAt: s.observedAt, fingerprint: s.fingerprint, grantees };
+    // `fpVersion` rides through the render, or the stamp is lost on the first rewrite and the
+    // baseline silently becomes unstamped — which reads as a format change forever after.
+    stages[stage] = {
+      observedAt: s.observedAt,
+      fingerprint: s.fingerprint,
+      ...(s.fpVersion != null ? { fpVersion: s.fpVersion } : {}),
+      grantees,
+    };
   }
   return JSON.stringify({ version: 1, stages }, null, 2) + '\n';
 }

package/src/cli/authz-canonical.ts

@@ -0,0 +1,146 @@
+/**
+ * authz-canonical — ONE definition of "these two authorization states are the same".
+ *
+ * Three surfaces answer that question and they must never answer it differently:
+ *
+ *   - `authz-reconcile`  — emits the SQL that closes the gap (statements == 0 means same)
+ *   - `authz-contract`   — reports drift (no findings means same)
+ *   - `schema-fingerprint` — content-addresses the state (equal hashes means same)
+ *
+ * They were two-and-a-half hand-mirrored copies, and that is exactly how the identity broke:
+ * the reconciler learned to exempt an ungoverned grantee, the fingerprint did not, and every
+ * brownfield adopter landed on "nothing to do" and "you have drifted" at the same time. The
+ * fingerprint is not a third opinion — it is this equivalence relation, cached. When the
+ * relation changes, the cache format changes with it.
+ *
+ * Two normalizations live here, and both are load-bearing:
+ *
+ * ROLE EXPANSION. A policy `TO a, b` and two identical-predicate policies `TO a` and `TO b`
+ * are applicable to precisely the same sessions, because Postgres selects policies per session
+ * role by membership. Expanding every policy to one entry per role makes those two states hash
+ * equal, which is what makes the reconciler's adoption of a role split legible to the gate.
+ *
+ * PUBLIC NEVER EXPANDS. It is an open set — every role that exists or ever will. Enumerating
+ * it at hash time against today's roles would rebuild, inside the fingerprint, exactly the
+ * contingent equivalence the matcher refuses: equal today, silently wrong the moment a role is
+ * created. It stays a single sentinel entry.
+ *
+ * MULTISET, NEVER A SET. Entries carry counts. If duplicates collapsed, two live policies with
+ * the same rule and different names would hash as one, the fingerprint would report MATCH, and
+ * the matcher — which adopts one and drops the other — would still emit statements. That is
+ * the same identity break in the opposite direction, and it is the harder one to notice.
+ */
+
+import type { PolicyContract, TableContract } from './authz-contract.js';
+import { effectivePolicyCheck } from './authz-contract.js';
+
+/** 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.
+ */
+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}`);
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+function stableRule(p: PolicyContract): string {
+  return JSON.stringify([
+    p.command,
+    p.permissive,
+    p.using ?? '',
+    effectivePolicyCheck(p) ?? '',
+  ]);
+}
+
+/** Sorted multiset: every entry kept, duplicates counted, order irrelevant. */
+function multiset(entries: string[]): Array<[string, number]> {
+  const counts = new Map<string, number>();
+  for (const e of entries) counts.set(e, (counts.get(e) ?? 0) + 1);
+  return [...counts.entries()].sort(([a], [b]) => (a < b ? -1 : 1));
+}
+
+/** The canonical policy form: every policy expanded across its roles, as a sorted multiset. */
+export function canonicalPolicies(policies: readonly PolicyContract[]): Array<[string, number]> {
+  return multiset(policies.flatMap(expandPolicy));
+}
+
+/**
+ * Keep only the grantees the models actually govern.
+ *
+ * The reconciler leaves an ungoverned grantee alone — a migrator, ETL or BI role the model
+ * vocabulary cannot name must not have its access destroyed by a plan nobody read. The hash
+ * has to make the same choice or it contradicts the plan: a live grant nothing will ever
+ * reconcile is not part of the state the models describe.
+ *
+ * `PUBLIC` compares case-insensitively (a pseudo-role with two catalog spellings); every other
+ * name compares exactly, because PostgreSQL role names are case-sensitive and `CREATE ROLE
+ * "Public"` is a real, distinct role.
+ */
+function governedOnly<T>(
+  map: Record<string, T> | undefined,
+  governed: ReadonlySet<string> | undefined,
+): Record<string, T> {
+  if (!map) return {};
+  if (!governed) return map;
+  return Object.fromEntries(
+    Object.entries(map).filter(([grantee]) =>
+      governed.has(grantee) || (grantee.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'))),
+  );
+}
+
+/**
+ * The canonical authorization form for one table.
+ *
+ * `governed` is the set the models declare. Pass it whenever hashing a LIVE contract, or the
+ * hash counts grants the reconciler will never touch and the state can never converge.
+ */
+export function canonicalAuthz(
+  contract: TableContract,
+  governed?: ReadonlySet<string>,
+): Record<string, unknown> {
+  const grants = governedOnly(contract.grants, governed);
+  const columnGrants = governedOnly(contract.columnGrants, governed);
+  return {
+    table: contract.table,
+    rls: { enabled: contract.rls.enabled, forced: contract.rls.forced },
+    grants: Object.fromEntries(
+      Object.entries(grants)
+        .map(([role, privs]) => [role, [...(privs as string[])].sort()] as const)
+        .sort(([a], [b]) => (a < b ? -1 : 1)),
+    ),
+    ...(Object.keys(columnGrants).length > 0
+      ? {
+          columnGrants: Object.fromEntries(
+            Object.entries(columnGrants)
+              .map(([role, byPriv]) => [
+                role,
+                Object.fromEntries(
+                  Object.entries(byPriv as Record<string, string[]>)
+                    .map(([priv, cols]) => [priv, [...cols].sort()] as const)
+                    .sort(([a], [b]) => (a < b ? -1 : 1)),
+                ),
+              ] as const)
+              .sort(([a], [b]) => (a < b ? -1 : 1)),
+          ),
+        }
+      : {}),
+    policies: canonicalPolicies(contract.policies),
+  };
+}

package/src/cli/authz-compile.ts

@@ -208,6 +208,31 @@ function isColumnRead(a: Ability): boolean {
   return a.action === 'read' && Boolean(a.condition.owner) && Boolean(a.condition.columns?.length);
 }
 
+/**
+ * `can(…, { role: 'public' })` names PostgreSQL's PUBLIC pseudo-role, and the two catalogs
+ * that describe it spell it differently — both correctly:
+ *
+ *   - `pg_policies.roles` renders it as the literal `{public}` (lowercase)
+ *   - `aclexplode()` yields grantee OID 0, which GRANTS_SQL renders as `'PUBLIC'`
+ *
+ * So the compiler speaks each catalog's spelling on its own axis. Saying `public` on both
+ * made the grant set-difference see `public` and `PUBLIC` as two grantees and emit a REVOKE
+ * and a GRANT that cancel out — on every run, converging never.
+ *
+ * The fold is COMPILE-TIME ONLY, applied to the author's declared role. Nothing folds at
+ * comparison time: `CREATE ROLE "Public"` is a legal, distinct role, and a case-insensitive
+ * compare against a live grantee would silently conflate it with the pseudo-role. (The cost
+ * of that choice: a real role named `Public` cannot be named by `role:`, because a model
+ * string carries no way to say "quoted identifier".)
+ */
+const isPseudoPublic = (role: string): boolean => role.toLowerCase() === 'public';
+
+/** The grant-side spelling of a declared role — what `aclexplode` would report. */
+const granteeKey = (role: string): string => (isPseudoPublic(role) ? 'PUBLIC' : role);
+
+/** The policy-side spelling of a declared role — what `pg_policies` would report. */
+const policyRole = (role: string): string => (isPseudoPublic(role) ? 'public' : role);
+
 /**
  * Column grants from the column-scoped read abilities: the read role (`authenticated`, since
  * the ability is owner-scoped, not role-gated) gets `SELECT (cols)`. Field keys are snake_cased
@@ -219,7 +244,7 @@ function compileColumnGrants(abilities: readonly Ability[]): Record<string, Reco
   const out: Record<string, Record<string, string[]>> = {};
   for (const a of abilities) {
     if (!isColumnRead(a)) continue;
-    const role = a.condition.role ?? 'authenticated';
+    const role = granteeKey(a.condition.role ?? 'authenticated');
     const cols = [...a.condition.columns!].map(toSnakeCase).sort();
     (out[role] ??= {}).SELECT = cols;
   }
@@ -436,7 +461,8 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   // discarded. That is the same failure `rawPredicate` throws over, one level up: a predicate
   // that evaporates is an authorization hole wearing the costume of a working rule.
   for (const a of abilities.filter(isRoleRead)) {
-    const role = a.condition.role!;
+    // The policy-side spelling, so `role: 'PUBLIC'` still matches what pg_policies reports.
+    const role = policyRole(a.condition.role!);
     const name = `${t}_select_${role}`;
     const where = `${table}: can('read', { role: '${role}' })`;
     if (policies.some((p) => p.name === name)) {
@@ -478,7 +504,7 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     // write on the owner connection and bypass RLS -> ENABLE-not-FORCE (on RDS the
     // owner is not a superuser, so a FORCEd table would block the owner's own writes).
     rls: { enabled: true, forced: model.writtenBy === 'app' },
-    grants: compileGrants(abilities),
+    grants: compileGrants(abilities, model.privileges),
     ...(compileColumnGrants(abilities) ? { columnGrants: compileColumnGrants(abilities) } : {}),
     policies,
   };
@@ -517,10 +543,19 @@ function verbsFor(action: Ability['action']): string[] {
  * table grants nothing, an owner-only table grants no anon SELECT, an admin-managed
  * table grants admin CRUD only. Deterministic: roles and privilege lists sorted,
  * so the output is byte-comparable with an introspected contract.
+ *
+ * `privileges` is the model's beyond-CRUD key — REFERENCES/TRIGGER/TRUNCATE, the table
+ * privileges `can()` has no verb for. They are UNIONED in, never subtracted: an admin that
+ * `can('manage')` and holds TRUNCATE keeps both. Without it, `manage` meant exactly CRUD and
+ * every live REFERENCES/TRIGGER/TRUNCATE read as drift, so the first plan against an existing
+ * schema revoked all three on every table — our spelling, not their schema.
  */
-function compileGrants(abilities: readonly Ability[]): Record<string, string[]> {
+function compileGrants(
+  abilities: readonly Ability[],
+  privileges: Record<string, readonly string[]> = {},
+): Record<string, string[]> {
   const grants: Record<string, Set<string>> = {};
-  const add = (role: string, verbs: string[]): void => {
+  const add = (role: string, verbs: readonly string[]): void => {
     const set = (grants[role] ??= new Set<string>());
     for (const v of verbs) set.add(v);
   };
@@ -531,13 +566,18 @@ function compileGrants(abilities: readonly Ability[]): Record<string, string[]>
     if (isColumnRead(a)) continue;
     const verbs = verbsFor(a.action);
     if (a.condition.role) {
-      add(a.condition.role, verbs);
+      add(granteeKey(a.condition.role), verbs);
     } else {
       add('authenticated', verbs);
       // A public read (no role, not owner/via-scoped) is anon-visible.
       if (a.action === 'read' && !a.condition.owner && !a.condition.via) add('anon', ['SELECT']);
     }
   }
+  // The role is spelled on the GRANT axis, so `privileges: { public: [...] }` reaches the
+  // same grantee `aclexplode` reports as `PUBLIC` — the fold the ability path already does.
+  for (const [role, privs] of Object.entries(privileges)) {
+    if (privs.length) add(granteeKey(role), privs);
+  }
   const out: Record<string, string[]> = {};
   for (const role of Object.keys(grants).sort()) out[role] = [...grants[role]].sort();
   return out;