@everystack/cli 0.4.40 → 0.4.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.40",
+  "version": "0.4.43",
   "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.6"
+    "@everystack/model": "0.4.8"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.4.0",

package/src/cli/apply-execute.ts

@@ -70,12 +70,20 @@ export interface ApplyPlanOptions {
    * attest their own --snapshot-ref keep the ceremony the command shell enforces).
    */
   verifySnapshot?: (ctx: { planFrom: string }) => Promise<{ ok: true } | { ok: false; reason: string }>;
+  /**
+   * The ungoverned-grantee gate, re-verified AT APPLY (B4). db:plan already refuses to mint
+   * against a stage holding a foreign grantee the baseline does not record — but a plan is
+   * an artifact with a lifetime, and a role minted between minting and applying would
+   * otherwise ride through unnoticed. Same contract as the other gates: refusal recorded in
+   * schema_log. Omitted = no gate (callers with no baseline to check against).
+   */
+  verifyAuthzBaseline?: (ctx: { contract: AuthzContract }) => Promise<{ ok: true } | { ok: false; reason: string }>;
   /** Injectable clock for tests. */
   now?: () => number;
 }
 
 export interface ApplyPlanResult {
-  status: 'applied' | 'already-applied' | 'refused' | 'descent-refused' | 'authority-refused' | 'snapshot-refused' | 'verify-failed';
+  status: 'applied' | 'already-applied' | 'refused' | 'descent-refused' | 'authority-refused' | 'snapshot-refused' | 'authz-refused' | 'verify-failed';
   liveFingerprint: string;
   reason?: string;
   logId?: number;
@@ -157,6 +165,17 @@ export async function executeApplyPlan(
     }
   }
 
