@everystack/cli 0.4.51 → 0.4.53

package/package.json

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

package/src/cli/authz-compile.ts

@@ -23,6 +23,7 @@
 import { isColumnAbility, type ModelDescriptor, type Ability } from '@everystack/model';
 import type { PolicyContract, TableContract, PolicyCommand } from './authz-contract.js';
 import { parenthesizeOnce } from './authz-contract.js';
+import { normalizeDeparsedExpr } from './deparse-normal.js';
 
 export interface CompileOptions {
   /** Schema the table lives in. Default: `public`. */
@@ -400,7 +401,14 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     name: string, command: PolicyCommand, roles: string[],
     using: string | null, check: string | null,
   ): void => {
-    policies.push({ name, command, roles, permissive: true, using, check });
+    // Same normalization the live producer applies (authz-contract's `predicate`): a model
+    // pulled on one PostgreSQL major carries that major's deparse spelling in its predicates,
+    // and it must compare equal against a stage on another. One rule table, two producers.
+    policies.push({
+      name, command, roles, permissive: true,
+      using: using == null ? null : normalizeDeparsedExpr(using),
+      check: check == null ? null : normalizeDeparsedExpr(check),
+    });
   };
 
   // admin-bypass — one ALL policy, true/true.
@@ -555,7 +563,12 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     // policies. 'app' writes through its policies -> FORCE; 'worker'/'functions'
     // 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' },
+    // `rls: false` (grants-only table) declares the flag OFF — defineModel guarantees
+    // zero abilities and a non-'app' principal there. Compared against `false`, not
+    // truthiness: a descriptor minted by an older @everystack/model carries no `rls`
+    // key, and undefined must mean ENABLED — the pre-flag behavior — never a silent
+    // security downgrade via version skew.
+    rls: { enabled: model.rls !== false, forced: model.rls !== false && model.writtenBy === 'app' },
     grants: compileGrants(abilities, model.privileges),
     ...(compileColumnGrants(abilities) ? { columnGrants: compileColumnGrants(abilities) } : {}),
     policies,

package/src/cli/authz-contract.ts

@@ -24,6 +24,7 @@
 import { parsePgArray } from './security-catalog.js';
 import { INTROSPECTION_SESSION, type SessionRunner } from './session.js';
 import { matchPolicies, roleSetEqual } from './authz-identity.js';
+import { normalizeDeparsedExpr } from './deparse-normal.js';
 
 // ---------------------------------------------------------------------------
 // The contract format — the frozen, reviewable, version-controlled shape.
