@everystack/cli 0.4.53 → 0.4.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.53",
+  "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/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-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/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
@@ -140,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))
@@ -269,7 +289,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/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 = 9;
+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 {