@everystack/cli 0.4.55 → 0.4.56

package/package.json

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

package/src/cli/authz-contract.ts

@@ -265,6 +265,27 @@ export interface FunctionContract {
    * operator. Pinned search_path is necessary but not sufficient.
    */
   ownerBypassesRls?: boolean;
+  /**
+   * SUPERUSER (or rds_superuser member) specifically — DIFFED.
+   *
+   * A deliberately-scoped operator role is commonly BYPASSRLS by design, so
+   * `ownerBypassesRls` reads `true` both for that correct design and for a function left
+   * owned by whoever ran the build. Identical value, wildly different blast radius: a
+   * consumer with 60 correctly-owned SECDEF functions saw the same `true` they would see if
+   * every one of them had silently moved to a superuser. This separates the two, and it is
+   * portable — no role name is compared.
+   */
+  ownerIsSuperuser?: boolean;
+  /**
+   * The owning role's NAME — RECORDED AND RENDERED, NEVER DIFFED.
+   *
+   * The name legitimately differs between a dev machine, a deployed master and a normalized
+   * operator, so comparing it would false-fire on every environment — that is why it was
+   * originally left out entirely. But omitting it also left a reader unable to tell
+   * "owned by our scoped operator" from "owned by a superuser" at a glance. It is carried
+   * for reading; `ownerIsSuperuser` is what the gate compares.
+   */
+  owner?: string;
 }
 
 /** The whole contract: every table and every function, as introspected. */
@@ -280,6 +301,50 @@ export interface AuthzContract {
    * that as "unknown", never as "no grants".
    */
   schemaAcls?: Record<string, Record<string, string[]>>;
+  /**
+   * The sequences behind serial/identity columns, with their live ACLs.
+   *
+   * These are INVISIBLE to every other read here: `schema-introspect`'s SEQUENCES_SQL
+   * deliberately excludes column-owned sequences (they are an implementation detail of the
+   * column, not a declarable object), and GRANTS_SQL covers relkind r/v/m only. So nothing
+   * carried their privileges, and a role that could INSERT into a serial-PK table could not
+   * draw its sequence value: every INSERT failed `permission denied for sequence`.
+   *
+   * Absent means NOT MEASURED (older recorder, hand-built fixture) and must never be read as
+   * "no sequences" — the emitter skips the whole pass rather than plan revokes against a set
+   * it did not read.
+   */
+  sequenceGrants?: SequenceGrantContract[];
+}
+
+/**
+ * One serial/identity sequence and the privileges it actually holds.
+ *
+ * The sequence is not declared anywhere — there is no `sequence:` key in the model and nobody
+ * wants one. Its privileges are DERIVED: they follow the owning table's declared grants. So
+ * this carries the live half plus the ownership edge that says which table to derive from.
+ */
+export interface SequenceGrantContract {
+  /** `schema.sequence_name`. */
+  sequence: string;
+  /** `schema.table` of the column that owns it — whose grants this sequence inherits. */
+  table: string;
+  /** Grantee → sorted privileges (USAGE | SELECT | UPDATE). Owner excluded, as in GRANTS_SQL. */
+  grants: Record<string, string[]>;
+  /**
+   * The owning column is `GENERATED … AS IDENTITY`, not `serial` — and that changes who needs
+   * what. A serial column's value comes from a DEFAULT `nextval(...)` evaluated with the
+   * CALLER's privileges, so an INSERTing role must hold USAGE/SELECT/UPDATE on the sequence or
+   * every insert fails `permission denied for sequence`. An identity column's value is supplied
+   * by the system as part of the column definition; no caller privilege is consulted at all.
+   *
+   * Measured, not assumed: a role with INSERT on the table and NOTHING on the sequence inserts
+   * successfully into an identity table and fails on a serial one. So the A6 inheritance rule
+   * applies to serial sequences only — see `reconcileSequenceGrants`.
+   *
+   * Absent on a read that predates this field (treated as serial, the prior behaviour).
+   */
+  identity?: boolean;
 }
 
 export type PolicyCommand = 'ALL' | 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE';
@@ -430,6 +495,78 @@ export interface SchemaAclRow {
   acl: unknown;
 }
 
