@everystack/cli 0.4.52 → 0.4.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.52",
+  "version": "0.4.55",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -164,6 +164,7 @@
   "scripts": {
     "test": "jest",
     "build": "tsc --build",
-    "lint": "tsc --noEmit"
+    "lint": "tsc --noEmit",
+    "check:artifact": "tsx scripts/check-generated-artifact.ts"
   }
 }

package/src/cli/authz-compile.ts

@@ -23,6 +23,7 @@
 import { isColumnAbility, type ModelDescriptor, type Ability } from '@everystack/model';
 import type { PolicyContract, TableContract, PolicyCommand } from './authz-contract.js';
 import { parenthesizeOnce } from './authz-contract.js';
+import { normalizeDeparsedExpr } from './deparse-normal.js';
 
 export interface CompileOptions {
   /** Schema the table lives in. Default: `public`. */
@@ -400,7 +401,14 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     name: string, command: PolicyCommand, roles: string[],
     using: string | null, check: string | null,
   ): void => {
-    policies.push({ name, command, roles, permissive: true, using, check });
+    // Same normalization the live producer applies (authz-contract's `predicate`): a model
+    // pulled on one PostgreSQL major carries that major's deparse spelling in its predicates,
+    // and it must compare equal against a stage on another. One rule table, two producers.
+    policies.push({
+      name, command, roles, permissive: true,
+      using: using == null ? null : normalizeDeparsedExpr(using),
+      check: check == null ? null : normalizeDeparsedExpr(check),
+    });
   };
 
   // admin-bypass — one ALL policy, true/true.

package/src/cli/authz-contract.ts

@@ -24,6 +24,7 @@
 import { parsePgArray } from './security-catalog.js';
 import { INTROSPECTION_SESSION, type SessionRunner } from './session.js';
 import { matchPolicies, roleSetEqual } from './authz-identity.js';
+import { normalizeDeparsedExpr } from './deparse-normal.js';
 
 // ---------------------------------------------------------------------------
 // The contract format — the frozen, reviewable, version-controlled shape.
