@metaobjectsdev/migrate-ts 0.23.1 → 0.24.0

package/dist/verify/replay-engine.js

@@ -0,0 +1,161 @@
+// 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";
+/** Open an empty in-process database of the given dialect. */
+export async function openReplayEngine(dialect) {
+    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() {
+    let LibsqlDialect;
+    try {
+        const mod = await import("@libsql/kysely-libsql");
+        LibsqlDialect = mod.LibsqlDialect;
+    }
+    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({
+        dialect: new LibsqlDialect({ url: `file:${join(dir, "replay.db")}` }),
+    });
+    return disposable(db, async () => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+}
+async function openPglite() {
+    let PGliteCtor;
+    try {
+        const mod = await import("@electric-sql/pglite");
+        PGliteCtor = mod.PGlite;
+    }
+    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({
+        dialect: new PostgresDialect({ pool: pgliteAsPool(pg) }),
+    });
+    // `?? 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;
+        }
+    });
+}
+/**
+ * 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) {
+    return {
+        async connect() {
+            return {
+                async query(sqlText, params) {
+                    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() { },
+            };
+        },
+        async end() {
+            await pg.close();
+        },
+    };
+}
+function disposable(db, closeEngine) {
+    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 */ }
+        },
+    };
+}
+//# sourceMappingURL=replay-engine.js.map

package/dist/verify/replay-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-engine.js","sourceRoot":"","sources":["../../src/verify/replay-engine.ts"],"names":[],"mappings":"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"}

package/dist/verify/replay.d.ts

@@ -1,5 +1,6 @@
 import type { Kysely } from "kysely";
 import { type DriftClassification } from "../drift/classify.js";
+import { type GovernedScope } from "../scope.js";
 import type { Dialect, SchemaSnapshot } from "../types.js";
 export interface VerifyReplayArgs {
     /** A FRESH, throwaway database. Replay applies every migration into it from empty. */
@@ -9,6 +10,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 {
     /** True when the replayed schema matches the snapshot (no drift, no unmanaged). */

package/dist/verify/replay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/verify/replay.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIrC,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,QAAQ,CAAC,CAAC;IACjD,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,mFAAmF;IACnF,EAAE,EAAE,OAAO,CAAC;CACb;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAYtF"}
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/verify/replay.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIrC,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,QAAQ,CAAC,CAAC;IACjD,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,EAAE,cAAc,CAAC;IACzB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,mFAAmF;IACnF,EAAE,EAAE,OAAO,CAAC;CACb;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiBtF"}

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.1",
+  "version": "0.24.0",
   "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.1"
+    "@metaobjectsdev/metadata": "0.24.0"
   },
   "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.
@@ -148,9 +151,16 @@ export async function diff(
   // schemas it mentions), else null = no scoping (empty model → prior whole-DB
   // behavior). A table outside the scope is excluded from both sides, so a
   // co-located schema owned by another app is neither dropped nor reported.
-  const declaredSchemas = new Set(
-    args.expected.tables.map((t) => t.schema ?? DEFAULT_DB_SCHEMA_POSTGRES),
-  );
+  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`
+    // 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
+    // undetected) rather than gated on it as an owned schema.
+    ...args.expected.views.map((v) => v.schema ?? DEFAULT_DB_SCHEMA_POSTGRES),
+  ]);
   const scopeSchemas: Set<string> | null =
     args.scopeSchemas !== undefined
       ? new Set(args.scopeSchemas)
@@ -583,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":