@everystack/cli 0.4.53 → 0.4.56

package/src/cli/derived-lint.ts

@@ -233,6 +233,62 @@ export function findPublicExecutableSecdef(derived: readonly DerivedDescriptor[]
   return warnings;
 }
 
+// ---------------------------------------------------------------------------
+// Advisory: SECURITY DEFINER with no pin (db:check warn) — A3's linter half
+// ---------------------------------------------------------------------------
+
+export interface UnpinnedDefinerFinding extends DerivedAuthzGap {
+  /** The schemas the DECLARATION can justify, `pg_catalog` first. A floor to review — never applied. */
+  suggested: string[];
+}
+
+/**
+ * Every SECURITY DEFINER function that declares `searchPath: 'unpinned'`, with a SUGGESTED pin.
+ *
+ * This is the half of A3 that keeps the honesty from becoming permission. `db:pull` no longer
+ * invents `['pg_catalog']` for a function whose live `proconfig` is empty — inventing it was an
+ * outage that passed every gate, and fabrication corrodes fingerprint, plan and apply, all of
+ * which rest on the model telling the truth. So the parser records what is there and the
+ * OPINION lives here: an unpinned definer function is a real latent vulnerability, and it gets
+ * named on every run until someone decides about it.
+ *
+ * SUGGEST, never apply. The suggestion is derived from the DECLARED structure — the function's
+ * own schema plus the schemas of its `dependsOn` — and not from reading the body. Body-derived
+ * pins are inventing with extra steps: dynamic SQL, operators and casts defeat the parse, and a
+ * pin that is wrong in the tool's favour is the same failure mode with better intentions. The
+ * suggestion is a floor. The author reviews it and lands it themselves.
+ *
+ * WARN, not fail. On an adopted database this is a faithful report of what is already true, and
+ * failing CI on a faithful pull would make `db:pull` unusable on exactly the schemas it exists
+ * for. Same call, and the same reasoning, as findPublicExecutableSecdef above.
+ */
+export function findUnpinnedDefiners(derived: readonly DerivedDescriptor[]): UnpinnedDefinerFinding[] {
+  const findings: UnpinnedDefinerFinding[] = [];
+  for (const d of derived) {
+    if (d.kind !== 'function' || d.security !== 'definer' || d.searchPath !== 'unpinned') continue;
+    const identity = identityOf(d);
+    const schemas = new Set<string>([parseQualified(d.name).schema]);
+    for (const ref of d.dependsOn ?? []) {
+      schemas.add(isModelRef(ref) ? (ref.schema ?? 'public') : parseQualified(ref.name).schema);
+    }
+    // pg_catalog FIRST and always: it is what stops a caller shadowing a built-in the body
+    // calls unqualified, which is the whole attack this pin defends against.
+    const suggested = ['pg_catalog', ...[...schemas].filter((s) => s !== 'pg_catalog').sort()];
+    findings.push({
+      identity,
+      suggested,
+      message:
+        `${identity} is SECURITY DEFINER with NO search_path — declared 'unpinned', which is the truth about the `
+        + `database, not an approval. It runs with its owner's rights, and a caller controls the search_path, so an `
+        + `unqualified name in the body can be resolved to an object the caller planted. SUGGESTED pin from what the `
+        + `declaration references: searchPath: [${suggested.map((s) => `'${s}'`).join(', ')}]. That is a FLOOR derived `
+        + `from dependsOn, not from reading the body — dynamic SQL, operators and casts are invisible to it, so review `
+        + `it, extend it, and land it yourself. Nothing here is ever applied for you.`,
+    });
+  }
+  return findings;
+}
+
 // ---------------------------------------------------------------------------
 // Gate: matview snapshot over row-scoped sources (db:check warn)
 // ---------------------------------------------------------------------------

package/src/cli/derived-plan.ts

