@everystack/cli 0.4.99 → 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/catalog-rename.ts

@@ -0,0 +1,115 @@
+/**
+ * catalog-rename — the catalog-only renames the planner emits, their parser, and the verdict
+ * db:apply reads from them.
+ *
+ * A rename of a check, a foreign key or an index changes no fingerprint: a check is hashed by its
+ * predicate and an index or key by its content. So a plan whose ONLY change is such a rename has
+ * from == to == live, and the endpoint cannot tell a rename that ran from one that did not. The
+ * live names can. The renderer and the parser live side by side here so they cannot drift; the
+ * parser accepts exactly what the renderer writes and nothing else.
+ */
+
+import type { SchemaSnapshot } from './schema-introspect';
+import { isPureComment } from './sql-statement';
+
+/** The same quoting schema-diff uses for every identifier it emits. */
+const quote = (name: string): string => `"${name}"`;
+
+/** `public.orders` → `public.`; an unqualified table carries no qualifier. */
+const schemaPrefix = (table: string): string => (table.includes('.') ? `${table.split('.')[0]}.` : '');
+
+export interface RenameChange {
+  /** Schema-qualified, as the snapshot spells it (`public.orders`). */
+  table: string;
+  from: string;
+  to: string;
+}
+
+/** `ALTER TABLE … RENAME CONSTRAINT` — catalog-only and instant; the constraint keeps its identity. */
+export function renderConstraintRename(change: RenameChange): string {
+  return `ALTER TABLE ${change.table} RENAME CONSTRAINT ${quote(change.from)} TO ${quote(change.to)};`;
+}
+
+/** `ALTER INDEX … RENAME TO` — no rebuild. The schema qualifies the OLD name only. */
+export function renderIndexRename(change: RenameChange): string {
+  return `ALTER INDEX ${schemaPrefix(change.table)}${quote(change.from)} RENAME TO ${quote(change.to)};`;
+}
+
+export type CatalogRename =
+  | { kind: 'constraint'; table: string; from: string; to: string }
+  /** ALTER INDEX names no table — an index name is unique within its schema, so the schema is the scope. */
+  | { kind: 'index'; schema: string; from: string; to: string };
+
+const IDENT = '"([^"]*)"';
+const CONSTRAINT_RE = new RegExp(`^ALTER TABLE (\\S+) RENAME CONSTRAINT ${IDENT} TO ${IDENT};$`);
+const INDEX_RE = new RegExp(`^ALTER INDEX (?:([^\\s."]+)\\.)?${IDENT} RENAME TO ${IDENT};$`);
+
+/** The rename a statement is, if it is exactly one the renderers above produce; otherwise null. */
+export function parseCatalogRename(sql: string): CatalogRename | null {
+  const c = CONSTRAINT_RE.exec(sql);
+  if (c) return { kind: 'constraint', table: c[1], from: c[2], to: c[3] };
+  const i = INDEX_RE.exec(sql);
+  // An unqualified ALTER INDEX resolves through search_path; the renderer only writes one for an
+  // unqualified table, which the snapshot spells as `public`.
+  if (i) return { kind: 'index', schema: i[1] ?? 'public', from: i[2], to: i[3] };
+  return null;
+}
+
+export type RenameEdgeVerdict =
+  /** Empty, or some statement is not a recognized rename — the names have nothing to say. */
+  | { verdict: 'not-renames' }
+  /** Every rename already landed: `to` present, `from` absent. */
+  | { verdict: 'settled' }
+  /** No rename has landed: `from` present, `to` absent. The edge still has to run. */
+  | { verdict: 'unsettled' }
+  /** Anything else — the plan describes neither the database before it nor after it. */
+  | { verdict: 'stale'; reason: string };
+
+/**
+ * Where each rename in the edge stands in the BEFORE snapshot (the one the lock was computed
+ * from). Only an edge made entirely of recognized renames gets a verdict other than
+ * `not-renames`; one rename in an odd state, or a mix of landed and not, makes the plan stale.
+ */
+export function renameEdgeVerdict(statements: readonly string[], before: SchemaSnapshot): RenameEdgeVerdict {
+  // A comment is never run, and the planner writes them beside real changes (an inert
+  // renamedFrom notice, a held drop). They must not hide a rename edge from the names.
+  const real = statements.filter((sql) => !isPureComment(sql));
+  if (real.length === 0) return { verdict: 'not-renames' };
+  const renames: CatalogRename[] = [];
+  for (const sql of real) {
+    const rename = parseCatalogRename(sql);
+    if (!rename) return { verdict: 'not-renames' };
+    renames.push(rename);
+  }
+
+  const settled: string[] = [];
+  const unsettled: string[] = [];
+  for (const rename of renames) {
+    let present: Set<string>;
+    let where: string;
+    if (rename.kind === 'constraint') {
+      const table = before.tables.find((t) => t.table === rename.table);
+      if (!table) return { verdict: 'stale', reason: `table ${rename.table} does not exist` };
+      present = new Set([...table.checks, ...table.foreignKeys, ...table.uniques].map((c) => c.name));
+      where = `on ${rename.table}`;
+    } else {
+      present = new Set(before.tables
+        .filter((t) => t.table.startsWith(`${rename.schema}.`))
+        .flatMap((t) => t.indexes.map((ix) => ix.name)));
+      where = `in schema ${rename.schema}`;
+    }
+    const hasFrom = present.has(rename.from);
+    const hasTo = present.has(rename.to);
+    const label = `"${rename.from}" → "${rename.to}"`;
+    if (hasTo && !hasFrom) settled.push(label);
+    else if (hasFrom && !hasTo) unsettled.push(label);
+    else if (hasFrom && hasTo) return { verdict: 'stale', reason: `both "${rename.from}" and "${rename.to}" exist ${where}` };
+    else return { verdict: 'stale', reason: `neither "${rename.from}" nor "${rename.to}" exists ${where}` };
+  }
+  if (unsettled.length === 0) return { verdict: 'settled' };
+  if (settled.length === 0) return { verdict: 'unsettled' };
+  return {
+    verdict: 'stale',
+    reason: `some of its renames are already applied (${settled.join(', ')}) and some are not (${unsettled.join(', ')})`,
+  };
+}