@metaobjectsdev/migrate-ts 0.23.2 → 0.24.1

package/dist/verify/replay.js

@@ -2,6 +2,7 @@ import { applyPending } from "../apply/apply.js";
 import { MIGRATIONS_TABLE } from "../apply/ledger.js";
 import { introspect } from "../introspect/index.js";
 import { driftAgainstSnapshot } from "../drift/classify.js";
+import { excludeFromSnapshot } from "../scope.js";
 /**
  * Replay all committed migrations into a fresh database, introspect the result,
  * and compare it to the committed snapshot. A non-empty `drift`/`unmanaged` means
@@ -16,7 +17,12 @@ export async function verifyReplay(args) {
         ...introspected,
         tables: introspected.tables.filter((t) => t.name !== MIGRATIONS_TABLE),
     };
-    const classification = await driftAgainstSnapshot(args.snapshot, actual, args.dialect);
+    // `excludeFromSnapshot` returns a ScopedExpectedSchema, so take `.snapshot`. With an
+    // empty `outOfScope` it returns the SAME object, not an equal copy.
+    const expected = args.governed !== undefined
+        ? excludeFromSnapshot(args.snapshot, args.governed).snapshot
+        : args.snapshot;
+    const classification = await driftAgainstSnapshot(expected, actual, args.dialect);
     return {
         ...classification,
         ok: classification.drift.length === 0 && classification.unmanaged.length === 0,

package/dist/verify/replay.js.map

@@ -1 +1 @@
-{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../src/verify/replay.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAA4B,MAAM,sBAAsB,CAAC;AAkBtF;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAsB;IACvD,MAAM,YAAY,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,aAAa,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1F,MAAM,YAAY,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAmB;QAC7B,GAAG,YAAY;QACf,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,gBAAgB,CAAC;KACvE,CAAC;IACF,MAAM,cAAc,GAAG,MAAM,oBAAoB,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACvF,OAAO;QACL,GAAG,cAAc;QACjB,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,cAAc,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;KAC/E,CAAC;AACJ,CAAC"}
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../src/verify/replay.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAA4B,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAE,mBAAmB,EAAsB,MAAM,aAAa,CAAC;AAgCtE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAsB;IACvD,MAAM,YAAY,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,aAAa,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1F,MAAM,YAAY,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAmB;QAC7B,GAAG,YAAY;QACf,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,gBAAgB,CAAC;KACvE,CAAC;IACF,qFAAqF;IACrF,oEAAoE;IACpE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,KAAK,SAAS;QAC1C,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ;QAC5D,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC;IAClB,MAAM,cAAc,GAAG,MAAM,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAClF,OAAO;QACL,GAAG,cAAc;QACjB,EAAE,EAAE,cAAc,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,cAAc,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;KAC/E,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/migrate-ts",
-  "version": "0.23.2",
+  "version": "0.24.1",
   "description": "Schema migration tooling for MetaObjects: diff metadata vs DB and emit SQL for Postgres and SQLite.",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,12 +45,23 @@
   },
   "dependencies": {
     "@iarna/toml": "^2.2.5",
-    "@metaobjectsdev/metadata": "0.23.2"
+    "@metaobjectsdev/metadata": "0.24.1"
   },
   "peerDependencies": {
-    "kysely": ">=0.27.0 <0.30.0"
+    "kysely": ">=0.27.0 <0.30.0",
+    "@electric-sql/pglite": ">=0.3.0 <0.6.0",
+    "@libsql/kysely-libsql": ">=0.4.0 <0.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    },
+    "@libsql/kysely-libsql": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.5.0",
     "@libsql/kysely-libsql": "^0.4.1",
     "@types/pg": "^8.20.0",
     "bun-types": "latest",

package/src/diff/index.ts

@@ -15,6 +15,7 @@ import { viewReplaceIsLegal } from "../view-column-types.js";
 import { checkExprEquals, normalizeCheckExpr } from "../check-expr-compare.js";
 import { isPgAutoSequenceDefault } from "../pg-identity-default.js";
 import { DEFAULT_DB_SCHEMA_POSTGRES } from "@metaobjectsdev/metadata";
+import { qualifiedDbName } from "../qualified-name.js";
 
 export interface DiffArgs {
   expected: SchemaSnapshot;
@@ -90,10 +91,12 @@ const DEFAULT_IGNORE_TABLES: string[] = [
  *
  * For SQLite (no schema concept), every table has schema=undefined, so this maps
  * all tables to the same "public." prefix — harmless and preserves existing behavior.
+ *
+ * `qualifiedDbName` is THE definition (qualified-name.ts): the act-side exclusion
+ * sets — declared-`@unmanaged` and out-of-scope — are matched against these keys, so
+ * a second spelling here would silently un-suppress an object and propose its drop.
  */
