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

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

@@ -0,0 +1 @@
+{"version":3,"file":"adoption.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/scorecard/adoption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,cAAc;IACd,MAAM;IACN,SAAS;IACT,UAAU;IACV,aAAa;IACb,cAAc;CACN,CAAC;AAaX,0EAA0E;AAC1E,MAAM,UAAU,UAAU,CACxB,UAA6F;IAE7F,MAAM,GAAG,GAAa,EAAE,YAAY,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IAC7G,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,aAAa;YAAE,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA4C;IACzE,YAAY,EAAE,CAAC,iBAAiB,EAAE,sBAAsB,CAAC;IACzD,IAAI,EAAE,EAAE;IACR,OAAO,EAAE,CAAC,oBAAoB,EAAE,uBAAuB,CAAC;IACxD,QAAQ,EAAE,EAAE;IACZ,WAAW,EAAE,CAAC,wBAAwB,CAAC;IACvC,YAAY,EAAE,CAAC,uBAAuB,CAAC;CACxC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAkB;IACjD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,SAAS;QACnC,KAAK,MAAM,IAAI,IAAI,kBAAkB,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["/**\n * The adoption vocabulary of the fleet scorecard: which contract axes a\n * service PARTICIPATES in, summed to the fleet's per-axis participation\n * counts, and the mechanical rule for which warnings the `--all` text report\n * may fold under a per-axis \"not started\" banner.\n *\n * A leaf on purpose: it imports nothing, so `../report.ts` (the text\n * renderer) and `./contracts.js` (which computes the per-service booleans)\n * can both use it without closing a cycle — `adoptionOf` takes the smallest\n * structural parameter it needs instead of the ContractCounts type,\n * core/vocabulary/maturity.ts's EdgeSource precedent for staying a leaf.\n */\n\n/**\n * The six contract axes a service adopts one at a time, in the order every\n * rendering walks them. Participation is a per-service boolean with one\n * mechanical rule per axis, spelled on `Scorecard.adoption` (./scorecard.js)\n * where the payload key freezes them.\n */\nexport const ADOPTION_AXES = [\n  \"requirements\",\n  \"arch\",\n  \"openapi\",\n  \"asyncapi\",\n  \"permissions\",\n  \"capabilities\",\n] as const;\n\nexport type AdoptionAxis = (typeof ADOPTION_AXES)[number];\n\n/**\n * Participating services per axis. Flat counts — the denominator is\n * `Scorecard.services`, carried once so two copies cannot disagree. An axis\n * at 0 reads \"not started\"; 0 < N < M is \"partially adopted\", and the two\n * must never be conflated: a banner that grouped a partially-adopted axis's\n * warnings would hide the exact services the count says are missing.\n */\nexport type Adoption = Record<AdoptionAxis, number>;\n\n/** Sum the per-service participation booleans into the fleet's counts. */\nexport function adoptionOf(\n  perService: ReadonlyArray<{ readonly participates: Readonly<Record<AdoptionAxis, boolean>> }>,\n): Adoption {\n  const out: Adoption = { requirements: 0, arch: 0, openapi: 0, asyncapi: 0, permissions: 0, capabilities: 0 };\n  for (const svc of perService) {\n    for (const axis of ADOPTION_AXES) if (svc.participates[axis]) out[axis] += 1;\n  }\n  return out;\n}\n\n/**\n * THE QUALIFICATION RULE — this table IS the rule, and it is mechanical and\n * fail-closed. A finding is grouped under an axis's \"not started\" banner iff\n * (1) its severity is `warn`, (2) its code is listed in this table's row for\n * the axis, (3) this run's `adoption[axis] === 0`, and (4) the run could\n * measure that zero at all — a fleet with at least one service and no\n * `service.unreadable` subject (report.ts enforces this half, beside the\n * banner it gates: \"0 of 0\" is no fleet, and an unreadable service's\n * all-false participation must not manufacture the zero). Anything else —\n * every error, every warn code not listed here, every warn on an axis with\n * even one participating service — prints ungrouped, exactly as before. When\n * in doubt a code stays OUT of the table: the cost of a wrongly-ungrouped\n * warning is noise, the cost of a wrongly-grouped one is a hidden defect.\n *\n * A row lists exactly the warn codes whose SOLE cause is the axis not being\n * started fleet-wide — codes whose remedy presupposes starting the axis at\n * all, so with zero participating services the per-target repetition carries\n * no information the one banner does not:\n *\n * - requirements: `service.no-spec` and `spec.no-requirements` fire once per\n *   service when nobody in the fleet has written a requirement block.\n * - openapi: `service.no-openapi`'s WARN form (the error form — dangling\n *   authored links into the absent file — never groups, by condition 1), and\n *   `spine.op-link-missing`, which never reads the contract (service/spine.ts\n *   documents exactly that) and so fires per titled Calls-edge even with zero\n *   contracts fleet-wide.\n * - permissions: `permissions.unenforced` — one finding whose whole content\n *   is \"the vocabulary exists and nothing cites it yet\".\n * - capabilities: `capability.unrealized` — deliberately one warn PER\n *   declared capability (core/capabilities/findings.ts), so a freshly landed\n *   vocabulary warns M times before the first requirement names any of them.\n * - arch and asyncapi have NO code whose sole cause is fleet-wide absence\n *   (an absent arch.spec.md is silent; an absent asyncapi.yaml is silent or\n *   an error when authored links strand on it), so their rows are empty and\n *   those axes surface only in the scorecard's not-started one-liner.\n *\n * Rows are disjoint — a code belongs to exactly one axis — which is what lets\n * `groupedWarnCodes` invert the table into a Map. Not prose alone:\n * test/adoption-rollup.test.ts asserts the flattened rows hold no duplicate,\n * because a code filed under two axes would be grouped under whichever\n * happens to sit at zero — possibly hiding it behind a fully adopted axis.\n */\nexport const AXIS_GROUPED_WARNS: Record<AdoptionAxis, readonly string[]> = {\n  requirements: [\"service.no-spec\", \"spec.no-requirements\"],\n  arch: [],\n  openapi: [\"service.no-openapi\", \"spine.op-link-missing\"],\n  asyncapi: [],\n  permissions: [\"permissions.unenforced\"],\n  capabilities: [\"capability.unrealized\"],\n};\n\n/**\n * The table inverted for this run: warn code → its axis, for exactly the axes\n * this run's adoption counts put at zero. Insertion order is ADOPTION_AXES\n * order then row order, so every walk over the Map renders deterministically.\n */\nexport function groupedWarnCodes(adoption: Adoption): Map<string, AdoptionAxis> {\n  const out = new Map<string, AdoptionAxis>();\n  for (const axis of ADOPTION_AXES) {\n    if (adoption[axis] !== 0) continue;\n    for (const code of AXIS_GROUPED_WARNS[axis]) out.set(code, axis);\n  }\n  return out;\n}\n"]}

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

