@metaobjectsdev/cli 0.23.2 → 0.24.0

package/dist/src/commands/verify.js

@@ -10,21 +10,22 @@ import { join, resolve as resolvePath } from "node:path";
 import { parseVerifyArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
 import { warnIfAgentContextStale } from "../lib/agent-context-staleness.js";
+import { warnIfManifestIgnored } from "../lib/manifest-ignored-check.js";
 import { scanSourceForAntiPatterns } from "../lib/anti-patterns.js";
 import { FileProvider } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
-import { loadMetaobjectsConfig } from "../lib/load-metaobjects-config.js";
+import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
 import { computeCodegenDrift } from "../lib/codegen-drift.js";
 import { checkRequirements, summariseRequirements } from "../lib/requirement-check.js";
-import { checkVerifiedBy } from "../lib/verified-by-scan.js";
 import { resolveD1Config, resolveMigrateConfig } from "../lib/config.js";
 import { buildWranglerExecuteArgs, defaultWranglerRunner, isWranglerLocalD1StatePath, } from "../lib/wrangler.js";
 import { buildProjectionViews } from "@metaobjectsdev/codegen-ts";
-import { buildKyselyFromUrl } from "../lib/kysely.js";
+import { buildKyselyFromUrl, inferDialect } from "../lib/kysely.js";
 import { tokensToAllowOptions, describeChange } from "../lib/allow.js";
-import { computeDrift, computeDriftFromActual, collectUnmanagedNames, introspect, diff, readSnapshot, snapshotPath, introspectD1, findWranglerConfig, parseWranglerConfig, resolveD1Binding, } from "@metaobjectsdev/migrate-ts";
-import { loadMemory } from "@metaobjectsdev/sdk";
-import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_PROMPT, TEMPLATE_SUBTYPE_OUTPUT, TEMPLATE_ATTR_PAYLOAD_REF, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_REQUIRED_SLOTS, TEMPLATE_ATTR_REQUIRED_TAGS, TEMPLATE_ATTR_KIND, TEMPLATE_KIND_EMAIL, TEMPLATE_KIND_DEFAULT, TEMPLATE_ATTR_SUBJECT_REF, TEMPLATE_ATTR_HTML_BODY_REF, TEMPLATE_ATTR_TEXT_BODY_REF, } from "@metaobjectsdev/metadata";
+import { computeDrift, computeDriftFromActual, collectUnmanagedNames, excludeFromSnapshot, scopedDiffInputs, scopeExpectedSchema, buildExpectedSchemaWithProvenance, applyPending, openReplayEngine, verifyReplay, introspect, diff, readSnapshot, snapshotPath, introspectD1, findWranglerConfig, parseWranglerConfig, resolveD1Binding, } from "@metaobjectsdev/migrate-ts";
+import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
+import { migrateScopeMismatch, outOfScopeNote } from "../lib/migrate-scope.js";
+import { TYPE_TEMPLATE, TEMPLATE_SUBTYPE_PROMPT, TEMPLATE_SUBTYPE_OUTPUT, TEMPLATE_ATTR_PAYLOAD_REF, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_REQUIRED_SLOTS, TEMPLATE_ATTR_REQUIRED_TAGS, TEMPLATE_ATTR_KIND, TEMPLATE_KIND_EMAIL, TEMPLATE_KIND_DEFAULT, TEMPLATE_ATTR_SUBJECT_REF, TEMPLATE_ATTR_HTML_BODY_REF, TEMPLATE_ATTR_TEXT_BODY_REF, REQUIREMENT_STATUSES, } from "@metaobjectsdev/metadata";
 import { verify, ERR_REQUIRED_SLOT_UNUSED, ERR_PARTIAL_UNRESOLVED } from "@metaobjectsdev/render";
 const DEFAULT_PROMPTS_DIR = "prompts";
 // Loader error code (from @metaobjectsdev/metadata's ERROR_CODES) raised by the