+/**
+ * The sequences behind serial/identity columns, with their owning table and their ACL.
+ *
+ * `pg_depend` with `deptype IN ('a','i')` and `refobjsubid > 0` is the column-ownership edge —
+ * the same predicate `schema-introspect`'s SEQUENCES_SQL uses to EXCLUDE these, inverted. 'a'
+ * is a serial's auto dependency, 'i' an identity column's internal one; both are "this sequence
+ * belongs to that column", and missing either would silently drop half the sequences.
+ *
+ * LEFT JOIN LATERAL, not CROSS JOIN: a sequence with a NULL acl (owner-only, the common case
+ * before this fix) must still come back as a row. Otherwise "no grants" and "no such sequence"
+ * would be the same answer, and the emitter could not tell an ungranted sequence from an
+ * unmeasured one. `grantee IS NULL` marks the no-ACL row; a real PUBLIC grant has grantee 0,
+ * which `aclexplode` reports and the CASE turns into the literal 'PUBLIC'.
+ */
+export const SEQUENCE_ACLS_SQL = `
+SELECT
+  n.nspname || '.' || c.relname AS sequence,
+  tn.nspname || '.' || t.relname AS "table",
+  CASE WHEN a.grantee IS NULL THEN NULL ELSE COALESCE(r.rolname, 'PUBLIC') END AS grantee,
+  a.privilege_type AS privilege,
+  -- 'i' = an IDENTITY column's internal dependency, 'a' = a serial's auto one. Carried, not
+  -- just filtered on, because the two need OPPOSITE treatment from the inheritance rule.
+  (d.deptype = 'i') AS is_identity
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+JOIN pg_depend d
+  ON d.classid = 'pg_class'::regclass AND d.objid = c.oid
+ AND d.deptype IN ('a', 'i') AND d.refobjsubid > 0
+JOIN pg_class t ON t.oid = d.refobjid
+JOIN pg_namespace tn ON tn.oid = t.relnamespace
+LEFT JOIN LATERAL aclexplode(c.relacl) a ON a.grantee <> c.relowner
+LEFT JOIN pg_roles r ON r.oid = a.grantee
+WHERE c.relkind = 'S'
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend e
+    WHERE e.objid = c.oid AND e.deptype = 'e'
+  )
+ORDER BY 1, 3, 4;
+`.trim();
+
+export interface SequenceAclRow {
+  sequence: string;
+  table: string;
+  /** NULL when the sequence has no ACL at all — the row still exists. */
+  grantee: unknown;
+  privilege: unknown;
+  /** `d.deptype = 'i'` — the owning column is an identity one. Absent on an older read. */
+  is_identity?: unknown;
+}
+
+/** Fold the per-privilege rows into one entry per sequence, grants sorted for stability. */
+export function assembleSequenceGrants(rows: readonly SequenceAclRow[]): SequenceGrantContract[] {
+  const bySequence = new Map<string, SequenceGrantContract>();
+  for (const row of rows) {
+    const entry = bySequence.get(row.sequence)
+      ?? {
+        sequence: row.sequence, table: row.table, grants: {} as Record<string, string[]>,
+        // Omitted rather than `false` on a serial sequence, so a contract read before this
+        // field existed and one read after compare structurally equal.
+        ...(truthy(row.is_identity) ? { identity: true } : {}),
+      };
+    if (row.grantee != null && row.privilege != null) {
+      const grantee = String(row.grantee);
+      entry.grants[grantee] = [...new Set([...(entry.grants[grantee] ?? []), String(row.privilege)])].sort();
+    }
+    bySequence.set(row.sequence, entry);
+  }
+  return [...bySequence.values()].sort((a, b) => a.sequence.localeCompare(b.sequence));
+}
+
 /** The two privileges a schema ACL can carry, in aclitem letter form. */
 const SCHEMA_PRIV_LETTERS: Record<string, string> = { U: 'USAGE', C: 'CREATE' };
 
