@ybotok/loam 0.2.0-alpha.5 → 0.2.0-alpha.7

package/dist/commands/validate/service/spine.js

@@ -13,11 +13,13 @@
  * PRODUCER owns the contract and it lives in another repository, so the two
  * could not share a walk even though they share the shape.
  */
+import { relative } from "node:path";
 import {} from "../../../core/kernel/ids/service.js";
 import {} from "../../../core/c4/likec4.js";
+import {} from "../../../core/kernel/ids/dirs.js";
 import {} from "../../../core/kernel/ids/service.js";
 import {} from "../../../core/vocabulary/report.js";
-import { errorText } from "../checks/vocabulary.js";
+import { errorText } from "../../../core/c4/likec4.js";
 import {} from "./api.js";
 export function spineFindings(spine) {
     const { service, me, land, landSvcOf, contract } = spine;
@@ -35,15 +37,51 @@ export function spineFindings(spine) {
             // becomes N copies of a dozen cascading diagnostics on a fleet of N
             // services — the report stops being readable at exactly the moment
             // somebody needs to read it, and the fix is one file either way.
+            // Which DOCUMENT broke, spelled exactly as the fleet arm spells it
+            // (`fleet/landscape.ts`): `land` is the whole `architecture/` project, so
+            // the broken file is as often a `usecases/*.likec4` as the map itself,
+            // and the filename used to be hardcoded here — an agent told to "fix the
+            // file the message names" opened a document that parses (verification
+            // 2026-09-04, W2).
+            const broken = [
+                ...new Set(land.errors.map((e) => e.sourceFsPath).filter((p) => p !== undefined)),
+            ]
+                .map((abs) => relative(spine.docsDir, abs).split(/[\\/]/).join("/"))
+                .sort();
+            const named = broken.length === 0 ? "architecture/landscape.likec4" : broken.join(", ");
+            // The verb agrees with the LIST, not with the count after it: `named` is a
+            // comma-joined series once two documents broke, and "a, b, c has 6
+            // error(s)" is a sentence a reader trips over — the same care `remedy()`
+            // in model/diverged.ts takes over "the kind differ".
+            const verb = broken.length > 1 ? "have" : "has";
             findings.push({
                 severity: "error",
                 code: "spine.landscape-invalid",
                 subject: service,
-                message: `${service}: landscape.likec4 has ${land.errors.length} error(s) — spine check impossible` +
+                message: `${service}: ${named} ${verb} ${land.errors.length} error(s) — spine check impossible` +
+                    (spine.modelExtends === true
+                        ? " — and model.likec4 extends it, so the model cannot be read either"
+                        : "") +
                     (spine.landscapeReported === true
                         ? "; the parser output is reported once, on the landscape target"
                         : ""),
-                ...(spine.landscapeReported === true ? {} : { details: land.errors.map(errorText) }),
+                ...(spine.landscapeReported === true
+                    ? {}
+                    : {
+                        // Every line carries its own file once more than one document is
+                        // broken, the fleet arm's rule verbatim: a bare `L8:` across two
+                        // documents is unactionable.
+                        details: land.errors.map((e) => e.sourceFsPath === undefined || broken.length < 2
+                            ? errorText(e)
+                            : `${relative(spine.docsDir, e.sourceFsPath).split(/[\\/]/).join("/")} ${errorText(e)}`),
+                    }),
+                // The broken document first, the service second: the finding is about a
+                // file under `architecture/` and is FILED on this service, and without
+                // the pair the payload carried only the service directory.
+                locations: [
+                    ...(broken.length === 0 ? [] : [{ path: broken[0], role: "primary" }]),
+                    { path: spine.treePath, role: "scope" },
+                ],
             });
         }
         else {

package/dist/commands/validate/service/spine.js.map

@@ -1 +1 @@
-{"version":3,"file":"spine.js","sourceRoot":"","sources":["../../../../src/commands/validate/service/spine.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The inbound half of the C4↔API spine: every cross-system edge the living\n * landscape draws INTO this service must resolve to a real operation in its\n * OpenAPI.\n *\n * Separate from `./api.js` because the two grade different documents and the\n * fix lives in different files — a broken edge is the fleet map's mistake, a\n * missing operation is the contract's — but it may conclude nothing without\n * `api.js`'s answer, which is why `ServiceContract` is a parameter rather than\n * a second read of openapi.yaml.\n *\n * The event-side mirror of this check is inside `./events.js`: there the\n * PRODUCER owns the contract and it lives in another repository, so the two\n * could not share a walk even though they share the shape.\n */\nimport { type DeclaredService } from \"../../../core/kernel/ids/service.js\";\nimport { type LoadedDoc } from \"../../../core/c4/likec4.js\";\nimport { type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { errorText } from \"../checks/vocabulary.js\";\nimport { type ServiceContract } from \"./api.js\";\n\n/** What the service target hands the spine check. */\nexport interface Spine {\n  service: PathableService;\n  /** `service` widened for `===` against the resolver's DOCUMENT text — see service.ts. */\n  me: string;\n  /** The living landscape, or null when the repo has none. */\n  land: LoadedDoc | null;\n  /** Its element→service resolver; null exactly when `land` is. */\n  landSvcOf: ((id: string) => DeclaredService) | null;\n  contract: ServiceContract;\n  /** True when this run also emits a landscape target — see `ServiceCheck`. */\n  landscapeReported?: boolean;\n}\n\nexport function spineFindings(spine: Spine): Finding[] {\n  const { service, me, land, landSvcOf, contract } = spine;\n  const findings: Finding[] = [];\n\n  // Landscape spine: cross-system edges calling THIS service must resolve to a real\n  // operation in its OpenAPI — the C4↔API contract, checked in the living landscape,\n  // not only in feature mode. Catches dangling / de-linked op edges.\n  if (land !== null) {\n    if (land.errors.length > 0) {\n      // A living landscape that does not parse disables the C4↔API spine check —\n      // that is a broken source of truth, not a skippable detail.\n      //\n      // The parser's own output is attached ONCE per run, and not here when the\n      // run has a landscape target to carry it. One syntax error in one file\n      // becomes N copies of a dozen cascading diagnostics on a fleet of N\n      // services — the report stops being readable at exactly the moment\n      // somebody needs to read it, and the fix is one file either way.\n      findings.push({\n        severity: \"error\",\n        code: \"spine.landscape-invalid\",\n        subject: service,\n        message:\n          `${service}: landscape.likec4 has ${land.errors.length} error(s) — spine check impossible` +\n          (spine.landscapeReported === true\n            ? \"; the parser output is reported once, on the landscape target\"\n            : \"\"),\n        ...(spine.landscapeReported === true ? {} : { details: land.errors.map(errorText) }),\n      });\n    } else {\n      // Which element IS this service is the binding's call, then a title that\n      // names a real services/<id>/, and an edge into a modelled container\n      // counts as an edge into its service — matching the exact id alone meant a\n      // container edge left the spine without a word.\n      const svcOf = landSvcOf!;\n      const opset = new Set(contract.ops);\n      let checked = 0;\n      let broken = 0;\n      for (const r of land.relationships) {\n        if (svcOf(r.target) !== me) continue;\n        if (r.op !== undefined) {\n          // A contract that cannot be read — broken, or not there at all —\n          // proves nothing about this edge, neither broken nor resolved.\n          // Grading the edges against an empty operation set turned ONE root\n          // cause (the file) into one `spine.op-undefined` per inbound edge, so\n          // a service with twelve consumers reported twelve landscape defects\n          // and never named the file. `openapi.invalid` / `service.no-openapi`\n          // already did, from ./api.js; only op-link-missing (which never reads\n          // the contract) stays live, and `checked` stays 0 so no false\n          // spine.resolved is claimed either.\n          if (contract.unreadable) continue;\n          checked += 1;\n          if (!opset.has(r.op)) {\n            broken += 1;\n            findings.push({\n              severity: \"error\",\n              code: \"spine.op-undefined\",\n              message: `${service}: landscape edge ${svcOf(r.source)} → ${service} calls '${r.op}', not defined in ${service}'s OpenAPI`,\n            });\n          } else if (contract.deprecated.has(r.op)) {\n            // The contract holds — the op is defined — but it is marked\n            // `deprecated: true`: the consumer is standing on a contract being\n            // retired, and should be migrating off it. Warn per inbound edge;\n            // a deprecated op nobody calls raises no spine finding at all.\n            findings.push({\n              severity: \"warn\",\n              code: \"spine.op-deprecated\",\n              message: `${service}: landscape edge ${svcOf(r.source)} → ${service} calls '${r.op}', which ${service}'s OpenAPI marks deprecated — the consumer should migrate off it`,\n            });\n          }\n        } else if ((r.title ?? \"\").toLowerCase().startsWith(\"call\")) {\n          findings.push({\n            severity: \"warn\",\n            code: \"spine.op-link-missing\",\n            message: `${service}: landscape edge ${svcOf(r.source)} → ${service} (\"${r.title}\") has no operation link (metadata { op })`,\n          });\n        }\n      }\n      if (broken === 0 && checked > 0) {\n        findings.push({\n          severity: \"ok\",\n          code: \"spine.resolved\",\n          message: `${service}: landscape spine (${checked} inbound call(s) resolve to OpenAPI)`,\n        });\n      }\n    }\n  }\n\n  return findings;\n}\n"]}
+{"version":3,"file":"spine.js","sourceRoot":"","sources":["../../../../src/commands/validate/service/spine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAwB,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EAAkB,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAgB,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAwB,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EAAgB,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAwB,MAAM,UAAU,CAAC;AAiChD,MAAM,UAAU,aAAa,CAAC,KAAY;IACxC,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IACzD,MAAM,QAAQ,GAAc,EAAE,CAAC;IAE/B,kFAAkF;IAClF,mFAAmF;IACnF,mEAAmE;IACnE,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,2EAA2E;YAC3E,4DAA4D;YAC5D,EAAE;YACF,0EAA0E;YAC1E,uEAAuE;YACvE,oEAAoE;YACpE,mEAAmE;YACnE,iEAAiE;YACjE,mEAAmE;YACnE,0EAA0E;YAC1E,uEAAuE;YACvE,yEAAyE;YACzE,sEAAsE;YACtE,mBAAmB;YACnB,MAAM,MAAM,GAAG;gBACb,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;aAC/F;iBACE,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;iBACnE,IAAI,EAAE,CAAC;YACV,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxF,2EAA2E;YAC3E,mEAAmE;YACnE,yEAAyE;YACzE,qDAAqD;YACrD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;YAChD,QAAQ,CAAC,IAAI,CAAC;gBACZ,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,yBAAyB;gBAC/B,OAAO,EAAE,OAAO;gBAChB,OAAO,EACL,GAAG,OAAO,KAAK,KAAK,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,oCAAoC;oBACtF,CAAC,KAAK,CAAC,YAAY,KAAK,IAAI;wBAC1B,CAAC,CAAC,oEAAoE;wBACtE,CAAC,CAAC,EAAE,CAAC;oBACP,CAAC,KAAK,CAAC,iBAAiB,KAAK,IAAI;wBAC/B,CAAC,CAAC,+DAA+D;wBACjE,CAAC,CAAC,EAAE,CAAC;gBACT,GAAG,CAAC,KAAK,CAAC,iBAAiB,KAAK,IAAI;oBAClC,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC;wBACE,iEAAiE;wBACjE,iEAAiE;wBACjE,6BAA6B;wBAC7B,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC7B,CAAC,CAAC,YAAY,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;4BAC/C,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;4BACd,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,CAC1F;qBACF,CAAC;gBACN,wEAAwE;gBACxE,uEAAuE;gBACvE,2DAA2D;gBAC3D,SAAS,EAAE;oBACT,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,SAAkB,EAAE,CAAC,CAAC;oBAChF,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAgB,EAAE;iBACjD;aACF,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,yEAAyE;YACzE,qEAAqE;YACrE,2EAA2E;YAC3E,gDAAgD;YAChD,MAAM,KAAK,GAAG,SAAU,CAAC;YACzB,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YACpC,IAAI,OAAO,GAAG,CAAC,CAAC;YAChB,IAAI,MAAM,GAAG,CAAC,CAAC;YACf,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;gBACnC,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE;oBAAE,SAAS;gBACrC,IAAI,CAAC,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;oBACvB,iEAAiE;oBACjE,+DAA+D;oBAC/D,mEAAmE;oBACnE,sEAAsE;oBACtE,oEAAoE;oBACpE,qEAAqE;oBACrE,sEAAsE;oBACtE,8DAA8D;oBAC9D,oCAAoC;oBACpC,IAAI,QAAQ,CAAC,UAAU;wBAAE,SAAS;oBAClC,OAAO,IAAI,CAAC,CAAC;oBACb,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;wBACrB,MAAM,IAAI,CAAC,CAAC;wBACZ,QAAQ,CAAC,IAAI,CAAC;4BACZ,QAAQ,EAAE,OAAO;4BACjB,IAAI,EAAE,oBAAoB;4BAC1B,OAAO,EAAE,GAAG,OAAO,oBAAoB,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC,EAAE,qBAAqB,OAAO,YAAY;yBAC3H,CAAC,CAAC;oBACL,CAAC;yBAAM,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;wBACzC,4DAA4D;wBAC5D,mEAAmE;wBACnE,kEAAkE;wBAClE,+DAA+D;wBAC/D,QAAQ,CAAC,IAAI,CAAC;4BACZ,QAAQ,EAAE,MAAM;4BAChB,IAAI,EAAE,qBAAqB;4BAC3B,OAAO,EAAE,GAAG,OAAO,oBAAoB,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC,EAAE,YAAY,OAAO,kEAAkE;yBACxK,CAAC,CAAC;oBACL,CAAC;gBACH,CAAC;qBAAM,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC5D,QAAQ,CAAC,IAAI,CAAC;wBACZ,QAAQ,EAAE,MAAM;wBAChB,IAAI,EAAE,uBAAuB;wBAC7B,OAAO,EAAE,GAAG,OAAO,oBAAoB,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC,KAAK,4CAA4C;qBAC7H,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YACD,IAAI,MAAM,KAAK,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;gBAChC,QAAQ,CAAC,IAAI,CAAC;oBACZ,QAAQ,EAAE,IAAI;oBACd,IAAI,EAAE,gBAAgB;oBACtB,OAAO,EAAE,GAAG,OAAO,sBAAsB,OAAO,sCAAsC;iBACvF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * The inbound half of the C4↔API spine: every cross-system edge the living\n * landscape draws INTO this service must resolve to a real operation in its\n * OpenAPI.\n *\n * Separate from `./api.js` because the two grade different documents and the\n * fix lives in different files — a broken edge is the fleet map's mistake, a\n * missing operation is the contract's — but it may conclude nothing without\n * `api.js`'s answer, which is why `ServiceContract` is a parameter rather than\n * a second read of openapi.yaml.\n *\n * The event-side mirror of this check is inside `./events.js`: there the\n * PRODUCER owns the contract and it lives in another repository, so the two\n * could not share a walk even though they share the shape.\n */\nimport { relative } from \"node:path\";\nimport { type DeclaredService } from \"../../../core/kernel/ids/service.js\";\nimport { type LoadedDoc } from \"../../../core/c4/likec4.js\";\nimport { type DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { errorText } from \"../../../core/c4/likec4.js\";\nimport { type ServiceContract } from \"./api.js\";\n\n/** What the service target hands the spine check. */\nexport interface Spine {\n  service: PathableService;\n  /** The docs root, so a project error's absolute path can be spelled repo-relative. */\n  docsDir: DocsDir;\n  /** The service directory, repo-relative and `/`-separated — the scope location beside the broken file. */\n  treePath: string;\n  /** `service` widened for `===` against the resolver's DOCUMENT text — see service.ts. */\n  me: string;\n  /** The living landscape, or null when the repo has none. */\n  land: LoadedDoc | null;\n  /** Its element→service resolver; null exactly when `land` is. */\n  landSvcOf: ((id: string) => DeclaredService) | null;\n  contract: ServiceContract;\n  /** True when this run also emits a landscape target — see `ServiceCheck`. */\n  landscapeReported?: boolean;\n  /**\n   * True when this service's `model.likec4` EXTENDS the map rather than\n   * standing alone (`core/c4/service-model/shape.ts`).\n   *\n   * It changes one sentence and no verdict. An extending model is parsed inside\n   * the `architecture/` project, so a map that does not parse takes the model\n   * with it: there is no `c4.invalid` and no `c4.valid` on the service target,\n   * and without this clause the report shows a service whose model is simply\n   * never mentioned. Said here rather than as a finding of its own because it is\n   * the same fact — one unreadable document — and a second code would be a\n   * second thing to fix for one repair.\n   */\n  modelExtends?: boolean;\n}\n\nexport function spineFindings(spine: Spine): Finding[] {\n  const { service, me, land, landSvcOf, contract } = spine;\n  const findings: Finding[] = [];\n\n  // Landscape spine: cross-system edges calling THIS service must resolve to a real\n  // operation in its OpenAPI — the C4↔API contract, checked in the living landscape,\n  // not only in feature mode. Catches dangling / de-linked op edges.\n  if (land !== null) {\n    if (land.errors.length > 0) {\n      // A living landscape that does not parse disables the C4↔API spine check —\n      // that is a broken source of truth, not a skippable detail.\n      //\n      // The parser's own output is attached ONCE per run, and not here when the\n      // run has a landscape target to carry it. One syntax error in one file\n      // becomes N copies of a dozen cascading diagnostics on a fleet of N\n      // services — the report stops being readable at exactly the moment\n      // somebody needs to read it, and the fix is one file either way.\n      // Which DOCUMENT broke, spelled exactly as the fleet arm spells it\n      // (`fleet/landscape.ts`): `land` is the whole `architecture/` project, so\n      // the broken file is as often a `usecases/*.likec4` as the map itself,\n      // and the filename used to be hardcoded here — an agent told to \"fix the\n      // file the message names\" opened a document that parses (verification\n      // 2026-09-04, W2).\n      const broken = [\n        ...new Set(land.errors.map((e) => e.sourceFsPath).filter((p): p is string => p !== undefined)),\n      ]\n        .map((abs) => relative(spine.docsDir, abs).split(/[\\\\/]/).join(\"/\"))\n        .sort();\n      const named = broken.length === 0 ? \"architecture/landscape.likec4\" : broken.join(\", \");\n      // The verb agrees with the LIST, not with the count after it: `named` is a\n      // comma-joined series once two documents broke, and \"a, b, c has 6\n      // error(s)\" is a sentence a reader trips over — the same care `remedy()`\n      // in model/diverged.ts takes over \"the kind differ\".\n      const verb = broken.length > 1 ? \"have\" : \"has\";\n      findings.push({\n        severity: \"error\",\n        code: \"spine.landscape-invalid\",\n        subject: service,\n        message:\n          `${service}: ${named} ${verb} ${land.errors.length} error(s) — spine check impossible` +\n          (spine.modelExtends === true\n            ? \" — and model.likec4 extends it, so the model cannot be read either\"\n            : \"\") +\n          (spine.landscapeReported === true\n            ? \"; the parser output is reported once, on the landscape target\"\n            : \"\"),\n        ...(spine.landscapeReported === true\n          ? {}\n          : {\n              // Every line carries its own file once more than one document is\n              // broken, the fleet arm's rule verbatim: a bare `L8:` across two\n              // documents is unactionable.\n              details: land.errors.map((e) =>\n                e.sourceFsPath === undefined || broken.length < 2\n                  ? errorText(e)\n                  : `${relative(spine.docsDir, e.sourceFsPath).split(/[\\\\/]/).join(\"/\")} ${errorText(e)}`,\n              ),\n            }),\n        // The broken document first, the service second: the finding is about a\n        // file under `architecture/` and is FILED on this service, and without\n        // the pair the payload carried only the service directory.\n        locations: [\n          ...(broken.length === 0 ? [] : [{ path: broken[0]!, role: \"primary\" as const }]),\n          { path: spine.treePath, role: \"scope\" as const },\n        ],\n      });\n    } else {\n      // Which element IS this service is the binding's call, then a title that\n      // names a real services/<id>/, and an edge into a modelled container\n      // counts as an edge into its service — matching the exact id alone meant a\n      // container edge left the spine without a word.\n      const svcOf = landSvcOf!;\n      const opset = new Set(contract.ops);\n      let checked = 0;\n      let broken = 0;\n      for (const r of land.relationships) {\n        if (svcOf(r.target) !== me) continue;\n        if (r.op !== undefined) {\n          // A contract that cannot be read — broken, or not there at all —\n          // proves nothing about this edge, neither broken nor resolved.\n          // Grading the edges against an empty operation set turned ONE root\n          // cause (the file) into one `spine.op-undefined` per inbound edge, so\n          // a service with twelve consumers reported twelve landscape defects\n          // and never named the file. `openapi.invalid` / `service.no-openapi`\n          // already did, from ./api.js; only op-link-missing (which never reads\n          // the contract) stays live, and `checked` stays 0 so no false\n          // spine.resolved is claimed either.\n          if (contract.unreadable) continue;\n          checked += 1;\n          if (!opset.has(r.op)) {\n            broken += 1;\n            findings.push({\n              severity: \"error\",\n              code: \"spine.op-undefined\",\n              message: `${service}: landscape edge ${svcOf(r.source)} → ${service} calls '${r.op}', not defined in ${service}'s OpenAPI`,\n            });\n          } else if (contract.deprecated.has(r.op)) {\n            // The contract holds — the op is defined — but it is marked\n            // `deprecated: true`: the consumer is standing on a contract being\n            // retired, and should be migrating off it. Warn per inbound edge;\n            // a deprecated op nobody calls raises no spine finding at all.\n            findings.push({\n              severity: \"warn\",\n              code: \"spine.op-deprecated\",\n              message: `${service}: landscape edge ${svcOf(r.source)} → ${service} calls '${r.op}', which ${service}'s OpenAPI marks deprecated — the consumer should migrate off it`,\n            });\n          }\n        } else if ((r.title ?? \"\").toLowerCase().startsWith(\"call\")) {\n          findings.push({\n            severity: \"warn\",\n            code: \"spine.op-link-missing\",\n            message: `${service}: landscape edge ${svcOf(r.source)} → ${service} (\"${r.title}\") has no operation link (metadata { op })`,\n          });\n        }\n      }\n      if (broken === 0 && checked > 0) {\n        findings.push({\n          severity: \"ok\",\n          code: \"spine.resolved\",\n          message: `${service}: landscape spine (${checked} inbound call(s) resolve to OpenAPI)`,\n        });\n      }\n    }\n  }\n\n  return findings;\n}\n"]}

package/dist/commands/validate/service/usecases/tags.js

@@ -0,0 +1,113 @@
+/**
+ * The two tag grades of a SERVICE-LOCAL use case: `usecase.requirement-unresolved`
+ * with service-worded arms, and `usecase.capability-unresolved`'s placement arm.
+ *
+ * Both codes are REUSED from the fleet target rather than minted, under
+ * add-error-code's "prefer existing" rule: a caller acts the same way (fix the
+ * tag, or the `Requirement-ID:` line it names), and only the sentences differ.
+ * The fleet's own graders (`../../fleet/usecases/{requirement,capability}-tag.ts`)
+ * are not reused for the sentences, because every one of theirs names a
+ * capability document, and a service-local flow has none.
+ *
+ * WHY `#req-` IS SCOPED BY THE SERVICE. Inside `architecture/`, a `#req-` tag
+ * means nothing until a `#cap-` tag has said which capability document the
+ * `Requirement-ID` is unique inside. Beside a model there is no such question:
+ * the directory IS the scope, and the ids are the ones THIS service's `spec.md`
+ * and `arch.spec.md` declare — the flow keeps a container-level promise the way
+ * a fleet flow keeps a business one. The join is `resolveRequirementTags` with
+ * the service as its one-element scope, so the arms fall out mechanically and
+ * `unscoped` is unreachable.
+ *
+ * WHY `#cap-` IS REFUSED, NOT IGNORED AND NOT RESOLVED. A capability is
+ * realized by a hop sequence across the fleet map — "the only join that
+ * crosses services" — and `keptBy` reads the fleet project only. Ignoring the
+ * tag would leave `#cap-checkout` on a service flow green and silently unread;
+ * resolving it against the vocabulary would make validate see a claim no other
+ * surface sees. So it is refused by PLACEMENT, whether or not
+ * `architecture/capabilities.yaml` exists: the reason is where the tag sits,
+ * not what the vocabulary says. The view stays opted in and its steps are
+ * graded — either prefix is the opt-in, exactly as at fleet altitude.
+ */
+import { CAP_TAG_PREFIX, REQ_TAG_PREFIX, resolveRequirementTags, tagSlug, } from "../../../../core/capabilities/usecase-join.js";
+import { compareIds } from "../../../../core/repo/entries.js";
+/** A `Requirement-ID` as an author must write it in a tag: `PAY.AUTH (#req-PAY-AUTH)`. */
+function idAndTag(id) {
+    return `${id} (#${REQ_TAG_PREFIX}${tagSlug(id)})`;
+}
+/**
+ * The fix for one unresolved claim, in the service's own vocabulary. The same
+ * arms the fleet grade has, each sentence pointing at the document that
+ * carries the fix here — spec.md and arch.spec.md, never a capability.
+ */
+function advice(claim, scope) {
+    const where = `${scope.service} (spec.md or arch.spec.md)`;
+    switch (claim.kind) {
+        case "unscoped":
+            // Unreachable: the scope is always exactly one service. A sentence
+            // rather than a throw, because this runs inside a validate run over
+            // somebody's fleet, and a broken invariant there is one finding, not a
+            // crash.
+            return "the flow could not be scoped to this service — report this: a service-local flow is always scoped to its own directory.";
+        case "undocumented":
+            return (`${scope.treePath}/ has no spec.md and no arch.spec.md, so it carries no requirements to satisfy. ` +
+                "Write the requirement first — a flow keeps a promise a document makes.");
+        case "empty":
+            return (`${scope.service}'s spec.md and arch.spec.md declare no \`Requirement-ID:\` at all — a #req- tag joins by ` +
+                "stable id, and a requirement without one cannot be named by a flow. Add `Requirement-ID: <id>` to the " +
+                "requirement this flow keeps.");
+        case "none":
+            return claim.close.length > 0
+                ? `no requirement of ${where} flattens to '${claim.slug}'. Did you mean: ${claim.close.map(idAndTag).join(", ")}?`
+                : `no requirement of ${where} flattens to '${claim.slug}' — check the \`Requirement-ID:\` lines in both documents.`;
+        default:
+            return (`${claim.ids.length} requirements of ${scope.service} flatten to '${claim.slug}' (${claim.ids.join(", ")}) — ` +
+                "a Requirement-ID is unique inside ONE document and this service has two, so nothing in the tag can say " +
+                "which promise the flow keeps. Rename one of them.");
+    }
+}
+/**
+ * One finding per `#req-` tag that does not resolve against the service's own
+ * ids — never one per view, for the fleet grade's reason: several `#req-` tags
+ * on one view are legal and normal, and a broken tag beside a working one must
+ * neither swallow the break nor lose the promise the view genuinely keeps.
+ */
+function requirementFindings(view, scope, place) {
+    const findings = [];
+    for (const claim of resolveRequirementTags(view.tags, [scope.service], () => scope.requirementIds)) {
+        if (claim.kind === "resolved")
+            continue;
+        findings.push({
+            severity: "error",
+            code: "usecase.requirement-unresolved",
+            // The VIEW, not the tag, as at fleet altitude: a subject is what a reader
+            // goes and opens, and one broken use case counts once however many of
+            // its tags are wrong.
+            subject: view.id,
+            message: `${place} is tagged #${claim.tag}, and it does not resolve: ${advice(claim, scope)}`,
+        });
+    }
+    return findings;
+}
+/**
+ * One finding per `#cap-` tag the view carries — the placement refusal. Sorted
+ * and de-duplicated for `resolveCapabilityTags`' reason: nothing in loam has
+ * measured that LikeC4 preserves the author's tag order, and one breach earns
+ * one finding.
+ */
+function capabilityFindings(view, place) {
+    const claimed = [...new Set(view.tags.filter((tag) => tag.startsWith(CAP_TAG_PREFIX)))].sort(compareIds);
+    return claimed.map((tag) => ({
+        severity: "error",
+        code: "usecase.capability-unresolved",
+        subject: view.id,
+        message: `${place} is tagged #${tag} inside this service's own project, where no capability can be claimed: ` +
+            "a capability is a fleet promise, and only a flow in architecture/usecases/ can keep one; a flow beside " +
+            "model.likec4 keeps THIS service's promises (#req-<Requirement-ID>). Drop the tag: the capability's promise " +
+            "is kept by the fleet flow that calls this service, and this flow is the hop sequence inside it.",
+    }));
+}
+/** Every tag finding one service-local view earns: the placement refusals first, then the requirement claims. */
+export function serviceTagFindings(view, scope, place) {
+    return [...capabilityFindings(view, place), ...requirementFindings(view, scope, place)];
+}
+//# sourceMappingURL=tags.js.map

package/dist/commands/validate/service/usecases/tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../../../../../src/commands/validate/service/usecases/tags.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The two tag grades of a SERVICE-LOCAL use case: `usecase.requirement-unresolved`\n * with service-worded arms, and `usecase.capability-unresolved`'s placement arm.\n *\n * Both codes are REUSED from the fleet target rather than minted, under\n * add-error-code's \"prefer existing\" rule: a caller acts the same way (fix the\n * tag, or the `Requirement-ID:` line it names), and only the sentences differ.\n * The fleet's own graders (`../../fleet/usecases/{requirement,capability}-tag.ts`)\n * are not reused for the sentences, because every one of theirs names a\n * capability document, and a service-local flow has none.\n *\n * WHY `#req-` IS SCOPED BY THE SERVICE. Inside `architecture/`, a `#req-` tag\n * means nothing until a `#cap-` tag has said which capability document the\n * `Requirement-ID` is unique inside. Beside a model there is no such question:\n * the directory IS the scope, and the ids are the ones THIS service's `spec.md`\n * and `arch.spec.md` declare — the flow keeps a container-level promise the way\n * a fleet flow keeps a business one. The join is `resolveRequirementTags` with\n * the service as its one-element scope, so the arms fall out mechanically and\n * `unscoped` is unreachable.\n *\n * WHY `#cap-` IS REFUSED, NOT IGNORED AND NOT RESOLVED. A capability is\n * realized by a hop sequence across the fleet map — \"the only join that\n * crosses services\" — and `keptBy` reads the fleet project only. Ignoring the\n * tag would leave `#cap-checkout` on a service flow green and silently unread;\n * resolving it against the vocabulary would make validate see a claim no other\n * surface sees. So it is refused by PLACEMENT, whether or not\n * `architecture/capabilities.yaml` exists: the reason is where the tag sits,\n * not what the vocabulary says. The view stays opted in and its steps are\n * graded — either prefix is the opt-in, exactly as at fleet altitude.\n */\nimport {\n  CAP_TAG_PREFIX,\n  REQ_TAG_PREFIX,\n  resolveRequirementTags,\n  tagSlug,\n  type RequirementClaim,\n} from \"../../../../core/capabilities/usecase-join.js\";\nimport type { ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport { compareIds } from \"../../../../core/repo/entries.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\n\n/** What the tag grades resolve against: the service, and its own identified requirements. */\nexport interface ServiceTagScope {\n  service: string;\n  /** Repo-relative tree path of the service directory, for the sentences. */\n  treePath: string;\n  /**\n   * Every `Requirement-ID` this service's spec.md (living, REMOVED skipped) and\n   * arch.spec.md declare, or `undefined` when NEITHER document exists — the\n   * same two answers `requirementsOf` gives one join over: no document at all,\n   * against documents declaring no identified promise yet.\n   */\n  requirementIds: ReadonlySet<string> | undefined;\n}\n\n/** A `Requirement-ID` as an author must write it in a tag: `PAY.AUTH (#req-PAY-AUTH)`. */\nfunction idAndTag(id: string): string {\n  return `${id} (#${REQ_TAG_PREFIX}${tagSlug(id)})`;\n}\n\n/**\n * The fix for one unresolved claim, in the service's own vocabulary. The same\n * arms the fleet grade has, each sentence pointing at the document that\n * carries the fix here — spec.md and arch.spec.md, never a capability.\n */\nfunction advice(claim: Exclude<RequirementClaim, { kind: \"resolved\" }>, scope: ServiceTagScope): string {\n  const where = `${scope.service} (spec.md or arch.spec.md)`;\n  switch (claim.kind) {\n    case \"unscoped\":\n      // Unreachable: the scope is always exactly one service. A sentence\n      // rather than a throw, because this runs inside a validate run over\n      // somebody's fleet, and a broken invariant there is one finding, not a\n      // crash.\n      return \"the flow could not be scoped to this service — report this: a service-local flow is always scoped to its own directory.\";\n    case \"undocumented\":\n      return (\n        `${scope.treePath}/ has no spec.md and no arch.spec.md, so it carries no requirements to satisfy. ` +\n        \"Write the requirement first — a flow keeps a promise a document makes.\"\n      );\n    case \"empty\":\n      return (\n        `${scope.service}'s spec.md and arch.spec.md declare no \\`Requirement-ID:\\` at all — a #req- tag joins by ` +\n        \"stable id, and a requirement without one cannot be named by a flow. Add `Requirement-ID: <id>` to the \" +\n        \"requirement this flow keeps.\"\n      );\n    case \"none\":\n      return claim.close.length > 0\n        ? `no requirement of ${where} flattens to '${claim.slug}'. Did you mean: ${claim.close.map(idAndTag).join(\", \")}?`\n        : `no requirement of ${where} flattens to '${claim.slug}' — check the \\`Requirement-ID:\\` lines in both documents.`;\n    default:\n      return (\n        `${claim.ids.length} requirements of ${scope.service} flatten to '${claim.slug}' (${claim.ids.join(\", \")}) — ` +\n        \"a Requirement-ID is unique inside ONE document and this service has two, so nothing in the tag can say \" +\n        \"which promise the flow keeps. Rename one of them.\"\n      );\n  }\n}\n\n/**\n * One finding per `#req-` tag that does not resolve against the service's own\n * ids — never one per view, for the fleet grade's reason: several `#req-` tags\n * on one view are legal and normal, and a broken tag beside a working one must\n * neither swallow the break nor lose the promise the view genuinely keeps.\n */\nfunction requirementFindings(view: ParsedView, scope: ServiceTagScope, place: string): Finding[] {\n  const findings: Finding[] = [];\n  for (const claim of resolveRequirementTags(view.tags, [scope.service], () => scope.requirementIds)) {\n    if (claim.kind === \"resolved\") continue;\n    findings.push({\n      severity: \"error\",\n      code: \"usecase.requirement-unresolved\",\n      // The VIEW, not the tag, as at fleet altitude: a subject is what a reader\n      // goes and opens, and one broken use case counts once however many of\n      // its tags are wrong.\n      subject: view.id,\n      message: `${place} is tagged #${claim.tag}, and it does not resolve: ${advice(claim, scope)}`,\n    });\n  }\n  return findings;\n}\n\n/**\n * One finding per `#cap-` tag the view carries — the placement refusal. Sorted\n * and de-duplicated for `resolveCapabilityTags`' reason: nothing in loam has\n * measured that LikeC4 preserves the author's tag order, and one breach earns\n * one finding.\n */\nfunction capabilityFindings(view: ParsedView, place: string): Finding[] {\n  const claimed = [...new Set(view.tags.filter((tag) => tag.startsWith(CAP_TAG_PREFIX)))].sort(compareIds);\n  return claimed.map((tag) => ({\n    severity: \"error\",\n    code: \"usecase.capability-unresolved\",\n    subject: view.id,\n    message:\n      `${place} is tagged #${tag} inside this service's own project, where no capability can be claimed: ` +\n      \"a capability is a fleet promise, and only a flow in architecture/usecases/ can keep one; a flow beside \" +\n      \"model.likec4 keeps THIS service's promises (#req-<Requirement-ID>). Drop the tag: the capability's promise \" +\n      \"is kept by the fleet flow that calls this service, and this flow is the hop sequence inside it.\",\n  }));\n}\n\n/** Every tag finding one service-local view earns: the placement refusals first, then the requirement claims. */\nexport function serviceTagFindings(view: ParsedView, scope: ServiceTagScope, place: string): Finding[] {\n  return [...capabilityFindings(view, place), ...requirementFindings(view, scope, place)];\n}\n"]}

