@metaobjectsdev/migrate-ts 0.23.2 → 0.24.0

package/src/scope.ts

@@ -0,0 +1,261 @@
+// Per-command scope — narrowing a migrate/verify run to the objects it governs.
+//
+// A consumer sharing a database with another owner declares
+// `"migrate": { "scope": ["acme::platform::**"] }`. Tables and views outside that
+// scope are neither created nor dropped, which takes TWO suppressions:
+//
+//   1. drop them from the EXPECTED side, so nothing is created or altered;
+//   2. suppress the same names on the ACTUAL side (via `diff`'s `unmanagedNames`,
+//      the seam `@unmanaged` already uses), so nothing is dropped.
+//
+// Doing only (1) is strictly worse than doing nothing: every out-of-scope table that
+// EXISTS in the database becomes a proposed `DROP TABLE` — the precise hazard this
+// feature exists to remove. `scopeExpectedSchema` therefore returns both halves and
+// callers must thread `outOfScope` into the diff.
+//
+// There is a THIRD half, and it is the one that bites hardest when the scope is
+// wrong. `diff` derives its SCHEMA scope from the schemas the expected side
+// mentions, falling back to "no schema scoping at all" when expected is empty (the
+// legacy whole-DB path for a project with no model). A scope matching NOTHING
+// empties `expected`, reaches that fallback, and every actual table in every schema
+// becomes a drop candidate — another owner's included, which was never in `expected`
+// so it has no provenance and never lands in `outOfScope`. Narrowing must never
+// WIDEN. `declaredSchemas` below reports the UNSCOPED model's schemas so callers can
+// pin `diff`'s `scopeSchemas` to a property of the whole model, which `migrate.scope`
+// then cannot move in either direction.
+//
+// THE RULE THAT FOLLOWS FROM THAT, stated once because it is easy to read the other
+// way: **a scope narrows which OBJECTS the tool governs, never which SCHEMAS it is
+// allowed to see.** Pinning `scopeSchemas` to the unscoped model means a scope that
+// excludes every declared object in schema `X` leaves `X` in scope, so another
+// owner's UNDECLARED table in `X` stays a drop candidate — exactly as it would be on
+// an unscoped run of the same model. That is deliberate: a schema this model
+// declares into is a schema this model manages, and deriving the schema set from the
+// survivors instead is precisely the inversion above. Declaring a scope is not a way
+// to hand a schema over; removing the objects from the model is.
+//
+// `scopedDiffInputs` exists so no caller has to remember any of this: it returns all
+// three obligations as one object, and every scoped `diff` call goes through it.
+
+import { DEFAULT_DB_SCHEMA_POSTGRES } from "@metaobjectsdev/metadata";
+import type { DiffArgs } from "./diff/index.js";
+import type { ExpectedSchemaWithProvenance } from "./expected-schema.js";
+import { qualifiedDbName } from "./qualified-name.js";
+import type { SchemaSnapshot } from "./types.js";
+
+/**
+ * Decides whether an object's fully-qualified name (`resolutionKey()`) is governed
+ * by this run. Supplied by the caller as a PREDICATE so migrate-ts never carries a
+ * second implementation of the scope-pattern grammar — `matchesScope` in
+ * `@metaobjectsdev/sdk` is the only one, and the CLI adapts a compiled scope to
+ * this seam.
+ */
+export type ObjectScopePredicate = (fqn: string) => boolean;
+
+export interface ScopedExpectedSchema {
+  /** The expected schema narrowed to the governed objects. */
+  snapshot: SchemaSnapshot;
+  /**
+   * Qualified physical names (`<schema>.<name>`) of the tables and views removed
+   * above. Reaches `diff`'s `unmanagedNames` (MERGED with `collectUnmanagedNames`,
+   * never replacing it) so the actual side is suppressed too — `scopedDiffInputs`
+   * does that merge; see the module header for why omitting it inverts the feature.
+   */
+  outOfScope: string[];
+  /**
+   * The database schemas the UNSCOPED model declares, for `diff`'s `scopeSchemas`.
+   * `scopedDiffInputs` threads it — see the module header: without it a scope
+   * matching nothing hands `diff` an empty expected side, which it reads as "no
+   * model, govern the whole database".
+   *
+   * `undefined` when no predicate was supplied (so `diff` derives its own set from
+   * an untouched `expected`, exactly as before — an unscoped project's arguments are
+   * unchanged) and also when the unscoped model declares no tables or views at all
+   * (nothing to derive from; `diff`'s legacy whole-DB fallback is preserved).
+   */
+  declaredSchemas?: string[];
+}
+
+/**
+ * Carry an out-of-scope object forward into the snapshot a run is about to commit.
+ *
+ * The committed snapshot is built from the metadata-expected schema, which a scoped
+ * run has already narrowed — so accepting a scoped run DELETES every out-of-scope
+ * entry the previous snapshot held. Widening or removing `migrate.scope` later then
+ * proposes `CREATE TABLE` for a table that exists, and the migration fails at apply.
+ *
+ * `prior` is the snapshot (or introspected schema) the run diffed against, and the
+ * entries taken from it are exactly the ones this run excluded — nothing else is
+ * carried, so a table the model never declared is unaffected either way. An empty
+ * `outOfScope` returns the SAME object, so an unscoped run commits a byte-identical
+ * snapshot.
+ */
+export function carryForwardOutOfScope(
+  next: SchemaSnapshot,
+  prior: SchemaSnapshot,
+  outOfScope: readonly string[],
+): SchemaSnapshot {
+  if (outOfScope.length === 0) return next;
+  const excluded = new Set(outOfScope);
+  return {
+    ...next,
+    tables: [...next.tables, ...splitOnName(prior.tables, excluded).named],
+    views: [...next.views, ...splitOnName(prior.views, excluded).named],
+  };
+}
+
+/**
+ * Drop the out-of-scope entries from a COMMITTED SNAPSHOT, producing the same
+ * three-part shape `scopeExpectedSchema` produces so the result can go straight
+ * through {@link scopedDiffInputs}.
+ *
+ * `verify`'s committed-snapshot gate (#292) needs this: `unmanagedNames` suppresses
+ * only the ACTUAL side, which is right when the expected side is the metadata (it is
+ * already scoped) and wrong here, where the expected side IS the snapshot — a
+ * snapshot written before the scope was declared still carries the other owner's
+ * tables, and leaving them in reports a phantom disagreement about an object this
+ * consumer does not manage.
+ *
+ * `governed` is the scope decision the caller's drift comparison already made — pass
+ * the `DriftResult` itself, which satisfies this shape. Taking `declaredSchemas`
+ * from there rather than re-deriving it from the snapshot is what closes the last
+ * whole-database door: a snapshot that is present but EMPTY (a never-migrated
+ * project) declares no schemas at all, so deriving from it hands `diff` nothing and
+ * reaches its "no model, govern the whole database" fallback — the very inversion
+ * this module exists to prevent, at the one call site that was still re-deriving.
+ *
+ * An empty `outOfScope` returns the SAME snapshot object with no schema pin, so an
+ * unscoped project's `diff` arguments are byte-for-byte what they always were.
+ */
+export function excludeFromSnapshot(
+  snapshot: SchemaSnapshot,
+  governed: GovernedScope,
+): ScopedExpectedSchema {
+  if (governed.outOfScope.length === 0) return { snapshot, outOfScope: [] };
+  const excluded = new Set(governed.outOfScope);
+  const declared = governed.declaredSchemas ?? declaredSchemasOf(snapshot);
+  return {
+    snapshot: {
+      ...snapshot,
+      tables: splitOnName(snapshot.tables, excluded).rest,
+      views: splitOnName(snapshot.views, excluded).rest,
+    },
+    outOfScope: [...governed.outOfScope],
+    declaredSchemas: [...declared],
+  };
+}
+
+/** The scope decision a run made, as `DriftResult` reports it. */
+export interface GovernedScope {
+  /** Qualified physical names (`<schema>.<name>`) the run does not govern. */
+  readonly outOfScope: readonly string[];
+  /** The schemas the run governs — `ScopedExpectedSchema.declaredSchemas`. */
+  readonly declaredSchemas?: readonly string[] | undefined;
+}
+
+/**
+ * Partition `objs` on whether `qualifiedDbName(o)` is in `names`.
+ *
+ * `carryForwardOutOfScope` wants the `named` half (carry the excluded entries
+ * forward) and `excludeFromSnapshot` wants the `rest` half (drop them). They are
+ * exact complements over the same key function, so they share one traversal rather
+ * than two filters that could come to key differently.
+ */
+function splitOnName<T extends { name: string; schema?: string }>(
+  objs: readonly T[],
+  names: ReadonlySet<string>,
+): { named: T[]; rest: T[] } {
+  const named: T[] = [];
+  const rest: T[] = [];
+  for (const o of objs) (names.has(qualifiedDbName(o)) ? named : rest).push(o);
+  return { named, rest };
+}
+
+/**
+ * The three `diff` arguments a scoped run owes, as ONE value.
+ *
+ * The module header lists them as three separate obligations, and five call sites
+ * re-derived them by hand — one of which had already drifted into its own guard.
+ * Every scoped `diff` call is now
+ * `diff({ ...scopedDiffInputs(scoped, collectUnmanagedNames(metadata)), actual, ... })`,
+ * so the rule is enforced by the type rather than by the comment.
+ *
+ * `unmanaged` is the `@unmanaged`-declared set (`collectUnmanagedNames`); it is
+ * MERGED with `outOfScope`, never replaced by it — both must reach `diff`.
+ * `scopeSchemas` is omitted entirely when the run narrowed nothing, so an unscoped
+ * project's arguments are unchanged.
+ */
+export function scopedDiffInputs(
+  scoped: ScopedExpectedSchema,
+  unmanaged: readonly string[],
+): Pick<DiffArgs, "expected" | "unmanagedNames" | "scopeSchemas"> {
+  return {
+    expected: scoped.snapshot,
+    unmanagedNames: [...unmanaged, ...scoped.outOfScope],
+    ...(scoped.declaredSchemas !== undefined ? { scopeSchemas: scoped.declaredSchemas } : {}),
+  };
+}
+
+/**
+ * The distinct database schemas a snapshot's tables and views sit in, absent
+ * normalized to the Postgres default — the value `diff` derives for itself when no
+ * `scopeSchemas` is supplied. The ONE definition: any caller narrowing an expected
+ * side must pin `diff`'s schema scope to the UNNARROWED snapshot's schemas, and a
+ * second encoding of "absent means public" here would silently disagree with the
+ * one inside `diff`.
+ *
+ * Empty in ⇒ empty out, which callers translate to "pass nothing", preserving
+ * `diff`'s legacy whole-database fallback for a genuinely empty model.
+ */
+export function declaredSchemasOf(snapshot: SchemaSnapshot): string[] {
+  return [
+    ...new Set(
+      [...snapshot.tables, ...snapshot.views].map(
+        (o) => o.schema ?? DEFAULT_DB_SCHEMA_POSTGRES,
+      ),
+    ),
+  ].sort();
+}
+
+/**
+ * Narrow an expected schema to the objects inside `inScope`.
+ *
+ * An undefined predicate returns the input untouched — the SAME snapshot object,
+ * not an equal copy — so a project that declares no `migrate.scope` reaches the
+ * diff, the emitter and the committed snapshot through an unchanged value.
+ *
+ * A table or view with NO recorded provenance is KEPT. Scope decides on the
+ * declaring object's FQN, and an object whose FQN is unknown was never proven to be
+ * anyone else's; dropping it would silently un-manage it (and, worse, suppressing
+ * its name on the actual side would hide real drift).
+ */
+export function scopeExpectedSchema(
+  built: ExpectedSchemaWithProvenance,
+  inScope: ObjectScopePredicate | undefined,
+): ScopedExpectedSchema {
+  if (inScope === undefined) return { snapshot: built.snapshot, outOfScope: [] };
+
+  // Computed from `built.snapshot` — the UNSCOPED side — deliberately, and before
+  // the filter below runs. Deriving it from the survivors would reproduce exactly
+  // the defect this exists to close.
+  const declared = declaredSchemasOf(built.snapshot);
+
+  const outOfScope: string[] = [];
+  const governed = <T extends { name: string; schema?: string }>(obj: T): boolean => {
+    const qualified = qualifiedDbName(obj);
+    const fqn = built.provenance.get(qualified);
+    if (fqn === undefined || inScope(fqn)) return true;
+    outOfScope.push(qualified);
+    return false;
+  };
+
+  return {
+    snapshot: {
+      ...built.snapshot,
+      tables: built.snapshot.tables.filter(governed),
+      views: built.snapshot.views.filter(governed),
+    },
+    outOfScope,
+    ...(declared.length > 0 ? { declaredSchemas: declared } : {}),
+  };
+}