@@ -0,0 +1,98 @@
+/**
+ * One service's contract-axis contributions to the fleet scorecard: the HTTP
+ * and event counts off its living documents, its arch `Covers:` entries for
+ * the C4 census, and the per-axis adoption booleans (`participates`).
+ * `./scorecard.js` sums these across the fleet; this module owns the
+ * per-service reads and their containment, and never prints.
+ */
+import { existsSync } from "node:fs";
+import { readAsyncapi } from "../../../../core/asyncapi/read.js";
+import {} from "../../../../core/c4/arch.js";
+import {} from "../../../../core/fleet-context.js";
+import { readOpenapi } from "../../../../core/openapi/doc.js";
+import {} from "../../../../core/repo/entries.js";
+import { servicePathsAt } from "../../../../core/repo/paths.js";
+import { coversEntries } from "../../checks/requirements.js";
+import {} from "./adoption.js";
+export async function contractCounts(svc, fleet, inbound) {
+    try {
+        return await readContracts(svc, fleet, inbound);
+    }
+    catch {
+        // `guarded`'s doctrine, one rollup down: these are the same memoized reads
+        // this service's own target already failed on, and a memoized REJECTION
+        // rejects again on every await — so a spec.md that is not UTF-8, or an
+        // openapi.yaml that is a directory, deleted the whole fleet's card from
+        // inside Promise.all. The service's `service.unreadable` finding names the
+        // cause; here the one unreadable service contributes zeros and the
+        // fleet's rollup survives. Participation is all-false the way the counts
+        // are zero — NOT because the service started nothing (an unreadable
+        // service proves nothing, least of all that), but because no claim can be
+        // made; the text renderer therefore refuses to group warnings on any run
+        // with an unreadable service (report.ts), since a false `false` here
+        // could manufacture the fleet-wide N=0 that licenses suppression.
+        return {
+            operations: { defined: 0, governed: 0, deprecated: 0, deprecatedStillConsumed: 0 },
+            messages: { defined: 0, linked: 0 },
+            covers: [],
+            participates: { requirements: false, arch: false, openapi: false, asyncapi: false, permissions: false, capabilities: false },
+        };
+    }
+}
+async function readContracts(svc, fleet, inbound) {
+    const paths = servicePathsAt(svc.dir);
+    const reqs = existsSync(paths.spec) ? await fleet.readRequirements(paths.spec) : [];
+    const archReqs = existsSync(paths.archSpec) ? await fleet.readRequirements(paths.archSpec) : [];
+    // The living rule the service target applies (service/specs.ts): a REMOVED
+    // requirement is on its way out and governs nothing. Hoisted for BOTH
+    // documents because the `linked` join and the participation booleans below
+    // read the same non-REMOVED sets.
+    const living = reqs.filter((r) => r.kind !== "REMOVED");
+    const archLiving = archReqs.filter((r) => r.kind !== "REMOVED");
+    const api = await readOpenapi(paths.openapi, fleet);
+    // Removal markers are never callable operations (service/api.ts's liveOps
+    // rule), and an unreadable contract defines nothing this census may count —
+    // swallowing it into its parsed subset would grade a broken file as a thin one.
+    const ops = api.unreadable ? [] : api.ops.filter((o) => !o.remove);
+    const governed = new Set(living.flatMap((r) => r.operations));
+    const deprecated = new Set(ops.filter((o) => o.deprecated).map((o) => o.id));
+    const events = await readAsyncapi(paths.asyncapi, fleet);
+    // Distinct names — every join on the event spine is by NAME, so a duplicate
+    // slot is one message — and the governance join is requirement lines from
+    // BOTH documents, never landscape edges: an edge is a claim about traffic,
+    // a requirement is governance (service/events/events.ts).
+    const declared = events.unreadable
+        ? []
+        : [...new Set(events.messages.filter((m) => m.remove !== true).map((m) => m.name))];
+    const linked = new Set([...living, ...archLiving].flatMap((r) => [...r.publishes, ...r.consumes]));
+    // The per-axis participation booleans, each the one-line rule the Scorecard
+    // doc comment pins. Requirements/arch count ANY parsed block (REMOVED
+    // included — a spec retiring its last requirement still started the axis),
+    // while permissions/capabilities apply the non-REMOVED rule their fleet
+    // checks apply (fleet-shape.ts's used sets), so "participates" and "cites"
+    // cannot disagree about the same line.
+    const participates = {
+        requirements: reqs.length > 0,
+        arch: archReqs.length > 0,
+        openapi: existsSync(paths.openapi),
+        asyncapi: existsSync(paths.asyncapi),
+        permissions: [...living, ...archLiving].some((r) => r.requires.length > 0),
+        capabilities: [...living, ...archLiving].some((r) => r.capabilities.length > 0),
+    };
+    return {
+        operations: {
+            defined: ops.length,
+            governed: ops.filter((o) => governed.has(o.id)).length,
+            deprecated: deprecated.size,
+            deprecatedStillConsumed: [...deprecated].filter((id) => governed.has(id) || inbound.has(id)).length,
+        },
+        messages: {
+            defined: declared.length,
+            linked: declared.filter((name) => linked.has(name)).length,
+        },
+        // coversEntries already drops REMOVED requirements.
+        covers: coversEntries(archReqs),
+        participates,
+    };
+}
+//# sourceMappingURL=contracts.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/scorecard/contracts.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One service's contract-axis contributions to the fleet scorecard: the HTTP\n * and event counts off its living documents, its arch `Covers:` entries for\n * the C4 census, and the per-axis adoption booleans (`participates`).\n * `./scorecard.js` sums these across the fleet; this module owns the\n * per-service reads and their containment, and never prints.\n */\nimport { existsSync } from \"node:fs\";\nimport { readAsyncapi } from \"../../../../core/asyncapi/read.js\";\nimport { type CoversEntry } from \"../../../../core/c4/arch.js\";\nimport { type FleetContext } from \"../../../../core/fleet-context.js\";\nimport { readOpenapi } from \"../../../../core/openapi/doc.js\";\nimport { type ServiceEntry } from \"../../../../core/repo/entries.js\";\nimport { servicePathsAt } from \"../../../../core/repo/paths.js\";\nimport { coversEntries } from \"../../checks/requirements.js\";\nimport { type AdoptionAxis } from \"./adoption.js\";\n\n/**\n * One service's contributions. Structurally identical to the `operations` and\n * `messages` sections of the Scorecard payload — spelled here rather than\n * imported from `./scorecard.js`, because that import would close a file\n * cycle with the module that sums these.\n */\nexport interface ContractCounts {\n  operations: { defined: number; governed: number; deprecated: number; deprecatedStillConsumed: number };\n  messages: { defined: number; linked: number };\n  covers: CoversEntry[];\n  /**\n   * Whether THIS service has started each adoption axis — the per-service\n   * booleans `adoptionOf` (./adoption.js) sums into the fleet's participation\n   * counts. The six rules are spelled on `Scorecard.adoption` (./scorecard.js),\n   * where the payload key freezes them; every input is a read this function\n   * already pays for.\n   */\n  participates: Record<AdoptionAxis, boolean>;\n}\n\nexport async function contractCounts(\n  svc: ServiceEntry,\n  fleet: FleetContext,\n  inbound: ReadonlySet<string>,\n): Promise<ContractCounts> {\n  try {\n    return await readContracts(svc, fleet, inbound);\n  } catch {\n    // `guarded`'s doctrine, one rollup down: these are the same memoized reads\n    // this service's own target already failed on, and a memoized REJECTION\n    // rejects again on every await — so a spec.md that is not UTF-8, or an\n    // openapi.yaml that is a directory, deleted the whole fleet's card from\n    // inside Promise.all. The service's `service.unreadable` finding names the\n    // cause; here the one unreadable service contributes zeros and the\n    // fleet's rollup survives. Participation is all-false the way the counts\n    // are zero — NOT because the service started nothing (an unreadable\n    // service proves nothing, least of all that), but because no claim can be\n    // made; the text renderer therefore refuses to group warnings on any run\n    // with an unreadable service (report.ts), since a false `false` here\n    // could manufacture the fleet-wide N=0 that licenses suppression.\n    return {\n      operations: { defined: 0, governed: 0, deprecated: 0, deprecatedStillConsumed: 0 },\n      messages: { defined: 0, linked: 0 },\n      covers: [],\n      participates: { requirements: false, arch: false, openapi: false, asyncapi: false, permissions: false, capabilities: false },\n    };\n  }\n}\n\nasync function readContracts(\n  svc: ServiceEntry,\n  fleet: FleetContext,\n  inbound: ReadonlySet<string>,\n): Promise<ContractCounts> {\n  const paths = servicePathsAt(svc.dir);\n  const reqs = existsSync(paths.spec) ? await fleet.readRequirements(paths.spec) : [];\n  const archReqs = existsSync(paths.archSpec) ? await fleet.readRequirements(paths.archSpec) : [];\n  // The living rule the service target applies (service/specs.ts): a REMOVED\n  // requirement is on its way out and governs nothing. Hoisted for BOTH\n  // documents because the `linked` join and the participation booleans below\n  // read the same non-REMOVED sets.\n  const living = reqs.filter((r) => r.kind !== \"REMOVED\");\n  const archLiving = archReqs.filter((r) => r.kind !== \"REMOVED\");\n\n  const api = await readOpenapi(paths.openapi, fleet);\n  // Removal markers are never callable operations (service/api.ts's liveOps\n  // rule), and an unreadable contract defines nothing this census may count —\n  // swallowing it into its parsed subset would grade a broken file as a thin one.\n  const ops = api.unreadable ? [] : api.ops.filter((o) => !o.remove);\n  const governed = new Set(living.flatMap((r) => r.operations));\n  const deprecated = new Set(ops.filter((o) => o.deprecated).map((o) => o.id));\n\n  const events = await readAsyncapi(paths.asyncapi, fleet);\n  // Distinct names — every join on the event spine is by NAME, so a duplicate\n  // slot is one message — and the governance join is requirement lines from\n  // BOTH documents, never landscape edges: an edge is a claim about traffic,\n  // a requirement is governance (service/events/events.ts).\n  const declared = events.unreadable\n    ? []\n    : [...new Set(events.messages.filter((m) => m.remove !== true).map((m) => m.name))];\n  const linked = new Set(\n    [...living, ...archLiving].flatMap((r) => [...r.publishes, ...r.consumes]),\n  );\n\n  // The per-axis participation booleans, each the one-line rule the Scorecard\n  // doc comment pins. Requirements/arch count ANY parsed block (REMOVED\n  // included — a spec retiring its last requirement still started the axis),\n  // while permissions/capabilities apply the non-REMOVED rule their fleet\n  // checks apply (fleet-shape.ts's used sets), so \"participates\" and \"cites\"\n  // cannot disagree about the same line.\n  const participates: Record<AdoptionAxis, boolean> = {\n    requirements: reqs.length > 0,\n    arch: archReqs.length > 0,\n    openapi: existsSync(paths.openapi),\n    asyncapi: existsSync(paths.asyncapi),\n    permissions: [...living, ...archLiving].some((r) => r.requires.length > 0),\n    capabilities: [...living, ...archLiving].some((r) => r.capabilities.length > 0),\n  };\n\n  return {\n    operations: {\n      defined: ops.length,\n      governed: ops.filter((o) => governed.has(o.id)).length,\n      deprecated: deprecated.size,\n      deprecatedStillConsumed: [...deprecated].filter((id) => governed.has(id) || inbound.has(id)).length,\n    },\n    messages: {\n      defined: declared.length,\n      linked: declared.filter((name) => linked.has(name)).length,\n    },\n    // coversEntries already drops REMOVED requirements.\n    covers: coversEntries(archReqs),\n    participates,\n  };\n}\n"]}

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