@@ -270,6 +271,15 @@ export interface FunctionContract {
 export interface AuthzContract {
   tables: TableContract[];
   functions: FunctionContract[];
+  /**
+   * Schema-level ACLs (pg_namespace.nspacl), schema → grantee → sorted privileges
+   * (USAGE | CREATE). `PUBLIC` is the pseudo-role entry. A schema with a NULL acl is
+   * ABSENT — owner-default, no explicit grants — so absence means "the grant does not
+   * exist" and an emitter may emit it. Optional: contracts assembled from older recorders
+   * or hand-built fixtures simply carry no schema knowledge, and consumers must treat
+   * that as "unknown", never as "no grants".
+   */
+  schemaAcls?: Record<string, Record<string, string[]>>;
 }
 
 export type PolicyCommand = 'ALL' | 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE';
@@ -398,6 +408,82 @@ WHERE c.relkind = 'r'
 ORDER BY n.nspname, c.relname;
 `.trim();
 
+/**
+ * Schema ACLs, for the emitters that grant schema USAGE. The consumer bug this closes: the
+ * usage phase emitted `GRANT USAGE ON SCHEMA` with no live read at all, so every plan with
+ * any authz statement re-granted what the database already held — two false statements on
+ * every stage plan, forever. `nspacl` casts to its array-literal text; NULL stays NULL
+ * (owner default — no explicit grants — which the parser must NOT read as an empty grant
+ * list on purpose: for nspacl the two mean the same emittable thing, but the distinction
+ * is kept so the contract says what the catalog said).
+ */
+export const SCHEMA_ACL_SQL = `
+SELECT n.nspname AS schema, n.nspacl::text AS acl
+FROM pg_namespace n
+WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+ORDER BY n.nspname;
+`.trim();
+
+export interface SchemaAclRow {
+  schema: string;
+  acl: unknown;
+}
+
+/** The two privileges a schema ACL can carry, in aclitem letter form. */
+const SCHEMA_PRIV_LETTERS: Record<string, string> = { U: 'USAGE', C: 'CREATE' };
+
+/**
+ * Parse one `aclitem[]::text` literal — `{postgres=UC/postgres,authenticator=U/postgres}` —
+ * into grantee → privileges. An empty grantee (`=U/postgres`) is PUBLIC. A quoted grantee
+ * (`"odd,role"=U/postgres`) is unwrapped with its doubled-quote escapes. A `*` (grant
+ * option) rides the letter before it and is dropped — holding WITH GRANT OPTION still
+ * holds the privilege. Unparseable input returns null: the caller treats it as unknown,
+ * never as "no grants".
+ */
+export function parseSchemaAcl(text: string | null | undefined): Record<string, string[]> | null {
+  if (text == null) return null;
+  const s = String(text).trim();
+  if (!s.startsWith('{') || !s.endsWith('}')) return null;
+  const body = s.slice(1, -1);
+  if (body.trim() === '') return {};
+  const out: Record<string, string[]> = {};
+  // Split items at top-level commas — a quoted region may contain commas.
+  const items: string[] = [];
+  let start = 0;
+  for (let j = 0; j < body.length; j++) {
+    if (body[j] === '"') {
+      for (j++; j < body.length; j++) {
+        if (body[j] !== '"') continue;
+        if (body[j + 1] === '"') { j++; continue; }
+        break;
+      }
+    } else if (body[j] === ',') {
+      items.push(body.slice(start, j));
+      start = j + 1;
+    }
+  }
+  items.push(body.slice(start));
+  for (const item of items) {
+    // grantee=letters/grantor — grantee may be quoted; the grantor half is irrelevant here.
+    const eq = item.indexOf('=', item.startsWith('"') ? item.indexOf('"', 1) + 1 : 0);
+    if (eq === -1) return null;
+    let grantee = item.slice(0, eq);
+    if (grantee.startsWith('"') && grantee.endsWith('"')) grantee = grantee.slice(1, -1).replace(/""/g, '"');
+    if (grantee === '') grantee = 'PUBLIC';
+    const slash = item.indexOf('/', eq);
+    const letters = item.slice(eq + 1, slash === -1 ? undefined : slash);
+    const privs = new Set<string>();
+    for (const ch of letters) {
+      if (ch === '*') continue;
+      const p = SCHEMA_PRIV_LETTERS[ch];
+      if (p) privs.add(p);
+    }
+    if (privs.size) out[grantee] = [...privs].sort();
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Pure mappers — one catalog row -> one descriptor.
 // ---------------------------------------------------------------------------
@@ -411,7 +497,10 @@ function truthy(v: unknown): boolean {
 function predicate(v: unknown): string | null {
   if (v == null) return null;
   const s = String(v).trim();
-  return s.length > 0 ? s : null;
+  // Normalized at the PRODUCER, so the matcher, the canonical hash, and the drift detail
+  // all see one spelling — a live tree deparsed by an older major must compare equal to
+  // the same predicate parsed on a newer one. See deparse-normal.ts for the rule table.
+  return s.length > 0 ? normalizeDeparsedExpr(s) : null;
 }
 
 export interface PolicyRow {
@@ -524,6 +613,8 @@ export interface ContractRows {
   policies: PolicyRow[];
   grants: GrantRow[];
   columnGrants?: ColumnGrantRow[];
+  /** pg_namespace ACL rows (SCHEMA_ACL_SQL) — optional; absent means schema ACLs unknown. */
+  schemaAcls?: SchemaAclRow[];
   /** Already-mapped function descriptors (from security-catalog's FUNCTIONS_SQL). */
   functions: { schema: string; name: string; securityDefiner: boolean; hasSearchPath: boolean; owner?: string; ownerBypassesRls?: boolean }[];
 }
@@ -585,9 +676,22 @@ export function assembleContract(rows: ContractRows): AuthzContract {
     }))
     .sort((a, b) => a.name.localeCompare(b.name));
 
+  // Schema ACLs, keyed only when the read ran (absent = unknown, per the contract's doc).
+  // A NULL acl (owner default) contributes an empty entry so "we looked, nothing granted"
+  // is distinguishable from "we never looked".
+  let schemaAcls: Record<string, Record<string, string[]>> | undefined;
+  if (rows.schemaAcls) {
+    schemaAcls = {};
+    for (const row of rows.schemaAcls) {
+      if (IGNORED_SCHEMAS.has(row.schema)) continue;
+      schemaAcls[row.schema] = parseSchemaAcl(row.acl == null ? '{}' : String(row.acl)) ?? {};
+    }
+  }
+
   return {
     tables: [...tables.values()].sort((a, b) => a.table.localeCompare(b.table)),
     functions,
+    ...(schemaAcls ? { schemaAcls } : {}),
   };
 }
 
@@ -597,11 +701,11 @@ export async function introspectContract(
   mapFunctionRow: (row: any) => { schema: string; name: string; securityDefiner: boolean; hasSearchPath: boolean },
   functionsSql: string,
 ): Promise<AuthzContract> {
-  // ONE session: the five queries describe one moment under one pinned search_path.
+  // ONE session: the six queries describe one moment under one pinned search_path.
   // Policy USING / WITH CHECK expressions deparse relative to that path, so a read spread
   // across connections can report authz drift that does not exist.
-  const [rls, policies, grants, columnGrants, fnRows] = await session(
-    [RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, functionsSql],
+  const [rls, policies, grants, columnGrants, schemaAcls, fnRows] = await session(
+    [RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, SCHEMA_ACL_SQL, functionsSql],
     INTROSPECTION_SESSION,
   );
   return assembleContract({
@@ -609,6 +713,7 @@ export async function introspectContract(
     policies: policies as PolicyRow[],
     grants: grants as GrantRow[],
     columnGrants: columnGrants as ColumnGrantRow[],
+    schemaAcls: schemaAcls as SchemaAclRow[],
     functions: (fnRows as any[]).map(mapFunctionRow),
   });
 }

package/src/cli/authz-derive.ts

@@ -326,8 +326,19 @@ function renderColumnAbility(
  * Deliberately conservative. Every branch that cannot prove what it would emit falls
  * through to `notes` rather than guessing — the caller renders those as comments beside
  * the model, so the human sees the real rule and decides.
+ *
+ * `governRoles` (db:pull --govern-roles) is the operator's EXPLICIT decision to transcribe a
+ * foreign role's grants into `privileges` — which GOVERNS the role, per the doctrine on
+ * GOVERNED_VOCABULARY. Never inferred: a re-pull must not silently convert a rendering
+ * decision into an access decision. Transcription is complete-or-refuse — a governed role
+ * holding a column-scoped grant THROWS, because the model cannot express it for a foreign
+ * role and governing the role would make the next plan REVOKE it.
  */
-export function deriveAbilities(contract: TableContract): DerivedAbilities {
+export function deriveAbilities(
+  contract: TableContract,
+  opts: { governRoles?: ReadonlySet<string> } = {},
+): DerivedAbilities {
+  const govern = opts.governRoles ?? new Set<string>();
   const abilities: string[] = [];
   const notes: string[] = [];
   const table = contract.table;
@@ -599,6 +610,20 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
   const renderedColumnRoles = new Set<string>();
   for (const grantee of Object.keys(contract.columnGrants ?? {}).sort()) {
     const byPriv = contract.columnGrants![grantee];
+    if (govern.has(grantee)) {
+      // Complete-or-refuse. Governing this role reconciles ALL its grants, and `privileges`
+      // has no column axis for a foreign role — a partial transcription would leave this
+      // grant undeclared on a governed role, and the very next plan would REVOKE it.
+      const held = Object.entries(byPriv)
+        .filter(([, cols]) => (cols ?? []).length)
+        .map(([priv, cols]) => `${priv}(${(cols ?? []).join(', ')})`);
+      throw new Error(
+        `${table}: --govern-roles ${grantee} refused — the role holds a COLUMN-scoped grant here: ${held.join('; ')}. ` +
+          `Governing a role transcribes and reconciles ALL of its grants, and the model cannot express a ` +
+          `column-scoped grant for a foreign role, so the next plan would revoke it. Normalize the grant to ` +
+          `table-wide in the database first, or leave the role ungoverned.`,
+      );
+    }
     for (const priv of Object.keys(byPriv).sort()) {
       const cols = byPriv[priv] ?? [];
       if (!cols.length) continue;
@@ -621,7 +646,7 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
 
   // --- roles the compiler has no vocabulary for ----------------------------------------
   const unmappedRoles = Object.keys(contract.grants).filter(
-    (r) => !KNOWN_ROLES.has(r) && r !== 'PUBLIC' && r !== 'public' && !renderedColumnRoles.has(r),
+    (r) => !KNOWN_ROLES.has(r) && r !== 'PUBLIC' && r !== 'public' && !renderedColumnRoles.has(r) && !govern.has(r),
   );
 
   if (!abilities.length && !notes.length && !unmappedRoles.length) {
@@ -636,6 +661,18 @@ export function deriveAbilities(contract: TableContract): DerivedAbilities {
     privileges[role] = [...new Set([...(privileges[role] ?? []), ...privs])].sort();
   }
 
+  // --- roles the operator chose to GOVERN (--govern-roles) ------------------------------
+  //
+  // The whole grant, verbatim — DML and beyond-CRUD alike. These are the grants a fresh
+  // build must recreate (the migrations being deleted are what used to create them); a
+  // declared grant with no policy stays subject to the naked-grant WARN, which on an
+  // rls: false table correctly names it as live, deliberate, table-wide access.
+  for (const role of Object.keys(contract.grants).sort()) {
+    if (!govern.has(role)) continue;
+    const held = (contract.grants[role] ?? []).sort();
+    if (held.length) privileges[role] = [...new Set([...(privileges[role] ?? []), ...held])].sort();
+  }
+
   return { abilities, notes, unmappedRoles, privileges };
 }
 

package/src/cli/authz-lint.ts

@@ -1,7 +1,7 @@
 /**
  * authz-lint — the "force-RLS with no read authz" gate.
  *
- * Every modeled table gets RLS enabled (`compileTableContract` emits `rls.enabled: true`), and the
+ * A modeled table gets RLS enabled unless it declares `rls: false` (grants-only), and the
  * model is default-deny: no matching `can()` means no policy. So an EXPOSED table that declares no
  * read ability is a superuser-drop landmine — it reads fine while a bypassing role (a superuser
  * api) is in front, then returns empty for every app role the instant that role becomes
@@ -37,11 +37,18 @@ export function findReadAuthzGaps(models: readonly ModelDescriptor[]): ReadAuthz
     gaps.push({
       schema: m.schema,
       table: m.table,
-      message:
-        `${m.schema}.${m.table} is exposed and RLS-enabled but declares no read ability — every app role ` +
-        `reads empty once it is RLS-subject (e.g. after dropping a superuser api). Declare a read: ` +
-        `can('read') for public data, can('read', { owner: '<col>' }) for private, or mark the model ` +
-        `private() if it is not part of the data API.`,
+      // An rls: false table cannot take the "declare a read" cure — defineModel refuses
+      // abilities there — so its message names the two options that exist. db:pull never
+      // authors this shape (it renders private: true beside rls: false); only a hand
+      // author can, and this is the line that stops them.
+      message: m.rls === false
+        ? `${m.schema}.${m.table} declares rls: false and is exposed to the generic data API — grants ` +
+          `are its only gate, so every granted role reads every row, unfiltered. A grants-only table ` +
+          `is operational, not API surface: mark it private(), or drop rls: false and declare abilities.`
+        : `${m.schema}.${m.table} is exposed and RLS-enabled but declares no read ability — every app role ` +
+          `reads empty once it is RLS-subject (e.g. after dropping a superuser api). Declare a read: ` +
+          `can('read') for public data, can('read', { owner: '<col>' }) for private, or mark the model ` +
+          `private() if it is not part of the data API.`,
     });
   }
   return gaps;
@@ -63,12 +70,12 @@ export function findReadAuthzGaps(models: readonly ModelDescriptor[]): ReadAuthz
  *
  * Severity is a WARNING, never fatal, and that is a considered narrowing of the original ruling.
  * The ruling asked for an ERROR on a table without RLS, where a naked grant is an unrestricted
- * table-wide privilege. That case cannot arise from models: `compileTableContract` emits
- * `rls: { enabled: true }` UNCONDITIONALLY for every modeled table (authz-compile.ts:558). So a
- * declared naked grant is always dead-on-arrival and only becomes live if someone later disables
- * RLS on that table — a real risk, but a future one, and failing CI over a faithful rendering of
- * a database the adopter is trying to adopt would make `db:pull` unusable on exactly the schemas
- * it exists for.
+ * table-wide privilege. Since `rls: false` landed, that case CAN arise from models — a
+ * grants-only table declares exactly that shape, deliberately: grants ARE its whole
+ * authorization, and there is no policy for the grant to be naked of. So the two RLS postures
+ * get two messages (dead grant vs live grants-only access), and both stay WARNINGs: failing CI
+ * over a faithful rendering of a database the adopter is trying to adopt would make `db:pull`
+ * unusable on exactly the schemas it exists for.
  */
 export interface NakedGrant {
   schema: string;
@@ -95,13 +102,20 @@ export function findNakedGrants(models: readonly ModelDescriptor[]): NakedGrant[
         table: m.table,
         role,
         privileges: dml,
-        message:
-          `${m.schema}.${m.table}: '${role}' holds ${dml.join(', ')} as a grant with no policy beside it. ` +
-          `It is dead while RLS is on — the role reads zero rows — and becomes an unrestricted ` +
-          `table-wide privilege the day RLS is disabled or a broad policy is added. If this came from ` +
-          `db:pull it is a faithful reading of the database; decide whether to give it a policy ` +
-          `(can(...)) or revoke it. If you wrote it by hand, you almost certainly want can() instead, ` +
-          `which decides the grant and the policy together.`,
+        // Two postures, two truths. Compared against literal `false`: a descriptor from an
+        // older @everystack/model has no rls key, and undefined means enabled (see
+        // authz-compile's identical guard).
+        message: m.rls === false
+          ? `${m.schema}.${m.table}: '${role}' holds ${dml.join(', ')} with rls: false — this is LIVE, ` +
+            `unrestricted table-wide access, not a dead grant: no row filter applies to '${role}' on ` +
+            `this table. That is what a grants-only table declares, so confirm it is deliberate; if ` +
+            `'${role}' should see only some rows, drop rls: false and declare can(...) instead.`
+          : `${m.schema}.${m.table}: '${role}' holds ${dml.join(', ')} as a grant with no policy beside it. ` +
+            `It is dead while RLS is on — the role reads zero rows — and becomes an unrestricted ` +
+            `table-wide privilege the day RLS is disabled or a broad policy is added. If this came from ` +
+            `db:pull it is a faithful reading of the database; decide whether to give it a policy ` +
+            `(can(...)) or revoke it. If you wrote it by hand, you almost certainly want can() instead, ` +
+            `which decides the grant and the policy together.`,
       });
     }
   }

package/src/cli/commands/db-check.ts

@@ -433,7 +433,11 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
   } else if (failed) {
     fail('db:check FAILED — the merged declared state is not shippable as-is (findings above).');
   } else if (ephemeral !== null) {
-    success(`db:check passed — declared state composes from scratch and lands MATCH at ${ephemeral.fingerprint.slice(0, 12)}.`);
+    success(`db:check passed — the declared state composes from scratch and lands on its own fingerprint (${ephemeral.fingerprint.slice(0, 12)}).`);
+    // Named because it kept being read as the stronger claim (a consumer, 2026-08-07): this
+    // ring proves the checkout against ITSELF, on an empty database. Whether an existing
+    // database IS this state is a different question with a different verb.
+    info('This proves the checkout is self-consistent and buildable — not that any existing database matches it. For that claim, run db:fingerprint against the database.');
   } else {
     success('db:check passed (static ring only — no database provided for the ephemeral compose).');
   }

package/src/cli/commands/db-pull.ts

@@ -42,7 +42,8 @@ import { introspectContract, type TableContract, type AuthzContract } from '../a
 import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport, type TableOwner } from '../authz-ownership.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { renderDerivedSource, renderDerivedFile, type DerivedRenderResult } from '../derived-render.js';
-import { renderModelSource, renderModelFiles, pullableTables, modelVarName, ABILITY_PRESETS } from '../model-render.js';
+import { renderModelSource, renderModelFiles, pullableTables, skippedInfrastructureTables, modelVarName, ABILITY_PRESETS } from '../model-render.js';
+import { deriveAbilities } from '../authz-derive.js';
 import type { QueryRunner } from '../authz-contract.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
 import { borrowedSessionRunner, type SessionRunner } from '../session.js';
@@ -132,6 +133,24 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     process.exit(1);
   }
 
+  // --govern-roles: the operator's EXPLICIT decision to transcribe these foreign roles'
+  // grants into `privileges` — which governs them. Required for migration deletion when
+  // the migrations created grants to roles outside the vocabulary: a fresh build from
+  // models must recreate them. Never inferred from the database (a re-pull must not turn
+  // a rendering decision into an access decision); complete-or-refuse per role — a listed
+  // role holding a column-scoped grant fails the pull (see deriveAbilities).
+  const governRoles = (flags['govern-roles'] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+  if (governRoles.length && abilities !== 'live') {
+    fail(`--govern-roles transcribes LIVE grants, so it requires --abilities live.`);
+    process.exit(1);
+  }
+  for (const r of governRoles) {
+    if (['anon', 'authenticated', 'admin', 'PUBLIC', 'public'].includes(r)) {
+      fail(`--govern-roles ${r}: the vocabulary roles and PUBLIC are always governed — name only foreign roles (an ops/connection role the migrations granted to).`);
+      process.exit(1);
+    }
+  }
+
   let dbSource: DbSource;
   try {
     dbSource = resolveDbSource(flags);
@@ -196,12 +215,15 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       const unmapped = new Set<string>();
       for (const t of contract.tables) {
         for (const r of Object.keys(t.grants)) {
-          if (!['anon', 'authenticated', 'admin', 'PUBLIC', 'public'].includes(r)) unmapped.add(r);
+          if (!['anon', 'authenticated', 'admin', 'PUBLIC', 'public'].includes(r) && !governRoles.includes(r)) unmapped.add(r);
         }
       }
+      if (governRoles.length) {
+        note(`--govern-roles ${governRoles.join(', ')}: their grants are transcribed as privileges — the models now OWN them, and a fresh build recreates them.`);
+      }
       if (unmapped.size) {
         note(`Grants exist for ${[...unmapped].sort().join(', ')} — not rendered: abilities name the roles the model knows (anon/authenticated/admin).`);
-        detail(`These are left exactly as they are in the database. Add can(..., { role }) only if you want the models to own them.`);
+        detail(`These are left exactly as they are in the database. Add can(..., { role }) to own them, or re-pull with --govern-roles to transcribe their grants as privileges.`);
       }
       // ADOPTION: record the foreign grantees that were already here, per stage. The
       // reconciler exempts them from revocation, so this artifact is what stops that
@@ -209,10 +231,10 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       // grown, refuses at db:plan. It lands as a reviewable diff, with writes flagged,
       // because nothing mechanical can tell a legitimate BI role from an attacker's on day
       // one; the defence is forcing the look and making it recur.
-      // The governed set at ADOPTION is the fixed vocabulary alone: the models being
-      // rendered here can only name anon/authenticated/admin, so every other grantee is
-      // foreign by construction — the same set `unmapped` just reported, with privileges.
-      pulledExemptions = ungovernedGrants(contract, new Set(ALWAYS_GOVERNED));
+      // The governed set at ADOPTION is the fixed vocabulary plus any --govern-roles: a
+      // governed role's grants are DECLARED (transcribed as privileges), so recording them
+      // as exemptions too would double-book them — declared and exempted at once.
+      pulledExemptions = ungovernedGrants(contract, new Set([...ALWAYS_GOVERNED, ...governRoles]));
       pulledFingerprint = fingerprintLive(current, contract).hash;
     }
     // --matviews-as-tables: the flip needs real fields — one extra catalog read for the
@@ -255,6 +277,33 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     process.exit(1);
   }
 
+  // The denylist's consequence, stated at the moment it applies: a migration tool's
+  // bookkeeping is never modeled, so it can never enter the declared state — and a
+  // fully-declared database therefore cannot contain it.
+  const skippedInfra = skippedInfrastructureTables(current, schema);
+  if (skippedInfra.length) {
+    caution(
+      `${skippedInfra.length} migration-tool table(s) skipped, never modeled: ${skippedInfra.join(', ')} — `
+      + `a migration journal is the tool's own state, not the app's. To reach a fully-declared database, `
+      + `DROP them once the tool that owns them is retired.`,
+    );
+  }
+
+  // The --govern-roles complete-or-refuse gate, run BEFORE any file is written: a refusal
+  // mid-render would leave a half-written models directory. Pure re-derivation, pulled
+  // tables only — a governed role's column grant on an UNPULLED table is safe (that table
+  // is not declared, so nothing reconciles it).
+  if (governRoles.length && liveAuthz) {
+    const pulledNames = new Set(pulled.map((t) => t.table));
+    try {
+      const govern = new Set(governRoles);
+      for (const [name, c] of liveAuthz) if (pulledNames.has(name)) deriveAbilities(c, { governRoles: govern });
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+  }
+
   // WHO owns the tables being pulled. Nothing is FLAGGED here: flagging needs a declared
   // write principal to contradict, and the models this pull is about to write do not exist
   // yet. Naming the owner is the half the pull genuinely saw — and the half that vanishes
@@ -328,7 +377,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
   if (flags.out && !flags.out.endsWith('.ts')) {
     // A directory: one file per model + index.ts — the default shape for a real app.
     const dir = path.resolve(flags.out);
-    const files = renderModelFiles(current, { schema, abilities, liveAuthz, derived: embeddedDerived, externalDerived });
+    const files = renderModelFiles(current, { schema, abilities, liveAuthz, governRoles, derived: embeddedDerived, externalDerived });
     try {
       await fs.mkdir(dir, { recursive: true });
       const written = new Set(files.map((f) => f.file));
@@ -345,7 +394,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     source = files.map((f) => f.source).join('\n');
   } else if (flags.out) {
     const outPath = path.resolve(flags.out);
-    source = renderModelSource(current, { schema, abilities, liveAuthz, derived: embeddedDerived });
+    source = renderModelSource(current, { schema, abilities, liveAuthz, governRoles, derived: embeddedDerived });
     try {
       await fs.mkdir(path.dirname(outPath), { recursive: true });
       await fs.writeFile(outPath, source, 'utf8');
@@ -355,7 +404,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     }
     ok(`Wrote ${path.relative(process.cwd(), outPath)} — ${pulled.length} model(s).`);
   } else {
-    source = renderModelSource(current, { schema, abilities, liveAuthz, derived: embeddedDerived });
+    source = renderModelSource(current, { schema, abilities, liveAuthz, governRoles, derived: embeddedDerived });
     process.stdout.write(source);
     ok(`Rendered ${pulled.length} model(s) from schema "${schema}" (stdout — redirect or pass --out to save).`);
   }
@@ -391,6 +440,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     const stageName = flags.stage;
     if (!stageName) {
       note(`No --stage, so ${BASELINE_FILE} was not written. The foreign grantees above are recorded per stage; re-run with --stage <name> to adopt them, or db:plan will refuse until you do.`);
+      note(`--stage composes with --database-url: the URL stays the connection, the stage only LABELS the baseline entry — a local clone can adopt for a deployed stage without touching it.`);
     } else {
       const entry = buildStageBaseline(pulledExemptions, { observedAt: new Date().toISOString(), fingerprint: pulledFingerprint });
       const merged = mergeBaseline(await readBaselineFile(), stageName, entry);

package/src/cli/deparse-normal.ts

@@ -0,0 +1,137 @@
+/**
+ * deparse-normal — cross-version normalization of `pg_get_expr` output.
+ *
+ * A policy predicate's stored tree is built by whichever server PARSED the DDL, and
+ * different PostgreSQL majors const-fold the same source differently. The measured case
+ * (a consumer's stage, 2026-08-08): an older major stores an array cast OUTSIDE the array,
+ *
+ *     (ARRAY['a'::character varying, 'b'::character varying])::text[]
+ *
+ * while PG17 distributes it over the elements at parse time,
+ *
+ *     ARRAY[('a'::character varying)::text, ('b'::character varying)::text]
+ *
+ * Text-identity across venues is then unreachable: models pulled on one major can never
+ * equal a stage on another, the differ plans DROP+CREATE forever (the stage re-deparses in
+ * its own spelling), and the fingerprint gate cannot MATCH. Identity must not depend on the
+ * two venues sharing a parser.
+ *
+ * THE RULE TABLE IS DELIBERATELY SMALL. Each rewrite must be provably semantics-preserving,
+ * because this text feeds the policy matcher, whose safety property is "misses are safe,
+ * false matches are the disaster". One rule today:
+ *
+ *   ARRAY-CAST DISTRIBUTION: `(ARRAY[e1, …, en])::T[]  ==  ARRAY[(e1)::T, …, (en)::T]`
+ *   for n ≥ 1. PostgreSQL defines an array-to-array cast element-wise (parse_coerce), so
+ *   the two expressions denote the same value for every input; wrapping an element in
+ *   parentheses is parse-neutral. The empty array is EXCLUDED: `ARRAY[]` without a cast has
+ *   no type, so its cast is load-bearing and stays.
+ *
+ * Anything the scanner does not positively recognize is left byte-for-byte unchanged — an
+ * unrecognized spelling is a MISS (drop + create, the pre-existing behavior), never a guess.
+ * Escalation is named, not implied: the SECOND cross-version variant found in the field is
+ * the trigger to adopt libpg_query and move identity onto normalized ASTs (Ty, 2026-08-09) —
+ * a growing rule table over raw text is where scanning stops being defensible.
+ *
+ * Applied at the PRODUCERS (live introspection's `predicate()`, the compiler's policy
+ * assembly), so every downstream comparison — the identity matcher, the canonical hash, the
+ * drift detail — sees normalized text without holding its own copy of this rule.
+ */
+
+/** `::text[]` / `::character varying[]` — the cast suffix after `(ARRAY[…])`. */
+const ARRAY_CAST_SUFFIX = /^::([A-Za-z_][A-Za-z0-9_]*(?:\s[A-Za-z_][A-Za-z0-9_]*)*)\[\]/;
+
+/**
+ * From an opening single or double quote, the index of its closing quote.
+ * SQL escapes a quote by doubling it; a doubled quote is content, not a close.
+ * Returns -1 on an unterminated literal (the caller then leaves the text alone).
+ */
+function skipQuoted(s: string, at: number): number {
+  const q = s[at];
+  for (let j = at + 1; j < s.length; j++) {
+    if (s[j] !== q) continue;
+    if (s[j + 1] === q) { j++; continue; }
+    return j;
+  }
+  return -1;
+}
+
+/** The index of the `]` closing the `[` at `open`, honoring nesting and quoted regions. */
+function matchBracket(s: string, open: number): number {
+  let sq = 0;
+  let par = 0;
+  for (let j = open; j < s.length; j++) {
+    const c = s[j];
+    if (c === "'" || c === '"') {
+      j = skipQuoted(s, j);
+      if (j < 0) return -1;
+    } else if (c === '[') sq++;
+    else if (c === ']') { sq--; if (sq === 0 && par === 0) return j; }
+    else if (c === '(') par++;
+    else if (c === ')') par--;
+  }
+  return -1;
+}
+
+/** Split on top-level commas (both nesting depths zero), or null on an unterminated literal. */
+function splitTopLevel(s: string): string[] | null {
+  const out: string[] = [];
+  let start = 0;
+  let sq = 0;
+  let par = 0;
+  for (let j = 0; j < s.length; j++) {
+    const c = s[j];
+    if (c === "'" || c === '"') {
+      j = skipQuoted(s, j);
+      if (j < 0) return null;
+    } else if (c === '[') sq++;
+    else if (c === ']') sq--;
+    else if (c === '(') par++;
+    else if (c === ')') par--;
+    else if (c === ',' && sq === 0 && par === 0) {
+      out.push(s.slice(start, j));
+      start = j + 1;
+    }
+  }
+  out.push(s.slice(start));
+  return out;
+}
+
+/** One left-to-right pass: rewrite the first recognized `(ARRAY[…])::T[]`, or null if none. */
+function distributeOnce(s: string): string | null {
+  let i = 0;
+  while ((i = s.indexOf('(ARRAY[', i)) !== -1) {
+    const open = i + 6; // the '['
+    const close = matchBracket(s, open);
+    if (close === -1) return null; // unparseable text — leave everything alone
+    if (s[close + 1] === ')') {
+      const m = ARRAY_CAST_SUFFIX.exec(s.slice(close + 2));
+      if (m) {
+        const inner = s.slice(open + 1, close);
+        const elements = splitTopLevel(inner);
+        // Empty array excluded: its cast carries the type. A failed split leaves the text alone.
+        if (elements !== null && inner.trim().length > 0) {
+          const t = m[1];
+          const rewritten = `ARRAY[${elements.map((e) => `(${e.trim()})::${t}`).join(', ')}]`;
+          return s.slice(0, i) + rewritten + s.slice(close + 2 + m[0].length);
+        }
+      }
+    }
+    i = open;
+  }
+  return null;
+}
+
+/**
+ * Normalize one deparsed expression. Idempotent; unrecognized text returns unchanged.
+ * Fixpoint-bounded: nesting deeper than the cap returns its progress, which is still
+ * deterministic — both sides of every comparison run this same function.
+ */
+export function normalizeDeparsedExpr(text: string): string {
+  let s = text;
+  for (let n = 0; n < 64; n++) {
+    const next = distributeOnce(s);
+    if (next === null) return s;
+    s = next;
+  }
+  return s;
+}

package/src/cli/index.ts

@@ -359,7 +359,7 @@ Usage:
   everystack db:export         --schema <name> [--stage <name> | --database-url <url> [--out <file.dump>]] [--models <barrel>]  Schema-scoped pg_dump artifact, stamped with the DECLARED schema fingerprint (the canonical-sync export; db:swap gates on that stamp). --stage dumps the stage's private DB via the ops Lambda → S3; --database-url (explicit flag, never the env) dumps a reachable DB to a local .dump + .meta.json — the build-locally → publish → swap on-ramp
   everystack db:swap           --schema <name> --from <artifact.dump | artifact-id> [--stage <name> --direct | --database-url <url>] --confirm [--fingerprint <hash>] [--snapshot physical|logical|none] [--snapshot-ref <id>] [--rebuild-derived] [--dump-build <file.json>]  Land a schema artifact atomically: fingerprint gate → pre-flight refusals → CONFIRMED snapshot → restore into <schema>_incoming (COPY-safe rewrite) → build the paired derived layer → one txn (drop+rename+recreate app→schema FKs, re-apply authz + schema USAGE) → assertions → drop retiring. Refresh-free; app.* untouched; the derived layer is never absent. DESTRUCTIVE. The venue is EXPLICIT — DATABASE_URL in the env is refused, and --stage requires --direct (a multi-GB restore exceeds the ops-Lambda 900s clock). The rollback point defaults to a PHYSICAL RDS snapshot on a stage that exposes databaseInstanceId (no locks, no pg_dump contending with the restore) and a WAITED logical db:backup otherwise; a bare --database-url refuses without --snapshot-ref <id> or --snapshot none. docs/schema-swap.md
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply] [--dry-run]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops). --dry-run prints the edge and writes NOTHING (no migration, no journal entry, no schema refresh) — the preview verb; db:diff computes a models-vs-models edge with no database at all. The resolved --schema-out is recorded in the migration journal: later flag-less runs reuse it (flag > recorded > default), a differing flag updates the record and says so
-  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities live|public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored). **--abilities live is the brownfield mode**: derive each model's authz from the grants and policies the database ALREADY has, and write the foreign-grantee baseline (db/authz-baseline.json) — this is what you want when adopting an existing schema. --abilities public-read stamps the common stanza (public read, admin write) uncommented — greenfield only, since on an existing database it declares public read of every table. Both are explicit generated code, never a runtime default. --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review; add --suggest-keys to probe the LIVE rows for functionally-unique columns (one scan per matview) and surface each as a commented .primaryKey() suggestion. docs/derived-objects.md#flipping-a-matview-to-a-materialized-table---matviews-as-tables
+  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities live|public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored). **--abilities live is the brownfield mode**: derive each model's authz from the grants and policies the database ALREADY has, and write the foreign-grantee baseline (db/authz-baseline.json) — this is what you want when adopting an existing schema. --abilities public-read stamps the common stanza (public read, admin write) uncommented — greenfield only, since on an existing database it declares public read of every table. Both are explicit generated code, never a runtime default. --govern-roles <r1,r2> (with --abilities live) transcribes the named FOREIGN roles' grants into privileges — the models then OWN them, so a fresh build recreates them; required for migration deletion when the migrations created grants to an ops/connection role. Explicit only (a re-pull must not silently govern), complete-or-refuse (a listed role holding a column-scoped grant fails the pull before anything is written). --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review; add --suggest-keys to probe the LIVE rows for functionally-unique columns (one scan per matview) and surface each as a commented .primaryKey() suggestion. docs/derived-objects.md#flipping-a-matview-to-a-materialized-table---matviews-as-tables
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
   everystack db:fingerprint    [--stage <name> | --database-url <url>] [--models <barrel>] [--json]  Content-address the live base schema (tables+constraints+authz) and compare against the models — MATCH/MISMATCH (exit 1), plus the unfingerprinted-objects report
   everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--only a,b] [--json]  Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (atomic — DDL + provenance in one transaction) and records provenance + schema_log; --apply --stage runs credential-free in the ops Lambda (no admin URL on the deployer, the db:apply twin), --apply --database-url runs direct. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive. --only <schema.name,…> restricts the run to the named objects (surgical); with --rebuild it FORCES those to rebuild from source even when the hashes show no diff — the recovery exit when a mistaken --rebaseline left a self-consistent-but-wrong provenance row (the dependency cascade rebuilds their live dependents).

package/src/cli/migration-generate.ts

@@ -90,7 +90,11 @@ function holdDrop(sql: string): string {
  */
 export function unmodeledTables(models: ModelDescriptor[], current: SchemaSnapshot, opts: GenerateOptions = {}): string[] {
   const schema = opts.schema ?? 'public';
-  const declared = new Set(models.map((m) => `${schema}.${m.table}`));
+  // The model's OWN schema first — the same rule the compiler applies. Qualifying every
+  // model with the call default read a multi-schema checkout's non-public models as
+  // unmodeled: a consumer's plan listed three modeled tables as riding through untouched,
+  // which is a false statement about what the plan governs.
+  const declared = new Set(models.map((m) => `${m.schema ?? schema}.${m.table}`));
   // A pending table rename's OR move's source is ours — declared under its new (qualified)
   // name; without this it reads as an undeclared orphan (F1) and the move/rename silently
   // degrades to CREATE + leave-behind, the exact bug the markers exist to prevent.
@@ -233,6 +237,20 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   // The from-scratch path had this from the start; the diff path did not, so a non-public
   // model reached through db:sync/db:generate was unreachable by every role that did not
   // pick up USAGE some other way. The example app's analytics schema is what surfaced it.
+  // Diffed against the LIVE schema ACLs when the contract carries them. This phase used to
+  // emit unconditionally, so any plan with an authz statement re-granted USAGE the database
+  // already held — two false statements on every one of a consumer's stage plans (measured,
+  // catalog-verified, 2026-08-08). A role holds USAGE when its own nspacl entry says so or
+  // when PUBLIC's does (PUBLIC reaches every role). Membership-derived usage is invisible
+  // here and stays emitted — idempotent, and rarer than the direct grants that were the bug.
+  // No schemaAcls (fresh compose, older recorder) = unknown = emit, exactly as before.
+  const liveSchemaAcls = liveAuthzRenamed?.schemaAcls;
+  const hasLiveUsage = (s: string, role: string): boolean => {
+    const acl = liveSchemaAcls?.[s];
+    if (!acl) return false;
+    const key = role.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : role;
+    return (acl[key] ?? []).includes('USAGE') || (acl.PUBLIC ?? []).includes('USAGE');
+  };
   const usagePhase = authzPhase.length
     ? [...new Set(desiredContracts.map((c) => c.table.split('.')[0]))]
         .filter((s) => s !== 'public')
@@ -244,8 +262,9 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
             for (const r of Object.keys(c.grants)) roles.add(r);
             for (const r of Object.keys(c.columnGrants ?? {})) roles.add(r);
           }
-          if (!roles.size) return [];
-          const targets = [...roles].sort().map((r) => (r.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : r)).join(', ');
+          const missing = [...roles].filter((r) => !hasLiveUsage(s, r));
+          if (!missing.length) return [];
+          const targets = missing.sort().map((r) => (r.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : r)).join(', ');
           return [`GRANT USAGE ON SCHEMA "${s}" TO ${targets}`];
         })
     : [];

package/src/cli/model-render.ts

@@ -79,6 +79,14 @@ export interface RenderOptions {
    * authz-derive.ts for the rule (policy presence is not effective privilege).
    */
   liveAuthz?: Map<string, TableContract>;
+  /**
+   * `--govern-roles` — the operator's explicit decision to transcribe these foreign roles'
+   * grants into `privileges`, which GOVERNS them. Required for migration deletion when the
+   * migrations created grants to roles outside the vocabulary (an ops/connection role): a
+   * fresh build from models must recreate them or the deletion loses the ops lane its
+   * access. Never inferred — see deriveAbilities. Complete-or-refuse per role.
+   */
+  governRoles?: string[];
   /** The rendered derived layer (B5) — rides the barrel: block after the models,
    *  sequences/derived arrays on the module wrapper, symbols on the import header. */
   derived?: DerivedRenderResult;
@@ -124,7 +132,7 @@ export function isPublicReadAbility(expr: string): boolean {
  * abilities, not a regex over the joined text (a live predicate can span lines and carry its
  * own braces). An unknown preset throws — grants are authored, never guessed.
  */
-function abilitiesStanza(mode: string, table?: TableSchema, liveAuthz?: Map<string, TableContract>): { text: string; publicRead: boolean } {
+function abilitiesStanza(mode: string, table?: TableSchema, liveAuthz?: Map<string, TableContract>, governRoles?: ReadonlySet<string>): { text: string; publicRead: boolean } {
   if (mode === 'live') {
     const contract = table && liveAuthz?.get(table.table);
     if (!contract) {
@@ -137,8 +145,20 @@ function abilitiesStanza(mode: string, table?: TableSchema, liveAuthz?: Map<stri
         publicRead: false,
       };
     }
-    const derived = deriveAbilities(contract);
-    return { text: renderDerivedAbilities(derived), publicRead: derived.abilities.some(isPublicReadAbility) };
+    const derived = deriveAbilities(contract, { governRoles });
+    const lines = [renderDerivedAbilities(derived)];
+    // A grants-only table: live RLS is OFF and no ability rendered. Transcribe the flag —
+    // without it the compiler declares RLS enabled and the first plan after adoption
+    // proposes ENABLE ROW LEVEL SECURITY, which with zero policies denies every non-owner
+    // role a table it already uses (a consumer's ops lane, measured 2026-08-07). Never
+    // rendered beside abilities: defineModel refuses the pair, and a live-off table whose
+    // grants DO derive abilities is adopt-mode territory, not a flag transcription.
+    // The writtenBy stanza always accompanies this line (live-off is never FORCEd), which
+    // is what lets the rendered model load — rls: false with the 'app' default is refused.
+    if (!derived.abilities.length && !contract.rls.enabled) {
+      lines.push(`  rls: false,   // live reality: row security is OFF — authorization here is grants-only.`);
+    }
+    return { text: lines.join('\n'), publicRead: derived.abilities.some(isPublicReadAbility) };
   }
   if (mode === 'commented') {
     return {
@@ -257,6 +277,21 @@ export function pullableTables(snapshot: SchemaSnapshot, schema: string | string
   });
 }
 
