@everystack/cli 0.3.23 → 0.3.25

package/README.md

@@ -223,6 +223,9 @@ everystack db:diff                      # the state edge between two declared st
 everystack db:plan | db:apply           # mint a reviewable plan against a target, apply it fingerprint-verified at both ends + the fast-forward rule (checkout must descend from the commit declaring the target's state); destructive plans: --confirm + snapshot + approver set when declared
 everystack db:check                     # the CI gate per PR: merged declared state composes + artifacts match regeneration (+ ephemeral from-scratch build w/ a scratch PG)
 everystack db:approvers                 # declare who can DESTROY: the stage's destructive-approver set (SSM, STS-verified at apply)
+everystack db:backfill                  # one-shot data jobs in db/backfills/*.sql — content-hash identity, own per-DB record, never a schema side effect
+everystack db:template:refresh          # (re)build the dev template from the declared state + your db:seed script — never a data copy
+everystack db:branch                    # per-branch dev DB minted from the template, keyed on the git branch (--list / --prune --confirm)
 
 # Security
 everystack db:doctor                    # is the DB least-privilege + RLS-subject?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.23",
+  "version": "0.3.25",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/cli/backfill.ts

@@ -0,0 +1,231 @@
+/**
+ * backfill — one-shot data jobs in their own lane (brick 8 of the
+ * migration-authority design, decision 15).
+ *
+ * Schema is fingerprint-governed; DATA has no live authority to fingerprint,
+ * so the backfill lane is the one place a per-database ledger is correct:
+ * `everystack.backfill_log` records what ran here, and the runner READS it —
+ * unlike `schema_log`, which stays a write-only memoir. The distrust that
+ * killed the migration tape doesn't transfer: nothing is numbered, nothing
+ * is watermarked, and identity is the NORMALIZED CONTENT HASH (the same
+ * comment-insensitive, dollar-quote-aware lexing as db/sql) — renaming a
+ * file or editing a comment is a no-op, never a re-run.
+ *
+ * One-shot jobs are IMMUTABLE. A file whose name already ran on this
+ * database in a different form is BLOCKED, loudly, with the fix named: a
+ * genuinely new job gets a new file; a cosmetic-but-not-comment edit gets
+ * `--mark-applied`. Never silently re-run, never silently skipped. A prior
+ * FAILED run is a retry, not an edit — it stays pending.
+ *
+ * Backfills never run as a side effect of a schema apply (expand →
+ * backfill → contract is a sequence of deliberate acts); the schema verbs
+ * only SURFACE pending backfills as notices. Long-running smells get an
+ * advisory naming the jobs lane — advisory only, taste is not enforced.
+ */
+
+import { createHash } from 'node:crypto';
+import { lex, normalizeSql, splitSqlStatements, type SourceFile } from './derived-source.js';
+import { escapeLiteral } from './derived-apply.js';
+import type { QueryRunner } from './authz-contract.js';
+
+// ---------------------------------------------------------------------------
+// Identity + advisories (pure).
+// ---------------------------------------------------------------------------
+
+/** The job's identity: sha256 over the comment-insensitive canonical form. */
+export function backfillIdentity(sql: string): string {
+  return createHash('sha256').update(normalizeSql(sql)).digest('hex');
+}
+
+/**
+ * The statement with comments dropped and quoted content blanked — a shape
+ * regexes can interrogate without being fooled by `'WHERE it hurts'`.
+ */
+function sqlSkeleton(sql: string): string {
+  let out = '';
+  lex(sql, (ch, state) => {
+    if (state === 'line-comment' || state === 'block-comment') return;
+    if (state === 'single' || state === 'dollar') return; // quoted content blanked
+    out += ch;
+  });
+  return out;
+}
+
+/** Advisory only — an unbounded data pass belongs in the jobs lane, but taste never blocks. */
+export function backfillAdvisories(sql: string): string[] {
+  const advisories: string[] = [];
+  for (const statement of splitSqlStatements(sql)) {
+    const skeleton = sqlSkeleton(statement);
+    const verb = skeleton.match(/^\s*(UPDATE|DELETE)\b/i)?.[1];
+    if (verb && !/\bWHERE\b/i.test(skeleton)) {
+      advisories.push(
+        `${verb.toUpperCase()} without WHERE — an unbounded pass over the table. Fine for small tables; for big ones, batch it or run it as a job (@everystack/jobs).`,
+      );
+    }
+  }
+  return advisories;
+}
+
+// ---------------------------------------------------------------------------
+// Planning (pure).
+// ---------------------------------------------------------------------------
+
+export interface BackfillRecord {
+  name: string;
+  identity: string;
+  outcome: string; // 'applied' | 'marked-applied' | 'failed'
+}
+
+export interface BackfillPlan {
+  applied: { file: string; identity: string }[];
+  /** To run, in file-name order. */
+  pending: { file: string; identity: string; sql: string; advisories: string[] }[];
+  /** Edited-after-run — refused with the fix named. */
+  blocked: { file: string; identity: string; reason: string }[];
+}
+
+const baseName = (file: string): string => file.split('/').pop() ?? file;
+const counts = (outcome: string): boolean => outcome === 'applied' || outcome === 'marked-applied';
+
+export function planBackfills(files: SourceFile[], log: BackfillRecord[]): BackfillPlan {
+  const appliedIdentities = new Set(log.filter((r) => counts(r.outcome)).map((r) => r.identity));
+  const appliedByName = new Map<string, string>(); // name → identity that ran under it
+  for (const r of log) {
+    if (counts(r.outcome)) appliedByName.set(r.name, r.identity);
+  }
+
+  const plan: BackfillPlan = { applied: [], pending: [], blocked: [] };
+  for (const file of [...files].sort((a, b) => baseName(a.file).localeCompare(baseName(b.file)))) {
+    const identity = backfillIdentity(file.sql);
+    if (appliedIdentities.has(identity)) {
+      plan.applied.push({ file: file.file, identity });
+      continue;
+    }
+    const ranAs = appliedByName.get(baseName(file.file));
+    if (ranAs !== undefined && ranAs !== identity) {
+      plan.blocked.push({
+        file: file.file,
+        identity,
+        reason:
+          `${baseName(file.file)} already ran on this database in a different form — one-shot jobs are immutable. ` +
+          'A genuinely new job gets a NEW file name; if this edit changed nothing the job does, record it: --mark-applied.',
+      });
+      continue;
+    }
+    plan.pending.push({ file: file.file, identity, sql: file.sql, advisories: backfillAdvisories(file.sql) });
+  }
+  return plan;
+}
+
+// ---------------------------------------------------------------------------
+// The record + the runner.
+// ---------------------------------------------------------------------------
+
+export const ENSURE_BACKFILL_SQL: string[] = [
+  'CREATE SCHEMA IF NOT EXISTS everystack',
+  `CREATE TABLE IF NOT EXISTS everystack.backfill_log (
+  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  applied_at timestamptz NOT NULL DEFAULT now(),
+  identity text NOT NULL,
+  name text NOT NULL,
+  actor text,
+  git_ref text,
+  sql text NOT NULL,
+  duration_ms integer,
+  outcome text NOT NULL
+)`,
+];
+
+export interface BackfillLogEntry {
+  identity: string;
+  name: string;
+  sql: string;
+  outcome: string;
+  actor?: string | null;
+  gitRef?: string | null;
+  durationMs?: number;
+}
+
+export function renderBackfillLogInsert(entry: BackfillLogEntry): string {
+  const opt = (v: string | null | undefined): string => (v == null ? 'NULL' : escapeLiteral(v));
+  const duration = entry.durationMs === undefined ? 'NULL' : String(Math.round(entry.durationMs));
+  return `INSERT INTO everystack.backfill_log (identity, name, actor, git_ref, sql, duration_ms, outcome)
+VALUES (${escapeLiteral(entry.identity)}, ${escapeLiteral(entry.name)}, ${opt(entry.actor)}, ${opt(entry.gitRef)}, ${escapeLiteral(entry.sql)}, ${duration}, ${escapeLiteral(entry.outcome)})`;
+}
+
+/** The applied record for this database. Empty when the lane has never run here. */
+export async function readBackfillLog(runner: QueryRunner): Promise<BackfillRecord[]> {
+  const rows = await runner(`
+    SELECT name, identity, outcome FROM everystack.backfill_log ORDER BY id
+  `).catch((err: any) => {
+    if (/relation .*backfill_log.* does not exist|schema .* does not exist/i.test(err.message ?? '')) return [];
+    throw err;
+  });
+  return rows as BackfillRecord[];
+}
+
+export interface BackfillRunOptions {
+  actor?: string | null;
+  gitRef?: string | null;
+  /** Injectable clock for tests. */
+  now?: () => number;
+}
+
+export interface BackfillRunResult {
+  ran: { file: string; identity: string; durationMs: number }[];
+  /** The first failure, if any — the run STOPS there (later files may depend on it). */
+  failed?: { file: string; identity: string; error: string };
+}
+
+/**
+ * Run the pending jobs in order, each as its own single batch (one implicit
+ * transaction per job — a failed job rolls back alone and is recorded as
+ * `failed`, staying pending for the retry). Blocked files never execute.
+ */
+export async function executeBackfills(
+  runner: QueryRunner,
+  plan: BackfillPlan,
+  options: BackfillRunOptions = {},
+): Promise<BackfillRunResult> {
+  const now = options.now ?? Date.now;
+  const result: BackfillRunResult = { ran: [] };
+  if (plan.pending.length === 0) return result;
+
+  await runner(ENSURE_BACKFILL_SQL.join(';\n'));
+  for (const job of plan.pending) {
+    const name = baseName(job.file);
+    const started = now();
+    try {
+      await runner(job.sql);
+      const durationMs = now() - started;
+      await runner(renderBackfillLogInsert({
+        identity: job.identity, name, sql: job.sql, outcome: 'applied',
+        actor: options.actor, gitRef: options.gitRef, durationMs,
+      }));
+      result.ran.push({ file: job.file, identity: job.identity, durationMs });
+    } catch (err: any) {
+      await runner(renderBackfillLogInsert({
+        identity: job.identity, name, sql: `-- FAILED: ${err.message}\n${job.sql}`, outcome: 'failed',
+        actor: options.actor, gitRef: options.gitRef, durationMs: now() - started,
+      }));
+      result.failed = { file: job.file, identity: job.identity, error: err.message };
+      return result;
+    }
+  }
+  return result;
+}
+
+/** The adopt hatch: record a job as applied WITHOUT running it (mirrors --baseline). */
+export async function markBackfillApplied(
+  runner: QueryRunner,
+  file: SourceFile,
+  options: BackfillRunOptions = {},
+): Promise<string> {
+  const identity = backfillIdentity(file.sql);
+  await runner(ENSURE_BACKFILL_SQL.join(';\n'));
+  await runner(renderBackfillLogInsert({
+    identity, name: baseName(file.file), sql: file.sql, outcome: 'marked-applied',
+    actor: options.actor, gitRef: options.gitRef,
+  }));
+  return identity;
+}