package/src/snapshot/plan.ts

@@ -1,8 +1,9 @@
 // src/snapshot/plan.ts
 import type { ColumnNamingStrategy, MetaData } from "@metaobjectsdev/metadata";
-import { buildExpectedSchema } from "../expected-schema.js";
+import { buildExpectedSchema, buildExpectedSchemaWithProvenance } from "../expected-schema.js";
 import { diff, type DiffArgs } from "../diff/index.js";
 import { collectUnmanagedNames } from "../unmanaged.js";
+import { carryForwardOutOfScope, scopeExpectedSchema, scopedDiffInputs, type ObjectScopePredicate } from "../scope.js";
 import type { Dialect, DiffResult, SchemaSnapshot } from "../types.js";
 import type { ExpectedViewInput } from "../expected-schema.js";
 
@@ -14,13 +15,34 @@ export interface PlanOfflineArgs extends Pick<DiffArgs, "allow" | "onAmbiguous"
   columnNamingStrategy?: ColumnNamingStrategy;
   /** Expected views (via codegen-ts `buildProjectionViews`) — threaded into buildExpectedSchema. */
   views?: readonly ExpectedViewInput[];
+  /**
+   * Per-command scope (`migrate.scope`): objects whose declaring FQN this predicate
+   * rejects are governed by somebody else. They leave the expected side (so no
+   * create/alter) AND the snapshot side (so no drop). Omit to govern everything
+   * loaded (unchanged behavior).
+   */
+  inScope?: ObjectScopePredicate;
 }
 
 export interface PlanOfflineResult {
   /** The change set to emit, from diffing metadata-expected against the snapshot. */
   diff: DiffResult;
-  /** The schema the migration brings us to — write this back as the new snapshot on accept. */
+  /**
+   * The schema the migration brings us to — write this back as the new snapshot on
+   * accept. Under a scope this is the governed schema PLUS the out-of-scope entries
+   * the prior snapshot held: committing the narrowed schema would delete them, and a
+   * later widening would then propose CREATE TABLE for a table that exists.
+   */
   nextSnapshot: SchemaSnapshot;
+  /**
+   * The governed (narrowed) expected side — what the diff compared and what the
+   * emitter renders against. Identical to `nextSnapshot` for an unscoped run; under
+   * a scope it is deliberately the SMALLER of the two, since a run must emit DDL
+   * only for what it governs.
+   */
+  expected: SchemaSnapshot;
+  /** Qualified physical names excluded by `inScope`; empty when no scope was given. */
+  outOfScope: readonly string[];
 }
 
 /**
@@ -29,28 +51,38 @@ export interface PlanOfflineResult {
  * accept, persists `nextSnapshot` via writeSnapshot.
  */
 export async function planOffline(args: PlanOfflineArgs): Promise<PlanOfflineResult> {
-  const nextSnapshot = buildExpectedSchema(args.metadata, {
-    dialect: args.dialect,
-    ...(args.columnNamingStrategy ? { columnNamingStrategy: args.columnNamingStrategy } : {}),
-    ...(args.views !== undefined ? { views: args.views } : {}),
-  });
+  const scoped = scopeExpectedSchema(
+    buildExpectedSchemaWithProvenance(args.metadata, {
+      dialect: args.dialect,
+      ...(args.columnNamingStrategy ? { columnNamingStrategy: args.columnNamingStrategy } : {}),
+      ...(args.views !== undefined ? { views: args.views } : {}),
+    }),
+    args.inScope,
+  );
+  // The DIFF runs against the narrowed side; the SNAPSHOT keeps what this run
+  // excluded. Committing the narrowed schema would delete every out-of-scope entry
+  // the previous snapshot held, so removing or widening `migrate.scope` later would
+  // propose CREATE TABLE for a table that exists and fail at apply. Byte-identical
+  // for an unscoped run (`outOfScope` empty ⇒ the same object).
+  const nextSnapshot = carryForwardOutOfScope(scoped.snapshot, args.snapshot, scoped.outOfScope);
   const result = await diff({
-    expected: nextSnapshot,
+    // The three scoped-diff obligations as one value (see scope.ts's header). The
+    // `unmanagedNames` merge matters as much on the OFFLINE path as anywhere: an
+    // out-of-scope table already recorded in the snapshot must not be dropped just
+    // because the scope excludes it, and neither must a declared-@unmanaged one a
+    // `baseline --from-db` captured (#208 §7).
+    ...scopedDiffInputs(scoped, collectUnmanagedNames(args.metadata)),
     actual: args.snapshot,
     dialect: args.dialect,
     // #258 — migration generation refuses a primary-key MOVE (there is no primary-key
     // change kind to express it; it would otherwise silently drop the constraint). The
     // read-only verify/drift path does NOT set this, so `meta verify` still reports drift.
     refusePrimaryKeyChange: true,
-    // #208 §7 — exclude declared-@unmanaged objects from the actual (snapshot) side too,
-    // so the OFFLINE generate path never proposes DROP for an external table that a
-    // `baseline --from-db` captured into the snapshot (parity with the online/verify paths).
-    unmanagedNames: collectUnmanagedNames(args.metadata),
     ...(args.allow ? { allow: args.allow } : {}),
     ...(args.onAmbiguous ? { onAmbiguous: args.onAmbiguous } : {}),
     ...(args.ignoreTables ? { ignoreTables: args.ignoreTables } : {}),
   });
-  return { diff: result, nextSnapshot };
+  return { diff: result, nextSnapshot, expected: scoped.snapshot, outOfScope: scoped.outOfScope };
 }
 
 /** Seed an initial reference snapshot from metadata (greenfield baseline). */

