@ybotok/loam 0.2.0-alpha.1 → 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

@@ -28,14 +28,15 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import {} from "../../../core/c4/likec4.js";
-import { closeIds, coversEdge, coversElement } from "../../../core/c4/arch.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 { readRequirementsDocument, parseRequirements } from "../../../core/document/parse.js";
 import { coversEntries } from "../checks/requirements.js";
 /**
  * The half that does not depend on the map: the file reads, and its `adr:`
@@ -76,7 +77,13 @@ export async function obligationFindings(check) {
     // 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.
-    const tagged = taggedObjects(check.land);
+    // 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))
@@ -123,7 +130,7 @@ export async function obligationFindings(check) {
  * resolves to `obligation.unknown` in every fleet that did not declare an empty
  * id, which is the honest answer.
  */
-function taggedObjects(land) {
+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))) {
@@ -145,6 +152,20 @@ function taggedObjects(land) {
             });
         }
     }
+    // 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;
 }
 /**
@@ -167,17 +188,29 @@ async function uncoveredFindings(check, tagged) {
     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) => t.element !== undefined
-        ? !covers.some((c) => coversElement(c, t.element))
-        : !covers.some((c) => coversEdge(c, t.edge, elements, known)))
+        .filter((t) => !covered(t))
         .map((t) => ({
         severity: "warn",
         code: "obligation.uncovered",
-        subject: t.subject,
+        ...(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 ${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.`,
+            `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.`,
     }));
 }
 /**
@@ -200,10 +233,7 @@ async function livingCovers(check) {
         for (const path of [paths.spec, paths.archSpec]) {
             if (!existsSync(path))
                 continue;
-            const reqs = check.fleet === undefined
-                ? parseRequirements(await readRequirementsDocument(path))
-                : await check.fleet.readRequirements(path);
-            entries.push(...coversEntries(reqs));
+            entries.push(...coversEntries(await check.fleet.readRequirements(path)));
         }
     }
     return entries;

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

@@ -1 +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 { closeIds, coversEdge, coversElement, type CoversEntry } from \"../../../core/c4/arch.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 { readRequirementsDocument, parseRequirements } from \"../../../core/document/parse.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  const tagged = taggedObjects(check.land);\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, or the edge — exactly one is set. */\n  element?: Elem;\n  edge?: Rel;\n  /** How the finding spells this object: an element id, or `source -> target`. */\n  where: string;\n  /** What the finding is filed under — the service that owns it, where one does. */\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): 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  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  return tagged\n    .filter((t) =>\n      t.element !== undefined\n        ? !covers.some((c) => coversElement(c, t.element!))\n        : !covers.some((c) => coversEdge(c, t.edge!, elements, known)),\n    )\n    .map((t) => ({\n      severity: \"warn\" as const,\n      code: \"obligation.uncovered\",\n      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 ${t.subject}'s arch.spec.md with ` +\n        `\\`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      const reqs =\n        check.fleet === undefined\n          ? parseRequirements(await readRequirementsDocument(path))\n          : await check.fleet.readRequirements(path);\n      entries.push(...coversEntries(reqs));\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"]}
+{"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/print.js

@@ -29,8 +29,12 @@ export function printScorecard(card) {
     // because that is where it changes the reading: "120 vouched" and "120
     // vouched (100 sampled)" are different fleets, and a reader who stops at
     // the first number must not have been told the stronger of the two.
+    // The content count rides beside the digest count rather than inside the
+    // vouched one: both are staleness, of the words and of the code, and
+    // "0 stale digest(s)" alone read as "nothing is stale" in a run that had
+    // just warned `content.stale`.
     `  provenance    ${p.vouched} vouched${p.sampledVouched > 0 ? ` (${p.sampledVouched} sampled)` : ""} — ` +
-        `${p.staleDigests} stale digest(s) · ${p.unverifiableFromHere} unverifiable from here`);
+        `${p.contentStale} stale content · ${p.staleDigests} stale digest(s) · ${p.unverifiableFromHere} unverifiable from here`);
     // The ceiling is the features axis's `active` — the payload deliberately
     // carries that denominator once, so this line reads it from there.
     console.log(`  verification  ${f.active} feature(s) → ${v.recorded} recorded — ` +
@@ -57,7 +61,11 @@ export function printScorecard(card) {
     const notStarted = ADOPTION_AXES.filter((axis) => a[axis] === 0);
     console.log(`  axes          adopted: ${adopted.length === 0 ? "none" : adopted.join(", ")}` +
         (notStarted.length === 0 ? "" : ` · not started: ${notStarted.join(", ")}`));
+    // The stage values are `loam status`'s branching vocabulary, and `ready` read
+    // alone as "ready to ship" — so the two that mislead are glossed in place
+    // (`loam explain ready` has the long form).
     console.log(`  features      ${f.active} active — ` +
-        ARTIFACT_STATUSES.map((stage) => `${f.stages[stage]} ${stage}`).join(" · "));
+        ARTIFACT_STATUSES.map((stage) => `${f.stages[stage]} ${stage}`).join(" · ") +
+        (f.active > 0 ? "  (ready = docs written, not yet verified; done = verified)" : ""));
 }
 //# sourceMappingURL=print.js.map

package/dist/commands/validate/fleet/scorecard/print.js.map

@@ -1 +1 @@
-{"version":3,"file":"print.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/scorecard/print.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet scorecard's one table — how the `--all` text report renders what\n * `./scorecard.js` derived. A module of its own for validate's own discipline\n * (validate.ts's header: the checks produce findings and none of them print;\n * printing happens after the last target is graded), and so the derivation\n * and the formatting do not share a file whose one seam is exactly that.\n *\n * One line per axis, ceiling before actual, read left to right the way the\n * numbers are read in a CI log — except the adoption row, which states\n * participation over the denominator (`requirements 3/40`): adoption is an\n * N-of-M spread, not a ceiling chased by an actual, and forcing it into the\n * arrow idiom would read as one. It prints under `--errors-only` too, on\n * purpose: like the summary footer it is a rollup, not a finding, and\n * `--errors-only` is a findings-rendering lever (report.ts).\n */\nimport { ARTIFACT_STATUSES } from \"../../../../core/status/report.js\";\nimport { ANSWERED_BY } from \"../../../../core/verify/answers.js\";\nimport { VERIFICATION_VERDICTS } from \"../../../../core/verify/record.js\";\nimport { MATURITY_LADDER } from \"../../../../core/vocabulary/maturity.js\";\nimport { ADOPTION_AXES } from \"./adoption.js\";\nimport { type Scorecard } from \"./scorecard.js\";\n\nexport function printScorecard(card: Scorecard): void {\n  const { maturity, provenance: p, verification: v, operations: o, messages: m, c4, features: f } =\n    card;\n  console.log(\"\\nfleet scorecard (ceiling → actual)\");\n  console.log(\n    `  services      ${card.services} — ` +\n      MATURITY_LADDER.map((rung) => `${maturity[rung]} ${rung}`).join(\" · \"),\n  );\n  console.log(\n    // The sampled count rides INSIDE the vouched number rather than after it,\n    // because that is where it changes the reading: \"120 vouched\" and \"120\n    // vouched (100 sampled)\" are different fleets, and a reader who stops at\n    // the first number must not have been told the stronger of the two.\n    `  provenance    ${p.vouched} vouched${p.sampledVouched > 0 ? ` (${p.sampledVouched} sampled)` : \"\"} — ` +\n      `${p.staleDigests} stale digest(s) · ${p.unverifiableFromHere} unverifiable from here`,\n  );\n  // The ceiling is the features axis's `active` — the payload deliberately\n  // carries that denominator once, so this line reads it from there.\n  console.log(\n    `  verification  ${f.active} feature(s) → ${v.recorded} recorded — ` +\n      VERIFICATION_VERDICTS.map((verdict) => `${v.verdicts[verdict]} ${verdict}`).join(\" · \") +\n      ` — claims ${v.claims.confirmed}/${v.claims.total} confirmed ` +\n      // Every provenance, under its own `answered_by` spelling and always all\n      // three — the same stable-shape rendering as the verdicts before it. Two\n      // buckets could not name what they held: the line said \"runner\" over\n      // claims no runner answered, and no label short of the real one fixes\n      // that, because `external-runner` is neither of the other two.\n      `(${ANSWERED_BY.map((who) => `${v.claims.answered[who]} ${who}`).join(\" · \")})`,\n  );\n  console.log(\n    `  operations    ${o.defined} defined → ${o.governed} governed · ` +\n      `${o.deprecated} deprecated (${o.deprecatedStillConsumed} still consumed)`,\n  );\n  console.log(`  messages      ${m.defined} defined → ${m.linked} linked`);\n  console.log(`  c4            ${c4.elements} elements → ${c4.covered} covered`);\n  // Participation per axis over the one denominator, then the same facts as\n  // the sentence a standup reads out: which axes the fleet has started at\n  // all. \"adopted\" here means at least one participating service — the\n  // per-axis counts on the line above say how many.\n  const a = card.adoption;\n  console.log(\n    `  adoption      ` +\n      ADOPTION_AXES.map((axis) => `${axis} ${a[axis]}/${card.services}`).join(\" · \"),\n  );\n  const adopted = ADOPTION_AXES.filter((axis) => a[axis] > 0);\n  const notStarted = ADOPTION_AXES.filter((axis) => a[axis] === 0);\n  console.log(\n    `  axes          adopted: ${adopted.length === 0 ? \"none\" : adopted.join(\", \")}` +\n      (notStarted.length === 0 ? \"\" : ` · not started: ${notStarted.join(\", \")}`),\n  );\n  console.log(\n    `  features      ${f.active} active — ` +\n      ARTIFACT_STATUSES.map((stage) => `${f.stages[stage]} ${stage}`).join(\" · \"),\n  );\n}\n"]}
+{"version":3,"file":"print.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/scorecard/print.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet scorecard's one table — how the `--all` text report renders what\n * `./scorecard.js` derived. A module of its own for validate's own discipline\n * (validate.ts's header: the checks produce findings and none of them print;\n * printing happens after the last target is graded), and so the derivation\n * and the formatting do not share a file whose one seam is exactly that.\n *\n * One line per axis, ceiling before actual, read left to right the way the\n * numbers are read in a CI log — except the adoption row, which states\n * participation over the denominator (`requirements 3/40`): adoption is an\n * N-of-M spread, not a ceiling chased by an actual, and forcing it into the\n * arrow idiom would read as one. It prints under `--errors-only` too, on\n * purpose: like the summary footer it is a rollup, not a finding, and\n * `--errors-only` is a findings-rendering lever (report.ts).\n */\nimport { ARTIFACT_STATUSES } from \"../../../../core/status/report.js\";\nimport { ANSWERED_BY } from \"../../../../core/verify/answers.js\";\nimport { VERIFICATION_VERDICTS } from \"../../../../core/verify/record.js\";\nimport { MATURITY_LADDER } from \"../../../../core/vocabulary/maturity.js\";\nimport { ADOPTION_AXES } from \"./adoption.js\";\nimport { type Scorecard } from \"./scorecard.js\";\n\nexport function printScorecard(card: Scorecard): void {\n  const { maturity, provenance: p, verification: v, operations: o, messages: m, c4, features: f } =\n    card;\n  console.log(\"\\nfleet scorecard (ceiling → actual)\");\n  console.log(\n    `  services      ${card.services} — ` +\n      MATURITY_LADDER.map((rung) => `${maturity[rung]} ${rung}`).join(\" · \"),\n  );\n  console.log(\n    // The sampled count rides INSIDE the vouched number rather than after it,\n    // because that is where it changes the reading: \"120 vouched\" and \"120\n    // vouched (100 sampled)\" are different fleets, and a reader who stops at\n    // the first number must not have been told the stronger of the two.\n    // The content count rides beside the digest count rather than inside the\n    // vouched one: both are staleness, of the words and of the code, and\n    // \"0 stale digest(s)\" alone read as \"nothing is stale\" in a run that had\n    // just warned `content.stale`.\n    `  provenance    ${p.vouched} vouched${p.sampledVouched > 0 ? ` (${p.sampledVouched} sampled)` : \"\"} — ` +\n      `${p.contentStale} stale content · ${p.staleDigests} stale digest(s) · ${p.unverifiableFromHere} unverifiable from here`,\n  );\n  // The ceiling is the features axis's `active` — the payload deliberately\n  // carries that denominator once, so this line reads it from there.\n  console.log(\n    `  verification  ${f.active} feature(s) → ${v.recorded} recorded — ` +\n      VERIFICATION_VERDICTS.map((verdict) => `${v.verdicts[verdict]} ${verdict}`).join(\" · \") +\n      ` — claims ${v.claims.confirmed}/${v.claims.total} confirmed ` +\n      // Every provenance, under its own `answered_by` spelling and always all\n      // three — the same stable-shape rendering as the verdicts before it. Two\n      // buckets could not name what they held: the line said \"runner\" over\n      // claims no runner answered, and no label short of the real one fixes\n      // that, because `external-runner` is neither of the other two.\n      `(${ANSWERED_BY.map((who) => `${v.claims.answered[who]} ${who}`).join(\" · \")})`,\n  );\n  console.log(\n    `  operations    ${o.defined} defined → ${o.governed} governed · ` +\n      `${o.deprecated} deprecated (${o.deprecatedStillConsumed} still consumed)`,\n  );\n  console.log(`  messages      ${m.defined} defined → ${m.linked} linked`);\n  console.log(`  c4            ${c4.elements} elements → ${c4.covered} covered`);\n  // Participation per axis over the one denominator, then the same facts as\n  // the sentence a standup reads out: which axes the fleet has started at\n  // all. \"adopted\" here means at least one participating service — the\n  // per-axis counts on the line above say how many.\n  const a = card.adoption;\n  console.log(\n    `  adoption      ` +\n      ADOPTION_AXES.map((axis) => `${axis} ${a[axis]}/${card.services}`).join(\" · \"),\n  );\n  const adopted = ADOPTION_AXES.filter((axis) => a[axis] > 0);\n  const notStarted = ADOPTION_AXES.filter((axis) => a[axis] === 0);\n  console.log(\n    `  axes          adopted: ${adopted.length === 0 ? \"none\" : adopted.join(\", \")}` +\n      (notStarted.length === 0 ? \"\" : ` · not started: ${notStarted.join(\", \")}`),\n  );\n  // The stage values are `loam status`'s branching vocabulary, and `ready` read\n  // alone as \"ready to ship\" — so the two that mislead are glossed in place\n  // (`loam explain ready` has the long form).\n  console.log(\n    `  features      ${f.active} active — ` +\n      ARTIFACT_STATUSES.map((stage) => `${f.stages[stage]} ${stage}`).join(\" · \") +\n      (f.active > 0 ? \"  (ready = docs written, not yet verified; done = verified)\" : \"\"),\n  );\n}\n"]}

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