package/src/cli/branch-db.ts

@@ -0,0 +1,269 @@
+/**
+ * branch-db — per-branch dev databases from a models-built template
+ * (brick 5-remainder of the migration-authority design, decision 14).
+ *
+ * The original wound: one shared dev database, poisoned by every branch
+ * switch. The cure: the dev template `<base>_tpl` is built FROM THE
+ * DECLARED STATE plus seed-as-code — deterministic, PII-free, refreshed by
+ * an explicit `db:template:refresh`, never a data copy (real data enters
+ * branch testing only through stage forks, brick 10) — and each branch
+ * gets its own database, minted `CREATE DATABASE … TEMPLATE`, keyed on the
+ * git branch. `db:sync` then evolves it with the checkout. Branch
+ * databases are disposable by construction: never long-lived, never
+ * poisoned.
+ *
+ * Names are deterministic lowercase identifiers; branches that clean to
+ * the same text (`feat/foo` vs `feat_foo`) get a disambiguating content
+ * hash. The raw branch name travels as a database COMMENT, so listing and
+ * pruning map databases back to branches without guessing — a database
+ * whose comment is gone is never pruned.
+ */
+
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import type { ModelDescriptor } from '@everystack/model';
+import type { QueryRunner } from './authz-contract.js';
+import { escapeLiteral } from './derived-apply.js';
+import { createUrlRunner } from './db-source.js';
+import {
+  withDatabase,
+  createDatabase,
+  dropDatabase,
+  buildIntoDatabase,
+  type BuildOptions,
+} from './db-build.js';
+
+export { withDatabase } from './db-build.js';
+
+// ---------------------------------------------------------------------------
+// Naming (pure).
+// ---------------------------------------------------------------------------
+
+const FAMILY_SUFFIX = /(_tpl|_br_.*|_eph_.*)$/;
+
+/** The family's base name, from ANY member's URL (base, template, branch, ephemeral). */
+export function baseNameFromUrl(url: string): string {
+  const m = url.match(/\/([^/?]+)(\?|$)/);
+  if (!m) throw new Error('the connection URL names no database — add the path segment (postgres://…/mydb)');
+  return m[1].replace(FAMILY_SUFFIX, '');
+}
+
+export function templateName(base: string): string {
+  return `${base}_tpl`;
+}
+
+/**
+ * The branch database's name: deterministic, collision-free, ≤63 chars.
+ * A branch that IS already a clean identifier passes through readably;
+ * anything cleaned (case, slashes, unicode) or truncated carries a 6-char
+ * content hash so `feat/foo` and `feat_foo` never collide.
+ */
+export function branchDatabaseName(base: string, branch: string): string {
+  const prefix = `${base}_br_`;
+  const clean = branch.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  const budget = 63 - prefix.length;
+  if (clean === branch && clean.length > 0 && clean.length <= budget) return `${prefix}${clean}`;
+  const hash = createHash('sha256').update(branch).digest('hex').slice(0, 6);
+  const body = clean.slice(0, Math.max(0, budget - 7));
+  return `${prefix}${body ? `${body}_` : ''}${hash}`;
+}
+
+// ---------------------------------------------------------------------------
+// Comments — the branch mapping and the template provenance (pure).
+// ---------------------------------------------------------------------------
+
+const BRANCH_PREFIX = 'everystack branch: ';
+
+export function branchComment(branch: string): string {
+  return `${BRANCH_PREFIX}${branch}`;
+}
+
+export function parseBranchComment(comment: string | null): string | null {
+  if (!comment || !comment.startsWith(BRANCH_PREFIX)) return null;
+  return comment.slice(BRANCH_PREFIX.length);
+}
+
+export function templateComment(fingerprint: string, gitRef: string | null, builtAt: string): string {
+  return `everystack template fp=${fingerprint} git=${gitRef ?? 'none'} built=${builtAt}`;
+}
+
+export function parseTemplateComment(
+  comment: string | null,
+): { fingerprint: string; gitRef: string | null; builtAt: string } | null {
+  const m = comment?.match(/^everystack template fp=(\S+) git=(\S+) built=(\S+)$/);
+  if (!m) return null;
+  return { fingerprint: m[1], gitRef: m[2] === 'none' ? null : m[2], builtAt: m[3] };
+}
+
+// ---------------------------------------------------------------------------
+// Pruning (pure).
+// ---------------------------------------------------------------------------
+
+export interface BranchDatabase {
+  database: string;
+  /** From the database comment; null when the mapping is lost — never pruned. */
+  branch: string | null;
+}
+
+/** Databases whose branch no longer exists — and ONLY those. Unknown = kept. */
+export function prunableBranchDatabases(
+  databases: BranchDatabase[],
+  liveBranches: string[],
+): BranchDatabase[] {
+  const live = new Set(liveBranches);
+  return databases.filter((d) => d.branch !== null && !live.has(d.branch));
+}
+
+// ---------------------------------------------------------------------------
+// Git (thin).
+// ---------------------------------------------------------------------------
+
+export function currentBranch(cwd?: string): string | null {
+  try {
+    const out = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd, stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString().trim();
+    return out === 'HEAD' ? null : out; // detached HEAD names no branch
+  } catch {
+    return null;
+  }
+}
+
+export function localBranches(cwd?: string): string[] {
+  try {
+    return execSync('git for-each-ref --format=%(refname:short) refs/heads', {
+      cwd, stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString().trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Orchestration.
+// ---------------------------------------------------------------------------
+
+async function withAdmin<T>(adminUrl: string, fn: (runner: QueryRunner) => Promise<T>): Promise<T> {
+  const { runner, end } = await createUrlRunner(adminUrl);
+  try {
+    return await fn(runner);
+  } finally {
+    await end?.();
+  }
+}
+
+async function databaseExists(runner: QueryRunner, name: string): Promise<boolean> {
+  const rows = await runner(`SELECT 1 FROM pg_database WHERE datname = ${escapeLiteral(name)}`);
+  return rows.length > 0;
+}
+
+async function setComment(runner: QueryRunner, database: string, comment: string): Promise<void> {
+  await runner(`COMMENT ON DATABASE "${database}" IS ${escapeLiteral(comment)}`);
+}
+
+export interface TemplateRefreshOptions extends BuildOptions {
+  /** Runs against the freshly built template (the app's own seed, injected by the shell). */
+  seed?: ((templateUrl: string) => Promise<void>) | null;
+  /** Injectable for tests. Default: now, ISO. */
+  builtAt?: string;
+}
+
+export interface TemplateRefreshResult {
+  database: string;
+  url: string;
+  fingerprint: string;
+  report: string[];
+}
+
+/**
+ * (Re)build the dev template from the declared state + seed. All or
+ * nothing: a template that fails to build (or seed) is DROPPED — a broken
+ * template silently minting broken branch databases is the one outcome
+ * this must never produce.
+ */
+export async function executeTemplateRefresh(
+  adminUrl: string,
+  models: ModelDescriptor[],
+  options: TemplateRefreshOptions = {},
+): Promise<TemplateRefreshResult> {
+  const base = baseNameFromUrl(adminUrl);
+  const template = templateName(base);
+  await dropDatabase(adminUrl, template);
+  await createDatabase(adminUrl, template);
+  const url = withDatabase(adminUrl, template);
+  try {
+    const built = await buildIntoDatabase(url, models, options);
+    if (!(built.converged && built.fingerprintMatch)) {
+      throw new Error(`the template did not land on the declared state:\n${built.report.join('\n')}`);
+    }
+    if (options.seed) await options.seed(url);
+    await withAdmin(adminUrl, (runner) =>
+      setComment(runner, template, templateComment(
+        built.fingerprint,
+        options.gitRef ?? null,
+        options.builtAt ?? new Date().toISOString(),
+      )),
+    );
+    return { database: template, url, fingerprint: built.fingerprint, report: built.report };
+  } catch (err) {
+    await dropDatabase(adminUrl, template).catch(() => {});
+    throw err;
+  }
+}
+
+export type EnsureBranchResult =
+  | { status: 'created' | 'exists'; database: string; url: string; template: string }
+  | { status: 'no-template'; database: string; url: string; template: string };
+
+/** Mint (or find) the current branch's database from the template. */
+export async function ensureBranchDatabase(adminUrl: string, branch: string): Promise<EnsureBranchResult> {
+  const base = baseNameFromUrl(adminUrl);
+  const template = templateName(base);
+  const database = branchDatabaseName(base, branch);
+  const url = withDatabase(adminUrl, database);
+
+  const exists = await withAdmin(adminUrl, (runner) => databaseExists(runner, database));
+  if (exists) return { status: 'exists', database, url, template };
+
+  const templateExists = await withAdmin(adminUrl, (runner) => databaseExists(runner, template));
+  if (!templateExists) return { status: 'no-template', database, url, template };
+
+  await createDatabase(adminUrl, database, template);
+  await withAdmin(adminUrl, (runner) => setComment(runner, database, branchComment(branch)));
+  return { status: 'created', database, url, template };
+}
+
+/** Every branch database in the family, with its branch (from the comment). */
+export async function listBranchDatabases(adminUrl: string): Promise<BranchDatabase[]> {
+  const base = baseNameFromUrl(adminUrl);
+  return withAdmin(adminUrl, async (runner) => {
+    const rows = await runner(
+      `SELECT datname, shobj_description(oid, 'pg_database') AS comment
+       FROM pg_database WHERE datname LIKE ${escapeLiteral(`${base}\\_br\\_%`)} ORDER BY datname`,
+    );
+    return rows.map((r: any) => ({ database: r.datname, branch: parseBranchComment(r.comment) }));
+  });
+}
+
+/** The template's provenance, or null when no template exists. */
+export async function readTemplateProvenance(
+  adminUrl: string,
+): Promise<{ fingerprint: string; gitRef: string | null; builtAt: string } | null> {
+  const base = baseNameFromUrl(adminUrl);
+  return withAdmin(adminUrl, async (runner) => {
+    const rows = await runner(
+      `SELECT shobj_description(oid, 'pg_database') AS comment
+       FROM pg_database WHERE datname = ${escapeLiteral(templateName(base))}`,
+    );
+    if (rows.length === 0) return null;
+    return parseTemplateComment(rows[0].comment);
+  });
+}
+
+/** Drop a branch database — refuses anything outside the `_br_` family. */
+export async function dropBranchDatabase(adminUrl: string, database: string): Promise<void> {
+  if (!/_br_/.test(database)) {
+    throw new Error(`${database} is not a branch database — this path only drops the _br_ family.`);
+  }
+  await dropDatabase(adminUrl, database);
+}

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

@@ -0,0 +1,127 @@
+/**
+ * `everystack db:backfill` — the one-shot data-job lane (brick 8).
+ *
+ *   db:backfill [--database-url <url>] [--dir db/backfills] [--json]
+ *   db:backfill --apply                     # run the pending jobs, in order
+ *   db:backfill --mark-applied <file.sql>   # record without running (adopt hatch)
+ *
+ * Plan first, always: applied (by content identity — renames and comment
+ * edits are no-ops), pending (in file-name order, with jobs-lane advisories
+ * for unbounded passes), and blocked (a file name that already ran here in
+ * a different form — one-shot jobs are immutable; the fix is named). Apply
+ * runs each pending job as its own transaction and records it in
+ * `everystack.backfill_log`; a failure rolls back alone, is recorded, and
+ * stops the run. Backfills NEVER run as a side effect of a schema verb —
+ * db:sync and db:plan only surface the pending count.
+ *
+ * Needs a direct connection (--database-url / DATABASE_URL): the lane
+ * reads and writes its own per-database record.
+ */
+
+import type { QueryRunner } from '../authz-contract.js';
+import {
+  planBackfills,
+  readBackfillLog,
+  executeBackfills,
+  markBackfillApplied,
+  type BackfillPlan,
+} from '../backfill.js';
+import { currentGitRef } from '../state-apply.js';
+import { resolveDbSource, createUrlRunner, type DbSource } from '../db-source.js';
+import { readSqlDirIfPresent } from './db-sync.js';
+import { step, success, fail, info, warn } from '../output.js';
+
+const DEFAULT_DIR = 'db/backfills';
+
+export function buildBackfillReport(plan: BackfillPlan): string[] {
+  const lines: string[] = [];
+  lines.push(`= ${plan.applied.length} applied (by content identity)`);
+  for (const b of plan.blocked) lines.push(`! BLOCKED ${b.file}: ${b.reason}`);
+  if (plan.pending.length === 0) {
+    lines.push('= nothing pending');
+  } else {
+    lines.push(`~ ${plan.pending.length} pending, in order:`);
+    for (const p of plan.pending) {
+      lines.push(`~   ${p.file}`);
+      for (const a of p.advisories) lines.push(`·     advisory: ${a}`);
+    }
+  }
+  return lines;
+}
+
+export async function dbBackfillCommand(flags: Record<string, string>): Promise<void> {
+  const dir = flags.dir || DEFAULT_DIR;
+  const files = await readSqlDirIfPresent(dir);
+  if (files === null) {
+    info(`No ${dir}/ directory — the backfill lane is not declared. One-shot data jobs live there as *.sql files.`);
+    return;
+  }
+
+  let dbSource: DbSource;
+  try {
+    dbSource = resolveDbSource(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  if (dbSource.kind !== 'url') {
+    fail('db:backfill needs a direct connection (--database-url or DATABASE_URL) — the lane reads and writes its per-database record.');
+    process.exit(1);
+  }
+
+  step(dbSource.from === 'flag' ? 'Connecting via --database-url...' : 'Connecting via DATABASE_URL...');
+  const { runner, end } = await createUrlRunner(dbSource.url);
+  try {
+    const opts = { actor: process.env.USER ?? null, gitRef: currentGitRef() };
+
+    if (flags['mark-applied'] !== undefined) {
+      const name = flags['mark-applied'];
+      const file = files.find((f) => f.file.endsWith(`/${name}`) || f.file === name);
+      if (name === 'true' || !file) {
+        fail(`--mark-applied needs a file from ${dir}/ (got ${name === 'true' ? 'nothing' : name}).`);
+        process.exit(1);
+      }
+      const identity = await markBackfillApplied(runner as QueryRunner, file, opts);
+      success(`Recorded ${file.file} as applied WITHOUT running it (identity ${identity.slice(0, 12)}).`);
+      return;
+    }
+
+    const plan = planBackfills(files, await readBackfillLog(runner));
+    for (const line of buildBackfillReport(plan)) info(line);
+
+    if (flags.json === 'true') {
+      console.log(JSON.stringify({
+        applied: plan.applied,
+        pending: plan.pending.map(({ sql: _sql, ...rest }) => rest),
+        blocked: plan.blocked,
+      }, null, 2));
+    }
+
+    if (flags.apply !== 'true') {
+      if (plan.pending.length > 0) info(`Run them: everystack db:backfill --apply`);
+      if (plan.blocked.length > 0) process.exit(1);
+      return;
+    }
+
+    if (plan.pending.length === 0) {
+      success('Nothing to run.');
+      if (plan.blocked.length > 0) process.exit(1);
+      return;
+    }
+
+    step(`Running ${plan.pending.length} backfill(s), each as its own transaction...`);
+    const result = await executeBackfills(runner, plan, opts);
+    for (const ran of result.ran) info(`~ ${ran.file} applied in ${ran.durationMs}ms`);
+    if (result.failed) {
+      fail(`${result.failed.file} FAILED and rolled back (recorded; it stays pending for the retry): ${result.failed.error}`);
+      process.exit(1);
+    }
+    if (plan.blocked.length > 0) {
+      fail('Pending jobs ran, but blocked file(s) remain above — fix them (new file name, or --mark-applied).');
+      process.exit(1);
+    }
+    success(`${result.ran.length} backfill(s) applied and recorded in everystack.backfill_log.`);
+  } finally {
+    await end?.();
+  }
+}

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

@@ -46,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';
@@ -294,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,
@@ -317,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 {

package/src/cli/index.ts

@@ -19,6 +19,8 @@ import { dbPlanCommand } from './commands/db-plan.js';
 import { dbApplyCommand } from './commands/db-apply.js';
 import { dbCheckCommand } from './commands/db-check.js';
 import { dbApproversCommand } from './commands/db-approvers.js';
+import { dbBackfillCommand } from './commands/db-backfill.js';
+import { dbTemplateRefreshCommand, dbBranchCommand } from './commands/db-branch.js';
 import { dbSnapshotCommand, dbSnapshotsCommand } from './commands/db-snapshot.js';
 import { dbBackupProbeCommand, dbBackupCommand, dbBackupsCommand, dbRestoreCommand, dbBackupDownloadCommand } from './commands/db-backup.js';
 import { consoleCommand } from './commands/console.js';
@@ -204,6 +206,15 @@ async function main() {
     case 'db:approvers':
       await dbApproversCommand(flags);
       break;
+    case 'db:backfill':
+      await dbBackfillCommand(flags);
+      break;
+    case 'db:template:refresh':
+      await dbTemplateRefreshCommand(flags);
+      break;
+    case 'db:branch':
+      await dbBranchCommand(flags);
+      break;
     case 'db:authz:pull':
       await dbAuthzPullCommand(flags);
       break;
@@ -334,6 +345,9 @@ Usage:
   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 + a snapshot (automatic via db:backup with --stage, else --snapshot-ref) + the stage's approver set when declared (STS identity-verified). Every refusal is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there; direct connection required
   everystack db:check          [--models <barrel>] [--sql-dir db/sql] [--schema-out <file.ts>] [--database-url <url>] [--json]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, db/sql parses) 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
+  everystack db:template:refresh [--database-url <url>] [--models <barrel>] [--sql-dir db/sql] [--seed "<cmd>"] [--no-seed]  (Re)build the dev template <base>_tpl FROM THE DECLARED STATE (both layers, fingerprint MATCH bar) + seed-as-code (the app's db:seed script, run with DATABASE_URL pointed at the template; --seed overrides). All or nothing: a failed build/seed leaves NO template. Never a data copy
+  everystack db:branch         [--list | --drop --confirm | --prune --confirm] [--database-url <url>]  Mint (or find) the current git branch's database from the template (CREATE DATABASE … TEMPLATE — schema, authz, derived layer, and seed rows inherited), print its DATABASE_URL, then db:sync evolves it with the checkout. --list maps every branch DB to its branch; --prune drops the ones whose branch is gone (never guesses: unknown mappings are kept)
   everystack db:authz:pull     [--stage <name>] [--dir authz]  Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
   everystack db:authz:diff     [--stage <name>] [--dir authz]  Validate the live DB against the committed contract (non-zero exit on drift)
   everystack db:authz:test     [--stage <name>] [--dir authz]  Red-team enforcement: SET ROLE + attempt per role/table/command (non-zero exit on a hole)

package/src/cli/model-api.ts

@@ -34,3 +34,10 @@ export * from './authz-owner-probe.js';
 
 // --- the SECDEF function catalog the contract introspection needs -----------
 export { FUNCTIONS_SQL, catalogFunctionToDescriptor } from './security-catalog.js';
+
+// --- databases FROM the declared state: ephemeral test DBs + the builder ----
+// `createEphemeralDatabase(adminUrl, models, { sources })` is the packaged
+// create-sync-drop shape for consumer test suites: a fresh database at the
+// declared state (state + authz + derived), verified to fingerprint MATCH,
+// dropped when you're done — never long-lived, never poisoned.
+export * from './db-build.js';