@everystack/cli 0.4.55 → 0.4.57

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

@@ -279,9 +279,26 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     // work — say so on the review surface, where a human still reads it.
     if (plan.statements.length > 0) {
       const verdict = await verifyDescent(modelsPath, { snapshot, contract }, {});
-      if (verdict.status === 'diverged' || verdict.status === 'drift') {
-        warn(`descent: ${verdict.reason}`);
-        warn('db:apply from this checkout will refuse this plan — rebase first, then re-mint.');
+      // A switch, not an `if (diverged || drift)`. That form silently ignored every verdict
+      // it did not name, so `indeterminate` would have minted a plan with no warning at all
+      // and then been refused at apply time with no hint of why. Exhaustive here means a new
+      // verdict cannot be forgotten.
+      switch (verdict.status) {
+        case 'ok':
+        case 'fresh-target':
+        case 'no-git':
+          break;
+        case 'diverged':
+        case 'drift':
+          warn(`descent: ${verdict.reason}`);
+          warn('db:apply from this checkout will refuse this plan — rebase first, then re-mint.');
+          break;
+        case 'indeterminate':
+          // NOT "rebase first" — nothing is wrong with the checkout or the database. The
+          // search failed, so the rule is unproven either way.
+          warn(`descent: ${verdict.reason}`);
+          warn('db:apply from this checkout will refuse this plan until that search completes — re-mint and try again.');
+          break;
       }
     }
 

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).');
         }

package/src/cli/commands/security.ts

@@ -15,6 +15,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
   audit,
+  schemaDescriptorsFromContract,
   parseFunctionsFromSql,
   parseViewsAndGrantsFromSql,
   type Waivers,
@@ -28,6 +29,7 @@ import {
   catalogFunctionToDescriptor,
   catalogRelationToDescriptor,
 } from '../security-catalog.js';
+import { SCHEMA_ACL_SQL, parseSchemaAcl } from '../authz-contract.js';
 import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