@@ -0,0 +1,71 @@
+/**
+ * The fleet scorecard's one table — how the `--all` text report renders what
+ * `./scorecard.js` derived. A module of its own for validate's own discipline
+ * (validate.ts's header: the checks produce findings and none of them print;
+ * printing happens after the last target is graded), and so the derivation
+ * and the formatting do not share a file whose one seam is exactly that.
+ *
+ * One line per axis, ceiling before actual, read left to right the way the
+ * numbers are read in a CI log — except the adoption row, which states
+ * participation over the denominator (`requirements 3/40`): adoption is an
+ * N-of-M spread, not a ceiling chased by an actual, and forcing it into the
+ * arrow idiom would read as one. It prints under `--errors-only` too, on
+ * purpose: like the summary footer it is a rollup, not a finding, and
+ * `--errors-only` is a findings-rendering lever (report.ts).
+ */
+import { ARTIFACT_STATUSES } from "../../../../core/status/report.js";
+import { ANSWERED_BY } from "../../../../core/verify/answers.js";
+import { VERIFICATION_VERDICTS } from "../../../../core/verify/record.js";
+import { MATURITY_LADDER } from "../../../../core/vocabulary/maturity.js";
+import { ADOPTION_AXES } from "./adoption.js";
+import {} from "./scorecard.js";
+export function printScorecard(card) {
+    const { maturity, provenance: p, verification: v, operations: o, messages: m, c4, features: f } = card;
+    console.log("\nfleet scorecard (ceiling → actual)");
+    console.log(`  services      ${card.services} — ` +
+        MATURITY_LADDER.map((rung) => `${maturity[rung]} ${rung}`).join(" · "));
+    console.log(
+    // The sampled count rides INSIDE the vouched number rather than after it,
+    // 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.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 — ` +
+        VERIFICATION_VERDICTS.map((verdict) => `${v.verdicts[verdict]} ${verdict}`).join(" · ") +
+        ` — claims ${v.claims.confirmed}/${v.claims.total} confirmed ` +
+        // Every provenance, under its own `answered_by` spelling and always all
+        // three — the same stable-shape rendering as the verdicts before it. Two
+        // buckets could not name what they held: the line said "runner" over
+        // claims no runner answered, and no label short of the real one fixes
+        // that, because `external-runner` is neither of the other two.
+        `(${ANSWERED_BY.map((who) => `${v.claims.answered[who]} ${who}`).join(" · ")})`);
+    console.log(`  operations    ${o.defined} defined → ${o.governed} governed · ` +
+        `${o.deprecated} deprecated (${o.deprecatedStillConsumed} still consumed)`);
+    console.log(`  messages      ${m.defined} defined → ${m.linked} linked`);
+    console.log(`  c4            ${c4.elements} elements → ${c4.covered} covered`);
+    // Participation per axis over the one denominator, then the same facts as
+    // the sentence a standup reads out: which axes the fleet has started at
+    // all. "adopted" here means at least one participating service — the
+    // per-axis counts on the line above say how many.
+    const a = card.adoption;
+    console.log(`  adoption      ` +
+        ADOPTION_AXES.map((axis) => `${axis} ${a[axis]}/${card.services}`).join(" · "));
+    const adopted = ADOPTION_AXES.filter((axis) => a[axis] > 0);
+    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(" · ") +
+        (f.active > 0 ? "  (ready = docs written, not yet verified; done = verified)" : ""));
+}
+//# sourceMappingURL=print.js.map

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