@@ -270,6 +271,15 @@ export interface FunctionContract {
 export interface AuthzContract {
   tables: TableContract[];
   functions: FunctionContract[];
+  /**
+   * Schema-level ACLs (pg_namespace.nspacl), schema → grantee → sorted privileges
+   * (USAGE | CREATE). `PUBLIC` is the pseudo-role entry. A schema with a NULL acl is
+   * ABSENT — owner-default, no explicit grants — so absence means "the grant does not
+   * exist" and an emitter may emit it. Optional: contracts assembled from older recorders
+   * or hand-built fixtures simply carry no schema knowledge, and consumers must treat
+   * that as "unknown", never as "no grants".
+   */
+  schemaAcls?: Record<string, Record<string, string[]>>;
 }
 
 export type PolicyCommand = 'ALL' | 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE';
@@ -398,6 +408,82 @@ WHERE c.relkind = 'r'
 ORDER BY n.nspname, c.relname;
 `.trim();
 
+/**
+ * Schema ACLs, for the emitters that grant schema USAGE. The consumer bug this closes: the
+ * usage phase emitted `GRANT USAGE ON SCHEMA` with no live read at all, so every plan with
+ * any authz statement re-granted what the database already held — two false statements on
+ * every stage plan, forever. `nspacl` casts to its array-literal text; NULL stays NULL
+ * (owner default — no explicit grants — which the parser must NOT read as an empty grant
+ * list on purpose: for nspacl the two mean the same emittable thing, but the distinction
+ * is kept so the contract says what the catalog said).
+ */
+export const SCHEMA_ACL_SQL = `
+SELECT n.nspname AS schema, n.nspacl::text AS acl
+FROM pg_namespace n
+WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_%'
+ORDER BY n.nspname;
+`.trim();
+
+export interface SchemaAclRow {
+  schema: string;
+  acl: unknown;
+}
+
+/** The two privileges a schema ACL can carry, in aclitem letter form. */
+const SCHEMA_PRIV_LETTERS: Record<string, string> = { U: 'USAGE', C: 'CREATE' };
+
+/**
+ * Parse one `aclitem[]::text` literal — `{postgres=UC/postgres,authenticator=U/postgres}` —
+ * into grantee → privileges. An empty grantee (`=U/postgres`) is PUBLIC. A quoted grantee
+ * (`"odd,role"=U/postgres`) is unwrapped with its doubled-quote escapes. A `*` (grant
+ * option) rides the letter before it and is dropped — holding WITH GRANT OPTION still
+ * holds the privilege. Unparseable input returns null: the caller treats it as unknown,
+ * never as "no grants".
+ */
+export function parseSchemaAcl(text: string | null | undefined): Record<string, string[]> | null {
+  if (text == null) return null;
+  const s = String(text).trim();
+  if (!s.startsWith('{') || !s.endsWith('}')) return null;
+  const body = s.slice(1, -1);
+  if (body.trim() === '') return {};
+  const out: Record<string, string[]> = {};
+  // Split items at top-level commas — a quoted region may contain commas.
+  const items: string[] = [];
+  let start = 0;
+  for (let j = 0; j < body.length; j++) {
+    if (body[j] === '"') {
+      for (j++; j < body.length; j++) {
+        if (body[j] !== '"') continue;
+        if (body[j + 1] === '"') { j++; continue; }
+        break;
+      }
+    } else if (body[j] === ',') {
+      items.push(body.slice(start, j));
+      start = j + 1;
+    }
+  }
+  items.push(body.slice(start));
+  for (const item of items) {
+    // grantee=letters/grantor — grantee may be quoted; the grantor half is irrelevant here.
+    const eq = item.indexOf('=', item.startsWith('"') ? item.indexOf('"', 1) + 1 : 0);
+    if (eq === -1) return null;
+    let grantee = item.slice(0, eq);
+    if (grantee.startsWith('"') && grantee.endsWith('"')) grantee = grantee.slice(1, -1).replace(/""/g, '"');
+    if (grantee === '') grantee = 'PUBLIC';
+    const slash = item.indexOf('/', eq);
+    const letters = item.slice(eq + 1, slash === -1 ? undefined : slash);
+    const privs = new Set<string>();
+    for (const ch of letters) {
+      if (ch === '*') continue;
+      const p = SCHEMA_PRIV_LETTERS[ch];
+      if (p) privs.add(p);
+    }
+    if (privs.size) out[grantee] = [...privs].sort();
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Pure mappers — one catalog row -> one descriptor.
 // ---------------------------------------------------------------------------
@@ -411,7 +497,10 @@ function truthy(v: unknown): boolean {
 function predicate(v: unknown): string | null {
   if (v == null) return null;
   const s = String(v).trim();
-  return s.length > 0 ? s : null;
+  // Normalized at the PRODUCER, so the matcher, the canonical hash, and the drift detail
+  // all see one spelling — a live tree deparsed by an older major must compare equal to
+  // the same predicate parsed on a newer one. See deparse-normal.ts for the rule table.
+  return s.length > 0 ? normalizeDeparsedExpr(s) : null;
 }
 
 export interface PolicyRow {
@@ -524,6 +613,8 @@ export interface ContractRows {
   policies: PolicyRow[];
   grants: GrantRow[];
   columnGrants?: ColumnGrantRow[];
+  /** pg_namespace ACL rows (SCHEMA_ACL_SQL) — optional; absent means schema ACLs unknown. */
+  schemaAcls?: SchemaAclRow[];
   /** Already-mapped function descriptors (from security-catalog's FUNCTIONS_SQL). */
   functions: { schema: string; name: string; securityDefiner: boolean; hasSearchPath: boolean; owner?: string; ownerBypassesRls?: boolean }[];
 }
@@ -585,9 +676,22 @@ export function assembleContract(rows: ContractRows): AuthzContract {
     }))
     .sort((a, b) => a.name.localeCompare(b.name));
 
+  // Schema ACLs, keyed only when the read ran (absent = unknown, per the contract's doc).
+  // A NULL acl (owner default) contributes an empty entry so "we looked, nothing granted"
+  // is distinguishable from "we never looked".
+  let schemaAcls: Record<string, Record<string, string[]>> | undefined;
+  if (rows.schemaAcls) {
+    schemaAcls = {};
+    for (const row of rows.schemaAcls) {
+      if (IGNORED_SCHEMAS.has(row.schema)) continue;
+      schemaAcls[row.schema] = parseSchemaAcl(row.acl == null ? '{}' : String(row.acl)) ?? {};
+    }
+  }
+
   return {
     tables: [...tables.values()].sort((a, b) => a.table.localeCompare(b.table)),
     functions,
+    ...(schemaAcls ? { schemaAcls } : {}),
   };
 }
 
@@ -597,11 +701,11 @@ export async function introspectContract(
   mapFunctionRow: (row: any) => { schema: string; name: string; securityDefiner: boolean; hasSearchPath: boolean },
   functionsSql: string,
 ): Promise<AuthzContract> {
-  // ONE session: the five queries describe one moment under one pinned search_path.
+  // ONE session: the six queries describe one moment under one pinned search_path.
   // Policy USING / WITH CHECK expressions deparse relative to that path, so a read spread
   // across connections can report authz drift that does not exist.
-  const [rls, policies, grants, columnGrants, fnRows] = await session(
-    [RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, functionsSql],
+  const [rls, policies, grants, columnGrants, schemaAcls, fnRows] = await session(
+    [RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, SCHEMA_ACL_SQL, functionsSql],
     INTROSPECTION_SESSION,
   );
   return assembleContract({
@@ -609,6 +713,7 @@ export async function introspectContract(
     policies: policies as PolicyRow[],
     grants: grants as GrantRow[],
     columnGrants: columnGrants as ColumnGrantRow[],
+    schemaAcls: schemaAcls as SchemaAclRow[],
     functions: (fnRows as any[]).map(mapFunctionRow),
   });
 }

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

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

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';
@@ -345,7 +346,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 +449,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-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

@@ -440,6 +440,7 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
     const stageName = flags.stage;
     if (!stageName) {
       note(`No --stage, so ${BASELINE_FILE} was not written. The foreign grantees above are recorded per stage; re-run with --stage <name> to adopt them, or db:plan will refuse until you do.`);
+      note(`--stage composes with --database-url: the URL stays the connection, the stage only LABELS the baseline entry — a local clone can adopt for a deployed stage without touching it.`);
     } else {
       const entry = buildStageBaseline(pulledExemptions, { observedAt: new Date().toISOString(), fingerprint: pulledFingerprint });
       const merged = mergeBaseline(await readBaselineFile(), stageName, entry);

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/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);

package/src/cli/deparse-normal.ts

@@ -0,0 +1,137 @@
+/**
+ * deparse-normal — cross-version normalization of `pg_get_expr` output.
+ *
+ * A policy predicate's stored tree is built by whichever server PARSED the DDL, and
+ * different PostgreSQL majors const-fold the same source differently. The measured case
+ * (a consumer's stage, 2026-08-08): an older major stores an array cast OUTSIDE the array,
+ *
+ *     (ARRAY['a'::character varying, 'b'::character varying])::text[]
+ *
+ * while PG17 distributes it over the elements at parse time,
+ *
+ *     ARRAY[('a'::character varying)::text, ('b'::character varying)::text]
+ *
+ * Text-identity across venues is then unreachable: models pulled on one major can never
+ * equal a stage on another, the differ plans DROP+CREATE forever (the stage re-deparses in
+ * its own spelling), and the fingerprint gate cannot MATCH. Identity must not depend on the
+ * two venues sharing a parser.
+ *
+ * THE RULE TABLE IS DELIBERATELY SMALL. Each rewrite must be provably semantics-preserving,
+ * because this text feeds the policy matcher, whose safety property is "misses are safe,
+ * false matches are the disaster". One rule today:
+ *
+ *   ARRAY-CAST DISTRIBUTION: `(ARRAY[e1, …, en])::T[]  ==  ARRAY[(e1)::T, …, (en)::T]`
+ *   for n ≥ 1. PostgreSQL defines an array-to-array cast element-wise (parse_coerce), so
+ *   the two expressions denote the same value for every input; wrapping an element in
+ *   parentheses is parse-neutral. The empty array is EXCLUDED: `ARRAY[]` without a cast has
+ *   no type, so its cast is load-bearing and stays.
+ *
+ * Anything the scanner does not positively recognize is left byte-for-byte unchanged — an
+ * unrecognized spelling is a MISS (drop + create, the pre-existing behavior), never a guess.
+ * Escalation is named, not implied: the SECOND cross-version variant found in the field is
+ * the trigger to adopt libpg_query and move identity onto normalized ASTs (Ty, 2026-08-09) —
+ * a growing rule table over raw text is where scanning stops being defensible.
+ *
+ * Applied at the PRODUCERS (live introspection's `predicate()`, the compiler's policy
+ * assembly), so every downstream comparison — the identity matcher, the canonical hash, the
+ * drift detail — sees normalized text without holding its own copy of this rule.
+ */
+
+/** `::text[]` / `::character varying[]` — the cast suffix after `(ARRAY[…])`. */
+const ARRAY_CAST_SUFFIX = /^::([A-Za-z_][A-Za-z0-9_]*(?:\s[A-Za-z_][A-Za-z0-9_]*)*)\[\]/;
+
+/**
+ * From an opening single or double quote, the index of its closing quote.
+ * SQL escapes a quote by doubling it; a doubled quote is content, not a close.
+ * Returns -1 on an unterminated literal (the caller then leaves the text alone).
+ */
+function skipQuoted(s: string, at: number): number {
+  const q = s[at];
+  for (let j = at + 1; j < s.length; j++) {
+    if (s[j] !== q) continue;
+    if (s[j + 1] === q) { j++; continue; }
+    return j;
+  }
+  return -1;
+}
+
+/** The index of the `]` closing the `[` at `open`, honoring nesting and quoted regions. */
+function matchBracket(s: string, open: number): number {
+  let sq = 0;
+  let par = 0;
+  for (let j = open; j < s.length; j++) {
+    const c = s[j];
+    if (c === "'" || c === '"') {
+      j = skipQuoted(s, j);
+      if (j < 0) return -1;
+    } else if (c === '[') sq++;
+    else if (c === ']') { sq--; if (sq === 0 && par === 0) return j; }
+    else if (c === '(') par++;
+    else if (c === ')') par--;
+  }
+  return -1;
+}
+
+/** Split on top-level commas (both nesting depths zero), or null on an unterminated literal. */
+function splitTopLevel(s: string): string[] | null {
+  const out: string[] = [];
+  let start = 0;
+  let sq = 0;
+  let par = 0;
+  for (let j = 0; j < s.length; j++) {
+    const c = s[j];
+    if (c === "'" || c === '"') {
+      j = skipQuoted(s, j);
+      if (j < 0) return null;
+    } else if (c === '[') sq++;
+    else if (c === ']') sq--;
+    else if (c === '(') par++;
+    else if (c === ')') par--;
+    else if (c === ',' && sq === 0 && par === 0) {
+      out.push(s.slice(start, j));
+      start = j + 1;
+    }
+  }
+  out.push(s.slice(start));
+  return out;
+}
+
+/** One left-to-right pass: rewrite the first recognized `(ARRAY[…])::T[]`, or null if none. */
+function distributeOnce(s: string): string | null {
+  let i = 0;
+  while ((i = s.indexOf('(ARRAY[', i)) !== -1) {
+    const open = i + 6; // the '['
+    const close = matchBracket(s, open);
+    if (close === -1) return null; // unparseable text — leave everything alone
+    if (s[close + 1] === ')') {
+      const m = ARRAY_CAST_SUFFIX.exec(s.slice(close + 2));
+      if (m) {
+        const inner = s.slice(open + 1, close);
+        const elements = splitTopLevel(inner);
+        // Empty array excluded: its cast carries the type. A failed split leaves the text alone.
+        if (elements !== null && inner.trim().length > 0) {
+          const t = m[1];
+          const rewritten = `ARRAY[${elements.map((e) => `(${e.trim()})::${t}`).join(', ')}]`;
+          return s.slice(0, i) + rewritten + s.slice(close + 2 + m[0].length);
+        }
+      }
+    }
+    i = open;
+  }
+  return null;
+}
+
+/**
+ * Normalize one deparsed expression. Idempotent; unrecognized text returns unchanged.
+ * Fixpoint-bounded: nesting deeper than the cap returns its progress, which is still
+ * deterministic — both sides of every comparison run this same function.
+ */
+export function normalizeDeparsedExpr(text: string): string {
+  let s = text;
+  for (let n = 0; n < 64; n++) {
+    const next = distributeOnce(s);
+    if (next === null) return s;
+    s = next;
+  }
+  return s;
+}

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
@@ -90,7 +93,11 @@ function holdDrop(sql: string): string {
  */
 export function unmodeledTables(models: ModelDescriptor[], current: SchemaSnapshot, opts: GenerateOptions = {}): string[] {
   const schema = opts.schema ?? 'public';
-  const declared = new Set(models.map((m) => `${schema}.${m.table}`));
+  // The model's OWN schema first — the same rule the compiler applies. Qualifying every
+  // model with the call default read a multi-schema checkout's non-public models as
+  // unmodeled: a consumer's plan listed three modeled tables as riding through untouched,
+  // which is a false statement about what the plan governs.
+  const declared = new Set(models.map((m) => `${m.schema ?? schema}.${m.table}`));
   // A pending table rename's OR move's source is ours — declared under its new (qualified)
   // name; without this it reads as an undeclared orphan (F1) and the move/rename silently
   // degrades to CREATE + leave-behind, the exact bug the markers exist to prevent.
@@ -136,6 +143,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))
@@ -233,6 +257,20 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   // The from-scratch path had this from the start; the diff path did not, so a non-public
   // model reached through db:sync/db:generate was unreachable by every role that did not
   // pick up USAGE some other way. The example app's analytics schema is what surfaced it.
+  // Diffed against the LIVE schema ACLs when the contract carries them. This phase used to
+  // emit unconditionally, so any plan with an authz statement re-granted USAGE the database
+  // already held — two false statements on every one of a consumer's stage plans (measured,
+  // catalog-verified, 2026-08-08). A role holds USAGE when its own nspacl entry says so or
+  // when PUBLIC's does (PUBLIC reaches every role). Membership-derived usage is invisible
+  // here and stays emitted — idempotent, and rarer than the direct grants that were the bug.
+  // No schemaAcls (fresh compose, older recorder) = unknown = emit, exactly as before.
+  const liveSchemaAcls = liveAuthzRenamed?.schemaAcls;
+  const hasLiveUsage = (s: string, role: string): boolean => {
+    const acl = liveSchemaAcls?.[s];
+    if (!acl) return false;
+    const key = role.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : role;
+    return (acl[key] ?? []).includes('USAGE') || (acl.PUBLIC ?? []).includes('USAGE');
+  };
   const usagePhase = authzPhase.length
     ? [...new Set(desiredContracts.map((c) => c.table.split('.')[0]))]
         .filter((s) => s !== 'public')
@@ -244,13 +282,14 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
             for (const r of Object.keys(c.grants)) roles.add(r);
             for (const r of Object.keys(c.columnGrants ?? {})) roles.add(r);
           }
-          if (!roles.size) return [];
-          const targets = [...roles].sort().map((r) => (r.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : r)).join(', ');
+          const missing = [...roles].filter((r) => !hasLiveUsage(s, r));
+          if (!missing.length) return [];
+          const targets = missing.sort().map((r) => (r.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : r)).join(', ');
           return [`GRANT USAGE ON SCHEMA "${s}" TO ${targets}`];
         })
     : [];
 
-  return [...schemaPhase, ...usagePhase, ...dataPhase, ...authzPhase];
+  return [...extensionPhase, ...schemaPhase, ...usagePhase, ...dataPhase, ...authzPhase];
 }
 
 /** The marker drizzle migration files put between statements. */

package/src/cli/schema-compile.ts

@@ -22,6 +22,7 @@
 import type { ModelDescriptor, FieldSpec, SequenceDescriptor } from '@everystack/model';
 import type { TableSchema, EnumType, SequenceSchema, UniqueConstraint, CheckConstraint, IndexSchema, ForeignKey } from './schema-introspect.js';
 import { nextvalSequence, type RenameMap } from './schema-diff.js';
+import { normalizeDeparsedExpr } from './deparse-normal.js';
 
 /** `authorId` -> `author_id`. SQL identifiers are snake_case. */
 export function toSnakeCase(name: string): string {
@@ -46,7 +47,10 @@ export function modelConstraintSpecs(model: ModelDescriptor): { uniques: UniqueC
       const cols = con.columns.map(toSnakeCase);
       uniques.push({ name: `${model.table}_${cols.join('_')}_unique`, columns: cols });
     } else if (con.kind === 'check') {
-      checks.push({ name: `${model.table}_check_${checkIndex++}`, expr: con.predicate });
+      // Normalized like the live producer (schema-introspect): a model that transcribes a
+      // pulled predicate must compare equal to the database it came from, whichever of the
+      // two equivalent deparse spellings each side happens to hold. See deparse-normal.ts.
+      checks.push({ name: `${model.table}_check_${checkIndex++}`, expr: normalizeDeparsedExpr(con.predicate) });
     } else if (con.kind === 'index') {
       // Plain entries are field keys → snake_cased; raw sql`` entries (expressions,
       // DESC, opclass) pass verbatim — they are already SQL (Brick E).
@@ -64,7 +68,7 @@ export function modelConstraintSpecs(model: ModelDescriptor): { uniques: UniqueC
         name,
         columns: cols,
         unique: con.isUnique,
-        ...(con.predicate ? { where: con.predicate } : {}),
+        ...(con.predicate ? { where: normalizeDeparsedExpr(con.predicate) } : {}),
         ...(con.method ? { using: con.method } : {}),
         ...(con.includeColumns?.length ? { include: con.includeColumns.map(toSnakeCase) } : {}),
       });
@@ -486,7 +490,9 @@ export function compileTableSchema(model: ModelDescriptor, opts: { schema?: stri
   const fieldChecks = entries.flatMap(([name, field]) => {
     const col = toSnakeCase(name);
     const pred = fieldCheckPredicate(col, field.spec);
-    return pred ? [{ name: `${model.table}_${col}_check`, expr: pred }] : [];
+    // Through the same funnel as every other predicate: a `z.enum([...])` compiles to an
+    // IN-list, which is exactly the shape whose deparse is unstable across a dump/restore.
+    return pred ? [{ name: `${model.table}_${col}_check`, expr: normalizeDeparsedExpr(pred) }] : [];
   });
   const checks = [...fieldChecks, ...tableConstraints.checks];
 

package/src/cli/schema-fingerprint.ts

@@ -110,7 +110,7 @@ import { normalizeDefault, normalizeCheck, indexKey } from './schema-diff.js';
 // it from the canonical form AND the reconciler leaves it alone, before and after. Restrictive
 // policies are never subsumed (they AND, so removing one would WIDEN), and the rule must match
 // exactly including the effective WITH CHECK.
-export const FINGERPRINT_VERSION = 8;
+export const FINGERPRINT_VERSION = 10;
 
 // ---------------------------------------------------------------------------
 // Canonical form.

package/src/cli/schema-introspect.ts

@@ -15,6 +15,7 @@
 
 import { IGNORED_SCHEMAS, coerceBool, type QueryRunner } from './authz-contract.js';
 import { INTROSPECTION_SESSION, type SessionRunner } from './session.js';
+import { normalizeDeparsedExpr } from './deparse-normal.js';
 
 // ---------------------------------------------------------------------------
 // The data-layer snapshot — the structured shape both producers target.
@@ -409,9 +410,12 @@ export function constraintRowToDescriptor(row: ConstraintRow): ConstraintDescrip
       onUpdate: action('UPDATE'),
     };
   }
-  // check — keep the predicate text inside the outer CHECK ( ... )
+  // check — keep the predicate text inside the outer CHECK ( ... ), normalized.
+  // `pg_get_expr` output is NOT a fixed point under re-parse: dump a CHECK and restore it
+  // and the same server deparses it differently (measured 2026-08-10, PG13-18 alike). A
+  // restored clone would then fingerprint differently from the database it was cloned from.
   const m = def.match(/^CHECK\s*\((.*)\)$/s);
-  return { table, name: row.name, kind: 'check', expr: m ? m[1].trim() : def };
+  return { table, name: row.name, kind: 'check', expr: normalizeDeparsedExpr(m ? m[1].trim() : def) };
 }
 
 // ---------------------------------------------------------------------------
@@ -491,6 +495,9 @@ export function parseIndexDefinition(definition: string): Omit<IndexSchema, 'nam
   let where = whereMatch ? whereMatch[1].trim() : '';
   // pg_get_indexdef wraps the predicate in one pair of parens — strip it.
   if (where.startsWith('(') && parenGroup(where, 0) === where.slice(1, -1)) where = where.slice(1, -1).trim();
+  // Same fixed-point failure as CHECK predicates: a partial index's WHERE survives a
+  // dump/restore as different text for the same predicate. Normalize at the producer.
+  where = normalizeDeparsedExpr(where);
   return {
     columns,
     unique: /^CREATE\s+UNIQUE\s+INDEX/i.test(definition),
@@ -504,7 +511,10 @@ export function parseIndexDefinition(definition: string): Omit<IndexSchema, 'nam
  *  a legacy row without one keeps the old plain-columns path, so fixtures stay valid.
  *  `is_unique`/`predicate`/`method` row fields take precedence over the parsed text. */
 export function indexRowToDescriptor(row: IndexRow): { table: string; index: IndexSchema } {
-  const pred = row.predicate == null ? '' : String(row.predicate);
+  // The row's own `predicate` column takes precedence over the parsed definition text, so
+  // it is the producer that must normalize — normalizing only the parse path left the
+  // predicate unstable across a dump/restore and the fingerprint with it.
+  const pred = row.predicate == null ? '' : normalizeDeparsedExpr(String(row.predicate));
   const table = `${row.schema}.${row.table}`;
   const base = { name: row.name, unique: coerceBool(row.is_unique), ...(pred ? { where: pred } : {}) };
 

package/src/cli/schema-source.ts

@@ -55,12 +55,23 @@ function strLiteral(value: string): string {
   return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
 
-/** A `.default(<v>)` argument literal for a value default (the JSON forms drizzle accepts). */
-function defaultValueLiteral(value: unknown): string {
+/**
+ * A `.default(<v>)` argument literal for a value default (the JSON forms drizzle accepts).
+ *
+ * `builder` is the drizzle column builder the value is a default FOR, because the accepted
+ * TYPE of the literal depends on it: drizzle's `numeric`/`decimal` take a STRING, since an
+ * arbitrary-precision default routed through a JS number is lossy by construction. A pulled
+ * model renders `field.numeric(4, 2).default(0.15)` — the model vocabulary accepting a number
+ * there is fine — and passing that straight through produced `.default(0.15)`, which fails
+ * `tsc --strict` with TS2345 and blocked a consumer from adopting the generated artifact.
+ */
+function defaultValueLiteral(value: unknown, builder?: string): string {
   if (typeof value === 'string') return strLiteral(value);
   if (typeof value === 'boolean') return value ? 'true' : 'false';
   if (value === null) return 'null';
-  if (typeof value === 'number') return String(value);
+  if (typeof value === 'number') {
+    return builder === 'numeric' || builder === 'decimal' ? strLiteral(String(value)) : String(value);
+  }
   // Arrays / objects: a JSON literal is valid TS for jsonb defaults.
   return JSON.stringify(value);
 }
@@ -159,6 +170,7 @@ function columnModifiers(
   spec: FieldSpec,
   isComposite: boolean,
   modelsByDescriptor: Map<ModelDescriptor, { camel: string }>,
+  ctx: { builder?: string; self?: ModelDescriptor; usedTypes?: Set<string> } = {},
 ): string {
   let s = '';
   if (spec.isArray) s += '.array()';
@@ -167,7 +179,7 @@ function columnModifiers(
 
   if (spec.defaultKind === 'now') s += '.defaultNow()';
   else if (spec.defaultKind === 'random') s += '.defaultRandom()';
-  else if (spec.defaultKind === 'value') s += `.default(${defaultValueLiteral(spec.default)})`;
+  else if (spec.defaultKind === 'value') s += `.default(${defaultValueLiteral(spec.default, ctx.builder)})`;
   else if (spec.defaultKind === 'sql') s += `.default(sql.raw(${strLiteral(String(spec.default))}))`;
 
   if (spec.isPrimaryKey && !isComposite) s += '.primaryKey()';
@@ -181,7 +193,17 @@ function columnModifiers(
       if (spec.onDelete) opts.push(`onDelete: ${strLiteral(spec.onDelete)}`);
       if (spec.onUpdate) opts.push(`onUpdate: ${strLiteral(spec.onUpdate)}`);
       const optsText = opts.length ? `, { ${opts.join(', ')} }` : '';
-      s += `.references(() => ${entry.camel}.${parentPk}${optsText})`;
+      // A SELF-referential FK needs drizzle's documented return-type annotation. Without it
+      // the table's own initializer references itself, TypeScript cannot infer it, and under
+      // `strict` it is TS7022 + TS7024 — which does not merely warn: the whole table
+      // degrades to `any`, so every query against it silently loses type safety in a project
+      // that otherwise builds. A reference to ANOTHER table infers fine and is left alone.
+      if (ctx.self && target === ctx.self) {
+        ctx.usedTypes?.add('AnyPgColumn');
+        s += `.references((): AnyPgColumn => ${entry.camel}.${parentPk}${optsText})`;
+      } else {
+        s += `.references(() => ${entry.camel}.${parentPk}${optsText})`;
+      }
     }
     // A reference to a model OUTSIDE the emitted set (a cross-schema FK) is omitted —
     // the runtime + relations never needed it; the DB constraint stays unmanaged.
@@ -333,6 +355,9 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
 
   // --- Track which pg-core builders + drizzle-orm symbols are used ----------
   const pgCoreBuilders = new Set<string>();
+  // TYPE-only imports from pg-core (today: AnyPgColumn, for self-referential FKs). Kept apart
+  // from the value imports so the emitted `import type` line carries no runtime cost.
+  const pgCoreTypes = new Set<string>();
   // Only when something actually lands in `public` — an all-non-public model set would
   // otherwise import a builder it never calls.
   if (models.some((m) => m.schema === 'public')) pgCoreBuilders.add('pgTable');
@@ -353,7 +378,7 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
       const { call, builder: pgBuilder } = baseColumnSource(toSnakeCase(key), spec);
       pgCoreBuilders.add(pgBuilder);
       if (spec.defaultKind === 'sql') pgCoreBuilders.add('sql'); // imported from 'drizzle-orm', handled below
-      const mods = columnModifiers(spec, isComposite, modelsByDescriptor);
+      const mods = columnModifiers(spec, isComposite, modelsByDescriptor, { builder: pgBuilder, self: model, usedTypes: pgCoreTypes });
       if (spec.isDeprecated) {
         // The contract phase (decision 13): the column stays in the database and
         // stays readable; the strikethrough warns new code away at author time.
@@ -457,7 +482,7 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
       pgCoreBuilders.add(pgBuilder);
       // Only .array()/.notNull() can appear — defineView/defineMaterializedView
       // reject every table-structural modifier at define time.
-      const mods = columnModifiers(spec, true, modelsByDescriptor);
+      const mods = columnModifiers(spec, true, modelsByDescriptor, { builder: pgBuilder });
       colLines.push(`  ${key}: ${call}${mods},`);
     }
     const cols = `{\n${colLines.join('\n')}\n}`;
@@ -501,6 +526,9 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
 
   const importLines: string[] = [];
   importLines.push(`import { ${pgCoreNames.join(', ')} } from 'drizzle-orm/pg-core';`);
+  if (pgCoreTypes.size) {
+    importLines.push(`import type { ${[...pgCoreTypes].sort().join(', ')} } from 'drizzle-orm/pg-core';`);
+  }
 
   const drizzleOrmNames: string[] = [];
   if (anyRelations) drizzleOrmNames.push('relations');

package/src/cli/state-apply.ts

@@ -347,6 +347,9 @@ export interface StateSyncOptions extends StateApplyOptions {
   allowDrops?: boolean;
   /** Standalone sequences — the verify re-diff must see the same declared state as the plan. */
   sequences?: SequenceDescriptor[];
+  /** Extensions the modules declare — the re-generated stream must carry them too, or a
+   *  verify-after re-plan disagrees with the plan that was applied. */
+  extensions?: string[];
 }
 
 export interface StateSyncOutcome {
@@ -406,7 +409,7 @@ export async function applyStateAndVerify(
   }
 
   const remaining = classifyGeneratedStatements(
-    generateMigrationSql(models, snapshot, { allowDrops: options.allowDrops, liveAuthz: contract, sequences: options.sequences }),
+    generateMigrationSql(models, snapshot, { allowDrops: options.allowDrops, liveAuthz: contract, sequences: options.sequences, extensions: options.extensions }),
   ).executable;
 
   return {