@everystack/cli 0.4.53 → 0.4.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.53",
+  "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",
@@ -164,6 +164,7 @@
   "scripts": {
     "test": "jest",
     "build": "tsc --build",
-    "lint": "tsc --noEmit"
+    "lint": "tsc --noEmit",
+    "check:artifact": "tsx scripts/check-generated-artifact.ts"
   }
 }

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-build.ts

@@ -0,0 +1,153 @@
+/**
+ * `everystack db:build --database-url <url>` — build a database FROM the models, and KEEP it.
+ *
+ *   db:build --database-url postgres://…/mydb [--models db/models]
+ *
+ * WHY THIS EXISTS. Deleting a migration folder is only safe once the models alone can rebuild
+ * an identical database — local dev, the test DB, a new stage. Every other verb failed that:
+ * `db:check` proved buildability on an ephemeral database and then DROPPED it, while
+ * `db:sync` / `db:generate --apply` run the DIFF builder, which has no bootstrap phase and
+ * cannot start from nothing. A consumer tested our own documentation sentence ("a fresh
+ * database is db:check's compose") and found no verb behind it. This is that verb.
+ *
+ * It is deliberately THIN: `buildIntoDatabase` is the same core `db:check`'s compose, the dev
+ * template and `createEphemeralDatabase` already run — extensions, schemas, contract roles,
+ * declared functions before the policies that call them, then state and the derived layer.
+ * A second implementation of that ordering would be a second thing to keep true.
+ *
+ * The venue is EXPLICIT (`--database-url` only, never the ambient env, same rule as db:swap
+ * and db:export): this command writes a whole schema, so the target must be named on the
+ * command line and never inherited from a shell that happens to point at production.
+ *
+ * It REFUSES a database that already holds declared objects. Building into an existing
+ * database is `db:sync`'s job (dev) or `db:plan`/`db:apply`'s (a stage); a verb that silently
+ * did both is how a populated database gets clobbered by a command whose name says "build".
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import { buildIntoDatabase } from '../db-build.js';
+import { createUrlRunner } from '../db-source.js';
+import { resolveModelsPath } from '../models-path.js';
+import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived.js';
+import { loadModels } from './db-generate.js';
+import { currentGitRef } from '../state-apply.js';
+import { step, info, success, fail, warn } from '../output.js';
+
+/** Tables already in the target, outside the schemas PostgreSQL owns. */
+const OCCUPANCY_SQL = `
+SELECT n.nspname || '.' || c.relname AS identity
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relkind IN ('r', 'v', 'm')
+  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+ORDER BY 1
+LIMIT 20;
+`.trim();
+
+export async function dbBuildCommand(flags: Record<string, string>): Promise<void> {
+  // Flag-only venue. The env is never consulted: `db:build` writes a whole schema, and an
+  // ambient DATABASE_URL must not be able to choose which database that happens to.
+  const url = flags['database-url'];
+  if (!url || url === 'true') {
+    fail('db:build needs --database-url <url> — the venue is explicit by design (the ambient environment never picks the target for a command that writes a whole schema).');
+    process.exit(1);
+  }
+  if (flags.stage) {
+    fail('db:build has no --stage lane: building a fresh database is a local/dev operation. Evolve a deployed stage with db:plan → db:apply.');
+    process.exit(1);
+  }
+
+  const modelsPath = resolveModelsPath(flags.models);
+  let models: ModelDescriptor[];
+  try {
+    step(`Loading models from ${modelsPath}...`);
+    models = await loadModels(modelsPath);
+    info(`${models.length} model(s).`);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  try {
+    if (flags['sql-dir']) {
+      fail(await retiredSqlDirFlagRefusal(flags['sql-dir']));
+      process.exit(1);
+    }
+    const retired = await retiredSqlDirAnywhere(flags.models);
+    if (retired) {
+      fail(retired);
+      process.exit(1);
+    }
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  // The modules carry what `models` alone cannot: the derived layer, standalone sequences,
+  // and the extensions whose types the columns are declared in.
+  let declaredDb: DeclaredDerived | null = null;
+  try {
+    declaredDb = await loadDeclaredDerived(flags.models);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  // Refuse a target that already holds objects — see the header. Read on its own connection,
+  // closed before the build opens its own, so no session outlives the check it performed.
+  try {
+    const { runner, end } = await createUrlRunner(url);
+    let occupied: string[];
+    try {
+      occupied = (await runner(OCCUPANCY_SQL)).map((r: any) => String(r.identity));
+    } finally {
+      await end?.();
+    }
+    if (occupied.length > 0) {
+      fail(
+        `db:build refuses a database that already holds objects — it found ${occupied.length}: ${occupied.slice(0, 8).join(', ')}${occupied.length > 8 ? ', …' : ''}.\n`
+        + `  This verb builds a FRESH database from the models. To evolve an existing one: db:sync (a dev database) or db:plan → db:apply (a stage).`,
+      );
+      process.exit(1);
+    }
+  } catch (err: any) {
+    fail(`Could not read the target: ${err.message}`);
+    process.exit(1);
+  }
+
+  step('Building the declared state (extensions → schemas → roles → functions → state → derived)...');
+  let built;
+  try {
+    built = await buildIntoDatabase(url, models, {
+      declared: declaredDb?.objects,
+      sequences: declaredDb?.sequences,
+      extensions: declaredDb?.extensions,
+      actor: process.env.USER ?? null,
+      gitRef: currentGitRef(),
+    });
+  } catch (err: any) {
+    fail(`Build failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  for (const line of built.report) info(line);
+  if (built.createdRoles.length) {
+    info(`Created ${built.createdRoles.length} contract role(s) (NOLOGIN, cluster-level): ${built.createdRoles.join(', ')}.`);
+  }
+
+  // The bar is the same one db:check reports, and it is stated as a fact or not at all:
+  // a database that did not land on the models' fingerprint is not the declared state,
+  // however few statements were left over.
+  if (!built.converged || !built.fingerprintMatch) {
+    fail(
+      `The database was built but does NOT match the declared state (fingerprint ${built.fingerprint.slice(0, 12)}). `
+      + `It is left in place for inspection — run db:generate --dry-run against it to see what differs.`,
+    );
+    process.exit(1);
+  }
+
+  success(`Built and kept — the database IS the declared state at ${built.fingerprint.slice(0, 12)}.`);
+  warn('Roles are cluster-level: a role this build created is visible to every database in the cluster.');
+  info('Verify independently: everystack db:fingerprint --database-url <url> (expect MATCH), db:reconcile --check.');
+}