@everystack/cli 0.3.22 → 0.3.25

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

@@ -0,0 +1,220 @@
+/**
+ * `everystack db:template:refresh` + `everystack db:branch` — per-branch
+ * dev databases from a models-built template (brick 5-remainder,
+ * decision 14).
+ *
+ *   db:template:refresh [--database-url <url>] [--models <barrel>]
+ *                       [--sql-dir db/sql] [--seed "<cmd>"] [--no-seed]
+ *   db:branch                       # mint (or find) the current branch's DB
+ *   db:branch --list                # every branch DB, mapped to its branch
+ *   db:branch --drop --confirm      # drop the current branch's DB
+ *   db:branch --prune --confirm     # drop DBs whose git branch is gone
+ *
+ * The template is built FROM THE DECLARED STATE (both layers, fingerprint
+ * MATCH bar) plus seed-as-code — the app's own `db:seed` script, run as a
+ * subprocess with DATABASE_URL pointed at the fresh template. Never a data
+ * copy: deterministic, PII-free (real data enters branch testing through
+ * stage forks, brick 10). Branch databases mint via `CREATE DATABASE …
+ * TEMPLATE`, keyed on the git branch, and `db:sync` evolves them with the
+ * checkout — disposable by construction, never long-lived, never poisoned.
+ */
+
+import fs from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import type { ModelDescriptor } from '@everystack/model';
+import {
+  executeTemplateRefresh,
+  ensureBranchDatabase,
+  listBranchDatabases,
+  readTemplateProvenance,
+  prunableBranchDatabases,
+  dropBranchDatabase,
+  branchDatabaseName,
+  baseNameFromUrl,
+  templateName,
+  currentBranch,
+  localBranches,
+} from '../branch-db.js';
+import { currentGitRef } from '../state-apply.js';
+import { fingerprintModels } from '../schema-fingerprint.js';
+import { resolveDbSource, type DbSource } from '../db-source.js';
+import { resolveModelsPath } from '../models-path.js';
+import { readSqlDirIfPresent } from './db-sync.js';
+import { loadModels } from './db-generate.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+function requireUrl(flags: Record<string, string>, verb: string): string {
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  if (dbSource.kind !== 'url') {
+    fail(`${verb} manages local databases — it needs a direct connection (--database-url or DATABASE_URL).`);
+    process.exit(1);
+  }
+  return dbSource.url;
+}
+
+/** The seed convention: the app's own `db:seed` script from package.json. */
+async function detectSeedCommand(): Promise<string | null> {
+  try {
+    const pkg = JSON.parse(await fs.readFile('package.json', 'utf8'));
+    return pkg?.scripts?.['db:seed'] ? 'npm run db:seed' : null;
+  } catch {
+    return null;
+  }
+}
+
+function runSeedSubprocess(command: string, templateUrl: string): void {
+  const result = spawnSync(command, {
+    shell: true,
+    stdio: 'inherit',
+    env: { ...process.env, DATABASE_URL: templateUrl },
+  });
+  if (result.status !== 0) {
+    throw new Error(`seed command failed (exit ${result.status}): ${command}`);
+  }
+}
+
+export async function dbTemplateRefreshCommand(flags: Record<string, string>): Promise<void> {
+  const url = requireUrl(flags, 'db:template:refresh');
+
+  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);
+  }
+  const sources = await readSqlDirIfPresent(flags['sql-dir'] || 'db/sql');
+
+  let seedCommand: string | null = null;
+  if (flags['no-seed'] === 'true') {
+    info('Seeding skipped (--no-seed).');
+  } else if (flags.seed && flags.seed !== 'true') {
+    seedCommand = flags.seed;
+  } else {
+    seedCommand = await detectSeedCommand();
+    if (seedCommand) info(`Seed: package.json db:seed script (override with --seed "<cmd>" / --no-seed).`);
+    else warn('No db:seed script in package.json — the template builds UNSEEDED (declare one, or pass --seed "<cmd>").');
+  }
+
+  const template = templateName(baseNameFromUrl(url));
+  step(`Rebuilding ${template} from the declared state (drop → create → sync both layers → seed)...`);
+  try {
+    const result = await executeTemplateRefresh(url, models, {
+      sources,
+      actor: process.env.USER ?? null,
+      gitRef: currentGitRef(),
+      seed: seedCommand === null ? null : (templateUrl) => {
+        step(`Seeding: ${seedCommand} (DATABASE_URL → ${redactUrl(templateUrl)})...`);
+        runSeedSubprocess(seedCommand!, templateUrl);
+        return Promise.resolve();
+      },
+    });
+    for (const line of result.report) info(`  ${line}`);
+    success(`Template ${result.database} is the declared state at ${result.fingerprint.slice(0, 12)}${seedCommand ? ', seeded' : ''}. Mint branch databases: everystack db:branch`);
+  } catch (err: any) {
+    fail(`Template refresh failed — no template was left behind (all or nothing): ${err.message}`);
+    process.exit(1);
+  }
+}
+
+/** Redact credentials when echoing a URL. */
+function redactUrl(url: string): string {
+  return url.replace(/\/\/[^@/]+@/, '//***@');
+}
+
+export async function dbBranchCommand(flags: Record<string, string>): Promise<void> {
+  const url = requireUrl(flags, 'db:branch');
+
+  if (flags.list === 'true') {
+    const provenance = await readTemplateProvenance(url);
+    if (provenance) {
+      info(`template ${templateName(baseNameFromUrl(url))}: fingerprint ${provenance.fingerprint.slice(0, 12)}, built ${provenance.builtAt}${provenance.gitRef ? ` at ${provenance.gitRef.slice(0, 12)}` : ''}`);
+    } else {
+      warn(`no template — build it once: everystack db:template:refresh`);
+    }
+    const all = await listBranchDatabases(url);
+    if (all.length === 0) {
+      info('no branch databases.');
+      return;
+    }
+    const live = new Set(localBranches());
+    for (const d of all) {
+      const state = d.branch === null ? 'branch unknown (comment lost)' : live.has(d.branch) ? d.branch : `${d.branch} — branch GONE (db:branch --prune)`;
+      info(`  ${d.database}  ←  ${state}`);
+    }
+    return;
+  }
+
+  if (flags.prune === 'true') {
+    const dead = prunableBranchDatabases(await listBranchDatabases(url), localBranches());
+    if (dead.length === 0) {
+      success('Nothing to prune — every branch database maps to a live branch.');
+      return;
+    }
+    for (const d of dead) info(`  ${d.database}  ←  ${d.branch} (gone)`);
+    if (flags.confirm !== 'true') {
+      fail(`Would drop the ${dead.length} database(s) above — confirm with --confirm.`);
+      process.exit(1);
+    }
+    for (const d of dead) {
+      await dropBranchDatabase(url, d.database);
+      info(`dropped ${d.database}`);
+    }
+    success(`Pruned ${dead.length} branch database(s).`);
+    return;
+  }
+
+  const branch = currentBranch();
+  if (branch === null) {
+    fail('db:branch is keyed on the git branch — not a repository, or detached HEAD.');
+    process.exit(1);
+  }
+
+  if (flags.drop === 'true') {
+    const database = branchDatabaseName(baseNameFromUrl(url), branch);
+    if (flags.confirm !== 'true') {
+      fail(`Would drop ${database} (branch ${branch}) — confirm with --confirm.`);
+      process.exit(1);
+    }
+    await dropBranchDatabase(url, database);
+    success(`Dropped ${database}.`);
+    return;
+  }
+
+  const result = await ensureBranchDatabase(url, branch);
+  switch (result.status) {
+    case 'no-template':
+      fail(`No template ${result.template} — build it once: everystack db:template:refresh. Branch databases mint from it.`);
+      process.exit(1);
+      break;
+    case 'exists':
+      info(`${result.database} already exists for branch ${branch}.`);
+      break;
+    case 'created': {
+      success(`Minted ${result.database} from ${result.template} (branch ${branch}).`);
+      try {
+        const provenance = await readTemplateProvenance(url);
+        const declared = fingerprintModels(await loadModels(resolveModelsPath(flags.models))).hash;
+        if (provenance && provenance.fingerprint !== declared) {
+          info(`· your checkout declares ${declared.slice(0, 12)}; the template was built at ${provenance.fingerprint.slice(0, 12)} — db:sync below evolves it (refresh the template when it drifts far).`);
+        }
+      } catch {
+        // The staleness note is best-effort — minting already succeeded.
+      }
+      break;
+    }
+  }
+  console.log('');
+  console.log(`  export DATABASE_URL="${result.url}"`);
+  console.log('');
+  info(`then: everystack db:sync    # evolve it with your checkout as you edit`);
+}

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

