@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/commands/validate/arch-coverage.js

@@ -0,0 +1,245 @@
+/**
+ * Whether the architecture a delta INTRODUCES is covered by a requirement that
+ * will actually merge.
+ *
+ * Three findings, one question asked three ways: `archedge.uncovered` (a
+ * scenario names the new edge — heuristic, warn-only), `c4.uncovered` (an
+ * arch.spec.md requirement covers the new element or edge — mechanical), and
+ * `covers.unknown` (the `Covers:` line resolves to something real). This is
+ * where agent-built code cuts its corners — the outbox, the retries, the alerts
+ * — because no business scenario was ever going to mention them.
+ *
+ * Split out of `validateFeature` because it is the only part of the feature
+ * target that needs the LIVING landscape: everything else there reads the
+ * feature directory alone. Keeping the lazy load and its two exemption sets in
+ * one module is what stops "new" being decided differently in three places.
+ */
+import { existsSync } from "node:fs";
+import {} from "../../core/c4/likec4.js";
+import { elementService, serviceResolver } from "../../core/c4/resolve/service.js";
+import { groupsServices } from "../../core/c4/resolve/systems.js";
+import {} from "../../core/kernel/ids/service.js";
+import { landscapePath as landscapeFile } from "../../core/repo/paths.js";
+import { locateServicePaths } from "../../core/repo/service-target.js";
+import { enumeratedServiceIds } from "../../core/repo/service-target.js";
+import {} from "../../core/vocabulary/report.js";
+import {} from "../../core/document/spec.js";
+import { coversEdge, coversElement } from "../../core/c4/arch.js";
+import { readHealth } from "../../core/vocabulary/health.js";
+import { FleetContext } from "../../core/fleet-context.js";
+import { ACTOR_KINDS, EXTERNAL_TAG } from "../../core/vocabulary/maturity.js";
+import { coversEntries, coversUnknownFindings } from "./checks/requirements.js";
+import { deltaSpelledCovers, mergedMapOf, survivingEdgeCover, survivingElementCover } from "./coverage/covers-after.js";
+export async function deltaArchCoverage(delta) {
+    const { docsDir, featureDir, featureId, elements, relationships, taggedEls, taggedRels, archDeltas, featureServices, scenarioText, preloadedLand, fleet, } = delta;
+    const findings = [];
+    // The delta's own element→service resolver, built once for the whole feature.
+    // `serviceOf` is a one-shot wrapper that rebuilds its index on every call, and
+    // the two loops below ask it up to five times per tagged edge — so a delta
+    // over a large model paid for one Map of every element per question asked.
+    // The enumerated fleet — `services/` plus the feature's own `specs/` names,
+    // where a service it introduces lives — rides into it, and into `baseSvcOf`
+    // below, which MUST resolve the same way or the already-living exemption
+    // keys never match: so an edge drawn into a modelled container
+    // (`payment.api`) grades against the service that owns it instead of a
+    // service called "api" that has never existed. An unenumerable services/
+    // degrades to the feature's own names, exactly what every caller got before
+    // the set existed.
+    const known = new Set([
+        ...(await enumeratedServiceIds(docsDir, fleet)),
+        ...featureServices,
+    ]);
+    const svcOf = serviceResolver(elements, known);
+    // The map this feature's merge would leave, parsed at most once and only when
+    // a hint or a `Covers:` line needs it (./coverage/covers-after.ts says when).
+    const merged = mergedMapOf({ docsDir, featureDir, featureId, fleet, known });
+    // Arch-edge coverage (heuristic, warn-only): each new tagged edge should be named by a scenario.
+    for (const r of taggedRels) {
+        const target = svcOf(r.target);
+        const covered = edgeCovered(target, r.title, scenarioText);
+        findings.push({
+            severity: covered ? "ok" : "warn",
+            code: covered ? "archedge.covered" : "archedge.uncovered",
+            subject: target,
+            message: `${svcOf(r.source)} → ${target}  "${r.title ?? ""}"${covered ? "" : "  — no scenario names it"}`,
+            text: { indent: 4, header: "arch-edge coverage (heuristic):" },
+        });
+    }
+    // The architecture spec axis, feature scope — the mechanical counterpart of
+    // the heuristic above. Every NEW tagged element and edge in the delta wants a
+    // `Covers:` line in one of the feature's arch.spec.md deltas (c4.uncovered):
+    // this is where agent-built code cuts its corners — the outbox, the retries,
+    // the alerts — because no business scenario was ever going to mention them.
+    // Grouping-only elements take the same exemptions the fleet map applies
+    // (person kinds, #external) — one set, in core/vocabulary/maturity.ts, so
+    // "not a service" cannot mean two things — and so does a GROUPING, an element
+    // that stands for no service and contains one (core/c4/resolve/systems.ts).
+    // A new domain drawn around a new service was asked for a `Covers:` line of
+    // its own: there is no obligation a group can carry, and the service inside
+    // it is graded on its own. Warnings, never archive gates; `--strict`
+    // escalates.
+    //
+    // Only requirements the archive will MERGE grant coverage here. In a delta,
+    // BASE means "the living state, quoted": it merges nothing, emits no
+    // .feature, and yields no scenario.tested claim — so a Covers: line under a
+    // plain `## Requirements` quote is an obligation that ships nowhere, and
+    // counting it silenced c4.uncovered for free. (The service-scope pass keeps
+    // the unfiltered call: a LIVING spec is legitimately all BASE.)
+    const activeCovers = archDeltas.flatMap(({ reqs }) => coversEntries(reqs.filter((r) => r.kind === "ADDED" || r.kind === "MODIFIED")));
+    // What the living landscape ALREADY holds. A delta has to re-declare the
+    // elements its new edges attach to, and authors tag those re-declarations
+    // along with everything else — so a requirements-only feature that touches an
+    // existing service was told to write `Covers:` lines for architecture it is
+    // not adding. c4.uncovered is an obligation on NEW architecture; an element
+    // the living landscape already resolves is not new, whatever the tag says.
+    // Loaded lazily: a delta with nothing tagged never pays for the parse.
+    let living = preloadedLand;
+    const livingLandscape = async () => {
+        if (living === undefined) {
+            const lp = landscapeFile(docsDir);
+            living = existsSync(lp) ? await fleet.loadLikeC4(lp) : null;
+        }
+        return living;
+    };
+    const alreadyLiving = async () => {
+        if (taggedEls.length === 0 && taggedRels.length === 0)
+            return null;
+        const doc = await livingLandscape();
+        return doc !== null && doc.errors.length === 0 ? doc : null;
+    };
+    const base = await alreadyLiving();
+    const baseSvcOf = base === null ? null : serviceResolver(base.elements, known);
+    const baseIds = new Set(base?.elements.map((e) => e.id) ?? []);
+    const baseServices = new Set((base?.elements ?? []).map(elementService));
+    // How a service→service pair is keyed, spelled ONCE. The two sides used to
+    // join with different separators — a NUL where the set was built, a space
+    // where it was queried — so the exemption never matched anything, and every
+    // edge a delta re-declares verbatim (which it must, to attach anything to
+    // it) was reported as new architecture nobody covers. The join is structural
+    // rather than a separator character: the last one was a NUL, and a raw NUL in
+    // a template literal makes the source read as binary to `file` and invisible
+    // to `grep` — which is how a one-character mismatch survived review.
+    const edgeKey = (source, target) => JSON.stringify([source, target]);
+    const baseEdges = new Set((base?.relationships ?? []).map((r) => edgeKey(baseSvcOf(r.source), baseSvcOf(r.target))));
+    for (const e of taggedEls) {
+        if (ACTOR_KINDS.has(e.kind.toLowerCase()) || e.tags.includes(EXTERNAL_TAG) || groupsServices(e, elements, known))
+            continue;
+        if (baseIds.has(e.id) || baseServices.has(elementService(e)))
+            continue;
+        if (activeCovers.some((c) => coversElement(c, e)))
+            continue;
+        // Spelled in the space it will live in, the line covers it too: the id the
+        // merge gives an element is the one the hint below recommends.
+        const cover = await survivingElementCover(e, { svcOf, known }, merged);
+        if (activeCovers.some((c) => c.form === "element" && c.id === cover))
+            continue;
+        findings.push({
+            severity: "warn",
+            code: "c4.uncovered",
+            subject: elementService(e),
+            message: `delta adds '${e.title}' (${e.id}) but no arch requirement covers it — add 'Covers: ${cover}' to a specs/<svc>/arch.spec.md delta, or its architectural obligations ship unchecked`,
+        });
+    }
+    for (const r of taggedRels) {
+        if (baseEdges.has(edgeKey(svcOf(r.source), svcOf(r.target))))
+            continue;
+        if (activeCovers.some((c) => coversEdge(c, r, elements, known)))
+            continue;
+        findings.push({
+            severity: "warn",
+            code: "c4.uncovered",
+            subject: svcOf(r.target),
+            message: `delta adds edge ${svcOf(r.source)} → ${svcOf(r.target)} ("${r.title ?? ""}") but no arch requirement covers it — add 'Covers: ${survivingEdgeCover(r, svcOf)}' to a specs/<svc>/arch.spec.md delta`,
+        });
+    }
+    // covers.unknown, feature scope. Resolution looks at the delta itself, the
+    // living landscape, the service's own model and its health.yaml — a delta's
+    // arch requirement may cover an element it adds, one that already exists, or
+    // an alert the service declares. The landscape and each model are loaded
+    // lazily, and only when an entry fails against what is already in hand: the
+    // clean path never pays for a workspace spin.
+    if (archDeltas.some(({ reqs }) => coversEntries(reqs).length > 0)) {
+        const land = await livingLandscape();
+        const landParses = land !== null && land.errors.length === 0 ? land : null;
+        const baseElements = [...elements, ...(landParses?.elements ?? [])];
+        const baseRels = [...relationships, ...(landParses?.relationships ?? [])];
+        // A feature never brings topology through `delta.likec4` — a `deployment { }`
+        // block in one is refused by the merge — so the living map is the whole
+        // scope for a `node:` entry in a delta, exactly as it is in service scope.
+        const baseDeployment = landParses?.deployment;
+        for (const { service: svc, reqs } of archDeltas) {
+            // An unreadable living health.yaml mutes the alert:/sli: entries here
+            // exactly as in service scope — the health.invalid finding itself
+            // belongs to the service target, which owns the file's diagnosis.
+            const svcPaths = await locateServicePaths(docsDir, svc, fleet);
+            const health = await readHealth(svcPaths.health);
+            // Through the ONE reader of `model.likec4`: a model that EXTENDS the map
+            // is not a file this could open, and reading it as one would answer with
+            // a pile of parse errors — which this arm reads as "no widening", so
+            // every `Covers:` line naming a container of a migrated service would be
+            // convicted as a typo. `mapUnreadable` is the same silence for the same
+            // reason: nothing may widen a scope out of a document nobody could read.
+            // Read at most once, and only when a line needs it.
+            let modelRead;
+            const model = () => (modelRead ??= (async () => {
+                const m = existsSync(svcPaths.model) ? await fleet.serviceModel(docsDir, svcPaths) : null;
+                return m !== null && !m.mapUnreadable && m.doc.errors.length === 0
+                    ? { elements: m.doc.elements, relationships: m.doc.relationships }
+                    : { elements: [], relationships: [] };
+            })());
+            let scope = {
+                elements: baseElements,
+                relationships: baseRels,
+                ...(baseDeployment === undefined ? {} : { deployment: baseDeployment }),
+                health: health.ids,
+                known,
+            };
+            const unresolved = coversUnknownFindings(reqs, { where: `${svc}: arch.spec.md`, subject: svc }, scope, health.unreadable);
+            if (unresolved.length > 0) {
+                const m = await model();
+                // Widened, never narrowed: the topology rides along. Rebuilding the
+                // record without it convicted every `node:` entry as a typo the moment
+                // another entry beside it sent the scope here.
+                scope = {
+                    ...scope,
+                    elements: [...baseElements, ...m.elements],
+                    relationships: [...baseRels, ...m.relationships],
+                };
+                // The map the merge would leave widens it last, and only for a line still
+                // unresolved: one spelled the way the living map will spell an element
+                // this feature adds resolves there and nowhere else yet — and it is the
+                // spelling the hints recommend.
+                const after = coversUnknownFindings(reqs, { where: svc, subject: svc }, scope, health.unreadable).length > 0 ? (await merged())?.doc : undefined;
+                if (after !== undefined) {
+                    scope = { ...scope, elements: [...scope.elements, ...after.elements], relationships: [...scope.relationships, ...after.relationships] };
+                }
+                findings.push(...coversUnknownFindings(reqs, { where: `${svc}: arch.spec.md`, subject: svc }, scope, health.unreadable));
+            }
+            // And the lines that DID resolve, read in the space they will live in:
+            // one that answered only through the delta's own ids is `covers.unknown`
+            // the moment the archive lands it (./coverage/covers-after.ts).
+            findings.push(...(await deltaSpelledCovers({
+                service: svc,
+                reqs,
+                featureScope: scope,
+                living: { elements: landParses?.elements ?? [], relationships: landParses?.relationships ?? [] },
+                model,
+                elements,
+                svcOf,
+                merged,
+            })));
+        }
+    }
+    return findings;
+}
+/** Heuristic: an edge is "covered" if a scenario names the target or a keyword from the edge title. */
+function edgeCovered(target, title, scenarioText) {
+    if (scenarioText.includes(target.toLowerCase()))
+        return true;
+    for (const token of (title ?? "").split(/[^A-Za-z0-9]+/)) {
+        if (token.length >= 5 && scenarioText.includes(token.toLowerCase()))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=arch-coverage.js.map

package/dist/commands/validate/arch-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arch-coverage.js","sourceRoot":"","sources":["../../../src/commands/validate/arch-coverage.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Whether the architecture a delta INTRODUCES is covered by a requirement that\n * will actually merge.\n *\n * Three findings, one question asked three ways: `archedge.uncovered` (a\n * scenario names the new edge — heuristic, warn-only), `c4.uncovered` (an\n * arch.spec.md requirement covers the new element or edge — mechanical), and\n * `covers.unknown` (the `Covers:` line resolves to something real). This is\n * where agent-built code cuts its corners — the outbox, the retries, the alerts\n * — because no business scenario was ever going to mention them.\n *\n * Split out of `validateFeature` because it is the only part of the feature\n * target that needs the LIVING landscape: everything else there reads the\n * feature directory alone. Keeping the lazy load and its two exemption sets in\n * one module is what stops \"new\" being decided differently in three places.\n */\nimport { existsSync } from \"node:fs\";\nimport { type Elem, type LoadedDoc, type Rel } from \"../../core/c4/likec4.js\";\nimport { elementService, serviceResolver } from \"../../core/c4/resolve/service.js\";\nimport { groupsServices } from \"../../core/c4/resolve/systems.js\";\nimport { type PathableService } from \"../../core/kernel/ids/service.js\";\nimport { landscapePath as landscapeFile } from \"../../core/repo/paths.js\";\nimport { locateServicePaths } from \"../../core/repo/service-target.js\";\nimport { enumeratedServiceIds } from \"../../core/repo/service-target.js\";\nimport { type Finding } from \"../../core/vocabulary/report.js\";\nimport { type Requirement } from \"../../core/document/spec.js\";\nimport { coversEdge, coversElement, type CoverageScope } from \"../../core/c4/arch.js\";\nimport { readHealth } from \"../../core/vocabulary/health.js\";\nimport { FleetContext } from \"../../core/fleet-context.js\";\nimport { ACTOR_KINDS, EXTERNAL_TAG } from \"../../core/vocabulary/maturity.js\";\nimport { coversEntries, coversUnknownFindings } from \"./checks/requirements.js\";\nimport { deltaSpelledCovers, mergedMapOf, survivingEdgeCover, survivingElementCover } from \"./coverage/covers-after.js\";\nimport type { DocsDir, FeatureDir } from \"../../core/kernel/ids/dirs.js\";\n\n/** One feature delta's architecture, and everything needed to decide what in it is new. */\nexport interface DeltaArch {\n  docsDir: DocsDir;\n  /** The feature itself — what the merge preview a `Covers:` line is checked against is computed from. */\n  featureDir: FeatureDir;\n  featureId: string;\n  /** Every element the delta declares — the resolver's index, and `coversEdge`'s scope. */\n  elements: Elem[];\n  /** Every relationship the delta declares. */\n  relationships: Rel[];\n  /** The delta's own additions: elements and edges carrying the feature id as a tag. */\n  taggedEls: Elem[];\n  taggedRels: Rel[];\n  /** Each addressed service's arch.spec.md delta, in enumeration order. */\n  archDeltas: Array<{ service: PathableService; reqs: Requirement[] }>;\n  /**\n   * Every service the feature's `specs/` addresses — not just the ones with an\n   * arch delta. The resolver's fleet set unions these in because a service the\n   * feature INTRODUCES has no `services/` directory yet, and without its name\n   * an edge into that service's own modelled container resolved to the\n   * container's title — a phantom the fleet half alone cannot rule out.\n   */\n  featureServices: PathableService[];\n  /** Every scenario the feature's deltas carry, lowercased — the heuristic's haystack. */\n  scenarioText: string;\n  /** The living landscape under --all; undefined means \"load it if you need it\", null \"there is none\". */\n  preloadedLand?: LoadedDoc | null;\n  /**\n   * The read index the service models below are read through. Required, for\n   * `validateService`'s reason: `serviceModel` needs the enumeration and a\n   * document memo to answer at all. Every validate mode builds one before it\n   * grades anything — `--feature` included (`validate.ts`) — so there is no\n   * second, unmemoised reading rule here for a run that arrived without one.\n   */\n  fleet: FleetContext;\n}\n\nexport async function deltaArchCoverage(delta: DeltaArch): Promise<Finding[]> {\n  const {\n    docsDir,\n    featureDir,\n    featureId,\n    elements,\n    relationships,\n    taggedEls,\n    taggedRels,\n    archDeltas,\n    featureServices,\n    scenarioText,\n    preloadedLand,\n    fleet,\n  } = delta;\n  const findings: Finding[] = [];\n\n  // The delta's own element→service resolver, built once for the whole feature.\n  // `serviceOf` is a one-shot wrapper that rebuilds its index on every call, and\n  // the two loops below ask it up to five times per tagged edge — so a delta\n  // over a large model paid for one Map of every element per question asked.\n  // The enumerated fleet — `services/` plus the feature's own `specs/` names,\n  // where a service it introduces lives — rides into it, and into `baseSvcOf`\n  // below, which MUST resolve the same way or the already-living exemption\n  // keys never match: so an edge drawn into a modelled container\n  // (`payment.api`) grades against the service that owns it instead of a\n  // service called \"api\" that has never existed. An unenumerable services/\n  // degrades to the feature's own names, exactly what every caller got before\n  // the set existed.\n  const known: ReadonlySet<string> = new Set<string>([\n    ...(await enumeratedServiceIds(docsDir, fleet)),\n    ...featureServices,\n  ]);\n  const svcOf = serviceResolver(elements, known);\n  // The map this feature's merge would leave, parsed at most once and only when\n  // a hint or a `Covers:` line needs it (./coverage/covers-after.ts says when).\n  const merged = mergedMapOf({ docsDir, featureDir, featureId, fleet, known });\n\n  // Arch-edge coverage (heuristic, warn-only): each new tagged edge should be named by a scenario.\n  for (const r of taggedRels) {\n    const target = svcOf(r.target);\n    const covered = edgeCovered(target, r.title, scenarioText);\n    findings.push({\n      severity: covered ? \"ok\" : \"warn\",\n      code: covered ? \"archedge.covered\" : \"archedge.uncovered\",\n      subject: target,\n      message: `${svcOf(r.source)} → ${target}  \"${r.title ?? \"\"}\"${covered ? \"\" : \"  — no scenario names it\"}`,\n      text: { indent: 4, header: \"arch-edge coverage (heuristic):\" },\n    });\n  }\n\n  // The architecture spec axis, feature scope — the mechanical counterpart of\n  // the heuristic above. Every NEW tagged element and edge in the delta wants a\n  // `Covers:` line in one of the feature's arch.spec.md deltas (c4.uncovered):\n  // this is where agent-built code cuts its corners — the outbox, the retries,\n  // the alerts — because no business scenario was ever going to mention them.\n  // Grouping-only elements take the same exemptions the fleet map applies\n  // (person kinds, #external) — one set, in core/vocabulary/maturity.ts, so\n  // \"not a service\" cannot mean two things — and so does a GROUPING, an element\n  // that stands for no service and contains one (core/c4/resolve/systems.ts).\n  // A new domain drawn around a new service was asked for a `Covers:` line of\n  // its own: there is no obligation a group can carry, and the service inside\n  // it is graded on its own. Warnings, never archive gates; `--strict`\n  // escalates.\n  //\n  // Only requirements the archive will MERGE grant coverage here. In a delta,\n  // BASE means \"the living state, quoted\": it merges nothing, emits no\n  // .feature, and yields no scenario.tested claim — so a Covers: line under a\n  // plain `## Requirements` quote is an obligation that ships nowhere, and\n  // counting it silenced c4.uncovered for free. (The service-scope pass keeps\n  // the unfiltered call: a LIVING spec is legitimately all BASE.)\n  const activeCovers = archDeltas.flatMap(({ reqs }) =>\n    coversEntries(reqs.filter((r) => r.kind === \"ADDED\" || r.kind === \"MODIFIED\")),\n  );\n\n  // What the living landscape ALREADY holds. A delta has to re-declare the\n  // elements its new edges attach to, and authors tag those re-declarations\n  // along with everything else — so a requirements-only feature that touches an\n  // existing service was told to write `Covers:` lines for architecture it is\n  // not adding. c4.uncovered is an obligation on NEW architecture; an element\n  // the living landscape already resolves is not new, whatever the tag says.\n  // Loaded lazily: a delta with nothing tagged never pays for the parse.\n  let living: LoadedDoc | null | undefined = preloadedLand;\n  const livingLandscape = async (): Promise<LoadedDoc | null> => {\n    if (living === undefined) {\n      const lp = landscapeFile(docsDir);\n      living = existsSync(lp) ? await fleet.loadLikeC4(lp) : null;\n    }\n    return living;\n  };\n  const alreadyLiving = async (): Promise<LoadedDoc | null> => {\n    if (taggedEls.length === 0 && taggedRels.length === 0) return null;\n    const doc = await livingLandscape();\n    return doc !== null && doc.errors.length === 0 ? doc : null;\n  };\n  const base = await alreadyLiving();\n  const baseSvcOf = base === null ? null : serviceResolver(base.elements, known);\n  const baseIds = new Set(base?.elements.map((e) => e.id) ?? []);\n  const baseServices = new Set((base?.elements ?? []).map(elementService));\n  // How a service→service pair is keyed, spelled ONCE. The two sides used to\n  // join with different separators — a NUL where the set was built, a space\n  // where it was queried — so the exemption never matched anything, and every\n  // edge a delta re-declares verbatim (which it must, to attach anything to\n  // it) was reported as new architecture nobody covers. The join is structural\n  // rather than a separator character: the last one was a NUL, and a raw NUL in\n  // a template literal makes the source read as binary to `file` and invisible\n  // to `grep` — which is how a one-character mismatch survived review.\n  const edgeKey = (source: string, target: string): string => JSON.stringify([source, target]);\n  const baseEdges = new Set(\n    (base?.relationships ?? []).map((r) => edgeKey(baseSvcOf!(r.source), baseSvcOf!(r.target))),\n  );\n\n  for (const e of taggedEls) {\n    if (ACTOR_KINDS.has(e.kind.toLowerCase()) || e.tags.includes(EXTERNAL_TAG) || groupsServices(e, elements, known)) continue;\n    if (baseIds.has(e.id) || baseServices.has(elementService(e))) continue;\n    if (activeCovers.some((c) => coversElement(c, e))) continue;\n    // Spelled in the space it will live in, the line covers it too: the id the\n    // merge gives an element is the one the hint below recommends.\n    const cover = await survivingElementCover(e, { svcOf, known }, merged);\n    if (activeCovers.some((c) => c.form === \"element\" && c.id === cover)) continue;\n    findings.push({\n      severity: \"warn\",\n      code: \"c4.uncovered\",\n      subject: elementService(e),\n      message: `delta adds '${e.title}' (${e.id}) but no arch requirement covers it — add 'Covers: ${cover}' to a specs/<svc>/arch.spec.md delta, or its architectural obligations ship unchecked`,\n    });\n  }\n  for (const r of taggedRels) {\n    if (baseEdges.has(edgeKey(svcOf(r.source), svcOf(r.target)))) continue;\n    if (activeCovers.some((c) => coversEdge(c, r, elements, known))) continue;\n    findings.push({\n      severity: \"warn\",\n      code: \"c4.uncovered\",\n      subject: svcOf(r.target),\n      message: `delta adds edge ${svcOf(r.source)} → ${svcOf(r.target)} (\"${r.title ?? \"\"}\") but no arch requirement covers it — add 'Covers: ${survivingEdgeCover(r, svcOf)}' to a specs/<svc>/arch.spec.md delta`,\n    });\n  }\n\n  // covers.unknown, feature scope. Resolution looks at the delta itself, the\n  // living landscape, the service's own model and its health.yaml — a delta's\n  // arch requirement may cover an element it adds, one that already exists, or\n  // an alert the service declares. The landscape and each model are loaded\n  // lazily, and only when an entry fails against what is already in hand: the\n  // clean path never pays for a workspace spin.\n  if (archDeltas.some(({ reqs }) => coversEntries(reqs).length > 0)) {\n    const land = await livingLandscape();\n    const landParses = land !== null && land.errors.length === 0 ? land : null;\n    const baseElements = [...elements, ...(landParses?.elements ?? [])];\n    const baseRels = [...relationships, ...(landParses?.relationships ?? [])];\n    // A feature never brings topology through `delta.likec4` — a `deployment { }`\n    // block in one is refused by the merge — so the living map is the whole\n    // scope for a `node:` entry in a delta, exactly as it is in service scope.\n    const baseDeployment = landParses?.deployment;\n    for (const { service: svc, reqs } of archDeltas) {\n      // An unreadable living health.yaml mutes the alert:/sli: entries here\n      // exactly as in service scope — the health.invalid finding itself\n      // belongs to the service target, which owns the file's diagnosis.\n      const svcPaths = await locateServicePaths(docsDir, svc, fleet);\n      const health = await readHealth(svcPaths.health);\n      // Through the ONE reader of `model.likec4`: a model that EXTENDS the map\n      // is not a file this could open, and reading it as one would answer with\n      // a pile of parse errors — which this arm reads as \"no widening\", so\n      // every `Covers:` line naming a container of a migrated service would be\n      // convicted as a typo. `mapUnreadable` is the same silence for the same\n      // reason: nothing may widen a scope out of a document nobody could read.\n      // Read at most once, and only when a line needs it.\n      let modelRead: Promise<{ elements: Elem[]; relationships: Rel[] }> | undefined;\n      const model = (): Promise<{ elements: Elem[]; relationships: Rel[] }> =>\n        (modelRead ??= (async () => {\n          const m = existsSync(svcPaths.model) ? await fleet.serviceModel(docsDir, svcPaths) : null;\n          return m !== null && !m.mapUnreadable && m.doc.errors.length === 0\n            ? { elements: m.doc.elements, relationships: m.doc.relationships }\n            : { elements: [], relationships: [] };\n        })());\n      let scope: CoverageScope = {\n        elements: baseElements,\n        relationships: baseRels,\n        ...(baseDeployment === undefined ? {} : { deployment: baseDeployment }),\n        health: health.ids,\n        known,\n      };\n      const unresolved = coversUnknownFindings(reqs, { where: `${svc}: arch.spec.md`, subject: svc }, scope, health.unreadable);\n      if (unresolved.length > 0) {\n        const m = await model();\n        // Widened, never narrowed: the topology rides along. Rebuilding the\n        // record without it convicted every `node:` entry as a typo the moment\n        // another entry beside it sent the scope here.\n        scope = {\n          ...scope,\n          elements: [...baseElements, ...m.elements],\n          relationships: [...baseRels, ...m.relationships],\n        };\n        // The map the merge would leave widens it last, and only for a line still\n        // unresolved: one spelled the way the living map will spell an element\n        // this feature adds resolves there and nowhere else yet — and it is the\n        // spelling the hints recommend.\n        const after = coversUnknownFindings(reqs, { where: svc, subject: svc }, scope, health.unreadable).length > 0 ? (await merged())?.doc : undefined;\n        if (after !== undefined) {\n          scope = { ...scope, elements: [...scope.elements, ...after.elements], relationships: [...scope.relationships, ...after.relationships] };\n        }\n        findings.push(...coversUnknownFindings(reqs, { where: `${svc}: arch.spec.md`, subject: svc }, scope, health.unreadable));\n      }\n      // And the lines that DID resolve, read in the space they will live in:\n      // one that answered only through the delta's own ids is `covers.unknown`\n      // the moment the archive lands it (./coverage/covers-after.ts).\n      findings.push(\n        ...(await deltaSpelledCovers({\n          service: svc,\n          reqs,\n          featureScope: scope,\n          living: { elements: landParses?.elements ?? [], relationships: landParses?.relationships ?? [] },\n          model,\n          elements,\n          svcOf,\n          merged,\n        })),\n      );\n    }\n  }\n\n  return findings;\n}\n\n/** Heuristic: an edge is \"covered\" if a scenario names the target or a keyword from the edge title. */\nfunction edgeCovered(target: string, title: string | undefined, scenarioText: string): boolean {\n  if (scenarioText.includes(target.toLowerCase())) return true;\n  for (const token of (title ?? \"\").split(/[^A-Za-z0-9]+/)) {\n    if (token.length >= 5 && scenarioText.includes(token.toLowerCase())) return true;\n  }\n  return false;\n}\n"]}