package/src/types.ts

@@ -347,6 +347,23 @@ export interface AllowOptions {
    * skips the default-diff for a live auto-sequence default entirely.)
    */
   dropIdentityDefault?: boolean;
+  /**
+   * Permits dropping an object the COMMITTED SNAPSHOT never contained — i.e. one
+   * this toolchain never managed. Without it, such a drop is refused at generation
+   * time, because the migration it would write cannot replay against a database
+   * where that object never existed (#313). `classify.ts` already states the
+   * doctrine: objects present in the DB but not the snapshot "must never be treated
+   * as actionable drift or auto-dropped".
+   *
+   * The ONE field here read by the CLI's generation-time provenance guard rather
+   * than by `diff()`'s status pass — `diff` compares metadata against introspection
+   * and never sees the snapshot, which is precisely why the doctrine was not
+   * enforced where it mattered. It lives in `AllowOptions` anyway so `--allow` keeps
+   * ONE token list and ONE grant map (`ALLOW_TOKENS` / `ALLOW_TOKEN_MAP`, pinned
+   * together by `cli/test/unit/allow-tokens-pinned.test.ts`): a second parallel
+   * validation path for a single token is the exact drift that pin exists to catch.
+   */
+  dropUnmanaged?: boolean;
 }
 
 export type AmbiguousChange =