+  // Before ANY write: a foreign grantee that arrived after the plan was minted must stop
+  // the apply, not ride through it. The plan's own gates check the SCHEMA has not moved;
+  // this checks who can reach it.
+  if (options.verifyAuthzBaseline) {
+    const authz = await options.verifyAuthzBaseline({ contract: beforeAuthz });
+    if (!authz.ok) {
+      await recordRefusal(runner, plan, live, 'ungoverned grantee', authz.reason, options);
+      return { status: 'authz-refused', liveFingerprint: live, reason: authz.reason };
+    }
+  }
+
   if (plan.destructive > 0 && options.verifyAuthority) {
     const authority = await options.verifyAuthority();
     if (!authority.ok) {

package/src/cli/authz-baseline.ts

@@ -0,0 +1,227 @@
+/**
+ * authz-baseline — the foreign grantees that were already there, and the gate that makes a
+ * NEW one fail.
+ *
+ * The reconciler exempts a grantee the models do not govern rather than revoking it
+ * (authz-reconcile's `governedRoleSet` — a migrator or BI role must not have its access
+ * destroyed by a plan nobody read). That exemption is only half a design. Without the other
+ * half, an attacker-minted role holding SELECT on every table is reported forever and fails
+ * nothing, which is the failure mode the exemption was rejected for in the first place.
+ *
+ * So: record the foreign grantees present AT ADOPTION, per stage. After that, an ungoverned
+ * grantee that is not in the stage's baseline — or a baselined one that has GROWN — refuses
+ * the plan. A greenfield app's baseline is empty, so any foreign grantee is a failure from
+ * day one; a brownfield app's migrator is in it, so adoption proceeds with a warning that
+ * never goes away.
+ *
+ * Two deliberate decisions, both adjudicated:
+ *
+ *   - The baseline lives in the REPO, not the database. Storing it in the database looks
+ *     tamper-evident and is not: the attacker who minted the role owns the database and can
+ *     write the baseline row in the same session. More importantly it would hide the
+ *     exemption from the one human checkpoint that exists — a pull request. Adding a
+ *     grantee is a diff line someone merges. The database keeps a `schema_log` memoir of
+ *     the adoption event so a reviewer can check the claim against the observation.
+ *   - It is FROZEN at adoption. There is no "it showed up in production, baseline it"
+ *     path — that is the whole gate. Admitting a new role costs a PR line, on purpose.
+ *
+ * Per-stage, because stages legitimately differ (a BI role in production and nowhere else) —
+ * and scoped, so a production entry excuses that grantee in production only. The same role
+ * appearing in dev still fails there.
+ *
+ * Pure, with one exception named at the bottom: `readBaselineFile`, which every gate needs
+ * to agree on (including "the file is absent", which must behave exactly like an empty
+ * baseline rather than like a skipped check).
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { GrantExemption } from './authz-reconcile.js';
+
+/** The repo-relative artifact. Generated — regenerating it must reproduce it byte for byte. */
+export const BASELINE_FILE = 'db/authz-baseline.json';
+
+/** Privileges that change data or structure — flagged loudly, because a reviewer skims. */
+const WRITE_PRIVILEGES = new Set(['INSERT', 'UPDATE', 'DELETE', 'TRUNCATE', 'REFERENCES', 'TRIGGER']);
+
+export interface BaselineGrantee {
+  /** The union of table-level privileges held at adoption, sorted. */
+  privileges: string[];
+  /** The tables it held them on, sorted. */
+  tables: string[];
+  /** True when any privilege writes. Surfaced so a reviewer sees it without reading the list. */
+  write: boolean;
+}
+
+export interface BaselineStage {
+  /** When the observation was taken — provenance for the claim, not used by the gate. */
+  observedAt: string;
+  /** The live base fingerprint at observation time — what the claim was true OF. */
+  fingerprint: string;
+  grantees: Record<string, BaselineGrantee>;
+}
+
+export interface AuthzBaseline {
+  version: 1;
+  stages: Record<string, BaselineStage>;
+}
+
+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 },
+): BaselineStage {
+  const grantees: Record<string, BaselineGrantee> = {};
+  for (const e of exemptions) {
+    const g = (grantees[e.grantee] ??= { privileges: [], tables: [], write: false });
+    g.privileges = [...new Set([...g.privileges, ...e.privileges])].sort();
+    g.tables = [...new Set([...g.tables, e.table])].sort();
+    // A column-scoped privilege is still that privilege — it must count toward `write`,
+    // or a column-scoped UPDATE would read as a harmless reader in review.
+    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 };
+}
+
+/** Write one stage's entry into the file, leaving every other stage untouched. */
+export function mergeBaseline(existing: AuthzBaseline | null, stage: string, entry: BaselineStage): AuthzBaseline {
+  return { version: 1, stages: { ...(existing?.stages ?? {}), [stage]: entry } };
+}
+
+/**
+ * The artifact's canonical text. Keys sorted at every level so regenerating an unchanged
+ * baseline is byte-identical — that equality IS the offline check, and a diff that reorders
+ * itself would make the review signal worthless.
+ */
+export function renderBaseline(baseline: AuthzBaseline): string {
+  const stages: Record<string, BaselineStage> = {};
+  for (const stage of Object.keys(baseline.stages).sort()) {
+    const s = baseline.stages[stage];
+    const grantees: Record<string, BaselineGrantee> = {};
+    for (const g of Object.keys(s.grantees).sort()) {
+      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 };
+  }
+  return JSON.stringify({ version: 1, stages }, null, 2) + '\n';
+}
+
+/** Parse the artifact, refusing anything malformed by name — a baseline that silently reads
+ *  as empty would disable the gate, which is the one outcome worse than failing. */
+export function parseBaseline(text: string, where = BASELINE_FILE): AuthzBaseline {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err: any) {
+    throw new Error(`${where} is not valid JSON: ${err.message}`);
+  }
+  const b = raw as Partial<AuthzBaseline>;
+  if (b?.version !== 1) throw new Error(`${where}: unsupported version ${String(b?.version)} — expected 1.`);
+  if (b.stages == null || typeof b.stages !== 'object') throw new Error(`${where}: missing a "stages" object.`);
+  for (const [stage, s] of Object.entries(b.stages)) {
+    if (s?.grantees == null || typeof s.grantees !== 'object') {
+      throw new Error(`${where}: stage "${stage}" has no "grantees" object.`);
+    }
+  }
+  return b as AuthzBaseline;
+}
+
+/** One reason a live grantee fails the gate. */
+export interface BaselineViolation {
+  grantee: string;
+  kind: 'unbaselined' | 'widened';
+  detail: string;
+}
+
+/**
+ * The gate. A stage passes when every ungoverned grantee is in its baseline AND holds
+ * nothing beyond what the baseline recorded.
+ *
+ * `widened` matters as much as `unbaselined`: a role baselined with SELECT that has since
+ * acquired UPDATE, or spread to new tables, is not the role that was reviewed. Freezing the
+ * NAME while letting the privileges grow would leave the gate defending nothing.
+ *
+ * An ABSENT stage entry is not an empty one — it means the stage was never adopted, and any
+ * foreign grantee there fails. That is deliberate: the safe reading of "no record" is "not
+ * reviewed", never "nothing to see".
+ */
+export function checkAgainstBaseline(
+  baseline: AuthzBaseline | null,
+  stage: string,
+  exemptions: readonly GrantExemption[],
+): BaselineViolation[] {
+  const observed = buildStageBaseline(exemptions, { observedAt: '', fingerprint: '' }).grantees;
+  const recorded = baseline?.stages[stage]?.grantees ?? {};
+  const violations: BaselineViolation[] = [];
+
+  for (const grantee of Object.keys(observed).sort()) {
+    const now = observed[grantee];
+    const then = recorded[grantee];
+    if (!then) {
+      violations.push({
+        grantee,
+        kind: 'unbaselined',
+        detail: `holds ${now.privileges.join(', ') || 'column-scoped privileges'} on ${now.tables.length} table(s) and is not in the ${stage} baseline`,
+      });
+      continue;
+    }
+    const newPrivileges = now.privileges.filter((p) => !then.privileges.includes(p));
+    const newTables = now.tables.filter((t) => !then.tables.includes(t));
+    if (newPrivileges.length > 0 || newTables.length > 0) {
+      violations.push({
+        grantee,
+        kind: 'widened',
+        detail: [
+          newPrivileges.length ? `gained ${newPrivileges.join(', ')}` : null,
+          newTables.length ? `spread to ${newTables.join(', ')}` : null,
+        ].filter(Boolean).join('; ') + ` since the ${stage} baseline`,
+      });
+    }
+  }
+  return violations;
+}
+
+/** The refusal an operator reads. Names every violation — a count would not be actionable. */
+export function baselineRefusal(stage: string, violations: readonly BaselineViolation[]): string {
+  const lines = violations.map((v) => `  - ${v.grantee} ${v.detail}`);
+  return [
+    `${violations.length} role(s) hold privileges on ${stage} that the models do not govern and the baseline does not record:`,
+    ...lines,
+    '',
+    `A role the models cannot name is left alone by the reconciler, so it must be reviewed instead of reconciled.`,
+    `If these are legitimate, add them deliberately: re-run \`db:pull --abilities live --stage ${stage}\` to regenerate ${BASELINE_FILE},`,
+    `review the diff (write privileges are flagged), and commit it. If they are NOT legitimate, revoke them in the database first.`,
+  ].join('\n');
+}
+
+/**
+ * Read the baseline artifact, or null when there is none.
+ *
+ * ABSENT is not an error and not a skip — it is an EMPTY baseline, so every foreign grantee
+ * fails the gate. That is the greenfield default and it is the safe direction: a project
+ * that never adopted a baseline has never reviewed a foreign role. A file that exists but
+ * cannot be parsed THROWS (see parseBaseline) — silently continuing past a corrupt baseline
+ * would disable the gate exactly when someone has been editing it.
+ */
+export async function readBaselineFile(cwd = process.cwd()): Promise<AuthzBaseline | null> {
+  const file = path.resolve(cwd, BASELINE_FILE);
+  let text: string;
+  try {
+    text = await fs.readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+  return parseBaseline(text, BASELINE_FILE);
+}
+
+/** Write the artifact, creating `db/` if this is the first adoption. */
+export async function writeBaselineFile(baseline: AuthzBaseline, cwd = process.cwd()): Promise<string> {
+  const file = path.resolve(cwd, BASELINE_FILE);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, renderBaseline(baseline), 'utf8');
+  return file;
+}

