@metaobjectsdev/cli 0.23.2 → 0.24.0

package/dist/src/commands/migrate.js

@@ -1,5 +1,6 @@
 import { resolve as resolvePath } from "node:path";
 import { mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { parseMigrateArgs } from "../lib/args.js";
 import { resolveMigrateConfig, MIGRATE_DEFAULT_OUT_DIR } from "../lib/config.js";
@@ -8,9 +9,10 @@ import { formatMigrateResultJson } from "../lib/output-json.js";
 import { toonEncode } from "../lib/format.js";
 import { buildKyselyFromUrl, redactUrl } from "../lib/kysely.js";
 import { log } from "../lib/log.js";
-import { loadMemory } from "@metaobjectsdev/sdk";
-import { loadMetaobjectsConfig } from "../lib/load-metaobjects-config.js";
-import { buildExpectedSchema, introspect, diff, collectUnmanagedNames, emit, writeMigration, baselineFromMetadata, planOffline, snapshotPath, readSnapshot, writeSnapshot, BlockedChangesError, PrimaryKeyChangeError, renderD1, writeMigrationD1, writeMigrationFlyway, introspectD1, applyPending, rollbackTo, findWranglerConfig, parseWranglerConfig, resolveD1Binding, } from "@metaobjectsdev/migrate-ts";
+import { loadMemory, resolveCollection, resolveConfigDir } from "@metaobjectsdev/sdk";
+import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { migrateScopeMismatch, outOfScopeNote } from "../lib/migrate-scope.js";
+import { buildExpectedSchemaWithProvenance, scopeExpectedSchema, scopedDiffInputs, introspect, diff, collectUnmanagedNames, carryForwardOutOfScope, emit, writeMigration, baselineFromMetadata, planOffline, snapshotPath, readSnapshot, writeSnapshot, qualifiedDbName, BlockedChangesError, PrimaryKeyChangeError, renderD1, writeMigrationD1, writeMigrationFlyway, introspectD1, applyPending, rollbackTo, findWranglerConfig, parseWranglerConfig, resolveD1Binding, } from "@metaobjectsdev/migrate-ts";
 import { buildWranglerExecuteArgs, defaultWranglerRunner, } from "../lib/wrangler.js";
 import { buildProjectionViews } from "@metaobjectsdev/codegen-ts";
 import { tokensToAllowOptions, describeChange } from "../lib/allow.js";
@@ -24,8 +26,11 @@ SUBCOMMANDS:
                        (use with --from-db). NOTE: for a brand-new/empty database use
                        the greenfield example below, NOT baseline — an offline baseline
                        records your metadata as already-applied and emits no CREATE TABLE.
-  apply-pending        Replay committed migration files against --db (no diff);
-                       provisions a fresh/CI database. postgres/sqlite only.
+  apply-pending        Replay committed migration files against --db (no diff).
+                       Provisions a fresh/CI database when the chain BUILDS the
+                       schema — 'meta verify --replay' proves that it does. A
+                       database adopted via 'baseline --from-db' has no such
+                       chain. postgres/sqlite only.
 
 MIGRATE FLAGS:
   --db <url>           DB connection URL (required for live-introspect / --apply / --rollback)
@@ -45,7 +50,13 @@ MIGRATE FLAGS:
   --allow <csv>        Comma-separated destructive-change permissions:
                        drop-column,drop-table,type-change,drop-index,drop-fk,
                        drop-check,drop-view,drop-view-cascade,
-                       adopt-view,nullable-to-not-null,drop-identity-default
+                       adopt-view,nullable-to-not-null,drop-identity-default,
+                       drop-unmanaged
+                       drop-unmanaged permits dropping a table/view the committed
+                       snapshot never contained — one this toolchain never managed.
+                       Without it that drop is refused, because the migration it
+                       writes cannot replay against a database where the object
+                       never existed.
   --on-ambiguous abort|rename|drop-add
                        How to handle ambiguous renames (default: abort)
   --from-db            Introspect live DB instead of using the committed snapshot
@@ -83,6 +94,69 @@ function resolveFormatOutDir(config, metaRoot) {
     }
     return resolvePath(metaRoot, config.outDir);
 }