@@ -33,9 +34,14 @@ const DEFAULT_PROMPTS_DIR = "prompts";
 const ERR_UNKNOWN_ATTR = "ERR_UNKNOWN_ATTR";
 /**
  * A no-flags MigrateFlags, so `resolveMigrateConfig` yields exactly what `meta migrate`
- * would use with nothing passed on the command line — config value, else default. verify
- * consumes only `outDir` from the result (#292); the other fields exist to satisfy the
- * shared shape, and reading any of them here would be reaching into migrate's decisions.
+ * would use with nothing passed on the command line — config value, else default.
+ *
+ * verify consumes `outDir` (#292) and — for the replay gate ONLY — `dialect`. The #292
+ * restriction that reading anything else "would be reaching into migrate's decisions"
+ * was written about the DRIFT gate, whose dialect comes from the live `--db` URL. The
+ * replay gate has no `--db` at all, and the dialect a committed chain was EMITTED for
+ * is a migrate decision by definition, so migrate's own resolution is the only correct
+ * source for it. Everything else here exists to satisfy the shared shape.
  */
 const EMPTY_MIGRATE_FLAGS = {
     db: undefined, dialect: undefined, format: undefined, outDir: undefined, slug: undefined,
@@ -63,8 +69,6 @@ wranglerRunner) {
         log.error(err.message);
         return 2;
     }
-    // Advisory: nudge to refresh the .claude/skills docs if they predate this CLI.
-    warnIfAgentContextStale(cwd);
     // ADR-0021 D2 — explicit verify subverbs. Each flag selects one drift mode;
     // any combination runs each and the overall exit code is the MAX (non-zero on
     // any drift). A bare `verify` (no explicit subverb) keeps its documented
@@ -76,8 +80,58 @@ wranglerRunner) {
     const runCodegen = flags.codegen;
     if (!flags.anyExplicit) {
         log.info("meta verify — running --templates (default). Explicit subverbs: " +
-            "--templates (prompt drift), --db/--dialect d1 (schema drift), --codegen (codegen drift).");
+            "--templates (prompt drift), --db/--dialect d1 (schema drift), --codegen (codegen drift), " +
+            "--replay/--replay-snapshot (the committed migration chain replays from empty).");
+    }
+    // Where the metadata lives is `resolveCollection`'s decision, not a hardcoded
+    // directory. It also carries the per-command `migrate.scope` the schema gate below
+    // honours — `verify --db` and `migrate` govern the identical object set — and the
+    // top-level `scope` `runCodegenVerify` (a nested function below) threads into
+    // `computeCodegenDrift`. Explicitly typed (unlike the `let collection;` pattern
+    // elsewhere in this codebase): a nested function body is OUTSIDE the control-flow
+    // narrowing TS performs on a same-scope `let x;` reassignment, so a bare
+    // `let collection;` type-checked clean until this task added exactly that nested
+    // reference — the reader who removes the annotation next reintroduces TS7034.
+    let collection;
+    try {
+        collection = await resolveCollection(cwd);
+    }
+    catch (err) {
+        log.error(err.message);
+        return 2;
     }
+    // The project root is whichever directory `resolveCollection` decided the
+    // metadata belongs to (design §4.6.1: "Per-port generator config is then read
+    // from that same directory"). The line this draws, applied throughout this
+    // command: anything named BY the metadata or by `.metaobjects/config.json`
+    // resolves against `projectRoot` — that file's operational block, the migrations
+    // `outDir` and `wranglerConfigPath` it carries, the `prompts/` a `@textRef`
+    // resolves in. Identical paths for a run from the project root.
+    //
+    // The two advisory passes — the agent-context staleness nudge and the
+    // anti-pattern scan — are rooted here too, matching `meta gen`. Both commands
+    // describe them as the same pass, and scanning two different trees for it made
+    // that false: a `verify` run from a subdirectory scanned only that subtree and
+    // found no agent-context manifest at all, so the nudge silently never fired.
+    const projectRoot = collection.configDir;
+    // The one thing NOT named by the metadata or its config: `metaobjects.config.ts`
+    // is this TypeScript package's own answer to a different question (design §4.6),
+    // so it gets its own nearest-ancestor walk and everything IT names follows —
+    // `outDir`/`targets` for `--codegen`. (It also carried `verify.testFiles` until
+    // 0.24.0 retired the `@verifiedBy` scan; both are gone.) In a
+    // Maven- or pip-rooted monorepo the collection is declared at the repo root while
+    // the TS config sits in the app; reading the second from the first made
+    // `--codegen` report "no config" for a package that has one (#326). Identical to
+    // `projectRoot` whenever the two files sit together, which is every `meta init`
+    // project.
+    const genConfigDir = resolveGenConfigDir(cwd, collection.configDir);
+    // Advisory: nudge to refresh the .claude/skills docs if they predate this CLI.
+    warnIfAgentContextStale(projectRoot);
+    // Advisory: the committed hash manifest is what makes hand-edit detection work on a
+    // machine that did not generate the output. Silent unless it is ignored. Keyed on
+    // projectRoot, not cwd, for the same reason its neighbour is — the manifest belongs to
+    // whichever directory `resolveCollection` decided the metadata lives in.
+    warnIfManifestIgnored(projectRoot);
     // Best-effort load of metaobjects.config.ts. Two consumers:
     //  1) consumer-supplied providers (e.g. a `template.toolcall` subtype) threaded
     //     into loadMemory — verify doesn't REQUIRE codegen config for templates/db;
