@metaobjectsdev/cli 0.21.5 → 0.22.0-rc.1

package/dist/src/lib/requirement-check.js

@@ -0,0 +1,234 @@
+// `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, } from "@metaobjectsdev/metadata";
+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 = "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) {
+    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, path) {
+    let cur = 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) {
+    const out = [];
+    const walk = (n) => {
+        for (const c of n.children()) {
+            if (c.type === TYPE_REQUIREMENT)
+                out.push(c);
+            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) {
+    const out = [];
+    const reqs = collectRequirements(root);
+    if (reqs.length === 0)
+        return out; // opt-in by declaration — no requirements, nothing to say
+    const claimedObjects = new Set();
+    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.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);
+        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;
+}
+//# sourceMappingURL=requirement-check.js.map

package/dist/src/lib/requirement-check.js.map

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

package/dist/src/lib/verified-by-scan.d.ts

@@ -0,0 +1,18 @@
+import { type MetaData } from "@metaobjectsdev/metadata";
+export declare const ERR_REQUIREMENT_TEST_MISSING = "ERR_REQUIREMENT_TEST_MISSING";
+export declare const WARN_REQUIREMENT_TEST_SKIPPED = "WARN_REQUIREMENT_TEST_SKIPPED";
+export interface VerifiedByDiagnostic {
+    severity: "error" | "warn";
+    code: string;
+    name?: string;
+    message: string;
+}
+/**
+ * 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 declare function checkVerifiedBy(root: MetaData, cwd: string): VerifiedByDiagnostic[];
+//# sourceMappingURL=verified-by-scan.d.ts.map

package/dist/src/lib/verified-by-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verified-by-scan.d.ts","sourceRoot":"","sources":["../../../src/lib/verified-by-scan.ts"],"names":[],"mappings":"AA0BA,OAAO,EAEL,KAAK,QAAQ,EAEd,MAAM,0BAA0B,CAAC;AAElC,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAC3E,eAAO,MAAM,6BAA6B,kCAAkC,CAAC;AAE7E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AA0FD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAoDnF"}

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":"AAAA,2CAA2C;AAC3C,EAAE;AACF,iFAAiF;AACjF,kFAAkF;AAClF,iFAAiF;AACjF,6CAA6C;AAC7C,EAAE;AACF,kFAAkF;AAClF,mFAAmF;AACnF,gFAAgF;AAChF,4CAA4C;AAC5C,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,kFAAkF;AAClF,kFAAkF;AAClF,mFAAmF;AACnF,oCAAoC;AACpC,EAAE;AACF,iFAAiF;AACjF,gFAAgF;AAChF,gFAAgF;AAChF,+CAA+C;AAE/C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EACL,gBAAgB,GAGjB,MAAM,0BAA0B,CAAC;AAElC,MAAM,CAAC,MAAM,4BAA4B,GAAG,8BAA8B,CAAC;AAC3E,MAAM,CAAC,MAAM,6BAA6B,GAAG,+BAA+B,CAAC;AAS7E,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;IAC9B,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU;IACnE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM;CACpF,CAAC,CAAC;AAEH,mEAAmE;AACnE,MAAM,SAAS,GAAG,IAAI,MAAM,CAC1B;IACE,kCAAkC,EAAE,8BAA8B;IAClE,kCAAkC,EAAE,uBAAuB;IAC3D,+BAA+B,EAAE,2CAA2C;IAC5E,yBAAyB,EAAE,0BAA0B;IACrD,mBAAmB,EAAE,yBAAyB;IAC9C,kBAAkB,EAAE,+CAA+C;IACnE,6BAA6B,EAAE,eAAe;CAC/C,CAAC,IAAI,CAAC,GAAG,CAAC,CACZ,CAAC;AAEF,8EAA8E;AAC9E,MAAM,WAAW,GAAG,IAAI,MAAM,CAC5B;IACE,4CAA4C,EAAE,kBAAkB;IAChE,6BAA6B,EAAE,8BAA8B;IAC7D,cAAc,EAAE,uCAAuC;IACvD,YAAY,EAAE,kDAAkD;IAChE,uBAAuB,EAAE,6BAA6B;IACtD,iBAAiB,EAAE,2CAA2C;IAC9D,cAAc,EAAE,2DAA2D;CAC5E,CAAC,IAAI,CAAC,GAAG,CAAC,CACZ,CAAC;AAQF,SAAS,IAAI,CAAC,GAAW,EAAE,IAAY,EAAE,GAAe,EAAE,KAAK,GAAG,CAAC;IACjE,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,CAAC,2DAA2D;IACnF,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YACpB,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,SAAS;YACpE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAC9C,SAAS;QACX,CAAC;QACD,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,SAAS;QACrD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC;YACH,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,GAAG,GAAG,IAAI;gBAAE,SAAS;YAC9C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YAChG,GAAG,CAAC,KAAK,EAAE,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,sCAAsC;QACxC,CAAC;IACH,CAAC;AACH,CAAC;AAED,oEAAoE;AACpE,SAAS,OAAO,CAAC,IAAc;IAC7B,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,MAAM,GAAG,GAAG,CAAC,CAAW,EAAQ,EAAE;QAChC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;YAC7B,IAAI,CAAC,CAAC,IAAI,KAAK,gBAAgB;gBAAE,GAAG,CAAC,IAAI,CAAC,CAAoB,CAAC,CAAC;YAChE,GAAG,CAAC,CAAC,CAAC,CAAC;QACT,CAAC;IACH,CAAC,CAAC;IACF,GAAG,CAAC,IAAI,CAAC,CAAC;IACV,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,MAAM,CAAC,IAAY;IAC1B,OAAO,IAAI,MAAM,CAAC,qBAAqB,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAC;AACvG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAc,EAAE,GAAW;IACzD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACpE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC,CAAC,wBAAwB;IAE1D,MAAM,MAAM,GAAe,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IAC3D,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IACvB,IAAI,MAAM,CAAC,KAAK,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC,CAAC,sCAAsC;IAEzE,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,UAAU,EAAE,EAAE,CAAC;YACpC,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;YACxB,IAAI,OAA2B,CAAC;YAChC,IAAI,SAA6B,CAAC;YAClC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;oBACtC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;wBAAE,SAAS;oBACvC,OAAO,KAAK,IAAI,CAAC;oBACjB,gEAAgE;oBAChE,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACjE,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC;wBAAE,SAAS,KAAK,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBACjE,CAAC;gBACD,IAAI,OAAO,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS;oBAAE,MAAM;YAC9D,CAAC;YAED,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,IAAI,GAAG,CAAC,iBAAiB,EAAE,EAAE,CAAC;oBAC5B,GAAG,CAAC,IAAI,CAAC;wBACP,QAAQ,EAAE,OAAO;wBACjB,IAAI,EAAE,4BAA4B;wBAClC,IAAI,EAAE,GAAG,CAAC,IAAI;wBACd,OAAO,EACL,uBAAuB,IAAI,kCAAkC;4BAC7D,GAAG,MAAM,CAAC,KAAK,8DAA8D;4BAC7E,kDAAkD;qBACrD,CAAC,CAAC;gBACL,CAAC;gBACD,SAAS;YACX,CAAC;YACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,GAAG,CAAC,IAAI,CAAC;oBACP,QAAQ,EAAE,MAAM;oBAChB,IAAI,EAAE,6BAA6B;oBACnC,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,OAAO,EACL,uBAAuB,IAAI,4BAA4B,SAAS,IAAI;wBACpE,+EAA+E;iBAClF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/cli",
-  "version": "0.21.5",
+  "version": "0.22.0-rc.1",
   "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.5",
-    "@metaobjectsdev/codegen-ts-react": "0.21.5",
-    "@metaobjectsdev/codegen-ts-tanstack": "0.21.5",
-    "@metaobjectsdev/docs-site": "0.21.5",
-    "@metaobjectsdev/metadata": "0.21.5",
-    "@metaobjectsdev/migrate-ts": "0.21.5",
-    "@metaobjectsdev/render": "0.21.5",
-    "@metaobjectsdev/runtime-ts": "0.21.5",
-    "@metaobjectsdev/sdk": "0.21.5",
+    "@metaobjectsdev/codegen-ts": "0.22.0-rc.1",
+    "@metaobjectsdev/codegen-ts-react": "0.22.0-rc.1",
+    "@metaobjectsdev/codegen-ts-tanstack": "0.22.0-rc.1",
+    "@metaobjectsdev/docs-site": "0.22.0-rc.1",
+    "@metaobjectsdev/metadata": "0.22.0-rc.1",
+    "@metaobjectsdev/migrate-ts": "0.22.0-rc.1",
+    "@metaobjectsdev/render": "0.22.0-rc.1",
+    "@metaobjectsdev/runtime-ts": "0.22.0-rc.1",
+    "@metaobjectsdev/sdk": "0.22.0-rc.1",
     "@toon-format/toon": "^2.3.0",
     "jiti": "^2.4.0"
   },

package/src/commands/init.ts

@@ -523,13 +523,19 @@ async function ensureEsmPackageType(cwd: string, result: InitResult): Promise<vo
 
 /**
  * ADR-0034 scaffold-and-own hands the project real source files under
- * `codegen/generators/`, and those files import `@metaobjectsdev/codegen-ts`,
- * `@metaobjectsdev/metadata` and `ts-poet`. Installing `@metaobjectsdev/cli` alone
- * does not put any of them where the project can resolve them, so the scaffold
- * arrived un-typecheckable: ten TS2307s on files `meta init` had just written.
+ * `codegen/generators/`, and those files import `@metaobjectsdev/codegen-ts` and
+ * `@metaobjectsdev/metadata`. Installing `@metaobjectsdev/cli` alone does not put
+ * either of them where the project can resolve them, so the scaffold arrived
+ * un-typecheckable: ten TS2307s on files `meta init` had just written.
  *
  * Declaring them is the honest fix — they are dependencies of code that now lives in
- * the adopter's repo. Only ever ADDS a missing key: an existing pin is the user's.
+ * the adopter's repo. Deliberately NOT declared: `ts-poet`. The scaffolded templates
+ * import the ts-poet combinators via @metaobjectsdev/codegen-ts (re-exported from its
+ * own ts-poet instance) precisely so that the Code objects they compose share ONE
+ * ts-poet copy with the engine's render* primitives — a project-local ts-poet is the
+ * second physical copy that split the class identity under a globally-installed /
+ * linked CLI (duplicate imports in generated files, TS2300 on first tsc; see the
+ * gen-split-tree gate). Only ever ADDS a missing key: an existing pin is the user's.
  * Returns what it added so the caller can tell them to install.
  */
 function addScaffoldDevDependencies(pkg: Record<string, unknown>): string[] {
@@ -537,7 +543,6 @@ function addScaffoldDevDependencies(pkg: Record<string, unknown>): string[] {
   const wanted: Record<string, string> = {
     "@metaobjectsdev/codegen-ts": `^${version}`,
     "@metaobjectsdev/metadata": `^${version}`,
-    "ts-poet": "^6.10.0",
   };
   const dev = (pkg.devDependencies ?? {}) as Record<string, string>;
   const deps = (pkg.dependencies ?? {}) as Record<string, string>;

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);
 }