package/dist/commands/validate/service/usecases/usecases.js

@@ -0,0 +1,209 @@
+/**
+ * The use-case axis of the SERVICE target: the `dynamic view`s a service's own
+ * LikeC4 project declares, graded as the hop sequences behind its requirements.
+ *
+ * The fleet target grades flows drawn over the map (`../../fleet/usecases/`);
+ * this grades flows drawn over ONE service's containers, which only that
+ * service's project can resolve — the whole reason the slot exists
+ * (`core/usecases/service/flows.ts` carries the report). The step grades are
+ * the fleet's own `stepFindings`, reused with the service's project as the
+ * model, the enumerated fleet as `services`, and one injection: where a
+ * finding says the view is. A second verdict→code mapping here would be the
+ * drift that package's banner forbids.
+ *
+ * ONLY VIEWS CARRYING A RESERVED TAG ARE GRADED, as at fleet altitude and for
+ * the same reason: a service's `views.likec4` full of hand-drawn diagrams must
+ * not turn red on upgrade. The reader applies the opt-in; this module never
+ * sees an untagged view. Graded is narrower than LOADED, and the difference is
+ * the reader's gate (`core/usecases/service/flows.ts`): an untagged sibling is
+ * not even loaded while no view in the project opts in and no sibling mentions
+ * either reserved prefix anywhere in its bytes — but once a view in
+ * model.likec4 itself opts in, or a sibling mentions `req-` or `cap-` in a
+ * comment or a title, every sibling is staged, and a project that does not
+ * read is one `usecase.flow-invalid` whether or not any view in it opted in.
+ *
+ * A SIBLING THAT BREAKS THE PROJECT is ONE `usecase.flow-invalid` — reused,
+ * because its meaning is exactly this ("loam could not read the flows against
+ * the map they are drawn over, so it graded none of them, and the renderer
+ * refuses the same project") applied to the service project instead of the
+ * merge preview — and NEVER `c4.invalid`: that code means "model.likec4 does
+ * not parse, every model check is suspended", and here the model parses and
+ * every model check RAN. Reusing it would tell an agent to fix the wrong file
+ * and tell the brief's `checks[]` row ("every other check stops here") a lie.
+ */
+import { existsSync } from "node:fs";
+import { relative } from "node:path";
+import { serviceResolver } from "../../../../core/c4/resolve/service.js";
+import { compareIds } from "../../../../core/repo/entries.js";
+import { errorText } from "../../../../core/c4/likec4.js";
+import { CAP_TAG_PREFIX, REQ_TAG_PREFIX } from "../../../../core/capabilities/usecase-join.js";
+import { stepFindings } from "../../fleet/usecases/steps.js";
+import { serviceTagFindings } from "./tags.js";
+/** `<svc>: services/<tree>/<file> — dynamic view '<id>'` — the service target's spelling of `viewPlace`. */
+function servicePlace(scope, view) {
+    // An absent `sourcePath` names the directory rather than guessing a file,
+    // for `viewFile`'s reason; nothing at the 1.59.2 pin reaches that arm.
+    return `${scope.service}: ${scope.treePath}/${view.sourcePath ?? ""} — dynamic view '${view.id}'`;
+}
+/** The repo-relative spelling of a project error's document, or the whole project when it carries none. */
+function fileOf(scope, error) {
+    return error.sourceFsPath === undefined
+        ? `${scope.treePath}/`
+        : relative(scope.docsDir, error.sourceFsPath).split(/[\\/]/).join("/");
+}
+/**
+ * The one finding a broken project earns. `details` is one `errorText` line
+ * per error, each prefixed by its file, because the project may hold several
+ * siblings and the fault may sit in any of them — including `model.likec4`
+ * itself when a sibling re-declares its `specification` block, an error LikeC4
+ * blames on both files. `locations` names the first broken file, in the sorted
+ * order the reader produced.
+ */
+function flowInvalidFinding(scope, errors) {
+    const files = [...new Set(errors.map((error) => fileOf(scope, error)))];
+    const [first = `${scope.treePath}/`, ...others] = files;
+    const named = others.length === 0 ? first : `${first} and ${others.length} more file(s)`;
+    return {
+        severity: "error",
+        code: "usecase.flow-invalid",
+        subject: scope.service,
+        message: `${scope.service}: ${named} has ${errors.length} error(s) — every .likec4 beside model.likec4 is one LikeC4 ` +
+            "project, read the way the renderer reads it, and the renderer refuses the whole project over one broken " +
+            "file; no flow in it was graded. model.likec4 itself parses and is graded alone.",
+        // The hint first, for `c4.invalid`'s reason (`../model/grade.ts`):
+        // `capDetails` keeps ten lines, one broken document can carry more than ten
+        // errors, and a diagnosis appended after them is dropped exactly when the
+        // reader needs it.
+        details: [...tagHint(errors), ...errors.map((error) => `${fileOf(scope, error)}: ${errorText(error)}`)],
+        locations: [{ path: first, role: "primary" }],
+    };
+}
+/** `Could not resolve reference to Tag named '#req-PAY-AUTH'.` — measured at the 1.59.2 pin. */
+const UNDECLARED_TAG = /reference to Tag named '#?([\w.-]+)'/;
+/**
+ * The one line an undeclared RESERVED tag earns.
+ *
+ * The opt-in is a tag, LikeC4 refuses a tag no `specification` declares, and the
+ * refusal is a bare `Could not resolve reference to Tag named …` — so an author
+ * following the protocol's "tag the view `#req-<id>`" got a parse error naming
+ * the thing they had just been told to write, with nothing saying a tag must be
+ * declared first (verification 2026-09-04, D10). One line, from the first such
+ * error only: the second one has the same repair.
+ */
+function tagHint(errors) {
+    for (const error of errors) {
+        const match = UNDECLARED_TAG.exec(error.message);
+        const name = match?.[1];
+        if (name === undefined)
+            continue;
+        // `cap-` and `req-` do NOT share a repair here, and covering both with one
+        // hint sent an author two steps where one would do: declaring `tag cap-…`
+        // makes the file parse and the very next run says `usecase.capability-
+        // unresolved` — "no capability can be claimed inside this service's own
+        // project. Drop the tag." A capability is claimed at fleet altitude, so the
+        // tag can never resolve to anything beside a model, whatever is declared
+        // (verification 2026-09-04).
+        if (name.startsWith(CAP_TAG_PREFIX)) {
+            return [
+                `\`#${name}\` claims a capability, and a capability is claimed at FLEET altitude only — a flow beside ` +
+                    "model.likec4 is read in this service's own project, where no capability can be resolved. Declaring " +
+                    `\`tag ${name}\` makes the file parse and earns \`usecase.capability-unresolved\` on the next run: ` +
+                    `drop the tag, and tag the flow \`#${REQ_TAG_PREFIX}<Requirement-ID>\` instead, or draw it in ` +
+                    "`architecture/usecases/` where a capability tag belongs",
+            ];
+        }
+        if (!name.startsWith(REQ_TAG_PREFIX))
+            continue;
+        return [
+            `declare \`tag ${name}\` in the \`specification { }\` block this project reads — model.likec4's own ` +
+                "for a model that stands alone, the fleet map's for one that extends it (or a tags-only " +
+                "`specification` in a document beside the model)",
+        ];
+    }
+    return [];
+}
+/**
+ * The FILE each finding is about, as `locations[0]`.
+ *
+ * The step and tag grades carry no `locations` of their own, so `findingJson`
+ * fell back to the target's scope — `services/<tree>` and nothing else — and an
+ * agent reading `--json`, which is the reason the envelope exists, had to parse
+ * the prose to learn which `.likec4` to open. `usecase.flow-invalid` on this
+ * same arm already names its file; these say the file the same way, with the
+ * service directory kept beside it as `scope` (`../spine.ts`'s shape).
+ */
+function atView(scope, view, findings) {
+    const file = view.sourcePath === undefined ? `${scope.treePath}/` : `${scope.treePath}/${view.sourcePath}`;
+    return findings.map((finding) => finding.locations === undefined
+        ? {
+            ...finding,
+            locations: [
+                { path: file, role: "primary" },
+                { path: scope.treePath, role: "scope" },
+            ],
+        }
+        : finding);
+}
+/**
+ * Every use-case finding a service's own project earns.
+ *
+ * Views are sorted by (file, view id) for the fleet grader's reason: nothing in
+ * loam has measured that the parse preserves declaration order, and a report
+ * whose row order depends on it would reorder under a dependency bump.
+ */
+export function serviceUseCaseFindings(scope) {
+    const { scan } = scope;
+    if (scan.kind === "none")
+        return [];
+    if (scan.kind === "unreadable")
+        return [flowInvalidFinding(scope, scan.errors)];
+    const place = (view) => servicePlace(scope, view);
+    const grading = {
+        model: scan.model,
+        services: scope.services,
+        // Built over the PROJECT's elements with the fleet set, exactly as the
+        // attribution's own fallback tier resolves — so "which service is this
+        // container" cannot be answered one way by `attributeStep` and another by
+        // the provider guard.
+        resolve: serviceResolver(scan.model.elements, scan.model.known),
+        place,
+    };
+    const findings = [];
+    const views = [...scan.views].sort((a, b) => compareIds(a.sourcePath ?? "", b.sourcePath ?? "") || compareIds(a.id, b.id));
+    for (const view of views) {
+        const forView = [...serviceTagFindings(view, scope, place(view))];
+        for (const step of view.steps)
+            forView.push(...stepFindings({ view, step }, grading));
+        findings.push(...atView(scope, view, forView));
+    }
+    return findings;
+}
+/**
+ * The `Requirement-ID`s a service-local `#req-` tag may name: every identified
+ * requirement of spec.md (living — a REMOVED one is on its way out and keeps no
+ * promise) and of arch.spec.md, as ONE set. `undefined` when NEITHER document
+ * exists, which the tag grade reads as "no requirement to satisfy" rather than
+ * "none flattening to this slug" — the same two answers the fleet's
+ * `requirementsOf` gives for a capability with no document at all.
+ *
+ * An id both documents declare resolves once (a set dedupes it); two ids that
+ * merely flatten alike — `PAY.AUTH` in one file, `PAY-AUTH` in the other — are
+ * the `many` arm, because a Requirement-ID is unique inside one document and a
+ * flow beside the model has two.
+ *
+ * It lives beside the grade it feeds rather than in `../service.ts`, which is
+ * the ORDER and nothing else: the set is this axis's input, its two answers are
+ * this axis's vocabulary, and the order module had grown past its line limit
+ * carrying it.
+ */
+export function requirementIdsOf(paths, livingReqs, archReqs) {
+    if (!existsSync(paths.spec) && !existsSync(paths.archSpec))
+        return undefined;
+    const ids = new Set();
+    for (const req of [...livingReqs, ...archReqs.filter((r) => r.kind !== "REMOVED")]) {
+        if (req.id !== undefined)
+            ids.add(req.id);
+    }
+    return ids;
+}
+//# sourceMappingURL=usecases.js.map