@@ -0,0 +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    // 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

@@ -0,0 +1,162 @@
+/**
+ * The fleet scorecard: ceiling-vs-actual aggregates for `validate --all`,
+ * recomputed per invocation from the same memoized FleetContext reads the run
+ * already paid for. loam stores no history — week-over-week tracking is the
+ * caller's pipeline's job: capture the `scorecard` payload key per run into a
+ * metrics store. Each axis is a pair of domain-named counts (`defined` vs
+ * `governed`) rather than abstract ceiling/actual keys, because payload keys
+ * freeze the moment they ship and the domain nouns survive axis nuance.
+ *
+ * This module derives and never prints; `./print.js` renders the one table
+ * the `--all` text report appends, and `./contracts.js` owns the per-service
+ * contract reads it sums.
+ */
+import { existsSync } from "node:fs";
+import { inOrder } from "../../../../core/kernel/concurrency.js";
+import { coversElement } from "../../../../core/c4/arch.js";
+import { serviceResolver } from "../../../../core/c4/resolve/service.js";
+import {} from "../../../../core/fleet-context.js";
+import {} from "../../../../core/kernel/ids/dirs.js";
+import { landscapePath } from "../../../../core/repo/paths.js";
+import { fleetStatus } from "../../../../core/status/fleet/fleet.js";
+import { ARTIFACT_STATUSES } from "../../../../core/status/report.js";
+import { ANSWERED_BY } from "../../../../core/verify/answers.js";
+import { VERIFICATION_VERDICTS } from "../../../../core/verify/record.js";
+import { maturityRollup } from "../../../../core/vocabulary/maturity.js";
+import { subjectsWith } from "../../../../core/vocabulary/report.js";
+import { featureVerification, serviceViews } from "../../../list/views.js";
+import { drawnSystems } from "../census.js";
+import { readLandscape } from "../load.js";
+import { adoptionOf } from "./adoption.js";
+import { contractCounts } from "./contracts.js";
+/**
+ * Derive the scorecard, or decline. The failure story, per axis: a memoized
+ * read that FAILED rejects again on every await, so the per-service fan-out
+ * contains those per subject — an unreadable service contributes zeros while
+ * its own `service.unreadable` finding names the cause — and every landscape
+ * read goes through `../load.ts`'s containment, so an unreadable fleet map
+ * zeroes the map-derived axes on every platform instead of deleting the card.
+ * The catch is the last line of defence for the fleet-wide reads this module
+ * does not own (the verification cells, the fleet status): a rollup that can
+ * die must not take the graded report with it. No number rather than a wrong
+ * number.
+ */
+export async function buildScorecard(input) {
+    try {
+        return await derive(input);
+    }
+    catch {
+        // Unreadable is not zero: the axes cannot be counted, so no claim is made.
+        return null;
+    }
+}
+async function derive(input) {
+    const { docsDir, targets, fleet, boundService } = input;
+    const services = await fleet.listServices(docsDir);
+    // The landscape, through the run's memo and the fleet target's containment:
+    // an unreadable file grades as one that did not parse, and a landscape that
+    // proves nothing contributes no inbound edges and no element census —
+    // fail-closed, exactly as the no-openapi grace reads the same absence.
+    // Loaded FIRST and handed to serviceViews below, so the maturity rollup
+    // costs no second parse of a document this run already holds.
+    const lp = landscapePath(docsDir);
+    const land = existsSync(lp) ? await readLandscape(() => fleet.loadLikeC4(lp)) : null;
+    const proven = land !== null && land.errors.length === 0;
+    const views = await serviceViews(docsDir, services, boundService, land);
+    const maturity = maturityRollup(views);
+    // Inbound op-linked edges per service, resolved exactly as the API axis
+    // resolves them (service/api.ts): the container-aware resolver, so an edge
+    // drawn into `paymentService.api` counts for the service that owns it.
+    const known = new Set(services.map((s) => s.id));
+    const inbound = new Map();
+    if (proven) {
+        const svcOf = serviceResolver(land.elements, known);
+        for (const r of land.relationships) {
+            if (r.op === undefined)
+                continue;
+            const owner = svcOf(r.target);
+            const ops = inbound.get(owner) ?? new Set();
+            ops.add(r.op);
+            inbound.set(owner, ops);
+        }
+    }
+    // Every read in THIS fan-out is a memo hit — the service targets already
+    // parsed both requirement documents and both contracts — so it spawns no new
+    // filesystem work and needs no pool (unlike the verification fan-out below).
+    const perService = await Promise.all(services.map((svc) => contractCounts(svc, fleet, inbound.get(svc.id) ?? new Set())));
+    const sum = (pick) => perService.reduce((n, c) => n + pick(c), 0);
+    const operations = {
+        defined: sum((c) => c.operations.defined),
+        governed: sum((c) => c.operations.governed),
+        deprecated: sum((c) => c.operations.deprecated),
+        deprecatedStillConsumed: sum((c) => c.operations.deprecatedStillConsumed),
+    };
+    const messages = { defined: sum((c) => c.messages.defined), linked: sum((c) => c.messages.linked) };
+    const adoption = adoptionOf(perService);
+    // C4 coverage: the fleet map's own system census (`drawnSystems` — the set
+    // the undocumented pass walks) against every living arch.spec.md's `Covers:`
+    // entries. Element entries only — an edge entry names no element.
+    const covers = perService.flatMap((c) => c.covers);
+    const eligible = proven ? drawnSystems(land.elements, known) : [];
+    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: 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, fleet));
+    const recorded = cells.filter((c) => c !== null);
+    const verdicts = Object.fromEntries(VERIFICATION_VERDICTS.map((v) => [v, 0]));
+    for (const cell of recorded)
+        verdicts[cell.verdict] += 1;
+    const confirmed = recorded.reduce((n, c) => n + c.confirmed, 0);
+    const answered = Object.fromEntries(ANSWERED_BY.map((who) => [who, recorded.reduce((n, c) => n + c.answered[who], 0)]));
+    // The fleet form of `status`, on this run's own snapshot: presence and
+    // dependency order, nothing graded — the stages an agent already branches on.
+    const status = await fleetStatus(docsDir, { context: fleet });
+    const stages = Object.fromEntries(ARTIFACT_STATUSES.map((s) => [s, 0]));
+    for (const f of status.features)
+        stages[f.stage] += 1;
+    return {
+        services: services.length,
+        maturity,
+        provenance: {
+            vouched: maturity.vouched,
+            // 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).
+            // 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` 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,
+            verdicts,
+            claims: {
+                total: recorded.reduce((n, c) => n + c.claims, 0),
+                confirmed,
+                answered,
+            },
+        },
+        operations,
+        messages,
+        c4: { elements: eligible.length, covered },
+        adoption,
+        features: { active: status.features.length, stages },
+    };
+}
+//# sourceMappingURL=scorecard.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scorecard.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/scorecard/scorecard.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet scorecard: ceiling-vs-actual aggregates for `validate --all`,\n * recomputed per invocation from the same memoized FleetContext reads the run\n * already paid for. loam stores no history — week-over-week tracking is the\n * caller's pipeline's job: capture the `scorecard` payload key per run into a\n * metrics store. Each axis is a pair of domain-named counts (`defined` vs\n * `governed`) rather than abstract ceiling/actual keys, because payload keys\n * freeze the moment they ship and the domain nouns survive axis nuance.\n *\n * This module derives and never prints; `./print.js` renders the one table\n * the `--all` text report appends, and `./contracts.js` owns the per-service\n * contract reads it sums.\n */\nimport { existsSync } from \"node:fs\";\nimport { inOrder } from \"../../../../core/kernel/concurrency.js\";\nimport { coversElement } from \"../../../../core/c4/arch.js\";\nimport { serviceResolver } from \"../../../../core/c4/resolve/service.js\";\nimport { type FleetContext } from \"../../../../core/fleet-context.js\";\nimport { type DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport { landscapePath } from \"../../../../core/repo/paths.js\";\nimport { fleetStatus } from \"../../../../core/status/fleet/fleet.js\";\nimport { ARTIFACT_STATUSES, type ArtifactStatus } from \"../../../../core/status/report.js\";\nimport { ANSWERED_BY, type AnsweredBy } from \"../../../../core/verify/answers.js\";\nimport { VERIFICATION_VERDICTS, type VerificationVerdict } from \"../../../../core/verify/record.js\";\nimport { maturityRollup, type Maturity } from \"../../../../core/vocabulary/maturity.js\";\nimport { subjectsWith, type TargetReport } from \"../../../../core/vocabulary/report.js\";\nimport { featureVerification, serviceViews, type VerificationCell } from \"../../../list/views.js\";\nimport { drawnSystems } from \"../census.js\";\nimport { readLandscape } from \"../load.js\";\nimport { adoptionOf, type Adoption } from \"./adoption.js\";\nimport { contractCounts, type ContractCounts } from \"./contracts.js\";\n\n/** What `buildScorecard` needs of the run that is already in hand. */\nexport interface ScorecardInput {\n  docsDir: DocsDir;\n  /** The run's graded targets — the source for the one count only a repo-bound check can make (`sources.stale` walks the service's own repository, and must not run twice). */\n  targets: TargetReport[];\n  /** The run's memoized snapshot: every read below is a hit on it. */\n  fleet: FleetContext;\n  /** loam.json's `service` — the one repo whose `sources` are checkable from here (serviceViews' rule). */\n  boundService: string | undefined;\n}\n\n/**\n * The additive `scorecard` payload key of `validate --all --json`, and the\n * `--all` text table. Shape frozen on ship, like every payload key: fields\n * may be added, never changed or removed.\n */\nexport interface Scorecard {\n  /** Every `services/` directory the enumeration lists — the maturity rollup's denominator. */\n  services: number;\n  /** Counts per adoption-maturity rung, every rung present (core/vocabulary/maturity.ts). */\n  maturity: Record<Maturity, number>;\n  provenance: {\n    /** Services at the `vouched` rung — a person stamped them. */\n    vouched: number;\n    /**\n     * Of those, the ones where the person read a recorded SAMPLE of the\n     * document rather than all of it, by subject off this run's\n     * `sources.sampled-vouch` findings.\n     *\n     * Additive beside `vouched` rather than subtracted from it, because the\n     * rung is real — a person did stamp it — but a dial reading\n     * `vouched: 120` where 100 of them are sampled is exactly the\n     * partial-trust-as-full-trust misreading the scope exists to prevent. A\n     * dashboard that wants the stricter number subtracts this one knowingly.\n     */\n    sampledVouched: number;\n    /**\n     * Services whose stamped sources digest no longer matches the code, by\n     * subject off this run's `sources.stale` findings — only what THIS run\n     * could verify, so read it beside the count below, never alone.\n     */\n    staleDigests: number;\n    /** Services whose declared `sources` only their own repos can check. */\n    unverifiableFromHere: number;\n    /**\n     * Services with a stamped document whose WORDS moved after the vouch, by\n     * subject off this run's `content.stale` findings. The doc-side half of\n     * staleness, so unlike `staleDigests` it is complete from the docs repo —\n     * and its absence was the scorecard saying \"1 vouched — 0 stale\" in the\n     * same run that warned `content.stale` one line above it. Additive beside\n     * `vouched` for `sampledVouched`'s reason.\n     */\n    contentStale: number;\n  };\n  verification: {\n    /**\n     * Active features with a verification record beside them. Its ceiling is\n     * `features.active` — deliberately not repeated here: one denominator,\n     * derived once, so the two axes cannot disagree about how many features\n     * are in flight.\n     */\n    recorded: number;\n    /** The recorded features' three-valued verdicts (core/verify/record.ts), every key present. */\n    verdicts: Record<VerificationVerdict, number>;\n    claims: {\n      /** Questions asked across every recorded feature, `tallyRecord`'s counting. */\n      total: number;\n      confirmed: number;\n      /**\n       * Of the confirmed, one count per `answered_by` value (`ANSWERED_BY`),\n       * every key present — the stable-shape rule `verdicts` and `stages`\n       * follow, so a fourth provenance would appear rather than be absorbed.\n       *\n       * Read off the answers' own provenance, never by subtracting the\n       * attested share: `attestedClaims` counts `scenario.tested` alone, so\n       * `confirmed - attested` filed every OTHER kind an agent confirmed — a\n       * permission, a capability, an exposed operation — under a test runner\n       * that had not run. A record with four agent answers printed as three\n       * runner and one agent, which is the reading this axis exists to give.\n       */\n      answered: Record<AnsweredBy, number>;\n    };\n  };\n  /**\n   * The HTTP axis, with a deliberate UNIT split: `defined`/`governed` count\n   * contract SLOTS, exactly as the API axis's own findings count operations,\n   * while `deprecated`/`deprecatedStillConsumed` count DISTINCT operationIds —\n   * a duplicate-id slot pair (already its own warning) retires as ONE\n   * operation, one migration owed.\n   */\n  operations: {\n    /** Slots the living contracts define (removal markers are never operations). */\n    defined: number;\n    /** Slots (like `defined`) whose id a living requirement's `Operations:` line governs. */\n    governed: number;\n    /** Distinct deprecated operationIds. */\n    deprecated: number;\n    /** Distinct deprecated ids something still joins to — a living `Operations:` line, or an op-linked inbound landscape edge. */\n    deprecatedStillConsumed: number;\n  };\n  messages: {\n    /** Distinct message names the living async contracts declare. */\n    defined: number;\n    /** Of them, the ones a requirement's `Publishes:`/`Consumes:` line governs. */\n    linked: number;\n  };\n  c4: {\n    /** The drawn SYSTEMS — `drawnSystems`, the fleet map's own census, so the map's exemptions (actors, INFRA kinds the fleet runs rather than adopts, `#external`, groupings, containers) and this count cannot drift. An INFRA-kind element that DOES stand for a `services/<id>/` stays in, so adopting a store never shrinks the denominator. */\n    elements: number;\n    /** Of them, the ones some living arch requirement's `Covers:` entry names. */\n    covered: number;\n  };\n  /**\n   * Services PARTICIPATING in each contract axis — how far the staged\n   * adoption has spread, axis by axis. The denominator is `services`, carried\n   * once above like every other denominator here. One mechanical rule per\n   * axis, per service: `requirements` — spec.md holds at least one\n   * `### Requirement:` block (content, not file presence, so a fleet of empty\n   * adopt scaffolds honestly reads \"not started\"); `arch` — the same for\n   * arch.spec.md; `openapi` / `asyncapi` — the contract file exists;\n   * `permissions` / `capabilities` — at least one non-REMOVED requirement in\n   * either spec document carries a `Requires:` / `Capability:` entry (the\n   * used-set rule the fleet vocabulary checks apply). An axis at 0 is \"not\n   * started\" — distinct from partially adopted — and is what licenses the\n   * text report's per-axis warning banner (./adoption.js). An unreadable\n   * service counts as participating in nothing, the same zeros doctrine as\n   * every count here — read these beside the run's `service.unreadable`\n   * findings, and note the text renderer refuses to group warnings on a run\n   * that has any (report.ts).\n   */\n  adoption: Adoption;\n  features: {\n    active: number;\n    /**\n     * The fleet form's stage per active feature — all five ARTIFACT_STATUSES\n     * keys even though that form never grades `draft` (the maturityRollup\n     * rule: a stable shape a dashboard can diff).\n     */\n    stages: Record<ArtifactStatus, number>;\n  };\n}\n\n/**\n * Derive the scorecard, or decline. The failure story, per axis: a memoized\n * read that FAILED rejects again on every await, so the per-service fan-out\n * contains those per subject — an unreadable service contributes zeros while\n * its own `service.unreadable` finding names the cause — and every landscape\n * read goes through `../load.ts`'s containment, so an unreadable fleet map\n * zeroes the map-derived axes on every platform instead of deleting the card.\n * The catch is the last line of defence for the fleet-wide reads this module\n * does not own (the verification cells, the fleet status): a rollup that can\n * die must not take the graded report with it. No number rather than a wrong\n * number.\n */\nexport async function buildScorecard(input: ScorecardInput): Promise<Scorecard | null> {\n  try {\n    return await derive(input);\n  } catch {\n    // Unreadable is not zero: the axes cannot be counted, so no claim is made.\n    return null;\n  }\n}\n\nasync function derive(input: ScorecardInput): Promise<Scorecard> {\n  const { docsDir, targets, fleet, boundService } = input;\n  const services = await fleet.listServices(docsDir);\n\n  // The landscape, through the run's memo and the fleet target's containment:\n  // an unreadable file grades as one that did not parse, and a landscape that\n  // proves nothing contributes no inbound edges and no element census —\n  // fail-closed, exactly as the no-openapi grace reads the same absence.\n  // Loaded FIRST and handed to serviceViews below, so the maturity rollup\n  // costs no second parse of a document this run already holds.\n  const lp = landscapePath(docsDir);\n  const land = existsSync(lp) ? await readLandscape(() => fleet.loadLikeC4(lp)) : null;\n  const proven = land !== null && land.errors.length === 0;\n\n  const views = await serviceViews(docsDir, services, boundService, land);\n  const maturity = maturityRollup(views);\n\n  // Inbound op-linked edges per service, resolved exactly as the API axis\n  // resolves them (service/api.ts): the container-aware resolver, so an edge\n  // drawn into `paymentService.api` counts for the service that owns it.\n  const known: ReadonlySet<string> = new Set(services.map((s) => s.id));\n  const inbound = new Map<string, Set<string>>();\n  if (proven) {\n    const svcOf = serviceResolver(land.elements, known);\n    for (const r of land.relationships) {\n      if (r.op === undefined) continue;\n      const owner: string = svcOf(r.target);\n      const ops = inbound.get(owner) ?? new Set<string>();\n      ops.add(r.op);\n      inbound.set(owner, ops);\n    }\n  }\n\n  // Every read in THIS fan-out is a memo hit — the service targets already\n  // parsed both requirement documents and both contracts — so it spawns no new\n  // filesystem work and needs no pool (unlike the verification fan-out below).\n  const perService = await Promise.all(\n    services.map((svc) => contractCounts(svc, fleet, inbound.get(svc.id) ?? new Set<string>())),\n  );\n  const sum = (pick: (c: ContractCounts) => number): number =>\n    perService.reduce((n, c) => n + pick(c), 0);\n  const operations = {\n    defined: sum((c) => c.operations.defined),\n    governed: sum((c) => c.operations.governed),\n    deprecated: sum((c) => c.operations.deprecated),\n    deprecatedStillConsumed: sum((c) => c.operations.deprecatedStillConsumed),\n  };\n  const messages = { defined: sum((c) => c.messages.defined), linked: sum((c) => c.messages.linked) };\n  const adoption = adoptionOf(perService);\n\n  // C4 coverage: the fleet map's own system census (`drawnSystems` — the set\n  // the undocumented pass walks) against every living arch.spec.md's `Covers:`\n  // entries. Element entries only — an edge entry names no element.\n  const covers = perService.flatMap((c) => c.covers);\n  const eligible = proven ? drawnSystems(land.elements, known) : [];\n  const covered = eligible.filter((e) => covers.some((c) => coversElement(c, e))).length;\n\n  // Verification: `list`'s own cells, so the two commands cannot disagree\n  // about a record's verdict. Active features only — an archived record is\n  // frozen history, not fleet debt. This fan-out is NOT memo hits: reading a\n  // feature's record is a directory listing plus a small read per record file\n  // (the one-file `verification.yaml` and one `verification/<svc>.yaml` per\n  // attesting service), and a recorded cell additionally derives its checklist\n  // (the same cost `list` pays for the same column; only its enumerations and\n  // delta parse are memo hits through `fleet`) — real filesystem work, so it\n  // runs through the bounded pool.\n  const features = await fleet.listFeatures(docsDir);\n  const cells = await inOrder(features, (f) => featureVerification(docsDir, f, fleet));\n  const recorded = cells.filter((c): c is VerificationCell => c !== null);\n  const verdicts = Object.fromEntries(VERIFICATION_VERDICTS.map((v) => [v, 0])) as Record<VerificationVerdict, number>;\n  for (const cell of recorded) verdicts[cell.verdict] += 1;\n  const confirmed = recorded.reduce((n, c) => n + c.confirmed, 0);\n  const answered = Object.fromEntries(\n    ANSWERED_BY.map((who) => [who, recorded.reduce((n, c) => n + c.answered[who], 0)]),\n  ) as Record<AnsweredBy, number>;\n\n  // The fleet form of `status`, on this run's own snapshot: presence and\n  // dependency order, nothing graded — the stages an agent already branches on.\n  const status = await fleetStatus(docsDir, { context: fleet });\n  const stages = Object.fromEntries(ARTIFACT_STATUSES.map((s) => [s, 0])) as Record<ArtifactStatus, number>;\n  for (const f of status.features) stages[f.stage] += 1;\n\n  return {\n    services: services.length,\n    maturity,\n    provenance: {\n      vouched: maturity.vouched,\n      // Every count joins through `subjectsWith` on the run's OWN findings, so\n      // each is structurally the same number as the report beside it — the\n      // unverifiable count is the footer's (unverifiableSubjects is the same\n      // call on the same code; this package cannot import the parent back).\n      // Every code is a LITERAL — the emitter's own spelling — because the\n      // stable-code collector reads counting sites and refuses a slot it\n      // cannot read; the collector is also what convicts a typo here.\n      staleDigests: subjectsWith(targets, \"sources.stale\"),\n      unverifiableFromHere: subjectsWith(targets, \"sources.unverifiable-from-here\"),\n      // Doc-side, so unlike `staleDigests` these two are complete even from\n      // the docs repo: neither `sources.sampled-vouch` nor `content.stale`\n      // needs a service repo to fire. `content.stale` names no subject, and\n      // `subjectsWith` falls back to the target id — the service, here.\n      sampledVouched: subjectsWith(targets, \"sources.sampled-vouch\"),\n      contentStale: subjectsWith(targets, \"content.stale\"),\n    },\n    verification: {\n      recorded: recorded.length,\n      verdicts,\n      claims: {\n        total: recorded.reduce((n, c) => n + c.claims, 0),\n        confirmed,\n        answered,\n      },\n    },\n    operations,\n    messages,\n    c4: { elements: eligible.length, covered },\n    adoption,\n    features: { active: status.features.length, stages },\n  };\n}\n"]}

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