@@ -615,8 +752,10 @@ export interface ContractRows {
   columnGrants?: ColumnGrantRow[];
   /** pg_namespace ACL rows (SCHEMA_ACL_SQL) — optional; absent means schema ACLs unknown. */
   schemaAcls?: SchemaAclRow[];
+  /** SEQUENCE_ACLS_SQL. Optional — absent means not measured, never "no sequences". */
+  sequenceAcls?: SequenceAclRow[];
   /** Already-mapped function descriptors (from security-catalog's FUNCTIONS_SQL). */
-  functions: { schema: string; name: string; securityDefiner: boolean; hasSearchPath: boolean; owner?: string; ownerBypassesRls?: boolean }[];
+  functions: { schema: string; name: string; securityDefiner: boolean; hasSearchPath: boolean; owner?: string; ownerBypassesRls?: boolean; ownerIsSuperuser?: boolean }[];
 }
 
 /**
@@ -673,6 +812,8 @@ export function assembleContract(rows: ContractRows): AuthzContract {
       securityDefiner: true,
       hasSearchPath: f.hasSearchPath,
       ...(f.ownerBypassesRls !== undefined ? { ownerBypassesRls: f.ownerBypassesRls } : {}),
+      ...(f.ownerIsSuperuser !== undefined ? { ownerIsSuperuser: f.ownerIsSuperuser } : {}),
+      ...(f.owner !== undefined ? { owner: f.owner } : {}),
     }))
     .sort((a, b) => a.name.localeCompare(b.name));
 
@@ -692,6 +833,8 @@ export function assembleContract(rows: ContractRows): AuthzContract {
     tables: [...tables.values()].sort((a, b) => a.table.localeCompare(b.table)),
     functions,
     ...(schemaAcls ? { schemaAcls } : {}),
+    // Same absent-means-unmeasured contract as schemaAcls above.
+    ...(rows.sequenceAcls ? { sequenceGrants: assembleSequenceGrants(rows.sequenceAcls) } : {}),
   };
 }
 
@@ -704,8 +847,8 @@ export async function introspectContract(
   // 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, schemaAcls, fnRows] = await session(
-    [RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, SCHEMA_ACL_SQL, functionsSql],
+  const [rls, policies, grants, columnGrants, schemaAcls, sequenceAcls, fnRows] = await session(
+    [RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, SCHEMA_ACL_SQL, SEQUENCE_ACLS_SQL, functionsSql],
     INTROSPECTION_SESSION,
   );
   return assembleContract({
@@ -714,6 +857,7 @@ export async function introspectContract(
     grants: grants as GrantRow[],
     columnGrants: columnGrants as ColumnGrantRow[],
     schemaAcls: schemaAcls as SchemaAclRow[],
+    sequenceAcls: sequenceAcls as SequenceAclRow[],
     functions: (fnRows as any[]).map(mapFunctionRow),
   });
 }
@@ -814,6 +958,14 @@ export function compareContracts(declared: AuthzContract, live: AuthzContract):
     if (d.ownerBypassesRls !== undefined && l.ownerBypassesRls !== undefined && d.ownerBypassesRls !== l.ownerBypassesRls) {
       findings.push({ subject: `fn:${name}`, kind: 'function', detail: `owner bypasses RLS: declared ${d.ownerBypassesRls}, live ${l.ownerBypassesRls}` });
     }
+    // The name is recorded but NEVER compared — it legitimately differs between a dev
+    // machine, a deployed master and a normalized operator, and diffing it would false-fire
+    // on every environment. This boolean is the portable half, and it is the one that
+    // separates a deliberately-scoped BYPASSRLS operator from a superuser: both read `true`
+    // for ownerBypassesRls, and only one of them is a catastrophe.
+    if (d.ownerIsSuperuser !== undefined && l.ownerIsSuperuser !== undefined && d.ownerIsSuperuser !== l.ownerIsSuperuser) {
+      findings.push({ subject: `fn:${name}`, kind: 'function', detail: `owner is SUPERUSER: declared ${d.ownerIsSuperuser}, live ${l.ownerIsSuperuser}${l.ownerIsSuperuser ? ` (live owner '${l.owner ?? 'unknown'}') — a SECURITY DEFINER function owned by a superuser runs above RLS as that superuser on every call` : ''}` });
+    }
   }
   for (const name of lFns.keys()) {
     if (!dFns.has(name)) {

package/src/cli/authz-reconcile.ts

@@ -15,7 +15,7 @@
  * this layer reconciles without a migration file (unlike the data layer).
  */
 
-import type { AuthzContract, TableContract, PolicyContract } from './authz-contract.js';
+import type { AuthzContract, TableContract, PolicyContract, SequenceGrantContract } from './authz-contract.js';
 import { effectivePolicyCheck, parenthesizeOnce, isPolicyDead, isPolicySubsumed } from './authz-contract.js';
 import { matchPolicies } from './authz-identity.js';
 import { quoteQualified } from './pg-ident.js';
@@ -118,6 +118,58 @@ export function renderGrantExemptions(exemptions: readonly GrantExemption[]): st
   return lines;
 }
 