+/**
+ * D1's OWN directory convention — `--out-dir` > `wrangler.toml`'s
+ * `migrations_dir` > `"migrations"` — kept apart from `resolveFormatOutDir`
+ * because the middle term is not knowable until a wrangler binding has been
+ * resolved (`runD1Migrate` step 1), while every other dialect can answer
+ * immediately from `config` alone.
+ */
+function resolveD1OutDir(config, metaRoot, migrationsDirHint) {
+    const isDefaultOutDir = config.outDir === MIGRATE_DEFAULT_OUT_DIR;
+    return resolvePath(metaRoot, isDefaultOutDir ? (migrationsDirHint ?? "migrations") : config.outDir);
+}
+/**
+ * Say so when the migrations directory this run will use is NOT the one sitting
+ * in the working directory.
+ *
+ * `metaRoot` is now the discovered project root rather than ambient cwd, and the
+ * migrations directory follows it. That is the right call — the ledger belongs
+ * with the config that declares it — but it is a behaviour change for the two
+ * subcommands that load no metadata at all: `apply-pending` and `--rollback`
+ * used cwd unconditionally, so a subdirectory holding `.metaobjects/migrations`
+ * under a project root that also has one now replays the ROOT's ledger.
+ * Replaying somebody else's migration history silently is the worst outcome
+ * available here, so it is announced.
+ *
+ * Conditioned on the local directory EXISTING, so the ordinary case — a run from
+ * anywhere inside a project with one ledger at its root — says nothing.
+ * `--out-dir` (and a `migrate.outDir` in the config) is honoured: the caller
+ * must pass the directory THIS run will actually WRITE to, never a default
+ * that was overridden — a deliberate redirection is compared, not a stale
+ * guess. That answer comes from **two** call sites, because there are two
+ * directory conventions: every dialect but d1 resolves via
+ * `resolveFormatOutDir` before the format/dialect dispatch below; d1 has its
+ * own convention (`resolveD1OutDir`, wrangler.toml's `migrations_dir`) that is
+ * unknowable until its binding resolves, so it calls this again for itself
+ * from inside `runD1Migrate`, once that binding is in hand.
+ */
+function warnIfLedgerRelocated(cwd, resolvedOutDir) {
+    const local = resolvePath(cwd, MIGRATE_DEFAULT_OUT_DIR);
+    if (resolvedOutDir === local || !existsSync(local))
+        return;
+    log.warn(`migrate: using the migrations directory ${resolvedOutDir}, not the ${local} ` +
+        `in this working directory — the ledger belongs to the project root that declares it. ` +
+        `Pass --out-dir ${local} to use the local one.`);
+}
+/**
+ * Report what a declared `migrate.scope` left out (wording: `outOfScopeNote`).
+ *
+ * STDOUT in text format, STDERR otherwise. `--format json` / `--format toon` put a
+ * single machine-readable document on stdout, and a prose line ahead of it breaks
+ * `| jq` outright — the same split `emitStructuredError` makes just below.
+ * Routed to stderr rather than dropped, because the non-TTY default format is toon
+ * (`resolveFormat`): suppressing it outright would silence the note for every
+ * piped and CI run, which is most of them.
+ */
+function logOutOfScope(names, fmt) {
+    if (names.length === 0)
+        return;
+    const msg = outOfScopeNote("migrate", names);
+    if (fmt === "text")
+        log.info(msg);
+    else
+        log.warn(msg);
+}
 function emitStructuredError(error, hint, fmt) {
     const payload = { error, hint };
     if (fmt === "json") {
@@ -93,6 +167,23 @@ function emitStructuredError(error, hint, fmt) {
     }
     // text format: errors go to stderr via log.error() — the caller handles that path
 }
+/**
+ * The refusal for a `migrate.scope` that matches nothing, as all three of migrate's
+ * pipelines (online, offline, D1) issue it.
+ *
+ * Returns the exit code to return, or `undefined` when there is nothing to refuse.
+ * Three byte-identical copies of the report-and-exit differed only in a local
+ * variable name; the hint string and the exit code are one decision, recorded once
+ * — a configuration error, so exit 2.
+ */
+function refuseScopeMismatch(collection, provenance, fmt) {
+    const mismatch = migrateScopeMismatch(collection, provenance);
+    if (mismatch === undefined)
+        return undefined;
+    log.error(`migrate: ${mismatch}`);
+    emitStructuredError(`migrate: ${mismatch}`, "fix or remove migrate.scope in .metaobjects/config.json", fmt);
+    return 2;
+}
 /**
  * Sentinel thrown by sub-functions that have already emitted a structured error
  * via emitStructuredError(). The top-level catch in migrateCommand re-throws
@@ -151,6 +242,75 @@ function summarizeChanges(changes) {
     }
     return counts;
 }
+/**
+ * The qualified names of tables/views/constraints this diff proposes to DROP that
+ * the committed snapshot never contained — i.e. objects this toolchain never
+ * managed (#313).
+ *
+ * FAILS OPEN. No snapshot on disk, or one that cannot be read, yields an empty list:
+ * a project that has never generated one is not in an error state, and refusing there
+ * would break the first `meta migrate` of every greenfield project. A parse failure is
+ * migrate's own error to raise elsewhere, with its own message, not a silent refusal
+ * here.
+ *
+ * Table/view names come from `qualifiedDbName` and nothing else. Three independent
+ * sets already have to agree on this spelling — the diff's identity maps, the
+ * `@unmanaged` exclusion set, and the out-of-scope set — and a fourth encoding of
+ * "absent schema means public" would silently un-guard every object it disagreed
+ * about.
+ *
+ * `drop-fk`/`drop-check`/constraint-backed `drop-index` are checked at the
+ * CONSTRAINT grain, not just the table's: the emitter's `IF EXISTS` on the
+ * enclosing `ALTER TABLE` (the SQL half of this same #313 gap) only stops the
+ * replay from failing outright — it says nothing about whether AUTHORING the
+ * drop was ever supposed to be permission-free. A table can be fully managed
+ * while carrying a constraint another tool added directly against the live
+ * database; that constraint's name is absent from the snapshotted table's own
+ * `foreignKeys`/`checks`/`indexes`, exactly like a whole unmanaged table is
+ * absent from `snapshot.tables`.
+ */
+async function snapshotAbsentDrops(changes, snapPath) {
+    let snapshot;
+    try {
+        snapshot = await readSnapshot(snapPath);
+    }
+    catch {
+        return [];
+    }
+    if (snapshot === null)
+        return [];
+    const managedTables = new Map();
+    for (const t of snapshot.tables)
+        managedTables.set(qualifiedDbName(t), t);
+    const managedViews = new Set();
+    for (const v of snapshot.views)
+        managedViews.add(qualifiedDbName(v));
+    const absent = [];
+    for (const c of changes) {
+        if (c.kind === "drop-table") {
+            const name = qualifiedDbName({ name: c.table, schema: c.schema });
+            if (!managedTables.has(name))
+                absent.push(name);
+        }
+        else if (c.kind === "drop-view") {
+            const name = qualifiedDbName({ name: c.view, schema: c.schema });
+            if (!managedViews.has(name))
+                absent.push(name);
+        }
+        else if (c.kind === "drop-fk" || c.kind === "drop-check" || c.kind === "drop-index") {
+            const tableName = qualifiedDbName({ name: c.table, schema: c.schema });
+            const table = managedTables.get(tableName);
+            const constraintName = c.kind === "drop-fk" ? c.fk : c.kind === "drop-check" ? c.check : c.index;
+            const recorded = c.kind === "drop-fk" ? table?.foreignKeys
+                : c.kind === "drop-check" ? table?.checks
+                    : table?.indexes;
+            if (recorded === undefined || !recorded.some((d) => d.name === constraintName)) {
+                absent.push(`${tableName}.${constraintName}`);
+            }
+        }
+    }
+    return absent;
+}
 function allowFlagFor(kind) {
     switch (kind) {
         case "drop-column": return "drop-column";
@@ -204,8 +364,56 @@ wranglerRunner, fmt = "text") {
         emitStructuredError(`migrate: ${msg}`, "run `meta migrate --help` for usage", fmt);
         return 2;
     }
-    const metaRoot = cwd;
+    // The project root is the directory whose `.metaobjects/config.json` governs
+    // this run — the same directory `resolveCollection` resolves the metadata
+    // from, found the same way (design §4.6.1: "Per-port generator config is then
+    // read from that same directory"). Everything below is relative to it: the
+    // `.metaobjects/config.json` operational block, `metaobjects.config.ts`'s
+    // `columnNamingStrategy`, the migrations `outDir`, `wrangler.toml` discovery.
+    //
+    // Read from ambient cwd instead, as this did, they DIVERGE the moment the two
+    // differ: run `meta migrate` from a subdirectory of a project whose root
+    // declares `columnNamingStrategy: "literal"` and the metadata resolves from
+    // the ancestor while the strategy silently defaults to snake_case — emitting a
+    // migration that renames every column. Newly reachable, too: before metadata
+    // sources were resolvable that invocation just failed with "no metaobjects/
+    // found".
+    //
+    // `resolveConfigDir` rather than `resolveCollection` deliberately: this must
+    // not require metadata to EXIST. `migrate apply-pending` and `--rollback`
+    // replay committed SQL and load no metadata at all, and making them fail on a
+    // project with no model would be a regression. It is the SAME walk
+    // `resolveCollection` runs (one exported definition in the sdk's
+    // `discovery.ts`, not two that agree by construction), so the directory this
+    // resolves and the directory the metadata comes from cannot diverge.
+    const metaRoot = await resolveConfigDir(cwd);
+    // `metaobjects.config.ts` is the one thing here NOT governed by that walk. It
+    // answers a different question from `.metaobjects/config.json` (design §4.6 —
+    // per-port "how is code generated here?" versus port-neutral "where does metadata
+    // come from?"), and in a Maven- or pip-rooted monorepo the two legitimately sit in
+    // different directories. Reading it from `metaRoot` there silently defaults
+    // `columnNamingStrategy` for a package that declares one — the exact
+    // rename-every-column failure the co-location was introduced to prevent, arrived
+    // at from the other side (#326). Nearest wins, so a subdirectory declaring nothing
+    // still walks up to the project root's config; identical to `metaRoot` in every
+    // `meta init` project, where the two files sit together.
+    const genRoot = resolveGenConfigDir(cwd, metaRoot);
     const config = await resolveMigrateConfig(flags, metaRoot);
+    // `resolveFormatOutDir`, not `resolvePath(metaRoot, config.outDir)`: under
+    // `--migration-format flyway` with a default outDir the run writes to
+    // Flyway's conventional location instead, so the unredirected path names a
+    // directory this invocation will never touch.
+    //
+    // Skipped for a plain `--dialect d1` run (format !== flyway): d1 resolves
+    // its OWN directory from wrangler.toml, unknowable until its binding
+    // resolves, so it issues this warning for itself from inside
+    // `runD1Migrate` instead — `resolveFormatOutDir` here would name the
+    // Kysely-path default, a directory that run never writes to. A d1 +
+    // `--migration-format flyway` run is refused just below before either
+    // directory is ever touched, so THAT combination still wants this one.
+    if (config.dialect !== "d1" || config.format === "flyway") {
+        warnIfLedgerRelocated(cwd, resolveFormatOutDir(config, metaRoot));
+    }
     try {
         // #192 — Flyway owns apply + history (flyway_schema_history). We generate the
         // migration; applying it is Flyway's job. Refuse at generation time rather than
@@ -254,11 +462,11 @@ wranglerRunner, fmt = "text") {
                 emitStructuredError(`migrate: --rollback is not supported for dialect 'd1'`, "use 'wrangler d1 migrations' tooling to roll back d1", fmt);
                 return 2;
             }
-            return await runD1Migrate(config, metaRoot, wranglerRunner ?? defaultWranglerRunner, fmt);
+            return await runD1Migrate(config, metaRoot, cwd, wranglerRunner ?? defaultWranglerRunner, fmt);
         }
         // `migrate baseline` — seed the committed reference snapshot, emit no migration.
         if (config.baseline) {
-            return await runBaseline(config, metaRoot, fmt);
+            return await runBaseline(config, metaRoot, fmt, genRoot);
         }
         // `migrate apply-pending` — replay committed migration files; no diff, no metadata load.
         if (config.applyPending) {
@@ -268,7 +476,7 @@ wranglerRunner, fmt = "text") {
         // when explicitly requested via --from-db, when --apply needs a connection, or
         // for --rollback (which runs hand-authored down.sql against the live DB).
         if (!config.fromDb && !config.apply && config.rollback === undefined) {
-            return await runOfflineGenerate(config, metaRoot, fmt);
+            return await runOfflineGenerate(config, metaRoot, fmt, genRoot);
         }
         if (config.databaseUrl === undefined) {
             log.error(`migrate: --db <url> required (or set DATABASE_URL, or add migrate.databaseUrl to .metaobjects/config.json)`);
@@ -284,28 +492,35 @@ wranglerRunner, fmt = "text") {
         // Best-effort load of metaobjects.config.ts to pick up consumer-supplied
         // providers. migrate's postgres/sqlite path also reads the config later
         // for columnNamingStrategy; we load it once here and reuse below.
-        let postgresConfigProviders;
+        let postgresLoadOptions = {};
         try {
-            const forgeConfig = await loadMetaobjectsConfig(metaRoot);
-            postgresConfigProviders = forgeConfig.providers;
+            postgresLoadOptions = loadMemoryOptionsFrom(await loadMetaobjectsConfig(genRoot));
         }
         catch {
-            postgresConfigProviders = undefined;
+            postgresLoadOptions = {};
+        }
+        // Discovery and load are two separate failure modes, kept in separate try blocks
+        // (the `meta gen` pattern): a broad catch around both reports a genuine ParseError
+        // as "no metadata found", masking the real failure. `resolveCollection` raises
+        // ERR_COLLECTION_NOT_FOUND with its own message — the same exit 2 the hand-rolled
+        // ENOENT sniff used to produce.
+        let collection;
+        try {
+            collection = await resolveCollection(metaRoot);
+        }
+        catch (err) {
+            log.error(err.message);
+            return 2;
         }
         let metadata;
         try {
-            metadata = await loadMemory(metaRoot, {
-                ...(postgresConfigProviders !== undefined ? { providers: postgresConfigProviders } : {}),
+            metadata = await loadMemory(collection.configDir, {
+                files: collection.files,
+                ...postgresLoadOptions,
             });
         }
         catch (err) {
-            const msg = err.message;
-            if (msg.includes("ENOENT") || msg.includes("no such") || msg.includes("cannot read")) {
-                log.error(`no metaobjects/ found in ${metaRoot}; run 'meta init' to scaffold`);
-            }
-            else {
-                log.error(`failed to load metadata: ${msg}`);
-            }
+            log.error(`failed to load metadata: ${err.message}`);
             return 2;
         }
         let kysely;
@@ -328,7 +543,7 @@ wranglerRunner, fmt = "text") {
             // and projection view DDL — derive it once, up front, so every view path agrees.
             let columnNamingStrategy = "snake_case";
             try {
-                const cfg = await loadMetaobjectsConfig(metaRoot);
+                const cfg = await loadMetaobjectsConfig(genRoot);
                 if (cfg.columnNamingStrategy)
                     columnNamingStrategy = cfg.columnNamingStrategy;
             }
@@ -340,11 +555,21 @@ wranglerRunner, fmt = "text") {
             // view DDL (create/drop/replace + dependency-recreate) and emit() renders it —
             // there is no separate view-migration emitter.
             const expectedViews = buildProjectionViews(metadata, { dialect: kysely.dialect, columnNamingStrategy });
-            const expected = buildExpectedSchema(metadata, {
+            const built = buildExpectedSchemaWithProvenance(metadata, {
                 dialect: kysely.dialect,
                 columnNamingStrategy,
                 views: expectedViews,
             });
+            const scopeRc = refuseScopeMismatch(collection, () => built.provenance, fmt);
+            if (scopeRc !== undefined)
+                return scopeRc;
+            // Per-command scope: objects outside `migrate.scope` are another owner's. They
+            // leave the expected schema here and are suppressed on the actual side below —
+            // dropping them from `expected` ALONE would propose DROP TABLE for every one of
+            // them that exists in the database.
+            const scoped = scopeExpectedSchema(built, collection.inMigrateScope);
+            const expected = scoped.snapshot;
+            logOutOfScope(scoped.outOfScope, fmt);
             let actual;
             try {
                 actual = await introspect(kysely.db, kysely.dialect);
@@ -359,7 +584,12 @@ wranglerRunner, fmt = "text") {
             let diffResult;
             try {
                 diffResult = await diff({
-                    expected,
+                    // The three scoped-diff obligations as one value (migrate-ts's scope.ts
+                    // header has the mechanism): the narrowed expected side, `unmanagedNames`
+                    // merging #208 §7's declared-@unmanaged set with the out-of-scope names so
+                    // neither is created or dropped, and the schema scope pinned to the
+                    // UNSCOPED model so narrowing can never widen the run.
+                    ...scopedDiffInputs(scoped, collectUnmanagedNames(metadata)),
                     actual,
                     dialect: kysely.dialect,
                     allow: tokensToAllowOptions(config.allow),
@@ -367,9 +597,6 @@ wranglerRunner, fmt = "text") {
                     // has no expressible migration; refuse loudly instead of emitting SQL that drops
                     // the constraint and breaks referencing FKs at apply.
                     refusePrimaryKeyChange: true,
-                    // #208 §7 — declared-@unmanaged objects are external: exclude them from the
-                    // actual side so migrate proposes neither create nor drop for them.
-                    unmanagedNames: collectUnmanagedNames(metadata),
                     onAmbiguous: async (a) => {
                         collectedAmbiguous.push(a);
                         return onAmbiguousResolution;
@@ -409,6 +636,34 @@ wranglerRunner, fmt = "text") {
                 throw err;
             }
             changeCounts = summarizeChanges(diffResult.changes);
+            // #313 — refuse to AUTHOR a drop for an object the committed snapshot never
+            // contained. This path diffs metadata against introspection and never reads the
+            // snapshot, so an object another tool owns reads as "in the DB, not in the model"
+            // and is proposed for a drop; the migration that results cannot replay against a
+            // database where that object never existed, which is how a chain stays broken for
+            // months. `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" — and this is where it is finally enforced.
+            //
+            // It does not false-fire on the brownfield cases, because both of them ADD to the
+            // snapshot: a `baseline --from-db` snapshot contains the foreign table, and a
+            // scoped project carries its out-of-scope entries forward. The guard fires
+            // precisely when nothing ever claimed the object.
+            //
+            // Only on THIS path, and that is not an omission: the offline path diffs metadata
+            // against the committed snapshot, so it proposes a drop only for an object the
+            // snapshot HAS. A snapshot-absent drop is unreachable there by construction.
+            const unmanagedDrops = await snapshotAbsentDrops(diffResult.changes, snapshotPath(resolvePath(metaRoot, config.outDir), kysely.dialect));
+            if (unmanagedDrops.length > 0 && tokensToAllowOptions(config.allow).dropUnmanaged !== true) {
+                const named = unmanagedDrops.join(", ");
+                log.error(`migrate: refusing to drop ${named} — absent from the committed schema snapshot, so this ` +
+                    `toolchain never managed ${unmanagedDrops.length === 1 ? "it" : "them"} and the migration ` +
+                    `could not replay against a database where ${unmanagedDrops.length === 1 ? "it" : "they"} ` +
+                    `never existed. Re-run with '--allow drop-unmanaged' if the drop is intended.`);
+                emitStructuredError(`migrate: refusing to drop ${named} — absent from the committed schema snapshot`, "re-run with '--allow drop-unmanaged' if the drop is intended", fmt);
+                await kysely.close();
+                return 2;
+            }
             // All changes — tables AND views — are emitted by the one schema-diff path.
             // View DDL (create/drop/replace) is produced by diff()'s view passes (2b body
             // comparison, 2c dependency-recreate) and rendered by every dialect's emitter;
@@ -507,7 +762,23 @@ wranglerRunner, fmt = "text") {
             // native ALTER vs recreate-and-copy on older SQLite.
             if (!config.dryRun && exitCode === 0 && !applyFailed && writtenPaths.length > 0) {
                 try {
-                    await writeSnapshot(snapshotPath(resolvePath(metaRoot, config.outDir), kysely.dialect), actual.meta !== undefined ? { ...expected, meta: actual.meta } : expected);
+                    // The COMMITTED snapshot keeps what `migrate.scope` excluded: writing the
+                    // narrowed schema would delete every out-of-scope entry, so a later widening
+                    // would propose CREATE TABLE for a table that exists and fail at apply. The
+                    // out-of-scope entries come from `actual` — they are in the database, which
+                    // is the same thing `baseline --from-db` records. Identical object, and so a
+                    // byte-identical snapshot, for an unscoped run.
+                    //
+                    // The trade-off, stated so it is not rediscovered: those carried entries are
+                    // INTROSPECTED descriptors, not metadata-built ones, so they can differ
+                    // cosmetically from what this model would have emitted for the same table
+                    // (column order, a default's rendered form). Removing the scope later can
+                    // therefore produce one round of alter churn. That is strictly better than
+                    // the alternative it replaced — a `CREATE TABLE` for a table that exists,
+                    // which fails at apply — and it is the same mixed-provenance snapshot
+                    // `baseline --from-db` writes for every table it adopts.
+                    const committed = carryForwardOutOfScope(expected, actual, scoped.outOfScope);
+                    await writeSnapshot(snapshotPath(resolvePath(metaRoot, config.outDir), kysely.dialect), actual.meta !== undefined ? { ...committed, meta: actual.meta } : committed);
                 }
                 catch (err) {
                     // The migration itself is written (and possibly applied) — report the
@@ -568,7 +839,11 @@ wranglerRunner, fmt = "text") {
  * `--from-metadata` (default) derives it from metadata; `--from-db` introspects
  * an existing database once. Emits no migration.
  */
-export async function runBaseline(config, metaRoot, fmt = "text") {
+export async function runBaseline(config, metaRoot, fmt = "text", 
+/** Directory whose `metaobjects.config.ts` governs — see `migrateCommand`'s
+ *  `genRoot`. Defaults to `metaRoot`, the co-located case every `meta init`
+ *  project is in and the only one the direct-call test suites construct. */
+genRoot = metaRoot) {
     if (config.dialect === undefined) {
         log.error(`migrate baseline: --dialect required (or set migrate.dialect in .metaobjects/config.json)`);
         return 2;
@@ -621,23 +896,34 @@ export async function runBaseline(config, metaRoot, fmt = "text") {
             `baseline — this emits NO CREATE TABLE. Use it only if your database already matches ` +
             `your metadata; for a new/empty database run \`${greenfieldCreateCmd(config.dialect)}\` instead.`);
         let metadata;
-        // Load metaobjects.config.ts ONCE, up front, for BOTH the consumer providers
+        // Load metaobjects.config.ts ONCE, up front, for BOTH the consumer providers/libraries
         // and the columnNamingStrategy — mirroring the DB path (and `meta gen`) so
         // offline baseline resolves config-registered custom subtypes too (#157).
-        let baselineConfigProviders;
+        let baselineLoadOptions = {};
         let baselineStrategy = "snake_case";
         try {
-            const cfg = await loadMetaobjectsConfig(metaRoot);
-            baselineConfigProviders = cfg.providers;
+            const cfg = await loadMetaobjectsConfig(genRoot);
+            baselineLoadOptions = loadMemoryOptionsFrom(cfg);
             if (cfg.columnNamingStrategy)
                 baselineStrategy = cfg.columnNamingStrategy;
         }
         catch {
-            // config absent — no custom providers, default snake_case
+            // config absent — no custom providers, no libraries, default snake_case
         }
+        // `baseline` records a STARTING POINT, so it is deliberately NOT scoped: the
+        // `--from-db` arm captures whatever the database holds (there is no provenance
+        // for an introspected table), and an offline baseline that recorded less would
+        // disagree with it. An out-of-scope table sitting in the snapshot is harmless:
+        // every later run suppresses it on both sides of the diff, and an accepted
+        // scoped run carries it FORWARD (`carryForwardOutOfScope`) rather than dropping
+        // it — which is what makes that true. Committing the narrowed schema instead
+        // would delete the entry, and removing the scope later would then propose
+        // CREATE TABLE for a table that exists.
         try {
-            metadata = await loadMemory(metaRoot, {
-                ...(baselineConfigProviders !== undefined ? { providers: baselineConfigProviders } : {}),
+            const collection = await resolveCollection(metaRoot);
+            metadata = await loadMemory(collection.configDir, {
+                files: collection.files,
+                ...baselineLoadOptions,
             });
         }
         catch (err) {
@@ -735,35 +1021,50 @@ export async function runApplyPending(config, metaRoot, fmt = "text") {
  * Scope: table/column/index/FK changes. Projection-view migrations stay on the
  * introspection path (offline-view parity is a follow-up).
  */
-export async function runOfflineGenerate(config, metaRoot, fmt = "text") {
+export async function runOfflineGenerate(config, metaRoot, fmt = "text", 
+/** Directory whose `metaobjects.config.ts` governs — see `migrateCommand`'s
+ *  `genRoot`. Defaults to `metaRoot`, the co-located case. */
+genRoot = metaRoot) {
     if (config.dialect === undefined) {
         log.error(`migrate: --dialect required for offline generation (or use --from-db)`);
         return 2;
     }
-    // Load metaobjects.config.ts ONCE, up front, for BOTH the consumer providers
+    // Load metaobjects.config.ts ONCE, up front, for BOTH the consumer providers/libraries
     // and the columnNamingStrategy — mirroring the DB path (and `meta gen`) so
     // offline generate resolves config-registered custom subtypes too (#157).
-    let offlineConfigProviders;
+    let offlineLoadOptions = {};
     let offlineStrategy = "snake_case";
     try {
-        const cfg = await loadMetaobjectsConfig(metaRoot);
-        offlineConfigProviders = cfg.providers;
+        const cfg = await loadMetaobjectsConfig(genRoot);
+        offlineLoadOptions = loadMemoryOptionsFrom(cfg);
         if (cfg.columnNamingStrategy)
             offlineStrategy = cfg.columnNamingStrategy;
     }
     catch {
-        // config absent — no custom providers, default snake_case
+        // config absent — no custom providers, no libraries, default snake_case
     }
     let metadata;
+    let collection;
     try {
-        metadata = await loadMemory(metaRoot, {
-            ...(offlineConfigProviders !== undefined ? { providers: offlineConfigProviders } : {}),
+        collection = await resolveCollection(metaRoot);
+        metadata = await loadMemory(collection.configDir, {
+            files: collection.files,
+            ...offlineLoadOptions,
         });
     }
     catch (err) {
         log.error(`migrate: failed to load metadata: ${err.message}`);
         return 2;
     }
+    const offlineDialect = config.dialect;
+    const offlineViews = buildProjectionViews(metadata, { dialect: offlineDialect, columnNamingStrategy: offlineStrategy });
+    const scopeRc = refuseScopeMismatch(collection, () => buildExpectedSchemaWithProvenance(metadata, {
+        dialect: offlineDialect,
+        columnNamingStrategy: offlineStrategy,
+        views: offlineViews,
+    }).provenance, fmt);
+    if (scopeRc !== undefined)
+        return scopeRc;
     const outDir = resolvePath(metaRoot, config.outDir);
     const path = snapshotPath(outDir, config.dialect);
     let snapshot;
@@ -788,7 +1089,7 @@ export async function runOfflineGenerate(config, metaRoot, fmt = "text") {
     }
     const collectedAmbiguous = [];
     const onAmbiguousResolution = mapOnAmbiguous(config.onAmbiguous);
-    const offlineViews = buildProjectionViews(metadata, { dialect: config.dialect, columnNamingStrategy: offlineStrategy });
+    const offlineScope = collection.inMigrateScope;
     let plan;
     try {
         plan = await planOffline({
@@ -797,6 +1098,8 @@ export async function runOfflineGenerate(config, metaRoot, fmt = "text") {
             snapshot,
             columnNamingStrategy: offlineStrategy,
             views: offlineViews,
+            // Per-command scope — narrows BOTH sides of the offline diff (see planOffline).
+            ...(offlineScope !== undefined ? { inScope: offlineScope } : {}),
             allow: tokensToAllowOptions(config.allow),
             onAmbiguous: async (a) => {
                 collectedAmbiguous.push(a);
@@ -817,7 +1120,11 @@ export async function runOfflineGenerate(config, metaRoot, fmt = "text") {
         }
         throw err;
     }
-    const { diff: diffResult, nextSnapshot } = plan;
+    // `nextSnapshot` is what gets COMMITTED (it retains this run's out-of-scope
+    // entries); `expected` is the governed side the emitter renders against. Equal
+    // for an unscoped run.
+    const { diff: diffResult, nextSnapshot, expected: governedExpected } = plan;
+    logOutOfScope(plan.outOfScope, fmt);
     if (diffResult.blocked.length > 0) {
         log.error(`migrate: ${diffResult.blocked.length} destructive change(s) blocked; re-run with --allow <tokens>`);
         return 1;
@@ -832,7 +1139,7 @@ export async function runOfflineGenerate(config, metaRoot, fmt = "text") {
     }
     const emitResult = emit(diffResult.changes, {
         dialect: config.dialect,
-        expectedSchema: nextSnapshot,
+        expectedSchema: governedExpected,
         actualSchema: snapshot,
         ...(snapshot.meta ? { actualMeta: snapshot.meta } : {}),
     });
@@ -907,7 +1214,12 @@ async function runRollback(config, metaRoot) {
         }
     }
 }
-async function runD1Migrate(config, metaRoot, runner, fmt = "text") {
+async function runD1Migrate(config, metaRoot, cwd, runner, fmt = "text") {
+    // Same split as `migrateCommand`: `.metaobjects/` state hangs off `metaRoot`,
+    // `metaobjects.config.ts` off its own nearest-ancestor walk (#326). Recomputed
+    // rather than threaded — it is a pure function of the two arguments this already
+    // takes, so the two cannot disagree.
+    const genRoot = resolveGenConfigDir(cwd, metaRoot);
     // 1. Resolve wrangler.toml + binding.
     const wranglerConfigPath = config.d1.wranglerConfigPath
         ? resolvePath(metaRoot, config.d1.wranglerConfigPath)
@@ -931,6 +1243,11 @@ async function runD1Migrate(config, metaRoot, runner, fmt = "text") {
         // No wrangler config but explicit binding — let wrangler discover the DB itself.
         binding = { binding: config.d1.binding, database_name: "", database_id: "", migrations_dir: undefined };
     }
+    // The binding — and with it wrangler.toml's `migrations_dir` — is only now
+    // known, so this is the earliest point d1 can honestly answer "where will
+    // this run write?" (the caller skipped its own generic check for exactly
+    // this reason; see the guard around that call).
+    warnIfLedgerRelocated(cwd, resolveD1OutDir(config, metaRoot, binding.migrations_dir));
     // 2. Build a D1Runner closure over the wrangler runner.
     const d1Runner = async (sql) => {
         const args = buildWranglerExecuteArgs({
@@ -944,34 +1261,39 @@ async function runD1Migrate(config, metaRoot, runner, fmt = "text") {
     };
     // 3. Load metadata. Best-effort config read for consumer providers; falls
     //    back to default core+forge bundle if metaobjects.config.ts is absent.
-    let d1ConfigProviders;
+    let d1LoadOptions = {};
     try {
-        const forgeConfig = await loadMetaobjectsConfig(metaRoot);
-        d1ConfigProviders = forgeConfig.providers;
+        d1LoadOptions = loadMemoryOptionsFrom(await loadMetaobjectsConfig(genRoot));
     }
     catch {
-        d1ConfigProviders = undefined;
+        d1LoadOptions = {};
+    }
+    // Discovery and load are separate failure modes (the `meta gen` pattern);
+    // `resolveCollection`'s own ERR_COLLECTION_NOT_FOUND replaces the hand-rolled
+    // ENOENT sniff, with the same exit 2.
+    let collection;
+    try {
+        collection = await resolveCollection(metaRoot);
+    }
+    catch (err) {
+        log.error(err.message);
+        return 2;
     }
     let metadata;
     try {
-        metadata = await loadMemory(metaRoot, {
-            ...(d1ConfigProviders !== undefined ? { providers: d1ConfigProviders } : {}),
+        metadata = await loadMemory(collection.configDir, {
+            files: collection.files,
+            ...d1LoadOptions,
         });
     }
     catch (err) {
-        const msg = err.message;
-        if (msg.includes("ENOENT") || msg.includes("no such") || msg.includes("cannot read")) {
-            log.error(`no metaobjects/ found in ${metaRoot}; run 'meta init' to scaffold`);
-        }
-        else {
-            log.error(`migrate: failed to load metadata: ${msg}`);
-        }
+        log.error(`migrate: failed to load metadata: ${err.message}`);
         return 2;
     }
     // 4. Build expected schema + introspect actual.
     let columnNamingStrategy = "snake_case";
     try {
-        const cfg = await loadMetaobjectsConfig(metaRoot);
+        const cfg = await loadMetaobjectsConfig(genRoot);
         if (cfg.columnNamingStrategy)
             columnNamingStrategy = cfg.columnNamingStrategy;
     }
@@ -979,7 +1301,14 @@ async function runD1Migrate(config, metaRoot, runner, fmt = "text") {
         // metaobjects.config.ts absent or invalid — use default snake_case
     }
     const expectedViews = buildProjectionViews(metadata, { dialect: "d1", columnNamingStrategy });
-    const expected = buildExpectedSchema(metadata, { dialect: "d1", columnNamingStrategy, views: expectedViews });
+    const built = buildExpectedSchemaWithProvenance(metadata, { dialect: "d1", columnNamingStrategy, views: expectedViews });
+    const scopeRc = refuseScopeMismatch(collection, () => built.provenance, fmt);
+    if (scopeRc !== undefined)
+        return scopeRc;
+    // Per-command scope — both-sided, exactly as on the Kysely path above.
+    const scoped = scopeExpectedSchema(built, collection.inMigrateScope);
+    const expected = scoped.snapshot;
+    logOutOfScope(scoped.outOfScope, fmt);
     let actual;
     try {
         actual = await introspectD1({
@@ -999,7 +1328,8 @@ async function runD1Migrate(config, metaRoot, runner, fmt = "text") {
     let diffResult;
     try {
         diffResult = await diff({
-            expected,
+            // The three scoped-diff obligations, exactly as on the online path above.
+            ...scopedDiffInputs(scoped, collectUnmanagedNames(metadata)),
             actual,
             // D1 is SQLite at the SQL level — the dialect activates the sqlite diff
             // semantics (structural FK matching: SQLite stores no FK names; CHECK
@@ -1011,8 +1341,6 @@ async function runD1Migrate(config, metaRoot, runner, fmt = "text") {
             // has no expressible migration; refuse loudly instead of emitting SQL that drops
             // the constraint and breaks referencing FKs at apply (same failure as the online path).
             refusePrimaryKeyChange: true,
-            // #208 §7 — declared-@unmanaged objects are external (see the online path above).
-            unmanagedNames: collectUnmanagedNames(metadata),
             onAmbiguous: async (a) => {
                 collectedAmbiguous.push(a);
                 return onAmbiguousResolution;
@@ -1067,11 +1395,9 @@ async function runD1Migrate(config, metaRoot, runner, fmt = "text") {
     }
     const combinedUp = emitResult.up;
     const combinedDown = emitResult.down;
-    // Migration dir resolution: --out-dir > wrangler.toml's migrations_dir > "migrations".
-    // The default outDir (./.metaobjects/migrations) is the Kysely-path default; for D1
-    // we fall back to wrangler conventions when the caller hasn't overridden it.
-    const isDefaultOutDir = config.outDir === MIGRATE_DEFAULT_OUT_DIR;
-    const migrationsDir = resolvePath(metaRoot, isDefaultOutDir ? (binding.migrations_dir ?? "migrations") : config.outDir);
+    // Migration dir resolution — same convention `warnIfLedgerRelocated` was
+    // just given above, so the two cannot drift apart.
+    const migrationsDir = resolveD1OutDir(config, metaRoot, binding.migrations_dir);
     if (config.dryRun) {
         log.info(`-- UP --\n${combinedUp}\n\n-- DOWN --\n${combinedDown}`);
         return 0;