package/src/cli/authz-compile.ts

@@ -22,6 +22,7 @@
 
 import type { ModelDescriptor, Ability } from '@everystack/model';
 import type { PolicyContract, TableContract, PolicyCommand } from './authz-contract.js';
+import { parenthesizeOnce } from './authz-contract.js';
 
 export interface CompileOptions {
   /** Schema the table lives in. Default: `public`. */
@@ -176,9 +177,17 @@ function resolveVia(model: ModelDescriptor): ViaRef | null {
   };
 }
 
-/** The conventional soft-delete column SQL name, when the model has one. */
+/**
+ * The soft-delete column SQL name, when the model DECLARES one.
+ *
+ * Keyed on `softDelete`, never on the field's presence. A column named `deleted_at` is not a
+ * statement of visibility intent, and inferring the guard from it made the compiler author a
+ * security predicate nobody wrote — one that `db:pull` then handed to every brownfield model
+ * automatically, so the first plan narrowed a policy the adopter had written. `defineModel`
+ * refuses to guess: a model with the field and a public read must say which it means.
+ */
 function softDeleteColumn(model: ModelDescriptor): string | null {
-  return 'deletedAt' in model.fields ? 'deleted_at' : null;
+  return model.softDelete ? 'deleted_at' : null;
 }
 
 /**
@@ -228,7 +237,11 @@ function rawPredicate(value: unknown, where: string): string | null {
       `${where}: expected a sql\`…\` fragment (import { sql } from '@everystack/model'), got ${typeof value}. A bare string is rejected on purpose — an RLS predicate is authored, never stringly assembled.`,
     );
   }
-  return `(${text.trim()})`;
+  // Parenthesized exactly once. A pulled predicate arrives already fully parenthesized
+  // (that is how pg_get_expr deparses it), and wrapping it again made the compiled policy
+  // differ from the live one by a single layer of parens — enough for the reconciler to
+  // plan a DROP + CREATE that changed nothing.
+  return parenthesizeOnce(text.trim());
 }
 
 /** AND-compose predicates, dropping the vacuous ones. A condition only ever NARROWS. */