+/** A grantee holding sequence privileges its table grants do not justify. */
+export interface VestigialSequenceGrant {
+  grantee: string;
+  /** The sequences it holds privileges on while holding no INSERT on their tables. */
+  sequences: string[];
+}
+
+/**
+ * Sequence grants with no corresponding INSERT — an ADVISORY, never a revoke.
+ *
+ * The shape a brownfield database arrives in: a blanket `GRANT USAGE ON ALL SEQUENCES IN
+ * SCHEMA public` sitting beside a blanket `GRANT SELECT ON ALL TABLES`, years old, granted
+ * to a role that can INSERT into nothing. One consumer had exactly this — `authenticated`
+ * holding USAGE on all 27 sequences with INSERT on zero tables — and it was the single
+ * divergence between their database and the inheritance rule.
+ *
+ * Reported rather than revoked, and the distinction is the whole point: the inheritance rule
+ * only ever ADDS what an INSERT needs, so a vestigial grant is untouched by reconciliation and
+ * would otherwise sit there unnoticed forever. Naming it lets the owner decide. Revoking it
+ * would be the tool making a security decision from an inference — the same move we refused for
+ * the invented search_path.
+ */
+export function vestigialSequenceGrants(live: AuthzContract): VestigialSequenceGrant[] {
+  if (!live.sequenceGrants) return []; // not measured
+  const insertsFor = new Map<string, Set<string>>();
+  for (const t of live.tables) {
+    for (const [grantee, privileges] of Object.entries(t.grants)) {
+      if (privileges.includes('INSERT')) {
+        (insertsFor.get(grantee) ?? insertsFor.set(grantee, new Set()).get(grantee)!).add(t.table);
+      }
+    }
+  }
+  const byGrantee = new Map<string, string[]>();
+  for (const seq of live.sequenceGrants) {
+    for (const grantee of Object.keys(seq.grants)) {
+      if (insertsFor.get(grantee)?.has(seq.table)) continue;
+      byGrantee.set(grantee, [...(byGrantee.get(grantee) ?? []), seq.sequence]);
+    }
+  }
+  return [...byGrantee.entries()]
+    .map(([grantee, sequences]) => ({ grantee, sequences: sequences.sort() }))
+    .sort((a, b) => a.grantee.localeCompare(b.grantee));
+}
+
+/** One line per grantee — the shared rendering, same idiom as renderGrantExemptions. */
+export function renderVestigialSequenceGrants(findings: readonly VestigialSequenceGrant[]): string[] {
+  return findings.map(({ grantee, sequences }) =>
+    `${grantee} holds privileges on ${sequences.length} sequence(s) but can INSERT into none of their tables — `
+    + `probably a vestigial blanket GRANT ... ON ALL SEQUENCES. Nothing revokes it (the inheritance rule only adds); `
+    + `review and revoke by hand if it is dead: ${sequences.slice(0, 6).join(', ')}${sequences.length > 6 ? `, +${sequences.length - 6} more` : ''}.`);
+}
+
 /** A USING/WITH CHECK clause expression, parenthesized exactly once. */
 const clause = parenthesizeOnce;
 
@@ -144,6 +196,91 @@ function tableMap(c: AuthzContract): Map<string, TableContract> {
   return new Map(c.tables.map((t) => [t.table, t]));
 }
 
