@metaobjectsdev/cli 0.21.6 → 0.22.0-rc.2

package/dist/src/lib/verified-by-scan.js

@@ -0,0 +1,168 @@
+// `meta verify` — the `@verifiedBy` check.
+//
+// A requirement's `@verifiedBy` names the tests that prove the behaviour. verify
+// checks each name EXISTS and is NOT SKIPPED; it never runs them. Running them is
+// the test runner's job, and a requirement gate that shelled out to one would be
+// slow, ecosystem-specific, and wrong in CI.
+//
+// Until this existed, `@verifiedBy` was registered vocabulary that nothing read —
+// the precise pattern ADR-0007 Amendment 2 and the `@role` shrink exist to punish.
+// An attribute the loader accepts and no consumer dispatches on teaches authors
+// that declaring is free and means nothing.
+//
+// PRECISION OVER RECALL, deliberately. The scan matches a name anywhere in the
+// test corpus, as a whole word, in any language. That is the most generous
+// possible reading, so a "missing" verdict means the name appears in NO test file
+// at all — which is a broken claim in any ecosystem. The repo's standing rule for
+// drift checks is to bias toward under-flagging, and a nagging gate gets disabled,
+// which costs more than the misses.
+//
+// FAIL-OPEN ON INABILITY. If the project has no test files this scan can see, it
+// says NOTHING rather than reporting every name missing. Absence of evidence is
+// not evidence of absence, and a monorepo whose tests live outside `--cwd` must
+// not be told its requirements are unverified.
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { TYPE_REQUIREMENT, } from "@metaobjectsdev/metadata";
+export const ERR_REQUIREMENT_TEST_MISSING = "ERR_REQUIREMENT_TEST_MISSING";
+export const WARN_REQUIREMENT_TEST_SKIPPED = "WARN_REQUIREMENT_TEST_SKIPPED";
+const IGNORE_SEGMENTS = new Set([
+    "node_modules", ".git", "dist", "build", "out", ".next", "coverage",
+    ".metaobjects", "generated", "target", "bin", "obj", "__pycache__", ".venv", "venv",
+]);
+/** Test files across the five ecosystems this project ports to. */
+const TEST_FILE = new RegExp([
+    "\\.(?:test|spec)\\.[cm]?[jt]sx?$", // bun / jest / vitest / mocha
+    "(?:^|[./_-])[Tt]est[^/]*\\.java$", // JUnit — TestFoo.java
+    "[A-Za-z0-9]Test(?:s)?\\.java$", //     JUnit — FooTest.java / FooTests.java
+    "[A-Za-z0-9]Tests?\\.cs$", //           xUnit / NUnit
+    "^test_[^/]*\\.py$", //                 pytest
+    "[^/]*_test\\.py$", //                  pytest, trailing convention
+    "[A-Za-z0-9]Test(?:s)?\\.kt$", //       Kotlin
+].join("|"));
+/** Markers that a test exists but is disabled, across the same ecosystems. */
+const SKIP_MARKER = new RegExp([
+    "\\b(?:it|test|describe)\\.(?:skip|todo)\\b", // jest/vitest/bun
+    "\\bx(?:it|test|describe)\\b", //               mocha/jasmine
+    "@Disabled\\b", //                              JUnit 5
+    "@Ignore\\b", //                                JUnit 4 / Kotlin
+    "@pytest\\.mark\\.skip", //                     pytest
+    "\\[Ignore[\\](]", //                           MSTest / NUnit
+    "\\bSkip\\s*=", //                              xUnit  [Fact(Skip = "...")]
+].join("|"));
+function walk(dir, root, acc, depth = 0) {
+    if (depth > 12)
+        return; // pathological trees; the scan is advisory, not exhaustive
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (e.isDirectory()) {
+            if (IGNORE_SEGMENTS.has(e.name) || e.name.startsWith("."))
+                continue;
+            walk(join(dir, e.name), root, acc, depth + 1);
+            continue;
+        }
+        if (!e.isFile() || !TEST_FILE.test(e.name))
+            continue;
+        const abs = join(dir, e.name);
+        try {
+            if (statSync(abs).size > 512 * 1024)
+                continue;
+            acc.byFile.set(relative(root, abs).split(sep).join("/"), readFileSync(abs, "utf8").split("\n"));
+            acc.files++;
+        }
+        catch {
+            /* unreadable file is not a finding */
+        }
+    }
+}
+/** Every `requirement.*` node in the tree, at any nesting depth. */
+function collect(root) {
+    const out = [];
+    const rec = (n) => {
+        for (const c of n.children()) {
+            if (c.type === TYPE_REQUIREMENT)
+                out.push(c);
+            rec(c);
+        }
+    };
+    rec(root);
+    return out;
+}
+/**
+ * A whole-word match, so `OrderServiceTest` never satisfies a claim naming `Order`.
+ *
+ * `_` counts as a SEPARATOR, not a word character: pytest's `def test_OrderServiceTest`
+ * plainly is the test a claim naming `OrderServiceTest` means, and refusing it would
+ * emit the confident false error this scan is built to avoid. Camel-case boundaries
+ * stay strict, which is what actually prevents a short name matching a longer one.
+ */
+function wordRx(name) {
+    return new RegExp(`(?:^|[^A-Za-z0-9])${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![A-Za-z0-9])`);
+}
+/**
+ * Check every `@verifiedBy` name against the project's test corpus.
+ *
+ * Severity mirrors `@implementedBy`: a broken claim is an ERROR on `live`/`partial`
+ * and silent on `abandoned`/`superseded`, because a retired requirement naming a
+ * deleted test is the entry doing its job, not drift.
+ */
+export function checkVerifiedBy(root, cwd) {
+    const reqs = collect(root).filter((r) => r.verifiedBy().length > 0);
+    if (reqs.length === 0)
+        return []; // opt-in by declaration
+    const corpus = { files: 0, byFile: new Map() };
+    walk(cwd, cwd, corpus);
+    if (corpus.files === 0)
+        return []; // fail open: nothing to judge against
+    const out = [];
+    for (const req of reqs) {
+        for (const test of req.verifiedBy()) {
+            const rx = wordRx(test);
+            let foundIn;
+            let skippedAt;
+            for (const [file, lines] of corpus.byFile) {
+                for (let i = 0; i < lines.length; i++) {
+                    if (!rx.test(lines[i] ?? ""))
+                        continue;
+                    foundIn ??= file;
+                    // a decorator/annotation sits above the declaration it disables
+                    const window = lines.slice(Math.max(0, i - 3), i + 1).join("\n");
+                    if (SKIP_MARKER.test(window))
+                        skippedAt ??= `${file}:${i + 1}`;
+                }
+                if (foundIn !== undefined && skippedAt !== undefined)
+                    break;
+            }
+            if (foundIn === undefined) {
+                if (req.requiresLiveNodes()) {
+                    out.push({
+                        severity: "error",
+                        code: ERR_REQUIREMENT_TEST_MISSING,
+                        name: req.name,
+                        message: `'verifiedBy' names '${test}', which appears in none of the ` +
+                            `${corpus.files} test file(s) found under this project. Either the test was ` +
+                            `renamed or removed, or the claim was never true.`,
+                    });
+                }
+                continue;
+            }
+            if (skippedAt !== undefined) {
+                out.push({
+                    severity: "warn",
+                    code: WARN_REQUIREMENT_TEST_SKIPPED,
+                    name: req.name,
+                    message: `'verifiedBy' names '${test}', but it is disabled at ${skippedAt}. ` +
+                        `A skipped test proves nothing — the requirement reads as verified and is not.`,
+                });
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=verified-by-scan.js.map

package/dist/src/lib/verified-by-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verified-by-scan.js","sourceRoot":"","sources":["../../../src/lib/verified-by-scan.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/cli",
-  "version": "0.21.6",
+  "version": "0.22.0-rc.2",
   "description": "CLI for MetaObjects: scaffold, codegen, migrate, and drift-detection commands.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -49,15 +49,15 @@
   ],
   "dependencies": {
     "@libsql/kysely-libsql": "^0.4.0",
-    "@metaobjectsdev/codegen-ts": "0.21.6",
-    "@metaobjectsdev/codegen-ts-react": "0.21.6",
-    "@metaobjectsdev/codegen-ts-tanstack": "0.21.6",
-    "@metaobjectsdev/docs-site": "0.21.6",
-    "@metaobjectsdev/metadata": "0.21.6",
-    "@metaobjectsdev/migrate-ts": "0.21.6",
-    "@metaobjectsdev/render": "0.21.6",
-    "@metaobjectsdev/runtime-ts": "0.21.6",
-    "@metaobjectsdev/sdk": "0.21.6",
+    "@metaobjectsdev/codegen-ts": "0.22.0-rc.2",
+    "@metaobjectsdev/codegen-ts-react": "0.22.0-rc.2",
+    "@metaobjectsdev/codegen-ts-tanstack": "0.22.0-rc.2",
+    "@metaobjectsdev/docs-site": "0.22.0-rc.2",
+    "@metaobjectsdev/metadata": "0.22.0-rc.2",
+    "@metaobjectsdev/migrate-ts": "0.22.0-rc.2",
+    "@metaobjectsdev/render": "0.22.0-rc.2",
+    "@metaobjectsdev/runtime-ts": "0.22.0-rc.2",
+    "@metaobjectsdev/sdk": "0.22.0-rc.2",
     "@toon-format/toon": "^2.3.0",
     "jiti": "^2.4.0"
   },

package/src/commands/verify.ts

@@ -16,6 +16,8 @@ import { FileProvider } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
 import { loadMetaobjectsConfig } from "../lib/load-metaobjects-config.js";
 import { computeCodegenDrift } from "../lib/codegen-drift.js";
+import { checkRequirements } from "../lib/requirement-check.js";
+import { checkVerifiedBy } from "../lib/verified-by-scan.js";
 import { resolveD1Config } from "../lib/config.js";
 import {
   buildWranglerExecuteArgs,
@@ -158,6 +160,10 @@ export async function verifyCommand(
   const templateExit = runTemplates ? runTemplateVerify() : 0;
   const schemaExit = await runSchemaVerify();
   const codegenExit = runCodegen ? await runCodegenVerify() : 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.
+  const requirementExit = runRequirementVerify();
 
   // Advisory verify-as-teacher pass: surface hand-rolled work the metadata could
   // model. Warnings ONLY — never changes the exit code (bias to under-flagging).
@@ -165,7 +171,28 @@ 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);
+  return Math.max(templateExit, schemaExit, codegenExit, requirementExit);
+
+  // -- 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.
+    const diags = [...checkRequirements(root), ...checkVerifiedBy(root, cwd)];
+    if (diags.length === 0) return 0;
+    const errors = diags.filter((d) => d.severity === "error");
+    const warns = diags.filter((d) => d.severity === "warn");
+    const CAP = 20;
+    for (const d of errors) log.error(`  ${d.code}${d.name !== undefined ? ` [${d.name}]` : ""}: ${d.message}`);
+    for (const d of warns.slice(0, CAP)) {
+      log.warn(`  ${d.code}${d.name !== undefined ? ` [${d.name}]` : ""}: ${d.message}`);
+    }
+    if (warns.length > CAP) log.warn(`  …and ${warns.length - CAP} more.`);
+    if (errors.length > 0) {
+      log.error(`meta verify — requirements: ${errors.length} error(s).`);
+      return 1;
+    }
+    return 0;
+  }
 
   // -- verify-as-teacher (advisory) ------------------------------------------
   function runAntiPatternAdvisory(): void {

package/src/lib/detect-stack.ts

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
+import type { Dirent } from "node:fs";
 import { join } from "node:path";
 import {
-  detectStack, makeStack,
+  detectStack, detectConcerns, makeStack,
   type ServerLang, type ClientFramework, type Stack, type ProjectProbe,
   SERVER_LANGS, CLIENT_FRAMEWORKS,
 } from "@metaobjectsdev/sdk/agent-context";
@@ -20,22 +21,64 @@ function depNames(cwd: string): Set<string> {
   return out;
 }
 
+const METADATA_DIR = "metaobjects";
+const METADATA_FILE_PATTERN = /\.(json|ya?ml)$/i;
+// Cheap substring probe, not a metamodel load: matches both canonical JSON's
+// quoted `"requirement.functional"` key and sigil-free YAML's bare
+// `requirement.functional:` authoring form.
+const REQUIREMENT_NODE_MARKER = "requirement.";
+
+/** Recursively scans `metaobjects/` for any `.json`/`.yaml`/`.yml` file containing a
+ * `requirement.*` node marker. Defensive throughout: a missing/unreadable directory
+ * or file is treated as "not found", never thrown — this is a cheap heuristic, not
+ * a metamodel load. */
+function hasRequirementNodes(cwd: string): boolean {
+  const root = join(cwd, METADATA_DIR);
+  if (!existsSync(root)) return false;
+  const pending: string[] = [root];
+  while (pending.length > 0) {
+    const dir = pending.pop()!;
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue; // unreadable directory — skip it, keep scanning siblings
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        pending.push(full);
+      } else if (METADATA_FILE_PATTERN.test(entry.name)) {
+        try {
+          if (readFileSync(full, "utf8").includes(REQUIREMENT_NODE_MARKER)) return true;
+        } catch { /* unreadable file — treat as no match */ }
+      }
+    }
+  }
+  return false;
+}
+
 function probe(cwd: string): ProjectProbe {
   const deps = depNames(cwd);
   const names = existsSync(cwd) ? readdirSync(cwd) : [];
   return {
     hasDep: (name) => deps.has(name),
     hasFileMatching: (re) => names.some((n) => re.test(n)),
+    hasRequirementNodes: () => hasRequirementNodes(cwd),
   };
 }
 
-/** Resolve the stack: explicit --server/--client overrides take precedence; otherwise detect. */
+/** Resolve the stack: explicit --server/--client overrides take precedence; otherwise detect.
+ * Concern tokens (e.g. requirements) are always OBSERVED from project state, independent of
+ * any --server/--client override — a concern is not a stack axis. */
 export function resolveStack(cwd: string, overrides: { servers: string[]; clients: string[] }): Stack {
   const validServers = SERVER_LANGS as readonly string[];
   const validClients = CLIENT_FRAMEWORKS as readonly string[];
   const oServers = overrides.servers.filter((s): s is ServerLang => validServers.includes(s));
   const oClients = overrides.clients.filter((c): c is ClientFramework => validClients.includes(c));
-  if (oServers.length > 0 || oClients.length > 0) return makeStack(oServers, oClients);
-  const detected = detectStack(probe(cwd));
-  return makeStack(detected.servers, detected.clients);
+  const p = probe(cwd);
+  const concerns = detectConcerns(p);
+  if (oServers.length > 0 || oClients.length > 0) return makeStack(oServers, oClients, concerns);
+  const detected = detectStack(p);
+  return makeStack(detected.servers, detected.clients, concerns);
 }

package/src/lib/requirement-check.ts

@@ -0,0 +1,272 @@
+// `meta verify` — the requirement (capability) gate.
+//
+// Requirements are METADATA: `requirement.functional` / `requirement.architectural`
+// are registered metamodel types, declared in `metaobjects/` beside the entities
+// they describe. So this file parses NOTHING. It reads `requirement.*` nodes off
+// the already-loaded model and checks the things the loader cannot.
+//
+// Division of labour, and the reason for it:
+//
+//   LOADER (unconditional)   the `@status` enum via `allowedValues`, required
+//                            attrs, child rules, levels being integers.
+//   VERIFY  (conditional)    `@implementedBy` resolution, whose SEVERITY DEPENDS
+//                            ON `@status`. A loader `references` descriptor
+//                            always errors on an unresolved target, and an
+//                            `abandoned` requirement exists precisely to name
+//                            nodes that are gone — declaring it there would make
+//                            the entries carrying the mechanism's only controlled
+//                            evidence fail to load.
+//
+// Two kinds, opposite checks: `functional` fails when NOTHING implements it;
+// `architectural` fails when something VIOLATES it (v1: an empty claim set on a
+// live policy — claim-set arithmetic, deliberately not a predicate DSL).
+
+import {
+  TYPE_OBJECT,
+  TYPE_REQUIREMENT,
+  OBJECT_SUBTYPE_ENTITY,
+  PACKAGE_SEPARATOR,
+  REQUIREMENT_SUBTYPE_ARCHITECTURAL,
+  REQUIREMENT_LINK_FLOOR_LEVEL,
+  REQUIREMENT_MIN_LEVEL,
+  REQUIREMENT_MAX_LEVEL,
+  REQUIREMENT_LEVEL_MEMBER,
+  REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES,
+  resolveObjectRef,
+  didYouMeanHint,
+  type MetaData,
+  type MetaRequirement,
+  type RequirementStatus,
+} from "@metaobjectsdev/metadata";
+
+export type Severity = "error" | "warn";
+
+export interface Diagnostic {
+  severity: Severity;
+  code: string;
+  /** The requirement node's name, when the diagnostic belongs to one. */
+  name?: string;
+  message: string;
+}
+
+export const ERR_REQUIREMENT_LINK_ABOVE_FLOOR = "ERR_REQUIREMENT_LINK_ABOVE_FLOOR";
+export const ERR_REQUIREMENT_DANGLING_REF = "ERR_REQUIREMENT_DANGLING_REF";
+export const ERR_REQUIREMENT_BAD_LEVEL = "ERR_REQUIREMENT_BAD_LEVEL";
+export const ERR_REQUIREMENT_LEVEL_NESTING = "ERR_REQUIREMENT_LEVEL_NESTING";
+export const ERR_REQUIREMENT_L4_NOT_OBJECT = "ERR_REQUIREMENT_L4_NOT_OBJECT";
+export const ERR_REQUIREMENT_L5_NOT_MEMBER = "ERR_REQUIREMENT_L5_NOT_MEMBER";
+export const ERR_REQUIREMENT_ARCH_NO_IMPLEMENTERS = "ERR_REQUIREMENT_ARCH_NO_IMPLEMENTERS";
+export const WARN_REQUIREMENT_OBJECT_UNCLAIMED = "WARN_REQUIREMENT_OBJECT_UNCLAIMED";
+
+/** Severity of the object-coverage gate. Promotion to `"error"` is a one-line
+ *  flip here, which activates an already-written test rather than requiring new
+ *  authoring under release pressure.
+ *
+ *  It stays `"warn"`, and the reason is measured rather than cautious:
+ *
+ *  - On a real 120-file estate carrying a SINGLE requirement, this gate reports
+ *    93 unclaimed entities — every entity in the repository. At `"error"` a
+ *    project adopting requirements incrementally fails its first `verify` after
+ *    authoring one entry, which teaches people to delete the entry.
+ *  - The gate is satisfiable without being informative: `claimedObjects` below
+ *    counts a claim from any requirement at any level and any status, so
+ *    appending an FQN to an existing list clears it. Green proves an entity is
+ *    NAMED, never that it is understood.
+ *  - The experiment meant to settle whether forcing it yields real entries or
+ *    padding stopped at its ceiling probe: at `"warn"` agents already authored
+ *    proper L3/L4/L5 entries for what they added, so the arms could not differ.
+ *    That is not evidence promotion is useless — it is evidence that instrument
+ *    cannot see it.
+ *
+ *  spec/design-docs/2026-08-11-prereg-duplication-and-levels.md, "Round E result". */
+export const OBJECT_COVERAGE_SEVERITY: Severity = "warn";
+
+/**
+ * Split a member reference into its owning object ref and the dotted member path.
+ * `::` qualifies the ROOT-level node only, so the object ref ends at the FIRST
+ * `.` after the last `::`.
+ * `acme::sales::Order.total.display` -> `["acme::sales::Order", ["total","display"]]`
+ */
+export function splitMemberRef(ref: string): { owner: string; path: string[] } {
+  const pkgEnd = ref.lastIndexOf(PACKAGE_SEPARATOR);
+  const from = pkgEnd === -1 ? 0 : pkgEnd + PACKAGE_SEPARATOR.length;
+  const dot = ref.indexOf(".", from);
+  if (dot === -1) return { owner: ref, path: [] };
+  return { owner: ref.slice(0, dot), path: ref.slice(dot + 1).split(".") };
+}
+
+/** Walk dotted member segments by CHILD NAME from an object node. */
+function resolveMember(obj: MetaData, path: string[]): MetaData | undefined {
+  let cur: MetaData | undefined = obj;
+  for (const seg of path) {
+    if (cur === undefined) return undefined;
+    cur = cur.children().find((c) => c.name === seg);
+  }
+  return cur;
+}
+
+/** Every `requirement.*` node in the tree, at any nesting depth. Hierarchy IS
+ *  nesting — an L1 solution contains its L2 segments — so this is a walk, not a
+ *  scan of a flat list keyed by a `parent` string. */
+export function collectRequirements(root: MetaData): MetaRequirement[] {
+  const out: MetaRequirement[] = [];
+  const walk = (n: MetaData): void => {
+    for (const c of n.children()) {
+      if (c.type === TYPE_REQUIREMENT) out.push(c as MetaRequirement);
+      walk(c);
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/**
+ * Check the requirement tree against the loaded model.
+ *
+ * What a clean run proves: referential integrity — links sit at or below the
+ * link floor, nesting agrees with levels, and references resolve. What it CANNOT
+ * prove: that a status is *true*, or that a node actually implements the
+ * requirement claiming it. No test can. That truth is the adopter's job.
+ */
+export function checkRequirements(root: MetaData): Diagnostic[] {
+  const out: Diagnostic[] = [];
+  const reqs = collectRequirements(root);
+  if (reqs.length === 0) return out; // opt-in by declaration — no requirements, nothing to say
+
+  const claimedObjects = new Set<string>();
+
+  for (const req of reqs) {
+    const architectural = req.subType === REQUIREMENT_SUBTYPE_ARCHITECTURAL;
+    const level = req.level();
+    const refs = req.implementedBy();
+
+    if (!architectural) {
+      if (level === undefined || !Number.isInteger(level)
+          || level < REQUIREMENT_MIN_LEVEL || level > REQUIREMENT_MAX_LEVEL) {
+        out.push({
+          severity: "error", code: ERR_REQUIREMENT_BAD_LEVEL, name: req.name,
+          message: `level must be an integer ${REQUIREMENT_MIN_LEVEL}-${REQUIREMENT_MAX_LEVEL} (got ${String(level)}). ` +
+            `L1 solution, L2 segment (app/library), L3 service, L4 object, L5 member.`,
+        });
+      }
+      // Nesting IS the hierarchy, so a child must sit strictly below its parent.
+      const parent = req.parent;
+      if (parent !== undefined && parent.type === TYPE_REQUIREMENT) {
+        const pl = (parent as MetaRequirement).level();
+        if (pl !== undefined && level !== undefined && level <= pl) {
+          out.push({
+            severity: "error", code: ERR_REQUIREMENT_LEVEL_NESTING, name: req.name,
+            message: `nested under "${parent.name}" (level ${pl}) but declares level ${level}. ` +
+              `Nesting is the hierarchy — a child sits strictly below its parent.`,
+          });
+        }
+      }
+    }
+
+    // -- the link boundary ----------------------------------------------------
+    if (refs.length > 0 && !req.mayReferenceModel()) {
+      out.push({
+        severity: "error", code: ERR_REQUIREMENT_LINK_ABOVE_FLOOR, name: req.name,
+        message: `'implementedBy' is legal at L${REQUIREMENT_LINK_FLOOR_LEVEL} (object) and ` +
+          `L${REQUIREMENT_MAX_LEVEL} (member) only. L1-L3 are organisational and never reference ` +
+          `the model — move the links to a nested L${REQUIREMENT_LINK_FLOOR_LEVEL} child.`,
+      });
+      continue;
+    }
+
+    for (const ref of refs) {
+      const { owner, path } = splitMemberRef(ref);
+      // referrerPkg is the requirement's own effective package, so a bare ref
+      // binds package-locally under the ADR-0042 contract — the loader's own
+      // resolver, never a parallel name scan (#228).
+      const referrerPkg = req.package ?? req.fileDefaultPackage ?? "";
+      const { node } = resolveObjectRef(root, owner, referrerPkg);
+      const isObjectRef = path.length === 0;
+
+      if (node !== undefined && (isObjectRef || resolveMember(node, path) !== undefined)) {
+        claimedObjects.add(node.resolutionKey());
+      }
+
+      if (!architectural && level === REQUIREMENT_LINK_FLOOR_LEVEL && !isObjectRef) {
+        out.push({
+          severity: "error", code: ERR_REQUIREMENT_L4_NOT_OBJECT, name: req.name,
+          message: `L${REQUIREMENT_LINK_FLOOR_LEVEL} references an object; '${ref}' names a member. ` +
+            `Move it to a nested L${REQUIREMENT_LEVEL_MEMBER} child, or reference the object itself.`,
+        });
+        continue;
+      }
+      if (!architectural && level === REQUIREMENT_LEVEL_MEMBER && isObjectRef) {
+        out.push({
+          severity: "error", code: ERR_REQUIREMENT_L5_NOT_MEMBER, name: req.name,
+          message: `L${REQUIREMENT_LEVEL_MEMBER} references a member (field, view or identity); ` +
+            `'${ref}' names an object. Move it to its L${REQUIREMENT_LINK_FLOOR_LEVEL} parent.`,
+        });
+        continue;
+      }
+
+      const resolved = node !== undefined && (isObjectRef || resolveMember(node, path) !== undefined);
+      if (!resolved) {
+        // Severity is CONDITIONAL ON STATUS, and the asymmetry inverts as a pair.
+        // On abandoned/superseded the nodes are SUPPOSED to be gone — that is the
+        // entry doing its job, and the reason this check cannot live in the loader.
+        if (req.requiresLiveNodes()) {
+          out.push({
+            severity: "error", code: ERR_REQUIREMENT_DANGLING_REF, name: req.name,
+            message: `'${ref}' does not resolve in the loaded model (status '${String(req.status())}' — ` +
+              `the model moved and the requirement is stale).` + didYouMeanHint(root, owner),
+          });
+        }
+      }
+    }
+
+    // -- architectural universality, v1: claim-set arithmetic -----------------
+    // A live policy claimed by nothing is the audited-base case: declared and
+    // applied to nothing. Deliberately NOT a violation-predicate DSL — that
+    // would be the registration this design already argued its way to, arriving
+    // a second time through the back door.
+    const status = req.status();
+    const live = status !== undefined
+      && REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES.includes(status as RequirementStatus);
+    if (architectural && live && refs.length === 0) {
+      out.push({
+        severity: "error", code: ERR_REQUIREMENT_ARCH_NO_IMPLEMENTERS, name: req.name,
+        message: `architectural requirement is '${String(status)}' but nothing implements it. ` +
+          `Its check is universality — a claim set of zero means the policy is declared and unapplied.`,
+      });
+    }
+  }
+
+  // -- object coverage: adding an entity forces a requirement -----------------
+  // Binary per entity, never a ratio: a "% claimed" number measures what the
+  // schema can express, is biased against the hardest rules, and invites
+  // optimising the number.
+  //
+  // SCOPE, stated because it is a decision and not an oversight:
+  //
+  //   ENTITIES ONLY. `object.value` and `object.projection` are exempt. A value is a
+  //   shape (a DTO, a payload, a message) and a projection is DERIVED from an entity
+  //   that is itself claimable — requiring both to carry their own capability claim
+  //   would multiply entries without adding information.
+  //
+  //   OBJECT GRAIN ONLY. Fields, views, validators and identities are never required
+  //   to be claimed. Member-grain coverage is the "thousands of meaningless links"
+  //   failure `spec/capability-ledger.md` argues against: plumbing members are covered
+  //   by ARCHITECTURAL requirements with high fan-out (one uuid-PK rule claims every
+  //   entity), not by a per-member entry. L5 exists so a claim about a specific member
+  //   CAN be made when it carries real meaning — never so that every member must.
+  //
+  // So a green run means "every entity is claimed by something", not "every node is
+  // described". The stronger reading would be false.
+  for (const ent of root.children()) {
+    if (ent.type !== TYPE_OBJECT || ent.subType !== OBJECT_SUBTYPE_ENTITY) continue;
+    const key = ent.resolutionKey();
+    if (!claimedObjects.has(key)) {
+      out.push({
+        severity: OBJECT_COVERAGE_SEVERITY, code: WARN_REQUIREMENT_OBJECT_UNCLAIMED,
+        message: `no requirement claims '${key}'. Add it to an L${REQUIREMENT_LINK_FLOOR_LEVEL} requirement's 'implementedBy'.`,
+      });
+    }
+  }
+
+  return out;
+}