@everystack/cli 0.4.11 → 0.4.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -82,7 +82,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.4.2"
+    "@everystack/model": "0.4.3"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.1.0",

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

@@ -0,0 +1,219 @@
+/**
+ * `everystack db:export --schema <name> [--stage <n> | --database-url <url>]` — the schema-scoped,
+ * fingerprint-stamped artifact (canonical-sync gap B). pg_dump ONE schema, stamped with the
+ * DECLARED schema fingerprint from the checkout, so db:swap can gate an incoming artifact against
+ * the target's declared shape (declared-vs-declared: does the artifact and the stage agree on the
+ * schema's shape). everystack owns the export so that fingerprint is one formula both sides.
+ *
+ * Two venues, mirroring db:swap:
+ * - `--stage` (default): the dump runs in the ops Lambda (the DB is private) → the stage's S3
+ *   artifact bucket, gzipped. Verification of the streaming path is a deploy smoke test.
+ * - `--database-url` (explicit flag only, never the env — the venue choice must be deliberate):
+ *   the CLI runs pg_dump itself against a reachable database and writes a plain `-Fc` `.dump`
+ *   plus the sibling `.meta.json` db:swap reads. This is the build-locally → publish → swap
+ *   on-ramp: a consumer pipeline shells this instead of hand-rolling pg_dump and duplicating
+ *   the fingerprint formula.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import type { ModelDescriptor } from '@everystack/model';
+import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
+import { invokeAction } from '../aws.js';
+import { fingerprintModels } from '../schema-fingerprint.js';
+import { resolveModelsPath } from '../models-path.js';
+import { loadModels } from './db-generate.js';
+import { loadDeclaredDerived } from '../declared-derived.js';
+import { pgDumpPreflightError } from './db-backup.js';
+import { pgEnvFromUrl } from './db.js';
+import { utcStamp } from '../backup.js';
+import { step, success, fail, info } from '../output.js';
+
+const fmtBytes = (b?: number): string =>
+  b == null ? '?' : b >= 1024 ** 3 ? `${(b / 1024 ** 3).toFixed(1)} GB` : b >= 1024 ** 2 ? `${(b / 1024 ** 2).toFixed(1)} MB` : `${(b / 1024).toFixed(0)} KB`;
+
+export type ExportVenue = { kind: 'local'; url: string } | { kind: 'stage'; stage: string | undefined };
+
+/**
+ * Which venue runs the dump. Local ONLY on an explicit `--database-url` — never the env, so a
+ * DATABASE_URL in the shell can't silently flip a stage export into a local one. Both flags at
+ * once is ambiguous and refused.
+ */
+export function resolveExportVenue(flags: Record<string, string>): ExportVenue {
+  const url = flags['database-url'];
+  if (url && flags.stage) {
+    throw new Error('db:export takes one venue: --database-url (dump a reachable database locally) OR --stage (dump the stage\'s private database in the ops Lambda) — not both.');
+  }
+  return url ? { kind: 'local', url } : { kind: 'stage', stage: flags.stage };
+}
+
+/**
+ * Where a local artifact lands. Mirrors the S3 scheme (`<stamp>-<shortId>`, meta as a sibling)
+ * with the schema in the file name since there is no bucket prefix; the id says `local` where
+ * the S3 id says the stage. Plain `.dump` (no gzip): db:swap's pg_restore reads the file as-is.
+ */
+export function localArtifactPaths(
+  schema: string,
+  now: Date,
+  shortId: string,
+  opts: { out?: string; outDir?: string } = {},
+): { dumpPath: string; metaPath: string; id: string } {
+  const stamp = utcStamp(now);
+  let dumpPath: string;
+  if (opts.out) {
+    if (!opts.out.endsWith('.dump')) {
+      throw new Error(`--out must end in .dump (got ${opts.out}) — db:swap resolves the sibling .meta.json from that suffix.`);
+    }
+    dumpPath = opts.out;
+  } else {
+    dumpPath = path.join(opts.outDir ?? '.', `${schema}-${stamp}-${shortId}.dump`);
+  }
+  return {
+    dumpPath,
+    metaPath: dumpPath.replace(/\.dump$/, '.meta.json'),
+    id: `${schema}/local/${stamp}-${shortId}`,
+  };
+}
+
+/** The meta record the swap gate reads — same shape as the S3 sidecar, `path` instead of `key`. */
+export function localArtifactMeta(opts: {
+  id: string;
+  schema: string;
+  createdAt: Date;
+  bytes: number;
+  path: string;
+  fingerprint: string;
+}): Record<string, unknown> {
+  return {
+    id: opts.id,
+    schema: opts.schema,
+    stage: 'local',
+    createdAt: opts.createdAt.toISOString(),
+    bytes: opts.bytes,
+    path: opts.path,
+    fingerprint: opts.fingerprint,
+  };
+}
+
+/** pg_dump args for the local venue — same dump shape as the ops venue, written straight to a file. */
+export function pgDumpLocalArgs(schema: string, dumpPath: string): string[] {
+  return ['-Fc', '--no-owner', '--no-privileges', '--no-comments', `--schema=${schema}`, '-f', dumpPath];
+}
+
+/**
+ * Run the local export: pg_dump one schema to a `-Fc` file, then write the meta sidecar. The
+ * connection rides PG* env (never argv). A failed dump removes the partial file — a truncated
+ * artifact never ships. Throws on failure; the command wraps it.
+ */
+export async function runLocalExport(opts: {
+  url: string;
+  schema: string;
+  fingerprint: string;
+  out?: string;
+  outDir?: string;
+}): Promise<{ id: string; dumpPath: string; metaPath: string; bytes: number }> {
+  const now = new Date();
+  const shortId = randomBytes(3).toString('hex');
+  const { dumpPath, metaPath, id } = localArtifactPaths(opts.schema, now, shortId, opts);
+
+  const env = { ...process.env, ...pgEnvFromUrl(opts.url) };
+  const child = spawn('pg_dump', pgDumpLocalArgs(opts.schema, dumpPath), { env, stdio: ['ignore', 'ignore', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', (d) => { stderr += d.toString(); });
+  try {
+    await new Promise<void>((resolve, reject) => {
+      child.on('error', reject);
+      child.on('close', (code) =>
+        code === 0 ? resolve() : reject(new Error(`pg_dump exited ${code}: ${stderr.trim()}`)));
+    });
+  } catch (err) {
+    fs.rmSync(dumpPath, { force: true });
+    throw err;
+  }
+
+  const bytes = fs.statSync(dumpPath).size;
+  fs.writeFileSync(metaPath, JSON.stringify(localArtifactMeta({
+    id, schema: opts.schema, createdAt: now, bytes, path: dumpPath, fingerprint: opts.fingerprint,
+  }), null, 2));
+  return { id, dumpPath, metaPath, bytes };
+}
+
+export async function dbExportCommand(flags: Record<string, string>): Promise<void> {
+  const schema = flags.schema;
+  if (!schema) {
+    fail('db:export needs --schema <name> (the schema to export as an artifact).');
+    process.exit(1);
+  }
+
+  let venue: ExportVenue;
+  try {
+    venue = resolveExportVenue(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  // The DECLARED fingerprint of just this schema — the stamp the swap gate compares against.
+  const modelsPath = resolveModelsPath(flags.models);
+  let fingerprint: string;
+  try {
+    step(`Loading models from ${modelsPath}...`);
+    const models: ModelDescriptor[] = await loadModels(modelsPath);
+    const declaredDb = await loadDeclaredDerived(flags.models);
+    fingerprint = fingerprintModels(models, { schemas: [schema], sequences: declaredDb?.sequences }).hash;
+    info(`Declared ${schema} fingerprint: ${fingerprint.slice(0, 12)}`);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  if (venue.kind === 'local') {
+    step(`Running pg_dump --schema=${schema} against --database-url...`);
+    try {
+      const res = await runLocalExport({ url: venue.url, schema, fingerprint, out: flags.out });
+      success(`Artifact ${res.dumpPath} (${fmtBytes(res.bytes)}, fingerprint ${fingerprint.slice(0, 12)}, meta ${res.metaPath}). Deploy with: everystack db:swap --schema ${schema} --from ${res.dumpPath} --database-url <target>`);
+    } catch (err: any) {
+      fail(`Export failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  step('Resolving deployed config...');
+  let config: CliConfig;
+  try {
+    config = await resolveConfig(venue.stage);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+
+  // The dump needs the pg_dump layer — surface a missing/incompatible layer as a one-line remedy
+  // here, not a mid-dump crash (same preflight db:backup runs).
+  step('Checking the pg_dump layer...');
+  try {
+    const probe = await invokeAction(config.region, opsFunction(config), 'db:backup:probe', {});
+    const preflightError = pgDumpPreflightError(probe);
+    if (preflightError) { fail(preflightError); process.exit(1); }
+  } catch (err: any) {
+    fail(`Export pre-flight failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  step(`Running pg_dump --schema=${schema} → S3 (this may take a while for large schemas)...`);
+  let result: any;
+  try {
+    result = await invokeAction(config.region, opsFunction(config), 'db:export', { schema, stage: venue.stage, fingerprint });
+  } catch (err: any) {
+    fail(`Export failed: ${err.message}`);
+    process.exit(1);
+  }
+  if (result?.error) {
+    fail(`Export failed: ${result.error}`);
+    process.exit(1);
+  }
+  success(`Artifact ${result.id} (${fmtBytes(result.bytes)}, fingerprint ${String(result.fingerprint).slice(0, 12)}). Deploy with: everystack db:swap --schema ${schema} --stage <target>`);
+}

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

@@ -0,0 +1,156 @@
+/**
+ * `everystack db:swap --schema <name> --database-url <url> --from <artifact.dump> [--confirm]` —
+ * the refresh-free, fingerprint-gated hot-swap (canonical-sync gap B).
+ *
+ * Lands a schema-scoped artifact onto a target and swaps it in atomically: gate on the declared
+ * fingerprint, snapshot, restore into `<schema>_incoming` (COPY-safe schema rewrite), the atomic
+ * rename + FK-recreate + authz-reapply transaction, a post-commit verify hook, then drop-retiring
+ * or roll back. The decision spine (swap-execute.ts) is proven on a real database; this shell wires
+ * the IO — the artifact restore and the connection.
+ *
+ * v1 venue: a direct `--database-url` (the operator connection). The credential-free `--stage`
+ * ops-Lambda / `--direct` venues ride the stage-write-lanes bricks; a multi-GB restore needs the
+ * unbounded clock those give, so `--stage` alone will refuse with the `--direct` advice.
+ */
+
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import type { ModelDescriptor } from '@everystack/model';
+import { fingerprintModels } from '../schema-fingerprint.js';
+import { resolveModelsPath } from '../models-path.js';
+import { loadModels } from './db-generate.js';
+import { loadDeclaredDerived } from '../declared-derived.js';
+import { createUrlRunner } from '../db-source.js';
+import { executeSwap, type SwapVerdict } from '../swap-execute.js';
+import { rewriteStatementLine, opensCopyData, closesCopyData } from '../schema-rewrite.js';
+import { step, success, fail, warn } from '../output.js';
+
+/** A COPY-aware line transform that rewrites the schema token on statement lines only. */
+function schemaRewriteStream(from: string, to: string): Transform {
+  let buf = '';
+  let inCopy = false;
+  const flushLine = (line: string, push: (s: string) => void) => {
+    if (inCopy) {
+      if (closesCopyData(line)) inCopy = false;
+      push(line + '\n');
+      return;
+    }
+    const rewritten = rewriteStatementLine(line, from, to);
+    if (opensCopyData(rewritten)) inCopy = true;
+    push(rewritten + '\n');
+  };
+  return new Transform({
+    transform(chunk, _enc, cb) {
+      buf += chunk.toString('utf8');
+      let nl: number;
+      const out: string[] = [];
+      while ((nl = buf.indexOf('\n')) !== -1) {
+        flushLine(buf.slice(0, nl), (s) => out.push(s));
+        buf = buf.slice(nl + 1);
+      }
+      cb(null, out.join(''));
+    },
+    flush(cb) {
+      if (buf.length) flushLine(buf, (s) => this.push(s));
+      cb();
+    },
+  });
+}
+
+/**
+ * Restore a `-Fc` artifact into `<schema>_incoming`: pg_restore -f - (archive → SQL) → the schema
+ * rewrite → psql. The archive names `<schema>`; the rewrite lands it as `<incoming>`, COPY-data-safe.
+ */
+async function restoreIntoIncoming(url: string, artifactPath: string, schema: string, incoming: string): Promise<void> {
+  // psql takes the connection URL directly (credential parsed by libpq, not on the process table
+  // beyond argv-as-URL); pg_restore -f - just reads the archive file to SQL on stdout.
+  const restore = spawn('pg_restore', ['-f', '-', artifactPath], { stdio: ['ignore', 'pipe', 'pipe'] });
+  const psql = spawn('psql', ['-v', 'ON_ERROR_STOP=1', '-d', url], { stdio: ['pipe', 'ignore', 'pipe'] });
+  let rErr = '', pErr = '';
+  restore.stderr.on('data', (d) => { rErr += d.toString(); });
+  psql.stderr.on('data', (d) => { pErr += d.toString(); });
+  const psqlExit = new Promise<void>((res, rej) => {
+    psql.on('error', rej);
+    psql.on('close', (c) => c === 0 ? res() : rej(new Error(`psql exited ${c}: ${pErr.trim()}`)));
+  });
+  const restoreExit = new Promise<void>((res, rej) => {
+    restore.on('error', rej);
+    restore.on('close', (c) => c === 0 ? res() : rej(new Error(`pg_restore exited ${c}: ${rErr.trim()}`)));
+  });
+  await Promise.all([
+    pipeline(restore.stdout!, schemaRewriteStream(schema, incoming), psql.stdin!),
+    restoreExit,
+    psqlExit,
+  ]);
+}
+
+/**
+ * Load the artifact's meta (fingerprint) from a sibling `.meta.json`, or fall back to a flag.
+ * Exported so the db:export local venue can prove its meta round-trips into this gate.
+ */
+export function readArtifactFingerprint(artifactPath: string, flag?: string): string | null {
+  if (flag) return flag;
+  const metaPath = artifactPath.replace(/\.dump(\.gz)?$/, '.meta.json');
+  try {
+    return JSON.parse(fs.readFileSync(metaPath, 'utf8')).fingerprint ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export async function dbSwapCommand(flags: Record<string, string>): Promise<void> {
+  const schema = flags.schema;
+  const url = flags['database-url'] || process.env.DATABASE_URL;
+  const from = flags.from;
+  if (!schema) { fail('db:swap needs --schema <name>.'); process.exit(1); }
+  if (!from) { fail('db:swap needs --from <artifact.dump> (the schema-scoped -Fc archive to land).'); process.exit(1); }
+  if (!url) {
+    fail('db:swap v1 needs a direct --database-url (the operator connection). The credential-free --stage venue rides the stage-write-lanes bricks; a large restore needs its unbounded clock.');
+    process.exit(1);
+  }
+
+  const modelsPath = resolveModelsPath(flags.models);
+  let models: ModelDescriptor[];
+  let declaredFingerprint: string;
+  try {
+    step(`Loading models from ${modelsPath}...`);
+    models = await loadModels(modelsPath);
+    const declaredDb = await loadDeclaredDerived(flags.models);
+    declaredFingerprint = fingerprintModels(models, { schemas: [schema], sequences: declaredDb?.sequences }).hash;
+  } catch (err: any) { fail(err.message); process.exit(1); }
+
+  const artifactFingerprint = readArtifactFingerprint(from, flags.fingerprint);
+  if (!artifactFingerprint) {
+    fail(`db:swap can't find the artifact fingerprint — expected a sibling .meta.json next to ${from}, or pass --fingerprint. Without it the gate can't run, and an unchecked swap is exactly what the gate prevents.`);
+    process.exit(1);
+  }
+
+  const { runner, end } = await createUrlRunner(url);
+  try {
+    step(`Swapping ${schema} — gate, land incoming, atomic swap, verify...`);
+    const res = await executeSwap(runner, {
+      models, schema,
+      artifactFingerprint,
+      declaredFingerprint,
+      applyIncoming: async () => { await restoreIntoIncoming(url, from, schema, `${schema}_incoming`); },
+      // Snapshot + verify-hook wiring land with the ops venue; a direct v1 swap warns rather than
+      // silently skipping the safety net.
+      snapshot: async () => { warn('no snapshot taken (direct v1) — take one first: everystack db:backup --database-url … before a production swap.'); },
+    });
+
+    if (res.status === 'swapped') {
+      success(`Swapped ${schema} — the artifact is live (no refresh ran).`);
+      for (const w of res.warnings ?? []) warn(`verify warning: ${w.name}${w.detail ? ` — ${w.detail}` : ''}`);
+    } else {
+      fail(`db:swap ${res.status}: ${res.reason}`);
+      process.exit(1);
+    }
+  } catch (err: any) {
+    fail(`Swap failed: ${err.message}`);
+    process.exit(1);
+  } finally {
+    await end?.();
+  }
+}

package/src/cli/index.ts

@@ -25,6 +25,8 @@ import { dbTemplateRefreshCommand, dbBranchCommand } from './commands/db-branch.
 import { dbForkCommand } from './commands/db-fork.js';
 import { dbSnapshotCommand, dbSnapshotsCommand } from './commands/db-snapshot.js';
 import { dbBackupProbeCommand, dbBackupCommand, dbBackupsCommand, dbRestoreCommand, dbBackupDownloadCommand } from './commands/db-backup.js';
+import { dbExportCommand } from './commands/db-export.js';
+import { dbSwapCommand } from './commands/db-swap.js';
 import { consoleCommand } from './commands/console.js';
 import { cachePurgeCommand } from './commands/cache.js';
 import { statusCommand } from './commands/status.js';
@@ -181,6 +183,12 @@ async function main() {
     case 'db:restore':
       await dbRestoreCommand(flags);
       break;
+    case 'db:export':
+      await dbExportCommand(flags);
+      break;
+    case 'db:swap':
+      await dbSwapCommand(flags);
+      break;
     case 'db:backup:download': {
       const backupId = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
       await dbBackupDownloadCommand(flags, backupId);
@@ -353,6 +361,8 @@ Usage:
   everystack db:backups        [--stage <name>]  List logical backups (id, size, created)
   everystack db:restore        --from <id> [--stage <name>] --confirm  Restore a backup INTO the stage's DB (DESTRUCTIVE)
   everystack db:backup:download <id> [--stage <name>]  Presigned URL to download a backup's dump (valid 1h)
+  everystack db:export         --schema <name> [--stage <name> | --database-url <url> [--out <file.dump>]] [--models <barrel>]  Schema-scoped pg_dump artifact, stamped with the DECLARED schema fingerprint (the canonical-sync export; db:swap gates on that stamp). --stage dumps the stage's private DB via the ops Lambda → S3; --database-url (explicit flag, never the env) dumps a reachable DB to a local .dump + .meta.json — the build-locally → publish → swap on-ramp
+  everystack db:swap           --schema <name> --database-url <url> --from <artifact.dump> [--fingerprint <hash>]  Land a schema artifact atomically: fingerprint gate → restore into <schema>_incoming (COPY-safe rewrite) → one txn (drop+rename+recreate app→schema FKs, re-apply authz) → verify → drop retiring. Refresh-free; app.* untouched. DESTRUCTIVE (--stage/--direct ops venue rides stage-write-lanes)
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply] [--dry-run]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops). --dry-run prints the edge and writes NOTHING (no migration, no journal entry, no schema refresh) — the preview verb; db:diff computes a models-vs-models edge with no database at all. The resolved --schema-out is recorded in the migration journal: later flag-less runs reuse it (flag > recorded > default), a differing flag updates the record and says so
   everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored); --abilities public-read stamps the common stanza (public read, admin write) uncommented — explicit generated code, never a runtime default
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.

package/src/cli/schema-fingerprint.ts

@@ -161,26 +161,54 @@ export interface CanonicalState {
   sequences?: Array<Record<string, unknown>>;
 }
 
+/** The schema of a (possibly) qualified name — `stats.entities` → `stats`, a bare name → `public`. */
+export function schemaOf(qualifiedName: string): string {
+  const dot = qualifiedName.indexOf('.');
+  return dot === -1 ? 'public' : qualifiedName.slice(0, dot);
+}
+
+export interface CanonicalizeOptions {
+  /** Restrict the state to these schemas — the content address of ONE schema (e.g. a
+   *  schema-scoped artifact) instead of the whole database. Omitted = every schema. */
+  schemas?: string[];
+}
+
 export function canonicalizeState(
   snapshot: SchemaSnapshot,
   authzTables: TableContract[],
+  opts: CanonicalizeOptions = {},
 ): CanonicalState {
+  const inScope = opts.schemas ? new Set(opts.schemas) : null;
+  const keepTable = (name: string) => inScope === null || inScope.has(schemaOf(name));
+
+  const tables = snapshot.tables.filter((t) => keepTable(t.table));
+  // Enums carry no schema in the descriptor (keyed by bare name, like the model side).
+  // Scope them by USE: an enum is in-scope when a kept table has a column of that type
+  // (the type may be qualified under canonical introspection — `stats.status` — so match
+  // on the bare tail). This keeps the exact set the scoped models declare.
+  const usedEnum = new Set<string>();
+  for (const t of tables) for (const c of t.columns) usedEnum.add(schemaOf(c.type) === 'public' ? c.type : c.type.slice(c.type.indexOf('.') + 1));
+
   const sequences = byKey(
-    (snapshot.sequences ?? []).map((s) => ({
-      name: s.name, as: s.as,
-      ...(s.start != null ? { start: s.start } : {}),
-      ...(s.increment != null ? { increment: s.increment } : {}),
-    })),
+    (snapshot.sequences ?? [])
+      .filter((s) => inScope === null || inScope.has(schemaOf(s.name)))
+      .map((s) => ({
+        name: s.name, as: s.as,
+        ...(s.start != null ? { start: s.start } : {}),
+        ...(s.increment != null ? { increment: s.increment } : {}),
+      })),
     (s) => String(s.name),
   );
   return {
     v: FINGERPRINT_VERSION,
-    tables: byKey(snapshot.tables.map(canonicalTable), (t) => String(t.table)),
+    tables: byKey(tables.map(canonicalTable), (t) => String(t.table)),
     enums: byKey(
-      (snapshot.enums ?? []).map((e) => ({ name: e.name, values: e.values })),
+      (snapshot.enums ?? [])
+        .filter((e) => inScope === null || usedEnum.has(e.name))
+        .map((e) => ({ name: e.name, values: e.values })),
       (e) => e.name,
     ),
-    authz: byKey(authzTables.map(canonicalAuthzTable), (t) => String(t.table)),
+    authz: byKey(authzTables.filter((t) => keepTable(t.table)).map(canonicalAuthzTable), (t) => String(t.table)),
     ...(sequences.length ? { sequences } : {}),
   };
 }
@@ -195,28 +223,38 @@ export interface Fingerprint {
 export function fingerprintState(
   snapshot: SchemaSnapshot,
   authzTables: TableContract[],
+  opts: CanonicalizeOptions = {},
 ): Fingerprint {
-  const canonical = canonicalizeState(snapshot, authzTables);
+  const canonical = canonicalizeState(snapshot, authzTables, opts);
   return { hash: createHash('sha256').update(stableStringify(canonical)).digest('hex'), canonical };
 }
 
-/** The DECLARED state: compile the models to the same canonical shape and hash it. */
+/** The DECLARED state: compile the models to the same canonical shape and hash it. When
+ *  `schemas` is set, only models in those schemas are compiled — the content address of a
+ *  schema slice (the export stamp and the swap gate compute this identically). */
 export function fingerprintModels(
   models: ModelDescriptor[],
-  opts: { schema?: string; sequences?: SequenceDescriptor[] } = {},
+  opts: { schema?: string; sequences?: SequenceDescriptor[]; schemas?: string[] } = {},
 ): Fingerprint {
+  const scoped = opts.schemas ? models.filter((m) => opts.schemas!.includes(m.schema)) : models;
   const snapshot: SchemaSnapshot = {
-    tables: models.map((m) => compileTableSchema(m, opts)),
-    enums: compileEnums(models),
+    tables: scoped.map((m) => compileTableSchema(m, opts)),
+    enums: compileEnums(scoped),
     ...(opts.sequences?.length ? { sequences: compileSequences(opts.sequences) } : {}),
   };
-  const authzTables = models.map((m) => compileTableContract(m, opts));
-  return fingerprintState(snapshot, authzTables);
+  const authzTables = scoped.map((m) => compileTableContract(m, opts));
+  // The models are already scoped, so no further schema filter — but standalone sequences
+  // are declared apart from models; scope them here too.
+  return fingerprintState(snapshot, authzTables, opts.schemas ? { schemas: opts.schemas } : {});
 }
 
 /** Convenience: the live side, from the two existing introspections. */
-export function fingerprintLive(snapshot: SchemaSnapshot, contract: AuthzContract): Fingerprint {
-  return fingerprintState(snapshot, contract.tables);
+export function fingerprintLive(
+  snapshot: SchemaSnapshot,
+  contract: AuthzContract,
+  opts: CanonicalizeOptions = {},
+): Fingerprint {
+  return fingerprintState(snapshot, contract.tables, opts);
 }
 
 // ---------------------------------------------------------------------------

package/src/cli/schema-rewrite.ts

@@ -0,0 +1,67 @@
+/**
+ * schema-rewrite — land a schema dump under a DIFFERENT schema name, COPY-data-safe.
+ *
+ * A `-Fc` archive pins the schema name it was dumped from; `pg_restore` filters by schema but can't
+ * remap one. For a ZERO-WINDOW hot-swap the incoming data must land in `<schema>_incoming` while the
+ * live `<schema>` keeps serving, so we restore the archive to SQL (`pg_restore -f -`) and rewrite the
+ * schema token on the way to `psql`. everystack owns both the export and this rewrite, so the token
+ * is our own dump output — deterministic.
+ *
+ * The one hazard is a COPY data row whose VALUE contains the schema name (`see stats.entities for…`):
+ * it must survive untouched. So the rewrite is COPY-aware — it rewrites STATEMENT lines only and
+ * passes every byte between `COPY … FROM stdin;` and the terminating `\.` through verbatim.
+ *
+ * Pure and line-oriented so it composes into a stream transform (the ops/-direct restore pipes
+ * pg_restore stdout → this → psql stdin); a failure here is a loud restore error, never silent
+ * corruption. When the rewrite can't be trusted (a truly exotic dump), the swap's documented
+ * fallback is the rename-dance (a brief window, snapshot-backed).
+ */
+
+const IDENT = '[A-Za-z_][A-Za-z0-9_$]*';
+
+/** True once this line OPENS a COPY data block (`COPY … FROM stdin;`) — data follows until `\.`. */
+export function opensCopyData(line: string): boolean {
+  return /^\s*COPY\s+.*\sFROM\s+stdin;\s*$/i.test(line);
+}
+
+/** True when this line CLOSES a COPY data block (a lone `\.`). */
+export function closesCopyData(line: string): boolean {
+  return line === '\\.' || /^\\\.\s*$/.test(line);
+}
+
+/**
+ * Rewrite the schema token `from` → `to` on a single STATEMENT line (never call on COPY data).
+ * Handles the forms pg_dump emits: the qualifier (`from.x`, `"from".x`), the standalone schema
+ * statements (`CREATE SCHEMA from`, `ALTER SCHEMA from …`, `DROP SCHEMA … from`), and a
+ * `SET search_path` naming it. The schema token must be a plain identifier at both ends so a
+ * substring of another name (`from_archive`) is never touched.
+ */
+export function rewriteStatementLine(line: string, from: string, to: string): string {
+  const f = from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // 1. Schema-qualified refs: `from.` or `"from".` → `to.` (normalize to bare; the token is safe).
+  let out = line.replace(new RegExp(`(^|[^A-Za-z0-9_$."])(?:${f}|"${f}")\\.`, 'g'), `$1${to}.`);
+  // 2. Standalone schema in CREATE/ALTER/DROP SCHEMA and search_path — the token as a whole word,
+  //    bare or quoted, not followed by a dot (those were handled above).
+  out = out.replace(new RegExp(`(^|[^A-Za-z0-9_$.])(?:${f}|"${f}")(?![A-Za-z0-9_$."])`, 'g'), `$1${to}`);
+  return out;
+}
+
+/**
+ * Rewrite a whole plain-SQL dump, COPY-data-safe. Splits on newlines, tracks COPY blocks, and
+ * rewrites only statement lines. Returns the rewritten SQL. (The streaming transform in the restore
+ * pipeline applies `rewriteStatementLine` per line with the same COPY tracking; this is the
+ * in-memory form the tests pin.)
+ */
+export function rewriteSchemaDump(sql: string, from: string, to: string): string {
+  const lines = sql.split('\n');
+  let inCopy = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (inCopy) {
+      if (closesCopyData(lines[i])) inCopy = false;
+      continue; // data (or the terminator) — never rewritten
+    }
+    lines[i] = rewriteStatementLine(lines[i], from, to);
+    if (opensCopyData(lines[i])) inCopy = true;
+  }
+  return lines.join('\n');
+}

package/src/cli/schema-swap.ts

@@ -0,0 +1,147 @@
+/**
+ * schema-swap — the refresh-free, FK-safe, atomic hot-swap of one schema (the core of
+ * db:swap; docs/plans/canonical-sync-artifacts.md, gap B).
+ *
+ * The incoming data has already been restored into `<schema>_incoming` while the live
+ * `<schema>` keeps serving. This renders the ONE transaction that swaps them in atomically:
+ * readers see the old schema or the new, never a partial. Pure — no database here; the
+ * command sends `statements` as one transaction and owns the snapshot / verify / drop-retiring
+ * lifecycle around it.
+ *
+ * The order is load-bearing, and every step verified on PostgreSQL 16:
+ *   1. DROP the app→schema foreign keys. They bind their target by OID, so the rename below
+ *      would carry them onto the RETIRING schema (they would reference stale data, and the
+ *      final DROP of the retiring schema would fail). Drop them first.
+ *   2. RENAME the live schema out (`<schema>` → `<schema>_retiring`) and the incoming in
+ *      (`<schema>_incoming` → `<schema>`). Schema renames are transactional and atomic.
+ *   3. RECREATE the app→schema foreign keys against the NEW schema. This RE-VALIDATES against
+ *      the new data: an app row referencing a key the new artifact dropped fails the
+ *      ADD CONSTRAINT, the whole transaction rolls back, and the swap is refused — the
+ *      cross-schema integrity gate, for free.
+ *   4. RE-APPLY the schema's authz (RLS, policies, grants) from the declared descriptors. The
+ *      incoming schema was restored `--no-owner --no-privileges`, so it carries no grants;
+ *      GRANT/POLICY are transactional, so they ride the same transaction — there is no
+ *      committed instant where the new schema serves with absent or stale grants.
+ *
+ * No REFRESH anywhere: the artifact ships computed rows as tables (defineMaterializedTable),
+ * so the swap is a pointer flip, never a recompute.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import { modelForeignKeys, qualifiedTable } from './schema-compile.js';
+import { compileTableContract } from './authz-compile.js';
+import { emitReconcileSql } from './authz-reconcile.js';
+import { schemaOf } from './schema-fingerprint.js';
+
+const SAFE_SCHEMA = /^[a-z_][a-z0-9_$]*$/;
+
+function assertSafeSchema(name: string): void {
+  if (!SAFE_SCHEMA.test(name)) {
+    throw new Error(`swap schema ${JSON.stringify(name)} is not a plain lowercase identifier — everystack swaps schemas it can name without quoting games.`);
+  }
+}
+
+/** ` ON DELETE … ON UPDATE …` for a FK, or '' when both are the PostgreSQL default. */
+function refActionSql(fk: { onDelete?: string; onUpdate?: string }): string {
+  let s = '';
+  if (fk.onDelete) s += ` ON DELETE ${fk.onDelete.toUpperCase()}`;
+  if (fk.onUpdate) s += ` ON UPDATE ${fk.onUpdate.toUpperCase()}`;
+  return s;
+}
+
+/** Quote a (possibly) schema-qualified ref: `stats.entities` → `"stats"."entities"`, `uploads` → `"uploads"`. */
+function quoteRef(name: string): string {
+  return name.split('.').map((p) => `"${p}"`).join('.');
+}
+
+export interface CrossSchemaFk {
+  /** The model that holds the FK (an app/public table pointing INTO the swapped schema). */
+  table: string;
+  name: string;
+  dropSql: string;
+  addSql: string;
+}
+
+/**
+ * The foreign keys that cross INTO `targetSchema` from a model in ANOTHER schema — the only FKs
+ * the swap must drop and recreate. FKs WITHIN the swapped schema ride the dump; FKs from the
+ * swapped schema OUT to a stable schema (e.g. stats → app) resolve by name on restore and are
+ * untouched. Only external → swapped edges bind the old schema by OID.
+ */
+export function crossSchemaForeignKeys(models: ModelDescriptor[], targetSchema: string): CrossSchemaFk[] {
+  const out: CrossSchemaFk[] = [];
+  for (const model of models) {
+    if ((model.schema || 'public') === targetSchema) continue; // internal edge, not external
+    const from = qualifiedTable(model);
+    for (const fk of modelForeignKeys(model)) {
+      if (schemaOf(fk.refTable) !== targetSchema) continue; // not pointing into the swapped schema
+      const cols = fk.columns.map((c) => `"${c}"`).join(', ');
+      const refCols = fk.refColumns.map((c) => `"${c}"`).join(', ');
+      out.push({
+        table: from,
+        name: fk.name,
+        dropSql: `ALTER TABLE ${from} DROP CONSTRAINT IF EXISTS "${fk.name}";`,
+        addSql: `ALTER TABLE ${from} ADD CONSTRAINT "${fk.name}" FOREIGN KEY (${cols}) REFERENCES ${quoteRef(fk.refTable)}(${refCols})${refActionSql(fk)};`,
+      });
+    }
+  }
+  return out;
+}
+
+export interface SwapPlan {
+  /** The ordered SQL for ONE transaction (the command wraps BEGIN/COMMIT). */
+  statements: string[];
+  /** The app→schema FKs dropped and recreated (the integrity gate). */
+  crossSchemaFks: CrossSchemaFk[];
+  /** The schema the live data is renamed to before the retiring drop (outside the txn). */
+  retiring: string;
+  incoming: string;
+}
+
+export interface SwapOptions {
+  /** The schema being swapped (e.g. `stats`). */
+  schema: string;
+  /** Where the incoming data was restored. Default `<schema>_incoming`. */
+  incoming?: string;
+  /** Where the live schema is renamed. Default `<schema>_retiring`; pass a stamped name for uniqueness. */
+  retiring?: string;
+}
+
+/**
+ * Render the atomic swap transaction for `opts.schema`, given the full declared model set (to
+ * find the app→schema FKs and the schema's authz). The returned `statements` go as ONE
+ * transaction; `crossSchemaFks` and `retiring` let the command report and drive the
+ * drop-retiring / rollback lifecycle.
+ */
+export function renderSchemaSwap(models: ModelDescriptor[], opts: SwapOptions): SwapPlan {
+  const { schema } = opts;
+  const incoming = opts.incoming ?? `${schema}_incoming`;
+  const retiring = opts.retiring ?? `${schema}_retiring`;
+  assertSafeSchema(schema);
+  assertSafeSchema(incoming);
+  assertSafeSchema(retiring);
+
+  const fks = crossSchemaForeignKeys(models, schema);
+  // Full authz for the swapped-in schema, from scratch (live side empty = every declared grant
+  // is a create) — the incoming schema was restored with privileges stripped.
+  const statsContracts = models
+    .filter((m) => (m.schema || 'public') === schema)
+    .map((m) => compileTableContract(m));
+  const authz = emitReconcileSql({ tables: statsContracts, functions: [] }, { tables: [], functions: [] });
+
+  const statements = [
+    ...fks.map((f) => f.dropSql),
+    `ALTER SCHEMA "${schema}" RENAME TO "${retiring}";`,
+    `ALTER SCHEMA "${incoming}" RENAME TO "${schema}";`,
+    ...fks.map((f) => f.addSql),
+    ...authz,
+  ];
+
+  return { statements, crossSchemaFks: fks, retiring, incoming };
+}
+
+/** The drop of the retiring schema, run AFTER the swap transaction commits and verify passes. */
+export function dropRetiringSql(retiring: string): string {
+  assertSafeSchema(retiring);
+  return `DROP SCHEMA IF EXISTS "${retiring}" CASCADE;`;
+}

package/src/cli/swap-execute.ts

@@ -0,0 +1,133 @@
+/**
+ * swap-execute — the db:swap ceremony: gate → snapshot → land incoming → atomic swap → verify →
+ * drop-retiring-or-rollback, as one function over an injected runner and injected IO.
+ *
+ * The destructive moves (the S3 artifact fetch, the pg_restore into the incoming schema, the RDS
+ * snapshot, the consumer's verify validators) are all injected, so this core is the DECISION spine
+ * and is proven on a real database without S3 or a deployed stage. The command shell wires the IO.
+ *
+ * Order, none skippable (docs/plans/canonical-sync-artifacts.md):
+ *   1. FINGERPRINT GATE — the artifact's declared-schema fingerprint must equal the target's
+ *      declared fingerprint, or REFUSE. Stale-shaped rows never load into a redefined schema.
+ *   2. SNAPSHOT — the rollback point, before anything destructive.
+ *   3. LAND INCOMING — restore the artifact into `<schema>_incoming` while live keeps serving.
+ *   4. ATOMIC SWAP — one transaction: drop app→schema FKs, rename out+in, recreate FKs (which
+ *      RE-VALIDATE against the new data — a bad artifact rolls back here), re-apply authz. A
+ *      failure rolls back whole; live never moved.
+ *   5. VERIFY — the post-commit hook runs against the swapped-in schema. A fatal verdict rolls the
+ *      stage back to the snapshot; a warn surfaces without rolling back.
+ *   6. DROP RETIRING — only after verify passes.
+ */
+
+import type { ModelDescriptor } from '@everystack/model';
+import type { QueryRunner } from './authz-contract.js';
+import { renderSchemaSwap, dropRetiringSql } from './schema-swap.js';
+
+/** One validator's result. A `fatal` (default) failure rolls back; a `warn` failure is surfaced only. */
+export interface SwapCheck {
+  name: string;
+  ok: boolean;
+  detail?: string;
+  severity?: 'fatal' | 'warn';
+}
+
+/** The post-commit verify hook's structured verdict — names WHICH validator failed, not just "failed". */
+export interface SwapVerdict {
+  ok: boolean;
+  checks?: SwapCheck[];
+}
+
+export interface ExecuteSwapOptions {
+  models: ModelDescriptor[];
+  schema: string;
+  incoming?: string;
+  retiring?: string;
+  /** The fingerprint the artifact was stamped with (from its meta). */
+  artifactFingerprint: string;
+  /** The target's DECLARED scoped fingerprint (the caller computes it from the checkout). */
+  declaredFingerprint: string;
+  /** Restore the artifact into the incoming schema (S3 → pg_restore → schema-rewrite → psql). */
+  applyIncoming: (runner: QueryRunner) => Promise<void>;
+  /** Take the pre-swap rollback point (db:snapshot / db:backup). Optional in tests. */
+  snapshot?: () => Promise<void>;
+  /** The consumer's post-commit validators — must see committed state, so they run after COMMIT. */
+  verify?: () => Promise<SwapVerdict>;
+  /** Restore the stage to the snapshot from step 2 when verify is fatal. */
+  rollbackToSnapshot?: () => Promise<void>;
+}
+
+export type SwapStatus =
+  | 'swapped'
+  | 'refused-fingerprint'
+  | 'refused-integrity'
+  | 'rolled-back-verify';
+
+export interface SwapResult {
+  status: SwapStatus;
+  reason?: string;
+  /** The verify verdict, when the hook ran. */
+  verdict?: SwapVerdict;
+  /** Warn-severity checks that did NOT trigger rollback (surfaced). */
+  warnings?: SwapCheck[];
+}
+
+/** Does the verdict force a rollback? Any failing check whose severity is fatal (the default). */
+export function isFatalVerdict(verdict: SwapVerdict): boolean {
+  if (verdict.ok) return false;
+  const checks = verdict.checks ?? [];
+  if (checks.length === 0) return true; // ok:false with no detail = fatal
+  return checks.some((c) => !c.ok && (c.severity ?? 'fatal') === 'fatal');
+}
+
+export async function executeSwap(runner: QueryRunner, opts: ExecuteSwapOptions): Promise<SwapResult> {
+  // 1. Fingerprint gate — declared-vs-declared: does the artifact and the target agree on the shape.
+  if (opts.artifactFingerprint !== opts.declaredFingerprint) {
+    return {
+      status: 'refused-fingerprint',
+      reason: `the artifact was built against ${opts.schema} fingerprint ${opts.artifactFingerprint.slice(0, 12)}, but the checkout declares ${opts.declaredFingerprint.slice(0, 12)} — rebase to the artifact's schema, or rebuild the artifact.`,
+    };
+  }
+
+  const plan = renderSchemaSwap(opts.models, { schema: opts.schema, incoming: opts.incoming, retiring: opts.retiring });
+
+  // 2. Snapshot (the rollback point) before anything destructive.
+  if (opts.snapshot) await opts.snapshot();
+
+  // 3. Land the incoming schema while live keeps serving.
+  await opts.applyIncoming(runner);
+
+  // 4. The atomic swap. A FK re-validation failure (a bad artifact) rolls the whole thing back.
+  await runner('BEGIN');
+  try {
+    await runner(plan.statements.join('\n'));
+    await runner('COMMIT');
+  } catch (err: any) {
+    try { await runner('ROLLBACK'); } catch { /* already aborted */ }
+    // Clean up the landed-but-unused incoming schema so a retry is idempotent.
+    try { await runner(`DROP SCHEMA IF EXISTS "${plan.incoming}" CASCADE`); } catch { /* best effort */ }
+    return {
+      status: 'refused-integrity',
+      reason: `the swap transaction failed — usually the cross-schema FK re-validation (an app row references a ${opts.schema} key the artifact dropped): ${String(err?.message ?? err)}`,
+    };
+  }
+
+  // 5. Verify (post-commit). Fatal → roll back to the snapshot; warn → surface only.
+  let verdict: SwapVerdict | undefined;
+  if (opts.verify) {
+    verdict = await opts.verify();
+    if (isFatalVerdict(verdict)) {
+      if (opts.rollbackToSnapshot) await opts.rollbackToSnapshot();
+      return {
+        status: 'rolled-back-verify',
+        reason: `verify failed: ${(verdict.checks ?? []).filter((c) => !c.ok).map((c) => c.name).join(', ') || 'no detail'} — rolled back to the pre-swap snapshot.`,
+        verdict,
+      };
+    }
+  }
+
+  // 6. Drop the retiring schema — the swap is committed and verified.
+  await runner(dropRetiringSql(plan.retiring));
+
+  const warnings = (verdict?.checks ?? []).filter((c) => !c.ok && c.severity === 'warn');
+  return { status: 'swapped', verdict, ...(warnings.length ? { warnings } : {}) };
+}