@@ -0,0 +1,13 @@
+import { viewFile } from "../../../../core/usecases/place.js";
+/**
+ * The opening of every finding in this family:
+ * `landscape: architecture/usecases/checkout.likec4 — dynamic view 'uc_checkout'`.
+ *
+ * The `landscape:` prefix is the TARGET's name, not a file reference — every
+ * finding filed on the fleet target carries it, and `landscape.invalid` already
+ * sets the precedent of naming another document right after it.
+ */
+export function viewPlace(view) {
+    return `landscape: ${viewFile(view)} — dynamic view '${view.id}'`;
+}
+//# sourceMappingURL=place.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"place.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/usecases/place.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,IAAgB;IACxC,OAAO,cAAc,QAAQ,CAAC,IAAI,CAAC,oBAAoB,IAAI,CAAC,EAAE,GAAG,CAAC;AACpE,CAAC","sourcesContent":["/**\n * Where a use-case FINDING points: the validate target it is filed against, the\n * document the view was written in, and the view itself.\n *\n * The fleet target's `landscape:` prefix, kept as command vocabulary when the\n * graders moved to `core/usecases/grade/` (`core/usecases/place.ts` says why):\n * every grader there takes the place as an argument, and\n * `../map/usecases.ts` hands them this one. It began as a leaf module beside\n * the graders it served, for the leaf-helper-stranded-in-a-heavier-module\n * reason docs/CODE-STYLE.md names as the cause of every import cycle this\n * repository has carried.\n *\n * NAMING THE FILE IS THE WHOLE SUBJECT. `validate --all` reads `architecture/`\n * as ONE LikeC4 project, so a `dynamic view` may have been written in\n * `architecture/landscape.likec4` or in any `architecture/usecases/*.likec4`,\n * and the project is what merges them. A message that named the landscape by\n * default would send its author to a file that does not contain the view — the\n * same defect `landscape.invalid`'s message was corrected for when the project\n * loader landed, arriving again one axis later.\n *\n * `viewFile` and `stepPlace` themselves moved to `core/usecases/place.ts` once\n * `loam diff`, `loam delta` and `loam context` became readers too; that module's\n * banner records why, and why the `landscape:` prefix below stayed here.\n */\nimport type { ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport { viewFile } from \"../../../../core/usecases/place.js\";\n\n/**\n * The opening of every finding in this family:\n * `landscape: architecture/usecases/checkout.likec4 — dynamic view 'uc_checkout'`.\n *\n * The `landscape:` prefix is the TARGET's name, not a file reference — every\n * finding filed on the fleet target carries it, and `landscape.invalid` already\n * sets the precedent of naming another document right after it.\n */\nexport function viewPlace(view: ParsedView): string {\n  return `landscape: ${viewFile(view)} — dynamic view '${view.id}'`;\n}\n"]}