+/**
+ * The infrastructure tables a pull SKIPPED, qualified — so the command can NAME them.
+ *
+ * The denylist has a consequence nothing used to state: these tables are never modeled,
+ * so an adopter with legacy bookkeeping (a retired Rails app's `schema_migrations`) can
+ * only reach a fully-declared database by DROPPING them. A consumer did that archaeology
+ * by hand (2026-08-07); one line at pull time is what it should have cost.
+ */
+export function skippedInfrastructureTables(snapshot: SchemaSnapshot, schema: string | string[]): string[] {
+  const schemas = new Set(Array.isArray(schema) ? schema : [schema]);
+  return snapshot.tables
+    .map((t) => t.table)
+    .filter((table) => schemas.has(schemaOf(table)) && INFRASTRUCTURE_TABLES.has(bareName(table)));
+}
+
 /** The schema a qualified (or bare) table lives in — bare means public. */
 function schemaOf(table: string): string {
   const dot = table.indexOf('.');
@@ -515,7 +550,7 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
 }
 
 /** One `export const X = defineModel(...)` block for a table. */
-export function renderModelBlock(table: TableSchema, known: Set<string>, enums: Map<string, string[]> = new Map(), abilities = 'commented', liveAuthz?: Map<string, TableContract>): string {
+export function renderModelBlock(table: TableSchema, known: Set<string>, enums: Map<string, string[]> = new Map(), abilities = 'commented', liveAuthz?: Map<string, TableContract>, governRoles?: ReadonlySet<string>): string {
   // A CHECK that reverses to a single field's .validate() is rendered on the field (ergonomic);
   // the rest stay table-level check(). Both round-trip — this only chooses the nicer form.
   const validates = new Map<string, string>();
@@ -532,7 +567,7 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
   // The authz decision renders FIRST — before fields — because it is the first thing a
   // reviewer must resolve about a model (and where the field-report consumer's codemod
   // put it, proving the position is mechanical-edit-friendly).
-  const stanza = abilitiesStanza(abilities, table, liveAuthz);
+  const stanza = abilitiesStanza(abilities, table, liveAuthz, governRoles);
   const writtenBy = writtenByStanza(table, liveAuthz);
   const softDelete = softDeleteStanza(table, stanza.publicRead);
 
@@ -654,7 +689,7 @@ export function renderModelSource(snapshot: SchemaSnapshot, opts: RenderOptions
   const known = new Set(tables.map((t) => bareName(t.table)));
   const enums = new Map((snapshot.enums ?? []).map((e) => [e.name, e.values]));
 
-  const blocks = tables.map((t) => renderModelBlock(t, known, enums, opts.abilities ?? 'commented', opts.liveAuthz));
+  const blocks = tables.map((t) => renderModelBlock(t, known, enums, opts.abilities ?? 'commented', opts.liveAuthz, opts.governRoles && new Set(opts.governRoles)));
   // The derived layer (B5): sequences + views/matviews/functions, after the models they
   // reference, before the module wrapper that composes all three.
   if (opts.derived?.block) blocks.push(opts.derived.block);
@@ -722,7 +757,7 @@ export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions =
   const enums = new Map((snapshot.enums ?? []).map((e) => [e.name, e.values]));
 
   const files: RenderedModelFile[] = tables.map((t) => {
-    const block = renderModelBlock(t, known, enums, opts.abilities ?? 'commented', opts.liveAuthz);
+    const block = renderModelBlock(t, known, enums, opts.abilities ?? 'commented', opts.liveAuthz, opts.governRoles && new Set(opts.governRoles));
     const crossImports = referencedTables(t, known).map(
       (target) => `import { ${modelVarName(target)} } from '${modelImportPath(target)}';`,
     );

package/src/cli/schema-fingerprint.ts

@@ -110,7 +110,7 @@ import { normalizeDefault, normalizeCheck, indexKey } from './schema-diff.js';
 // it from the canonical form AND the reconciler leaves it alone, before and after. Restrictive
 // policies are never subsumed (they AND, so removing one would WIDEN), and the rule must match
 // exactly including the effective WITH CHECK.
-export const FINGERPRINT_VERSION = 8;
+export const FINGERPRINT_VERSION = 9;
 
 // ---------------------------------------------------------------------------
 // Canonical form.