@@ -116,11 +118,28 @@ export async function auditDeployedSql(
   step('Introspecting database catalog (functions + relations)...');
   const fnRows = await catalogQuery(region, opsFn, FUNCTIONS_SQL);
   const relRows = await catalogQuery(region, opsFn, RELATIONS_SQL);
+  // A10(ii) — the PRECONDITION leg. Unpinned SECDEF and owner-bypasses-RLS both describe the
+  // privileged CODE; neither says whether an attacker can plant something for it to resolve to.
+  // Only the catalog path can answer that, so the static path leaves `schemas` empty rather
+  // than report every schema as clean.
+  const aclRows = await catalogQuery(region, opsFn, SCHEMA_ACL_SQL);
 
   const functions: FunctionDescriptor[] = fnRows.map(catalogFunctionToDescriptor);
   const views: ViewDescriptor[] = relRows.map(catalogRelationToDescriptor);
-  info(`Catalog: ${functions.length} function(s), ${views.length} relation(s).`);
-  return audit(functions, views, waivers);
+  const schemaAcls: Record<string, Record<string, string[]>> = {};
+  for (const row of aclRows) {
+    schemaAcls[String(row.schema)] = parseSchemaAcl(row.acl == null ? '{}' : String(row.acl)) ?? {};
+  }
+  const schemas = schemaDescriptorsFromContract(
+    schemaAcls,
+    fnRows.map((r: any) => ({
+      name: `${r.schema}.${r.name}`,
+      securityDefiner: r.security_definer === true || r.security_definer === 't',
+      hasSearchPath: r.has_search_path === true || r.has_search_path === 't',
+    })),
+  );
+  info(`Catalog: ${functions.length} function(s), ${views.length} relation(s), ${schemas.length} schema(s).`);
+  return audit(functions, views, waivers, schemas);
 }
 
 async function catalogQuery(region: string, fn: string, sql: string): Promise<any[]> {
@@ -153,12 +172,14 @@ export function printReport(report: AuditReport, instrument: 'static' | 'catalog
   const reds = [
     ...report.functions.filter((f) => f.severity === 'red'),
     ...report.views.filter((v) => v.severity === 'red'),
+    ...report.schemas.filter((s) => s.severity === 'red'),
   ];
   const warns = [
     ...report.functions.filter((f) => f.severity === 'warn'),
     ...report.views.filter((v) => v.severity === 'warn'),
+    ...report.schemas.filter((s) => s.severity === 'warn'),
   ];
-  const waived = report.functions.filter((f) => f.waived);
+  const waived = [...report.functions.filter((f) => f.waived), ...report.schemas.filter((s) => s.waived)];
 
   if (reds.length > 0) {
     console.log('');

package/src/cli/db-build.ts

@@ -129,6 +129,19 @@ export async function buildIntoDatabase(
     for (const schema of [...new Set([...modelSchemas, ...derivedSchemas])].filter((s) => s && s !== 'public').sort()) {
       await runner(`CREATE SCHEMA IF NOT EXISTS "${schema}"`);
     }
+    // A10(i) — ASSERT the schema posture, do not inherit it.
+    //
+    // PG15 removed PUBLIC's CREATE on schema `public`; before that it was the default, and it
+    // still rides in with any pre-PG15 dump. So a database everystack BUILDS was hardened only
+    // by accident of the server version, while one it ADOPTS was not — and db:fingerprint
+    // reported MATCH across both. A security posture that depends on which major created the
+    // database is exactly the environmental dependence this class of defect is about.
+    //
+    // Safe here and ONLY here: db:build refuses a database that already holds objects, so there
+    // is nothing in `public` to strand. Bringing an ADOPTED database to this posture is a
+    // reviewable REVOKE the operator sees before it runs, never a silent side effect — some
+    // legacy apps do create objects in `public` at runtime.
+    await runner('REVOKE CREATE ON SCHEMA public FROM PUBLIC');
     const createdRoles = await ensureContractRoles(runner, models);
 
     // FUNCTIONS BEFORE STATE. An RLS policy's predicate is resolved when the policy is
@@ -170,12 +183,34 @@ export async function buildIntoDatabase(
         await runner('RESET check_function_bodies');
       }
     }
-    const run = await executeSync(runner, session, models, {
+    let run = await executeSync(runner, session, models, {
       declared: options.declared,
       sequences: options.sequences,
       actor: options.actor ?? 'db-build',
       gitRef: options.gitRef ?? null,
     });
+    // A12 — THE SECOND PASS, and it is inherent to building from nothing rather than a patch
+    // over one bug. `executeSync` is a single diff-and-verify: it reads the live authz contract,
+    // computes the delta, applies it. On a FROM-SCRATCH build some objects the authz layer must
+    // grant on do not exist at read time — most sharply the sequence behind a serial column,
+    // which our own CREATE TABLE makes moments later. So the first pass cannot see it, the
+    // sequence inheritance rule (A6) has nothing to grant on, and the build lands with a role
+    // that may INSERT into a table but cannot draw its sequence value.
+    //
+    // Caught by the round-trip oracle (B7), not by A6's own tests: the rule converges perfectly
+    // against an EXISTING database, which is what those tests exercise.
+    //
+    // Bounded at exactly one extra pass. The second read sees everything the first one created,
+    // so a third could only differ if the apply were non-convergent — and that is a real failure
+    // the `converged` bar must report, never something to loop away.
+    if (!run.converged) {
+      run = await executeSync(runner, session, models, {
+        declared: options.declared,
+        sequences: options.sequences,
+        actor: options.actor ?? 'db-build',
+        gitRef: options.gitRef ?? null,
+      });
+    }
     return {
       converged: run.converged,
       fingerprintMatch: run.fingerprintMatch,

package/src/cli/derived-apply.ts

@@ -106,19 +106,72 @@ export function ensureOrReplace(sql: string): string {
 const WITH_NO_DATA_RE = /WITH\s+NO\s+DATA\s*$/i;
 
 /**
- * An object's full creation SQL: the CREATE statement plus its attachments, in
- * source order. A matview whose source says `WITH NO DATA` gets a trailing
- * REFRESH: the reconciler dropped a populated matview to rebuild it, and
- * executing the source verbatim would leave it unpopulated — matching the
- * text but regressing the database. (Found by a consumer whose extracted
- * sources carry pg_dump's WITH NO DATA ordering.)
+ * How the applier enacts a declared owner. Chosen from the BUILDER, not from taste.
+ *
+ * `set-role` — run the CREATE as the owner. Works for any builder that can assume the role, and
+ * it is the only option for a non-superuser builder: PostgreSQL will not let it hand an object
+ * to somebody else. The cost is real, and it is borne by the role the feature exists to protect:
+ * the CREATE happens AS the owner, so the owner needs `CREATE` on the schema — and a
+ * deliberately-powerless operator role commonly has CREATE nowhere.
+ *
+ * `alter-owner` — create as the builder, then `ALTER … OWNER TO`. Available only to a SUPERUSER
+ * (or rds_superuser member), which needs neither membership in the owner nor CREATE for it, and
+ * can replace a function it does not own on the re-run. Measured on PG16.
+ *
+ * Getting this backwards is not cosmetic: forcing `set-role` on a superuser builder would demand
+ * a privilege expansion onto the very role that is supposed to hold none.
+ */
+export type OwnerApplyMode = 'set-role' | 'alter-owner';
+
+/**
+ * An object's full creation SQL: the CREATE statement plus its attachments, in source order. A
+ * matview whose source says `WITH NO DATA` gets a trailing REFRESH: the reconciler dropped a
+ * populated matview to rebuild it, and executing the source verbatim would leave it unpopulated
+ * — matching the text but regressing the database. (Found by a consumer whose extracted sources
+ * carry pg_dump's WITH NO DATA ordering.)
+ *
+ * A declared owner is enacted one of two ways; see {@link OwnerApplyMode} for which and why.
  */
-function objectSql(obj: SourceObject): string[] {
+function objectSql(obj: SourceObject, ownerMode: OwnerApplyMode = 'set-role'): string[] {
   const statements = [obj.sql, ...obj.attachments.map((a) => a.sql)];
   if (obj.kind === 'materialized view' && WITH_NO_DATA_RE.test(normalizeSql(obj.sql))) {
     statements.push(`REFRESH MATERIALIZED VIEW ${quoteQualified(obj.identity)}`);
   }
-  return statements;
+  if (!obj.owner) return statements;
+
+  if (ownerMode === 'alter-owner') {
+    // A superuser builder creates as itself and hands the object over. It needs no membership in
+    // the owner and no CREATE on the owner's behalf, so the owner role stays as powerless as it
+    // was designed to be — which is the whole point of naming it. The re-run is safe for the
+    // same reason: a superuser may CREATE OR REPLACE a function it does not own.
+    //
+    // The ALTER trails the attachments because a superuser can still make them either way, and
+    // "build it, then hand it over" is the order a reader expects.
+    return [...statements, `${ALTER_OWNER[obj.kind] ?? 'ALTER FUNCTION'} ${ownerTarget(obj)} OWNER TO ${obj.owner}`];
+  }
+
+  // Every other builder creates AS the owner. Measured on PG16: a non-superuser cannot give an
+  // object away, and once ownership has moved off the applying role the next `CREATE OR REPLACE`
+  // fails with "must be owner of function" — so the alter-after form would work exactly once and
+  // break every later reconcile. Creating under SET ROLE is correct by construction and stays
+  // correct on re-run.
+  //
+  // The attachments stay INSIDE the block: GRANT and COMMENT on a function require ownership, so
+  // once the function belongs to `owner` the applying role can no longer make them. RESET ROLE is
+  // last and unconditional — a leaked SET ROLE would silently re-own every object created after
+  // it. The role name is validated at declaration (defineFunction), never here.
+  return [`SET ROLE ${obj.owner}`, ...statements, 'RESET ROLE'];
+}
+
+const ALTER_OWNER: Record<string, string> = {
+  function: 'ALTER FUNCTION',
+  view: 'ALTER VIEW',
+  'materialized view': 'ALTER MATERIALIZED VIEW',
+};
+
+/** The `ALTER … OWNER TO` target. A function needs its argument types — the same rule as DROP. */
+function ownerTarget(obj: SourceObject): string {
+  return obj.kind === 'function' ? dropTarget('function', obj.identity) : quoteQualified(obj.identity);
 }
 
 /**
@@ -166,10 +219,22 @@ export function renderSetSearchPath(schemas: string[], local: boolean): string |
  *
  * `GRANT USAGE` rides along per schema (0a-bis mirrored), derived from the objects'
  * own grant attachments: a role granted SELECT on a matview in a non-public schema
- * cannot reach it without USAGE, so the object grant is dead without this. A PUBLIC
- * that appears only as explicitly-revoked gets nothing. Empty for all-public apps —
- * their apply stays byte-identical. Idempotent when the state layer already created
- * the schema (a model schema also carrying derived objects).
+ * cannot reach it without USAGE, so the object grant is dead without this. Empty for
+ * all-public apps — their apply stays byte-identical. Idempotent when the state layer
+ * already created the schema (a model schema also carrying derived objects).
+ *
+ * A13 — PUBLIC IS NEVER GRANTED SCHEMA USAGE HERE, and the reason is the distinction this
+ * codebase draws everywhere else: an ability is an intended audience, a privilege is a recorded
+ * fact. PostgreSQL grants every new function EXECUTE to PUBLIC, `db:pull` faithfully records
+ * that as `privileges: { PUBLIC: ['EXECUTE'] }` — and this pass used to read it as an audience
+ * and widen the SCHEMA to match. Caught by the round-trip oracle (B7): a schema whose original
+ * ACL gave PUBLIC nothing came back from a rebuild with `GRANT USAGE ON SCHEMA … TO PUBLIC`,
+ * turning an unreachable default grant into a reachable one. Recording a fact about one object
+ * must never widen a DIFFERENT object.
+ *
+ * The consequence is deliberate: a genuinely PUBLIC-callable function in a non-public schema
+ * needs schema USAGE, and that is now a decision someone DECLARES on the schema, not one this
+ * pass infers from a default nobody chose.
  */
 export function renderEnsureObjectSchemas(objects: SourceObject[]): string[] {
   const statements: string[] = [];
@@ -181,18 +246,184 @@ export function renderEnsureObjectSchemas(objects: SourceObject[]): string[] {
       if (o.schema !== schema) continue;
       const { grants } = parseGrantAttachments(o.attachments);
       for (const [role, privileges] of Object.entries(grants)) {
-        if (privileges.length > 0) roles.add(role);
+        // See A13 above: PUBLIC's presence here is a recorded default, never a declared
+        // audience, and widening the schema to match it is a real privilege escalation.
+        if (privileges.length > 0 && role.toUpperCase() !== 'PUBLIC') roles.add(role);
       }
     }
     if (roles.size > 0) {
-      const targets = [...roles].sort().map((r) => (r.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : r)).join(', ');
-      statements.push(`GRANT USAGE ON SCHEMA ${quoteIdent(schema)} TO ${targets}`);
+      statements.push(`GRANT USAGE ON SCHEMA ${quoteIdent(schema)} TO ${[...roles].sort().join(', ')}`);
     }
   }
   return statements;
 }
 
-export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[]): RenderedReconcile {
+// ---------------------------------------------------------------------------
+// Declared-owner preflight — the refusal that beats a raw Postgres error.
+// ---------------------------------------------------------------------------
+
+/** One declared owner and every schema the batch will create an object of theirs in. */
+export interface OwnerRequirement {
+  owner: string;
+  schemas: string[];
+}
+
+/**
+ * The declared owners this batch will actually enact, and where.
+ *
+ * Scoped to CREATE and REPLACE, because those are the actions that run under `SET ROLE`. A
+ * baseline, a prune or an unchanged object never assumes anyone's identity, so demanding its
+ * owner be assumable would refuse work the batch was never going to attempt. On a from-scratch
+ * build every object is created, so this set is every declared owner anyway.
+ */
+export function ownerRequirements(plan: ReconcilePlan, source: SourceObject[]): OwnerRequirement[] {
+  const srcById = new Map(source.map((o) => [o.identity, o]));
+  const byOwner = new Map<string, Set<string>>();
+  for (const action of plan.actions) {
+    if (action.action !== 'create' && action.action !== 'replace') continue;
+    const obj = srcById.get(action.identity);
+    if (!obj?.owner) continue;
+    (byOwner.get(obj.owner) ?? byOwner.set(obj.owner, new Set()).get(obj.owner)!).add(obj.schema);
+  }
+  return [...byOwner.entries()]
+    .map(([owner, schemas]) => ({ owner, schemas: [...schemas].sort() }))
+    .sort((a, b) => a.owner.localeCompare(b.owner));
+}
+
+/**
+ * ONE catalog read answering every question the preflight has, for every declared owner at once
+ * — so the refusal can name the COMPLETE list. A first-failure refusal makes the operator
+ * provision one role, re-run, and discover the next; the whole point is that they see the work.
+ *
+ * `has_schema_privilege` throws on a schema that does not exist, so the schema is LEFT JOINed
+ * and the privilege only evaluated when it is really there.
+ */
+export function ownerPreflightSql(requirements: OwnerRequirement[]): string {
+  const pairs = requirements.flatMap((r) => r.schemas.map((s) => `(${escapeLiteral(r.owner)}, ${escapeLiteral(s)})`));
+  return `
+WITH declared(owner_name, schema_name) AS (VALUES ${pairs.join(', ')})
+SELECT
+  CURRENT_USER AS builder,
+  -- Which mechanism the applier may use. A SUPERUSER (RDS: an rds_superuser member) can hand an
+  -- object to a role it is not a member of, so it creates as itself and ALTERs the owner —
+  -- demanding SET ROLE of it would force CREATE-on-schema onto the very role that is supposed to
+  -- hold none. Everyone else creates AS the owner. Same shape as security-catalog's rule.
+  (
+    SELECT b.rolsuper OR EXISTS (
+      SELECT 1 FROM pg_auth_members m JOIN pg_roles g ON g.oid = m.roleid
+      WHERE m.member = b.oid AND g.rolname = 'rds_superuser'
+    )
+    FROM pg_roles b WHERE b.rolname = CURRENT_USER
+  ) AS builder_is_superuser,
+  d.owner_name,
+  d.schema_name,
+  (r.oid IS NOT NULL) AS role_exists,
+  (n.oid IS NOT NULL) AS schema_exists,
+  r.rolsuper AS owner_is_superuser,
+  CASE WHEN r.oid IS NULL THEN NULL ELSE pg_has_role(CURRENT_USER, r.oid, 'SET') END AS can_set_role,
+  CASE WHEN r.oid IS NULL OR n.oid IS NULL THEN NULL
+       ELSE has_schema_privilege(r.oid, n.oid, 'CREATE') END AS owner_can_create
+FROM declared d
+LEFT JOIN pg_roles r ON r.rolname = d.owner_name
+LEFT JOIN pg_namespace n ON n.nspname = d.schema_name
+ORDER BY d.owner_name, d.schema_name
+`.trim();
+}
+
+export interface OwnerPreflightRow {
+  builder?: unknown;
+  builder_is_superuser?: unknown;
+  owner_name: string;
+  schema_name: string;
+  role_exists?: unknown;
+  schema_exists?: unknown;
+  owner_is_superuser?: unknown;
+  can_set_role?: unknown;
+  owner_can_create?: unknown;
+}
+
+const truthy = (v: unknown): boolean => v === true || v === 't' || v === 'true';
+
+/**
+ * The mechanism this builder may use, read off the same preflight rows.
+ *
+ * Defaults to `set-role` when the column is absent — an older caller or a fixture — because that
+ * is the mechanism that works for everyone. Guessing `alter-owner` for an unknown builder would
+ * emit an ALTER a non-superuser cannot run, and fail mid-batch.
+ */
+export function builderOwnerMode(rows: OwnerPreflightRow[]): OwnerApplyMode {
+  return rows.some((r) => truthy(r.builder_is_superuser)) ? 'alter-owner' : 'set-role';
+}
+
+/**
+ * The refusal text, or null when every declared owner is usable.
+ *
+ * Three ways a declared owner fails, all named at once with the exact statement that fixes each:
+ *
+ *   1. THE ROLE DOES NOT EXIST. The build refuses and does NOT create it. A role is
+ *      cluster-scoped and a security principal, and a principal invented by a tool cannot know
+ *      the design it stands in for — it would arrive with no memberships, no grants and no
+ *      review, wearing the name of something that was supposed to be deliberate.
+ *   2. THE BUILDER CANNOT ASSUME IT. The CREATE runs under `SET ROLE <owner>`, so membership
+ *      WITH SET TRUE is required. `WITH INHERIT FALSE` is part of the fix on purpose: it lets
+ *      the builder become the owner without silently inheriting the owner's privileges.
+ *   3. THE OWNER CANNOT CREATE IN THE SCHEMA. Same mechanism — the CREATE happens AS the owner,
+ *      so the owner needs CREATE on the schema the object lives in. A schema that does not exist
+ *      yet counts: this build creates it as the BUILDER, and the owner will not hold CREATE on it.
+ */
+export function ownerPreflightRefusal(rows: OwnerPreflightRow[]): string | null {
+  const builder = rows.find((r) => r.builder != null)?.builder;
+  const builderName = builder == null ? 'the connecting role' : String(builder);
+  const missing = new Set<string>();
+  const unassumable = new Set<string>();
+  const noCreate: Array<{ owner: string; schema: string; exists: boolean }> = [];
+
+  // A superuser builder creates as itself and ALTERs the owner, so it needs neither membership in
+  // the owner nor CREATE on the owner's behalf. Refusing on either would be a false refusal that
+  // demands a privilege expansion onto a role designed to hold none. Only "the role must exist"
+  // survives, because no mechanism can hand an object to a principal that is not there.
+  const alterOwner = builderOwnerMode(rows) === 'alter-owner';
+
+  for (const row of rows) {
+    const owner = String(row.owner_name);
+    if (!truthy(row.role_exists)) { missing.add(owner); continue; }
+    if (alterOwner) continue;
+    if (!truthy(row.can_set_role)) unassumable.add(owner);
+    // A superuser owner holds CREATE everywhere, including in a schema this build is about to
+    // make — there is nothing to refuse.
+    if (truthy(row.owner_is_superuser)) continue;
+    if (!truthy(row.schema_exists)) noCreate.push({ owner, schema: String(row.schema_name), exists: false });
+    else if (!truthy(row.owner_can_create)) noCreate.push({ owner, schema: String(row.schema_name), exists: true });
+  }
+
+  if (!missing.size && !unassumable.size && !noCreate.length) return null;
+
+  const lines: string[] = [
+    `declared function owner(s) cannot be enacted by '${builderName}' — refused before any DDL, so nothing is half-applied:`,
+  ];
+  for (const owner of [...missing].sort()) {
+    lines.push(
+      `  NO SUCH ROLE  '${owner}' does not exist in this cluster. The build will not create it —`,
+      `      a role is a security principal, and one invented by a tool arrives with no memberships,`,
+      `      no grants and no review. Provision it, then re-run:  CREATE ROLE ${owner} NOLOGIN;`,
+    );
+  }
+  for (const owner of [...unassumable].sort()) {
+    lines.push(
+      `  CANNOT SET ROLE  '${builderName}' cannot assume '${owner}'. The CREATE runs as the owner:`,
+      `      GRANT ${owner} TO ${builderName} WITH INHERIT FALSE, SET TRUE;`,
+    );
+  }
+  for (const { owner, schema, exists } of noCreate) {
+    lines.push(
+      `  NO CREATE ON SCHEMA  '${owner}' cannot create in schema "${schema}"${exists ? '' : ' (which this build creates as the builder)'}:`,
+      `      GRANT CREATE ON SCHEMA ${schema} TO ${owner};`,
+    );
+  }
+  return lines.join('\n');
+}
+
+export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[], ownerMode: OwnerApplyMode = 'set-role'): RenderedReconcile {
   const srcById = new Map(source.map((o) => [o.identity, o]));
   const statements: string[] = [];
   const record: string[] = [];
@@ -214,14 +445,14 @@ export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[]):
       case 'replace': {
         const obj = srcById.get(action.identity);
         if (!obj) throw new Error(`replace action for ${action.identity} has no source object`);
-        statements.push(...objectSql(obj).map(ensureOrReplace));
+        statements.push(...objectSql(obj, ownerMode).map(ensureOrReplace));
         record.push(action.identity);
         break;
       }
       case 'create': {
         const obj = srcById.get(action.identity);
         if (!obj) throw new Error(`create action for ${action.identity} has no source object`);
-        statements.push(...objectSql(obj));
+        statements.push(...objectSql(obj, ownerMode));
         record.push(action.identity);
         break;
       }