@@ -101,12 +101,15 @@ async function derive(input) {
     const covered = eligible.filter((e) => covers.some((c) => coversElement(c, e))).length;
     // Verification: `list`'s own cells, so the two commands cannot disagree
     // about a record's verdict. Active features only — an archived record is
-    // frozen history, not fleet debt. This fan-out is NOT memo hits:
-    // readVerification is one small file read per feature, and a recorded cell
-    // additionally derives its checklist (the same cost `list` pays for the same
-    // column) — real filesystem work, so it runs through the bounded pool.
+    // frozen history, not fleet debt. This fan-out is NOT memo hits: reading a
+    // feature's record is a directory listing plus a small read per record file
+    // (the one-file `verification.yaml` and one `verification/<svc>.yaml` per
+    // attesting service), and a recorded cell additionally derives its checklist
+    // (the same cost `list` pays for the same column; only its enumerations and
+    // delta parse are memo hits through `fleet`) — real filesystem work, so it
+    // runs through the bounded pool.
     const features = await fleet.listFeatures(docsDir);
-    const cells = await inOrder(features, (f) => featureVerification(docsDir, f));
+    const cells = await inOrder(features, (f) => featureVerification(docsDir, f, fleet));
     const recorded = cells.filter((c) => c !== null);
     const verdicts = Object.fromEntries(VERIFICATION_VERDICTS.map((v) => [v, 0]));
     for (const cell of recorded)
@@ -124,18 +127,21 @@ async function derive(input) {
         maturity,
         provenance: {
             vouched: maturity.vouched,
-            // Both counts join through `subjectsWith` on the run's OWN findings, so
+            // Every count joins through `subjectsWith` on the run's OWN findings, so
             // each is structurally the same number as the report beside it — the
             // unverifiable count is the footer's (unverifiableSubjects is the same
             // call on the same code; this package cannot import the parent back).
-            // Both codes are LITERALS — provenance/sources.ts's own spellings —
-            // because the stable-code collector reads counting sites and refuses a
-            // slot it cannot read; the collector is also what convicts a typo here.
+            // Every code is a LITERAL — the emitter's own spelling — because the
+            // stable-code collector reads counting sites and refuses a slot it
+            // cannot read; the collector is also what convicts a typo here.
             staleDigests: subjectsWith(targets, "sources.stale"),
             unverifiableFromHere: subjectsWith(targets, "sources.unverifiable-from-here"),
-            // Doc-side, so unlike `staleDigests` this one is complete even from the
-            // docs repo: `sources.sampled-vouch` needs no service repo to fire.
+            // Doc-side, so unlike `staleDigests` these two are complete even from
+            // the docs repo: neither `sources.sampled-vouch` nor `content.stale`
+            // needs a service repo to fire. `content.stale` names no subject, and
+            // `subjectsWith` falls back to the target id — the service, here.
             sampledVouched: subjectsWith(targets, "sources.sampled-vouch"),
+            contentStale: subjectsWith(targets, "content.stale"),
         },
         verification: {
             recorded: recorded.length,