@everystack/cli 0.4.31 → 0.4.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.31",
+  "version": "0.4.33",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -100,6 +100,7 @@
     "@aws-sdk/client-lambda": "3.1053.0",
     "@aws-sdk/client-s3": "3.1053.0",
     "@aws-sdk/client-ssm": "3.1053.0",
+    "@aws-sdk/lib-storage": "3.1053.0",
     "@aws-sdk/client-sts": "3.1053.0",
     "@aws-sdk/signature-v4a": "3.1048.0",
     "glob": "13.0.6",
@@ -107,7 +108,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.4.4"
+    "@everystack/model": "0.4.5"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.1.0",

package/src/cli/aws.ts

@@ -13,7 +13,7 @@ let lambdaClient: InstanceType<typeof import('@aws-sdk/client-lambda').LambdaCli
 let kvsClient: InstanceType<typeof import('@aws-sdk/client-cloudfront-keyvaluestore').CloudFrontKeyValueStoreClient> | null = null;
 let rdsClient: InstanceType<typeof import('@aws-sdk/client-rds').RDSClient> | null = null;
 
-async function getS3(region: string) {
+export async function getS3(region: string) {
   if (!s3Client) {
     const { S3Client } = await importOptionalAws(
       () => import('@aws-sdk/client-s3'), '@aws-sdk/client-s3', 'this command',

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

@@ -4,14 +4,152 @@
  * db:backup/db:export run in the ephemeral Task lane (the ops Lambda holds no pg binaries); the CLI
  * dispatches and polls. db:backups/db:restore/download are thin invokeAction wrappers. The image's
  * version handshake is the compatibility gate — verify a deploy with `everystack task:probe`.
+ *
+ * db:backup has a SECOND venue for break-glass: `--database-url <local> --stage <target>` dumps a
+ * LOCAL database and uploads it into the target stage's backups bucket as a db:backup-shaped object
+ * (same key scheme + .meta.json + dump flags as a server backup). The standard credential-free
+ * `db:restore --from <id> --stage <target>` then lands it via the Task lane (pg_restore runs as the
+ * privileged `migrator` role, which can CREATE SCHEMA + own objects). The local dump is the only
+ * held connection; the upload rides the operator's AWS credentials — the same trust boundary as
+ * db:fork's cross-stage presign. This is the sanctioned local→stage full replace on a role-managed
+ * stage (raw pg_restore can't: the operator/api role can't CREATE SCHEMA, and only the master could).
  */
 
+import { spawn } from 'node:child_process';
+import { createGzip } from 'node:zlib';
+import { pipeline } from 'node:stream/promises';
+import { randomBytes } from 'node:crypto';
 import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
-import { invokeAction, presignGet } from '../aws.js';
-import { parseBackupRef, keyForId, crossStageGuard, restoreTargetGuard } from '../backup.js';
+import { invokeAction, presignGet, getS3 } from '../aws.js';
+import {
+  parseBackupRef, keyForId, crossStageGuard, restoreTargetGuard,
+  backupKey, backupId, metaKey, utcStamp,
+} from '../backup.js';
+import { pgEnvFromUrl } from './db.js';
 import { pollTaskUntilStopped } from '../task-poll.js';
 import { step, success, fail, info, warn } from '../output.js';
 
+/** Which database db:backup dumps. LOCAL requires a target --stage (its bucket receives the upload
+ *  AND names the backup id). Note this DIVERGES from db:export, where --database-url and --stage are
+ *  mutually-exclusive venues: here the local venue COMBINES them (dump local → upload to the stage). */
+export type BackupVenue =
+  | { kind: 'local'; url: string; stage: string }
+  | { kind: 'stage'; stage: string | undefined };
+
+export function resolveBackupVenue(flags: Record<string, string>): BackupVenue {
+  const url = flags['database-url'];
+  if (url) {
+    if (!flags.stage) {
+      throw new Error(
+        'db:backup --database-url <local> also needs --stage <target> — the local dump uploads into '
+        + "that stage's backups bucket, and the stage names the backup id `db:restore --from` consumes.",
+      );
+    }
+    return { kind: 'local', url, stage: flags.stage };
+  }
+  return { kind: 'stage', stage: flags.stage };
+}
+
+/**
+ * Full-DB streaming pg_dump args — IDENTICAL to the server's db:backup dump (packages/server
+ * backup.ts pgDumpArgs()), minus `-f`: streamed to stdout so it pipes into gzip → S3. Excludes the
+ * everystack ops schema (task_log/schema_log/etc — the TARGET's own audit history, not app data;
+ * restoring it would rewind that history AND makes pg_restore --clean fail on DROP SCHEMA everystack).
+ */
+export function pgDumpFullArgs(): string[] {
+  return ['-Fc', '--no-owner', '--no-privileges', '--no-comments', '--exclude-schema=everystack'];
+}
+
+/** The .meta.json sidecar — byte-shape identical to the server's runBackup meta (backup-run.ts:156),
+ *  so db:backups list and the destructive-apply gate read a local upload exactly like a stage backup.
+ *  `bytes` is undefined-safe (JSON.stringify drops it) exactly as the server leaves it on a failed
+ *  HeadObject — never coerced to 0. */
+export function localBackupMeta(opts: {
+  id: string;
+  stage: string;
+  createdAt: Date;
+  bytes?: number;
+  key: string;
+}): Record<string, unknown> {
+  return {
+    id: opts.id,
+    stage: opts.stage,
+    createdAt: opts.createdAt.toISOString(),
+    bytes: opts.bytes,
+    key: opts.key,
+  };
+}
+
+/**
+ * Stream a local database into a stage's backups bucket as a db:backup-shaped object. Mirrors the
+ * server's runBackup streaming AND its load-bearing correctness rule: a completed S3 multipart upload
+ * does NOT mean pg_dump succeeded (pg_dump can exit non-zero mid-stream while the upload "completes"),
+ * so we await the child exit code SEPARATELY and, on any failure, abort the upload and delete the
+ * partial object. A backup tool that ships a truncated dump is worse than none.
+ */
+export async function runLocalBackupUpload(deps: {
+  region: string;
+  bucket: string;
+  url: string;
+  stage: string;
+}): Promise<{ id: string; key: string; bytes?: number }> {
+  const now = new Date();
+  const stamp = utcStamp(now);
+  const shortId = randomBytes(3).toString('hex');
+  const key = backupKey(deps.stage, stamp, shortId);
+  const id = backupId(deps.stage, stamp, shortId);
+  const mkey = metaKey(key);
+
+  const env = { ...process.env, ...pgEnvFromUrl(deps.url) };
+  const s3 = await getS3(deps.region);
+  const { Upload } = await import('@aws-sdk/lib-storage');
+  const { DeleteObjectCommand, PutObjectCommand, HeadObjectCommand } = await import('@aws-sdk/client-s3');
+
+  const child = spawn('pg_dump', pgDumpFullArgs(), { env, stdio: ['ignore', 'pipe', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', (d) => { stderr += d.toString(); });
+  const childExit = 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()}`)));
+  });
+
+  const gzip = createGzip();
+  const upload = new Upload({
+    client: s3,
+    params: {
+      Bucket: deps.bucket, Key: key, Body: gzip,
+      ContentType: 'application/gzip', ServerSideEncryption: 'AES256',
+    },
+  });
+
+  try {
+    await Promise.all([
+      pipeline(child.stdout!, gzip), // pg_dump → gzip; errors propagate, streams destroyed
+      upload.done(),                 // gzip → S3 multipart
+      childExit,                     // the guard: non-zero pg_dump rejects the whole thing
+    ]);
+  } catch (err) {
+    try { await upload.abort(); } catch { /* may already have completed */ }
+    await s3.send(new DeleteObjectCommand({ Bucket: deps.bucket, Key: key })).catch(() => {});
+    throw err;
+  }
+
+  let bytes: number | undefined;
+  try {
+    const head = await s3.send(new HeadObjectCommand({ Bucket: deps.bucket, Key: key }));
+    bytes = head.ContentLength;
+  } catch { /* size is best-effort */ }
+
+  await s3.send(new PutObjectCommand({
+    Bucket: deps.bucket, Key: mkey,
+    Body: JSON.stringify(localBackupMeta({ id, stage: deps.stage, createdAt: now, bytes, key })),
+    ContentType: 'application/json', ServerSideEncryption: 'AES256',
+  }));
+
+  return { id, key, bytes };
+}
+
 function fmtBytes(n?: number): string {
   if (n == null) return '-';
   if (n < 1024) return `${n} B`;
@@ -27,6 +165,53 @@ function fmtBytes(n?: number): string {
  * the compatibility gate (a too-old image fails the run loudly — no separate layer pre-flight).
  */
 export async function dbBackupCommand(flags: Record<string, string>): Promise<void> {
+  let venue: BackupVenue;
+  try {
+    venue = resolveBackupVenue(flags);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+
+  // Local venue: dump a reachable database here and upload it into the target stage's backups bucket
+  // as a db:backup-shaped object, so `db:restore --from <id> --stage <target>` lands it credential-free.
+  if (venue.kind === 'local') {
+    step('Resolving deployed config...');
+    let config: CliConfig;
+    try {
+      config = await resolveConfig(venue.stage);
+    } catch (err: any) {
+      fail(err.message);
+      process.exit(1);
+    }
+    if (!config.backupsBucket) {
+      fail('No backupsBucket in the deployed config. Add `backupsBucket: backups.name` to sst.config outputs and redeploy.');
+      process.exit(1);
+    }
+    info(`Region: ${config.region}, Bucket: ${config.backupsBucket}`);
+    // Version gate for the local venue: unlike the stage venue (whose pg binaries are the Task image),
+    // this dumps with the OPERATOR's pg_dump. pg_restore refuses an archive from a NEWER pg_dump major,
+    // so a mismatch surfaces only at restore time ("unsupported version in file header") — loud and
+    // lossless (it fails before --clean drops anything), but discovered exactly when you need the
+    // backup. Surface the local major up front so the operator can match it to the target's PG major.
+    try {
+      const { execFileSync } = await import('node:child_process');
+      const v = execFileSync('pg_dump', ['--version']).toString().trim();
+      info(`Local ${v} — must be ≤ the target stage's PostgreSQL major, or db:restore will reject the dump.`);
+    } catch { /* a missing pg_dump surfaces loudly in the dump step below */ }
+    step(`Running pg_dump (full, --exclude-schema=everystack) against --database-url → S3 (this may take a while for large databases)...`);
+    try {
+      const res = await runLocalBackupUpload({
+        region: config.region, bucket: config.backupsBucket, url: venue.url, stage: venue.stage,
+      });
+      success(`Backup ${res.id} (${fmtBytes(res.bytes)}). Restore with: everystack db:restore --from ${res.id} --stage ${venue.stage} --confirm`);
+    } catch (err: any) {
+      fail(`Backup failed: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
   step('Resolving deployed config...');
   let config: CliConfig;
   try {

package/src/cli/declared-derived.ts

@@ -13,7 +13,7 @@ import fs from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
 import type { Module, ModelDescriptor, SequenceDescriptor, DerivedDescriptor } from '@everystack/model';
 import { compileDerived } from './derived-compile.js';
-import { compileTableRenames } from './schema-compile.js';
+import { compileTableRenames, compileTableMoves } from './schema-compile.js';
 import type { SourceObject } from './derived-source.js';
 import { resolveModelsPath } from './models-path.js';
 import { asModelComposeError } from './ops-advice.js';
@@ -168,7 +168,10 @@ export function composeDeclaredDerived(modules: Module[], modelsPath: string): D
       objects: compileDerived(models, derived),
       derived,
       sequences: modules.flatMap((m) => m.sequences),
-      renamedTables: compileTableRenames(models, {}),
+      // A table's qualified identity changes under BOTH a rename (new name) and a move
+      // (new schema); PostgreSQL carries triggers through ALTER TABLE ... RENAME and
+      // ... SET SCHEMA alike, so the trigger-provenance migration is identical — feed both.
+      renamedTables: { ...compileTableRenames(models, {}), ...compileTableMoves(models, {}) },
       models,
     };
   } catch (err) {

package/src/cli/edge-plan.ts

@@ -32,7 +32,7 @@ import { generateMigrationSql, unmodeledTables } from './migration-generate.js';
 import { classifyGeneratedStatements, classifyDestructive, renderStatementHistogram } from './state-apply.js';
 import { fingerprintLive, fingerprintState, fingerprintModels, stableStringify } from './schema-fingerprint.js';
 import { compileDeclaredState } from './declared-diff.js';
-import { compileTableRenames } from './schema-compile.js';
+import { compileTableRenames, compileTableMoves } from './schema-compile.js';
 
 export const PLAN_VERSION = 2;
 
@@ -101,8 +101,16 @@ export function predictLiveFingerprint(
       .filter(([to, from]) => !currentNames.has(to) && currentNames.has(from))
       .map(([, from]) => from),
   );
+  // A move's source is consumed by the move (SET SCHEMA), not left behind — so it does NOT
+  // ride through into the predicted endpoint. Without this the prediction counts the
+  // moved-away table and every move plan mismatches its own verify-after (F3).
+  const pendingMoveSources = new Set(
+    Object.entries(compileTableMoves(models, { schema: opts.schema }))
+      .filter(([to, from]) => !currentNames.has(to) && currentNames.has(from))
+      .map(([, from]) => from),
+  );
   const ridesThrough = (table: string): boolean =>
-    !declaredTables.has(table) && !pendingRenameSources.has(table);
+    !declaredTables.has(table) && !pendingRenameSources.has(table) && !pendingMoveSources.has(table);
   const declaredEnumList = declared.snapshot.enums ?? [];
   const declaredEnums = new Set(declaredEnumList.map((e) => e.name));
   const mergedSnapshot: SchemaSnapshot = {

package/src/cli/index.ts

@@ -368,7 +368,7 @@ Usage:
   everystack db:provision      --stage <name> [--direct | --database-url <url>]  Create the least-privilege role chain on an EXISTING database (idempotent; creates no DB). No flag = ops-Lambda venue (auto-falls to direct via the ADMIN_DATABASE_URL secret if the handler has no dbPlugin). --direct = direct connection reading that secret (master never on argv); --database-url = explicit URL. Declared schemas are set as the ROLE default (ALTER ROLE … SET search_path) — the secret stays credentials-only, and the URL is libpq-clean
   everystack db:snapshot       [--stage <name>] [--instance <id>]  Take a physical RDS snapshot (instant DR point; RDS only — use db:backup for portable logical backups)
   everystack db:snapshots      [--stage <name>] [--instance <id>]  List manual RDS snapshots for the instance
-  everystack db:backup         [--stage <name>]  Logical pg_dump of the DB → private S3 backups bucket (prints the backup id)
+  everystack db:backup         [--stage <name>]  Logical pg_dump of the DB → private S3 backups bucket (prints the backup id). Add --database-url <local> --stage <target> to dump a LOCAL database and upload it into the target stage's bucket as a restorable backup — the credential-free break-glass local→stage full replace (then: db:restore --from <id> --stage <target>)
   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)

package/src/cli/migration-generate.ts

@@ -18,7 +18,7 @@
 import type { ModelDescriptor, SequenceDescriptor } from '@everystack/model';
 import type { SchemaSnapshot } from './schema-introspect.js';
 import type { AuthzContract } from './authz-contract.js';
-import { compileTableSchema, compileRenames, compileTableRenames, compileCreateTable, compileEnums, compileSequences } from './schema-compile.js';
+import { compileTableSchema, compileRenames, compileTableRenames, compileTableMoves, compileCreateTable, compileEnums, compileSequences } from './schema-compile.js';
 import { compileTableContract } from './authz-compile.js';
 import { emitReconcileSql } from './authz-reconcile.js';
 import { diffSchema, emitSchemaSql, type SchemaChange } from './schema-diff.js';
@@ -84,11 +84,16 @@ function holdDrop(sql: string): string {
 export function unmodeledTables(models: ModelDescriptor[], current: SchemaSnapshot, opts: GenerateOptions = {}): string[] {
   const schema = opts.schema ?? 'public';
   const declared = new Set(models.map((m) => `${schema}.${m.table}`));
-  // A pending table rename's source is ours — declared under its new name.
+  // A pending table rename's OR move's source is ours — declared under its new (qualified)
+  // name; without this it reads as an undeclared orphan (F1) and the move/rename silently
+  // degrades to CREATE + leave-behind, the exact bug the markers exist to prevent.
   const currentNames = new Set(current.tables.map((t) => t.table));
   for (const [to, from] of Object.entries(compileTableRenames(models, { schema }))) {
     if (!currentNames.has(to)) declared.add(from);
   }
+  for (const [to, from] of Object.entries(compileTableMoves(models, { schema }))) {
+    if (!currentNames.has(to)) declared.add(from);
+  }
   return current.tables.map((t) => t.table).filter((t) => !declared.has(t)).sort();
 }
 
@@ -131,20 +136,28 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
     .map((s) => `CREATE SCHEMA IF NOT EXISTS "${s}"`);
 
   const tableRenames = compileTableRenames(models, { schema });
+  const tableMoves = compileTableMoves(models, { schema });
   const currentNames = new Set(current.tables.map((t) => t.table));
   const pendingRenameSources = new Set(
     Object.entries(tableRenames)
       .filter(([to, from]) => !currentNames.has(to) && currentNames.has(from))
       .map(([, from]) => from),
   );
+  // A move's source (old schema, same name) must survive the declared-scope filter too —
+  // else the diff's pre-pass never sees it and the move degrades to CREATE + orphan (F1).
+  const pendingMoveSources = new Set(
+    Object.entries(tableMoves)
+      .filter(([to, from]) => !currentNames.has(to) && currentNames.has(from))
+      .map(([, from]) => from),
+  );
   const scopedCurrent: SchemaSnapshot = opts.scope === 'full'
     ? { tables: current.tables, enums: current.enums ?? [] }
     : {
-        tables: current.tables.filter((t) => declaredTables.has(t.table) || pendingRenameSources.has(t.table)),
+        tables: current.tables.filter((t) => declaredTables.has(t.table) || pendingRenameSources.has(t.table) || pendingMoveSources.has(t.table)),
         enums: (current.enums ?? []).filter((e) => declaredEnums.has(e.name)),
       };
   const renames = compileRenames(models, { schema });
-  const changes = diffSchema(desired, scopedCurrent, renames, tableRenames);
+  const changes = diffSchema(desired, scopedCurrent, renames, tableRenames, tableMoves);
 
   const modelByTable = new Map(models.map((m) => [`${schemaOf(m)}.${m.table}`, m]));
   const emitted = emitSchemaSql(changes, {
@@ -174,11 +187,18 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
   // data DDL just created. Emitted only when the live contract is supplied; the Models'
   // `abilities` compile to the same contract shape introspection reads, so the two diff.
   // Authz changes are data-safe (no row touches), so they are never held by `allowDrops`.
-  const pendingByFrom = new Map(
-    Object.entries(tableRenames)
+  // A moved table carries its policies/grants with it through SET SCHEMA (OID-attached),
+  // so the live authz keyed under the OLD schema must be read under the NEW name — else
+  // emitReconcileSql finds no live entry and emits a bare CREATE POLICY that collides
+  // post-move and rolls back the whole apply (F2). Same rewrite the rename path relies on.
+  const pendingByFrom = new Map([
+    ...Object.entries(tableRenames)
       .filter(([, from]) => pendingRenameSources.has(from))
       .map(([to, from]) => [from, to] as const),
-  );
+    ...Object.entries(tableMoves)
+      .filter(([, from]) => pendingMoveSources.has(from))
+      .map(([to, from]) => [from, to] as const),
+  ]);
   const liveAuthzRenamed = opts.liveAuthz && pendingByFrom.size > 0
     ? {
         ...opts.liveAuthz,

package/src/cli/schema-compile.ts

@@ -575,3 +575,20 @@ export function compileTableRenames(models: ModelDescriptor[], opts: { schema?:
   }
   return map;
 }
+
+/**
+ * Table-level MOVE intent: qualified new name → qualified old name, SAME table name in a
+ * DIFFERENT schema (the cross-schema twin of `compileTableRenames`). Produced off the
+ * Models' `movedFrom` option, consumed by `diffSchema`'s pre-pass, which turns a
+ * create-in-new-schema + undeclared orphan into one `ALTER TABLE … SET SCHEMA …`.
+ */
+export function compileTableMoves(models: ModelDescriptor[], opts: { schema?: string } = {}): Record<string, string> {
+  const map: Record<string, string> = {};
+  for (const model of models) {
+    if (!model.movedFrom) continue;
+    const newSchema = model.schema ?? opts.schema ?? 'public';
+    // Same table name; only the schema changes. from = old schema, to = new schema.
+    map[`${newSchema}.${model.table}`] = `${model.movedFrom}.${model.table}`;
+  }
+  return map;
+}

package/src/cli/schema-diff.ts

@@ -72,6 +72,12 @@ export type SchemaChange =
   | { kind: 'renameTableSatisfied'; table: string; from: string }
   /** A table marker pointing at a table the database doesn't have — fell back to CREATE, a notice. */
   | { kind: 'renameTableSourceMissing'; table: string; from: string }
+  /** A table-level `movedFrom` satisfied: old-schema table present, new absent → one SET SCHEMA, data preserved. */
+  | { kind: 'moveTable'; from: string; to: string }
+  /** A move marker whose move is already applied (table already in the new schema) — inert, a notice. */
+  | { kind: 'moveTableSatisfied'; table: string; from: string }
+  /** A move marker pointing at a table absent in BOTH schemas — fell back to CREATE, a notice. */
+  | { kind: 'moveTableSourceMissing'; table: string; from: string }
   /** A new enum type → `CREATE TYPE … AS ENUM (…)`, emitted before the tables that use it. */
   | { kind: 'createType'; name: string; values: string[] }
   /** A value appended to an existing enum → `ALTER TYPE … ADD VALUE` (carries a -- WARNING). */
@@ -105,6 +111,15 @@ export type RenameMap = Record<string, Record<string, string>>;
  */
 export type TableRenameMap = Record<string, string>;
 
+/**
+ * Table-level MOVE intent: qualified new name → qualified old name (SAME table name, a
+ * DIFFERENT schema). Produced by `compileTableMoves` off the Models' `movedFrom` option;
+ * consumed by `diffSchema`'s pre-pass, which rewrites the current snapshot (old-schema
+ * table seen under its new qualified name, and every referencing FK re-pointed) so a
+ * create-in-new-schema + orphan collapses to one `ALTER TABLE … SET SCHEMA …`.
+ */
+export type TableMoveMap = Record<string, string>;
+
 // ---------------------------------------------------------------------------
 // Normalization — so semantically-equal expressions don't read as drift.
 // ---------------------------------------------------------------------------
@@ -290,8 +305,9 @@ export function normalizeCheck(expr: string): string {
  * replaced constraint never clashes with its old self and a column is never dropped out
  * from under a constraint that still references it.
  */
-export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, renames: RenameMap = {}, tableRenames: TableRenameMap = {}): SchemaChange[] {
+export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, renames: RenameMap = {}, tableRenames: TableRenameMap = {}, tableMoves: TableMoveMap = {}): SchemaChange[] {
   const creates: SchemaChange[] = [];
+  const moveTables: SchemaChange[] = [];
   const renameTables: SchemaChange[] = [];
   const renameColumns: SchemaChange[] = [];
   const addColumns: SchemaChange[] = [];
@@ -307,6 +323,55 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
   const currentByName = new Map(current.tables.map((t) => [t.table, t]));
   const desiredNames = new Set(desired.tables.map((t) => t.table));
 
+  // Table-move pre-pass: honor the Models' cross-schema `movedFrom` before any matching
+  // (runs before the rename pre-pass; a table cannot carry both markers — defineModel
+  // forbids it). SET SCHEMA carries the table's data, indexes, constraints, policies,
+  // grants, triggers and owned sequences with it (OID-attached), so a satisfied move
+  // rewrites the current snapshot: the old-schema table is seen under its new qualified
+  // name (every downstream column/constraint/index diff lands on it, and the old name
+  // never reaches the dropTables sweep), AND every referencing FK is re-pointed old→new.
+  // new-name-present → inert notice; source absent in both schemas → CREATE path + notice.
+  for (const [to, from] of Object.entries(tableMoves)) {
+    if (!desiredNames.has(to)) continue; // the marker's model isn't in this diff
+    if (currentByName.has(to)) {
+      notices.push({ kind: 'moveTableSatisfied', table: to, from });
+      continue;
+    }
+    const source = currentByName.get(from);
+    if (!source) {
+      notices.push({ kind: 'moveTableSourceMissing', table: to, from });
+      continue;
+    }
+    moveTables.push({ kind: 'moveTable', from, to });
+    currentByName.delete(from);
+    // The table's OWNED sequences ride SET SCHEMA too, so a serial default that qualified
+    // the old schema (`nextval('stats.foo_id_seq')`) reads `nextval('curated.foo_id_seq')`
+    // after the move — rewrite it on the copied source so it does not churn as a spurious
+    // SET DEFAULT (F8). Only the moved table's OWN sequence-qualified defaults are touched.
+    const fromSchema = from.split('.')[0];
+    const toSchema = to.split('.')[0];
+    // Literal replace (split/join), not a RegExp — a schema name can be a quoted identifier
+    // carrying regex metacharacters, which `new RegExp` would misfire or throw on.
+    const requalifyDefault = (d: string | null): string | null =>
+      d == null ? d : d.split(`nextval('${fromSchema}.`).join(`nextval('${toSchema}.`);
+    currentByName.set(to, {
+      ...source,
+      table: to,
+      columns: source.columns.map((col) => (col.default != null ? { ...col, default: requalifyDefault(col.default) } : col)),
+    });
+    // F4: re-point every referencing FK (including the moved table's own self-FKs) from
+    // the old qualified name to the new, across the WHOLE current snapshot — so a
+    // referencing table's FK content-key matches the desired side and Postgres's
+    // carried-through FK is not needlessly dropped and re-added.
+    for (const [name, t] of currentByName) {
+      if (!t.foreignKeys.some((fk) => fk.refTable === from)) continue;
+      currentByName.set(name, {
+        ...t,
+        foreignKeys: t.foreignKeys.map((fk) => (fk.refTable === from ? { ...fk, refTable: to } : fk)),
+      });
+    }
+  }
+
   // Table-rename pre-pass: honor the Models' table-level `renamedFrom` before
   // any matching. A satisfied rename rewrites the current snapshot — the old
   // table is seen under its new name — so every downstream diff (columns,
@@ -404,6 +469,7 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
   // the other removals; notices are comments — emitted last, after the DDL.
   return [
     ...e.creates, ...e.adds, ...sequenceCreates,
+    ...moveTables,
     ...renameTables,
     ...creates, ...renameColumns, ...addColumns, ...alters, ...trailingDefaults,
     ...dropConstraints, ...addConstraints, ...createIndexes,
@@ -753,6 +819,16 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string {
     case 'renameTable':
       // RENAME TO takes a bare name — the table stays in its schema.
       return `ALTER TABLE ${change.from} RENAME TO ${quote(change.to.split('.').pop()!)};`;
+    case 'moveTable':
+      // SET SCHEMA takes a bare schema name; the table keeps its name and carries its data,
+      // indexes, constraints, policies, grants, triggers and owned sequences with it. The
+      // WARNING (not NOTICE — this statement is executable; NOTICE is the reserved pure-comment
+      // prefix) flags the consumer-breakage surface a move can't see (see F7).
+      return `-- WARNING: ${change.from} moves to schema ${change.to.split('.')[0]} — unqualified readers resolve by search_path (verify ordering), and qualified references (views, functions, app queries naming ${change.from}) must be updated + reconciled.\nALTER TABLE ${change.from} SET SCHEMA ${quote(change.to.split('.')[0])};`;
+    case 'moveTableSatisfied':
+      return `-- NOTICE: the movedFrom marker on table ${change.table} is satisfied — the table already exists in its declared schema, ASSUMED to be the completed move from "${change.from.split('.')[0]}" (a pre-existing unrelated table of the same name would read the same); the marker is now inert and can be removed.`;
+    case 'moveTableSourceMissing':
+      return `-- NOTICE: table ${change.table} declares movedFrom "${change.from.split('.')[0]}", but the database has it in neither schema — created fresh; remove the marker once every environment is past it.`;
     case 'renameTableSatisfied':
       return `-- NOTICE: the renamedFrom marker on table ${change.table} is satisfied — the rename from "${change.from}" is applied, the marker is now inert and can be removed.`;
     case 'renameTableSourceMissing':