@metaobjectsdev/cli 1.0.2 → 1.0.3

package/src/commands/verify.ts

@@ -24,12 +24,15 @@ import { replayRemedy } from "../lib/replay-remedy.js";
 import { FileProvider } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenCollection, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { collectionLoadOptions } from "../lib/collection-load-options.js";
 import { computeCodegenDrift } from "../lib/codegen-drift.js";
 import { computeDocsDrift } from "../lib/docs-drift.js";
 import {
   checkRequirements, summariseRequirements, scanRequirements, type Diagnostic,
 } from "../lib/requirement-check.js";
 import { lintRequirements } from "../lib/requirement-lint.js";
+import { lintOverlays } from "../lib/overlay-lint.js";
+import { FileSource } from "@metaobjectsdev/metadata/core";
 import { resolveD1Config, resolveMigrateConfig } from "../lib/config.js";
 import {
   buildWranglerExecuteArgs,
@@ -69,8 +72,15 @@ import {
   type D1Runner,
   type DriftResult,
 } from "@metaobjectsdev/migrate-ts";
-import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
-import { migrateScopeMismatch, outOfScopeNote } from "../lib/migrate-scope.js";
+import {
+  DEFAULT_METAOBJECTS_DIR,
+  loadConfig,
+  loadMemory,
+  resolveCollection,
+  type DependencySpec,
+} from "@metaobjectsdev/sdk";
+import { checkDependencies, ERR_DEPENDENCY_UPSTREAM_DRIFT, formatCheckLine, readLockOrThrow } from "../lib/dependency-sync.js";
+import { exclusionNotes, importedOption, migrateScopeMismatch } from "../lib/migrate-scope.js";
 import {
   TYPE_TEMPLATE,
   TEMPLATE_SUBTYPE_PROMPT,
@@ -163,11 +173,15 @@ export async function verifyCommand(
   // D1 has no URL connection); that check lives inside runSchemaVerify.
   const runCodegen = flags.codegen;
   const runDocs = flags.docs;
+  // Task 15 — same shape as --codegen/--docs: selected ONLY by its own flag,
+  // never folded into the bare-verify default (it needs the publisher
+  // reachable, which CI may not have — see the VerifyFlags doc on `deps`).
+  const runDeps = flags.deps;
   if (!flags.anyExplicit) {
     say(
       "meta verify — running --templates (default). Explicit subverbs: " +
         "--templates (prompt drift), --db/--dialect d1 (schema drift), --codegen (codegen drift), " +
-        "--docs (docs drift), " +
+        "--docs (docs drift), --deps (dependency drift), " +
         "--replay/--replay-snapshot (the committed migration chain replays from empty).",
     );
   }
@@ -248,7 +262,7 @@ export async function verifyCommand(
   let root: Awaited<ReturnType<typeof loadMemory>>;
   try {
     root = await loadMemory(collection.configDir, {
-      files: collection.files,
+      ...collectionLoadOptions(collection),
       ...configLoadOptions,
       strict: !flags.lax,
     });
@@ -314,7 +328,7 @@ export async function verifyCommand(
   const promptsDir = join(projectRoot, flags.prompts ?? DEFAULT_PROMPTS_DIR);
   const provider = new FileProvider(promptsDir);
 
-  // The two advisory sections, captured as the gates run so the structured payload
+  // The advisory sections, captured as the gates run so the structured payload
   // can carry them IN FULL. They were previously formatted straight to stderr and
   // existed nowhere else, which is why 96% of a 239-finding report was unreachable
   // by any flag, env var or format.
@@ -322,6 +336,12 @@ export async function verifyCommand(
     skippedSection("the requirement pass did not run");
   let antiPatternSection: AdvisorySection<AdvisoryFindingRow> =
     skippedSection("the advisory anti-pattern pass did not run");
+  // FR-023 §11.1 item 4 (Task 17) — the overlay authoring lint. Its own section
+  // (never folded into `requirements`, which is about a different kind of node
+  // entirely) so the structured payload names what ran and what didn't the same
+  // way every other advisory pass does.
+  let overlaySection: AdvisorySection<AdvisoryDiagnosticRow> =
+    skippedSection("the overlay lint did not run");
   // The ledger counts `meta verify` prints on every run. Undefined for a project
   // declaring no requirement.* node at all (opt-in by declaration) — the payload
   // then omits the block rather than reporting zeroes that would read as an empty
@@ -341,6 +361,7 @@ export async function verifyCommand(
   const schemaExit = await runSchemaVerify();
   const codegenExit = runCodegen ? await runCodegenVerify() : 0;
   const docsExit = runDocs ? await runDocsVerify() : 0;
+  const depsExit = runDeps ? await runDepsVerify() : 0;
   // Requirements have no subverb: `requirement.*` nodes are metadata, so they
   // are checked on every `meta verify`. Opt-in by DECLARATION — a model with no
   // requirement nodes is silent, not in drift.
@@ -351,6 +372,12 @@ export async function verifyCommand(
   // would parse cleanly and do nothing at all.
   const replayExit = flags.replay || flags.replaySnapshot ? await runReplayVerify() : 0;
 
+  // FR-023 §11.1 item 4 (Task 17) — the overlay authoring lint. Runs on every
+  // `meta verify`, not gated on any subverb (an unflagged cross-file
+  // redeclaration is a risk regardless of which drift gates were selected).
+  // Warnings ONLY — never changes the exit code.
+  await runOverlayLintAdvisory();
+
   // 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
@@ -362,6 +389,7 @@ export async function verifyCommand(
     schemaExit,
     codegenExit,
     docsExit,
+    depsExit,
     requirementExit,
     replayExit,
   );
@@ -378,6 +406,7 @@ export async function verifyCommand(
           { gate: "schema", ran: ranSchemaGate, ok: schemaExit === 0 },
           { gate: "codegen", ran: runCodegen, ok: codegenExit === 0 },
           { gate: "docs", ran: runDocs, ok: docsExit === 0 },
+          { gate: "deps", ran: runDeps, ok: depsExit === 0 },
           { gate: "requirements", ran: true, ok: requirementExit === 0 },
           { gate: "replay", ran: flags.replay || flags.replaySnapshot, ok: replayExit === 0 },
         ],
@@ -385,6 +414,7 @@ export async function verifyCommand(
         requirements: requirementSection,
         requirementCounts,
         antiPatterns: antiPatternSection,
+        overlays: overlaySection,
       }),
       fmt,
     );
@@ -553,7 +583,7 @@ export async function verifyCommand(
         columnNamingStrategy: viewStrategy,
         views: buildProjectionViews(root, { dialect, columnNamingStrategy: viewStrategy }),
       });
-      governed = scopeExpectedSchema(built, schemaScope);
+      governed = scopeExpectedSchema(built, schemaScope, importedOption(collection));
     }
 
     // `verifyReplay` calls `applyPending` itself. That is NOT a second replay: the
@@ -594,7 +624,7 @@ export async function verifyCommand(
     // ONE scan for all three passes. The gate and the summary each used to walk the
     // model AND resolve every @implementedBy claim for themselves — the resolution
     // being the expensive half — and the lint added a third walk on top.
-    const scan = scanRequirements(root);
+    const scan = scanRequirements(root, { coverable: collection.inScope });
     const diags = [...checkRequirements(root, scan)];
 
     // Printed on EVERY run, clean or not — a gate that says nothing when it
@@ -617,7 +647,14 @@ export async function verifyCommand(
         `meta verify — requirements: ${s.total} entries (${s.functional} functional, ` +
         `${s.architectural} architectural) — ${parts.join(", ")}; ` +
         `${s.entitiesClaimed}/${s.entitiesTotal} entities claimed, ` +
-        `counted over ${collection.files.length} metadata file(s).`,
+        `counted over ${collection.files.length} metadata file(s)` +
+        // FR-023 — only when there ARE dependencies. A project that declares none
+        // must print the sentence it printed before dependencies existed, to the
+        // byte: "0 from dependencies" is noise on every existing project, and this
+        // line is a SURFACE the no-dependency guarantee covers like any other.
+        (collection.dependencies.length > 0
+          ? `, ${collection.dependencies.length} from dependencies.`
+          : `.`),
       );
       if (s.undecided > 0) {
         say(
@@ -645,18 +682,13 @@ export async function verifyCommand(
 
     const errors = diags.filter((d) => d.severity === "error");
     const warns = diags.filter((d) => d.severity === "warn");
-    // Named `fmtDiag`, not `fmt`: `fmt` is this command's OUTPUT FORMAT parameter,
-    // and a shadow of it inside the one function that must not confuse the two is
-    // how a structured run quietly reverts to text.
-    const fmtDiag = (d: Diagnostic): string =>
-      `  ${d.code}${d.path !== undefined ? ` [${d.path}]` : ""}: ${d.message}`;
     // Capped per SECTION, never across them: a ledger of a few hundred entries can
     // produce hundreds of prose findings, and a shared budget would let the advisory
     // lint push every gate warning off the end. The cap VALUE is now one shared
     // constant (`--limit`), so raising it cannot miss a section — errors stay
     // uncapped, as they always were.
-    for (const d of errors) log.error(fmtDiag(d));
-    warnCapped(warns.map(fmtDiag), flags.limit, { structured });
+    for (const d of errors) log.error(formatDiagnostic(d));
+    warnCapped(warns.map(formatDiagnostic), flags.limit, { structured });
 
     // -- the authoring lint: its own section, its own cap ----------------------
     // Separate from the gate above because it makes a different claim. The gate
@@ -685,7 +717,7 @@ export async function verifyCommand(
         `meta verify — requirements: ${lint.length} authoring warning(s) ` +
         `(advisory — does not fail the build):`,
       );
-      warnCapped(lint.map(fmtDiag), flags.limit, { structured });
+      warnCapped(lint.map(formatDiagnostic), flags.limit, { structured });
     }
 
     // Everything this pass found, uncapped, for the structured payload — gate
@@ -703,6 +735,44 @@ export async function verifyCommand(
     return 0;
   }
 
+  // -- overlay authoring lint (FR-023 §11.1 item 4, Task 17) ------------------
+  // Its own section, its own cap — same discipline as the requirement lint
+  // above: a noisy section must not push another section's findings off the
+  // end of a capped run. This lint has NO gate half at all (no
+  // "ledger disagrees with the model" claim to make), so nothing here can
+  // ever reach the exit code — records its result either way, same as the
+  // anti-pattern pass below.
+  //
+  // Reads raw file content (via `lintOverlays` + `declaredTopLevelKeys`), never
+  // the loaded/merged model: the merge has already lost which FILE contributed
+  // which declaration, and that is exactly what this lint needs to name.
+  async function runOverlayLintAdvisory(): Promise<void> {
+    if (flags.noOverlayLint) {
+      overlaySection = skippedSection("suppressed by --no-overlay-lint");
+      return;
+    }
+    if (process.env.META_NO_OVERLAY_LINT === "1") {
+      overlaySection = skippedSection("suppressed by META_NO_OVERLAY_LINT=1");
+      return;
+    }
+    let findings: Diagnostic[];
+    try {
+      findings = await lintOverlays(collection, (path) => new FileSource(path));
+    } catch (err) {
+      // Never let an advisory scan break verify — and never report it as clean.
+      overlaySection = skippedSection(`the overlay lint failed: ${(err as Error).message}`);
+      return;
+    }
+    overlaySection = ranSection(findings.map((d) => toDiagnosticRow(d, "lint")));
+    if (findings.length > 0) {
+      log.warn(
+        `meta verify — overlays: ${findings.length} unflagged cross-file redeclaration(s) ` +
+          `(advisory — does not fail the build):`,
+      );
+      warnCapped(findings.map(formatDiagnostic), flags.limit, { structured });
+    }
+  }
+
   // -- verify-as-teacher (advisory) ------------------------------------------
   // Records its result EITHER WAY — a skip carries its reason rather than looking
   // like a clean scan. Warnings only; nothing here reaches the exit code (the
@@ -994,6 +1064,9 @@ export async function verifyCommand(
           allow,
           views: expectedViews,
           ...(schemaScope !== undefined ? { inScope: schemaScope } : {}),
+          // The import exclusion reaches scopeExpectedSchema through this option bag —
+          // there is no direct call on this path to attach it to.
+          ...importedOption(collection),
         });
       } catch (err) {
         log.error(`verify: failed to introspect ${kysely.displayUrl}: ${(err as Error).message}`);
@@ -1080,6 +1153,8 @@ export async function verifyCommand(
         allow,
         views: expectedViews,
         ...(schemaScope !== undefined ? { inScope: schemaScope } : {}),
+        // Same option bag on the D1 path, for the same reason.
+        ...importedOption(collection),
       });
     } catch (err) {
       log.error(`verify: ${(err as Error).message}`);
@@ -1192,11 +1267,12 @@ 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) {
-      say(outOfScopeNote("verify", driftResult.outOfScope));
+    // Same reasoning for the per-command scope and for imported metadata: an object
+    // excluded either way was NOT checked, and silence would misreport it as
+    // checked-and-clean. Shared wording with `meta migrate` — one declaration, one
+    // sentence about it — and each object named once (`exclusionNotes`).
+    for (const note of exclusionNotes("verify", driftResult.outOfScope, driftResult.importedOutOfScope ?? [])) {
+      say(note);
     }
 
     const changes = driftResult.changes;
@@ -1249,7 +1325,7 @@ export async function verifyCommand(
     if (genCollection !== collection) {
       try {
         codegenRoot = await loadMemory(genCollection.configDir, {
-          files: genCollection.files,
+          ...collectionLoadOptions(genCollection),
           ...configLoadOptions,
           strict: !flags.lax,
         });
@@ -1390,6 +1466,55 @@ export async function verifyCommand(
     }
     return 1;
   }
+
+  // -- dependency drift (Task 15, FR-023) --------------------------------------
+  // Gated on --deps. Re-resolves each declared dependency exactly as `meta deps
+  // check` does — never part of the bare-verify default (it needs the publisher
+  // reachable, which CI may not have).
+  async function runDepsVerify(): Promise<number> {
+    // Read RAW declared specs (never `collection.dependencies`, which is the
+    // already-`ResolvedDependency[]` the LOCK produced — it carries no
+    // transport info, so it cannot be re-resolved). A project with no
+    // config.json at all declares no dependencies.
+    let depSpecs: readonly DependencySpec[] = [];
+    try {
+      const cfg = await loadConfig(join(collection.configDir, DEFAULT_METAOBJECTS_DIR));
+      depSpecs = cfg.dependencies;
+    } catch {
+      depSpecs = [];
+    }
+
+    if (depSpecs.length === 0) {
+      say("verify --deps: no dependencies declared — nothing to check.");
+      return 0;
+    }
+
+    let lock: Awaited<ReturnType<typeof readLockOrThrow>>;
+    try {
+      lock = await readLockOrThrow(collection.configDir);
+    } catch (err) {
+      log.error(`verify --deps: ${(err as Error).message}`);
+      return 2;
+    }
+
+    const results = await checkDependencies(collection.configDir, depSpecs, lock);
+    const failing = results.filter((r) => r.status !== "current");
+
+    for (const r of results) {
+      if (r.status === "current") say(formatCheckLine(r));
+      else log.error(formatCheckLine(r));
+    }
+
+    if (failing.length > 0) {
+      log.error(
+        `verify --deps: ${failing.length} of ${results.length} dependenc` +
+          `${results.length === 1 ? "y" : "ies"} drifted or unresolved (${ERR_DEPENDENCY_UPSTREAM_DRIFT}).`,
+      );
+      return 1;
+    }
+    say("verify --deps: every dependency's installed artifact matches the lock.");
+    return 0;
+  }
 }
 
 /**
@@ -1460,6 +1585,17 @@ interface VerifyGateRow {
   ok: boolean;
 }
 
+/**
+ * Format one `Diagnostic` as a printed TEXT line. Named `formatDiagnostic`, not
+ * `fmt`: `fmt` is this command's OUTPUT FORMAT parameter, and a shadow of it
+ * anywhere near this code is how a structured run quietly reverts to text.
+ * Shared by the requirement gate/lint AND the overlay lint — every advisory or
+ * gate pass that speaks in `Diagnostic` prints it identically.
+ */
+function formatDiagnostic(d: Diagnostic): string {
+  return `  ${d.code}${d.path !== undefined ? ` [${d.path}]` : ""}: ${d.message}`;
+}
+
 /** Project a requirement diagnostic into a payload row. */
 function toDiagnosticRow(d: Diagnostic, source: "gate" | "lint"): AdvisoryDiagnosticRow {
   return {
@@ -1491,6 +1627,7 @@ function buildVerifyPayload(input: {
   requirements: AdvisorySection<AdvisoryDiagnosticRow>;
   requirementCounts: RequirementCounts | undefined;
   antiPatterns: AdvisorySection<AdvisoryFindingRow>;
+  overlays: AdvisorySection<AdvisoryDiagnosticRow>;
 }): Record<string, unknown> {
   const ran = input.gates.filter((g) => g.ran);
   const failed = ran.filter((g) => !g.ok);
@@ -1505,6 +1642,9 @@ function buildVerifyPayload(input: {
   if (input.requirements.total > 0) {
     parts.push(`${input.requirements.total} requirement diagnostic(s)`);
   }
+  if (input.overlays.status === "ran" && input.overlays.total > 0) {
+    parts.push(`${input.overlays.total} overlay authoring finding(s)`);
+  }
 
   const help: string[] = [];
   if (failed.length > 0) {
@@ -1517,7 +1657,17 @@ function buildVerifyPayload(input: {
       `${input.antiPatterns.total} authored site(s) hand-roll what MetaObjects can model — see antiPatterns.rows[] and run \`meta types <construct>\``,
     );
   }
-  if (failed.length === 0 && input.antiPatterns.total === 0 && input.requirements.total === 0) {
+  if (input.overlays.total > 0) {
+    help.push(
+      `${input.overlays.total} unflagged cross-file redeclaration(s) — see overlays.rows[]; add overlay: true so a renamed or removed target fails loudly instead of silently becoming a new object`,
+    );
+  }
+  if (
+    failed.length === 0 &&
+    input.antiPatterns.total === 0 &&
+    input.requirements.total === 0 &&
+    input.overlays.total === 0
+  ) {
     help.push("no drift and nothing advisory to answer — nothing to do");
   }
 
@@ -1528,6 +1678,7 @@ function buildVerifyPayload(input: {
     help,
     antiPatterns: input.antiPatterns,
     requirements: input.requirements,
+    overlays: input.overlays,
     ...(input.requirementCounts !== undefined ? { requirementCounts: input.requirementCounts } : {}),
     // The honest boundary. Everything named here is REACHABLE — it is printed as
     // text on stderr — but it is not in this document, and a reader must not have

package/src/index.ts

@@ -17,7 +17,7 @@ const VERSION = cliVersion();
  * human text. It is named ONCE and used by both the warning below and the help
  * text above, so the two cannot drift apart.
  */
-const FORMAT_AWARE_COMMANDS: readonly string[] = ["gen", "verify", "migrate", "types"];
+const FORMAT_AWARE_COMMANDS: readonly string[] = ["gen", "verify", "migrate", "types", "deps"];
 
 const HELP_TEXT = `meta — MetaObjects CLI (v${VERSION})
 
@@ -32,10 +32,13 @@ COMMANDS:
   gen [<entity>...]     Codegen TS targets from your declared metadata
   eject <generator>     Copy a reference generator into codegen/generators/ to own it (any time after init)
   eject --list          List every ejectable generator name, grouped by package
+  deps sync [<name>...] Resolve declared dependencies (path transport): sync the committed
+                        snapshot + sha256 lock (.metaobjects/deps/, .metaobjects/deps.lock.json)
+  deps list             One line per locked dependency: name, version, hash, node/package summary
   types [query]         Search the metadata vocabulary (types, subtypes, @attrs) by name or description
   export                Flatten loaded metadata to one canonical JSON artifact
   docs [<project-root>] --out <dir>  Generate neutral metadata documentation (entity + template pages; --site for HTML site)
-  verify                Drift gate — subverbs: --templates / --db / --codegen / --docs (bare = --templates)
+  verify                Drift gate — subverbs: --templates / --db / --codegen / --docs / --deps (bare = --templates)
   upgrade               Rewrite retired metadata vocabulary (previews; --apply writes)
   prompt-snapshot       Snapshot rendered template.* output; --check gates drift
   migrate               Diff metadata vs live DB; emit migration SQL files
@@ -94,6 +97,10 @@ VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drif
                         run would emit; never reports an extra file, because docs.outDir
                         holds hand-written documentation MetaObjects did not write.
                         Needs metaobjects.config.ts; exit 2 if absent.
+  --deps                Dependency drift — re-resolve each declared dependency and compare
+                        its installed artifact's hash against .metaobjects/deps.lock.json
+                        (the same check 'meta deps check' runs). Never part of the bare-verify
+                        default — it needs the publisher reachable, which CI may not have.
   --db <url>            Schema drift — live DB URL enables the schema-drift gate.
                         Supports: file:, libsql:, postgres:, postgresql:. Omit to skip.
                         D1 has no URL — use --dialect d1 / --d1 <binding> instead.
@@ -108,6 +115,8 @@ VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drif
   --no-antipatterns     Suppress the advisory "you hand-rolled what MetaObjects can
                         model" pass (aggregate/currency/enum hints; warnings only)
   --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
+  --no-overlay-lint     Suppress the advisory overlay-redeclaration AUTHORING lint
+                        (never a gate — this lint can't fail the build)
   --limit <n|all>       How many advisory lines TEXT output prints per section before
                         it truncates (default 20). Never applies to --format
                         toon/json, which carry every finding and every diagnostic.
@@ -191,6 +200,38 @@ the same operation for ANY generator — one you skipped at init time, a UI-tier
 generator like form/hooks/grid, or one a package gains later. It prints the
 import line to paste into metaobjects.config.ts, and it never overwrites a
 file you already own unless you pass --force.
+`,
+  deps: `meta deps — sync a declared metadata dependency's committed snapshot
+
+USAGE:
+  meta deps sync [<name>...]   Resolve each declared dependency (path transport only in
+                                this release — npm/python refuse by name), validate its
+                                manifest + artifact, copy it into .metaobjects/deps/<name>/,
+                                and pin it in .metaobjects/deps.lock.json. Naming one or more
+                                <name>s syncs only those; bare 'sync' syncs everything
+                                declared. A dependency removed from config is PRUNED from
+                                the lock and its snapshot dir deleted, every run.
+  meta deps list                One line per locked dependency: name, version, hash8,
+                                node count, packages.
+  meta deps check                Re-resolve each declared dependency (path transport, same
+                                as sync steps 1-2) and compare its INSTALLED artifact's hash
+                                against .metaobjects/deps.lock.json. Read-only — never
+                                touches the lock or the snapshot. Exits 1 if any dependency
+                                has drifted or cannot be resolved (ERR_DEPENDENCY_UPSTREAM_DRIFT).
+
+FLAGS:
+  --dry-run              Plan and report; write nothing (sync only)
+  --format <toon|json|text>   Output format (global flag; default toon off-TTY)
+  --help, -h              Print this help
+
+Only the "path" transport resolves in this release — a "npm"/"python" dependency spec is
+valid config (reserved for a future toolchain) but 'meta deps sync' refuses it by name:
+"transport \`npm\` is not supported by this toolchain yet; use \`path\`".
+
+The lock is the ONLY thing 'meta deps sync' writes to besides the snapshot directory —
+sync never touches your own metadata files. 'meta deps check' compares the lock against
+what is installed right now (the same check 'meta verify --deps' runs); 'meta deps sync'
+only ever compares against what config DECLARES.
 `,
   verify: `meta verify — drift gate (templates / DB schema / codegen / migration replay)
 
@@ -210,6 +251,12 @@ FLAGS:
                         a namespace MetaObjects owns); the count of exempt pages is
                         reported either way, and a run where every page is ignored is
                         refused rather than reported clean.
+  --deps                Dependency drift — re-resolve each declared dependency exactly as
+                        'meta deps check' does and compare its installed artifact's hash
+                        against .metaobjects/deps.lock.json. Exits 1 if any dependency has
+                        drifted or cannot be resolved (ERR_DEPENDENCY_UPSTREAM_DRIFT). NEVER
+                        part of the bare-verify default — it needs the publisher reachable,
+                        which CI may not have.
   --db <url>            Schema drift — live DB URL enables the schema-drift gate.
                         Supports: file:, libsql:, postgres:, postgresql:
                         D1 has no URL — use --dialect d1 / --d1 <binding> instead.
@@ -237,6 +284,8 @@ FLAGS:
                         migrating a model onto a registered provider.
   --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
   --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
+  --no-overlay-lint     Suppress the advisory overlay-redeclaration AUTHORING lint —
+                        never a gate; this lint can't fail the build
   --limit <n|all>       Advisory lines TEXT output prints PER SECTION before truncating
                         (default 20; per-section so the authoring lint can never push
                         the gate's own warnings off the end)
@@ -258,6 +307,13 @@ lint in its own section: names that are not addressable, prose slots holding one
 sentence twice, content written where no surface reads it. Warnings only — it can
 never fail the build. Opt out with --no-requirement-lint or META_NO_REQUIREMENT_LINT=1.
 The requirements GATE itself (dangling refs, link floor, levels) always runs.
+
+verify also prints an ADVISORY overlay authoring lint, in its own section: a
+top-level declaration redeclared in two or more files where more than one
+redeclaration lacks 'overlay: true' — today's default merge rule reuses it
+silently, but the same unflagged redeclaration silently becomes a NEW object
+the day the target is renamed or removed upstream. Warnings only — it can
+never fail the build. Opt out with --no-overlay-lint or META_NO_OVERLAY_LINT=1.
 `,
   export: `meta export — flatten loaded metadata to one canonical JSON artifact
 
@@ -530,6 +586,10 @@ export async function run(argv: string[]): Promise<number> {
       const { ejectCommand } = await import("./commands/eject.js");
       return ejectCommand(rest, cwd);
     }
+    case "deps": {
+      const { depsCommand } = await import("./commands/deps.js");
+      return depsCommand(rest, cwd, fmt);
+    }
     case "export": {
       const { exportCommand } = await import("./commands/export.js");
       return exportCommand(rest, cwd);

package/src/lib/agent-context-staleness.ts

@@ -1,6 +1,12 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { AGENT_CONTEXT_MANIFEST_PATH, agentContextStaleness, type Manifest } from "@metaobjectsdev/sdk";
+// The agent-context subpath, not the root barrel: `@metaobjectsdev/sdk` exports TWO
+// types named `Manifest` — this one (the scaffolded agent context) via `export *`,
+// and FR-023's `metaobjects.pkg.json` explicitly. An explicit export shadows a
+// star one, so the root barrel now hands out the dependency manifest under this
+// name. `init.ts` already imports these from the subpath; this was the last site
+// reading them from the root.
+import { AGENT_CONTEXT_MANIFEST_PATH, agentContextStaleness, type Manifest } from "@metaobjectsdev/sdk/agent-context";
 import { cliVersion } from "./version.js";
 import { log } from "./log.js";