@@ -28,20 +28,22 @@
  */
 
 import fs from 'node:fs/promises';
-import postgres from 'postgres';
 import type { ModelDescriptor } from '@everystack/model';
-import type { TableContract } from '../authz-contract.js';
 import { compileDeclaredState } from '../declared-diff.js';
 import { compileMigration } from '../migration-compile.js';
 import { compileDrizzleSource } from '../schema-source.js';
 import { parseSqlSources, type SourceFile } from '../derived-source.js';
 import { currentGitRef } from '../state-apply.js';
-import { createUrlRunner } from '../db-source.js';
+import { createDatabase, dropDatabase, buildIntoDatabase, withDatabase } from '../db-build.js';
 import { resolveModelsPath } from '../models-path.js';
-import { executeSync, buildSyncReport, readSqlDirIfPresent } from './db-sync.js';
+import { readSqlDirIfPresent } from './db-sync.js';
 import { loadModels } from './db-generate.js';
 import { step, success, fail, info, warn } from '../output.js';
 
+// The role derivation moved to the shared builder (db-build) with brick
+// 5-remainder; re-exported here because db:check is where it grew up.
+export { rolesFromContract } from '../db-build.js';
+
 const DEFAULT_SQL_DIR = 'db/sql';
 const DEFAULT_SCHEMA_OUT = 'db/schema.generated.ts';
 