@@ -266,11 +279,20 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   // A "row-scoped" condition is either a direct owner or a transitive via.
   const rowScoped = (a: Ability): boolean => Boolean(a.condition.owner || a.condition.via);
 
+  /**
+   * A read scoped to a named role — `can('read', { role })`. It compiles to its own
+   * `<table>_select_<role>` policy, so its predicate must NOT also be folded into the
+   * public read's predicate: a rule written for one role would otherwise narrow what
+   * every other role can see.
+   */
+  const isRoleRead = (a: Ability): boolean =>
+    a.action === 'read' && Boolean(a.condition.role) && !isColumnRead(a);
+
   // Author-supplied predicates, per action. `manage` carries no predicate of its own —
   // it is the admin bypass — so only the specific verbs are consulted.
   const predFor = (action: Ability['action']): string | null => {
     for (const a of model.abilities) {
-      if (a.action !== action) continue;
+      if (a.action !== action || isRoleRead(a)) continue;
       const p = rawPredicate(a.condition.sql ?? a.condition.where, `${table}: can('${action}')`);
       if (p) return p;
     }
@@ -336,6 +358,26 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     policy(`${t}_select_self`, 'SELECT', ['authenticated'], rowPred, null);
   }
 
+  // Role-scoped reads — `can('read', { role })`, with or without a predicate. These match
+  // none of the branches above: the public read requires NO role, and the owner/column reads
+  // require a row-scoping condition. Before this they compiled to a SELECT grant and no
+  // policy at all — and since `rls.enabled` is unconditional, the role saw ZERO rows while
+  // the model read as though it could see its own. The declared predicate was computed and
+  // 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!;
+    const name = `${t}_select_${role}`;
+    const where = `${table}: can('read', { role: '${role}' })`;
+    if (policies.some((p) => p.name === name)) {
+      throw new Error(
+        `${where} collides with the ${name} policy already compiled from this model's public read. `
+        + `Declare one or the other: permissive policies OR together, so the role-scoped rule could only ever widen — never the narrowing it reads as.`,
+      );
+    }
+    policy(name, 'SELECT', [role], rawPredicate(a.condition.sql ?? a.condition.where, where) ?? 'true', null);
+  }
+
   // owner-gated writes. INSERT checks ownership (you can only create rows you own);
   // UPDATE gates + checks; DELETE gates. `rowPred` is the direct-owner or `via:` predicate.
   //