package/dist/commands/validate/checks/fleet-shape.js

@@ -0,0 +1,204 @@
+/**
+ * Fleet-shape advisories over the parsed landscape: the way a fleet map stops
+ * answering questions as it grows, caught while the map is already in memory.
+ *
+ * The shape becomes visible at service three rather than service two.
+ * Ubiquitous infrastructure — logging Kafka, an identity provider, service
+ * discovery — takes one inbound edge per modelled service until the map is a
+ * hairball around it; deleting the element fixes the picture and loses "who
+ * depends on the Identity Provider", which is the question the map exists to
+ * answer during an incident. Tagging keeps both: the fleet view excludes
+ * `#platform`, and a platform view keeps the dependents.
+ *
+ * The DATASTORE half of this pair moved to `../fleet/map/consumers.ts` when its
+ * consumer count stopped being a fact about the map alone: a private store now
+ * lives nested inside its owner's element, and the services reaching it are
+ * attested in their own models (E3/R1). The census both checks read is built
+ * there and handed in here as `consumers`, so a hub and a store can never
+ * disagree about who consumes what.
+ *
+ * loam still reads no code and decides no policy: the team chooses what counts
+ * as platform — this warning only names a shape that is usually wrong.
+ */
+import { existsSync } from "node:fs";
+import {} from "../../../core/c4/likec4.js";
+import {} from "../../../core/vocabulary/report.js";
+import {} from "../../../core/repo/entries.js";
+import { permissionsPath, servicePathsAt } from "../../../core/repo/paths.js";
+import { readVocabulary } from "../../../core/permissions/permissions.js";
+import { capabilityDocFindings, capabilityRequirementIndex, docMissingFindings, gradableCapabilityIds, invalidVocabularyFinding, unrealizedFindings, } from "../../../core/capabilities/findings.js";
+import { useCaseRequirementClaims } from "../../../core/usecases/capability.js";
+import { capabilityRollup, usedCapabilities } from "../../../core/capabilities/rollup.js";
+import { requirementUnrealizedFindings } from "../../../core/capabilities/realizes/findings.js";
+import { FleetContext } from "../../../core/fleet-context.js";
+import { EXTERNAL_TAG, PLATFORM_TAG } from "../../../core/vocabulary/maturity.js";
+/**
+ * Consumers at which an untagged external hub starts to warn. Three, not two:
+ * two services sharing a dependency is a fact about those two services, the
+ * same edge from three is a pattern about the element — and three is where
+ * the shared hub starts making the map unreadable.
+ */
+export const PLATFORM_CANDIDATE_MIN_CONSUMERS = 3;
+export function fleetShapeFindings(shape) {
+    const { drawn, services } = shape;
+    const findings = [];
+    for (const e of drawn) {
+        // An element that stands for a real service is the fleet itself, not its
+        // shape: many consumers is what a well-used service looks like.
+        if (e.service !== undefined || services.has(e.title))
+            continue;
+        if (!e.tags.includes(EXTERNAL_TAG) || e.tags.includes(PLATFORM_TAG))
+            continue;
+        const consumers = shape.consumers(e.id);
+        if (consumers.length < PLATFORM_CANDIDATE_MIN_CONSUMERS)
+            continue;
+        findings.push({
+            severity: "warn",
+            code: "landscape.platform-candidate",
+            subject: e.title,
+            message: `landscape: '${e.title}' is consumed by ${consumers.length} services (${consumers.join(", ")}) ` +
+                `and is not tagged #platform — a hub like this takes one more edge per modelled service until ` +
+                `the fleet view is unreadable. Declare \`tag platform\` in the specification block and tag the ` +
+                `element (LikeC4 refuses an undeclared tag, so both steps are needed): the fleet view then ` +
+                `excludes it, and a platform view over \`include * -> element.tag = #platform\` keeps ` +
+                `"who depends on it" answerable`,
+        });
+    }
+    return findings;
+}
+/**
+ * The authorization vocabulary graded against the fleet that uses it — the half
+ * of the axis no single service can answer.
+ *
+ * `permissions.invalid` is an error and it is the only one reported when it
+ * fires: a vocabulary nobody can read resolves nothing, so every `Requires:`
+ * line in the fleet would follow it as `permissions.unknown`, and a hundred
+ * findings about one broken file is a cascade, not a diagnosis.
+ *
+ * `permissions.unenforced` is the mirror of `api.ungoverned`, and it earns its
+ * place for the same reason: a vocabulary is only worth what cites it. A
+ * permission nothing requires is either a rule that was removed and left its
+ * word behind, or a word nobody adopted — both are drift, and neither is
+ * visible from inside the file. Warn, because the honest answer is sometimes
+ * "not modelled yet".
+ */
+export async function permissionFindings(docsDir, services, fleet) {
+    const vocabulary = await readVocabulary(permissionsPath(docsDir));
+    if (!vocabulary.present)
+        return [];
+    if (vocabulary.invalid !== undefined) {
+        return [
+            {
+                severity: "error",
+                code: "permissions.invalid",
+                message: `landscape: architecture/permissions.yaml does not read as a vocabulary — ${vocabulary.invalid}. ` +
+                    "Every `Requires:` line in the fleet resolves against this file, so none of them can be graded until it parses. " +
+                    "The shape is `subjects: {<kind>: {description}}` then `permissions: {<kind>: {<name>: {description, owned_by, enforced_by}}}`.",
+            },
+        ];
+    }
+    const used = new Set();
+    for (const entry of services) {
+        const paths = servicePathsAt(entry.dir);
+        for (const path of [paths.spec, paths.archSpec]) {
+            // Existence first, and for BOTH documents: arch.spec.md is optional (most
+            // of a legacy fleet has none) and spec.md is missing on a half-adopted
+            // service. `FleetContext.readRequirements` throws ENOENT, which surfaces
+            // as `repository-unavailable` and takes the whole `--all` run down — an
+            // absent optional artifact must never be able to do that.
+            if (!existsSync(path))
+                continue;
+            const reqs = await fleet.readRequirements(path);
+            for (const r of reqs) {
+                if (r.kind !== "REMOVED")
+                    for (const p of r.requires)
+                        used.add(p);
+            }
+        }
+    }
+    const unenforced = [...vocabulary.byId.keys()].filter((id) => !used.has(id));
+    if (unenforced.length === 0)
+        return [];
+    return [
+        {
+            severity: "warn",
+            code: "permissions.unenforced",
+            message: `landscape: ${unenforced.length} declared permission(s) that no requirement's \`Requires:\` line names — write the requirement that gates on each, or drop the declaration`,
+            details: unenforced,
+        },
+    ];
+}
+/**
+ * The capability vocabulary graded against the fleet that realizes it — the
+ * axis's fleet half, beside permissionFindings and shaped by the same two
+ * verdicts. `capability.invalid` is a `validate --all` run's ONE finding about
+ * an unreadable file — fleet scope, so single-target runs stay silent about
+ * it — and it suppresses the rest of the family (the unknown
+ * grades at every service target return [] for the same vocabulary — one
+ * breach, one finding, never a cascade). `capability.unrealized` is one warn
+ * PER declared-but-unnamed capability, subject = the id, because the roadmap's
+ * criterion is 'one warning per capability, not one per service'. Holding
+ * NEITHER `architecture/capabilities.yaml` nor `capabilities/` is total
+ * silence: the fleet's own files are this axis's opt-in, either of them.
+ *
+ * The used set comes through capabilityRollup with the fleet's own cached
+ * reader, so under --all the walk re-parses nothing the service targets have
+ * not already paid for — and the rollup, the warn and `loam list capabilities`
+ * can never disagree about what "realized" means.
+ *
+ * The AUTHORED documents are graded here too, and they ride this function
+ * rather than a target of their own for `viewsStaleFindings`' reason one tree
+ * over: a capability belongs to no service, so only the fleet run has the whole
+ * vocabulary and the enumerated tree in view at once. Their reads are NOT
+ * wrapped, deliberately — a `capabilities/<id>/spec.md` that is not UTF-8 takes
+ * the run down exactly as a `services/<id>/spec.md` does, because a document
+ * loam cannot decode is a refusal everywhere else in the product and a quiet
+ * "zero requirements" here would grade a whole capability green on bytes
+ * nobody read.
+ */
+export async function capabilityFleetFindings(docsDir, services, fleet, flows) {
+    const vocab = await fleet.capabilities(docsDir);
+    if (!vocab.present)
+        return [];
+    const read = (p) => fleet.readRequirements(p);
+    const authored = docMissingFindings(vocab.tree);
+    for (const doc of vocab.tree.docs)
+        authored.push(...capabilityDocFindings(await read(doc.spec), doc.id));
+    const invalid = invalidVocabularyFinding(vocab);
+    if (invalid !== null)
+        return [invalid, ...authored];
+    // A USE CASE IS THE OTHER WAY TO KEEP A PROMISE, and it is the only carrier a
+    // cross-service criterion has: "I enter a login and a password and I am in"
+    // belongs to no single service's spec, so a fleet could satisfy it perfectly
+    // through a `#cap-`/`#req-` tagged flow and still be told nobody realizes it.
+    //
+    // The claims go INTO the rollup rather than beside it, so both unrealized
+    // grades and `loam list capabilities` read one set of rows. `flows === null`
+    // means loam could not READ the flows (no preload, or an `architecture/` that
+    // did not parse); the key is then OMITTED rather than empty, and every
+    // `keptBy` below is `undefined` — the three-state contract `rollup.ts` states.
+    const index = await capabilityRequirementIndex(vocab, read);
+    const keptByFlows = flows === null
+        ? undefined
+        : useCaseRequirementClaims(flows, gradableCapabilityIds(vocab), (c) => index.byCapability.get(c));
+    const rows = await capabilityRollup({ services, vocab, read, ...(keptByFlows === undefined ? {} : { keptByFlows }) });
+    // The two unrealized grades read the SAME rollup, which is what keeps them
+    // from disagreeing about the word: a capability is unrealized when nothing
+    // names it by any join, and one of its requirements is unrealized when nothing
+    // keeps that promise. Both are warnings, and the second is the one that
+    // survives a healthy-looking row — a capability with four requirements and
+    // three kept reports nothing at all through the first.
+    //
+    // The suspension falls out of the DATA rather than a branch: `keptBy` absent
+    // means nobody looked, and a promise nobody looked for is not a promise
+    // reported unkept.
+    const unrealizedRequirements = rows.flatMap((row) => (row.requirements ?? [])
+        .filter((req) => req.realizedBy.length === 0 && req.keptBy?.length === 0)
+        .map((req) => ({ capability: row.id, id: req.id, name: req.name })));
+    return [
+        ...authored,
+        ...unrealizedFindings(vocab, usedCapabilities(rows)),
+        ...requirementUnrealizedFindings(unrealizedRequirements),
+    ];
+}
+//# sourceMappingURL=fleet-shape.js.map