@@ -145,19 +147,6 @@ export function checkFailed(findings: CheckFinding[]): boolean {
 // The ephemeral compose ring.
 // ---------------------------------------------------------------------------
 
-/** Every role the contract grants to or names in a policy — the compose DB needs them. */
-export function rolesFromContract(tables: TableContract[]): string[] {
-  const roles = new Set<string>();
-  for (const t of tables) {
-    for (const grantee of Object.keys(t.grants)) roles.add(grantee);
-    for (const grantee of Object.keys(t.columnGrants ?? {})) roles.add(grantee);
-    for (const p of t.policies) for (const r of p.roles) roles.add(r);
-  }
-  roles.delete('PUBLIC');
-  roles.delete('public');
-  return [...roles].sort();
-}
-
 export interface EphemeralComposeResult {
   database: string;
   createdRoles: string[];
@@ -168,12 +157,10 @@ export interface EphemeralComposeResult {
 }
 
 /**
- * Build the declared state from scratch on an ephemeral database: CREATE
- * DATABASE, roles the contract references (NOLOGIN, cluster-level, created
- * only if absent), one `executeSync` for both layers, DROP DATABASE —
- * always, error or not. The bar is `converged && fingerprintMatch`: a
- * fresh database has nothing unmodeled and nothing to drop, so anything
- * short of MATCH is a real compose fault.
+ * Build the declared state from scratch on an ephemeral database (the
+ * shared db-build core), then DROP it — always, error or not. The bar is
+ * `converged && fingerprintMatch`: a fresh database has nothing unmodeled
+ * and nothing to drop, so anything short of MATCH is a real compose fault.
  */
 export async function executeEphemeralCompose(
   adminUrl: string,
@@ -181,46 +168,17 @@ export async function executeEphemeralCompose(
   sources: SourceFile[] | null,
   opts: { actor?: string | null; gitRef?: string | null } = {},
 ): Promise<EphemeralComposeResult> {
-  const dbName = `escheck_${process.pid}_${Date.now()}`;
-  const admin = postgres(adminUrl, { max: 1 });
-  try {
-    await admin.unsafe(`CREATE DATABASE "${dbName}"`);
-  } finally {
-    await admin.end();
-  }
-
-  const { runner, end } = await createUrlRunner(adminUrl.replace(/\/[^/?]+(\?|$)/, `/${dbName}$1`));
+  const database = `escheck_${process.pid}_${Date.now()}`;
+  await createDatabase(adminUrl, database);
   try {
-    const roles = rolesFromContract(compileDeclaredState(models).contract.tables);
-    for (const role of roles) {
-      if (!/^[a-z_][a-z0-9_$]*$/i.test(role)) {
-        throw new Error(`contract references a role name that is not a plain identifier: ${JSON.stringify(role)}`);
-      }
-      await runner(
-        `DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${role}') THEN CREATE ROLE "${role}" NOLOGIN; END IF; END $$`,
-      );
-    }
-
-    const run = await executeSync(runner, models, sources, {
+    const built = await buildIntoDatabase(withDatabase(adminUrl, database), models, {
+      sources,
       actor: opts.actor ?? 'db:check',
       gitRef: opts.gitRef ?? null,
     });
-    return {
-      database: dbName,
-      createdRoles: roles,
-      converged: run.converged,
-      fingerprintMatch: run.fingerprintMatch,
-      fingerprint: run.state.toFingerprint,
-      report: buildSyncReport(run),
-    };
+    return { database, ...built };
   } finally {
-    await end?.();
-    const reaper = postgres(adminUrl, { max: 1 });
-    try {
-      await reaper.unsafe(`DROP DATABASE IF EXISTS "${dbName}" WITH (FORCE)`);
-    } finally {
-      await reaper.end();
-    }
+    await dropDatabase(adminUrl, database);
   }
 }
 

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

@@ -25,6 +25,8 @@ import { introspectSchema } from '../schema-introspect.js';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog.js';
 import { mintEdgePlan, planHash, buildPlanSummary } from '../edge-plan.js';
 import { verifyDescent } from '../git-descent.js';
+import { planBackfills, readBackfillLog } from '../backfill.js';
+import { readSqlDirIfPresent } from './db-sync.js';
 import { currentGitRef } from '../state-apply.js';
 import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
 import { resolveModelsPath } from '../models-path.js';
@@ -113,6 +115,25 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
         warn('db:apply from this checkout will refuse this plan — rebase first, then re-mint.');
       }
     }
+
+    // Visibility, never automation (brick 8): the review surface names the
+    // target's pending backfills — expand → backfill → contract stays a
+    // sequence of deliberate acts, and a contraction plan minted while its
+    // data move is unrun should be caught by the human reading this.
+    const backfillFiles = await readSqlDirIfPresent('db/backfills');
+    if (backfillFiles !== null) {
+      try {
+        const bf = planBackfills(backfillFiles, await readBackfillLog(runner));
+        if (bf.blocked.length > 0) {
+          warn(`${bf.blocked.length} backfill(s) BLOCKED on this target (edited after running) — everystack db:backfill names the fix.`);
+        }
+        if (bf.pending.length > 0) {
+          warn(`${bf.pending.length} backfill(s) pending on this target: ${bf.pending.map((p) => p.file).join(', ')} — run them deliberately (db:backfill --apply) before a contraction lands.`);
+        }
+      } catch (err: any) {
+        warn(`backfill lane: could not read everystack.backfill_log (${err.message}) — pending-backfill visibility unavailable.`);
+      }
+    }
     if (out !== '-') {
       success(`Wrote ${out} — review it, then \`everystack db:apply --plan ${out}\`.`);
       warn('Plans are ephemeral release artifacts — attach to the run, do NOT commit.');

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

@@ -37,6 +37,7 @@ import { generateMigrationSql, unmodeledTables } from '../migration-generate.js'
 import {
   applyStateAndVerify,
   classifyGeneratedStatements,
+  classifyDestructive,
   currentGitRef,
   type ClassifiedStatements,
   type StateSyncOutcome,
@@ -45,6 +46,7 @@ import { fingerprintModels } from '../schema-fingerprint.js';
 import { compileDrizzleSource } from '../schema-source.js';
 import type { SourceFile } from '../derived-source.js';
 import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { planBackfills, readBackfillLog } from '../backfill.js';
 import { resolveModelsPath } from '../models-path.js';
 import { executeReconcile, buildReconcileReport, type ReconcileRun } from './db-reconcile.js';
 import { loadModels } from './db-generate.js';
@@ -277,6 +279,10 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
         onStatePlan: (statements, classified) => {
           if (classified.executable.length > 0) {
             info(`state plan — ${classified.executable.length} statement(s):`);
+            const { drops, narrowings } = classifyDestructive(classified.executable);
+            if (drops.length + narrowings.length > 0) {
+              warn(`${drops.length + narrowings.length} DESTRUCTIVE — ${drops.length} drop(s), ${narrowings.length} narrowing type change(s). Dev sync runs them; protected stages gate them (db:plan → db:apply).`);
+            }
             console.log('');
             for (const s of statements) console.log(s.endsWith(';') ? s : `${s};`);
             console.log('');
@@ -289,8 +295,22 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
       },
     );
 
+    // Visibility, never automation (brick 8): pending backfills surface
+    // here, but a schema verb never runs a data job.
+    let backfills: { pending: number; blocked: number } | null = null;
+    const backfillFiles = await readSqlDirIfPresent('db/backfills');
+    if (backfillFiles !== null) {
+      try {
+        const bf = planBackfills(backfillFiles, await readBackfillLog(runner));
+        backfills = { pending: bf.pending.length, blocked: bf.blocked.length };
+      } catch (err: any) {
+        warn(`backfill lane: could not read everystack.backfill_log (${err.message}) — pending-backfill visibility unavailable.`);
+      }
+    }
+
     if (flags.json === 'true') {
       console.log(JSON.stringify({
+        backfills,
         state: {
           applied: run.state.applied,
           executed: run.state.classified.executable.length,
@@ -312,6 +332,12 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
       }, null, 2));
     } else {
       for (const line of buildSyncReport(run)) info(line);
+      if (backfills && backfills.blocked > 0) {
+        warn(`${backfills.blocked} backfill(s) BLOCKED (edited after running) — everystack db:backfill names the fix.`);
+      }
+      if (backfills && backfills.pending > 0) {
+        info(`· ${backfills.pending} backfill(s) pending — data jobs run deliberately, never as a sync side effect: everystack db:backfill --apply`);
+      }
       console.log('');
       if (!run.converged) {
         fail('NOT converged — fix the findings above and re-run db:sync.');

package/src/cli/db-build.ts

@@ -0,0 +1,161 @@
+/**
+ * db-build — build a database FROM the declared state (brick 5-remainder's
+ * shared core; decision 14: models-built, never data copies).
+ *
+ * One builder, three consumers: `db:check`'s ephemeral compose ring, the
+ * dev template (`db:template:refresh`), and `createEphemeralDatabase` — the
+ * exported test-database helper (the create-sync-drop shape this repo's own
+ * integration harness proves on every run, packaged for consumers). The bar
+ * is always the brick-2 identity: a fresh database built from the declared
+ * state lands EXACTLY on the models' fingerprint.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import type { TableContract, QueryRunner } from './authz-contract.js';
+import type { SourceFile } from './derived-source.js';
+import { compileDeclaredState } from './declared-diff.js';
+import { createUrlRunner } from './db-source.js';
+import { executeSync, buildSyncReport } from './commands/db-sync.js';
+
+const SAFE_NAME = /^[a-z_][a-z0-9_$]*$/;
+
+function assertSafeName(name: string, what: string): void {
+  if (!SAFE_NAME.test(name)) {
+    throw new Error(`${what} ${JSON.stringify(name)} is not a plain lowercase identifier — everystack manages databases it can name without quoting games.`);
+  }
+}
+
+/** Swap the database path segment of a connection URL. */
+export function withDatabase(url: string, database: string): string {
+  if (!/\/[^/?]+(\?|$)/.test(url)) {
+    throw new Error('the connection URL names no database — add the path segment (postgres://…/mydb)');
+  }
+  return url.replace(/\/[^/?]+(\?|$)/, `/${database}$1`);
+}
+
+/** Every role the contract grants to or names in a policy — a fresh database needs them. */
+export function rolesFromContract(tables: TableContract[]): string[] {
+  const roles = new Set<string>();
+  for (const t of tables) {
+    for (const grantee of Object.keys(t.grants)) roles.add(grantee);
+    for (const grantee of Object.keys(t.columnGrants ?? {})) roles.add(grantee);
+    for (const p of t.policies) for (const r of p.roles) roles.add(r);
+  }
+  roles.delete('PUBLIC');
+  roles.delete('public');
+  return [...roles].sort();
+}
+
+/** Create the contract's roles, NOLOGIN, only if absent (roles are cluster-level). */
+export async function ensureContractRoles(runner: QueryRunner, models: ModelDescriptor[]): Promise<string[]> {
+  const roles = rolesFromContract(compileDeclaredState(models).contract.tables);
+  for (const role of roles) {
+    assertSafeName(role, 'contract role');
+    await runner(
+      `DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${role}') THEN CREATE ROLE "${role}" NOLOGIN; END IF; END $$`,
+    );
+  }
+  return roles;
+}
+
+export async function createDatabase(adminUrl: string, name: string, template?: string): Promise<void> {
+  assertSafeName(name, 'database name');
+  if (template !== undefined) assertSafeName(template, 'template name');
+  const { runner, end } = await createUrlRunner(adminUrl);
+  try {
+    await runner(`CREATE DATABASE "${name}"${template ? ` TEMPLATE "${template}"` : ''}`);
+  } finally {
+    await end?.();
+  }
+}
+
+export async function dropDatabase(adminUrl: string, name: string): Promise<void> {
+  assertSafeName(name, 'database name');
+  const { runner, end } = await createUrlRunner(adminUrl);
+  try {
+    await runner(`DROP DATABASE IF EXISTS "${name}" WITH (FORCE)`);
+  } finally {
+    await end?.();
+  }
+}
+
+export interface BuildResult {
+  converged: boolean;
+  fingerprintMatch: boolean;
+  fingerprint: string;
+  createdRoles: string[];
+  report: string[];
+}
+
+export interface BuildOptions {
+  sources?: SourceFile[] | null;
+  actor?: string | null;
+  gitRef?: string | null;
+}
+
+/**
+ * Sync a (typically fresh) database to the declared state — both layers —
+ * and report against the MATCH bar. Opens and closes its own connection,
+ * so the database is immediately usable as a `TEMPLATE` source afterwards.
+ */
+export async function buildIntoDatabase(
+  url: string,
+  models: ModelDescriptor[],
+  options: BuildOptions = {},
+): Promise<BuildResult> {
+  const { runner, end } = await createUrlRunner(url);
+  try {
+    const createdRoles = await ensureContractRoles(runner, models);
+    const run = await executeSync(runner, models, options.sources ?? null, {
+      actor: options.actor ?? 'db-build',
+      gitRef: options.gitRef ?? null,
+    });
+    return {
+      converged: run.converged,
+      fingerprintMatch: run.fingerprintMatch,
+      fingerprint: run.state.toFingerprint,
+      createdRoles,
+      report: buildSyncReport(run),
+    };
+  } finally {
+    await end?.();
+  }
+}
+
+export interface EphemeralDatabase {
+  database: string;
+  url: string;
+  fingerprint: string;
+  drop: () => Promise<void>;
+}
+
+/**
+ * The packaged create-sync-drop shape for consumer test suites: a fresh
+ * database at the declared state (state + authz + derived layer), never
+ * long-lived, so never poisoned. Throws (and drops) unless the build lands
+ * MATCH — a test database that isn't the declared state proves nothing.
+ */
+export async function createEphemeralDatabase(
+  adminUrl: string,
+  models: ModelDescriptor[],
+  options: BuildOptions & { name?: string } = {},
+): Promise<EphemeralDatabase> {
+  const database = options.name ?? `eph_${process.pid}_${Date.now()}`;
+  await createDatabase(adminUrl, database);
+  const url = withDatabase(adminUrl, database);
+  try {
+    const built = await buildIntoDatabase(url, models, options);
+    if (!(built.converged && built.fingerprintMatch)) {
+      throw new Error(`the ephemeral database did not land on the declared state:\n${built.report.join('\n')}`);
+    }
+    return {
+      database,
+      url,
+      fingerprint: built.fingerprint,
+      drop: () => dropDatabase(adminUrl, database),
+    };
+  } catch (err) {
+    await dropDatabase(adminUrl, database).catch(() => {});
+    throw err;
+  }
+}

package/src/cli/derived-source.ts

@@ -62,7 +62,7 @@ export interface ParsedSources {
 // Lexer.
 // ---------------------------------------------------------------------------
 
-type LexState =
+export type LexState =
   | { in: 'normal' }
   | { in: 'single'; escaped: boolean }
   | { in: 'double' }
@@ -82,7 +82,8 @@ function dollarTagAt(text: string, i: number): string | null {
  * (comments/strings/normal). The shared core under both the statement splitter
  * and the normalizer, so they can never disagree about where a string ends.
  */
-function lex(
+/** The dollar-quote-aware SQL lexer — exported for siblings that need string-safe scans (the backfill lane). */
+export function lex(
   text: string,
   emit: (ch: string, state: LexState['in'], index: number) => void,
 ): void {