package/src/cli/authz-contract.ts

@@ -82,6 +82,51 @@ export interface PolicyContract {
   check: string | null;
 }
 
+/**
+ * The WITH CHECK expression PostgreSQL will actually enforce.
+ *
+ * For `ALL` and `UPDATE`, an omitted `WITH CHECK` is not "no check" — the server reuses the
+ * `USING` expression. So a live `FOR ALL USING (true)` (which is what `CREATE POLICY … USING
+ * (true)` records, with `pg_policies.with_check` NULL) and a compiled `FOR ALL USING (true)
+ * WITH CHECK (true)` are the SAME authorization. Comparing the raw fields calls them
+ * different and plans a DROP + CREATE — the loudest possible way to say "no change", and it
+ * defeats a zero-statement bar even when the SQL is identical.
+ *
+ * `INSERT` has only a check, `SELECT`/`DELETE` have none — for those the field stands alone
+ * and no defaulting applies.
+ */
+export function effectivePolicyCheck(p: PolicyContract): string | null {
+  if (p.command === 'ALL' || p.command === 'UPDATE') return p.check ?? p.using;
+  return p.check;
+}
+
+/** 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;
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === '(') depth++;
+    else if (s[i] === ')') {
+      depth--;
+      if (depth === 0 && i < s.length - 1) return false;
+    }
+  }
+  return depth === 0;
+}
+
+/**
+ * A predicate parenthesized exactly once — the normal form both producers must agree on.
+ *
+ * `pg_get_expr` already deparses a policy predicate fully parenthesized, so `db:pull` renders
+ * one into a model verbatim. Wrapping it again produced a compiled predicate identical to
+ * live but for one layer of parens, which the equality check called a difference and turned
+ * into a same-name DROP + CREATE that changed nothing. Emission already knew this rule; the
+ * comparison did not, so both go through this.
+ */
+export function parenthesizeOnce(expr: string): string {
+  return isWrappedExpression(expr) ? expr : `(${expr})`;
+}
+
 /**
  * One function, enumerated. The cross-table authorization that RLS does not hold lives
  * in SECURITY DEFINER functions as imperative gates; the contract records that they
@@ -581,7 +626,9 @@ function diffPolicies(table: string, d: TableContract, l: TableContract, out: Dr
     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`);
-    if ((dp.check ?? '') !== (lp.check ?? '')) changes.push(`WITH CHECK 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(', ')}` });
     }

package/src/cli/authz-reconcile.ts

@@ -16,27 +16,110 @@
  */
 
 import type { AuthzContract, TableContract, PolicyContract } from './authz-contract.js';
+import { effectivePolicyCheck, parenthesizeOnce } from './authz-contract.js';
 import { quoteQualified } from './pg-ident.js';
 