package/dist/commands/validate/service/usecases/usecases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usecases.js","sourceRoot":"","sources":["../../../../../src/commands/validate/service/usecases/usecases.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The use-case axis of the SERVICE target: the `dynamic view`s a service's own\n * LikeC4 project declares, graded as the hop sequences behind its requirements.\n *\n * The fleet target grades flows drawn over the map (`../../fleet/usecases/`);\n * this grades flows drawn over ONE service's containers, which only that\n * service's project can resolve — the whole reason the slot exists\n * (`core/usecases/service/flows.ts` carries the report). The step grades are\n * the fleet's own `stepFindings`, reused with the service's project as the\n * model, the enumerated fleet as `services`, and one injection: where a\n * finding says the view is. A second verdict→code mapping here would be the\n * drift that package's banner forbids.\n *\n * ONLY VIEWS CARRYING A RESERVED TAG ARE GRADED, as at fleet altitude and for\n * the same reason: a service's `views.likec4` full of hand-drawn diagrams must\n * not turn red on upgrade. The reader applies the opt-in; this module never\n * sees an untagged view. Graded is narrower than LOADED, and the difference is\n * the reader's gate (`core/usecases/service/flows.ts`): an untagged sibling is\n * not even loaded while no view in the project opts in and no sibling mentions\n * either reserved prefix anywhere in its bytes — but once a view in\n * model.likec4 itself opts in, or a sibling mentions `req-` or `cap-` in a\n * comment or a title, every sibling is staged, and a project that does not\n * read is one `usecase.flow-invalid` whether or not any view in it opted in.\n *\n * A SIBLING THAT BREAKS THE PROJECT is ONE `usecase.flow-invalid` — reused,\n * because its meaning is exactly this (\"loam could not read the flows against\n * the map they are drawn over, so it graded none of them, and the renderer\n * refuses the same project\") applied to the service project instead of the\n * merge preview — and NEVER `c4.invalid`: that code means \"model.likec4 does\n * not parse, every model check is suspended\", and here the model parses and\n * every model check RAN. Reusing it would tell an agent to fix the wrong file\n * and tell the brief's `checks[]` row (\"every other check stops here\") a lie.\n */\nimport { existsSync } from \"node:fs\";\nimport { relative } from \"node:path\";\nimport type { LikeC4Error } from \"../../../../core/c4/likec4.js\";\nimport type { Requirement } from \"../../../../core/document/spec.js\";\nimport type { ServicePaths } from \"../../../../core/repo/paths.js\";\nimport type { ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport { serviceResolver } from \"../../../../core/c4/resolve/service.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport { compareIds } from \"../../../../core/repo/entries.js\";\nimport type { ServiceFlowScan } from \"../../../../core/usecases/service/flows.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { errorText } from \"../../../../core/c4/likec4.js\";\nimport { CAP_TAG_PREFIX, REQ_TAG_PREFIX } from \"../../../../core/capabilities/usecase-join.js\";\nimport { stepFindings, type StepGrading } from \"../../fleet/usecases/steps.js\";\nimport { serviceTagFindings, type ServiceTagScope } from \"./tags.js\";\n\n/** What the service's use-case grades run over. */\nexport interface ServiceUseCaseScope extends ServiceTagScope {\n  /** The docs root, so a project error's absolute path can be spelled repo-relative. */\n  docsDir: DocsDir;\n  scan: ServiceFlowScan;\n  /**\n   * The `services/<id>/` directories that exist — the SAME enumerated set the\n   * fleet target hands `stepFindings`, never an empty one: `StepGrading`\n   * documents why the intra-service exemption is a guard and not a scope.\n   */\n  services: ReadonlySet<string>;\n}\n\n/** `<svc>: services/<tree>/<file> — dynamic view '<id>'` — the service target's spelling of `viewPlace`. */\nfunction servicePlace(scope: ServiceUseCaseScope, view: ParsedView): string {\n  // An absent `sourcePath` names the directory rather than guessing a file,\n  // for `viewFile`'s reason; nothing at the 1.59.2 pin reaches that arm.\n  return `${scope.service}: ${scope.treePath}/${view.sourcePath ?? \"\"} — dynamic view '${view.id}'`;\n}\n\n/** The repo-relative spelling of a project error's document, or the whole project when it carries none. */\nfunction fileOf(scope: ServiceUseCaseScope, error: LikeC4Error): string {\n  return error.sourceFsPath === undefined\n    ? `${scope.treePath}/`\n    : relative(scope.docsDir, error.sourceFsPath).split(/[\\\\/]/).join(\"/\");\n}\n\n/**\n * The one finding a broken project earns. `details` is one `errorText` line\n * per error, each prefixed by its file, because the project may hold several\n * siblings and the fault may sit in any of them — including `model.likec4`\n * itself when a sibling re-declares its `specification` block, an error LikeC4\n * blames on both files. `locations` names the first broken file, in the sorted\n * order the reader produced.\n */\nfunction flowInvalidFinding(scope: ServiceUseCaseScope, errors: readonly LikeC4Error[]): Finding {\n  const files = [...new Set(errors.map((error) => fileOf(scope, error)))];\n  const [first = `${scope.treePath}/`, ...others] = files;\n  const named = others.length === 0 ? first : `${first} and ${others.length} more file(s)`;\n  return {\n    severity: \"error\",\n    code: \"usecase.flow-invalid\",\n    subject: scope.service,\n    message:\n      `${scope.service}: ${named} has ${errors.length} error(s) — every .likec4 beside model.likec4 is one LikeC4 ` +\n      \"project, read the way the renderer reads it, and the renderer refuses the whole project over one broken \" +\n      \"file; no flow in it was graded. model.likec4 itself parses and is graded alone.\",\n    // The hint first, for `c4.invalid`'s reason (`../model/grade.ts`):\n    // `capDetails` keeps ten lines, one broken document can carry more than ten\n    // errors, and a diagnosis appended after them is dropped exactly when the\n    // reader needs it.\n    details: [...tagHint(errors), ...errors.map((error) => `${fileOf(scope, error)}: ${errorText(error)}`)],\n    locations: [{ path: first, role: \"primary\" }],\n  };\n}\n\n/** `Could not resolve reference to Tag named '#req-PAY-AUTH'.` — measured at the 1.59.2 pin. */\nconst UNDECLARED_TAG = /reference to Tag named '#?([\\w.-]+)'/;\n\n/**\n * The one line an undeclared RESERVED tag earns.\n *\n * The opt-in is a tag, LikeC4 refuses a tag no `specification` declares, and the\n * refusal is a bare `Could not resolve reference to Tag named …` — so an author\n * following the protocol's \"tag the view `#req-<id>`\" got a parse error naming\n * the thing they had just been told to write, with nothing saying a tag must be\n * declared first (verification 2026-09-04, D10). One line, from the first such\n * error only: the second one has the same repair.\n */\nfunction tagHint(errors: readonly LikeC4Error[]): string[] {\n  for (const error of errors) {\n    const match = UNDECLARED_TAG.exec(error.message);\n    const name = match?.[1];\n    if (name === undefined) continue;\n    // `cap-` and `req-` do NOT share a repair here, and covering both with one\n    // hint sent an author two steps where one would do: declaring `tag cap-…`\n    // makes the file parse and the very next run says `usecase.capability-\n    // unresolved` — \"no capability can be claimed inside this service's own\n    // project. Drop the tag.\" A capability is claimed at fleet altitude, so the\n    // tag can never resolve to anything beside a model, whatever is declared\n    // (verification 2026-09-04).\n    if (name.startsWith(CAP_TAG_PREFIX)) {\n      return [\n        `\\`#${name}\\` claims a capability, and a capability is claimed at FLEET altitude only — a flow beside ` +\n          \"model.likec4 is read in this service's own project, where no capability can be resolved. Declaring \" +\n          `\\`tag ${name}\\` makes the file parse and earns \\`usecase.capability-unresolved\\` on the next run: ` +\n          `drop the tag, and tag the flow \\`#${REQ_TAG_PREFIX}<Requirement-ID>\\` instead, or draw it in ` +\n          \"`architecture/usecases/` where a capability tag belongs\",\n      ];\n    }\n    if (!name.startsWith(REQ_TAG_PREFIX)) continue;\n    return [\n      `declare \\`tag ${name}\\` in the \\`specification { }\\` block this project reads — model.likec4's own ` +\n        \"for a model that stands alone, the fleet map's for one that extends it (or a tags-only \" +\n        \"`specification` in a document beside the model)\",\n    ];\n  }\n  return [];\n}\n\n/**\n * The FILE each finding is about, as `locations[0]`.\n *\n * The step and tag grades carry no `locations` of their own, so `findingJson`\n * fell back to the target's scope — `services/<tree>` and nothing else — and an\n * agent reading `--json`, which is the reason the envelope exists, had to parse\n * the prose to learn which `.likec4` to open. `usecase.flow-invalid` on this\n * same arm already names its file; these say the file the same way, with the\n * service directory kept beside it as `scope` (`../spine.ts`'s shape).\n */\nfunction atView(scope: ServiceUseCaseScope, view: ParsedView, findings: Finding[]): Finding[] {\n  const file = view.sourcePath === undefined ? `${scope.treePath}/` : `${scope.treePath}/${view.sourcePath}`;\n  return findings.map((finding) =>\n    finding.locations === undefined\n      ? {\n          ...finding,\n          locations: [\n            { path: file, role: \"primary\" as const },\n            { path: scope.treePath, role: \"scope\" as const },\n          ],\n        }\n      : finding,\n  );\n}\n\n/**\n * Every use-case finding a service's own project earns.\n *\n * Views are sorted by (file, view id) for the fleet grader's reason: nothing in\n * loam has measured that the parse preserves declaration order, and a report\n * whose row order depends on it would reorder under a dependency bump.\n */\nexport function serviceUseCaseFindings(scope: ServiceUseCaseScope): Finding[] {\n  const { scan } = scope;\n  if (scan.kind === \"none\") return [];\n  if (scan.kind === \"unreadable\") return [flowInvalidFinding(scope, scan.errors)];\n\n  const place = (view: ParsedView): string => servicePlace(scope, view);\n  const grading: StepGrading = {\n    model: scan.model,\n    services: scope.services,\n    // Built over the PROJECT's elements with the fleet set, exactly as the\n    // attribution's own fallback tier resolves — so \"which service is this\n    // container\" cannot be answered one way by `attributeStep` and another by\n    // the provider guard.\n    resolve: serviceResolver(scan.model.elements, scan.model.known),\n    place,\n  };\n  const findings: Finding[] = [];\n  const views = [...scan.views].sort(\n    (a, b) => compareIds(a.sourcePath ?? \"\", b.sourcePath ?? \"\") || compareIds(a.id, b.id),\n  );\n  for (const view of views) {\n    const forView: Finding[] = [...serviceTagFindings(view, scope, place(view))];\n    for (const step of view.steps) forView.push(...stepFindings({ view, step }, grading));\n    findings.push(...atView(scope, view, forView));\n  }\n  return findings;\n}\n\n/**\n * The `Requirement-ID`s a service-local `#req-` tag may name: every identified\n * requirement of spec.md (living — a REMOVED one is on its way out and keeps no\n * promise) and of arch.spec.md, as ONE set. `undefined` when NEITHER document\n * exists, which the tag grade reads as \"no requirement to satisfy\" rather than\n * \"none flattening to this slug\" — the same two answers the fleet's\n * `requirementsOf` gives for a capability with no document at all.\n *\n * An id both documents declare resolves once (a set dedupes it); two ids that\n * merely flatten alike — `PAY.AUTH` in one file, `PAY-AUTH` in the other — are\n * the `many` arm, because a Requirement-ID is unique inside one document and a\n * flow beside the model has two.\n *\n * It lives beside the grade it feeds rather than in `../service.ts`, which is\n * the ORDER and nothing else: the set is this axis's input, its two answers are\n * this axis's vocabulary, and the order module had grown past its line limit\n * carrying it.\n */\nexport function requirementIdsOf(\n  paths: ServicePaths,\n  livingReqs: readonly Requirement[],\n  archReqs: readonly Requirement[],\n): ReadonlySet<string> | undefined {\n  if (!existsSync(paths.spec) && !existsSync(paths.archSpec)) return undefined;\n  const ids = new Set<string>();\n  for (const req of [...livingReqs, ...archReqs.filter((r) => r.kind !== \"REMOVED\")]) {\n    if (req.id !== undefined) ids.add(req.id);\n  }\n  return ids;\n}\n"]}

