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

package/dist/commands/validate/fleet/map/isolation.js

@@ -0,0 +1,116 @@
+/**
+ * `landscape.service-isolated` — a service the fleet map draws and nothing
+ * reaches, graded on EVIDENCE rather than on the shape alone.
+ *
+ * The state is the one `loam seed --from fleet.yaml` leaves for every service
+ * nobody listed under `calls:`: a bound element with no edge. Nothing used to
+ * report it — `landscape.service-unmodelled` wants a missing element, and the
+ * element is present — so a service could be adopted with a full artifact set
+ * and stay invisible to every cross-service check while the run ended on
+ * `landscape.matched`.
+ *
+ * Why the evidence gate, and not "every edgeless bound element": a warning with
+ * no correct fix is the warning somebody silences. A worker or a cron that
+ * genuinely calls nothing has an edgeless element that is TRUE, and there is
+ * no tag loam reads for "deliberately isolated" (inventing one is the invented
+ * need the non-goals forbid). So this fires only when the service's own
+ * `model.likec4` parses and declares at least one call across its boundary —
+ * a JOIN between two authored documents: the model attests a call the map
+ * does not draw. The list comes from `attestedCalls`, the same derivation the
+ * adopt brief names those calls with, so the brief and this check can never
+ * disagree about which edges the map owes. Silent, on purpose, for a service
+ * with no model (seed's fleet), an unparseable model (`c4.invalid` owns it), a
+ * model reaching nothing, and an unmodelled service (`service-unmodelled` owns
+ * it).
+ *
+ * `#external` is never a SUBJECT, and that is now enforced rather than assumed.
+ * The claim used to rest on "an `#external` element is not an enumerated
+ * service" — true of the ordinary case and false of the reachable one: an
+ * element tagged `#external` and bound with `metadata { service '<id>' }` to a
+ * directory that exists resolved like any other, so a foreign box answered for
+ * one of our services (R4). The two neighbouring binding checks have always
+ * skipped the tag; the input set here does too, so "deliberately not ours"
+ * means the same thing in all three.
+ *
+ * The subject set ONLY, and that boundary is the whole of the rule. The filter
+ * also sat inside the `touched` walk for one round, which answers a different
+ * question — does the map draw any edge on this service — and got it wrong: a
+ * kind carrying the tag (`element topic { #external }`, the idiom
+ * `examples/docs/architecture/landscape.likec4` defends at length) puts
+ * `#external` on every element of that kind, so an edge drawn from a service's
+ * OWN topic stopped touching it and the warning fired on a service the map
+ * demonstrably reaches — while `loam adopt`, whose `landscape.touched` has no
+ * tag filter, said `touched: true` on the same tree. Two answers to one rule
+ * is the drift this file's banner promises there cannot be, so the walk below
+ * is the brief's predicate exactly, tag and all.
+ *
+ * A sub-package of its own because `fleet/` sits at the five-file cap, and it
+ * imports NOTHING from `fleet/`: a child reaching back into its parent while
+ * the parent calls the child is the package cycle `scripts/package-graph.mjs`
+ * refuses, which is why the input is one record the caller fills. The models
+ * are no longer read here either — `./attest.ts` reads each of them once for
+ * this check and the datastore census together.
+ */
+import {} from "../../../../core/c4/likec4.js";
+import { edgeTemplates, spellCall } from "../../../../core/c4/resolve/attested.js";
+import {} from "../../../../core/vocabulary/report.js";
+import {} from "./attest.js";
+/** How many attested calls the message spells out before "…" — three reads; thirty is a wall. */
+const NAMED_CALLS = 3;
+export function isolationFindings(input) {
+    const { land, resolve, pathOf } = input;
+    // One pass over the relationships: a service is touched when EITHER endpoint
+    // resolves to it. An intra-service edge (`svc.api -> svc.db`) therefore
+    // counts, which is the brief's `landscape.touched` predicate exactly, and
+    // what keeps a self-model drawn as one service of container edges silent.
+    // NO tag filter here, deliberately — see the banner: an `#external` endpoint
+    // is still an edge the map draws on whatever it resolves to, and skipping one
+    // made this check contradict `loam adopt` on a service whose own topic (a
+    // kind-tagged `#external` element) was the endpoint.
+    const touched = new Set();
+    for (const r of land.relationships) {
+        for (const endpoint of [r.source, r.target])
+            touched.add(resolve(endpoint));
+    }
+    const findings = [];
+    for (const model of input.attested) {
+        if (!input.modelled.has(model.service) || touched.has(model.service))
+            continue;
+        const calls = model.calls;
+        if (calls.length === 0)
+            continue;
+        // `modelled.has` proves a non-external element resolves; the find is the
+        // same predicate spelled on the elements, and an empty answer fails closed
+        // rather than naming an element that is not there.
+        const element = land.elements.find((e) => resolve(e.id) === model.service && !input.external.has(e.id));
+        if (element === undefined)
+            continue;
+        const named = calls.slice(0, NAMED_CALLS).map(spellCall).join(", ") + (calls.length > NAMED_CALLS ? ", …" : "");
+        // The repair form follows the calls' direction (`edgeTemplates`): the
+        // outbound form alone, spelled here until 2026-09-03, sent an inbound
+        // call backwards.
+        const forms = edgeTemplates(element.id, calls)
+            .map((t) => `\`${t}\``)
+            .join(" or ");
+        findings.push({
+            severity: "warn",
+            code: "landscape.service-isolated",
+            subject: model.service,
+            message: 
+            // "the fleet map (architecture/)", never the landscape FILE: the input
+            // is the whole PROJECT, so an edge added to `architecture/extra.likec4`
+            // and never to landscape.likec4 silences this finding — measured on both
+            // the seed lab and examples/docs. Naming one file told a reader the edge
+            // had to land there, which SCHEMA, `loam explain` and the brief all
+            // already contradicted (verification 2026-09-04).
+            `landscape: ${pathOf(model.service)}/ resolves to '${element.id}' and no edge in the fleet map ` +
+                `(architecture/) touches it, while ${pathOf(model.service)}/model.likec4 declares ${calls.length} ` +
+                `call(s) across its boundary ` +
+                `(${named}) — the service is drawn and invisible to every cross-service check. Draw each as one edge on ` +
+                `${element.id}: ${forms} for a call, ` +
+                `\`publishes\`/\`consumes\` for an event, naming the other party as the map already spells it`,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=isolation.js.map

package/dist/commands/validate/fleet/map/isolation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isolation.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/map/isolation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `landscape.service-isolated` — a service the fleet map draws and nothing\n * reaches, graded on EVIDENCE rather than on the shape alone.\n *\n * The state is the one `loam seed --from fleet.yaml` leaves for every service\n * nobody listed under `calls:`: a bound element with no edge. Nothing used to\n * report it — `landscape.service-unmodelled` wants a missing element, and the\n * element is present — so a service could be adopted with a full artifact set\n * and stay invisible to every cross-service check while the run ended on\n * `landscape.matched`.\n *\n * Why the evidence gate, and not \"every edgeless bound element\": a warning with\n * no correct fix is the warning somebody silences. A worker or a cron that\n * genuinely calls nothing has an edgeless element that is TRUE, and there is\n * no tag loam reads for \"deliberately isolated\" (inventing one is the invented\n * need the non-goals forbid). So this fires only when the service's own\n * `model.likec4` parses and declares at least one call across its boundary —\n * a JOIN between two authored documents: the model attests a call the map\n * does not draw. The list comes from `attestedCalls`, the same derivation the\n * adopt brief names those calls with, so the brief and this check can never\n * disagree about which edges the map owes. Silent, on purpose, for a service\n * with no model (seed's fleet), an unparseable model (`c4.invalid` owns it), a\n * model reaching nothing, and an unmodelled service (`service-unmodelled` owns\n * it).\n *\n * `#external` is never a SUBJECT, and that is now enforced rather than assumed.\n * The claim used to rest on \"an `#external` element is not an enumerated\n * service\" — true of the ordinary case and false of the reachable one: an\n * element tagged `#external` and bound with `metadata { service '<id>' }` to a\n * directory that exists resolved like any other, so a foreign box answered for\n * one of our services (R4). The two neighbouring binding checks have always\n * skipped the tag; the input set here does too, so \"deliberately not ours\"\n * means the same thing in all three.\n *\n * The subject set ONLY, and that boundary is the whole of the rule. The filter\n * also sat inside the `touched` walk for one round, which answers a different\n * question — does the map draw any edge on this service — and got it wrong: a\n * kind carrying the tag (`element topic { #external }`, the idiom\n * `examples/docs/architecture/landscape.likec4` defends at length) puts\n * `#external` on every element of that kind, so an edge drawn from a service's\n * OWN topic stopped touching it and the warning fired on a service the map\n * demonstrably reaches — while `loam adopt`, whose `landscape.touched` has no\n * tag filter, said `touched: true` on the same tree. Two answers to one rule\n * is the drift this file's banner promises there cannot be, so the walk below\n * is the brief's predicate exactly, tag and all.\n *\n * A sub-package of its own because `fleet/` sits at the five-file cap, and it\n * imports NOTHING from `fleet/`: a child reaching back into its parent while\n * the parent calls the child is the package cycle `scripts/package-graph.mjs`\n * refuses, which is why the input is one record the caller fills. The models\n * are no longer read here either — `./attest.ts` reads each of them once for\n * this check and the datastore census together.\n */\nimport { type LoadedDoc } from \"../../../../core/c4/likec4.js\";\nimport { edgeTemplates, spellCall } from \"../../../../core/c4/resolve/attested.js\";\nimport { type Finding } from \"../../../../core/vocabulary/report.js\";\nimport { type AttestedModel } from \"./attest.js\";\n\nexport interface IsolationInput {\n  /** The parsed landscape. */\n  land: LoadedDoc;\n  /**\n   * The services a NON-`#external` element resolves to — `service-unmodelled`'s\n   * set with the tag filter applied, which is what keeps a foreign box from\n   * answering for one of our directories.\n   */\n  modelled: ReadonlySet<string>;\n  /** The ids of the map's `#external` elements: never a subject — and never what the message names. */\n  external: ReadonlySet<string>;\n  /** What each service's own model attests, read once by `./attest.ts` for this check and the store census. */\n  attested: readonly AttestedModel[];\n  /** The shared element→service resolver every edge join uses. */\n  resolve: (id: string) => string;\n  /** Where a service's directory sits, repo-relative — the enumeration's answer, never `services/<id>`. */\n  pathOf: (id: string) => string;\n}\n\n/** How many attested calls the message spells out before \"…\" — three reads; thirty is a wall. */\nconst NAMED_CALLS = 3;\n\nexport function isolationFindings(input: IsolationInput): Finding[] {\n  const { land, resolve, pathOf } = input;\n  // One pass over the relationships: a service is touched when EITHER endpoint\n  // resolves to it. An intra-service edge (`svc.api -> svc.db`) therefore\n  // counts, which is the brief's `landscape.touched` predicate exactly, and\n  // what keeps a self-model drawn as one service of container edges silent.\n  // NO tag filter here, deliberately — see the banner: an `#external` endpoint\n  // is still an edge the map draws on whatever it resolves to, and skipping one\n  // made this check contradict `loam adopt` on a service whose own topic (a\n  // kind-tagged `#external` element) was the endpoint.\n  const touched = new Set<string>();\n  for (const r of land.relationships) {\n    for (const endpoint of [r.source, r.target]) touched.add(resolve(endpoint));\n  }\n\n  const findings: Finding[] = [];\n  for (const model of input.attested) {\n    if (!input.modelled.has(model.service) || touched.has(model.service)) continue;\n    const calls = model.calls;\n    if (calls.length === 0) continue;\n    // `modelled.has` proves a non-external element resolves; the find is the\n    // same predicate spelled on the elements, and an empty answer fails closed\n    // rather than naming an element that is not there.\n    const element = land.elements.find((e) => resolve(e.id) === model.service && !input.external.has(e.id));\n    if (element === undefined) continue;\n    const named = calls.slice(0, NAMED_CALLS).map(spellCall).join(\", \") + (calls.length > NAMED_CALLS ? \", …\" : \"\");\n    // The repair form follows the calls' direction (`edgeTemplates`): the\n    // outbound form alone, spelled here until 2026-09-03, sent an inbound\n    // call backwards.\n    const forms = edgeTemplates(element.id, calls)\n      .map((t) => `\\`${t}\\``)\n      .join(\" or \");\n    findings.push({\n      severity: \"warn\",\n      code: \"landscape.service-isolated\",\n      subject: model.service,\n      message:\n        // \"the fleet map (architecture/)\", never the landscape FILE: the input\n        // is the whole PROJECT, so an edge added to `architecture/extra.likec4`\n        // and never to landscape.likec4 silences this finding — measured on both\n        // the seed lab and examples/docs. Naming one file told a reader the edge\n        // had to land there, which SCHEMA, `loam explain` and the brief all\n        // already contradicted (verification 2026-09-04).\n        `landscape: ${pathOf(model.service)}/ resolves to '${element.id}' and no edge in the fleet map ` +\n        `(architecture/) touches it, while ${pathOf(model.service)}/model.likec4 declares ${calls.length} ` +\n        `call(s) across its boundary ` +\n        `(${named}) — the service is drawn and invisible to every cross-service check. Draw each as one edge on ` +\n        `${element.id}: ${forms} for a call, ` +\n        `\\`publishes\\`/\\`consumes\\` for an event, naming the other party as the map already spells it`,\n    });\n  }\n  return findings;\n}\n"]}

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

@@ -0,0 +1,54 @@
+/**
+ * The fleet's use cases, graded — the CALL, with the two vocabulary reads it
+ * needs, lifted out of `../landscape.ts` when that module reached its line
+ * limit.
+ *
+ * The seam is a phase rather than a subject: everything here happens after the
+ * map has parsed and grades documents the map does not own — every
+ * `dynamic view` in `architecture/landscape.likec4` and in every
+ * `architecture/usecases/*.likec4`. `core/usecases/grade/usecases.ts` owns the opt-in and
+ * the grades; this owns which inputs they are handed, which is the part that has
+ * twice been got wrong and is worth stating in one place.
+ *
+ * A sub-package of `fleet/` for `./isolation.ts`'s reason, and with its rule:
+ * it imports NOTHING from `fleet/` itself, so everything it needs arrives in
+ * one record the caller fills — besides `../usecases/place.ts`, the fleet target's
+ * own name for where a view is, which the graders (`core/usecases/grade/`) take
+ * as an argument because core may not hold it.
+ */
+import { capabilityRequirementIndex, gradableCapabilityIds } from "../../../../core/capabilities/findings.js";
+import { FleetContext } from "../../../../core/fleet-context.js";
+import { useCaseFindings } from "../../../../core/usecases/grade/usecases.js";
+import { viewPlace } from "../usecases/place.js";
+/**
+ * The capability ladder is APPLIED BY ITS OWN FUNCTION rather than re-spelled
+ * here: an absent or unreadable capabilities.yaml means silence for the whole
+ * family, not a fleet full of unresolved tags, so `null` travels rather than an
+ * empty list — which the join would read as "the fleet declares no capabilities"
+ * and grade every tag against. `gradableCapabilityIds`
+ * (`core/capabilities/findings.ts`) is the one statement of that rule, and this
+ * is a caller of it precisely so a fourth un-gradable vocabulary state cannot be
+ * fixed in core while the command layer keeps handing the join a whole key set.
+ *
+ * Both reads are already paid for under `--all`: `capabilityFleetFindings` has
+ * asked for the vocabulary, and every requirement document behind the `#req-`
+ * tag was parsed by it, so the fleet memo answers from cache. The requirement
+ * index is built here rather than inside the use-case package so that package
+ * never learns what a capability document is.
+ */
+export async function fleetUseCaseFindings(input) {
+    const { docsDir, fleet } = input;
+    const vocabulary = await fleet.capabilities(docsDir);
+    const capabilityReqs = await capabilityRequirementIndex(vocabulary, (p) => fleet.readRequirements(p));
+    return useCaseFindings({
+        views: input.views,
+        elements: input.elements,
+        relationships: input.relationships,
+        services: input.services,
+        resolve: input.resolve,
+        capabilities: gradableCapabilityIds(vocabulary),
+        requirementsOf: (capability) => capabilityReqs.byCapability.get(capability),
+        place: viewPlace,
+    });
+}
+//# sourceMappingURL=usecases.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usecases.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/map/usecases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,2CAA2C,CAAC;AAC9G,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAKjE,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAsBjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,KAAoB;IAC7D,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IACjC,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,cAAc,GAAG,MAAM,0BAA0B,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACtG,OAAO,eAAe,CAAC;QACrB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,YAAY,EAAE,qBAAqB,CAAC,UAAU,CAAC;QAC/C,cAAc,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,cAAc,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC;QAC3E,KAAK,EAAE,SAAS;KACjB,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * The fleet's use cases, graded — the CALL, with the two vocabulary reads it\n * needs, lifted out of `../landscape.ts` when that module reached its line\n * limit.\n *\n * The seam is a phase rather than a subject: everything here happens after the\n * map has parsed and grades documents the map does not own — every\n * `dynamic view` in `architecture/landscape.likec4` and in every\n * `architecture/usecases/*.likec4`. `core/usecases/grade/usecases.ts` owns the opt-in and\n * the grades; this owns which inputs they are handed, which is the part that has\n * twice been got wrong and is worth stating in one place.\n *\n * A sub-package of `fleet/` for `./isolation.ts`'s reason, and with its rule:\n * it imports NOTHING from `fleet/` itself, so everything it needs arrives in\n * one record the caller fills — besides `../usecases/place.ts`, the fleet target's\n * own name for where a view is, which the graders (`core/usecases/grade/`) take\n * as an argument because core may not hold it.\n */\nimport { capabilityRequirementIndex, gradableCapabilityIds } from \"../../../../core/capabilities/findings.js\";\nimport { FleetContext } from \"../../../../core/fleet-context.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport type { Elem, Rel } from \"../../../../core/c4/likec4.js\";\nimport type { ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { useCaseFindings } from \"../../../../core/usecases/grade/usecases.js\";\nimport { viewPlace } from \"../usecases/place.js\";\n\nexport interface FleetUseCases {\n  docsDir: DocsDir;\n  /**\n   * The views come from the PROJECT load, never from a single-file fallback,\n   * and that is the file-naming rule made mechanical instead of remembered:\n   * only the project load gives a view the `sourcePath` a finding has to name,\n   * while a single-file load calls every document `source.c4` — so a message\n   * built from that load would send its reader to `architecture/source.c4`, a\n   * file that has never existed. No project, no views, and nothing to get wrong.\n   */\n  views: readonly ParsedView[];\n  /** The map's model — what a hop is resolved against. */\n  elements: Elem[];\n  relationships: Rel[];\n  /** The enumerated fleet, and the resolver every other edge join in the target uses. */\n  services: ReadonlySet<string>;\n  resolve: (id: string) => string;\n  fleet: FleetContext;\n}\n\n/**\n * The capability ladder is APPLIED BY ITS OWN FUNCTION rather than re-spelled\n * here: an absent or unreadable capabilities.yaml means silence for the whole\n * family, not a fleet full of unresolved tags, so `null` travels rather than an\n * empty list — which the join would read as \"the fleet declares no capabilities\"\n * and grade every tag against. `gradableCapabilityIds`\n * (`core/capabilities/findings.ts`) is the one statement of that rule, and this\n * is a caller of it precisely so a fourth un-gradable vocabulary state cannot be\n * fixed in core while the command layer keeps handing the join a whole key set.\n *\n * Both reads are already paid for under `--all`: `capabilityFleetFindings` has\n * asked for the vocabulary, and every requirement document behind the `#req-`\n * tag was parsed by it, so the fleet memo answers from cache. The requirement\n * index is built here rather than inside the use-case package so that package\n * never learns what a capability document is.\n */\nexport async function fleetUseCaseFindings(input: FleetUseCases): Promise<Finding[]> {\n  const { docsDir, fleet } = input;\n  const vocabulary = await fleet.capabilities(docsDir);\n  const capabilityReqs = await capabilityRequirementIndex(vocabulary, (p) => fleet.readRequirements(p));\n  return useCaseFindings({\n    views: input.views,\n    elements: input.elements,\n    relationships: input.relationships,\n    services: input.services,\n    resolve: input.resolve,\n    capabilities: gradableCapabilityIds(vocabulary),\n    requirementsOf: (capability) => capabilityReqs.byCapability.get(capability),\n    place: viewPlace,\n  });\n}\n"]}

package/dist/commands/validate/fleet/obligations.js

@@ -0,0 +1,266 @@
+/**
+ * The architectural obligation axis, graded against the fleet it is about.
+ *
+ * `core/obligations/obligations.ts` states what the axis IS and why it has this
+ * shape. This module is the four questions asked of a fleet that has one, and
+ * the order they are asked in — the same division `checks/fleet-shape.ts` keeps
+ * for the authorization and capability vocabularies, which this sits beside on
+ * the `landscape` target for their reason: an obligation crosses services by
+ * construction, so no service target can answer for it.
+ *
+ * THE FOUR ARE TWO PAIRS, and each pair is one join read in both directions.
+ * A tag nothing declares is an ERROR (`obligation.unknown`) and a declaration
+ * nothing tags is a WARNING (`obligation.unapplied`) — exactly the asymmetry
+ * `permissions.unknown`/`permissions.unenforced` already carry, and for the
+ * same reason: a typo in a tag reads like a rule, while a word nobody has
+ * adopted yet is an honest state. Then a tagged object no requirement covers is
+ * a WARNING (`obligation.uncovered`) and an `adr:` naming no file is an ERROR
+ * (`obligation.adr-missing`): the team's work being outstanding is normal, and
+ * a pointer at a decision nobody can read is not.
+ *
+ * `obligation.uncovered` IS THE PREREQUISITE THE ROADMAP NAMED. `c4.uncovered`
+ * has always been able to say "this architecture object owes a requirement",
+ * but only about a NEW tagged element in a feature's `delta.likec4` — never
+ * about the map the fleet actually runs on. This asks the same question of the
+ * LIVING landscape, against the union of every service's living `arch.spec.md`
+ * `Covers:` lines, which is the index that did not exist before.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {} from "../../../core/c4/likec4.js";
+import { closeIds, coversDeployEdge, coversDeployNode, coversEdge, coversElement, } from "../../../core/c4/arch.js";
+import { NO_DEPLOYMENT } from "../../../core/c4/parsed/deployment.js";
+import { taggedDeployment } from "../../../core/deployment/objects.js";
+import { elementService } from "../../../core/c4/resolve/service.js";
+import { OBLIGATION_TAG_PREFIX } from "../../../core/obligations/obligations.js";
+import { servicePathsAt } from "../../../core/repo/paths.js";
+import {} from "../../../core/repo/entries.js";
+import {} from "../../../core/vocabulary/report.js";
+import { FleetContext } from "../../../core/fleet-context.js";
+import { coversEntries } from "../checks/requirements.js";
+/**
+ * The half that does not depend on the map: the file reads, and its `adr:`
+ * pointers resolve.
+ *
+ * Separate from the map questions because the landscape target returns early
+ * twice — an absent map, and one that did not parse — and a broken vocabulary
+ * must still be named in exactly the runs where somebody is fixing something
+ * else. The same placement `permissionFindings` and `capabilityFleetFindings`
+ * already have, one level of precision finer.
+ */
+export function obligationVocabularyFindings(docsDir, vocabulary) {
+    if (!vocabulary.present)
+        return [];
+    if (vocabulary.invalid !== undefined) {
+        // Reported ALONE, exactly as `permissions.invalid` and `capability.invalid`
+        // are: every `#obl-` tag in the fleet resolves against this file, so grading
+        // them on top of a broken vocabulary is a cascade, not a diagnosis.
+        return [
+            {
+                severity: "error",
+                code: "obligation.invalid",
+                message: `landscape: architecture/obligations.yaml does not read as a vocabulary — ${vocabulary.invalid}. ` +
+                    "Every `#obl-` tag on the fleet map resolves against this file, so none of them can be graded until it parses. " +
+                    "The shape is `obligations: {<id>: {description, adr}}`, ids spelled with letters, digits, `_` and `-` only.",
+            },
+        ];
+    }
+    return adrFindings(docsDir, [...vocabulary.byId.values()]);
+}
+/** The three questions that need the map, suspended entirely when it could not be read. */
+export async function obligationFindings(check) {
+    const { vocabulary } = check;
+    if (!vocabulary.present || vocabulary.invalid !== undefined)
+        return [];
+    const findings = [];
+    // Which objects carry which obligation. Elements and edges are collected
+    // together because every question below treats them alike: an obligation
+    // applies to a thing on the map, and whether that thing is a box or an arrow
+    // changes only how the message spells it and how `Covers:` matches it.
+    // The enumerated fleet rides in for the deployment half of the walk: an
+    // instance deploys a CONTAINER more often than a whole system, and resolving
+    // which service owns one needs the ancestor walk `serviceResolver` performs.
+    // It is the same set `uncoveredFindings` resolves edge endpoints with, or the
+    // message would name one service and the coverage check count another.
+    const known = new Set(check.services.map((s) => s.id));
+    const tagged = taggedObjects(check.land, known);
+    const applied = new Set(tagged.map((t) => t.obligation));
+    for (const id of [...applied].sort()) {
+        if (vocabulary.byId.has(id))
+            continue;
+        const close = closeIds(id, [...vocabulary.byId.keys()]);
+        findings.push({
+            severity: "error",
+            code: "obligation.unknown",
+            subject: id,
+            message: `landscape: #${OBLIGATION_TAG_PREFIX}${id} tags ${count(tagged.filter((t) => t.obligation === id).length, "object")} on the fleet map, ` +
+                `and architecture/obligations.yaml declares no obligation '${id}'` +
+                (close.length > 0 ? ` — did you mean: ${close.join(", ")}?` : "") +
+                ". A tag that resolves to nothing reads exactly like a rule the fleet keeps: declare it, or fix the tag.",
+            details: tagged.filter((t) => t.obligation === id).map((t) => t.where),
+        });
+    }
+    const unapplied = [...vocabulary.byId.keys()].filter((id) => !applied.has(id)).sort();
+    if (unapplied.length > 0) {
+        findings.push({
+            severity: "warn",
+            code: "obligation.unapplied",
+            message: `landscape: ${unapplied.length} declared obligation(s) that no \`#${OBLIGATION_TAG_PREFIX}\` tag applies anywhere on the fleet map — ` +
+                "either a decision that was reversed and left its word behind, or one nobody has placed yet. " +
+                "Tag the elements and edges it governs, or drop the declaration; a vocabulary is worth what cites it.",
+            details: unapplied,
+        });
+    }
+    // ONLY A RESOLVED APPLICATION IS ASKED ABOUT COVERAGE. A tag naming no
+    // declared obligation has already earned its error above, and "no requirement
+    // covers #obl-typo" is not a second breach — it is the same one restated in
+    // words that ask the reader to write a requirement for a rule that does not
+    // exist. The use-case axis draws this line in the same place: only a resolved
+    // `#cap-` claim keeps a promise.
+    findings.push(...(await uncoveredFindings(check, tagged.filter((t) => vocabulary.byId.has(t.obligation)))));
+    return findings;
+}
+/**
+ * Every `#obl-` tag on the living map, one entry per (obligation, object) pair.
+ *
+ * A bare `#obl-` slugs to the empty string and is kept as an application on
+ * purpose, exactly as a bare `#cap-` is kept as a claim: the prefix is the
+ * author's opt-in however little follows it, and dropping it as unreserved
+ * would leave an object that asked to be graded silently ungraded. It then
+ * resolves to `obligation.unknown` in every fleet that did not declare an empty
+ * id, which is the honest answer.
+ */
+function taggedObjects(land, known) {
+    const out = [];
+    for (const element of land.elements) {
+        for (const tag of element.tags.filter((t) => t.startsWith(OBLIGATION_TAG_PREFIX))) {
+            out.push({
+                obligation: tag.slice(OBLIGATION_TAG_PREFIX.length),
+                element,
+                where: element.id,
+                subject: elementService(element),
+            });
+        }
+    }
+    for (const edge of land.relationships) {
+        for (const tag of edge.tags.filter((t) => t.startsWith(OBLIGATION_TAG_PREFIX))) {
+            out.push({
+                obligation: tag.slice(OBLIGATION_TAG_PREFIX.length),
+                edge,
+                where: `${edge.source} -> ${edge.target}`,
+                subject: edge.target,
+            });
+        }
+    }
+    // The topology, walked by the same rule and for the reason the rule exists: a
+    // tag is a claim about the object it sits on, and which MODEL that object
+    // lives in is not something a reader of the tag can see. Until this walk the
+    // same undeclared tag was an error on a container and silence on a
+    // datacenter — fail-open, and the case FEAT-1's ARCH-LOAM-DEPLOY-TAGGED was
+    // written about. A fleet that draws no topology contributes nothing here.
+    for (const d of taggedDeployment(land.deployment ?? NO_DEPLOYMENT, land.elements, known, OBLIGATION_TAG_PREFIX)) {
+        out.push({
+            obligation: d.obligation,
+            deployed: d,
+            where: d.where,
+            ...(d.service === undefined ? {} : { subject: d.service }),
+        });
+    }
+    return out;
+}
+/**
+ * `obligation.uncovered` — a tagged object no living arch requirement covers.
+ *
+ * The index is the union of EVERY service's living `arch.spec.md` `Covers:`
+ * lines, because an obligation is placed by the architect on the map and met by
+ * whichever team owns the thing it sits on — and a per-service index would
+ * report an edge as uncovered because the requirement that covers it lives in
+ * the service at the other end. `coversEntries` already drops REMOVED
+ * requirements: a retired requirement covers nothing.
+ *
+ * ONE FINDING PER TAGGED OBJECT, subject = the service that owns it, so a
+ * fleet-wide report reads as a worklist per team rather than as one line naming
+ * forty edges.
+ */
+async function uncoveredFindings(check, tagged) {
+    if (tagged.length === 0)
+        return [];
+    const covers = await livingCovers(check);
+    const elements = check.land.elements;
+    const known = new Set(check.services.map((s) => s.id));
+    const covered = (t) => {
+        if (t.element !== undefined)
+            return covers.some((c) => coversElement(c, t.element));
+        if (t.edge !== undefined)
+            return covers.some((c) => coversEdge(c, t.edge, elements, known));
+        const d = t.deployed;
+        return d.edge === undefined
+            ? covers.some((c) => coversDeployNode(c, d.id))
+            : covers.some((c) => coversDeployEdge(c, d.edge.source, d.edge.target));
+    };
+    return tagged
+        .filter((t) => !covered(t))
+        .map((t) => ({
+        severity: "warn",
+        code: "obligation.uncovered",
+        ...(t.subject === undefined ? {} : { subject: t.subject }),
+        message: `${t.where} carries #${OBLIGATION_TAG_PREFIX}${t.obligation} and no living arch requirement covers it — ` +
+            `the obligation is placed and nothing says it is met. Write the requirement in ` +
+            // A region, a datacenter or a cluster is owned by no service, so the
+            // sentence stays general rather than naming a team at random. Every
+            // other object here has a real owner and keeps the actionable form.
+            `${t.subject === undefined ? "the arch.spec.md of whichever service answers for this topology" : `${t.subject}'s arch.spec.md`}` +
+            ` with \`Covers: ${t.where}\` and a scenario that proves it, or drop the tag if the decision no longer applies here.`,
+    }));
+}
+/**
+ * Every `Covers:` entry the LIVING fleet writes, across both requirement
+ * documents of every service.
+ *
+ * Existence is checked for both files and for the same reason
+ * `permissionFindings` checks it: `arch.spec.md` is optional and most of a
+ * legacy fleet has none, while `spec.md` is missing on a half-adopted service —
+ * and `FleetContext.readRequirements` throws ENOENT, which surfaces as
+ * `repository-unavailable` and takes the whole `--all` run down. Both axes are
+ * read, not only the architecture one: `Covers:` is parsed everywhere for one
+ * grammar's sake, and a fleet that wrote its outbox requirement in `spec.md`
+ * has said the thing loam is asking about.
+ */
+async function livingCovers(check) {
+    const entries = [];
+    for (const service of check.services) {
+        const paths = servicePathsAt(service.dir);
+        for (const path of [paths.spec, paths.archSpec]) {
+            if (!existsSync(path))
+                continue;
+            entries.push(...coversEntries(await check.fleet.readRequirements(path)));
+        }
+    }
+    return entries;
+}
+/**
+ * `obligation.adr-missing` — an `adr:` path that names no file.
+ *
+ * The path is relative to the docs repo root rather than to
+ * `architecture/obligations.yaml`, because that is how a reader of a fleet
+ * document thinks about a fleet path, and because the value is a YAML field
+ * rather than a markdown link — `link.unresolved` grades links written in prose,
+ * and this one is written in a slot loam defined.
+ */
+function adrFindings(docsDir, obligations) {
+    return obligations
+        .filter((o) => o.adr !== undefined && !existsSync(join(docsDir, o.adr)))
+        .map((o) => ({
+        severity: "error",
+        code: "obligation.adr-missing",
+        subject: o.id,
+        message: `landscape: obligation '${o.id}' names \`adr: ${o.adr}\` and no such file exists — ` +
+            "the ADR is where the decision itself is written, so a pointer at nothing leaves every tag citing a rule nobody can read. " +
+            "Fix the path (it is relative to the docs repo root), write the record, or drop the field.",
+    }));
+}
+/** `1 object` / `3 objects` — the plural spelled once, because three messages count things. */
+function count(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+//# sourceMappingURL=obligations.js.map

package/dist/commands/validate/fleet/obligations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"obligations.js","sourceRoot":"","sources":["../../../../src/commands/validate/fleet/obligations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The architectural obligation axis, graded against the fleet it is about.\n *\n * `core/obligations/obligations.ts` states what the axis IS and why it has this\n * shape. This module is the four questions asked of a fleet that has one, and\n * the order they are asked in — the same division `checks/fleet-shape.ts` keeps\n * for the authorization and capability vocabularies, which this sits beside on\n * the `landscape` target for their reason: an obligation crosses services by\n * construction, so no service target can answer for it.\n *\n * THE FOUR ARE TWO PAIRS, and each pair is one join read in both directions.\n * A tag nothing declares is an ERROR (`obligation.unknown`) and a declaration\n * nothing tags is a WARNING (`obligation.unapplied`) — exactly the asymmetry\n * `permissions.unknown`/`permissions.unenforced` already carry, and for the\n * same reason: a typo in a tag reads like a rule, while a word nobody has\n * adopted yet is an honest state. Then a tagged object no requirement covers is\n * a WARNING (`obligation.uncovered`) and an `adr:` naming no file is an ERROR\n * (`obligation.adr-missing`): the team's work being outstanding is normal, and\n * a pointer at a decision nobody can read is not.\n *\n * `obligation.uncovered` IS THE PREREQUISITE THE ROADMAP NAMED. `c4.uncovered`\n * has always been able to say \"this architecture object owes a requirement\",\n * but only about a NEW tagged element in a feature's `delta.likec4` — never\n * about the map the fleet actually runs on. This asks the same question of the\n * LIVING landscape, against the union of every service's living `arch.spec.md`\n * `Covers:` lines, which is the index that did not exist before.\n */\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { type Elem, type LoadedDoc, type Rel } from \"../../../core/c4/likec4.js\";\nimport {\n  closeIds,\n  coversDeployEdge,\n  coversDeployNode,\n  coversEdge,\n  coversElement,\n  type CoversEntry,\n} from \"../../../core/c4/arch.js\";\nimport { NO_DEPLOYMENT } from \"../../../core/c4/parsed/deployment.js\";\nimport { taggedDeployment, type TaggedDeployment } from \"../../../core/deployment/objects.js\";\nimport { elementService } from \"../../../core/c4/resolve/service.js\";\nimport { OBLIGATION_TAG_PREFIX, type ObligationVocabulary } from \"../../../core/obligations/obligations.js\";\nimport { servicePathsAt } from \"../../../core/repo/paths.js\";\nimport { type ServiceEntry } from \"../../../core/repo/entries.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { coversEntries } from \"../checks/requirements.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\n\nexport interface ObligationCheck {\n  docsDir: DocsDir;\n  vocabulary: ObligationVocabulary;\n  /**\n   * The living landscape, PARSED. Not nullable, and the absence is the point:\n   * the landscape target returns before it reaches this call when the map is\n   * missing or did not parse, so a run that could not read the map asks none of\n   * the three questions below rather than answering them empty. \"Loam did not\n   * look\" is never the same answer as \"there is nothing there\" — an unreadable\n   * map graded as empty would report every declared obligation as applied\n   * nowhere — and the suspension lives at the call site because that is where\n   * the fact is known. It is also why the vocabulary half is a separate\n   * function: those two verdicts must survive exactly those early returns.\n   */\n  land: LoadedDoc;\n  services: ServiceEntry[];\n  fleet: FleetContext;\n}\n\n/**\n * The half that does not depend on the map: the file reads, and its `adr:`\n * pointers resolve.\n *\n * Separate from the map questions because the landscape target returns early\n * twice — an absent map, and one that did not parse — and a broken vocabulary\n * must still be named in exactly the runs where somebody is fixing something\n * else. The same placement `permissionFindings` and `capabilityFleetFindings`\n * already have, one level of precision finer.\n */\nexport function obligationVocabularyFindings(docsDir: DocsDir, vocabulary: ObligationVocabulary): Finding[] {\n  if (!vocabulary.present) return [];\n  if (vocabulary.invalid !== undefined) {\n    // Reported ALONE, exactly as `permissions.invalid` and `capability.invalid`\n    // are: every `#obl-` tag in the fleet resolves against this file, so grading\n    // them on top of a broken vocabulary is a cascade, not a diagnosis.\n    return [\n      {\n        severity: \"error\",\n        code: \"obligation.invalid\",\n        message:\n          `landscape: architecture/obligations.yaml does not read as a vocabulary — ${vocabulary.invalid}. ` +\n          \"Every `#obl-` tag on the fleet map resolves against this file, so none of them can be graded until it parses. \" +\n          \"The shape is `obligations: {<id>: {description, adr}}`, ids spelled with letters, digits, `_` and `-` only.\",\n      },\n    ];\n  }\n\n  return adrFindings(docsDir, [...vocabulary.byId.values()]);\n}\n\n/** The three questions that need the map, suspended entirely when it could not be read. */\nexport async function obligationFindings(check: ObligationCheck): Promise<Finding[]> {\n  const { vocabulary } = check;\n  if (!vocabulary.present || vocabulary.invalid !== undefined) return [];\n  const findings: Finding[] = [];\n\n  // Which objects carry which obligation. Elements and edges are collected\n  // together because every question below treats them alike: an obligation\n  // applies to a thing on the map, and whether that thing is a box or an arrow\n  // changes only how the message spells it and how `Covers:` matches it.\n  // The enumerated fleet rides in for the deployment half of the walk: an\n  // instance deploys a CONTAINER more often than a whole system, and resolving\n  // which service owns one needs the ancestor walk `serviceResolver` performs.\n  // It is the same set `uncoveredFindings` resolves edge endpoints with, or the\n  // message would name one service and the coverage check count another.\n  const known = new Set(check.services.map((s) => s.id));\n  const tagged = taggedObjects(check.land, known);\n  const applied = new Set(tagged.map((t) => t.obligation));\n\n  for (const id of [...applied].sort()) {\n    if (vocabulary.byId.has(id)) continue;\n    const close = closeIds(id, [...vocabulary.byId.keys()]);\n    findings.push({\n      severity: \"error\",\n      code: \"obligation.unknown\",\n      subject: id,\n      message:\n        `landscape: #${OBLIGATION_TAG_PREFIX}${id} tags ${count(tagged.filter((t) => t.obligation === id).length, \"object\")} on the fleet map, ` +\n        `and architecture/obligations.yaml declares no obligation '${id}'` +\n        (close.length > 0 ? ` — did you mean: ${close.join(\", \")}?` : \"\") +\n        \". A tag that resolves to nothing reads exactly like a rule the fleet keeps: declare it, or fix the tag.\",\n      details: tagged.filter((t) => t.obligation === id).map((t) => t.where),\n    });\n  }\n\n  const unapplied = [...vocabulary.byId.keys()].filter((id) => !applied.has(id)).sort();\n  if (unapplied.length > 0) {\n    findings.push({\n      severity: \"warn\",\n      code: \"obligation.unapplied\",\n      message:\n        `landscape: ${unapplied.length} declared obligation(s) that no \\`#${OBLIGATION_TAG_PREFIX}\\` tag applies anywhere on the fleet map — ` +\n        \"either a decision that was reversed and left its word behind, or one nobody has placed yet. \" +\n        \"Tag the elements and edges it governs, or drop the declaration; a vocabulary is worth what cites it.\",\n      details: unapplied,\n    });\n  }\n\n  // ONLY A RESOLVED APPLICATION IS ASKED ABOUT COVERAGE. A tag naming no\n  // declared obligation has already earned its error above, and \"no requirement\n  // covers #obl-typo\" is not a second breach — it is the same one restated in\n  // words that ask the reader to write a requirement for a rule that does not\n  // exist. The use-case axis draws this line in the same place: only a resolved\n  // `#cap-` claim keeps a promise.\n  findings.push(...(await uncoveredFindings(check, tagged.filter((t) => vocabulary.byId.has(t.obligation)))));\n  return findings;\n}\n\n/** One place an obligation is applied: which obligation, on what, and how a message names it. */\ninterface TaggedObject {\n  obligation: string;\n  /** The element, the edge, or the deployment object — exactly one is set. */\n  element?: Elem;\n  edge?: Rel;\n  deployed?: TaggedDeployment;\n  /**\n   * How the finding spells this object, and how a `Covers:` line has to: an\n   * element id, `source -> target`, or the `node:` forms.\n   */\n  where: string;\n  /**\n   * What the finding is filed under — the service that owns it, where one\n   * does. ABSENT for a region, a datacenter or a cluster: nobody-s service\n   * runs one, and naming a team that did not ask for the work is worse than\n   * leaving the sentence general.\n   */\n  subject?: string;\n}\n\n/**\n * Every `#obl-` tag on the living map, one entry per (obligation, object) pair.\n *\n * A bare `#obl-` slugs to the empty string and is kept as an application on\n * purpose, exactly as a bare `#cap-` is kept as a claim: the prefix is the\n * author's opt-in however little follows it, and dropping it as unreserved\n * would leave an object that asked to be graded silently ungraded. It then\n * resolves to `obligation.unknown` in every fleet that did not declare an empty\n * id, which is the honest answer.\n */\nfunction taggedObjects(land: LoadedDoc, known: ReadonlySet<string>): TaggedObject[] {\n  const out: TaggedObject[] = [];\n  for (const element of land.elements) {\n    for (const tag of element.tags.filter((t) => t.startsWith(OBLIGATION_TAG_PREFIX))) {\n      out.push({\n        obligation: tag.slice(OBLIGATION_TAG_PREFIX.length),\n        element,\n        where: element.id,\n        subject: elementService(element),\n      });\n    }\n  }\n  for (const edge of land.relationships) {\n    for (const tag of edge.tags.filter((t) => t.startsWith(OBLIGATION_TAG_PREFIX))) {\n      out.push({\n        obligation: tag.slice(OBLIGATION_TAG_PREFIX.length),\n        edge,\n        where: `${edge.source} -> ${edge.target}`,\n        subject: edge.target,\n      });\n    }\n  }\n  // The topology, walked by the same rule and for the reason the rule exists: a\n  // tag is a claim about the object it sits on, and which MODEL that object\n  // lives in is not something a reader of the tag can see. Until this walk the\n  // same undeclared tag was an error on a container and silence on a\n  // datacenter — fail-open, and the case FEAT-1's ARCH-LOAM-DEPLOY-TAGGED was\n  // written about. A fleet that draws no topology contributes nothing here.\n  for (const d of taggedDeployment(land.deployment ?? NO_DEPLOYMENT, land.elements, known, OBLIGATION_TAG_PREFIX)) {\n    out.push({\n      obligation: d.obligation,\n      deployed: d,\n      where: d.where,\n      ...(d.service === undefined ? {} : { subject: d.service }),\n    });\n  }\n  return out;\n}\n\n/**\n * `obligation.uncovered` — a tagged object no living arch requirement covers.\n *\n * The index is the union of EVERY service's living `arch.spec.md` `Covers:`\n * lines, because an obligation is placed by the architect on the map and met by\n * whichever team owns the thing it sits on — and a per-service index would\n * report an edge as uncovered because the requirement that covers it lives in\n * the service at the other end. `coversEntries` already drops REMOVED\n * requirements: a retired requirement covers nothing.\n *\n * ONE FINDING PER TAGGED OBJECT, subject = the service that owns it, so a\n * fleet-wide report reads as a worklist per team rather than as one line naming\n * forty edges.\n */\nasync function uncoveredFindings(check: ObligationCheck, tagged: TaggedObject[]): Promise<Finding[]> {\n  if (tagged.length === 0) return [];\n  const covers = await livingCovers(check);\n  const elements = check.land.elements;\n  const known = new Set(check.services.map((s) => s.id));\n  const covered = (t: TaggedObject): boolean => {\n    if (t.element !== undefined) return covers.some((c) => coversElement(c, t.element!));\n    if (t.edge !== undefined) return covers.some((c) => coversEdge(c, t.edge!, elements, known));\n    const d = t.deployed!;\n    return d.edge === undefined\n      ? covers.some((c) => coversDeployNode(c, d.id!))\n      : covers.some((c) => coversDeployEdge(c, d.edge!.source, d.edge!.target));\n  };\n  return tagged\n    .filter((t) => !covered(t))\n    .map((t) => ({\n      severity: \"warn\" as const,\n      code: \"obligation.uncovered\",\n      ...(t.subject === undefined ? {} : { subject: t.subject }),\n      message:\n        `${t.where} carries #${OBLIGATION_TAG_PREFIX}${t.obligation} and no living arch requirement covers it — ` +\n        `the obligation is placed and nothing says it is met. Write the requirement in ` +\n        // A region, a datacenter or a cluster is owned by no service, so the\n        // sentence stays general rather than naming a team at random. Every\n        // other object here has a real owner and keeps the actionable form.\n        `${t.subject === undefined ? \"the arch.spec.md of whichever service answers for this topology\" : `${t.subject}'s arch.spec.md`}` +\n        ` with \\`Covers: ${t.where}\\` and a scenario that proves it, or drop the tag if the decision no longer applies here.`,\n    }));\n}\n\n/**\n * Every `Covers:` entry the LIVING fleet writes, across both requirement\n * documents of every service.\n *\n * Existence is checked for both files and for the same reason\n * `permissionFindings` checks it: `arch.spec.md` is optional and most of a\n * legacy fleet has none, while `spec.md` is missing on a half-adopted service —\n * and `FleetContext.readRequirements` throws ENOENT, which surfaces as\n * `repository-unavailable` and takes the whole `--all` run down. Both axes are\n * read, not only the architecture one: `Covers:` is parsed everywhere for one\n * grammar's sake, and a fleet that wrote its outbox requirement in `spec.md`\n * has said the thing loam is asking about.\n */\nasync function livingCovers(check: ObligationCheck): Promise<CoversEntry[]> {\n  const entries: CoversEntry[] = [];\n  for (const service of check.services) {\n    const paths = servicePathsAt(service.dir);\n    for (const path of [paths.spec, paths.archSpec]) {\n      if (!existsSync(path)) continue;\n      entries.push(...coversEntries(await check.fleet.readRequirements(path)));\n    }\n  }\n  return entries;\n}\n\n/**\n * `obligation.adr-missing` — an `adr:` path that names no file.\n *\n * The path is relative to the docs repo root rather than to\n * `architecture/obligations.yaml`, because that is how a reader of a fleet\n * document thinks about a fleet path, and because the value is a YAML field\n * rather than a markdown link — `link.unresolved` grades links written in prose,\n * and this one is written in a slot loam defined.\n */\nfunction adrFindings(docsDir: DocsDir, obligations: readonly { id: string; adr?: string }[]): Finding[] {\n  return obligations\n    .filter((o) => o.adr !== undefined && !existsSync(join(docsDir, o.adr)))\n    .map((o) => ({\n      severity: \"error\" as const,\n      code: \"obligation.adr-missing\",\n      subject: o.id,\n      message:\n        `landscape: obligation '${o.id}' names \\`adr: ${o.adr!}\\` and no such file exists — ` +\n        \"the ADR is where the decision itself is written, so a pointer at nothing leaves every tag citing a rule nobody can read. \" +\n        \"Fix the path (it is relative to the docs repo root), write the record, or drop the field.\",\n    }));\n}\n\n/** `1 object` / `3 objects` — the plural spelled once, because three messages count things. */\nfunction count(n: number, noun: string): string {\n  return `${n} ${noun}${n === 1 ? \"\" : \"s\"}`;\n}\n"]}

package/dist/commands/validate/fleet/scorecard/adoption.js

@@ -0,0 +1,102 @@
+/**
+ * The adoption vocabulary of the fleet scorecard: which contract axes a
+ * service PARTICIPATES in, summed to the fleet's per-axis participation
+ * counts, and the mechanical rule for which warnings the `--all` text report
+ * may fold under a per-axis "not started" banner.
+ *
+ * A leaf on purpose: it imports nothing, so `../report.ts` (the text
+ * renderer) and `./contracts.js` (which computes the per-service booleans)
+ * can both use it without closing a cycle — `adoptionOf` takes the smallest
+ * structural parameter it needs instead of the ContractCounts type,
+ * core/vocabulary/maturity.ts's EdgeSource precedent for staying a leaf.
+ */
+/**
+ * The six contract axes a service adopts one at a time, in the order every
+ * rendering walks them. Participation is a per-service boolean with one
+ * mechanical rule per axis, spelled on `Scorecard.adoption` (./scorecard.js)
+ * where the payload key freezes them.
+ */
+export const ADOPTION_AXES = [
+    "requirements",
+    "arch",
+    "openapi",
+    "asyncapi",
+    "permissions",
+    "capabilities",
+];
+/** Sum the per-service participation booleans into the fleet's counts. */
+export function adoptionOf(perService) {
+    const out = { requirements: 0, arch: 0, openapi: 0, asyncapi: 0, permissions: 0, capabilities: 0 };
+    for (const svc of perService) {
+        for (const axis of ADOPTION_AXES)
+            if (svc.participates[axis])
+                out[axis] += 1;
+    }
+    return out;
+}
+/**
+ * THE QUALIFICATION RULE — this table IS the rule, and it is mechanical and
+ * fail-closed. A finding is grouped under an axis's "not started" banner iff
+ * (1) its severity is `warn`, (2) its code is listed in this table's row for
+ * the axis, (3) this run's `adoption[axis] === 0`, and (4) the run could
+ * measure that zero at all — a fleet with at least one service and no
+ * `service.unreadable` subject (report.ts enforces this half, beside the
+ * banner it gates: "0 of 0" is no fleet, and an unreadable service's
+ * all-false participation must not manufacture the zero). Anything else —
+ * every error, every warn code not listed here, every warn on an axis with
+ * even one participating service — prints ungrouped, exactly as before. When
+ * in doubt a code stays OUT of the table: the cost of a wrongly-ungrouped
+ * warning is noise, the cost of a wrongly-grouped one is a hidden defect.
+ *
+ * A row lists exactly the warn codes whose SOLE cause is the axis not being
+ * started fleet-wide — codes whose remedy presupposes starting the axis at
+ * all, so with zero participating services the per-target repetition carries
+ * no information the one banner does not:
+ *
+ * - requirements: `service.no-spec` and `spec.no-requirements` fire once per
+ *   service when nobody in the fleet has written a requirement block.
+ * - openapi: `service.no-openapi`'s WARN form (the error form — dangling
+ *   authored links into the absent file — never groups, by condition 1), and
+ *   `spine.op-link-missing`, which never reads the contract (service/spine.ts
+ *   documents exactly that) and so fires per titled Calls-edge even with zero
+ *   contracts fleet-wide.
+ * - permissions: `permissions.unenforced` — one finding whose whole content
+ *   is "the vocabulary exists and nothing cites it yet".
+ * - capabilities: `capability.unrealized` — deliberately one warn PER
+ *   declared capability (core/capabilities/findings.ts), so a freshly landed
+ *   vocabulary warns M times before the first requirement names any of them.
+ * - arch and asyncapi have NO code whose sole cause is fleet-wide absence
+ *   (an absent arch.spec.md is silent; an absent asyncapi.yaml is silent or
+ *   an error when authored links strand on it), so their rows are empty and
+ *   those axes surface only in the scorecard's not-started one-liner.
+ *
+ * Rows are disjoint — a code belongs to exactly one axis — which is what lets
+ * `groupedWarnCodes` invert the table into a Map. Not prose alone:
+ * test/adoption-rollup.test.ts asserts the flattened rows hold no duplicate,
+ * because a code filed under two axes would be grouped under whichever
+ * happens to sit at zero — possibly hiding it behind a fully adopted axis.
+ */
+export const AXIS_GROUPED_WARNS = {
+    requirements: ["service.no-spec", "spec.no-requirements"],
+    arch: [],
+    openapi: ["service.no-openapi", "spine.op-link-missing"],
+    asyncapi: [],
+    permissions: ["permissions.unenforced"],
+    capabilities: ["capability.unrealized"],
+};
+/**
+ * The table inverted for this run: warn code → its axis, for exactly the axes
+ * this run's adoption counts put at zero. Insertion order is ADOPTION_AXES
+ * order then row order, so every walk over the Map renders deterministically.
+ */
+export function groupedWarnCodes(adoption) {
+    const out = new Map();
+    for (const axis of ADOPTION_AXES) {
+        if (adoption[axis] !== 0)
+            continue;
+        for (const code of AXIS_GROUPED_WARNS[axis])
+            out.set(code, axis);
+    }
+    return out;
+}
+//# sourceMappingURL=adoption.js.map