package/dist/commands/validate/checks/fleet-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-shape.js","sourceRoot":"","sources":["../../../../src/commands/validate/checks/fleet-shape.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Fleet-shape advisories over the parsed landscape: the way a fleet map stops\n * answering questions as it grows, caught while the map is already in memory.\n *\n * The shape becomes visible at service three rather than service two.\n * Ubiquitous infrastructure — logging Kafka, an identity provider, service\n * discovery — takes one inbound edge per modelled service until the map is a\n * hairball around it; deleting the element fixes the picture and loses \"who\n * depends on the Identity Provider\", which is the question the map exists to\n * answer during an incident. Tagging keeps both: the fleet view excludes\n * `#platform`, and a platform view keeps the dependents.\n *\n * The DATASTORE half of this pair moved to `../fleet/map/consumers.ts` when its\n * consumer count stopped being a fact about the map alone: a private store now\n * lives nested inside its owner's element, and the services reaching it are\n * attested in their own models (E3/R1). The census both checks read is built\n * there and handed in here as `consumers`, so a hub and a store can never\n * disagree about who consumes what.\n *\n * loam still reads no code and decides no policy: the team chooses what counts\n * as platform — this warning only names a shape that is usually wrong.\n */\nimport { existsSync } from \"node:fs\";\nimport { type Elem } from \"../../../core/c4/likec4.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { type ServiceEntry } from \"../../../core/repo/entries.js\";\nimport { permissionsPath, servicePathsAt } from \"../../../core/repo/paths.js\";\nimport { readVocabulary } from \"../../../core/permissions/permissions.js\";\nimport {\n  capabilityDocFindings,\n  capabilityRequirementIndex,\n  docMissingFindings,\n  gradableCapabilityIds,\n  invalidVocabularyFinding,\n  unrealizedFindings,\n} from \"../../../core/capabilities/findings.js\";\nimport { useCaseRequirementClaims } from \"../../../core/usecases/capability.js\";\nimport type { ParsedView } from \"../../../core/c4/parsed/dynamic-views.js\";\nimport { capabilityRollup, usedCapabilities } from \"../../../core/capabilities/rollup.js\";\nimport { requirementUnrealizedFindings } from \"../../../core/capabilities/realizes/findings.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { EXTERNAL_TAG, PLATFORM_TAG } from \"../../../core/vocabulary/maturity.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\n\n/**\n * Consumers at which an untagged external hub starts to warn. Three, not two:\n * two services sharing a dependency is a fact about those two services, the\n * same edge from three is a pattern about the element — and three is where\n * the shared hub starts making the map unreadable.\n */\nexport const PLATFORM_CANDIDATE_MIN_CONSUMERS = 3;\n\nexport interface FleetShape {\n  /** Service-LEVEL elements — the fleet map's own boxes (landscape.ts `drawn`). */\n  drawn: Elem[];\n  /** The services/<id>/ directories that exist. */\n  services: ReadonlySet<string>;\n  /**\n   * Distinct consumer SERVICES of an element, its nested children included —\n   * `../fleet/map/consumers.ts` owns the derivation and both checks that read a\n   * consumer count share this one instance of it.\n   */\n  consumers: (elementId: string) => string[];\n}\n\nexport function fleetShapeFindings(shape: FleetShape): Finding[] {\n  const { drawn, services } = shape;\n  const findings: Finding[] = [];\n\n  for (const e of drawn) {\n    // An element that stands for a real service is the fleet itself, not its\n    // shape: many consumers is what a well-used service looks like.\n    if (e.service !== undefined || services.has(e.title)) continue;\n    if (!e.tags.includes(EXTERNAL_TAG) || e.tags.includes(PLATFORM_TAG)) continue;\n    const consumers = shape.consumers(e.id);\n    if (consumers.length < PLATFORM_CANDIDATE_MIN_CONSUMERS) continue;\n    findings.push({\n      severity: \"warn\",\n      code: \"landscape.platform-candidate\",\n      subject: e.title,\n      message:\n        `landscape: '${e.title}' is consumed by ${consumers.length} services (${consumers.join(\", \")}) ` +\n        `and is not tagged #platform — a hub like this takes one more edge per modelled service until ` +\n        `the fleet view is unreadable. Declare \\`tag platform\\` in the specification block and tag the ` +\n        `element (LikeC4 refuses an undeclared tag, so both steps are needed): the fleet view then ` +\n        `excludes it, and a platform view over \\`include * -> element.tag = #platform\\` keeps ` +\n        `\"who depends on it\" answerable`,\n    });\n  }\n  return findings;\n}\n\n/**\n * The authorization vocabulary graded against the fleet that uses it — the half\n * of the axis no single service can answer.\n *\n * `permissions.invalid` is an error and it is the only one reported when it\n * fires: a vocabulary nobody can read resolves nothing, so every `Requires:`\n * line in the fleet would follow it as `permissions.unknown`, and a hundred\n * findings about one broken file is a cascade, not a diagnosis.\n *\n * `permissions.unenforced` is the mirror of `api.ungoverned`, and it earns its\n * place for the same reason: a vocabulary is only worth what cites it. A\n * permission nothing requires is either a rule that was removed and left its\n * word behind, or a word nobody adopted — both are drift, and neither is\n * visible from inside the file. Warn, because the honest answer is sometimes\n * \"not modelled yet\".\n */\nexport async function permissionFindings(\n  docsDir: DocsDir,\n  services: ServiceEntry[],\n  fleet: FleetContext,\n): Promise<Finding[]> {\n  const vocabulary = await readVocabulary(permissionsPath(docsDir));\n  if (!vocabulary.present) return [];\n  if (vocabulary.invalid !== undefined) {\n    return [\n      {\n        severity: \"error\",\n        code: \"permissions.invalid\",\n        message:\n          `landscape: architecture/permissions.yaml does not read as a vocabulary — ${vocabulary.invalid}. ` +\n          \"Every `Requires:` line in the fleet resolves against this file, so none of them can be graded until it parses. \" +\n          \"The shape is `subjects: {<kind>: {description}}` then `permissions: {<kind>: {<name>: {description, owned_by, enforced_by}}}`.\",\n      },\n    ];\n  }\n  const used = new Set<string>();\n  for (const entry of services) {\n    const paths = servicePathsAt(entry.dir);\n    for (const path of [paths.spec, paths.archSpec]) {\n      // Existence first, and for BOTH documents: arch.spec.md is optional (most\n      // of a legacy fleet has none) and spec.md is missing on a half-adopted\n      // service. `FleetContext.readRequirements` throws ENOENT, which surfaces\n      // as `repository-unavailable` and takes the whole `--all` run down — an\n      // absent optional artifact must never be able to do that.\n      if (!existsSync(path)) continue;\n      const reqs = await fleet.readRequirements(path);\n      for (const r of reqs) {\n        if (r.kind !== \"REMOVED\") for (const p of r.requires) used.add(p);\n      }\n    }\n  }\n  const unenforced = [...vocabulary.byId.keys()].filter((id) => !used.has(id));\n  if (unenforced.length === 0) return [];\n  return [\n    {\n      severity: \"warn\",\n      code: \"permissions.unenforced\",\n      message: `landscape: ${unenforced.length} declared permission(s) that no requirement's \\`Requires:\\` line names — write the requirement that gates on each, or drop the declaration`,\n      details: unenforced,\n    },\n  ];\n}\n\n/**\n * The capability vocabulary graded against the fleet that realizes it — the\n * axis's fleet half, beside permissionFindings and shaped by the same two\n * verdicts. `capability.invalid` is a `validate --all` run's ONE finding about\n * an unreadable file — fleet scope, so single-target runs stay silent about\n * it — and it suppresses the rest of the family (the unknown\n * grades at every service target return [] for the same vocabulary — one\n * breach, one finding, never a cascade). `capability.unrealized` is one warn\n * PER declared-but-unnamed capability, subject = the id, because the roadmap's\n * criterion is 'one warning per capability, not one per service'. Holding\n * NEITHER `architecture/capabilities.yaml` nor `capabilities/` is total\n * silence: the fleet's own files are this axis's opt-in, either of them.\n *\n * The used set comes through capabilityRollup with the fleet's own cached\n * reader, so under --all the walk re-parses nothing the service targets have\n * not already paid for — and the rollup, the warn and `loam list capabilities`\n * can never disagree about what \"realized\" means.\n *\n * The AUTHORED documents are graded here too, and they ride this function\n * rather than a target of their own for `viewsStaleFindings`' reason one tree\n * over: a capability belongs to no service, so only the fleet run has the whole\n * vocabulary and the enumerated tree in view at once. Their reads are NOT\n * wrapped, deliberately — a `capabilities/<id>/spec.md` that is not UTF-8 takes\n * the run down exactly as a `services/<id>/spec.md` does, because a document\n * loam cannot decode is a refusal everywhere else in the product and a quiet\n * \"zero requirements\" here would grade a whole capability green on bytes\n * nobody read.\n */\nexport async function capabilityFleetFindings(\n  docsDir: DocsDir,\n  services: ServiceEntry[],\n  fleet: FleetContext,\n  flows: readonly ParsedView[] | null,\n): Promise<Finding[]> {\n  const vocab = await fleet.capabilities(docsDir);\n  if (!vocab.present) return [];\n  const read = (p: string) => fleet.readRequirements(p);\n  const authored: Finding[] = docMissingFindings(vocab.tree);\n  for (const doc of vocab.tree.docs) authored.push(...capabilityDocFindings(await read(doc.spec), doc.id));\n\n  const invalid = invalidVocabularyFinding(vocab);\n  if (invalid !== null) return [invalid, ...authored];\n  // A USE CASE IS THE OTHER WAY TO KEEP A PROMISE, and it is the only carrier a\n  // cross-service criterion has: \"I enter a login and a password and I am in\"\n  // belongs to no single service's spec, so a fleet could satisfy it perfectly\n  // through a `#cap-`/`#req-` tagged flow and still be told nobody realizes it.\n  //\n  // The claims go INTO the rollup rather than beside it, so both unrealized\n  // grades and `loam list capabilities` read one set of rows. `flows === null`\n  // means loam could not READ the flows (no preload, or an `architecture/` that\n  // did not parse); the key is then OMITTED rather than empty, and every\n  // `keptBy` below is `undefined` — the three-state contract `rollup.ts` states.\n  const index = await capabilityRequirementIndex(vocab, read);\n  const keptByFlows =\n    flows === null\n      ? undefined\n      : useCaseRequirementClaims(flows, gradableCapabilityIds(vocab), (c) => index.byCapability.get(c));\n  const rows = await capabilityRollup({ services, vocab, read, ...(keptByFlows === undefined ? {} : { keptByFlows }) });\n\n  // The two unrealized grades read the SAME rollup, which is what keeps them\n  // from disagreeing about the word: a capability is unrealized when nothing\n  // names it by any join, and one of its requirements is unrealized when nothing\n  // keeps that promise. Both are warnings, and the second is the one that\n  // survives a healthy-looking row — a capability with four requirements and\n  // three kept reports nothing at all through the first.\n  //\n  // The suspension falls out of the DATA rather than a branch: `keptBy` absent\n  // means nobody looked, and a promise nobody looked for is not a promise\n  // reported unkept.\n  const unrealizedRequirements = rows.flatMap((row) =>\n    (row.requirements ?? [])\n      .filter((req) => req.realizedBy.length === 0 && req.keptBy?.length === 0)\n      .map((req) => ({ capability: row.id, id: req.id, name: req.name })),\n  );\n  return [\n    ...authored,\n    ...unrealizedFindings(vocab, usedCapabilities(rows)),\n    ...requirementUnrealizedFindings(unrealizedRequirements),\n  ];\n}\n"]}