package/src/unmanaged.ts

@@ -10,10 +10,10 @@
 import {
   isMetaSource,
   resolveTableSchema,
-  DEFAULT_DB_SCHEMA_POSTGRES,
   TYPE_OBJECT,
   type MetaData,
 } from "@metaobjectsdev/metadata";
+import { qualifiedDbName } from "./qualified-name.js";
 
 /**
  * The qualified physical names (`schema.name`, schema defaulting to Postgres `public`)
@@ -38,8 +38,7 @@ export function collectUnmanagedNames(root: MetaData): string[] {
       // make the class check false and silently un-silence a declared-@unmanaged
       // object, turning it back into a proposed drop.
       if (!isMetaSource(src) || !src.isUnmanaged) continue;
-      const schema = resolveTableSchema(obj) ?? DEFAULT_DB_SCHEMA_POSTGRES;
-      out.push(`${schema}.${src.physicalName}`);
+      out.push(qualifiedDbName({ name: src.physicalName, schema: resolveTableSchema(obj) }));
     }
   }
   return out;

package/src/verify/replay-engine.ts

@@ -0,0 +1,184 @@
+// An empty, throwaway database that lives INSIDE this process.
+//
+// The replay gate has to apply a whole committed chain from nothing. Doing that
+// against the user's server would mean CREATE DATABASE — which needs CREATEDB,
+// breaks behind a connection pooler, is restricted on managed Postgres, collides
+// between parallel CI jobs sharing one server, and puts a DROP DATABASE next to a
+// name derived from a real one (Postgres truncates identifiers at 63 bytes, so a
+// long enough target derives a scratch name that truncates back ONTO the target).
+// None of that is worth it when the engine runs locally and disposably: PGlite is
+// real Postgres compiled to WASM and lives in this process; sqlite is a throwaway
+// file in a private temp directory (see `openMemorySqlite` for why not `:memory:`).
+// Nothing to provision, nothing to name, nothing to drop by mistake.
+//
+// Both drivers are OPTIONAL peers imported lazily. PGlite is ~22 MB of WASM and must
+// not land in the node_modules of every adopter who only ever runs `meta gen`; the
+// install hints mirror `buildKyselyFromUrl`'s. `cli` already depends on
+// `@libsql/kysely-libsql` outright, so only a direct embedder can miss that one.
+import { Kysely } from "kysely";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface ReplayEngine {
+  /** An empty database. The caller owns applying migrations into it. */
+  db: Kysely<Record<string, unknown>>;
+  /** Release the engine. Safe to call more than once. */
+  dispose: () => Promise<void>;
+}
+
+/** Open an empty in-process database of the given dialect. */
+export async function openReplayEngine(
+  dialect: "postgres" | "sqlite",
+): Promise<ReplayEngine> {
+  return dialect === "postgres" ? openPglite() : openMemorySqlite();
+}
+
+/**
+ * A throwaway sqlite database in a private temp directory, removed on dispose.
+ *
+ * NOT `:memory:`, and that is the whole point of this comment. Under
+ * `@libsql/kysely-libsql`, `:memory:` gives every CONNECTION its own database — so a
+ * table created inside a transaction is invisible the moment the transaction's
+ * connection is released. `applyPending` runs each migration file in a transaction,
+ * which means an in-memory engine would replay a whole chain into a series of
+ * throwaway databases, introspect an empty one, and never let migration 2 see
+ * migration 1's tables. The gate would pass having proved nothing.
+ *
+ * `file::memory:?cache=shared` fixes the visibility and breaks isolation instead —
+ * two engines in one process land in the SAME database — and libsql rejects the
+ * named `?mode=memory&cache=shared` form outright (`URL_PARAM_NOT_SUPPORTED`). A
+ * unique temp file is correct on both counts, and it is what the existing
+ * `test/integrity/replay.test.ts` has always used.
+ */
+async function openMemorySqlite(): Promise<ReplayEngine> {
+  type LibsqlDialectCtor = new (opts: { url: string }) =>
+    ConstructorParameters<typeof Kysely<Record<string, unknown>>>[0]["dialect"];
+  let LibsqlDialect: LibsqlDialectCtor;
+  try {
+    const mod = await import("@libsql/kysely-libsql");
+    LibsqlDialect = mod.LibsqlDialect as unknown as LibsqlDialectCtor;
+  } catch {
+    throw new Error(
+      `the sqlite replay engine requires '@libsql/kysely-libsql'; install it to run 'meta verify --replay'`,
+    );
+  }
+  const dir = mkdtempSync(join(tmpdir(), "meta-replay-"));
+  const db = new Kysely<Record<string, unknown>>({
+    dialect: new LibsqlDialect({ url: `file:${join(dir, "replay.db")}` }),
+  });
+  return disposable(db, async () => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+}
+
+async function openPglite(): Promise<ReplayEngine> {
+  let PGliteCtor: new () => PgliteInstance;
+  try {
+    const mod = await import("@electric-sql/pglite");
+    PGliteCtor = mod.PGlite as unknown as new () => PgliteInstance;
+  } catch {
+    throw new Error(
+      `the postgres replay engine requires '@electric-sql/pglite' (in-process WASM Postgres); ` +
+        `install it to run 'meta verify --replay' against a postgres chain`,
+    );
+  }
+  const { PostgresDialect } = await import("kysely");
+
+  // PGlite is Postgres compiled to WASM, and Emscripten propagates the WASM
+  // program's internal exit status into `process.exitCode` — it becomes 99 on the
+  // FIRST QUERY (not on teardown) and stays there for the life of the process.
+  // Opening an engine must not decide what the HOST process exits with, so the
+  // caller's value is captured here and restored on dispose.
+  //
+  // `bin/meta.ts` ends with `process.exit(code)`, which overrides this, so the
+  // shipped CLI never showed it. Anything that does NOT force its own exit did:
+  // this package's `bun test` exited 99 on 0 failures, turning two
+  // `ci-local.sh --only ts` gates red with no failing test to point at, and an
+  // embedder calling `openReplayEngine` directly would exit non-zero on success.
+  const hostExitCode = process.exitCode;
+  const pg = new PGliteCtor();
+  const db = new Kysely<Record<string, unknown>>({
+    dialect: new PostgresDialect({ pool: pgliteAsPool(pg) as never }),
+  });
+
+  // `?? 0` is load-bearing, not defensive: assigning `undefined` to
+  // `process.exitCode` is a NO-OP under Bun (measured — set 99, assign
+  // `undefined`, it stays 99; assign 0 and it clears). The pristine value IS
+  // `undefined`, so restoring it literally runs and changes nothing — which is
+  // the shape this bug already took once during the fix.
+  //
+  // The restore sits in a `finally` because this close is frequently the SECOND:
+  // `disposable` runs `db.destroy()` first, which drives the pool's `end()`,
+  // which already called `pg.close()`, so this call throws `PGlite is closed`.
+  return disposable(db, async () => {
+    try {
+      await pg.close();
+    } finally {
+      process.exitCode = hostExitCode ?? 0;
+    }
+  });
+}
+
+/** The slice of PGlite's surface this file uses. */
+interface PgliteInstance {
+  query(
+    sql: string,
+    params?: unknown[],
+  ): Promise<{ rows: unknown[]; affectedRows?: number; statement?: string }>;
+  close(): Promise<void>;
+}
+
+/**
+ * Adapt PGlite to the `pg.Pool` shape kysely's `PostgresDialect` expects: `connect()`
+ * returning a client with `query()`/`release()`, plus `end()`. PGlite offers only
+ * `query`/`close`, so without this the dialect cannot drive it at all.
+ *
+ * PGlite is a SINGLE session, so every `connect()` hands back the same underlying
+ * instance. That is correct here — a replay is strictly sequential — and it is what
+ * makes a session advisory lock taken on one kysely connection visible to the next.
+ *
+ * `command` is read by kysely only to decide whether to report numAffectedRows; the
+ * replay path never reads it, so PGlite's `statement` (or a SELECT default) suffices.
+ */
+function pgliteAsPool(pg: PgliteInstance): unknown {
+  return {
+    async connect() {
+      return {
+        async query(sqlText: unknown, params?: readonly unknown[]) {
+          if (typeof sqlText !== "string") {
+            throw new Error(`the PGlite replay engine does not support cursors`);
+          }
+          const r = await pg.query(sqlText, params ? [...params] : []);
+          return {
+            command: r.statement ?? "SELECT",
+            rowCount: r.affectedRows ?? r.rows.length,
+            rows: r.rows,
+          };
+        },
+        release() { /* single session — there is no pool to return to */ },
+      };
+    },
+    async end() {
+      await pg.close();
+    },
+  };
+}
+
+function disposable(
+  db: Kysely<Record<string, unknown>>,
+  closeEngine: () => Promise<void>,
+): ReplayEngine {
+  let disposed = false;
+  return {
+    db,
+    dispose: async () => {
+      if (disposed) return;
+      disposed = true;
+      // Both swallow: the engine is throwaway, and a teardown error must not mask
+      // the replay verdict the caller is about to report.
+      try { await db.destroy(); } catch { /* ignore */ }
+      try { await closeEngine(); } catch { /* ignore */ }
+    },
+  };
+}

package/src/verify/replay.ts

@@ -4,6 +4,7 @@ import { applyPending } from "../apply/apply.js";
 import { MIGRATIONS_TABLE } from "../apply/ledger.js";
 import { introspect } from "../introspect/index.js";
 import { driftAgainstSnapshot, type DriftClassification } from "../drift/classify.js";
+import { excludeFromSnapshot, type GovernedScope } from "../scope.js";
 import type { Dialect, SchemaSnapshot } from "../types.js";
 
 export interface VerifyReplayArgs {
@@ -14,6 +15,20 @@ export interface VerifyReplayArgs {
   migrationsDir: string;
   /** The committed snapshot the migrations are expected to reproduce. */
   snapshot: SchemaSnapshot;
+  /**
+   * The scope decision the run made, as `scopeExpectedSchema` reports it.
+   *
+   * A project declaring `migrate.scope` carries the OTHER owner's tables into its
+   * committed snapshot on purpose (`carryForwardOutOfScope`), and its chain — also on
+   * purpose — never creates them. Without this they read as missing on every replay,
+   * so a scoped project could never use this check at all.
+   *
+   * Excluded from the SNAPSHOT side only: the replayed database never had them
+   * either, so there is nothing to suppress on the actual side. Omitted ⇒ the
+   * comparison is byte-for-byte what it was, which is what every unscoped project
+   * gets.
+   */
+  governed?: GovernedScope;
 }
 
 export interface VerifyReplayResult extends DriftClassification {
@@ -35,7 +50,12 @@ export async function verifyReplay(args: VerifyReplayArgs): Promise<VerifyReplay
     ...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,