@everystack/cli 0.4.53 → 0.4.56

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

@@ -37,7 +37,8 @@ import { compileDrizzleSource } from '../schema-source.js';
 import { currentGitRef } from '../state-apply.js';
 import { createDatabase, dropDatabase, buildIntoDatabase, withDatabase } from '../db-build.js';
 import { resolveModelsPath } from '../models-path.js';
-import { loadModels, loadModules } from './db-generate.js';
+import { loadModels, loadModules, readJournal, DEFAULT_MIGRATIONS } from './db-generate.js';
+import { resolveSchemaOut } from '../migration-generate.js';
 import { findUnexportedModels, scanModelDirectory, type ModelFileScan } from '../model-barrel-lint.js';
 import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived.js';
 import type { SequenceDescriptor } from '@everystack/model';
@@ -46,6 +47,7 @@ import { findReadAuthzGaps, findNakedGrants } from '../authz-lint.js';
 import { parseBaseline, renderBaseline, BASELINE_FILE } from '../authz-baseline.js';
 import {
   findDerivedReadGaps, findSecdefExecuteGaps, findMatviewSnapshotWarnings, findPublicExecutableSecdef,
+  findUnpinnedDefiners,
 } from '../derived-lint.js';
 import { step, success, fail, info, warn } from '../output.js';
 
@@ -234,7 +236,9 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
     for (const gap of derivedGaps) {
       findings.push({ level: 'fail', area: 'authz', message: gap.message });
     }
-    for (const warning of [...findMatviewSnapshotWarnings(input.derived), ...findPublicExecutableSecdef(input.derived)]) {
+    // findUnpinnedDefiners is the advisory half of A3: db:pull stopped inventing a pin, so the
+    // opinion moved here. It SUGGESTS one and never applies it.
+    for (const warning of [...findMatviewSnapshotWarnings(input.derived), ...findPublicExecutableSecdef(input.derived), ...findUnpinnedDefiners(input.derived)]) {
       findings.push({ level: 'warn', area: 'authz', message: warning.message });
     }
     if (derivedGaps.length === 0) {
@@ -345,7 +349,17 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
     } catch { /* a models-only barrel has no modules export — nothing to bootstrap */ }
   }
 
-  const artifactPath = flags['schema-out'] || DEFAULT_SCHEMA_OUT;
+  // The SAME resolution db:generate uses — flag > journal-recorded > default. db:check read
+  // only the flag, so a project that had RELOCATED its artifact (recorded in the journal by
+  // db:generate, per its own help) had the two verbs disagree about which file is the
+  // artifact: generate wrote one path, check guarded another. A consumer worked around it by
+  // passing the flag explicitly in their CI script.
+  const journal = await readJournal(path.resolve(flags.dir || DEFAULT_MIGRATIONS));
+  const artifactRes = resolveSchemaOut(flags['schema-out'], journal, DEFAULT_SCHEMA_OUT);
+  const artifactPath = artifactRes.path;
+  if (artifactRes.source === 'recorded') {
+    info(`schema-out: ${artifactPath} (recorded in the journal; override with --schema-out)`);
+  }
   let artifactSource: string | null = null;
   try {
     artifactSource = await fs.readFile(artifactPath, 'utf8');
@@ -438,6 +452,9 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
     // ring proves the checkout against ITSELF, on an empty database. Whether an existing
     // database IS this state is a different question with a different verb.
     info('This proves the checkout is self-consistent and buildable — not that any existing database matches it. For that claim, run db:fingerprint against the database.');
+    // The ephemeral database is DROPPED. Saying so here is what stops this line being read
+    // as "you now have a database" — a consumer read exactly that into it, from our own docs.
+    info('The database this composed on was ephemeral and has been dropped. To build one you KEEP: everystack db:build --database-url <url>.');
   } else {
     success('db:check passed (static ring only — no database provided for the ephemeral compose).');
   }

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

@@ -43,7 +43,7 @@ import { resolveConfig, opsFunction } from '../config.js';
 import { invokeAction, lambdaQueryRunner, lambdaSessionRunner } from '../aws.js';
 import { step, success, fail, info, warn } from '../output.js';
 