package/dist/commands/validate/validate.js

@@ -6,7 +6,7 @@ import { resolveServiceTarget } from "../../core/repo/service-target.js";
 import { loadConfig } from "../../core/envelope/config.js";
 import { emitJson, fail, NO_SERVICE_MESSAGE, reportNoConfig } from "../../core/envelope/json.js";
 import { DocsRepoUnavailableError } from "../../core/repo/state.js";
-import { agentsPath as agentsFile, featurePaths, landscapePath as landscapeFile, servicePathsAt } from "../../core/repo/paths.js";
+import { agentsPath as agentsFile, landscapePath as landscapeFile } from "../../core/repo/paths.js";
 import { listFeatures, listServices, missingFeatureMessage, resolveFeature } from "../../core/repo/repo.js";
 import { countSeverity, reportValid, targetJson, targetValid, } from "../../core/vocabulary/report.js";
 import { LOAM_VERSION } from "../../core/envelope/version.js";
@@ -16,8 +16,7 @@ import { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable, } from
 import { interruptedCommitFinding } from "../../core/staging/recovery/finding.js";
 import { scopeJson, scopeLine, scopeSince } from "../../core/diff/scope/changed-paths.js";
 import { validateLandscape } from "./fleet/landscape.js";
-import { loadArchitecture } from "../../core/c4/project/architecture.js";
-import { readLandscape } from "./fleet/load.js";
+import { prefetchFleetDocuments, readLandscape } from "./fleet/load.js";
 import { buildScorecard } from "./fleet/scorecard/scorecard.js";
 import { printScorecard } from "./fleet/scorecard/print.js";
 import { validateFeature } from "./feature.js";
