@metaobjectsdev/cli 0.23.2 → 0.24.0

package/src/commands/migrate.ts

@@ -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";
@@ -10,13 +11,17 @@ import type { OutputFormat } from "../lib/format.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 { loadMemory, resolveCollection, resolveConfigDir, type Collection } from "@metaobjectsdev/sdk";
+import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { migrateScopeMismatch, outOfScopeNote } from "../lib/migrate-scope.js";
 import {
-  buildExpectedSchema,
+  buildExpectedSchemaWithProvenance,
+  scopeExpectedSchema,
+  scopedDiffInputs,
   introspect,
   diff,
   collectUnmanagedNames,
+  carryForwardOutOfScope,
   emit,
   writeMigration,
   baselineFromMetadata,
@@ -24,6 +29,7 @@ import {
   snapshotPath,
   readSnapshot,
   writeSnapshot,
+  qualifiedDbName,
   BlockedChangesError,
   PrimaryKeyChangeError,
   renderD1,
@@ -41,6 +47,9 @@ import {
   type D1Binding,
   type EmitResult,
   type D1Runner,
+  type SchemaProvenance,
+  type SchemaSnapshot,
+  type TableDescriptor,
 } from "@metaobjectsdev/migrate-ts";
 import {
   buildWranglerExecuteArgs,
@@ -60,8 +69,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)
@@ -81,7 +93,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
@@ -122,6 +140,74 @@ function resolveFormatOutDir(config: ResolvedMigrateConfig, metaRoot: string): s
   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: ResolvedMigrateConfig,
+  metaRoot: string,
+  migrationsDirHint: string | undefined,
+): string {
+  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: string, resolvedOutDir: string): void {
+  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: readonly string[], fmt: OutputFormat): void {
+  if (names.length === 0) return;
+  const msg = outOfScopeNote("migrate", names);
+  if (fmt === "text") log.info(msg);
+  else log.warn(msg);
+}
+
 function emitStructuredError(error: string, hint: string, fmt: OutputFormat): void {
   const payload = { error, hint };
   if (fmt === "json") {
@@ -132,6 +218,27 @@ function emitStructuredError(error: string, hint: string, fmt: OutputFormat): vo
   // 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: Collection,
+  provenance: () => SchemaProvenance,
+  fmt: OutputFormat,
+): number | undefined {
+  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
@@ -196,6 +303,71 @@ function summarizeChanges(changes: Change[]): Record<string, number> {
   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: Change[], snapPath: string): Promise<string[]> {
+  let snapshot: SchemaSnapshot | null;
+  try {
+    snapshot = await readSnapshot(snapPath);
+  } catch {
+    return [];
+  }
+  if (snapshot === null) return [];
+
+  const managedTables = new Map<string, TableDescriptor>();
+  for (const t of snapshot.tables) managedTables.set(qualifiedDbName(t), t);
+  const managedViews = new Set<string>();
+  for (const v of snapshot.views) managedViews.add(qualifiedDbName(v));
+
+  const absent: string[] = [];
+  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: string): string {
   switch (kind) {
     case "drop-column": return "drop-column";
@@ -257,8 +429,56 @@ export async function migrateCommand(
     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
@@ -341,12 +561,12 @@ export async function migrateCommand(
       );
       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.
@@ -358,7 +578,7 @@ export async function migrateCommand(
   // 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) {
@@ -381,26 +601,34 @@ export async function migrateCommand(
   // 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: readonly import("@metaobjectsdev/codegen-ts").MetaDataTypeProvider[] | undefined;
+  let postgresLoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
   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 as Error).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 as Error).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 as Error).message}`);
     return 2;
   }
 
@@ -425,7 +653,7 @@ export async function migrateCommand(
     // and projection view DDL — derive it once, up front, so every view path agrees.
     let columnNamingStrategy: "snake_case" | "literal" | "kebab-case" = "snake_case";
     try {
-      const cfg = await loadMetaobjectsConfig(metaRoot);
+      const cfg = await loadMetaobjectsConfig(genRoot);
       if (cfg.columnNamingStrategy) columnNamingStrategy = cfg.columnNamingStrategy;
     } catch {
       // metaobjects.config.ts absent or invalid — use default snake_case
@@ -435,11 +663,20 @@ export async function migrateCommand(
     // 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);
@@ -455,7 +692,12 @@ export async function migrateCommand(
     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),
@@ -463,9 +705,6 @@ export async function migrateCommand(
         // 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;
@@ -507,6 +746,44 @@ export async function migrateCommand(
 
     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;
@@ -610,9 +887,25 @@ export async function migrateCommand(
     // native ALTER vs recreate-and-copy on older SQLite.
     if (!config.dryRun && exitCode === 0 && !applyFailed && writtenPaths.length > 0) {
       try {
+        // 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 ? { ...expected, meta: actual.meta } : expected,
+          actual.meta !== undefined ? { ...committed, meta: actual.meta } : committed,
         );
       } catch (err) {
         // The migration itself is written (and possibly applied) — report the
@@ -676,6 +969,10 @@ export async function runBaseline(
   config: ResolvedMigrateConfig,
   metaRoot: string,
   fmt: OutputFormat = "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: string = metaRoot,
 ): Promise<number> {
   if (config.dialect === undefined) {
     log.error(`migrate baseline: --dialect required (or set migrate.dialect in .metaobjects/config.json)`);
@@ -731,23 +1028,32 @@ export async function runBaseline(
       `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:
-      | readonly import("@metaobjectsdev/codegen-ts").MetaDataTypeProvider[]
-      | undefined;
+    let baselineLoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
     let baselineStrategy: "snake_case" | "literal" | "kebab-case" = "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) {
       log.error(`migrate baseline: failed to load metadata: ${(err as Error).message}`);
@@ -859,36 +1165,53 @@ export async function runOfflineGenerate(
   config: ResolvedMigrateConfig,
   metaRoot: string,
   fmt: OutputFormat = "text",
+  /** Directory whose `metaobjects.config.ts` governs — see `migrateCommand`'s
+   *  `genRoot`. Defaults to `metaRoot`, the co-located case. */
+  genRoot: string = metaRoot,
 ): Promise<number> {
   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:
-    | readonly import("@metaobjectsdev/codegen-ts").MetaDataTypeProvider[]
-    | undefined;
+  let offlineLoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
   let offlineStrategy: "snake_case" | "literal" | "kebab-case" = "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 as Error).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;
@@ -916,7 +1239,7 @@ export async function runOfflineGenerate(
   const collectedAmbiguous: AmbiguousChange[] = [];
   const onAmbiguousResolution = mapOnAmbiguous(config.onAmbiguous);
 
-  const offlineViews = buildProjectionViews(metadata, { dialect: config.dialect, columnNamingStrategy: offlineStrategy });
+  const offlineScope = collection.inMigrateScope;
 
   let plan;
   try {
@@ -926,6 +1249,8 @@ export async function runOfflineGenerate(
       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);
@@ -946,7 +1271,11 @@ export async function runOfflineGenerate(
     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>`);
@@ -963,7 +1292,7 @@ export async function runOfflineGenerate(
 
   const emitResult = emit(diffResult.changes, {
     dialect: config.dialect,
-    expectedSchema: nextSnapshot,
+    expectedSchema: governedExpected,
     actualSchema: snapshot,
     ...(snapshot.meta ? { actualMeta: snapshot.meta } : {}),
   });
@@ -1052,9 +1381,16 @@ async function runRollback(
 async function runD1Migrate(
   config: ResolvedMigrateConfig,
   metaRoot: string,
+  cwd: string,
   runner: WranglerRunner,
   fmt: OutputFormat = "text",
 ): Promise<number> {
+  // 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)
@@ -1079,6 +1415,12 @@ async function runD1Migrate(
     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: D1Runner = async (sql) => {
     const args = buildWranglerExecuteArgs({
@@ -1093,39 +1435,51 @@ async function runD1Migrate(
 
   // 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: readonly import("@metaobjectsdev/codegen-ts").MetaDataTypeProvider[] | undefined;
+  let d1LoadOptions: ReturnType<typeof loadMemoryOptionsFrom> = {};
   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 as Error).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 as Error).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 as Error).message}`);
     return 2;
   }
 
   // 4. Build expected schema + introspect actual.
   let columnNamingStrategy: "snake_case" | "literal" | "kebab-case" = "snake_case";
   try {
-    const cfg = await loadMetaobjectsConfig(metaRoot);
+    const cfg = await loadMetaobjectsConfig(genRoot);
     if (cfg.columnNamingStrategy) columnNamingStrategy = cfg.columnNamingStrategy;
   } catch {
     // 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({
@@ -1145,7 +1499,8 @@ async function runD1Migrate(
   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
@@ -1157,8 +1512,6 @@ async function runD1Migrate(
       // 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;
@@ -1217,14 +1570,9 @@ async function runD1Migrate(
   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}`);