-const DEFAULT_MIGRATIONS = 'drizzle';
+export const DEFAULT_MIGRATIONS = 'drizzle';
 const DEFAULT_SCHEMA_OUT = 'db/schema.generated.ts';
 
 /** Import the app's Model barrel and return its `models` array (runs under tsx, so TS imports work).
@@ -187,7 +187,7 @@ function reportOwnership(
   }
 }
 
-async function readJournal(migrationsDir: string): Promise<Journal | null> {
+export async function readJournal(migrationsDir: string): Promise<Journal | null> {
   try {
     return JSON.parse(await fs.readFile(path.join(migrationsDir, 'meta', '_journal.json'), 'utf8'));
   } catch {
@@ -290,7 +290,7 @@ export async function dbGenerateCommand(flags: Record<string, string>): Promise<
 
   // One ordered migration carries both layers: data DDL first, then the authz reconcile
   // (RLS/policies/grants) the Models' abilities declare, diffed against the live contract.
-  const statements = generateMigrationSql(models, current, { allowDrops, liveAuthz, sequences: declaredDb?.sequences, governedRoles: declaredDb?.governedRoles });
+  const statements = generateMigrationSql(models, current, { allowDrops, liveAuthz, sequences: declaredDb?.sequences, governedRoles: declaredDb?.governedRoles, extensions: declaredDb?.extensions });
   const unmodeled = unmodeledTables(models, current);
   if (unmodeled.length) {
     info(`${unmodeled.length} table(s) in the database are not declared by any model — left untouched (db:generate manages only declared tables).`);

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

@@ -172,8 +172,13 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
     // The modules' widened governed-role set. A barrel that exports only `models` has none,
     // which is the greenfield default: govern exactly what the models name.
     let declaredGovernedRoles: string[] = [];
+    // The modules' extensions ride the same read. Without them the plan omits every
+    // CREATE EXTENSION the target lacks, and the apply fails on a type the plan promised.
+    let declaredExtensions: string[] = [];
     try {
-      declaredGovernedRoles = (await loadDeclaredDerived(flags.models))?.governedRoles ?? [];
+      const declared = await loadDeclaredDerived(flags.models);
+      declaredGovernedRoles = declared?.governedRoles ?? [];
+      declaredExtensions = declared?.extensions ?? [];
     } catch {
       // The barrel's own compose errors surface on the paths that need the derived layer;
       // a plan must not fail to mint because a module could not be read for this one field.
@@ -202,6 +207,7 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
         // Without this the MINTED PLAN carries a REVOKE for every live grantee the models
         // do not name — which is the artifact an operator actually applies.
         governedRoles: declaredGovernedRoles,
+        extensions: declaredExtensions,
       });
     } catch (err: any) {
       fail(`Mint refused: ${err.message}`);

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/db-sync.ts

@@ -76,6 +76,8 @@ export interface SyncOptions {
   declared?: SourceObject[];
   /** Standalone sequences the modules declare (state — created before tables, fingerprinted). */
   sequences?: SequenceDescriptor[];
+  /** Extensions the modules declare — emitted before anything that uses their types. */
+  extensions?: string[];
   /** Roles the modules govern beyond the ones the models name — a grantee outside the set
    *  is exempted from revocation and enumerated instead (authz-reconcile's governedRoleSet). */
   governedRoles?: string[];
@@ -123,12 +125,12 @@ export async function executeSync(
   const liveAuthz = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
   const statements = generateMigrationSql(models, current, {
     allowDrops: options.allowDrops, liveAuthz, sequences: options.sequences,
-    governedRoles: options.governedRoles,
+    governedRoles: options.governedRoles, extensions: options.extensions,
   });
   hooks.onStatePlan?.(statements, classifyGeneratedStatements(statements));
 
   const state = await applyStateAndVerify(runner, session, models, statements, current, liveAuthz, {
-    allowDrops: options.allowDrops, sequences: options.sequences,
+    allowDrops: options.allowDrops, sequences: options.sequences, extensions: options.extensions,
     actor: options.actor, gitRef: options.gitRef, now: options.now,
   });
   hooks.onStateDone?.(state);
@@ -315,6 +317,7 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
       {
         declared: declaredDb?.objects,
         sequences: declaredDb?.sequences,
+        extensions: declaredDb?.extensions,
         renamedTables: declaredDb?.renamedTables,
         allowDrops: flags['allow-drops'] === 'true',
         overwriteDrift: flags['overwrite-drift'] === 'true',

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/declared-derived.ts

@@ -34,6 +34,16 @@ export interface DeclaredDerived {
   /** Roles the modules declare as governed beyond the ones the models name. A live grantee
    *  outside the governed set is exempted from reconciliation and ENUMERATED instead. */
   governedRoles: string[];
+  /**
+   * Postgres extensions the modules declare — the bootstrap the state layer needs before
+   * anything that uses their types. Only the from-scratch compiler consumed these; the DIFF
+   * path never saw them, so `db:generate --apply`, `db:sync` and the whole `db:plan`/
+   * `db:apply` stage lane emitted zero `CREATE EXTENSION`. A consumer measured the gap as
+   * exactly their nine extensions (471 statements vs db:check's 480 on one checkout), and
+   * it is not only a fresh-build problem: a deployed stage evolving onto a model that newly
+   * uses `hstore` or `postgis` fails on apply.
+   */
+  extensions: string[];
 }
 
 /**
@@ -178,6 +188,7 @@ export function composeDeclaredDerived(modules: Module[], modelsPath: string): D
       renamedTables: { ...compileTableRenames(models, {}), ...compileTableMoves(models, {}) },
       models,
       governedRoles: moduleGovernedRoles(modules),
+      extensions: [...new Set(modules.flatMap((m) => m.extensions ?? []))].sort(),
     };
   } catch (err) {
     throw asModelComposeError(modelsPath, err);