-function tableIdentity(table: { name: string; schema?: string }): string {
-  return (table.schema ?? DEFAULT_DB_SCHEMA_POSTGRES) + "." + table.name;
-}
+const tableIdentity = qualifiedDbName;
 
 /**
  * Build the optional-schema spread used when constructing Change records.
@@ -151,7 +154,7 @@ export async function diff(
   const declaredSchemas = new Set([
     ...args.expected.tables.map((t) => t.schema ?? DEFAULT_DB_SCHEMA_POSTGRES),
     // A model that declares views in a schema with no table of its own (e.g. an
-    // API/read-model schema like `p3_api` sitting alongside an all-`public`
+    // API/read-model schema like `acme_api` sitting alongside an all-`public`
     // entity model) must still bring that schema into scope — otherwise its
     // views are silently excluded from BOTH sides of the diff (never compared,
     // so real drift in an opaque @sql body or a genuine missing/extra view goes
@@ -590,9 +593,7 @@ function diffTableChecks(
   }
 }
 
-function viewIdentity(v: { name: string; schema?: string }): string {
-  return (v.schema ?? DEFAULT_DB_SCHEMA_POSTGRES) + "." + v.name;
-}
+const viewIdentity = qualifiedDbName;
 
 /**
  * Decide, per view, whether the DB matches the model.

package/src/drift/drift.ts

@@ -16,10 +16,11 @@
 import type { Kysely } from "kysely";
 import type { MetaRoot } from "@metaobjectsdev/metadata";
 import type { ColumnNamingStrategy } from "@metaobjectsdev/metadata";
-import { buildExpectedSchema } from "../expected-schema.js";
+import { buildExpectedSchemaWithProvenance } from "../expected-schema.js";
 import { introspect } from "../introspect/index.js";
 import { diff } from "../diff/index.js";
 import { collectUnmanagedNames } from "../unmanaged.js";
+import { scopeExpectedSchema, scopedDiffInputs, type ObjectScopePredicate } from "../scope.js";
 import type { AllowOptions, Dialect, DiffResult, SchemaSnapshot } from "../types.js";
 
 export interface ComputeDriftOptions {
@@ -46,6 +47,36 @@ export interface ComputeDriftOptions {
    * itself; pass these so view drift is detected. Defaults to none.
    */
   views?: readonly import("../expected-schema.js").ExpectedViewInput[];
