@metaobjectsdev/cli 0.23.2 → 0.24.0

package/src/commands/verify.ts

@@ -11,13 +11,13 @@ import { join, resolve as resolvePath } from "node:path";
 import { parseVerifyArgs, type MigrateFlags } 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,
@@ -27,12 +27,22 @@ import {
 } from "../lib/wrangler.js";
 import type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 import { buildProjectionViews } from "@metaobjectsdev/codegen-ts";
-import { buildKyselyFromUrl, type Dialect } from "../lib/kysely.js";
+import { buildKyselyFromUrl, inferDialect, type Dialect } from "../lib/kysely.js";
 import { tokensToAllowOptions, describeChange } from "../lib/allow.js";
 import {
   computeDrift,
   computeDriftFromActual,
   collectUnmanagedNames,
+  excludeFromSnapshot,
+  scopedDiffInputs,
+  scopeExpectedSchema,
+  buildExpectedSchemaWithProvenance,
+  type GovernedScope,
+  applyPending,
+  type ApplyPendingResult,
+  openReplayEngine,
+  type ReplayEngine,
+  verifyReplay,
   introspect,
   diff,
   readSnapshot,
@@ -45,9 +55,10 @@ import {
   type Change,
   type D1Binding,
   type D1Runner,
-  type DiffResult,
+  type DriftResult,
 } from "@metaobjectsdev/migrate-ts";
-import { loadMemory } from "@metaobjectsdev/sdk";
+import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
+import { migrateScopeMismatch, outOfScopeNote } from "../lib/migrate-scope.js";
 import {
   TYPE_TEMPLATE,
   TEMPLATE_SUBTYPE_PROMPT,
@@ -62,6 +73,7 @@ import {
   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";
 
@@ -74,9 +86,14 @@ 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,
@@ -107,9 +124,6 @@ export async function verifyCommand(
     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
@@ -122,10 +136,63 @@ export async function verifyCommand(
   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: Awaited<ReturnType<typeof resolveCollection>>;
+  try {
+    collection = await resolveCollection(cwd);
+  } catch (err) {
+    log.error((err as Error).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;
@@ -134,26 +201,26 @@ export async function verifyCommand(
   // error (it can't diff without knowing where the committed output lives).
   let forgeConfig: MetaobjectsGenConfig | undefined;
   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: Awaited<ReturnType<typeof loadMemory>>;
   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 as Error).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.
@@ -169,7 +236,13 @@ export async function verifyCommand(
     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
@@ -182,6 +255,11 @@ export async function verifyCommand(
   // 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).
@@ -189,33 +267,223 @@ export async function verifyCommand(
   // 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(): Promise<number> {
+    // 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: Dialect | undefined = 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: ReplayEngine;
+    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 as Error).message}`);
+      return 2;
+    }
+
+    try {
+      let applied: ApplyPendingResult;
+      try {
+        applied = await applyPending(engine.db, dir, { dryRun: false, dialect });
+      } catch (err) {
+        log.error(`meta verify --replay: ${(err as Error).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: ReplayEngine,
+    dialect: Extract<Dialect, "postgres" | "sqlite">,
+    dir: string,
+  ): Promise<number> {
+    // 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: SchemaSnapshot | null;
+    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: GovernedScope | undefined;
+    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(): number {
-    // `@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(
@@ -245,7 +513,7 @@ export async function verifyCommand(
   function runAntiPatternAdvisory(): void {
     let findings;
     try {
-      findings = scanSourceForAntiPatterns(cwd);
+      findings = scanSourceForAntiPatterns(projectRoot);
     } catch {
       return; // never let an advisory scan break verify
     }
@@ -378,6 +646,26 @@ export async function verifyCommand(
     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: Dialect = usingD1 ? "d1" : (flags.dialect ?? inferDialect(flags.db as string));
+      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;
@@ -428,7 +716,11 @@ export async function verifyCommand(
         // `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 as Error).message}`);
         return 1;
@@ -436,7 +728,7 @@ export async function verifyCommand(
 
       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);
@@ -460,14 +752,14 @@ export async function verifyCommand(
   // computeDriftFromActual and the SAME reportSchemaDrift the sqlite/postgres
   // path uses — no forked reporting/exit-code logic.
   async function runD1SchemaVerify(ledgerDrift: string[]): Promise<number> {
-    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;
     }
 
@@ -493,7 +785,7 @@ export async function verifyCommand(
         command: sql,
         configPath: wranglerConfigPath,
       });
-      const { stdout } = await activeWranglerRunner(wranglerArgs, cwd);
+      const { stdout } = await activeWranglerRunner(wranglerArgs, projectRoot);
       return stdout;
     };
 
@@ -510,7 +802,11 @@ export async function verifyCommand(
     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 as Error).message}`);
       return 1;
@@ -554,14 +850,15 @@ export async function verifyCommand(
     actual: SchemaSnapshot,
     dialect: Dialect,
     displayUrl: string,
+    governed: GovernedScope,
   ): Promise<string[]> {
     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: SchemaSnapshot | null;
     try {
       snapshot = await readSnapshot(snapshotPath(dir, dialect));
@@ -570,11 +867,28 @@ export async function verifyCommand(
     }
     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 [];
 
@@ -586,7 +900,7 @@ export async function verifyCommand(
     ];
   }
 
-  function reportSchemaDrift(driftResult: DiffResult, ledgerDrift: string[], displayUrl: string): number {
+  function reportSchemaDrift(driftResult: DriftResult, ledgerDrift: string[], displayUrl: string): number {
     // #208 §8 — make declared-external objects visible: they are excluded from the
     // drift comparison (computeDrift/computeDriftFromActual thread them out), so
     // annotate them as external (declared) rather than let them vanish silently.
@@ -597,6 +911,13 @@ export async function verifyCommand(
       );
     }
 
+    // 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}.`);
@@ -629,9 +950,13 @@ export async function verifyCommand(
       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 as Error).message}`);
       return 1;