@@ -91,20 +90,9 @@ export function registerValidate(program) {
         let scope = null;
         try {
             if (opts.all) {
-                // ONE LikeC4 workspace for the whole run. The per-path load pays a
-                // fresh Langium workspace per document (~100ms each even warm), which
-                // made the fleet's main CI command O(documents) workspace spins —
-                // 13.7s median over the 120-service benchmark (docs/BENCHMARKS.md).
-                // So --all enumerates its documents up front — the landscape, every
-                // service model, every active feature's delta — and batch-parses
-                // them into the fleet context's memo; every loadLikeC4 below, the
-                // landscape read included, is then a seeded hit. The enumerations are
-                // the same memoized promises the target loops reuse. If the batch
-                // CANNOT run (a sandbox denying tmpdir writes), prefetch seeds
-                // nothing and every load falls back to today's per-path parse:
-                // identical findings, the old speed. Single-service validate and
-                // list keep their untouched code paths on purpose — the ≤10%
-                // regression bound in docs/BENCHMARKS.md holds by construction.
+                // ONE workspace per document kind for the whole run — the block moved
+                // to `fleet/load.ts` (`prefetchFleetDocuments`), which is where the
+                // rule about which shape parses in which workspace belongs.
                 const lp = landscapeFile(docsDir);
                 const enumerated = await listServices(docsDir, fleet);
                 const active = await listFeatures(docsDir, {}, fleet);
@@ -123,15 +111,13 @@ export function registerValidate(program) {
                 }
                 const services = scope === null ? enumerated : scope.services;
                 const features = scope === null ? active : scope.features;
-                await fleet.prefetchLikeC4([
-                    ...(existsSync(lp) ? [lp] : []),
-                    ...services.filter((svc) => svc.has.model).map((svc) => servicePathsAt(svc.dir).model),
-                    ...features.filter((feat) => feat.has.delta).map((feat) => featurePaths(feat.dir).delta),
-                ]);
+                await prefetchFleetDocuments({ docsDir, fleet, services, features });
                 // Read whether or not the landscape is a TARGET: every service check
                 // below joins against it, so a scoped run needs the map in hand even
-                // when it does not grade the map itself.
-                const land = existsSync(lp) ? await readLandscape(() => loadArchitecture(docsDir)) : null;
+                // when it does not grade the map itself. Through the fleet index, so
+                // the single-service path — which now reads the same project — answers
+                // out of the same memo rather than parsing it a second time.
+                const land = existsSync(lp) ? await readLandscape(() => fleet.architecture(docsDir)) : null;
                 // The fleet-level cross-check first: it frames everything below it, and a
                 // service nobody drew is worth knowing before its own findings scroll past.
                 // Under `--base` it is a target only when `architecture/` changed — the