+  /**
+   * Per-command scope (`migrate.scope`): objects whose declaring FQN this predicate
+   * rejects are governed by somebody else. They leave the expected side AND are
+   * suppressed on the actual side, so their divergence is neither drift nor a
+   * proposed drop — `verify` reports them as out-of-scope instead (see
+   * `DriftResult.outOfScope`). Omit to govern everything loaded (unchanged behavior).
+   *
+   * `verify --db` and `migrate` deliberately share ONE declaration: a drift gate
+   * failing on tables migrate does not own is incoherent.
+   */
+  inScope?: ObjectScopePredicate;
+}
+
+export interface DriftResult extends DiffResult {
+  /**
+   * Qualified physical names excluded by `inScope` — empty when no scope was
+   * given. The caller REPORTS these: an object silently dropped from the
+   * comparison is indistinguishable from one that was checked and found clean.
+   */
+  outOfScope: readonly string[];
+  /**
+   * The schemas this comparison governed (`ScopedExpectedSchema.declaredSchemas`),
+   * `undefined` when no scope was given and `diff` derived its own.
+   *
+   * Reported so a SECOND comparison over the same run — `verify`'s committed-snapshot
+   * gate — can govern exactly the same schemas instead of re-deriving them from a
+   * different expected side. Together with `outOfScope` this pair is a
+   * `GovernedScope`, which is what `excludeFromSnapshot` takes.
+   */
+  declaredSchemas: readonly string[] | undefined;
 }
 
 /**
@@ -65,24 +96,33 @@ export async function computeDriftFromActual(
   dialect: Dialect,
   metadata: MetaRoot,
   opts?: ComputeDriftOptions,
-): Promise<DiffResult> {
-  const expected = buildExpectedSchema(metadata, {
-    dialect,
-    ...(opts?.columnNamingStrategy !== undefined
-      ? { columnNamingStrategy: opts.columnNamingStrategy }
-      : {}),
-    ...(opts?.views !== undefined ? { views: opts.views } : {}),
-  });
-  return diff({
-    expected,
+): Promise<DriftResult> {
+  const scoped = scopeExpectedSchema(
+    buildExpectedSchemaWithProvenance(metadata, {
+      dialect,
+      ...(opts?.columnNamingStrategy !== undefined
+        ? { columnNamingStrategy: opts.columnNamingStrategy }
+        : {}),
+      ...(opts?.views !== undefined ? { views: opts.views } : {}),
+    }),
+    opts?.inScope,
+  );
+  const result = await diff({
+    // The three scoped-diff obligations as one value (see scope.ts's header):
+    // the narrowed expected side, `unmanagedNames` merging @unmanaged with the
+    // out-of-scope names so neither is proposed for drop, and the schema scope
+    // pinned to the UNSCOPED model so a narrow scope can never widen the run.
+    ...scopedDiffInputs(scoped, collectUnmanagedNames(metadata)),
     actual,
     dialect,
     allow: opts?.allow ?? {},
-    // #208 §7 — a declared-@unmanaged object is external, so it is not drift: exclude it
-    // from the actual side (same as `meta migrate`) rather than surface a false drop-*.
-    unmanagedNames: collectUnmanagedNames(metadata),
     ...(opts?.ignoreTables !== undefined ? { ignoreTables: opts.ignoreTables } : {}),
   });
+  return {
+    ...result,
+    outOfScope: scoped.outOfScope,
+    declaredSchemas: scoped.declaredSchemas,
+  };
 }
 
 /**
@@ -97,7 +137,7 @@ export async function computeDrift(
   dialect: Dialect,
   metadata: MetaRoot,
   opts?: ComputeDriftOptions,
-): Promise<DiffResult> {
+): Promise<DriftResult> {
   const actual = await introspect(db, dialect);
   return computeDriftFromActual(actual, dialect, metadata, opts);
 }

package/src/emit/postgres.ts

@@ -54,16 +54,53 @@ export function renderPostgres(changes: Change[]): EmitResult {
   }
   // Down runs in reverse order (so creates undo correctly w.r.t. FKs).
   return {
-    up: upStmts.join("\n\n"),
+    up: [...createSchemaStmts(sorted), ...upStmts].join("\n\n"),
     down: [...downStmts].reverse().join("\n\n"),
     recreatedTables: new Set(), // postgres alters in place; no recreate-and-copy
   };
 }
 
+/**
+ * `CREATE SCHEMA IF NOT EXISTS` for every non-default schema this migration creates
+ * an object in, ahead of everything else it emits.
+ *
+ * A chain must be appliable to a VIRGIN database (#313), and `CREATE TABLE "s"."x"`
+ * fails there unless `s` exists — yet `CREATE SCHEMA` was emitted nowhere in either
+ * emitter, only by the ledger's own setup. So an `@schema` project's chain could
+ * never be replayed, and the first `apply-pending` against a fresh CI database died.
+ *
+ * VIEWS count, not only tables: a first migration that creates only a view in a
+ * non-default schema fails identically. A `create-view` carries the schema in two
+ * places and the change's own key wins, matching `renderCreateView(c.view, c.schema)`.
+ *
+ * `IF NOT EXISTS` because a later migration in the same chain, or an operator, may
+ * have created it already. Sorted so output is deterministic — the committed snapshot
+ * and the golden tests depend on that. Deliberately NOT dropped in `down`: the schema
+ * may hold objects this tool does not own and cannot restore.
+ */
+function createSchemaStmts(sorted: readonly Change[]): string[] {
+  const schemas = new Set<string>();
+  for (const c of sorted) {
+    const s =
+      c.kind === "create-table" ? c.table.schema
+      : c.kind === "create-view" ? (c.schema ?? c.view.schema)
+      : undefined;
+    if (s !== undefined && s !== DEFAULT_DB_SCHEMA_POSTGRES) schemas.add(s);
+  }
+  return [...schemas].sort().map((s) => `CREATE SCHEMA IF NOT EXISTS ${quote(s)};`);
+}
+
 function renderUp(c: Change): string {
   switch (c.kind) {
     case "create-table":           return renderCreateTable(c.table);
-    case "drop-table":             return `DROP TABLE ${quoteQualified(c.table, c.schema)};`;
+    // #313 — every FORWARD drop is `IF EXISTS`. A committed chain must apply to a
+    // VIRGIN database, and the diff legitimately proposes dropping an object that
+    // exists in the live DB but was never created by any migration in the chain (a
+    // table another tool owns, say). Bare, that statement kills the replay with
+    // `table "x" does not exist`. The DOWN renderer below is deliberately NOT
+    // guarded: `rollbackTo` runs down.sql and the ledger delete in ONE transaction,
+    // so a no-op down would still record the rollback as done.
+    case "drop-table":             return `DROP TABLE IF EXISTS ${quoteQualified(c.table, c.schema)};`;
     case "rename-table":           return `ALTER TABLE ${quoteQualified(c.from, c.schema)} RENAME TO ${quote(c.to)};`;
     case "add-column": {
       const base = `ALTER TABLE ${quoteQualified(c.table, c.schema)} ADD COLUMN ${renderColumn(c.column)};`;
@@ -90,18 +127,37 @@ function renderUp(c: Change): string {
     // descriptor (both diff producers populate it), which is where the marker lives.
     // Matters broadly, not marginally: Drizzle's `unique()` emits constraints, so every
     // schema adopted from Drizzle has constraint-backed unique indexes.
+    // Both arms carry the #313 `IF EXISTS`: they are two renderings of the SAME
+    // `drop-index` change, and guarding one would leave the change kind half-covered.
+    // The constraint-backed arm ALSO guards the enclosing `ALTER TABLE` (not just
+    // the constraint name) — see the `drop-fk`/`drop-check` comment below for why.
     case "drop-index":
       return c.restore?.constraint !== undefined
-        ? `ALTER TABLE ${quoteQualified(c.table, c.schema)} DROP CONSTRAINT ${quote(c.index)};`
-        : `DROP INDEX ${quoteIndexQualified(c.index, c.schema)};`;
+        ? `ALTER TABLE IF EXISTS ${quoteQualified(c.table, c.schema)} DROP CONSTRAINT IF EXISTS ${quote(c.index)};`
+        : `DROP INDEX IF EXISTS ${quoteIndexQualified(c.index, c.schema)};`;
     case "add-fk":                 return renderAddFk(c.table, c.schema, c.fk);
-    case "drop-fk":                return `ALTER TABLE ${quoteQualified(c.table, c.schema)} DROP CONSTRAINT ${quote(c.fk)};`;
-    // add-check / drop-check are declared but NOT yet produced by the diff —
-    // checks are create-time-only (inlined in CREATE TABLE via renderCreateTable).
-    // These arms exist for future existing-table CHECK evolution support, mirroring
-    // the create-view/drop-view "declared, not yet produced" pattern.
+    // #313 (constraint-level): `DROP CONSTRAINT IF EXISTS` alone only guards the
+    // constraint NAME — Postgres still requires the TABLE to exist to parse an
+    // `ALTER TABLE` at all, so a table another tool owns (never created by any
+    // migration in this chain) still killed the replay with `relation "x" does
+    // not exist`. Postgres supports `ALTER TABLE IF EXISTS` directly; using it
+    // closes the gap the same way `DROP TABLE IF EXISTS` above already does.
+    case "drop-fk":                return `ALTER TABLE IF EXISTS ${quoteQualified(c.table, c.schema)} DROP CONSTRAINT IF EXISTS ${quote(c.fk)};`;
+    // `drop-check` IS produced by the diff — diff/index.ts:579 and :592 both push it,
+    // and an evolved `field.enum @values` is a live producer. (A comment here used to
+    // claim these arms were unreachable "declared, not yet produced" stubs; that was
+    // false, and two tests already asserted the emitted statement.) `add-check` is the
+    // paired ADD and rides the same passes.
+    //
+    // `drop-fk`/`drop-check` are guarded on Postgres ONLY, and that is not a dialect
+    // split: SQLite emits no standalone statement for either kind — `renderUpNative`
+    // throws, because SQLite constraints are create-time-only and inline, so the change
+    // folds into a table recreate that rebuilds from the EXPECTED descriptor and never
+    // references the dropped constraint. SQLite is already replay-safe by construction;
+    // guarding Postgres makes the two dialects agree.
     case "add-check":              return `ALTER TABLE ${quoteQualified(c.table, c.schema)} ADD CONSTRAINT ${quote(c.check.name)} CHECK (${c.check.expression});`;
-    case "drop-check":             return `ALTER TABLE ${quoteQualified(c.table, c.schema)} DROP CONSTRAINT ${quote(c.check)};`;
+    // Same `ALTER TABLE IF EXISTS` gap as `drop-fk` above.
+    case "drop-check":             return `ALTER TABLE IF EXISTS ${quoteQualified(c.table, c.schema)} DROP CONSTRAINT IF EXISTS ${quote(c.check)};`;
     case "create-view":            return renderCreateView(c.view, c.schema, /* orReplace */ false);
     case "drop-view":              return renderDropView(c);
     case "replace-view":           return renderCreateView(c.view, c.schema, /* orReplace */ true);
@@ -372,7 +428,9 @@ function renderViewComment(qualifiedView: string, comment: string | null): strin
 function renderDropView(c: Extract<Change, { kind: "drop-view" }>): string {
   const qualified = quoteQualifiedView(c.view, c.schema);
   const dependents = c.dependents ?? [];
-  if (dependents.length === 0) return `DROP VIEW ${qualified};`;
+  // #313 `IF EXISTS` on both forms — this is the FORWARD renderer. `renderRestoreView`
+  // below stays bare: it is reached only from `renderDown`.
+  if (dependents.length === 0) return `DROP VIEW IF EXISTS ${qualified};`;
 
   const listed = dependents
     .map((d) => `--   ${d.schema}.${d.name} (${d.relkind === "m" ? "materialized view" : "view"})`)
@@ -385,7 +443,7 @@ function renderDropView(c: Extract<Change, { kind: "drop-view" }>): string {
     "-- restore them:",
     listed,
     rule,
-    `DROP VIEW ${qualified} CASCADE;`,
+    `DROP VIEW IF EXISTS ${qualified} CASCADE;`,
   ].join("\n");
 }
 

package/src/emit/sqlite.ts

@@ -216,13 +216,20 @@ function renderRecreate(
 function renderUpNative(c: Change): string {
   switch (c.kind) {
     case "create-table":   return renderCreateTable(c.table);
-    case "drop-table":     return `DROP TABLE ${quote(c.table)};`;
+    // #313 — FORWARD drops are `IF EXISTS` so a committed chain applies to a VIRGIN
+    // database: the diff legitimately proposes dropping an object present in the live
+    // DB that no migration in the chain ever created. `renderDownNative` stays bare
+    // (a no-op rollback would still be recorded as done), and so does the
+    // recreate-and-copy rebuild's DROP above — that one drops a table the same recipe
+    // just INSERT…SELECTed from, where IF EXISTS turns a caught corruption into a
+    // silent one.
+    case "drop-table":     return `DROP TABLE IF EXISTS ${quote(c.table)};`;
     case "rename-table":   return `ALTER TABLE ${quote(c.from)} RENAME TO ${quote(c.to)};`;
     case "add-column":     return `ALTER TABLE ${quote(c.table)} ADD COLUMN ${renderColumnInline(c.column)};`;
     case "drop-column":    return `ALTER TABLE ${quote(c.table)} DROP COLUMN ${quote(c.column)};`;
     case "rename-column":  return `ALTER TABLE ${quote(c.table)} RENAME COLUMN ${quote(c.from)} TO ${quote(c.to)};`;
     case "add-index":      return renderCreateIndex(c.table, c.index);
-    case "drop-index":     return `DROP INDEX ${quote(c.index)};`;
+    case "drop-index":     return `DROP INDEX IF EXISTS ${quote(c.index)};`;
     case "add-check":
     case "drop-check":
     case "change-column-type":

package/src/expected-schema.ts

@@ -61,6 +61,7 @@ import type {
   Dialect, SchemaSnapshot, TableDescriptor, ColumnDescriptor, IndexDescriptor, FkDescriptor,
   CheckDescriptor, ViewDescriptor,
 } from "./types.js";
+import { qualifiedDbName } from "./qualified-name.js";
 import { viewFingerprint } from "./view-fingerprint.js";
 import { resolveViewColumns, type ExpectedViewColumnInput } from "./view-column-types.js";
 import {
@@ -112,12 +113,55 @@ export interface ExpectedViewInput {
   sql?: string;
   dependsOn?: readonly string[];
   columns?: readonly ExpectedViewColumnInput[];
+  /**
+   * `resolutionKey()` of the object that declared this view — its PROVENANCE.
+   * Recorded in the provenance map and deliberately NEVER copied onto the
+   * `ViewDescriptor`: descriptors are serialized into the committed snapshot, and
+   * a descriptor that gains a field owes a `SNAPSHOT_FORMAT_VERSION` bump, which
+   * hard-fails every older reader. Optional — a caller that supplies no FQN gets a
+   * view with no provenance, which `scopeExpectedSchema` keeps (never guesses).
+   */
+  fqn?: string;
 }
 
+/**
+ * Qualified physical name (`qualifiedDbName`) → the `resolutionKey()` of the
+ * metadata object that declared it. The ONLY sound basis for a per-command scope
+ * decision: a SQL name cannot be reversed into an FQN (naming strategies, `@table`
+ * overrides and TPH folding are all lossy), and a second metadata walk would have
+ * to re-implement Pass 1's skip rules — abstract, TPH subtype, no writable source,
+ * `@unmanaged` — and would drift from them.
+ */
+export type SchemaProvenance = ReadonlyMap<string, string>;
+
+export interface ExpectedSchemaWithProvenance {
+  snapshot: SchemaSnapshot;
+  provenance: SchemaProvenance;
+}
+
+/**
+ * The expected schema as every existing caller wants it. Thin wrapper over
+ * {@link buildExpectedSchemaWithProvenance}; byte-identical output.
+ */
 export function buildExpectedSchema(
   root: MetaData,
   opts?: BuildExpectedSchemaOptions,
 ): SchemaSnapshot {
+  return buildExpectedSchemaWithProvenance(root, opts).snapshot;
+}
+
+/**
+ * The expected schema PLUS the declaring FQN of every table and view in it.
+ *
+ * Provenance is threaded out of the passes that already hold the declaring node —
+ * Pass 2 has each table's entity, Pass 4 each view's input — so there is exactly
+ * one walk and one set of skip rules. Callers that filter by scope
+ * (`scopeExpectedSchema`) consume it; callers that don't use the wrapper above.
+ */
+export function buildExpectedSchemaWithProvenance(
+  root: MetaData,
+  opts?: BuildExpectedSchemaOptions,
+): ExpectedSchemaWithProvenance {
   // D1 is SQLite at the SQL level; normalize it so downstream dialect checks
   // don't need to handle "d1" separately.
   const dialect = opts?.dialect === "d1" ? "sqlite" : opts?.dialect;
@@ -207,6 +251,12 @@ export function buildExpectedSchema(
     return byBareHit === AMBIGUOUS ? undefined : byBareHit;
   };
 
+  // Provenance: qualified physical name → declaring object's FQN. Recorded as the
+  // descriptors are built, never re-derived from a SQL name (lossy) and never by a
+  // second walk (it would have to duplicate Pass 1's skip rules and would drift from
+  // them — a TPH subtype, for one, shares its base's table and declares none of its own).
+  const provenance = new Map<string, string>();
+
   // Pass 2: build full descriptors with FK resolution.
   // Schema is resolved here (not stored in Pass 1) to avoid exactOptionalPropertyTypes
   // issues with `string | undefined` vs `schema?: string`.
@@ -214,6 +264,7 @@ export function buildExpectedSchema(
     const t = buildTable(entity, tableName, resolveTargetTable, root as MetaRoot, strategy, dialect);
     const schema = resolveTableSchema(entity);
     if (schema !== undefined) t.schema = schema;
+    provenance.set(qualifiedDbName(t), entity.resolutionKey());
     return t;
   });
 
@@ -288,13 +339,17 @@ export function buildExpectedSchema(
   //     whether a view change can use a non-destructive CREATE OR REPLACE.
   const views: ViewDescriptor[] = (opts?.views ?? []).map((v) => {
     const columns = resolveViewColumns(v.columns, tables);
-    return {
+    const descriptor: ViewDescriptor = {
       name: v.name,
       ...(v.schema !== undefined ? { schema: v.schema } : {}),
       ...(v.sql !== undefined ? { sql: v.sql, fingerprint: viewFingerprint(v.sql) } : {}),
       ...(v.dependsOn !== undefined ? { dependsOn: v.dependsOn } : {}),
       ...(columns !== undefined ? { columns } : {}),
     };
+    // The declaring FQN goes to the provenance map ONLY — never onto the descriptor,
+    // which is what the committed snapshot serializes (see ExpectedViewInput.fqn).
+    if (v.fqn !== undefined) provenance.set(qualifiedDbName(descriptor), v.fqn);
+    return descriptor;
   });
 
   // Collision guard: two DISTINCT metadata objects that resolve to the same generated
@@ -324,7 +379,7 @@ export function buildExpectedSchema(
     );
   }
 
-  return { tables, views };
+  return { snapshot: { tables, views }, provenance };
 }
 
 /**

package/src/index.ts

@@ -8,11 +8,23 @@
 // See docs/specs/2026-05-11-v0.2-sp4-migrate-ts-design.md.
 
 // Pipeline functions
-export { buildExpectedSchema } from "./expected-schema.js";
+export { buildExpectedSchema, buildExpectedSchemaWithProvenance } from "./expected-schema.js";
+export type { ExpectedSchemaWithProvenance, SchemaProvenance } from "./expected-schema.js";
 export { introspect, introspectPostgres, introspectSqlite } from "./introspect/index.js";
 export { diff } from "./diff/index.js";
 export { collectUnmanagedNames } from "./unmanaged.js";
-export { computeDrift, computeDriftFromActual, type ComputeDriftOptions } from "./drift/drift.js";
+// Per-command scope (`migrate.scope`) — see scope.ts for why the suppression is
+// two-sided and why the pattern engine stays in @metaobjectsdev/sdk.
+export {
+  scopeExpectedSchema,
+  declaredSchemasOf,
+  carryForwardOutOfScope,
+  excludeFromSnapshot,
+  scopedDiffInputs,
+} from "./scope.js";
+export type { ObjectScopePredicate, ScopedExpectedSchema, GovernedScope } from "./scope.js";
+export { qualifiedDbName } from "./qualified-name.js";
+export { computeDrift, computeDriftFromActual, type ComputeDriftOptions, type DriftResult } from "./drift/drift.js";
 export { classifyDrift, driftAgainstSnapshot } from "./drift/classify.js";
 export type { DriftClassification } from "./drift/classify.js";
 export { emit } from "./emit/index.js";
@@ -100,6 +112,10 @@ export {
 export { verifyReplay } from "./verify/replay.js";
 export type { VerifyReplayArgs, VerifyReplayResult } from "./verify/replay.js";
 
+// An empty in-process database to replay a committed chain into (#313).
+export { openReplayEngine } from "./verify/replay-engine.js";
+export type { ReplayEngine } from "./verify/replay-engine.js";
+
 // Wrangler config helpers
 export {
   findWranglerConfig,

package/src/qualified-name.ts

@@ -0,0 +1,22 @@
+// The ONE qualified-physical-name form: `<schema>.<name>`, with an absent schema
+// normalized to the Postgres default.
+//
+// Three things must key DB objects identically or the diff silently disagrees with
+// itself: `diff`'s table/view identity maps, the declared-`@unmanaged` exclusion set
+// (`collectUnmanagedNames`), and the out-of-scope exclusion set (`scopeExpectedSchema`).
+// The last two are ACT-side suppressions matched against the first, so a name built a
+// second way — a different default schema, a different separator — reads as "not
+// suppressed" and the object it names comes back as a proposed DROP. One function.
+//
+// SQLite has no schema concept, so every SQLite object normalizes to the same prefix.
+// That is harmless: it is a constant, and the un-prefixed names were already unique.
+
+import { DEFAULT_DB_SCHEMA_POSTGRES } from "@metaobjectsdev/metadata";
+
+/** `<schema>.<name>`; an absent schema is the Postgres default (`public`). The
+ *  parameter accepts an EXPLICIT `undefined` schema (not only an omitted key) so a
+ *  caller holding a `string | undefined` can pass it straight through under
+ *  `exactOptionalPropertyTypes` — the two spell the same thing here. */
+export function qualifiedDbName(obj: { name: string; schema?: string | undefined }): string {
+  return `${obj.schema ?? DEFAULT_DB_SCHEMA_POSTGRES}.${obj.name}`;
+}