@@ -233,6 +233,30 @@ export function planReconcile(
   const sqlDrops = new Map<string, { dropSql: string; reason: string }>();
   const extraWarnings: string[] = [];
 
+  /**
+   * B2 — the declared `SET search_path` compared against the LIVE one, structurally.
+   *
+   * Every other comparison in this table is a hash against a RECORDED hash, which is why the
+   * pin could differ in silence: `--baseline` records the declared source hash beside the live
+   * def hash without ever comparing the two, so a model claiming `search_path=pg_catalog` about
+   * a database with no pin reads as up to date forever. Measured — `db:reconcile --check`
+   * returned zero actions and zero drift on exactly that state.
+   *
+   * This is the one comparison that reads both sides at once. Null when they agree, or when
+   * either side was not measured (a parser-era object with no declared pin, a pre-B5 catalog
+   * read with no structured fields) — absent evidence is not evidence.
+   */
+  const pinMismatch = (src: SourceObject, liveObj: LiveObject): string | null => {
+    if (src.kind !== 'function' || src.searchPath === undefined || !liveObj.fn) return null;
+    const tokens = (v: string | undefined): string[] =>
+      (v ?? '').split(',').map((s) => s.trim().replace(/^"|"$/g, '')).filter(Boolean);
+    const declared = src.searchPath === 'unpinned' ? [] : src.searchPath.map((s) => s.trim());
+    const livePin = tokens(liveObj.fn.searchPath);
+    if (declared.length === livePin.length && declared.every((s, i) => s === livePin[i])) return null;
+    const say = (p: string[]): string => (p.length ? `search_path = ${p.join(', ')}` : 'no search_path');
+    return `declared ${say(declared)}, live has ${say(livePin)} — replaced from source`;
+  };
+
   for (const src of source.objects) {
     // --only restricts the primary decisions to the named identities; the rest are left
     // untouched (they are not skips — they were never in scope, so they get no plan entry).
@@ -271,9 +295,16 @@ export function planReconcile(
       // (live deparse), so the reconciler can't verify live == source. --baseline trusts it,
       // --rebuild guarantees it by rebuilding from source (relations through the dependency graph
       // below; functions replace in place), and the default flags it for a decision.
+      const pin = pinMismatch(src, liveObj);
       if (options.rebuild) {
         if (isRelation(src.kind)) rebuild.set(src.identity, 'rebuilt from source (first contact, --rebuild)');
         else fnReplace.set(src.identity, 'replaced from source (first contact, --rebuild)');
+      } else if (pin) {
+        // --baseline asserts "live IS the source, trust me". Here we can PROVE it is not, so
+        // recording the assertion would bless the difference permanently — nothing downstream
+        // ever compares these two again. Converge instead, on every path: an object whose pin
+        // is measurably wrong is not unverifiable, it is verifiably different.
+        fnReplace.set(src.identity, `search_path differs from live: ${pin}`);
       } else if (options.baseline) {
         baseline.push(src.identity);
       } else {
@@ -341,6 +372,15 @@ export function planReconcile(
       else fnReplace.set(src.identity, 'source changed');
       continue;
     }
+    // Self-consistent provenance is not proof. A --baseline taken before B2, or a mistaken
+    // --rebaseline, records the declared source hash beside the live def hash without ever
+    // comparing them — so a declared pin the database does not have reads as up to date on
+    // every run. The structural read is what breaks that loop; it self-heals in one apply.
+    const pin = pinMismatch(src, liveObj);
+    if (pin) {
+      fnReplace.set(src.identity, `search_path differs from live: ${pin}`);
+      continue;
+    }
     // Up-to-date (src + live both match provenance). If provenance predates body_hash, record it
     // once — a record-only backfill that ARMS the authz-only fast path for a future grant change.
     // Converges: after this run the row has body_hash, so it skips cleanly next time.
@@ -430,8 +470,15 @@ export function planReconcile(
         );
       } else {
         const target = parsed.target ?? (src.kind === 'function' ? `FUNCTION ${src.identity}` : src.identity);
-        const statements = diffObjectGrants(target, parsed.grants, liveObj.grants);
+        // Functions carry ownership context; relations do not (relacl's NULL means owner-only
+        // and aclexplode(NULL) is empty, so a relation's grant set does not shift with its owner).
+        const owners = src.kind === 'function'
+          ? { ...(src.owner !== undefined ? { declared: src.owner } : {}), ...(liveObj.owner !== undefined ? { live: liveObj.owner } : {}) }
+          : undefined;
+        const { statements, suppressed } = diffObjectGrants(target, parsed.grants, liveObj.grants, owners);
         if (statements.length > 0) regrants.push({ identity: src.identity, statements });
+        // Never silent: a withheld revoke is reported every run until the owner is declared.
+        for (const note of suppressed) extraWarnings.push(note);
       }
     }
 

package/src/cli/derived-render.ts

@@ -208,6 +208,110 @@ function parseArgs(args: string): ParsedArg[] | null {
   return out;
 }
 
+/**
+ * The role-name shape `defineFunction` accepts (packages/model derived.ts OWNER_ROLE_NAME).
+ * The owner is interpolated into `SET ROLE` / `ALTER … OWNER TO`, so anything else is refused
+ * at declaration — which means rendering it here would emit source that throws on import.
+ */
+const RENDERABLE_ROLE = /^[a-z_][a-z0-9_]*$/;
+
+/**
+ * An object that RUNS AS ITS OWNER, and the sentence that says so.
+ *
+ * Two shapes qualify, and they are the same hazard one object apart: a `SECURITY DEFINER`
+ * function, and a view with `security_invoker = false`. For both, an owner nobody chose is a
+ * live privilege surface, so the FIXME is loud and the warning reaches stderr.
+ */
+export interface ElevatedRights {
+  /** How the object declares it — `'SECURITY DEFINER'`, `'not securityInvoker'`. */
+  posture: string;
+  /** What runs as the owner — `'Every call'`, `'Every read through it'`. */
+  what: string;
+}
+
+export const SECURITY_DEFINER_RIGHTS: ElevatedRights = { posture: 'SECURITY DEFINER', what: 'Every call' };
+export const DEFINER_VIEW_RIGHTS: ElevatedRights = { posture: 'not securityInvoker', what: 'Every read through it' };
+export const MATVIEW_RIGHTS: ElevatedRights = { posture: 'a materialized view', what: 'Every REFRESH' };
+
+/**
+ * What db:pull says about an object's OBSERVED owner: render it, or flag it.
+ *
+ * Ownership is a privilege boundary, so a pulled model that stays silent about it reproduces
+ * the wrong database. But rendering EVERY observed owner is worse than saying nothing: on a
+ * brownfield database most objects are owned by whoever ran the migration, and writing
+ * `owner: 'postgres'` into the models would BLESS that accident — converting an unreviewed
+ * superuser-owned SECURITY DEFINER function into fingerprinted, reproducible design.
+ *
+ * So the discriminator is the AMBIENT BUILD CREDENTIAL, two clauses and no more: the owner is
+ * a superuser, or it is the role this pull connected as. Neither → a deliberately chosen
+ * principal → render it. Either → a FIXME naming the observed owner, loud when the object runs
+ * as its owner. The defect stays visible without being ratified.
+ *
+ * This also settles the portability objection: the roles whose names legitimately differ
+ * between a dev machine, a deployed master and a normalized operator ARE the operator tier —
+ * exactly the tier this declines to render.
+ *
+ * A15 — ONE discriminator for functions AND relations. The rule is identical and the reason is
+ * identical; two copies of it is how the view half ends up subtly different from the function
+ * half, which is the defect this whole plan keeps finding.
+ */
+export function renderedOwner(
+  o: Pick<LiveObject, 'identity' | 'owner' | 'ownerIsSuperuser' | 'ownerIsConnectedRole'>,
+  elevated: ElevatedRights | null,
+): { prop?: string; fixme?: string; warning?: string } {
+  const owner = o.owner;
+  // Not measured. A pre-owner catalog read carries no owner at all, and absent evidence is
+  // not evidence of a problem — say nothing, exactly as before.
+  if (owner === undefined) return {};
+
+  const superuser = o.ownerIsSuperuser;
+  const connected = o.ownerIsConnectedRole;
+  const ambient: string[] = [];
+  if (superuser === true) ambient.push('a superuser');
+  if (connected === true) ambient.push('the role db:pull connected as');
+
+  if (!ambient.length && superuser !== undefined && connected !== undefined) {
+    // A chosen principal. Render it — unless PostgreSQL's name is one defineFunction refuses,
+    // in which case rendering would emit source that throws on import.
+    if (!RENDERABLE_ROLE.test(owner)) {
+      const why = `${o.identity}: owner '${owner}' is not a bare lowercase role name, which is all the model's owner property accepts (it is interpolated into SET ROLE) — ownership NOT declared. Rename the role, or declare the owner by hand.`;
+      return { fixme: `// FIXME: ${why}`, warning: why };
+    }
+    return { prop: `owner: ${tsString(owner)},` };
+  }
+
+  if (!ambient.length) {
+    // Owner known, discriminator not measured. Refuse to classify rather than guess.
+    return {
+      fixme: `// FIXME: ${o.identity} is owned by '${owner}', but this pull could not tell whether that is a chosen principal or the build credential — owner is NOT declared. Add owner: '${owner}' if that role is the intended owner.`,
+    };
+  }
+
+  const because = ambient.join(' and ');
+  // The runs-as-owner case is the one that reaches stderr as well as the file: it is a live
+  // privilege-escalation surface, not a style note. The plain case stays an inline FIXME —
+  // on a brownfield database it is the common shape, and echoing all of it would bury the rest.
+  return elevated
+    ? {
+      fixme: `// FIXME SECURITY: ${o.identity} is ${elevated.posture} and owned by '${owner}' — ${because}. ${elevated.what} runs with that role's privileges. The observed owner is NOT declared, because declaring the build credential would make the accident reproducible; declare the intended owner with owner: '<role>'.`,
+      warning: `${o.identity}: ${elevated.posture}, owned by '${owner}' (${because}) — ${elevated.what.toLowerCase()} runs with that role's privileges. Ownership was NOT declared; declare the intended owner with owner: '<role>'.`,
+    }
+    : {
+      fixme: `// FIXME: ${o.identity} is owned by '${owner}' — ${because}, not a chosen principal, so ownership is NOT declared. Add owner: '<role>' if a specific role should own it.`,
+    };
+}
+
+/**
+ * The A4 spelling, kept so existing callers and tests read unchanged. `renderedOwner` is the
+ * implementation; this is the function-shaped door onto it.
+ */
+export function renderedFunctionOwner(
+  o: Pick<LiveObject, 'identity' | 'owner' | 'ownerIsSuperuser' | 'ownerIsConnectedRole'>,
+  secdef: boolean,
+): { prop?: string; fixme?: string; warning?: string } {
+  return renderedOwner(o, secdef ? SECURITY_DEFINER_RIGHTS : null);
+}
+
 /** One matview index attachment → the Brick E builder chain, or null (FIXME). */
 function renderIndexBuilder(indexdef: string): string | null {
   const parsed = parseIndexDefinition(indexdef);
@@ -469,6 +573,24 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       const props: string[] = [];
       const hasPrivileges = Object.keys(privileges).length > 0;
       if (o.kind === 'view') props.push(`securityInvoker: ${o.securityInvoker === true},`);
+      // A15 — the owner, through the SAME discriminator functions use. Elevated exactly when
+      // the relation runs as its owner: a view that is not securityInvoker, and a matview
+      // always (its rows are computed at REFRESH time with the owner's rights, no exceptions).
+      const relationOwnership = renderedOwner(
+        o,
+        o.kind === 'materialized view' ? MATVIEW_RIGHTS
+          : o.securityInvoker === false ? DEFINER_VIEW_RIGHTS
+            : null,
+      );
+      if (relationOwnership.prop) props.push(relationOwnership.prop);
+      if (relationOwnership.fixme) fixmes.push(relationOwnership.fixme);
+      // The FIXME lands in the file, at the declaration, which is where the operator acts on
+      // it. The stderr WARNING is deliberately NOT raised for relations: `SECURITY DEFINER` is
+      // opt-in and rare, so echoing those is signal, but `security_invoker = false` is
+      // PostgreSQL's DEFAULT for views — on any real database nearly every view and every
+      // matview qualifies, and promoting all of them would bury the function findings the
+      // channel exists for. Same judgement the function branch already makes for its plain
+      // case, applied where the base rate is inverted.
       // `private: true` means "declared dark, no grants" — it contradicts a recorded
       // grant, and the model refuses the pair. A relation whose only reach is recorded
       // (PUBLIC SELECT, or a write grant) is not dark; it just has no CHOSEN audience.
@@ -516,6 +638,7 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
     const roleGrants = Object.keys(grants).filter((r) => r.toUpperCase() !== 'PUBLIC').sort();
     const publicExec = Object.keys(grants).some((r) => r.toUpperCase() === 'PUBLIC');
     const args = f && (f.language === 'sql' || f.language === 'plpgsql') ? parseArgs(f.args) : null;
+    const ownership = renderedFunctionOwner(o, f?.secdef === true);
 
     if (!f || args === null || (f.language !== 'sql' && f.language !== 'plpgsql')) {
       warnings.push(`${o.identity}: signature beyond the v1 vocabulary (${f ? `language ${f.language}, args '${f.args}'` : 'no structured fields'}) — rendered as defineSql.`);
@@ -523,6 +646,14 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
       // collapse to one provenance row here too — the declared name carries the signature
       // (the drop is explicit, so the name is a label, and a unique one is what it needs).
       const sqlName = declaredName(o) + (f?.identityArgs !== undefined ? `(${f.identityArgs})` : '');
+      // A defineSql object cannot carry an owner. Where the pull observed a CHOSEN owner that
+      // is real fidelity loss, so it is said out loud on both surfaces — never dropped. An
+      // ambient owner needs no note here: there is nothing to declare and nothing was lost.
+      if (ownership.prop) {
+        const why = `${o.identity}: owned by '${o.owner}', but defineSql cannot declare an owner — the build will create it as the connecting role. Move it into defineFunction's vocabulary, or set the owner by hand after the build.`;
+        warnings.push(why);
+        lines.push(`// FIXME: ${why}`);
+      }
       lines.push(
         `// FIXME: ${o.identity} — signature beyond defineFunction's v1 vocabulary; kept verbatim as defineSql.`,
         `export const ${varName} = defineSql(${tsString(sqlName)}, {`,
@@ -548,11 +679,30 @@ export function renderDerivedSource(catalog: DerivedCatalog, opts: DerivedRender
     props.push(`returns: ${tsString(f.returns)},`);
     props.push(`language: ${tsString(f.language)},`);
     if (VOLATILITY[f.volatility]) props.push(`volatility: ${tsString(VOLATILITY[f.volatility])},`);
-    if (f.secdef) {
-      props.push(`security: 'definer',`);
-      const path = (f.searchPath ?? 'pg_catalog').split(',').map((s) => s.trim().replace(/^"|"$/g, '')).filter(Boolean);
+    if (f.secdef) props.push(`security: 'definer',`);
+    // THE PIN IS READ, NEVER INVENTED.
+    //
+    // This used to render `searchPath: ['pg_catalog']` for any definer function whose live
+    // proconfig was empty. A build from those models then applied the invented pin for real, so
+    // functions that had always resolved `public` stopped resolving it — sign-up and password
+    // change died on a database built from the consumer's own models, with every gate green.
+    // 34 of their 34 pinned-in-the-model functions were unpinned in the database.
+    //
+    // A live pin renders as the array. No live pin on a definer function renders the explicit
+    // `'unpinned'` sentinel — an ANSWER, not silence, so `defineFunction` still throws for the
+    // author who simply forgot. No live pin on an invoker function renders nothing, which
+    // already means exactly that.
+    if (f.searchPath) {
+      const path = f.searchPath.split(',').map((s) => s.trim().replace(/^"|"$/g, '')).filter(Boolean);
       props.push(`searchPath: [${path.map(tsString).join(', ')}],`);
+    } else if (f.secdef) {
+      props.push(`searchPath: 'unpinned',`);
     }
+    // Ownership sits beside security because it IS the other half of it: `security: 'definer'`
+    // says the function runs as its owner, and this says who that is.
+    if (ownership.prop) props.push(ownership.prop);
+    if (ownership.fixme) fixmes.push(ownership.fixme);
+    if (ownership.warning) warnings.push(ownership.warning);
     if (roleGrants.length) {
       props.push(`abilities: [${roleGrants.map((r) => `can('execute', { role: ${tsString(r)} })`).join(', ')}],`);
       need('can');

package/src/cli/derived-source.ts

@@ -60,6 +60,30 @@ export interface SourceObject {
   file: string;
   /** Position in the concatenated source — a valid dependency order by convention. */
   seq: number;
+  /**
+   * kind 'function' only: the declared owning role.
+   *
+   * A SECURITY DEFINER function executes with its OWNER's rights, so this is a privilege
+   * boundary. The applier enacts it by running the CREATE under `SET ROLE <owner>` rather
+   * than following it with `ALTER … OWNER TO`: measured on PG16, once ownership has moved the
+   * builder gets "must be owner of function" on the next `CREATE OR REPLACE`, so the
+   * alter-after form works exactly once and breaks every re-run.
+   */
+  owner?: string;
+  /**
+   * kind 'function' only: the declared `SET search_path`, or the sentinel `'unpinned'`.
+   *
+   * It is already inside `sql`, so this is NOT in the hash and changes no fingerprint. It rides
+   * structurally so the differ can compare the declared pin against the LIVE catalog directly
+   * rather than only against a recorded hash. Without that, `--baseline` records a declared pin
+   * the database does not have and every later check reports zero actions, forever: measured,
+   * and it is how a model came to claim `search_path=pg_catalog` about a database with none
+   * while every gate stayed green.
+   *
+   * `undefined` means NOT DECLARED — a parser-era db/sql object, or an invoker function with no
+   * pin. The comparison is skipped there; absent evidence is not evidence.
+   */
+  searchPath?: string[] | 'unpinned';
   /** kind 'sql' only: the declared PostgreSQL object kind (`'aggregate'`, …). */
   objectKind?: string;
   /** kind 'sql' only: the explicit DROP for kinds whose drop isn't derivable from the name. */
@@ -82,9 +106,15 @@ export const DECLARED_SOURCE_FILE = 'db/models (declared)';
 /** The one content-hash formula. Unchanged since the db/sql era on purpose: provenance
  *  recorded from parser-era objects still matches the descriptor-compiled hash of the
  *  same SQL, so the db/sql → descriptor migration reconciles as a no-op. */
-export function hashSourceContent(createSql: string, attachments: Attachment[]): string {
+export function hashSourceContent(createSql: string, attachments: Attachment[], owner?: string): string {
   const content = [normalizeSql(createSql), ...attachments.map((a) => normalizeSql(a.sql))].join('\n');
-  return createHash('sha256').update(content).digest('hex');
+  // Ownership is part of the declared state — a SECURITY DEFINER function that changes owner
+  // changes who it executes as, which is a rebuild, not an authz delta. It is folded in as a
+  // PREFIX only when declared, so every object without an owner hashes byte-identically to
+  // before this existed. That is deliberate: a consumer mid-adoption must not be forced into a
+  // second fingerprint re-mint in a week by a field they do not use.
+  const body = owner ? `-- owner: ${owner}\n${content}` : content;
+  return createHash('sha256').update(body).digest('hex');
 }
 
 /** A raw file the generic dir readers return (db/backfills, seed lanes). */

package/src/cli/edge-plan.ts

@@ -123,6 +123,12 @@ export interface MintOptions {
    * MINTED PLAN carries those revokes, which is where they would actually be applied.
    */
   governedRoles?: string[];
+  /**
+   * Extensions the modules declare. A plan minted without them silently omits every
+   * `CREATE EXTENSION` the target lacks — so a stage evolving onto a model that newly uses
+   * an extension type fails at APPLY, with the plan having promised it would not.
+   */
+  extensions?: string[];
 }
 
 /**
@@ -217,6 +223,7 @@ export function mintEdgePlan(
     allowDrops: opts.allowDrops,
     liveAuthz: contract,
     governedRoles: opts.governedRoles,
+    extensions: opts.extensions,
   });
   const classified = classifyGeneratedStatements(statements);
   if (classified.heldDrops.length > 0) {

package/src/cli/index.ts

@@ -19,6 +19,7 @@ import { dbDiffCommand } from './commands/db-diff.js';
 import { dbPlanCommand } from './commands/db-plan.js';
 import { dbApplyCommand } from './commands/db-apply.js';
 import { dbCheckCommand } from './commands/db-check.js';
+import { dbBuildCommand } from './commands/db-build.js';
 import { dbApproversCommand } from './commands/db-approvers.js';
 import { dbBackfillCommand } from './commands/db-backfill.js';
 import { dbExecCommand } from './commands/db-exec.js';
@@ -208,6 +209,9 @@ async function main() {
     case 'db:check':
       await dbCheckCommand(flags);
       break;
+    case 'db:build':
+      await dbBuildCommand(flags);
+      break;
     case 'db:approvers':
       await dbApproversCommand(flags);
       break;
@@ -368,6 +372,7 @@ Usage:
   everystack db:diff           --from-models <barrel> [--to-models db/models/index.ts] [--allow-drops] [--check] [--json]  The state edge between two declared states, NO database: the SQL db:generate would produce, computed purely — CI plan previews (--check exits 1 on a non-empty edge) and computed rollbacks (swap the flags)
   everystack db:plan           [--stage <name> [--direct] | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only; plans are ephemeral, never committed. VENUES: --stage runs via the ops Lambda, which reads TWICE and refuses on disagreement — agreement there is a DETECTOR, not a verification. --stage --direct resolves the stage's operator connection from its IAM-gated ops Lambda, holds it in memory only, and reads ONCE over one session: the lane for a fingerprint you intend to trust, with the credential never on argv. --database-url is the local-dev venue (same read guarantee, but against a deployed stage it puts a privileged DSN on the command line)
   everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--snapshot-ref <ref>] [--force-descent <snapshot-ref> --confirm]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule, else refuse — "rebase first"), and for DESTRUCTIVE plans require --confirm always + an attested --snapshot-ref + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there
+  everystack db:build          --database-url <url> [--models <barrel>]  Build a database FROM the models and KEEP it — the fresh-database bootstrap a deleted migration folder is replaced BY. Runs the same compose db:check proves buildability with (extensions -> schemas -> contract roles -> declared functions -> state -> derived layer), against a real target, then reports MATCH. Venue is EXPLICIT: --database-url only, never the ambient environment, because this writes a whole schema. REFUSES a database that already holds objects — evolving an existing one is db:sync (dev) or db:plan -> db:apply (a stage). Contract roles are created NOLOGIN if absent, and roles are cluster-level
   everystack db:check          [--models <barrel>] [--schema-out <file.ts>] [--database-url <url>] [--json]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, descriptors compile), every exposed RLS-enabled table must declare a read path (no force-RLS-with-no-read landmine that goes dark on the superuser drop), and generated artifacts must MATCH regeneration byte-for-byte; with a scratch PostgreSQL it builds the state from scratch on an ephemeral database (created + dropped) and requires fingerprint MATCH. Exit 1 on any failure; never touches a real target
   everystack db:approvers      --stage <name> [--set "cto,arn:..."] [--remove]  Declare who can DESTROY: the stage's destructive-approver set (SSM parameter, admin-writable). Destructive db:apply runs are then identity-verified (STS) against it; --set '' disables destructive applies; --remove returns the stage to ceremony-only
   everystack db:backfill       [--database-url <url>] [--dir db/backfills] [--apply] [--mark-applied <file.sql>] [--json]  One-shot data jobs in their own lane: plan shows applied (by CONTENT identity — renames/comment edits are no-ops) / pending (in order, unbounded-pass advisories) / blocked (a name that already ran in a different form — one-shot jobs are immutable). --apply runs each pending job as its own transaction, recorded in everystack.backfill_log (a failure rolls back alone, is recorded, stops the run); --mark-applied records without running. Never runs as a schema side effect; direct connection required

package/src/cli/migration-generate.ts

@@ -28,6 +28,9 @@ export interface GenerateOptions {
   schema?: string;
   /** Standalone sequences the modules declare (state layer — created before tables). */
   sequences?: SequenceDescriptor[];
+  /** Postgres extensions the modules declare — emitted first, before anything using their
+   *  types. Omitted = none declared; the live side's absent `extensions` means unknown. */
+  extensions?: string[];
   /**
    * Emit real `DROP COLUMN`/`DROP CONSTRAINT`/`DROP TABLE` for things present in the
    * database but absent from the Models. Default `false` — those are held back as
@@ -73,6 +76,9 @@ export const HELD_DROP_PREFIX = '-- DROP held back';
  */
 function isRemoval(change: SchemaChange, replacedConstraints: Set<string>): boolean {
   if (change.kind === 'dropColumn' || change.kind === 'dropTable' || change.kind === 'dropType' || change.kind === 'dropIndex') return true;
+  // DROP IDENTITY destroys the backing sequence and its counter — a removal, not a change.
+  // ADD/SET GENERATED are not: they create or retune the auto-value and lose nothing.
+  if (change.kind === 'setIdentity' && change.identity == null) return true;
   if (change.kind === 'dropConstraint') return !replacedConstraints.has(`${change.table}::${change.name}`);
   return false;
 }
@@ -140,6 +146,23 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   //    databases already have their schemas (their own migrations made them), so this is
   //    invisible in the brownfield loop. IF NOT EXISTS keeps an empty-but-existing schema
   //    (no tables for the live side to reveal it by) from failing the create.
+  // 0-pre. EXTENSIONS, before anything that could use their types.
+  //
+  // The from-scratch compiler emitted these from day one; this DIFF path never did, so the
+  // brownfield loop (db:sync, db:generate --apply) and the whole db:plan/db:apply stage lane
+  // were silently missing them. Two distinct failures, both measured on a consumer's
+  // checkout: a fresh build dies on `type "hstore" does not exist`, and a DEPLOYED stage
+  // evolving onto a model that newly uses an extension type fails the same way at apply.
+  //
+  // `current.extensions` is ABSENT when the caller never ran the extensions query — absent
+  // means unknown, not empty, so everything declared is emitted. `IF NOT EXISTS` makes that
+  // safe: the cost of not knowing is a no-op statement, never a failure.
+  const liveExtensions = current.extensions === undefined ? null : new Set(current.extensions);
+  const extensionPhase = [...new Set(opts.extensions ?? [])]
+    .filter((e) => liveExtensions === null || !liveExtensions.has(e))
+    .sort()
+    .map((e) => `CREATE EXTENSION IF NOT EXISTS "${e}"`);
+
   const liveSchemas = new Set(current.tables.map((t) => t.table.split('.')[0]));
   const schemaPhase = [...new Set(desired.tables.map((t) => t.table.split('.')[0]))]
     .filter((s) => s !== 'public' && !liveSchemas.has(s))
@@ -269,7 +292,7 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
         })
     : [];
 
-  return [...schemaPhase, ...usagePhase, ...dataPhase, ...authzPhase];
+  return [...extensionPhase, ...schemaPhase, ...usagePhase, ...dataPhase, ...authzPhase];
 }
 
 /** The marker drizzle migration files put between statements. */

package/src/cli/model-render.ts

@@ -20,6 +20,7 @@ import type { DerivedRenderResult } from './derived-render.js';
 import type { TableContract } from './authz-contract.js';
 import { deriveAbilities, renderDerivedAbilities } from './authz-derive.js';
 import { normalizeDefault, normalizeCheck } from './schema-diff.js';
+import { generatedIndexName, generatedForeignKeyName } from './schema-compile.js';
 
 /**
  * Reverse a CHECK predicate back into the `.validate(z…)` that produced it — the inverse of
@@ -459,10 +460,17 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
   let expr = call ?? verbatimFieldCall(col.type);
   let comment = call ? '' : ` // verbatim: no first-class field for '${col.type}' — carried as-is`;
 
+  // The auto-value the database actually holds. Rendered BEFORE .primaryKey()/.notNull() so a
+  // pulled surrogate key reads the way one is authored, and rendered at all because without it
+  // the rebuilt column has no auto-value and every INSERT that omits it fails NOT NULL.
+  if (col.identity) {
+    expr += col.identity === 'always' ? '.generatedAlwaysAsIdentity()' : '.generatedByDefaultAsIdentity()';
+  }
+
   const isPk = table.primaryKey.includes(col.name);
   if (isPk) expr += '.primaryKey()';
-  // A serial field is NOT NULL by construction, so the modifier would be redundant.
-  else if (col.notNull && !serial) expr += '.notNull()';
+  // A serial or identity field is NOT NULL by construction, so the modifier would be redundant.
+  else if (col.notNull && !serial && !col.identity) expr += '.notNull()';
 
   if (table.uniques.some((u) => u.columns.length === 1 && u.columns[0] === col.name)) expr += '.unique()';
 
@@ -473,7 +481,11 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
         fk.onDelete ? `onDelete: ${tsLiteral(fk.onDelete)}` : null,
         fk.onUpdate ? `onUpdate: ${tsLiteral(fk.onUpdate)}` : null,
       ].filter(Boolean);
-      const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
+      // A8 — the FK's own name, said only when it is not the one the compiler would generate.
+    if (fk.name && fk.name !== generatedForeignKeyName(bareName(table.table), fk.columns, bareName(fk.refTable), fk.refColumns)) {
+      actions.push(`name: ${tsLiteral(fk.name)}`);
+    }
+    const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
       expr += `.references(() => ${modelVarName(fk.refTable)}${opts})`;
     } else comment += ` // FK → ${fk.refTable} (not in the pulled set)`;
   }
@@ -528,6 +540,15 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
     if (ix.unique) s += '.unique()';
     if (ix.include?.length) s += `.include(${ix.include.map((c) => tsLiteral(toCamelCase(c))).join(', ')})`;
     if (ix.where) s += `.where(sql\`${normalizeCheck(ix.where)}\`)`;
+    // A7 — keep the name the database actually has, but only say it when it is not the one the
+    // compiler would generate anyway. A brownfield schema arrives with its previous tooling's
+    // names (`index_contents_on_destination_id`), and rebuilding under ours renamed ~200 of one
+    // consumer's indexes: counts and definitions matched, so every gate stayed green while a
+    // planner regression test, runbooks and pg_stat_user_indexes history all broke. Declaring
+    // only the divergent ones keeps a greenfield pull clean and an adopted one faithful.
+    if (ix.name && ix.name !== generatedIndexName(bareName(table.table), ix.columns)) {
+      s += `.name(${tsLiteral(ix.name)})`;
+    }
     items.push(s);
   }
   for (const fk of table.foreignKeys) {
@@ -542,6 +563,10 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
       fk.onDelete ? `onDelete: ${tsLiteral(fk.onDelete)}` : null,
       fk.onUpdate ? `onUpdate: ${tsLiteral(fk.onUpdate)}` : null,
     ].filter(Boolean);
+    // A8 — the FK's own name, said only when it is not the one the compiler would generate.
+    if (fk.name && fk.name !== generatedForeignKeyName(bareName(table.table), fk.columns, bareName(fk.refTable), fk.refColumns)) {
+      actions.push(`name: ${tsLiteral(fk.name)}`);
+    }
     const opts = actions.length ? `, { ${actions.join(', ')} }` : '';
     items.push(`foreignKey(${cols}, () => ${modelVarName(fk.refTable)}, ${refCols}${opts})`);
   }