@@ -86,27 +140,27 @@ wranglerRunner) {
     // error (it can't diff without knowing where the committed output lives).
     let forgeConfig;
     try {
-        forgeConfig = await loadMetaobjectsConfig(cwd);
+        forgeConfig = await loadMetaobjectsConfig(genConfigDir);
     }
     catch {
         forgeConfig = undefined;
     }
-    const configProviders = forgeConfig?.providers;
+    // Both of the gen config's contributions to the load, together — see
+    // `loadMemoryOptionsFrom`. Threading `providers` and forgetting `libraries` is how
+    // a shipped library became unloadable through the CLI (#333).
+    const configLoadOptions = loadMemoryOptionsFrom(forgeConfig);
     // ADR-0023 strict-by-default (#96): verify loads strict unless --lax is passed,
     // so an undeclared/typo'd own @attr fails verify (matching Java's Maven goal).
     let root;
     try {
-        root = await loadMemory(cwd, {
-            ...(configProviders !== undefined ? { providers: configProviders } : {}),
+        root = await loadMemory(collection.configDir, {
+            files: collection.files,
+            ...configLoadOptions,
             strict: !flags.lax,
         });
     }
     catch (err) {
         const msg = err.message;
-        if (msg.includes("ENOENT") || msg.includes("no such") || msg.includes("cannot read")) {
-            log.error(`no metaobjects/ found in ${cwd}; run 'meta init' to scaffold`);
-            return 2;
-        }
         log.error(`failed to load metadata: ${msg}`);
         // Strict-load rejection (ADR-0023): give the author the three exits — register
         // the attr on a provider, stash it in the `attr.properties` bag, or pass --lax.
@@ -119,7 +173,12 @@ wranglerRunner) {
         }
         return 1;
     }
-    const promptsDir = join(cwd, flags.prompts ?? DEFAULT_PROMPTS_DIR);
+    // The schema gate governs exactly the objects `meta migrate` governs — ONE
+    // declaration (`migrate.scope`), not a second key: a drift gate that fails on
+    // tables migrate deliberately does not own is incoherent. Undefined ⇒ everything
+    // loaded, which is every project that declares no scope.
+    const schemaScope = collection.inMigrateScope;
+    const promptsDir = join(projectRoot, flags.prompts ?? DEFAULT_PROMPTS_DIR);
     const provider = new FileProvider(promptsDir);
     // Exit-code composition: the overall result is the MAX across every selected
     // subverb so ANY kind of drift fails CI. Each gate only runs when its mode is
@@ -131,36 +190,211 @@ wranglerRunner) {
     // are checked on every `meta verify`. Opt-in by DECLARATION — a model with no
     // requirement nodes is silent, not in drift.
     const requirementExit = runRequirementVerify();
+    // #313 — BOTH replay flags select this gate. `--replay-snapshot` implies
+    // `--replay`'s work, so a broken chain must fail under it even when `--replay`
+    // was not passed; naming only `flags.replay` here is how `--replay-snapshot`
+    // would parse cleanly and do nothing at all.
+    const replayExit = flags.replay || flags.replaySnapshot ? await runReplayVerify() : 0;
     // Advisory verify-as-teacher pass: surface hand-rolled work the metadata could
     // model. Warnings ONLY — never changes the exit code (bias to under-flagging).
     // Suppressed with --no-antipatterns or META_NO_ANTIPATTERNS=1 for the rare
     // noisy project (both opt-outs work on `meta verify` and `meta gen`).
     if (!flags.noAntipatterns && process.env.META_NO_ANTIPATTERNS !== "1")
         runAntiPatternAdvisory();
-    return Math.max(templateExit, schemaExit, codegenExit, requirementExit);
+    return Math.max(templateExit, schemaExit, codegenExit, requirementExit, replayExit);
+    // -- replay (#313) ---------------------------------------------------------
+    /**
+     * Replay the committed migration chain into an EMPTY throwaway database and assert
+     * it applies. `--replay-snapshot` additionally asserts the result equals the
+     * committed snapshot.
+     *
+     * This exists because `meta migrate` could write a chain that cannot be replayed —
+     * a bare `DROP TABLE "x"` for an object no migration ever created — and nothing
+     * noticed until someone tried to provision a fresh database, which for the reporter
+     * was three months later. The two tiers are separate because a project adopted via
+     * `migrate baseline --from-db` passes the first trivially and CANNOT pass the second
+     * by construction: its snapshot is the whole introspected database and its chain is
+     * empty.
+     *
+     * Exit codes follow verify's convention: a chain that fails to apply, or a snapshot
+     * mismatch, is drift → 1; an engine that will not start is operational → 2.
+     */
+    async function runReplayVerify() {
+        // Resolve the migrations directory and the chain's dialect through MIGRATE's own
+        // precedence, never a second derivation — verify must not look somewhere migrate
+        // does not write, nor assume a dialect the chain was not emitted for.
+        const migrateConfig = await resolveMigrateConfig(EMPTY_MIGRATE_FLAGS, projectRoot);
+        if (migrateConfig.format === "flyway") {
+            log.error(`meta verify --replay is not supported with --migration-format flyway — run 'flyway migrate' against a scratch database to replay`);
+            return 2;
+        }
+        // --dialect wins; else migrate's resolved dialect; else refuse. There is no --db
+        // to infer from, so guessing would replay a postgres chain through sqlite.
+        const dialect = flags.dialect ?? migrateConfig.dialect;
+        if (dialect === undefined) {
+            log.error(`meta verify --replay: no dialect — pass --dialect <postgres|sqlite>, or set migrate.dialect in .metaobjects/config.json`);
+            return 2;
+        }
+        if (dialect === "d1") {
+            log.error(`meta verify --replay is not supported for dialect 'd1' — use 'wrangler d1 migrations apply' against a scratch database to replay committed migrations`);
+            return 2;
+        }
+        const dir = resolvePath(projectRoot, migrateConfig.outDir);
+        let engine;
+        try {
+            engine = await openReplayEngine(dialect);
+        }
+        catch (err) {
+            // A missing optional driver lands here, and its message already carries the
+            // install hint. Operational, not drift.
+            log.error(`meta verify --replay: ${err.message}`);
+            return 2;
+        }
+        try {
+            let applied;
+            try {
+                applied = await applyPending(engine.db, dir, { dryRun: false, dialect });
+            }
+            catch (err) {
+                log.error(`meta verify --replay: ${err.message}`);
+                log.error(`meta verify --replay: the committed chain does not apply to an empty database. ` +
+                    `Applied migrations are immutable, so fix this with a NEW migration that creates the ` +
+                    `missing object — not by editing a committed up.sql.`);
+                return 1;
+            }
+            // Not a silent pass. `discoverMigrations` returns [] for a missing directory, so
+            // a run over an empty chain would otherwise "succeed" having proved nothing —
+            // and a gate that is quiet when it checked nothing cannot be told from one that
+            // passed. Every migration is pending against a fresh engine, so an empty
+            // `pending` means the directory held none.
+            //
+            // This return is for TIER 1 ONLY: an empty chain trivially "applies" (there is
+            // nothing that could fail), so tier 1 is done. Tier 2 is NOT done — its job is
+            // "does the replay reproduce the committed snapshot?", and a wrong
+            // `migrate.outDir` or a project adopted via `migrate baseline --from-db` (whose
+            // own chain is empty by construction) both look identical to this point. Return
+            // ONLY when `--replay-snapshot` was not requested; otherwise fall through so an
+            // empty replay is still compared against a snapshot that may record dozens of
+            // tables, rather than reporting success having compared nothing.
+            if (applied.pending.length === 0) {
+                log.info(`meta verify --replay: no committed migrations — nothing to replay`);
+                if (!flags.replaySnapshot)
+                    return 0;
+            }
+            else {
+                log.info(`meta verify --replay — the committed chain applies to an empty ${dialect} database ` +
+                    `(${applied.applied.length} migration(s)).`);
+            }
+            if (!flags.replaySnapshot)
+                return 0;
+            return await runReplaySnapshotTier(engine, dialect, dir);
+        }
+        finally {
+            await engine.dispose();
+        }
+    }
+    /**
+     * The second tier: the replayed schema must EQUAL the committed snapshot.
+     *
+     * This is the 2026-05-31 §8 integrity aid, finally wired — `verifyReplay` has been
+     * built and exported with no CLI caller since then. What it catches that tier 1
+     * cannot is hand-edited structural DDL: a committed up.sql someone changed so the
+     * chain still applies but no longer produces the schema the snapshot records.
+     *
+     * It does NOT support a project adopted via `migrate baseline --from-db`, and does
+     * not try to detect one. The only candidate signal (`BASELINE_NAME`/`recordBaseline`)
+     * has no production caller and would live in the TARGET database's ledger, while
+     * this runs against a fresh engine with no ledger at all. So the failure message
+     * names baseline adoption as the first thing to rule out.
+     */
+    async function runReplaySnapshotTier(engine, dialect, dir) {
+        // Fails OPEN on a missing snapshot: a project that has never generated one
+        // offline is not in an error state, and an unreadable/unparseable file is
+        // migrate's error to raise with its own message, not a drift verdict. It still
+        // SAYS so — silence here would be indistinguishable from a pass.
+        let snapshot;
+        try {
+            snapshot = await readSnapshot(snapshotPath(dir, dialect));
+        }
+        catch {
+            log.info(`meta verify --replay-snapshot: the committed snapshot could not be read — nothing to compare`);
+            return 0;
+        }
+        if (snapshot === null) {
+            log.info(`meta verify --replay-snapshot: no committed snapshot — nothing to compare`);
+            return 0;
+        }
+        // A scoped project carries the OTHER owner's tables into its snapshot on purpose
+        // and its chain never creates them, so they must leave the comparison. The
+        // committed snapshot alone cannot be scoped — `scopeExpectedSchema` decides on a
+        // qualified-name → metadata-FQN provenance map the snapshot does not carry — so
+        // the expected side is rebuilt from metadata purely to derive that decision.
+        //
+        // Only for a project that actually declares `migrate.scope`. An unscoped project
+        // passes no `governed` and gets the comparison exactly as it was.
+        let governed;
+        if (schemaScope !== undefined) {
+            const viewStrategy = forgeConfig?.columnNamingStrategy ?? "snake_case";
+            const built = buildExpectedSchemaWithProvenance(root, {
+                dialect,
+                columnNamingStrategy: viewStrategy,
+                views: buildProjectionViews(root, { dialect, columnNamingStrategy: viewStrategy }),
+            });
+            governed = scopeExpectedSchema(built, schemaScope);
+        }
+        // `verifyReplay` calls `applyPending` itself. That is NOT a second replay: the
+        // first one recorded every migration in this engine's ledger, so the call finds
+        // nothing pending and returns immediately.
+        const result = await verifyReplay({
+            db: engine.db,
+            dialect,
+            migrationsDir: dir,
+            snapshot,
+            ...(governed !== undefined ? { governed } : {}),
+        });
+        if (result.ok) {
+            log.info(`meta verify --replay-snapshot — the replayed chain reproduces the committed snapshot.`);
+            return 0;
+        }
+        log.error(`meta verify --replay-snapshot: the replayed chain does not reproduce the committed snapshot. ` +
+            `If this project was adopted with 'migrate baseline --from-db', its chain does not build the ` +
+            `schema and this tier does not apply — use --replay instead.`);
+        for (const line of summarizeDrift([...result.drift, ...result.unmanaged]))
+            log.error(`  ${line}`);
+        return 1;
+    }
     // -- requirements (#290) ---------------------------------------------------
     function runRequirementVerify() {
-        // `@verifiedBy` resolution needs the project on disk, so it is a separate
-        // scan; its diagnostics carry the same severities and share this reporter.
-        // `verify.testFiles` lets a project name its own test-file conventions. What counts
-        // as a test is project-specific, and the built-in patterns are a convenience, not an
-        // authority — see the verified-by-scan header.
-        const diags = [
-            ...checkRequirements(root),
-            ...checkVerifiedBy(root, cwd, forgeConfig?.verify?.testFiles),
-        ];
+        // No test-corpus scan runs here any more. `@verifiedBy` asked the author to
+        // name a test and checked only that the NAME occurred somewhere in the test
+        // sources — an audit of one real 19-name ledger found 4 names that did not
+        // verify their claim (a comment, a DI key, a test of a different claim, a
+        // test of the output where the claim was about the source text) while verify
+        // reported zero errors throughout. Existence was never proof, and no lexical
+        // rule reaches the semantic cases. FR-038 retires the attribute rather than
+        // narrowing it; the replacement generates the test FROM the requirement, so
+        // the link is structural instead of a string the author picks.
+        const diags = [...checkRequirements(root)];
         // Printed on EVERY run, clean or not — a gate that says nothing when it
         // passes cannot be told apart from a gate that checked nothing, and the
         // recorded-gap counts are the whole reason to keep a ledger.
         const s = summariseRequirements(root);
         if (s !== undefined) {
-            const order = ["planned", "live", "partial", "abandoned", "superseded"];
+            const order = [...REQUIREMENT_STATUSES];
             const parts = order
                 .filter((k) => (s.byStatus[k] ?? 0) > 0)
                 .map((k) => `${s.byStatus[k]} ${k}`);
+            // The file count is the DENOMINATOR'S PROVENANCE, and it is here because
+            // `entitiesTotal` is only ever computed over what actually loaded. A spine that
+            // covers half an estate reports the covered half as fully claimed — an adopter
+            // found `76/76` while two of their four metadata trees were not in `sources` at
+            // all, which is why nothing had ever flagged the templates living in them. No
+            // check can see a tree it was never pointed at, so the honest fix is to publish
+            // what the count was taken over and let a wrong number be noticeable.
             log.info(`meta verify — requirements: ${s.total} entries (${s.functional} functional, ` +
                 `${s.architectural} architectural) — ${parts.join(", ")}; ` +
-                `${s.entitiesClaimed}/${s.entitiesTotal} entities claimed.`);
+                `${s.entitiesClaimed}/${s.entitiesTotal} entities claimed, ` +
+                `counted over ${collection.files.length} metadata file(s).`);
             if (s.undecided > 0) {
                 log.info(`meta verify — requirements: ${s.undecided} recorded gap(s) with no @disposition. ` +
                     `These are known problems nobody has ruled on — set 'accepted' or 'deferred' to close the question.`);
@@ -188,7 +422,7 @@ wranglerRunner) {
     function runAntiPatternAdvisory() {
         let findings;
         try {
-            findings = scanSourceForAntiPatterns(cwd);
+            findings = scanSourceForAntiPatterns(projectRoot);
         }
         catch {
             return; // never let an advisory scan break verify
@@ -316,6 +550,25 @@ wranglerRunner) {
         const usingD1 = flags.dialect === "d1";
         if ((flags.db === undefined && !usingD1) || flags.skipSchema)
             return 0;
+        // A `migrate.scope` matching nothing it could govern is refused, not tolerated —
+        // it would make this gate compare zero objects and report "in sync" (see
+        // `migrateScopeMismatch`). Checked HERE rather than beside the other collection
+        // work at the top of `verifyCommand`, because `migrate.scope` governs only the
+        // schema gate: a stale pattern must not fail a `--templates` run that never
+        // consults it.
+        const scopeMismatch = migrateScopeMismatch(collection, () => {
+            const dialect = usingD1 ? "d1" : (flags.dialect ?? inferDialect(flags.db));
+            const viewStrategy = forgeConfig?.columnNamingStrategy ?? "snake_case";
+            return buildExpectedSchemaWithProvenance(root, {
+                dialect,
+                columnNamingStrategy: viewStrategy,
+                views: buildProjectionViews(root, { dialect, columnNamingStrategy: viewStrategy }),
+            }).provenance;
+        });
+        if (scopeMismatch !== undefined) {
+            log.error(`verify: ${scopeMismatch}`);
+            return 2;
+        }
         if (usingD1 && flags.db !== undefined) {
             log.error(`verify: --db is not used for dialect 'd1' — wrangler.toml owns the connection; pass --d1 <binding> instead`);
             return 2;
@@ -361,14 +614,18 @@ wranglerRunner) {
                 // `actual` this drift comparison uses, and re-introspecting for it would both
                 // cost a second round trip and open a window where the two could disagree.
                 actual = await introspect(kysely.db, kysely.dialect);
-                driftResult = await computeDriftFromActual(actual, kysely.dialect, root, { allow, views: expectedViews });
+                driftResult = await computeDriftFromActual(actual, kysely.dialect, root, {
+                    allow,
+                    views: expectedViews,
+                    ...(schemaScope !== undefined ? { inScope: schemaScope } : {}),
+                });
             }
             catch (err) {
                 log.error(`verify: failed to introspect ${kysely.displayUrl}: ${err.message}`);
                 return 1;
             }
             const snapshotDrift = driftResult.changes.length === 0
-                ? await checkCommittedSnapshot(actual, kysely.dialect, kysely.displayUrl)
+                ? await checkCommittedSnapshot(actual, kysely.dialect, kysely.displayUrl, driftResult)
                 : [];
             return reportSchemaDrift(driftResult, [...ledgerDrift, ...snapshotDrift], kysely.displayUrl);
         }
@@ -392,12 +649,12 @@ wranglerRunner) {
     // computeDriftFromActual and the SAME reportSchemaDrift the sqlite/postgres
     // path uses — no forked reporting/exit-code logic.
     async function runD1SchemaVerify(ledgerDrift) {
-        const d1Config = await resolveD1Config({ d1Binding: flags.d1, remote: flags.remote }, cwd);
+        const d1Config = await resolveD1Config({ d1Binding: flags.d1, remote: flags.remote }, projectRoot);
         const wranglerConfigPath = d1Config.wranglerConfigPath
-            ? resolvePath(cwd, d1Config.wranglerConfigPath)
-            : findWranglerConfig(cwd);
+            ? resolvePath(projectRoot, d1Config.wranglerConfigPath)
+            : findWranglerConfig(projectRoot);
         if (wranglerConfigPath === undefined && d1Config.binding === undefined) {
-            log.error(`verify: no wrangler.toml found in ${cwd} or parents; pass --d1 <binding> to bypass`);
+            log.error(`verify: no wrangler.toml found in ${projectRoot} or parents; pass --d1 <binding> to bypass`);
             return 2;
         }
         let binding;
@@ -423,7 +680,7 @@ wranglerRunner) {
                 command: sql,
                 configPath: wranglerConfigPath,
             });
-            const { stdout } = await activeWranglerRunner(wranglerArgs, cwd);
+            const { stdout } = await activeWranglerRunner(wranglerArgs, projectRoot);
             return stdout;
         };
         let actual;
@@ -439,7 +696,11 @@ wranglerRunner) {
         const expectedViews = buildProjectionViews(root, { dialect: "d1", columnNamingStrategy: viewStrategy });
         let driftResult;
         try {
-            driftResult = await computeDriftFromActual(actual, "d1", root, { allow, views: expectedViews });
+            driftResult = await computeDriftFromActual(actual, "d1", root, {
+                allow,
+                views: expectedViews,
+                ...(schemaScope !== undefined ? { inScope: schemaScope } : {}),
+            });
         }
         catch (err) {
             log.error(`verify: ${err.message}`);
@@ -478,15 +739,15 @@ wranglerRunner) {
     // Fails OPEN when there is no snapshot on disk (a project that has never generated one
     // offline is not in an error state) and when the file cannot be read or parsed (that is
     // migrate's error to raise, with its own message, not a drift verdict).
-    async function checkCommittedSnapshot(actual, dialect, displayUrl) {
+    async function checkCommittedSnapshot(actual, dialect, displayUrl, governed) {
         if (dialect === "d1")
             return []; // d1 keeps migrations Wrangler-native; no offline snapshot
         // Resolve the migrations dir through migrate's OWN precedence (flag > config >
         // default) rather than re-deriving it, so verify can never look somewhere migrate
         // does not write. Only `outDir` is consumed; the rest of the resolved config is
         // migrate's business.
-        const migrateConfig = await resolveMigrateConfig(EMPTY_MIGRATE_FLAGS, cwd);
-        const dir = resolvePath(cwd, migrateConfig.outDir);
+        const migrateConfig = await resolveMigrateConfig(EMPTY_MIGRATE_FLAGS, projectRoot);
+        const dir = resolvePath(projectRoot, migrateConfig.outDir);
         let snapshot;
         try {
             snapshot = await readSnapshot(snapshotPath(dir, dialect));
@@ -496,11 +757,28 @@ wranglerRunner) {
         }
         if (snapshot === null)
             return [];
+        // Out-of-scope objects leave BOTH sides of this comparison, and the schema pin
+        // comes from the scope decision the DRIFT comparison already made — one door
+        // (migrate-ts's `excludeFromSnapshot` + `scopedDiffInputs`), not a fifth
+        // hand-rolled copy of the three-part contract. `unmanagedNames` suppresses the
+        // actual side only, which is right for the metadata↔DB diff (its expected side
+        // is already scoped) but not here: the committed snapshot IS the expected side,
+        // and a snapshot written before the scope was declared still carries the other
+        // owner's tables. Re-deriving the pin from the snapshot is what left an empty
+        // (never-migrated) snapshot reaching `diff`'s whole-database fallback.
         const result = await diff({
-            expected: snapshot,
+            ...scopedDiffInputs(excludeFromSnapshot(snapshot, governed), collectUnmanagedNames(root)),
             actual,
             allow: {},
-            unmanagedNames: collectUnmanagedNames(root),
+            // #297 — the SAME pipeline `meta migrate` runs, or this gate answers a different
+            // question than the one it reports on. `DiffArgs.dialect` is optional, so omitting
+            // it was silently accepted: views fell through to comparing our emitted body
+            // against the deparser's (never equal, so permanent drift on Postgres), CHECK
+            // constraints were skipped entirely, and SQLite type canonicalization no-opped.
+            //
+            // Note `unmanagedNames` is NOT restated here: `scopedDiffInputs` above supplies it
+            // MERGED with the out-of-scope set, and a second key would silently drop that half.
+            dialect,
         });
         if (result.changes.length === 0)
             return [];
@@ -519,6 +797,12 @@ wranglerRunner) {
         if (externalDeclared.length > 0) {
             log.info(`meta verify — ${externalDeclared.length} object(s) external (declared @unmanaged, managed elsewhere): ${externalDeclared.join(", ")}`);
         }
+        // Same reasoning for the per-command scope: an object `migrate.scope` excluded
+        // was NOT checked, and silence would misreport it as checked-and-clean. Shared
+        // wording with `meta migrate` — one declaration, one sentence about it.
+        if (driftResult.outOfScope.length > 0) {
+            log.info(outOfScopeNote("verify", driftResult.outOfScope));
+        }
         const changes = driftResult.changes;
         if (changes.length === 0 && ledgerDrift.length === 0) {
             log.info(`meta verify — schema in sync with ${displayUrl}.`);
@@ -548,9 +832,13 @@ wranglerRunner) {
                 "Run 'meta init' to scaffold one, or run without --codegen.");
             return 2;
         }
+        // The identical predicate `meta gen` applies (Task 12b / design §7 open
+        // question 3) — a `gen` that committed under a narrowed scope and a
+        // `verify --codegen` that regenerates unscoped would disagree about which
+        // files should exist, reporting every out-of-scope entity as drift.
         let result;
         try {
-            result = await computeCodegenDrift(forgeConfig, root, cwd);
+            result = await computeCodegenDrift(forgeConfig, root, genConfigDir, collection.inScope);
         }
         catch (err) {
             log.error(`verify --codegen: regeneration failed: ${err.message}`);