+/**
+ * A6 — the privileges a SERIAL sequence INHERITS from its table's declared grants.
+ *
+ * SERIAL only. An identity column's sequence is exempt and is skipped before this is
+ * consulted — see `reconcileSequenceGrants` for the measurement and why it matters.
+ *
+ * A role that may INSERT into a table but cannot draw its sequence value is not a state anyone
+ * declares deliberately; it is a state that happens when nobody carries the privilege across.
+ * Measured on a consumer's database: every INSERT into a serial-PK table failed
+ * `permission denied for sequence`, and two of their 563 tests were exactly that.
+ *
+ * The rule is INSERT on the table → USAGE + SELECT + UPDATE on its sequence, and all three
+ * matter. USAGE alone permits `nextval`, but `setval` needs UPDATE and reading `last_value`
+ * needs SELECT, so the common `rU` shape breaks the moment anything reseeds the counter.
+ *
+ * Signed off after measurement, not assumed: the consumer checked every role against every
+ * serial/identity sequence and found zero cases of INSERT-without-sequence-USAGE and zero of
+ * USAGE-without-UPDATE, so this under-grants nobody. Their one divergence — `authenticated`
+ * holding USAGE on all 27 sequences while able to INSERT into none — was a vestigial 2023
+ * blanket grant they are revoking, so their database converges to this rule rather than the
+ * reverse. The pull ADVISORY names that shape wherever it appears.
+ *
+ * Derived, never declared: there is no `sequence:` key in the model and nobody wants one.
+ */
+export const SEQUENCE_PRIVILEGES_FOR_INSERT = ['SELECT', 'UPDATE', 'USAGE'] as const;
+
+export function inheritedSequenceGrants(table: TableContract): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const [grantee, privileges] of Object.entries(table.grants)) {
+    if (privileges.includes('INSERT')) out[grantee] = [...SEQUENCE_PRIVILEGES_FOR_INSERT];
+  }
+  return out;
+}
+
+/**
+ * Reconcile one table's SERIAL sequences against the grants they inherit. Identity sequences
+ * are read the same way but exempt from the rule — the skip below says why.
+ *
+ * Same per-grantee shape as `reconcileGrants`, and the same ungoverned-role exemption: a live
+ * grantee the declared authz does not govern is LEFT ALONE, because "no declaration" and "no
+ * privileges" are identical to a set difference, and treating them alike is what produced 32
+ * revokes against a brownfield adopter's migration role.
+ *
+ * The live side must have been READ for this to run at all. `sequenceGrants` absent means the
+ * recorder never looked, and planning revokes against a set nobody read is how a phantom
+ * statement gets minted on every run forever — a bug class that has already bitten this
+ * codebase twice.
+ */
+function reconcileSequenceGrants(
+  d: TableContract,
+  liveSequences: readonly SequenceGrantContract[],
+  out: string[],
+  governed: ReadonlySet<string>,
+): void {
+  const declared = inheritedSequenceGrants(d);
+  for (const seq of liveSequences) {
+    // An IDENTITY sequence inherits NOTHING, and is neither granted nor revoked here.
+    //
+    // The A6 rule exists because a serial column's value comes from a DEFAULT `nextval(...)`
+    // that Postgres evaluates with the CALLER's privileges — no sequence grant, no INSERT. An
+    // identity column's value is supplied by the system as part of the column definition and
+    // consults no caller privilege at all. Measured: a role holding INSERT on the table and
+    // NOTHING on the sequence inserts fine into an identity table and fails on a serial one.
+    //
+    // Applying the rule here was a real WIDENING, caught by the round-trip oracle the day
+    // identity columns became declarable: the rebuild handed an INSERTing role SELECT + UPDATE
+    // + USAGE — direct `setval` control of a surrogate key — that the original database never
+    // granted and never needed. Nothing is revoked either: a grant somebody made deliberately
+    // is not ours to remove, and no declaration says it should not be there.
+    if (seq.identity) continue;
+    const target = quoteQualified(seq.sequence);
+    const grantees = new Set([...Object.keys(declared), ...Object.keys(seq.grants)]);
+    for (const grantee of [...grantees].sort()) {
+      if (!isGoverned(governed, grantee)) continue;
+      const want = new Set(declared[grantee] ?? []);
+      const have = new Set(seq.grants[grantee] ?? []);
+      const role = grantee.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : grantee;
+      const toRevoke = [...have].filter((p) => !want.has(p)).sort();
+      const toGrant = [...want].filter((p) => !have.has(p)).sort();
+      if (toRevoke.length) out.push(`REVOKE ${toRevoke.join(', ')} ON SEQUENCE ${target} FROM ${role};`);
+      if (toGrant.length) out.push(`GRANT ${toGrant.join(', ')} ON SEQUENCE ${target} TO ${role};`);
+    }
+  }
+}
+
 /**
  * Emit the ordered SQL that transforms the live database into the declared
  * contract. Empty when they already match (the reconcile no-op). Order per table:
@@ -162,6 +299,12 @@ export function emitReconcileSql(
   // that passes nothing gets the safe-for-greenfield behaviour; a brownfield caller widens
   // it with the modules' declared governedRoles.
   const governed = opts.governedRoles ?? governedRoleSet(declared);
+  // Absent = the recorder never read sequences; skip the pass entirely rather than diff
+  // against a set nobody measured. Grouped once, not re-scanned per table.
+  const sequencesByTable = new Map<string, SequenceGrantContract[]>();
+  for (const seq of live.sequenceGrants ?? []) {
+    (sequencesByTable.get(seq.table) ?? sequencesByTable.set(seq.table, []).get(seq.table)!).push(seq);
+  }
 
   for (const d of declared.tables) {
     const l = lTables.get(d.table);
@@ -172,6 +315,8 @@ export function emitReconcileSql(
     reconcilePolicies(table, d, l, sql, governed);
     reconcileGrants(table, d, l, sql, governed);
     reconcileColumnGrants(table, d, l, sql, governed);
+    // A6: the sequences behind this table's SERIAL columns inherit its grants (identity ones do not).
+    reconcileSequenceGrants(d, sequencesByTable.get(d.table) ?? [], sql, governed);
   }
 
   return sql;

package/src/cli/authz-render.ts

@@ -231,15 +231,37 @@ export function renderContractMarkdown(contract: AuthzContract): string {
     lines.push('');
     lines.push('These run with their owner\'s privileges, **above row security** — their own bodies enforce access. Review each one deliberately. A missing `search_path` is a hijack vector; an owner that bypasses RLS (superuser / BYPASSRLS) makes the function run above RLS as that role — the maximum blast radius. `db:migrate` often leaves functions superuser-owned; normalize ownership to a non-superuser operator.');
     lines.push('');
-    const elevated = contract.functions.filter((f) => f.ownerBypassesRls);
+    // A correct design lights this whole report up: a deliberately-scoped operator is
+    // usually BYPASSRLS, so every SECDEF function it owns is "elevated". Splitting the
+    // superuser case out is what lets a reader tell correct from catastrophic at a glance —
+    // a consumer with 60 correctly-owned functions was reading the same warning they would
+    // have seen if all 60 had silently moved to a superuser.
+    // Three states, not two. `ownerIsSuperuser === undefined` means the contract predates
+    // the field — we do NOT know, and must not claim "non-superuser" for it.
+    const superuserOwned = contract.functions.filter((f) => f.ownerIsSuperuser === true);
+    const elevated = contract.functions.filter((f) => f.ownerBypassesRls && f.ownerIsSuperuser === false);
+    const unknownOwner = contract.functions.filter((f) => f.ownerBypassesRls && f.ownerIsSuperuser === undefined);
+    if (unknownOwner.length) {
+      lines.push(`> **⚠ ${unknownOwner.length} function(s) are owned by a role that bypasses RLS** — they run above row security regardless of \`search_path\`. Re-run \`db:authz:pull\` to record whether the owner is a SUPERUSER, which is the difference between a scoped operator and the maximum blast radius.`);
+      lines.push('');
+    }
+    if (superuserOwned.length) {
+      lines.push(`> **🛑 ${superuserOwned.length} function(s) are owned by a SUPERUSER** — each runs above row security as that superuser on every call. This is the maximum blast radius and is almost never intended; it is what \`db:migrate\` and a models-only build both leave behind by default. Normalize ownership to a scoped operator.`);
+      lines.push('');
+    }
     if (elevated.length) {
-      lines.push(`> **⚠ ${elevated.length} function(s) are owned by a role that bypasses RLS** — they run above row security regardless of \`search_path\`. Normalize their ownership.`);
+      lines.push(`> **⚠ ${elevated.length} function(s) are owned by a non-superuser role that bypasses RLS.** If that role is your intended scoped operator, this is expected and the bodies are what enforce access. Confirm the owner below is the role you meant.`);
       lines.push('');
     }
     for (const f of contract.functions) {
       const sp = f.hasSearchPath ? 'search_path pinned ✓' : '**search_path NOT pinned ⚠**';
-      const own = f.ownerBypassesRls ? ' · **owner bypasses RLS ⚠**' : '';
-      lines.push(`- \`${f.name}\` — ${sp}${own}`);
+      const owner = f.owner ? ` · owner \`${f.owner}\`` : '';
+      const own = f.ownerIsSuperuser === true
+        ? ' · **owned by SUPERUSER 🛑**'
+        : f.ownerBypassesRls
+          ? (f.ownerIsSuperuser === false ? ' · owner bypasses RLS' : ' · **owner bypasses RLS ⚠**')
+          : '';
+      lines.push(`- \`${f.name}\` — ${sp}${owner}${own}`);
     }
     lines.push('');
   }

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

@@ -47,6 +47,7 @@ import { findReadAuthzGaps, findNakedGrants } from '../authz-lint.js';
 import { parseBaseline, renderBaseline, BASELINE_FILE } from '../authz-baseline.js';
 import {
   findDerivedReadGaps, findSecdefExecuteGaps, findMatviewSnapshotWarnings, findPublicExecutableSecdef,
+  findUnpinnedDefiners,
 } from '../derived-lint.js';
 import { step, success, fail, info, warn } from '../output.js';
 
@@ -235,7 +236,9 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
     for (const gap of derivedGaps) {
       findings.push({ level: 'fail', area: 'authz', message: gap.message });
     }
-    for (const warning of [...findMatviewSnapshotWarnings(input.derived), ...findPublicExecutableSecdef(input.derived)]) {
+    // findUnpinnedDefiners is the advisory half of A3: db:pull stopped inventing a pin, so the
+    // opinion moved here. It SUGGESTS one and never applies it.
+    for (const warning of [...findMatviewSnapshotWarnings(input.derived), ...findPublicExecutableSecdef(input.derived), ...findUnpinnedDefiners(input.derived)]) {
       findings.push({ level: 'warn', area: 'authz', message: warning.message });
     }
     if (derivedGaps.length === 0) {

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

@@ -65,6 +65,8 @@ export async function computeFingerprintStatus(
   models: ModelDescriptor[] | null,
   sequences?: SequenceDescriptor[],
   governedExtras?: readonly string[],
+  /** Declared derived objects — used to drop the `function owner` rows that ARE fingerprinted. */
+  declaredDerived?: readonly { kind: string; identity: string; owner?: string }[],
 ): Promise<FingerprintStatus> {
   const snapshot = await introspectSchema(session);
   const contract = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
@@ -77,7 +79,16 @@ export async function computeFingerprintStatus(
   const governedRoles = models ? governedRolesForModels(models, governedExtras) : undefined;
   const governedLive = governedRoles ? governedLiveFingerprint(snapshot, contract, governedRoles) : undefined;
   const predicted = models ? predictLiveFingerprint(models, snapshot, contract, { governedRoles }) : undefined;
-  const unfingerprinted = mapUnfingerprintedRows(unfingerprintedRows as any[]);
+  // B5 — a declared owner IS hashed (derived-source prefixes it), so reporting it as
+  // unfingerprinted would be a false claim in the one report whose whole job is honesty about
+  // coverage. SQL cannot know what the models declare; the filter belongs here.
+  const ownerDeclared = new Set(
+    (declaredDerived ?? [])
+      .filter((o) => o.kind === 'function' && o.owner !== undefined)
+      .map((o) => o.identity.replace(/\(.*\)$/, '')),
+  );
+  const unfingerprinted = mapUnfingerprintedRows(unfingerprintedRows as any[])
+    .filter((u) => u.kind !== 'function owner' || !ownerDeclared.has(u.identity.split(' → ')[0]));
   return {
     live,
     ...(governedLive !== undefined ? { governedLive } : {}),
@@ -101,11 +112,14 @@ export async function dbFingerprintCommand(flags: Record<string, string>): Promi
   let models: ModelDescriptor[] | null = null;
   let sequences: SequenceDescriptor[] | undefined;
   let governedExtras: string[] | undefined;
+  let declaredDerived: readonly { kind: string; identity: string; owner?: string }[] | undefined;
   try {
     models = await loadModels(modelsPath);
     const declared = await loadDeclaredDerived(flags.models);
     sequences = declared?.sequences;
     governedExtras = declared?.governedRoles;
+    // B5 — needed to tell a function whose owner IS hashed (declared) from one whose is not.
+    declaredDerived = declared?.objects;
   } catch (err: any) {
     // Two very different situations used to land here identically.
     //
@@ -141,7 +155,7 @@ export async function dbFingerprintCommand(flags: Record<string, string>): Promi
   }
 
   try {
-    const status = await computeFingerprintStatus(session, models, sequences, governedExtras);
+    const status = await computeFingerprintStatus(session, models, sequences, governedExtras, declaredDerived);
 
     if (flags.json === 'true') {
       console.log(JSON.stringify(status, null, 2));

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

@@ -35,7 +35,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { introspectSchema, MATVIEW_COLUMNS_SQL, matviewColumnsByIdentity, type ColumnRow, type ColumnSchema } from '../schema-introspect.js';
 import { fingerprintLive } from '../schema-fingerprint.js';
-import { ungovernedGrants, ALWAYS_GOVERNED, type GrantExemption } from '../authz-reconcile.js';
+import { ungovernedGrants, vestigialSequenceGrants, renderVestigialSequenceGrants, ALWAYS_GOVERNED, type GrantExemption } from '../authz-reconcile.js';
 import { buildStageBaseline, mergeBaseline, readBaselineFile, writeBaselineFile, BASELINE_FILE } from '../authz-baseline.js';
 import { introspectDerived, type DerivedCatalog } from '../derived-introspect.js';
 import { introspectContract, type TableContract, type AuthzContract } from '../authz-contract.js';
@@ -235,6 +235,11 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       // 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]));
+      // A6's advisory. A blanket `GRANT USAGE ON ALL SEQUENCES` beside a blanket SELECT is a
+      // common brownfield shape, and the inheritance rule never touches it — the rule only ADDS
+      // what an INSERT needs — so it would sit unnoticed forever. Named, never revoked: revoking
+      // it would be the tool deciding a security property from an inference.
+      for (const line of renderVestigialSequenceGrants(vestigialSequenceGrants(contract))) caution(line);
       pulledFingerprint = fingerprintLive(current, contract).hash;
     }
     // --matviews-as-tables: the flip needs real fields — one extra catalog read for the

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

@@ -43,6 +43,11 @@ import {
   derivedSearchPath,
   renderSetSearchPath,
   renderEnsureObjectSchemas,
+  ownerRequirements,
+  ownerPreflightSql,
+  ownerPreflightRefusal,
+  builderOwnerMode,
+  type OwnerApplyMode,
   ENSURE_RECONCILER_SQL,
 } from '../derived-apply.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
@@ -78,6 +83,13 @@ export interface ReconcileRun {
   statements: string[];
   /** Why apply was refused, when it was. */
   refusal?: string;
+  /**
+   * Which mechanism enacted the declared owners, when any were enacted. Reported because the two
+   * make different demands of the operator: `set-role` needs membership plus CREATE-on-schema for
+   * the owner, `alter-owner` needs a superuser builder and nothing of the owner at all. An
+   * operator debugging a permission error should not have to guess which one ran.
+   */
+  ownerMode?: OwnerApplyMode;
 }
 
 /**
@@ -118,7 +130,10 @@ export async function executeReconcile(
   const live = await introspectDerived(session);
   const parsed = { objects: options.declared ?? [], warnings: [] as string[] };
   const plan = planReconcile(parsed, live, options);
-  const rendered = renderReconcileSql(plan, parsed.objects);
+  // Rendered with the mechanism that works for EVERY builder. The preflight below reads the
+  // catalog and re-renders if this builder can use the cheaper one; a plan that is never applied
+  // (or is refused) shows the conservative form, which is the honest default.
+  let rendered = renderReconcileSql(plan, parsed.objects);
 
   if (!options.apply) return { plan, applied: false, statements: rendered.statements };
 
@@ -138,6 +153,23 @@ export async function executeReconcile(
     return { plan, applied: false, statements: [] };
   }
 
+  // DECLARED-OWNER PREFLIGHT — the last thing before any DDL, bookkeeping included.
+  //
+  // Two jobs, one read. It refuses what this builder cannot enact, naming every owner at once
+  // rather than one per re-run, so the operator's first news is not a raw Postgres error from the
+  // middle of a batch. And it CHOOSES the mechanism: a superuser builder hands the object over
+  // with ALTER … OWNER TO, which asks nothing of the owner role; everyone else creates AS the
+  // owner, which needs membership and CREATE on the schema.
+  const requirements = ownerRequirements(plan, parsed.objects);
+  let ownerMode: OwnerApplyMode | undefined;
+  if (requirements.length > 0) {
+    const rows = (await runner(ownerPreflightSql(requirements))) as any[];
+    const refusal = ownerPreflightRefusal(rows);
+    if (refusal) return { plan, applied: false, statements: rendered.statements, refusal };
+    ownerMode = builderOwnerMode(rows);
+    if (ownerMode !== 'set-role') rendered = renderReconcileSql(plan, parsed.objects, ownerMode);
+  }
+
   const now = options.now ?? Date.now;
   await runner(ENSURE_RECONCILER_SQL.join(';\n'));
 
@@ -263,7 +295,7 @@ export async function executeReconcile(
     throw explainReconcileError(err);
   }
 
-  return { plan, applied: true, statements: rendered.statements };
+  return { plan, applied: true, statements: rendered.statements, ...(ownerMode ? { ownerMode } : {}) };
 }
 
 /**
@@ -520,6 +552,13 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
         fail(`not applied: ${run.refusal}`);
       } else if (run.applied) {
         success(`Applied ${run.statements.length} statement(s); provenance and schema_log recorded.`);
+        // Which ownership mechanism ran. The two make different demands, so an operator
+        // debugging a permission error should not have to guess which one they hit.
+        if (run.ownerMode === 'alter-owner') {
+          info('Declared owners applied with ALTER … OWNER TO (this builder is a superuser) — the owner roles needed no membership grant and no CREATE on their schemas.');
+        } else if (run.ownerMode === 'set-role') {
+          info('Declared owners applied under SET ROLE (this builder is not a superuser) — each owner must be assumable by the builder and hold CREATE on its schema.');
+        }
         if (run.plan.actions.some((a) => a.action === 'baseline')) {
           warn('baseline recorded trust WITHOUT verifying live matches source — on first contact it CANNOT compare a source hash to a live deparse, so it trusts your assertion, it does not check. If you need a guarantee that live == the declared source, drop the object and let reconcile recreate it (or --overwrite-drift when the plan reports drift).');
         }