@everystack/cli 0.4.100 → 0.4.102

package/src/cli/authz-derive.ts

@@ -28,6 +28,9 @@
 import { EXTRA_PRIVILEGES, sessionlessAudience } from '@everystack/model';
 import { holdsPrivilege, holdsTablePrivilege } from './authz-contract';
 import type { TableContract, PolicyContract } from './authz-contract';
+import { templateBody, tsString, commentLines } from './ts-template';
+import { refuseProtoKey, liveObject } from './generated-names';
+import { normalizeDeparsedExpr } from './deparse-normal';
 
 /** One rendered decision: either an ability line, or a comment explaining the omission. */
 export interface DerivedAbilities {
@@ -55,6 +58,13 @@ export interface DerivedAbilities {
    * it once, for the whole pull.
    */
   unmappedRoles: string[];
+  /**
+   * What a GOVERNED custom role (--govern-roles) holds that `can()` cannot state exactly, one
+   * line each, naming the table and the role. db:pull prints them as WARNINGs and the model
+   * carries them as comments: a grant kept as a raw `privileges` entry, or a policy the model
+   * does not declare (so the next db:plan drops it). Never silently approximated.
+   */
+  warnings: string[];
 }
 
 const DML: Record<string, 'read' | 'create' | 'update' | 'delete'> = {
@@ -260,13 +270,43 @@ export function parsePublicOrOwn(
  */
 const granted = holdsTablePrivilege;
 
-/** The policies that apply to a role for a command (an `ALL` policy covers every command). */
-function policiesFor(contract: TableContract, role: string, command: string): PolicyContract[] {
+/** The policies that name a role for a command (an `ALL` policy covers every command). */
+function policiesNaming(contract: TableContract, role: string, command: string): PolicyContract[] {
   return contract.policies.filter(
     (p) => (p.command === command || p.command === 'ALL') && (p.roles.includes(role) || p.roles.includes('public')),
   );
 }
 
+/**
+ * Can this policy admit any row for the command? PostgreSQL skips a policy whose expression is
+ * null: SELECT, UPDATE and DELETE read USING; INSERT reads WITH CHECK, and an ALL policy with no
+ * WITH CHECK falls back to its USING. A policy with neither admits NO row, and an ability with
+ * no predicate compiles USING (true): EVERY row.
+ */
+function admitsRows(p: PolicyContract, command: string): boolean {
+  return (command === 'INSERT' ? p.check ?? p.using : p.using) != null;
+}
+
+/**
+ * The policies that apply to a role for a command and can admit a row. Every ability site reads
+ * this, so a policy that admits no row never becomes an ability; its grant is declared raw.
+ */
+function policiesFor(contract: TableContract, role: string, command: string): PolicyContract[] {
+  return policiesNaming(contract, role, command).filter((p) => admitsRows(p, command));
+}
+
+/** Notes naming the permissive policies a role's dead grants sit under that admit no row. */
+function noRowPolicyNotes(contract: TableContract, role: string, privs: readonly string[]): string[] {
+  const out: string[] = [];
+  for (const priv of privs) {
+    for (const p of policiesNaming(contract, role, priv)) {
+      if (!p.permissive || admitsRows(p, priv)) continue;
+      out.push(`  policy "${p.name}" (${priv}) has no ${priv === 'INSERT' ? 'WITH CHECK' : 'USING'}, so it admits no row; an ability would admit every row.`);
+    }
+  }
+  return out;
+}
+
 /**
  * Does this grant actually give the role rows?
  *
@@ -336,7 +376,7 @@ function sqlFragment(pred: string | null): string | null {
   if (!pred) return null;
   const t = pred.trim();
   if (t === 'true' || t === '(true)') return null;
-  return `sql\`${t.replace(/`/g, '\\`')}\``;
+  return `sql\`${templateBody(t)}\``;
 }
 
 /** The policy catalog spells the PUBLIC pseudo-role lower-case; grants spell it upper-case. */
@@ -391,7 +431,7 @@ function renderColumnAbility(
   // Owner-only uses the model's authenticated default. Every other grantee must be named so the
   // compiler emits the policy TO the live role, not a role-less public ability — and a differing
   // check names it too, to escape the F-A12 refusal above.
-  if (!owner || role !== 'authenticated' || distinctCheck) parts.push(`role: '${role}'`);
+  if (!owner || role !== 'authenticated' || distinctCheck) parts.push(`role: ${tsString(role)}`);
   if (owner) {
     parts.push(`owner: '${modelFieldKey(owner.column)}'`);
     if (owner.claim !== 'sub') parts.push(`userField: '${owner.claim}'`);
@@ -422,10 +462,139 @@ function renderColumnAbility(
       notes.push(`    ${policy.check}`);
     }
   }
-  parts.push(`columns: [${columns.map((column) => `'${modelFieldKey(column)}'`).join(', ')}]`);
+  parts.push(`columns: [${columns.map((column) => tsString(modelFieldKey(column))).join(', ')}]`);
   return `can('${action}', { ${parts.join(', ')} })`;
 }
 
+/**
+ * A named owner read emits both SELECT policies. Recover that declaration only when
+ * the complete pair agrees. Differing rules remain two reads; unsupported pairs refuse.
+ */
+function deriveOwnerReadPair(contract: TableContract): string[] | null {
+  const table = contract.table.split('.').pop()!;
+  const named = contract.policies.find(p => p.name === `${table}_select_authenticated`);
+  const own = contract.policies.find(p => p.name === `${table}_select_own`);
+  if (!named || !own) return null;
+
+  const refuse = (): never => {
+    throw new Error(`${contract.table}: owner-read pair cannot be represented faithfully; keep the live policies and normalize them before pulling.`);
+  };
+  const reads = policiesNaming(contract, 'authenticated', 'SELECT');
+  if (reads.length !== 2 || [named, own].some(p => p.command !== 'SELECT' || !p.permissive
+    || p.roles.length !== 1 || p.roles[0] !== 'authenticated' || p.check != null || p.using == null)) {
+    return refuse();
+  }
+  const namedPred = normalizeDeparsedExpr(named.using!);
+  const ownPred = normalizeDeparsedExpr(own.using!);
+  const exactOwner = parseOwnerPredicate(ownPred);
+  const split = splitOwnerPredicate(ownPred);
+  const owner = exactOwner ?? split.owner;
+  if (!owner) return refuse();
+  const parts = [`owner: '${modelFieldKey(owner.column)}'`];
+  if (owner.claim !== 'sub') parts.push(`userField: '${owner.claim}'`);
+  if (owner.expr) parts.push(`ownerExpr: sql\`${templateBody(owner.expr)}\``);
+  if (namedPred === ownPred && exactOwner) {
+    return [`can('read', { role: 'authenticated', ${parts.join(', ')} })`];
+  }
+  // A named SQL read does not inherit the model's owner gate. The own read does,
+  // so carry only its remaining guard there, avoiding a second copy of the gate.
+  return [
+    `can('read', { role: 'authenticated', sql: sql\`${templateBody(namedPred)}\` })`,
+    `can('read', { ${parts.join(', ')}, sql: sql\`${templateBody(split.guard ?? 'true')}\` })`,
+  ];
+}
+
+/**
+ * A GOVERNED custom role (`--govern-roles`) on a table with row security ON: each table-level
+ * CRUD grant renders as a role-scoped `can()` when exactly one permissive policy TO that role
+ * alone states its row rule in a spelling the compiler emits back unchanged.
+ *
+ * Why: governing a role reconciles its policies as well as its grants. Transcribing only the
+ * grants as `privileges` (all governing did before F4) declared no policy, so the next plan
+ * DROPPED every live policy TO the role. An ability declares the grant and the policy together.
+ *
+ * Exact or not at all. Each shape compiles back to the live rule, never to a wider one:
+ *   - manage: all four grants, ONE `FOR ALL` policy with USING `true` and WITH CHECK `true` or
+ *     none, and no per-command policy. Compiles to one ALL policy USING true WITH CHECK true.
+ *   - read / delete: the USING text rides verbatim as `sql:` (none when it is `true`).
+ *   - update: as read, and the WITH CHECK must be absent or equal to USING, because the
+ *     compiler sets WITH CHECK to the same predicate.
+ *   - create: the WITH CHECK must be exactly `true`.
+ * A policy with no USING (or an INSERT policy with no WITH CHECK) admits NO row. An ability
+ * without a predicate admits EVERY row, so that shape falls back like any other.
+ *
+ * Fallback: the grant stays a raw `privileges` entry (kept, never revoked) and a warning says
+ * why. A role with no policy of its own for a grant needs no warning: the raw grant is exact.
+ */
+function deriveGovernedRole(contract: TableContract, role: string): {
+  abilities: string[];
+  /** The CRUD privileges stated by an ability, so they are NOT also transcribed raw. */
+  asAbility: Set<string>;
+  /** The policies those abilities declare. */
+  usedPolicies: Set<string>;
+  warnings: string[];
+} {
+  const out = { abilities: [] as string[], asAbility: new Set<string>(), usedPolicies: new Set<string>(), warnings: [] as string[] };
+  if (!contract.rls.enabled) return out;
+  const own = (command: string): PolicyContract[] => contract.policies.filter(
+    (p) => p.permissive && p.roles.length === 1 && p.roles[0] === role && p.command === command,
+  );
+  const held = CRUD_PRIVS.filter((p) => granted(contract, role, p));
+  const fallback = (priv: string, why: string): void => {
+    out.warnings.push(`${contract.table}: --govern-roles ${role}: ${priv} is kept as privileges (a raw grant), not can() — ${why}.`);
+  };
+
+  const all = own('ALL');
+  if (all.length) {
+    const a = all[0];
+    if (all.length === 1 && held.length === CRUD_PRIVS.length && CRUD_PRIVS.every((c) => own(c).length === 0)
+      && a.using === 'true' && (a.check == null || a.check === 'true')) {
+      out.abilities.push(`can('manage', { role: ${tsString(role)} })`);
+      for (const p of CRUD_PRIVS) out.asAbility.add(p);
+      out.usedPolicies.add(a.name);
+      return out;
+    }
+    const names = all.map((p) => `"${p.name}"`).join(', ');
+    for (const priv of held) {
+      fallback(priv, `FOR ALL policy ${names} is not the plain manage shape (all four grants, one FOR ALL USING true, no per-command policy)`);
+    }
+    return out;
+  }
+
+  for (const priv of held) {
+    const pols = own(priv);
+    if (pols.length === 0) continue;
+    if (pols.length > 1) {
+      fallback(priv, `${pols.length} permissive ${priv} policies TO ${role} (${pols.map((p) => `"${p.name}"`).join(', ')}); can() states one`);
+      continue;
+    }
+    const p = pols[0];
+    if (priv === 'INSERT') {
+      if (p.check !== 'true') {
+        fallback(priv, p.check == null
+          ? `INSERT policy "${p.name}" has no WITH CHECK, so it admits no row; can('create') would admit every row`
+          : `INSERT policy "${p.name}" has WITH CHECK ${p.check}; can('create', { role }) states only WITH CHECK (true)`);
+        continue;
+      }
+      out.abilities.push(`can('create', { role: ${tsString(role)} })`);
+    } else {
+      if (p.using == null) {
+        fallback(priv, `${priv} policy "${p.name}" has no USING, so it admits no row; can('${DML[priv]}') would admit every row`);
+        continue;
+      }
+      if (priv === 'UPDATE' && p.check != null && p.check !== p.using) {
+        fallback(priv, `UPDATE policy "${p.name}": WITH CHECK differs from USING (USING ${p.using}; WITH CHECK ${p.check})`);
+        continue;
+      }
+      const frag = sqlFragment(p.using);
+      out.abilities.push(frag ? `can('${DML[priv]}', { role: ${tsString(role)}, sql: ${frag} })` : `can('${DML[priv]}', { role: ${tsString(role)} })`);
+    }
+    out.asAbility.add(priv);
+    out.usedPolicies.add(p.name);
+  }
+  return out;
+}
+
 /**
  * Derive the ability stanza for ONE table from its live contract.
  *
@@ -433,18 +602,25 @@ function renderColumnAbility(
  * 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.
+ * `governRoles` (db:pull --govern-roles) is the operator's EXPLICIT decision to GOVERN a foreign
+ * role, per the doctrine on GOVERNED_VOCABULARY. Never inferred: a re-pull must not silently
+ * convert a rendering decision into an access decision. Its grants and policies render as
+ * role-scoped `can()` where they pair exactly (see deriveGovernedRole), else as raw
+ * `privileges` with a warning. Complete-or-refuse where the model cannot keep live access:
+ * a column-scoped grant with no exactly-paired policy THROWS (the next plan would REVOKE it),
+ * and so does a RESTRICTIVE policy TO the role (the next plan would DROP it, a widening).
  */
 export function deriveAbilities(
   contract: TableContract,
   opts: { governRoles?: ReadonlySet<string> } = {},
 ): DerivedAbilities {
   const govern = opts.governRoles ?? new Set<string>();
+  // A role is a KEY in every accumulator below (and in the rendered `privileges`), and a key
+  // named __proto__ sets the prototype instead. Introspection keeps such a role (null-prototype
+  // maps), so a live grant to "__proto__" reaches here and the pull refuses, naming it.
+  for (const role of [...Object.keys(contract.grants), ...Object.keys(contract.columnGrants ?? {})]) {
+    refuseProtoKey(role, liveObject('role', role));
+  }
   /** One classification pass; every ability-vs-grant decision below reads this tag. */
   const abilitySurfaces = classifyAbilitySurfaces(contract);
   const isAbilitySurface = (role: string, priv: string): boolean => abilitySurfaces.has(`${role}:${priv}`);
@@ -505,6 +681,7 @@ export function deriveAbilities(
     notes.push(
       `  an ability: an ability would ADD the policy the database does not have.`,
     );
+    notes.push(...noRowPolicyNotes(contract, 'admin', adminDead));
   }
 
   // The same accounting for the app roles. A grant they hold with no policy behind it is
@@ -516,6 +693,7 @@ export function deriveAbilities(
     deadGrants[role] = dead;
     notes.push(`${role} holds ${dead.join(', ')} but no policy covers ${role} —`);
     notes.push(`  the grant is live in the catalog and gives no rows; declared as a grant, not an ability.`);
+    notes.push(...noRowPolicyNotes(contract, role, dead));
   }
 
   // --- policed but not granted at the table level ---------------------------------------
@@ -555,8 +733,11 @@ export function deriveAbilities(
   // not have. Same defect as the admin branch above; the round-trip gate found it here.
   const anonRead = isAbilitySurface('anon', 'SELECT');
   const authedRead = isAbilitySurface('authenticated', 'SELECT');
+  const ownerPair = !anonRead && authedRead ? deriveOwnerReadPair(contract) : null;
 
-  if (anonRead) {
+  if (ownerPair) {
+    abilities.push(...ownerPair);
+  } else if (anonRead) {
     // Public read. If the live policy narrows it (a soft-delete guard, a published flag),
     // carry that predicate — a public read with a filter is still a public read.
     const anonPol = policiesFor(contract, 'anon', 'SELECT')[0];
@@ -643,7 +824,7 @@ export function deriveAbilities(
       // DISCLOSURE, not refusal: `verbatim-sql:` is a stable marker so an adoption that
       // reached zero through escape hatches can be counted apart from one that reached zero
       // through vocabulary. Fidelity achieved is not expressiveness achieved.
-      abilities.push(`can('read', { role: 'authenticated', sql: sql\`${authedPred!.replace(/`/g, '\\`')}\` })`);
+      abilities.push(`can('read', { role: 'authenticated', sql: sql\`${templateBody(authedPred!)}\` })`);
       notes.push(
         `verbatim-sql: policy "${authedPol!.name}" (SELECT) grants authenticated MORE than the anon read.`,
       );
@@ -753,27 +934,74 @@ export function deriveAbilities(
   // exactly one permissive policy TO the same role proves the row gate. Anything else stays a
   // note: guessing the pairing could grant the right columns under the wrong row policy.
   const renderedColumnRoles = new Set<string>();
+
+  // --- custom roles the operator chose to GOVERN (--govern-roles): their row rules (F4) ---
+  const governedCustom = [...govern].filter((r) => !GOVERNED_VOCABULARY.has(r)).sort();
+  const governedAsAbility = new Map<string, Set<string>>();
+  const usedPolicies = new Set<string>();
+  const warnings: string[] = [];
+  for (const role of governedCustom) {
+    const g = deriveGovernedRole(contract, role);
+    abilities.push(...g.abilities);
+    warnings.push(...g.warnings);
+    governedAsAbility.set(role, g.asAbility);
+    for (const name of g.usedPolicies) usedPolicies.add(name);
+  }
+
   for (const grantee of Object.keys(contract.columnGrants ?? {}).sort()) {
     const byPriv = contract.columnGrants![grantee];
     if (govern.has(grantee)) {
+      // A governed role's column grant renders ONLY as an exact column ability: SELECT or
+      // UPDATE, row security on, exactly one permissive policy TO the role alone, and no
+      // table-level ability for the same privilege (two policies of one name would collide).
+      // `columns:` keeps it column-scoped; it never becomes a table-level grant.
+      // A paired policy with NO USING admits no row (PostgreSQL 16: a SELECT policy without
+      // USING, or an UPDATE policy with only a WITH CHECK); a column ability compiles USING (true),
+      // every row. `privileges` has no column axis, so there is no raw fallback that keeps the
+      // grant without widening it to the table: this refuses, as main did.
+      const tableLevel = governedAsAbility.get(grantee) ?? new Set<string>();
+      const noUsing: string[] = [];
+      const pairs = Object.keys(byPriv).sort().filter((priv) => (byPriv[priv] ?? []).length).map((priv) => {
+        const action = priv === 'SELECT' ? 'read' : priv === 'UPDATE' ? 'update' : null;
+        let policy = action && contract.rls.enabled && !tableLevel.has(priv) ? columnPolicyFor(contract, grantee, priv) : null;
+        if (policy && policy.using == null) {
+          noUsing.push(`its ${priv} policy "${policy.name}" has no USING, so it admits no row and a column ability would admit every row`);
+          policy = null;
+        }
+        return { policy, ability: action && policy ? renderColumnAbility(action, grantee, byPriv[priv]!, policy, notes) : null };
+      });
+      if (pairs.length && pairs.every((p) => p.ability)) {
+        for (const p of pairs) {
+          abilities.push(p.ability!);
+          usedPolicies.add(p.policy!.name);
+        }
+        renderedColumnRoles.add(grantee);
+        continue;
+      }
       // 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.
+      // has no column axis — 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.`,
+          `Governing a role reconciles ALL of its grants, and the model states a column-scoped grant only as a ` +
+          `column ability: SELECT or UPDATE, row security on, and exactly one permissive policy of that command ` +
+          `TO ${grantee} alone, with a USING. Without it the next plan would revoke the grant. ` +
+          `${noUsing.length ? `Here ${noUsing.join('; ')}. ` : ''}` +
+          `Add that policy or normalize the grant 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;
       const action = priv === 'SELECT' ? 'read' : priv === 'UPDATE' ? 'update' : null;
-      const policy = action ? columnPolicyFor(contract, grantee, priv) : null;
+      const paired = action ? columnPolicyFor(contract, grantee, priv) : null;
+      // The governed rule, here too: a paired policy with no USING admits no row, and a column
+      // ability compiles USING (true), every row. Not rendered; the note below names the policy.
+      const noUsing = paired && paired.using == null ? paired : null;
+      const policy = noUsing ? null : paired;
       const ability = action && policy ? renderColumnAbility(action, grantee, cols, policy, notes) : null;
       if (ability) {
         abilities.push(ability);
@@ -782,11 +1010,33 @@ export function deriveAbilities(
       }
       notes.push(`${grantee} holds a COLUMN-scoped ${priv} on ${cols.length} column(s): ${cols.join(', ')}.`);
       notes.push(
-        action
-          ? `  NOT rendered — it needs exactly one permissive ${priv} policy TO ${policyRoleForGrantee(grantee)}.`
-          : `  NOT rendered — the model supports column-scoped SELECT and UPDATE only.`,
+        noUsing
+          ? `  NOT rendered — its ${priv} policy "${noUsing.name}" has no USING, so it admits no row; a column ability would admit every row.`
+          : action
+            ? `  NOT rendered — it needs exactly one permissive ${priv} policy TO ${policyRoleForGrantee(grantee)}.`
+            : `  NOT rendered — the model supports column-scoped SELECT and UPDATE only.`,
+      );
+    }
+  }
+
+  // --- every policy TO a governed custom role is declared, warned, or refused -------------
+  // The plan reconciles a governed role's policies, so a policy no ability above declares is
+  // DROPPED. Dropping a permissive policy can only narrow, so it is a warning. Dropping a
+  // RESTRICTIVE one widens (it subtracts rows), and the model cannot declare one: refuse.
+  for (const p of contract.policies) {
+    const roles = p.roles.filter((r) => governedCustom.includes(r));
+    if (!roles.length || usedPolicies.has(p.name)) continue;
+    if (!p.permissive) {
+      throw new Error(
+        `${table}: --govern-roles ${roles.join(', ')} refused — RESTRICTIVE policy "${p.name}" (${p.command}) applies to it. ` +
+          `The model cannot declare a restrictive policy, so governing the role would make the next plan DROP it ` +
+          `and WIDEN the role's access. Leave the role ungoverned.`,
       );
     }
+    warnings.push(
+      `${table}: --govern-roles ${roles.join(', ')}: policy "${p.name}" (${p.command} TO ${p.roles.join(', ')}) is not ` +
+        `declared by the model; the next db:plan DROPS policy "${p.name}".`,
+    );
   }
 
   // --- roles the compiler has no vocabulary for ----------------------------------------
@@ -794,7 +1044,7 @@ export function deriveAbilities(
     (r) => !KNOWN_ROLES.has(r) && r !== 'PUBLIC' && r !== 'public' && !renderedColumnRoles.has(r) && !govern.has(r),
   );
 
-  if (!abilities.length && !notes.length && !unmappedRoles.length) {
+  if (!abilities.length && !notes.length && !unmappedRoles.length && !warnings.length) {
     notes.push(`no grants found — this table is internal (nothing reaches it through the data API).`);
   }
 
@@ -808,17 +1058,18 @@ export function deriveAbilities(
 
   // --- 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.
+  // Every grant an ability above did not state, 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();
+    const asAbility = governedAsAbility.get(role) ?? new Set<string>();
+    const held = (contract.grants[role] ?? []).filter((p) => !asAbility.has(p)).sort();
     if (held.length) privileges[role] = [...new Set([...(privileges[role] ?? []), ...held])].sort();
   }
 
-  return { abilities, notes, unmappedRoles, privileges };
+  return { abilities, notes, unmappedRoles, privileges, warnings };
 }
 
 /** An object key, quoted only when the role name is not a bare JS identifier. */
@@ -833,7 +1084,8 @@ export function renderDerivedAbilities(d: DerivedAbilities): string {
   // deparses a subquery across several lines. One `//` for the first line left the rest
   // as bare SQL in the middle of a TypeScript object — a generated file that would not
   // parse. Commenting per line here means no note, present or future, can do that.
-  for (const n of d.notes) for (const line of String(n).split('\n')) out.push(`  // ${line}`);
+  for (const n of d.notes) for (const line of commentLines(String(n))) out.push(`  // ${line}`);
+  for (const w of d.warnings) for (const line of commentLines(String(w))) out.push(`  // WARNING: ${line}`);
   if (d.abilities.length) {
     out.push(`  abilities: [${d.abilities.join(', ')}],`);
   } else {

package/src/cli/authz-reconcile.ts

@@ -118,15 +118,17 @@ export function carryUngovernedAuthz(
 ): TableContract {
   const foreign = (role: string): boolean => !isGoverned(governed, role);
 
-  const grants: Record<string, string[]> = { ...declared.grants };
+  // Null-prototype copies: a carried role is a live name, and `grants['__proto__'] = …` on a
+  // plain object would set the prototype and drop the grant from the predicted endpoint.
+  const grants: Record<string, string[]> = Object.assign(Object.create(null), declared.grants);
   for (const [role, privileges] of Object.entries(live.grants)) {
     if (foreign(role)) grants[role] = [...privileges];
   }
 
-  const columnGrants: Record<string, Record<string, string[]>> = { ...(declared.columnGrants ?? {}) };
+  const columnGrants: Record<string, Record<string, string[]>> = Object.assign(Object.create(null), declared.columnGrants);
   for (const [role, byPrivilege] of Object.entries(live.columnGrants ?? {})) {
     if (!foreign(role)) continue;
-    const kept: Record<string, string[]> = {};
+    const kept: Record<string, string[]> = Object.create(null);
     for (const [privilege, columns] of Object.entries(byPrivilege)) {
       const present = columns.filter((c) => presentColumns.has(c));
       if (present.length > 0) kept[privilege] = present;
@@ -296,7 +298,7 @@ function tableMap(c: AuthzContract): Map<string, TableContract> {
 export const SEQUENCE_PRIVILEGES_FOR_INSERT = ['USAGE'] as const;
 
 export function inheritedSequenceGrants(table: TableContract): Record<string, string[]> {
-  const out: Record<string, string[]> = {};
+  const out: Record<string, string[]> = Object.create(null); // keyed by a role name
   for (const [grantee, privileges] of Object.entries(table.grants)) {
     if (privileges.includes('INSERT')) out[grantee] = [...SEQUENCE_PRIVILEGES_FOR_INSERT];
   }

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

@@ -34,6 +34,7 @@ import type { ModelDescriptor, DerivedDescriptor } from '@everystack/model';
 import { compileDeclaredState } from '../declared-diff';
 import { compileMigration } from '../migration-compile';
 import { compileDrizzleSource } from '../schema-source';
+import { modelMapPath, renderModelMap } from '../model-map';
 import { currentGitRef } from '../state-apply';
 import { createDatabase, dropDatabase, buildIntoDatabase, withDatabase } from '../db-build';
 import { resolveModelsPath } from '../models-path';
@@ -115,6 +116,15 @@ export interface StaticCheckInput {
   /** Raw `db/authz-baseline.json`, or null when there is none. The ARTIFACT half of the
    *  ungoverned-grantee gate — see the check below for what it deliberately does not do. */
   baselineSource?: string | null;
+  /** Where the model map lives: beside `artifactPath` (model-map.ts `modelMapPath`). */
+  modelMapPath?: string;
+  /**
+   * The committed model map, read raw. null = no file there (a NOTE, like the schema artifact at
+   * its default path: an app that upgraded and has not run db:generate yet is not broken; the
+   * map's path is never named on its own, so its absence is never a claim that vanished).
+   * Absent (undefined) = the caller did not read it (older callers): no map finding at all.
+   */
+  modelMapSource?: string | null;
 }
 
 export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
@@ -303,6 +313,27 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
     });
   }
 
+  // F8 — the model map, the same regenerate-and-compare gate as the drizzle schema. Pure: the
+  // map is a function of the models, so nothing here reads a database (T2).
+  if (input.modelMapSource !== undefined) {
+    const mapPath = input.modelMapPath ?? modelMapPath(input.artifactPath);
+    if (input.modelMapSource === null) {
+      findings.push({
+        level: 'note',
+        area: 'artifact',
+        message: `no model map at ${mapPath} — nothing to match (\`everystack db:generate\` writes it beside the drizzle schema)`,
+      });
+    } else if (input.modelMapSource === renderModelMap(input.models)) {
+      findings.push({ level: 'ok', area: 'artifact', message: `${mapPath} matches regeneration byte-for-byte` });
+    } else {
+      findings.push({
+        level: 'fail',
+        area: 'artifact',
+        message: `${mapPath} does NOT match regeneration — the models moved without db:generate, or the artifact was hand-edited (generated artifacts are never edited). Run \`everystack db:generate\` (it rewrites the map from the models before it reads any database) and commit ${mapPath}.`,
+      });
+    }
+  }
+
   // B7 — db/sql is retired. Files still present would be silently unmanaged: fail
   // with the migration path. (Absence is the normal state; nothing to report.)
   if (input.sqlDirRetired) {
@@ -407,6 +438,14 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
   } catch {
     artifactSource = null;
   }
+  // F8 — the model map lives beside the drizzle schema, so it follows the same resolution.
+  const mapPath = modelMapPath(artifactPath);
+  let modelMapSource: string | null = null;
+  try {
+    modelMapSource = await fs.readFile(mapPath, 'utf8');
+  } catch {
+    modelMapSource = null;
+  }
   // B7 tombstone — a retired db/sql directory still carrying .sql files is a FAIL
   // finding (the message carries the migration path), never a silent skip. The retired
   // --sql-dir flag is itself a FAIL finding here (the sibling verbs refuse it outright);
@@ -438,6 +477,7 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
     sequences: declaredDb?.sequences, derived: declaredDb?.derived, derivedError,
     moduleModels: declaredDb?.models ?? null,
     baselineSource,
+    modelMapPath: mapPath, modelMapSource,
   });
   // Per-finding detail is the --verbose report. The quiet default answers the one question a
   // human asked — is anything pending? — and names the verb that shows it.

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

@@ -25,7 +25,8 @@ import { pathToFileURL } from 'node:url';
 import type { ModelDescriptor, Module } from '@everystack/model';
 import { linkModels } from '@everystack/model';
 import { introspectSchema } from '../schema-introspect';
-import { compileDrizzleSource } from '../schema-source';
+import { writeGeneratedArtifacts } from '../generated-artifacts';
+import { modelMapPath } from '../model-map';
 import { compileModuleMigration } from '../migration-compile';
 import { generateMigrationSql, unmodeledTables, formatMigrationFile, planMigrationFile, resolveSchemaOut, HELD_DROP_PREFIX, type Journal } from '../migration-generate';
 import { introspectContract, type QueryRunner, type AuthzContract } from '../authz-contract';
@@ -103,8 +104,8 @@ async function dbGenerateInit(modelsPath: string, migrationsDir: string, schemaO
   const models = modules.flatMap((m) => m.models);
   info(`${modules.length} module(s), ${models.length} model(s).`);
 
-  step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
-  await fs.writeFile(schemaOut, compileDrizzleSource(models, { derived: modules.flatMap((m) => m.derived) }), 'utf8');
+  step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)} and the model map → ${path.relative(process.cwd(), modelMapPath(schemaOut))}...`);
+  await writeGeneratedArtifacts(schemaOut, models, modules.flatMap((m) => m.derived));
 
   const statements = compileModuleMigration(modules);
 
@@ -252,13 +253,13 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
     models = await loadModels(modelsPath);
     declaredDb = await loadDeclaredDerived(flags.models);
     info(`${models.length} model(s).`);
-    // The drizzle runtime schema is a derived artifact — refresh it from the models
-    // every run (it needs no DB), so a relation-only change with no DDL diff still
-    // updates it. The drift-guard test asserts this file matches the models (and the
-    // typed derived relations — B6a). A dry run refreshes NOTHING — not even this.
+    // The drizzle runtime schema and the model map are derived artifacts — refresh them
+    // from the models every run (they need no DB), so a relation-only change with no DDL
+    // diff still updates them. db:check asserts both match the models byte for byte (the
+    // schema with the typed derived relations — B6a). A dry run refreshes NOTHING.
     if (!dryRun) {
-      step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)}...`);
-      await fs.writeFile(schemaOut, compileDrizzleSource(models, { derived: declaredDb?.derived }), 'utf8');
+      step(`Writing the drizzle schema → ${path.relative(process.cwd(), schemaOut)} and the model map → ${path.relative(process.cwd(), modelMapPath(schemaOut))}...`);
+      await writeGeneratedArtifacts(schemaOut, models, declaredDb?.derived);
     }
     const dbSource: DbSource = resolveDbSource(flags);
     if (apply && dbSource.kind !== 'url') {