-/** True when `s`'s outer parens already wrap the whole expression (redundant to add more). */
-function isWrapped(s: string): boolean {
-  if (!s.startsWith('(') || !s.endsWith(')')) return false;
-  let depth = 0;
-  for (let i = 0; i < s.length; i++) {
-    if (s[i] === '(') depth++;
-    else if (s[i] === ')') {
-      depth--;
-      if (depth === 0 && i < s.length - 1) return false;
+/**
+ * Always governed, whatever the models say. `PUBLIC` because a grant to PUBLIC is the
+ * broadest privilege the database can express and must never be exemptible; the three
+ * vocabulary roles because they ARE the model's authz surface — letting a module drop one
+ * would be a way to hide a grant from the thing that audits it.
+ */
+export const ALWAYS_GOVERNED = ['PUBLIC', 'admin', 'anon', 'authenticated'] as const;
+
+/** One grantee the declared contract does not govern, with what it actually holds. */
+export interface GrantExemption {
+  grantee: string;
+  table: string;
+  /** Table-level privileges. */
+  privileges: string[];
+  /** Column-scoped privileges, `privilege → columns`. Present only when there are any. */
+  columnPrivileges?: Record<string, string[]>;
+}
+
+/**
+ * The roles the declared authz governs: everything the models name, plus the always-governed
+ * set, plus whatever the modules widen it with. WIDEN-ONLY by construction — `declared` and
+ * {@link ALWAYS_GOVERNED} go in unconditionally, so `extra` can add and can never subtract.
+ *
+ * Grantee comparison is case-insensitive on `PUBLIC` only (PostgreSQL's pseudo-role, which
+ * the catalog reports uppercase and the models spell either way); real role names are
+ * case-sensitive because PostgreSQL's are.
+ */
+export function governedRoleSet(declared: AuthzContract, extra: readonly string[] = []): Set<string> {
+  const governed = new Set<string>(ALWAYS_GOVERNED);
+  for (const t of declared.tables) {
+    for (const grantee of Object.keys(t.grants)) governed.add(grantee);
+    for (const grantee of Object.keys(t.columnGrants ?? {})) governed.add(grantee);
+  }
+  for (const role of extra) governed.add(role);
+  return governed;
+}
+
+const isGoverned = (governed: ReadonlySet<string>, grantee: string): boolean =>
+  governed.has(grantee) || (grantee.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'));
+
+/**
+ * Every live grantee the declared contract does not govern, with its exact privileges —
+ * the enumeration that makes exempting them acceptable at all.
+ *
+ * The reconciler leaves these alone (a live migrator/ETL/BI role the model vocabulary
+ * cannot name must not have its access destroyed by a plan nobody read). That is only
+ * defensible because every artifact claiming to describe authz state reprints this list:
+ * exempt from reconciliation, never exempt from the report. Returns `grantee → table →
+ * privileges`, sorted, because a COUNT is not auditable.
+ */
+export function ungovernedGrants(live: AuthzContract, governed: ReadonlySet<string>): GrantExemption[] {
+  const out: GrantExemption[] = [];
+  for (const t of live.tables) {
+    const grantees = new Set([...Object.keys(t.grants), ...Object.keys(t.columnGrants ?? {})]);
+    for (const grantee of [...grantees].sort()) {
+      if (isGoverned(governed, grantee)) continue;
+      const columnPrivileges = t.columnGrants?.[grantee];
+      out.push({
+        grantee,
+        table: t.table,
+        privileges: [...(t.grants[grantee] ?? [])].sort(),
+        ...(columnPrivileges && Object.keys(columnPrivileges).length > 0 ? { columnPrivileges } : {}),
+      });
     }
   }
-  return depth === 0;
+  return out.sort((a, b) => a.grantee.localeCompare(b.grantee) || a.table.localeCompare(b.table));
 }
 
-/** A USING/WITH CHECK clause expression, parenthesized exactly once. */
-function clause(expr: string): string {
-  return isWrapped(expr) ? expr : `(${expr})`;
+/**
+ * The exemption report, one line per grantee — the shared rendering every surface prints.
+ *
+ * Grouped by grantee (an operator asks "what does this role have?", not "what does this
+ * table give?") and always EXACT: role, privileges, and the tables. `3 ungoverned roles`
+ * would not be auditable, which is the whole reason the exemption is allowed to exist.
+ */
+export function renderGrantExemptions(exemptions: readonly GrantExemption[]): string[] {
+  const byGrantee = new Map<string, GrantExemption[]>();
+  for (const e of exemptions) byGrantee.set(e.grantee, [...(byGrantee.get(e.grantee) ?? []), e]);
+
+  const lines: string[] = [];
+  for (const [grantee, entries] of [...byGrantee.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    // The privilege set is usually uniform across the tables; say it once and list the
+    // tables, and only fall back to per-table lines when it genuinely differs.
+    const shapes = new Set(entries.map((e) => e.privileges.join(',')));
+    if (shapes.size === 1 && entries.length > 1) {
+      lines.push(`${grantee}: ${entries[0].privileges.join(', ')} on ${entries.length} table(s) — ${entries.map((e) => e.table).sort().join(', ')}`);
+    } else {
+      for (const e of entries.sort((a, b) => a.table.localeCompare(b.table))) {
+        const cols = e.columnPrivileges
+          ? `; column-scoped ${Object.entries(e.columnPrivileges).map(([p, c]) => `${p} (${c.join(', ')})`).join(', ')}`
+          : '';
+        lines.push(`${grantee}: ${e.privileges.join(', ') || 'no table-level privileges'} on ${e.table}${cols}`);
+      }
+    }
+  }
+  return lines;
 }
 
+/** A USING/WITH CHECK clause expression, parenthesized exactly once. */
+const clause = parenthesizeOnce;
+
 /** A CREATE POLICY statement from a policy descriptor. */
 function policyCreateSql(table: string, p: PolicyContract): string {
   const parts = [`CREATE POLICY ${p.name} ON ${table}`];
@@ -52,13 +135,19 @@ function policyDropSql(table: string, name: string): string {
   return `DROP POLICY IF EXISTS ${name} ON ${table};`;
 }
 
-/** Two policies are the same authorization when every diffed field matches. */
+/**
+ * Two policies are the same authorization when every diffed field matches. The check is
+ * compared through {@link effectivePolicyCheck}, i.e. the server's own defaulting rule —
+ * a live `FOR ALL USING (true)` and a compiled `FOR ALL USING (true) WITH CHECK (true)`
+ * authorize identically, and reconciling them would emit a DROP + CREATE that changes
+ * nothing.
+ */
 function policiesEqual(a: PolicyContract, b: PolicyContract): boolean {
   return a.command === b.command
     && a.permissive === b.permissive
     && a.roles.join(',') === b.roles.join(',')
     && (a.using ?? '') === (b.using ?? '')
-    && (a.check ?? '') === (b.check ?? '');
+    && (effectivePolicyCheck(a) ?? '') === (effectivePolicyCheck(b) ?? '');
 }
 
 function tableMap(c: AuthzContract): Map<string, TableContract> {
@@ -72,9 +161,17 @@ function tableMap(c: AuthzContract): Map<string, TableContract> {
  * revoke/grant — so a replaced policy never briefly co-exists with its old form
  * and policies exist before grants reference the table.
  */
-export function emitReconcileSql(declared: AuthzContract, live: AuthzContract): string[] {
+export function emitReconcileSql(
+  declared: AuthzContract,
+  live: AuthzContract,
+  opts: { governedRoles?: ReadonlySet<string> } = {},
+): string[] {
   const sql: string[] = [];
   const lTables = tableMap(live);
+  // Default: govern exactly what the models name (plus the always-governed set). A caller
+  // that passes nothing gets the safe-for-greenfield behaviour; a brownfield caller widens
+  // it with the modules' declared governedRoles.
+  const governed = opts.governedRoles ?? governedRoleSet(declared);
 
   for (const d of declared.tables) {
     const l = lTables.get(d.table);
@@ -83,8 +180,8 @@ export function emitReconcileSql(declared: AuthzContract, live: AuthzContract):
     const table = quoteQualified(d.table);
     reconcileRls(table, d, l, sql);
     reconcilePolicies(table, d, l, sql);
-    reconcileGrants(table, d, l, sql);
-    reconcileColumnGrants(table, d, l, sql);
+    reconcileGrants(table, d, l, sql, governed);
+    reconcileColumnGrants(table, d, l, sql, governed);
   }
 
   return sql;
@@ -108,6 +205,7 @@ export function emitReconcileSql(declared: AuthzContract, live: AuthzContract):
  */
 export function emitSwapAuthzSql(declared: AuthzContract): string[] {
   const sql: string[] = [];
+  const governed = governedRoleSet(declared);
   for (const d of declared.tables) {
     const table = quoteQualified(d.table);
     if (d.rls.enabled) sql.push(`ALTER TABLE ${table} ENABLE ROW LEVEL SECURITY;`);
@@ -116,8 +214,10 @@ export function emitSwapAuthzSql(declared: AuthzContract): string[] {
       sql.push(policyDropSql(table, p.name)); // idempotent against the policy the dump restored
       sql.push(policyCreateSql(table, p));
     }
-    reconcileGrants(table, d, undefined, sql);
-    reconcileColumnGrants(table, d, undefined, sql);
+    // No live side here, so every grantee comes from the DECLARED contract and is
+    // governed by definition — the exemption can never fire on this path.
+    reconcileGrants(table, d, undefined, sql, governed);
+    reconcileColumnGrants(table, d, undefined, sql, governed);
   }
   return sql;
 }
@@ -145,9 +245,15 @@ function reconcilePolicies(table: string, d: TableContract, l: TableContract | u
   }
 }
 
-function reconcileGrants(table: string, d: TableContract, l: TableContract | undefined, out: string[]): void {
+function reconcileGrants(table: string, d: TableContract, l: TableContract | undefined, out: string[], governed: ReadonlySet<string>): void {
   const grantees = new Set([...Object.keys(d.grants), ...Object.keys(l?.grants ?? {})]);
   for (const grantee of [...grantees].sort()) {
+    // A live grantee the declared authz does not govern is LEFT ALONE. The union below
+    // would otherwise revoke every privilege it holds, because "no declaration" and "no
+    // privileges" are the same thing to a set difference — which is how a plan came to
+    // carry 32 revokes against a brownfield adopter's migration role. It is reported
+    // instead, by ungovernedGrants(), on every surface that describes authz state.
+    if (!isGoverned(governed, grantee)) continue;
     const declared = new Set(d.grants[grantee] ?? []);
     const live = new Set(l?.grants?.[grantee] ?? []);
     const target = grantee.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : grantee;
@@ -165,10 +271,13 @@ function reconcileGrants(table: string, d: TableContract, l: TableContract | und
  * those live-but-not-declared. This is how `auth.users` exposes id/email/role (and only those)
  * to `authenticated` without a whole-table grant. Columns are sorted, so a re-pull is a no-op.
  */
-function reconcileColumnGrants(table: string, d: TableContract, l: TableContract | undefined, out: string[]): void {
+function reconcileColumnGrants(table: string, d: TableContract, l: TableContract | undefined, out: string[], governed: ReadonlySet<string>): void {
   const dcg = d.columnGrants ?? {};
   const lcg = l?.columnGrants ?? {};
   for (const grantee of [...new Set([...Object.keys(dcg), ...Object.keys(lcg)])].sort()) {
+    // Same exemption as the table-level grants — a column grant to an ungoverned role is
+    // still that role's access, and revoking it breaks the same pipeline.
+    if (!isGoverned(governed, grantee)) continue;
     const target = grantee.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : grantee;
     const dPriv = dcg[grantee] ?? {};
     const lPriv = lcg[grantee] ?? {};