package/dist/commands/validate/checks/health-deps.js

@@ -0,0 +1,58 @@
+/**
+ * The health.yaml → model reconciliation: every id the `dependencies:` block
+ * declares must be something this service's OWN model answers to.
+ *
+ * Without this reconciliation, a disabled optional service registry can leave
+ * the model, landscape, arch spec and runbook corrected while health.yaml still
+ * declares `serviceRegistry` as a `critical: startup` dependency under a green
+ * validator — in the file an on-call engineer reaches for first. Its
+ * dependencies block was otherwise free text as far as validation was
+ * concerned.
+ *
+ * Resolution is against the SERVICE'S OWN model — deliberately never the
+ * landscape. A store one service owns may be nested inside that service's
+ * element or drawn as a fleet-level peer, whichever the team chose (loam grades
+ * neither: `landscape.datastore-private`, which used to push it into the first,
+ * was retired 2026-09-07). Only the nested placement puts it in the landscape's
+ * interior at all, so the landscape is not a set this check could rely on, while
+ * the model carries everything the service touches — and that is the set the
+ * on-call file has to agree with. An id resolves by the same names every other join
+ * uses: the element's likec4 id, its `metadata { service }` binding, or its
+ * title. Exact match, no case folding — a fold would be a permanent
+ * equivalence semantic no other loam join has, able to silently join two
+ * genuinely different names; the did-you-mean hint bridges the typo case
+ * instead.
+ */
+import { closeIds } from "../../../core/c4/arch.js";
+import {} from "../../../core/c4/likec4.js";
+import { elementService } from "../../../core/c4/resolve/service.js";
+import {} from "../../../core/vocabulary/report.js";
+export function healthDependencyFindings(deps) {
+    const { service, dependencies, elements, modelPath } = deps;
+    // An absent or unparsable model already has its own finding, and grading
+    // health.yaml against a model nobody could read would manufacture warns out
+    // of the wrong file's breakage.
+    if (elements.length === 0)
+        return [];
+    const findings = [];
+    for (const dep of dependencies) {
+        if (elements.some((e) => e.id === dep || elementService(e) === dep))
+            continue;
+        const pool = [...new Set(elements.flatMap((e) => [e.id, elementService(e)]))];
+        const close = closeIds(dep, pool);
+        findings.push({
+            severity: "warn",
+            code: "health.dependency-unmodelled",
+            subject: service,
+            message: `${service}: health.yaml declares dependency '${dep}' but nothing in ` +
+                `${modelPath} answers to that name — either a dependency nobody ` +
+                `modelled, or one that no longer exists. Model it (an external system as its own element ` +
+                `with the edge this service actually has; a store this service owns as a nested container ` +
+                `or as its own element, whichever the map already does), or ` +
+                `delete the entry` +
+                (close.length > 0 ? `. Did you mean: ${close.join(", ")}?` : ""),
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=health-deps.js.map

package/dist/commands/validate/checks/health-deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-deps.js","sourceRoot":"","sources":["../../../../src/commands/validate/checks/health-deps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAa,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAgB,MAAM,oCAAoC,CAAC;AAoBlE,MAAM,UAAU,wBAAwB,CAAC,IAAgB;IACvD,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC5D,yEAAyE;IACzE,4EAA4E;IAC5E,gCAAgC;IAChC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI,cAAc,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;YAAE,SAAS;QAC9E,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC,CAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QACxF,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClC,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,8BAA8B;YACpC,OAAO,EAAE,OAAO;YAChB,OAAO,EACL,GAAG,OAAO,sCAAsC,GAAG,mBAAmB;gBACtE,GAAG,SAAS,qDAAqD;gBACjE,0FAA0F;gBAC1F,2FAA2F;gBAC3F,6DAA6D;gBAC7D,kBAAkB;gBAClB,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,mBAAmB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;SACnE,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * The health.yaml → model reconciliation: every id the `dependencies:` block\n * declares must be something this service's OWN model answers to.\n *\n * Without this reconciliation, a disabled optional service registry can leave\n * the model, landscape, arch spec and runbook corrected while health.yaml still\n * declares `serviceRegistry` as a `critical: startup` dependency under a green\n * validator — in the file an on-call engineer reaches for first. Its\n * dependencies block was otherwise free text as far as validation was\n * concerned.\n *\n * Resolution is against the SERVICE'S OWN model — deliberately never the\n * landscape. A store one service owns may be nested inside that service's\n * element or drawn as a fleet-level peer, whichever the team chose (loam grades\n * neither: `landscape.datastore-private`, which used to push it into the first,\n * was retired 2026-09-07). Only the nested placement puts it in the landscape's\n * interior at all, so the landscape is not a set this check could rely on, while\n * the model carries everything the service touches — and that is the set the\n * on-call file has to agree with. An id resolves by the same names every other join\n * uses: the element's likec4 id, its `metadata { service }` binding, or its\n * title. Exact match, no case folding — a fold would be a permanent\n * equivalence semantic no other loam join has, able to silently join two\n * genuinely different names; the did-you-mean hint bridges the typo case\n * instead.\n */\nimport { closeIds } from \"../../../core/c4/arch.js\";\nimport { type Elem } from \"../../../core/c4/likec4.js\";\nimport { elementService } from \"../../../core/c4/resolve/service.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\n\nexport interface HealthDeps {\n  service: string;\n  /**\n   * The resolved path of the service's own `model.likec4`, repo-relative and\n   * `/`-separated — the file this check grades and the one its message names.\n   * Handed in rather than joined from the id: `services/<id>/model.likec4` is\n   * right only for an unfiled service, and every sibling finding in this\n   * command prints the resolved path of the file it means. Relative because a\n   * message is read beside other people's runs: an absolute path names the\n   * machine that ran the check, not the file in the repository.\n   */\n  modelPath: string;\n  /** `dependencies:` ids, already muted by the caller when health.yaml is unreadable. */\n  dependencies: string[];\n  /** The service's own parsed model — empty when absent or invalid, which mutes the check. */\n  elements: Elem[];\n}\n\nexport function healthDependencyFindings(deps: HealthDeps): Finding[] {\n  const { service, dependencies, elements, modelPath } = deps;\n  // An absent or unparsable model already has its own finding, and grading\n  // health.yaml against a model nobody could read would manufacture warns out\n  // of the wrong file's breakage.\n  if (elements.length === 0) return [];\n  const findings: Finding[] = [];\n  for (const dep of dependencies) {\n    if (elements.some((e) => e.id === dep || elementService(e) === dep)) continue;\n    const pool = [...new Set(elements.flatMap((e) => [e.id, elementService(e) as string]))];\n    const close = closeIds(dep, pool);\n    findings.push({\n      severity: \"warn\",\n      code: \"health.dependency-unmodelled\",\n      subject: service,\n      message:\n        `${service}: health.yaml declares dependency '${dep}' but nothing in ` +\n        `${modelPath} answers to that name — either a dependency nobody ` +\n        `modelled, or one that no longer exists. Model it (an external system as its own element ` +\n        `with the edge this service actually has; a store this service owns as a nested container ` +\n        `or as its own element, whichever the map already does), or ` +\n        `delete the entry` +\n        (close.length > 0 ? `. Did you mean: ${close.join(\", \")}?` : \"\"),\n    });\n  }\n  return findings;\n}\n"]}