@ybotok/loam 0.1.0-beta.2 → 0.2.0-alpha.1

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

@@ -0,0 +1,156 @@
+/**
+ * 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:
+    // 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.
+    const features = await fleet.listFeatures(docsDir);
+    const cells = await inOrder(features, (f) => featureVerification(docsDir, f));
+    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,
+            // Both counts join 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.
+            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.
+            sampledVouched: subjectsWith(targets, "sources.sampled-vouch"),
+        },
+        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  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, `#external`, groupings, containers) and this count cannot drift. */\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:\n  // readVerification is one small file read per feature, and a recorded cell\n  // additionally derives its checklist (the same cost `list` pays for the same\n  // column) — real filesystem work, so it runs through the bounded pool.\n  const features = await fleet.listFeatures(docsDir);\n  const cells = await inOrder(features, (f) => featureVerification(docsDir, f));\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      // Both counts join 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      // Both codes are LITERALS — provenance/sources.ts's own spellings —\n      // because the stable-code collector reads counting sites and refuses a\n      // slot it 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` this one is complete even from the\n      // docs repo: `sources.sampled-vouch` needs no service repo to fire.\n      sampledVouched: subjectsWith(targets, \"sources.sampled-vouch\"),\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/capability-tag.js

@@ -0,0 +1,94 @@
+/**
+ * `usecase.capability-unresolved` — the `#cap-` tag that names no declared
+ * capability, or more than one.
+ *
+ * The join itself lives in `core/capabilities/usecase-join.ts` and none of it is
+ * repeated here: this module owns the grade and the sentence, nothing else. That
+ * split is why the tag can answer "many" at all — the slug is not injective, so
+ * `payments/refunds` and `payments-refunds` both flatten to
+ * `payments-refunds` — and why the close candidates a message offers are real
+ * declared ids rather than loam's flattened spelling of them.
+ *
+ * ERROR, the same grade `capability.unknown` carries on a `Capability:` line and
+ * for its reason: an invented capability reads exactly like a real one. Here it
+ * reads that way at flow altitude — the tag is what files a whole business
+ * sequence under an owner, so a claim that resolves to nothing produces a use
+ * case nobody can find and a capability nobody can see is realized.
+ *
+ * SUPPRESSED ENTIRELY when the vocabulary is absent or unreadable: the caller
+ * resolves no claims at all in that case, so this answers with nothing. The
+ * claims are RESOLVED BY THE CALLER rather than here because the `#req-` grade
+ * beside this one is scoped by the very same verdicts, and two resolutions of
+ * one view's tags are two chances to disagree about which capability a flow is
+ * about. The ladder that produces the suppressing `null` is
+ * `gradableCapabilityIds` in `core/capabilities/findings.ts` — one function, called by every site that needs the graded id list, this module's
+ * caller in `../landscape.ts` included. The FILE is this axis's opt-in, so a
+ * fleet with no `architecture/capabilities.yaml` produces no capability finding
+ * at all, and an unreadable one is `capability.invalid` alone rather than one
+ * unresolved tag per use case in the fleet, which is a cascade and not a
+ * diagnosis. That rule is not re-decided here: a second reading of
+ * `CapabilityVocabulary` anywhere in this package is the copy that goes stale
+ * the day a fourth un-gradable state is added, so call the function.
+ */
+import { CAP_TAG_PREFIX, tagSlug, } from "../../../../core/capabilities/usecase-join.js";
+import { viewPlace } from "./place.js";
+/** A capability id as an author must write it in a tag: `identity/tokens (#cap-identity-tokens)`. */
+function idAndTag(id) {
+    return `${id} (#${CAP_TAG_PREFIX}${tagSlug(id)})`;
+}
+/**
+ * A tag nothing declares, with the close names spelled as TAGS as well as ids.
+ *
+ * Both spellings, because either alone sends the author somewhere wrong: the id
+ * is what `capabilities.yaml` holds and the tag is what the view must carry, and
+ * an author handed only `identity/tokens` writes `#cap-identity/tokens`, which
+ * LikeC4 refuses to parse. The flattening rule is stated in the same breath so
+ * the reader can derive the next one without being told again.
+ */
+function noneMessage(view, claim) {
+    const hint = claim.close.length > 0
+        ? `Did you mean: ${claim.close.map(idAndTag).join(", ")}?`
+        : "Declare it there (`capabilities: {<id>: {description, owner}}`), or fix the tag.";
+    return (`${viewPlace(view)} is tagged #${claim.tag}, and no capability declared in ` +
+        `architecture/capabilities.yaml flattens to '${claim.slug}'. ${hint} ` +
+        "A tag spells the id with every character outside `[A-Za-z0-9_-]` flattened to `-`, because that is all a LikeC4 tag name accepts.");
+}
+/**
+ * A tag two or more declared ids answer to. Every colliding id is named — a
+ * message that stopped at the first would be reporting the ambiguity while
+ * hiding half of what makes it one.
+ */
+function manyMessage(view, claim) {
+    return (`${viewPlace(view)} is tagged #${claim.tag}, and ${claim.ids.length} declared capabilities flatten to ` +
+        `'${claim.slug}' (${claim.ids.join(", ")}) — nothing in the tag can say which one this use case realizes. ` +
+        "Rename one of them in architecture/capabilities.yaml: a guessed capability files every hop of the flow, " +
+        "and every rollup built over it, under an owner who never claimed it — and the wrong answer looks exactly " +
+        "like the right one.");
+}
+/**
+ * One finding per `#cap-` tag that does not resolve — never one per view.
+ *
+ * A view may legitimately carry two capability tags (a checkout flow that also
+ * issues the identity token realizes both), and `resolveCapabilityTags` answers
+ * each on its own terms for that reason. Collapsing them here would either
+ * swallow a broken tag beside a working one or lose the capability the view
+ * genuinely does realize; one tag, one verdict, one finding keeps both facts.
+ */
+export function capabilityTagFindings(view, claims) {
+    const findings = [];
+    for (const claim of claims) {
+        if (claim.kind === "resolved")
+            continue;
+        findings.push({
+            severity: "error",
+            code: "usecase.capability-unresolved",
+            // The VIEW, not the tag: a subject is what a reader goes and opens, and
+            // `subjectsWith` counts one broken use case once however many of its tags
+            // are wrong.
+            subject: view.id,
+            message: claim.kind === "none" ? noneMessage(view, claim) : manyMessage(view, claim),
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=capability-tag.js.map

package/dist/commands/validate/fleet/usecases/capability-tag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-tag.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/usecases/capability-tag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EACL,cAAc,EACd,OAAO,GAER,MAAM,+CAA+C,CAAC;AAGvD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,qGAAqG;AACrG,SAAS,QAAQ,CAAC,EAAU;IAC1B,OAAO,GAAG,EAAE,MAAM,cAAc,GAAG,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC;AACpD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,WAAW,CAAC,IAAgB,EAAE,KAAiD;IACtF,MAAM,IAAI,GACR,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;QACpB,CAAC,CAAC,iBAAiB,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QAC1D,CAAC,CAAC,kFAAkF,CAAC;IACzF,OAAO,CACL,GAAG,SAAS,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,GAAG,kCAAkC;QAC5E,+CAA+C,KAAK,CAAC,IAAI,MAAM,IAAI,GAAG;QACtE,mIAAmI,CACpI,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,IAAgB,EAAE,KAAiD;IACtF,OAAO,CACL,GAAG,SAAS,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,CAAC,MAAM,oCAAoC;QACvG,IAAI,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,mEAAmE;QAC3G,0GAA0G;QAC1G,2GAA2G;QAC3G,qBAAqB,CACtB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAgB,EAAE,MAAkC;IACxF,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;YAAE,SAAS;QACxC,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,+BAA+B;YACrC,wEAAwE;YACxE,0EAA0E;YAC1E,aAAa;YACb,OAAO,EAAE,IAAI,CAAC,EAAE;YAChB,OAAO,EAAE,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC;SACrF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * `usecase.capability-unresolved` — the `#cap-` tag that names no declared\n * capability, or more than one.\n *\n * The join itself lives in `core/capabilities/usecase-join.ts` and none of it is\n * repeated here: this module owns the grade and the sentence, nothing else. That\n * split is why the tag can answer \"many\" at all — the slug is not injective, so\n * `payments/refunds` and `payments-refunds` both flatten to\n * `payments-refunds` — and why the close candidates a message offers are real\n * declared ids rather than loam's flattened spelling of them.\n *\n * ERROR, the same grade `capability.unknown` carries on a `Capability:` line and\n * for its reason: an invented capability reads exactly like a real one. Here it\n * reads that way at flow altitude — the tag is what files a whole business\n * sequence under an owner, so a claim that resolves to nothing produces a use\n * case nobody can find and a capability nobody can see is realized.\n *\n * SUPPRESSED ENTIRELY when the vocabulary is absent or unreadable: the caller\n * resolves no claims at all in that case, so this answers with nothing. The\n * claims are RESOLVED BY THE CALLER rather than here because the `#req-` grade\n * beside this one is scoped by the very same verdicts, and two resolutions of\n * one view's tags are two chances to disagree about which capability a flow is\n * about. The ladder that produces the suppressing `null` is\n * `gradableCapabilityIds` in `core/capabilities/findings.ts` — one function, called by every site that needs the graded id list, this module's\n * caller in `../landscape.ts` included. The FILE is this axis's opt-in, so a\n * fleet with no `architecture/capabilities.yaml` produces no capability finding\n * at all, and an unreadable one is `capability.invalid` alone rather than one\n * unresolved tag per use case in the fleet, which is a cascade and not a\n * diagnosis. That rule is not re-decided here: a second reading of\n * `CapabilityVocabulary` anywhere in this package is the copy that goes stale\n * the day a fourth un-gradable state is added, so call the function.\n */\nimport {\n  CAP_TAG_PREFIX,\n  tagSlug,\n  type CapabilityClaim,\n} from \"../../../../core/capabilities/usecase-join.js\";\nimport type { ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { viewPlace } from \"./place.js\";\n\n/** A capability id as an author must write it in a tag: `identity/tokens (#cap-identity-tokens)`. */\nfunction idAndTag(id: string): string {\n  return `${id} (#${CAP_TAG_PREFIX}${tagSlug(id)})`;\n}\n\n/**\n * A tag nothing declares, with the close names spelled as TAGS as well as ids.\n *\n * Both spellings, because either alone sends the author somewhere wrong: the id\n * is what `capabilities.yaml` holds and the tag is what the view must carry, and\n * an author handed only `identity/tokens` writes `#cap-identity/tokens`, which\n * LikeC4 refuses to parse. The flattening rule is stated in the same breath so\n * the reader can derive the next one without being told again.\n */\nfunction noneMessage(view: ParsedView, claim: Extract<CapabilityClaim, { kind: \"none\" }>): string {\n  const hint =\n    claim.close.length > 0\n      ? `Did you mean: ${claim.close.map(idAndTag).join(\", \")}?`\n      : \"Declare it there (`capabilities: {<id>: {description, owner}}`), or fix the tag.\";\n  return (\n    `${viewPlace(view)} is tagged #${claim.tag}, and no capability declared in ` +\n    `architecture/capabilities.yaml flattens to '${claim.slug}'. ${hint} ` +\n    \"A tag spells the id with every character outside `[A-Za-z0-9_-]` flattened to `-`, because that is all a LikeC4 tag name accepts.\"\n  );\n}\n\n/**\n * A tag two or more declared ids answer to. Every colliding id is named — a\n * message that stopped at the first would be reporting the ambiguity while\n * hiding half of what makes it one.\n */\nfunction manyMessage(view: ParsedView, claim: Extract<CapabilityClaim, { kind: \"many\" }>): string {\n  return (\n    `${viewPlace(view)} is tagged #${claim.tag}, and ${claim.ids.length} declared capabilities flatten to ` +\n    `'${claim.slug}' (${claim.ids.join(\", \")}) — nothing in the tag can say which one this use case realizes. ` +\n    \"Rename one of them in architecture/capabilities.yaml: a guessed capability files every hop of the flow, \" +\n    \"and every rollup built over it, under an owner who never claimed it — and the wrong answer looks exactly \" +\n    \"like the right one.\"\n  );\n}\n\n/**\n * One finding per `#cap-` tag that does not resolve — never one per view.\n *\n * A view may legitimately carry two capability tags (a checkout flow that also\n * issues the identity token realizes both), and `resolveCapabilityTags` answers\n * each on its own terms for that reason. Collapsing them here would either\n * swallow a broken tag beside a working one or lose the capability the view\n * genuinely does realize; one tag, one verdict, one finding keeps both facts.\n */\nexport function capabilityTagFindings(view: ParsedView, claims: readonly CapabilityClaim[]): Finding[] {\n  const findings: Finding[] = [];\n  for (const claim of claims) {\n    if (claim.kind === \"resolved\") continue;\n    findings.push({\n      severity: \"error\",\n      code: \"usecase.capability-unresolved\",\n      // The VIEW, not the tag: a subject is what a reader goes and opens, and\n      // `subjectsWith` counts one broken use case once however many of its tags\n      // are wrong.\n      subject: view.id,\n      message: claim.kind === \"none\" ? noneMessage(view, claim) : manyMessage(view, claim),\n    });\n  }\n  return findings;\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":"AAsBA,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 * A leaf module rather than another export on `./usecases.ts`, because both\n * graders in this package need it while the entry module imports both of them —\n * the leaf-helper-stranded-in-a-heavier-module shape docs/CODE-STYLE.md names as\n * the cause of every import cycle this 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"]}

package/dist/commands/validate/fleet/usecases/requirement-tag.js

@@ -0,0 +1,95 @@
+/**
+ * `usecase.requirement-unresolved` — the `#req-` tag that names no requirement
+ * of the capability the view is about.
+ *
+ * The join lives in `core/capabilities/usecase-join.ts` and none of it is
+ * repeated here: this module owns the grade and the sentences. Six arms, six
+ * fixes, and they are deliberately the same vocabulary
+ * `capability.realizes-unknown` uses for the OTHER carrier of this claim — an
+ * author who has learned one set of messages has learned both.
+ *
+ * ERROR, for `usecase.capability-unresolved`'s reason one join deeper: the tag
+ * is the architect's claim that a flow satisfies a named business promise, and a
+ * claim that resolves to nothing reads exactly like one that does — in the view,
+ * in review, and to anyone asking which flow keeps that promise.
+ *
+ * AN UNRESOLVED CLAIM SUPPRESSES NOTHING. `capability.requirement-unrealized`
+ * counts only RESOLVED claims, so a typo'd `#req-` tag leaves the requirement
+ * reported as realized by nobody — which is the truth, and is exactly what a
+ * broken claim should not be able to hide. The two findings arriving together is
+ * the intended reading: one says the tag is wrong, the other says the promise is
+ * still unkept.
+ */
+import { REQ_TAG_PREFIX, tagSlug, resolveRequirementTags, } from "../../../../core/capabilities/usecase-join.js";
+import { viewPlace } from "./place.js";
+/** A `Requirement-ID` as an author must write it in a tag: `CHK.ONCE (#req-CHK-ONCE)`. */
+function idAndTag(id) {
+    return `${id} (#${REQ_TAG_PREFIX}${tagSlug(id)})`;
+}
+/**
+ * The fix for one unresolved claim. The `unscoped` arm splits in two on the
+ * count, because none and several are opposite mistakes: one author forgot to
+ * say which capability, the other said two and left the id homeless.
+ */
+function advice(claim) {
+    switch (claim.kind) {
+        case "unscoped":
+            return claim.capabilities.length === 0
+                ? "the view carries no `#cap-` tag that resolves to a declared capability, and a `Requirement-ID` is " +
+                    "unique only inside its own document — so there is nothing for this id to be looked up in. " +
+                    "Add the `#cap-<slug>` tag naming the capability this flow is about."
+                : `the view resolves ${claim.capabilities.length} capabilities (${claim.capabilities.join(", ")}), ` +
+                    "so nothing says which document the id belongs to. A flow realizing promises from two capabilities " +
+                    "needs one `#req-` tag per capability to be unambiguous, which the tag grammar cannot express — " +
+                    "split the flow, or drop the `#req-` tag and let `Realizes:` on the service requirements carry it.";
+        case "undocumented":
+            return (`capability '${claim.capability}' is declared but has no capabilities/${claim.capability}/spec.md, ` +
+                "so it carries no requirements to satisfy. Write the document — a name alone can be claimed with " +
+                "`#cap-`, but only a document has promises a flow can keep.");
+        case "empty":
+            return (`capabilities/${claim.capability}/spec.md exists and declares no requirements yet — ` +
+                "add the `## Requirements` section, each requirement carrying its `Requirement-ID:`.");
+        case "none":
+            return claim.close.length > 0
+                ? `capabilities/${claim.capability}/spec.md declares no requirement flattening to '${claim.slug}'. ` +
+                    `Did you mean: ${claim.close.map(idAndTag).join(", ")}?`
+                : `capabilities/${claim.capability}/spec.md declares no requirement flattening to '${claim.slug}' — ` +
+                    "check the `Requirement-ID:` lines in that document.";
+        default:
+            return (`${claim.ids.length} requirements of '${claim.capability}' flatten to '${claim.slug}' ` +
+                `(${claim.ids.join(", ")}) — nothing in the tag can say which promise this flow keeps. ` +
+                "Rename one of them: a guessed requirement reports the wrong promise as kept and the right one as " +
+                "unimplemented, and both answers look exactly like the truth.");
+    }
+}
+/**
+ * One finding per `#req-` tag that does not resolve — never one per view.
+ *
+ * Several `#req-` tags on one view are legal and normal: a checkout flow that
+ * charges once AND honours the price keeps two promises, and there is no honest
+ * way to make its author pick one. So a broken tag beside a working one must
+ * neither swallow the break nor lose the promise the view genuinely does keep.
+ *
+ * `claims` is the view's OWN capability verdicts, already resolved by the
+ * caller — passed rather than recomputed so the scope this grade uses and the
+ * scope `capabilityTagFindings` graded are the same list, and an unresolved
+ * `#cap-` tag cannot silently scope a requirement lookup.
+ */
+export function requirementTagFindings(view, claims, requirementsOf) {
+    const scope = claims.flatMap((claim) => (claim.kind === "resolved" ? [claim.id] : []));
+    const findings = [];
+    for (const claim of resolveRequirementTags(view.tags, scope, requirementsOf)) {
+        if (claim.kind === "resolved")
+            continue;
+        findings.push({
+            severity: "error",
+            code: "usecase.requirement-unresolved",
+            // The VIEW, not the tag — a subject is what a reader goes and opens, and
+            // one broken use case counts once however many of its tags are wrong.
+            subject: view.id,
+            message: `${viewPlace(view)} is tagged #${claim.tag}, and it does not resolve: ${advice(claim)}`,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=requirement-tag.js.map

package/dist/commands/validate/fleet/usecases/requirement-tag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-tag.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/usecases/requirement-tag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,cAAc,EACd,OAAO,EACP,sBAAsB,GAGvB,MAAM,+CAA+C,CAAC;AAGvD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,0FAA0F;AAC1F,SAAS,QAAQ,CAAC,EAAU;IAC1B,OAAO,GAAG,EAAE,MAAM,cAAc,GAAG,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,SAAS,MAAM,CAAC,KAAsD;IACpE,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,UAAU;YACb,OAAO,KAAK,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC;gBACpC,CAAC,CAAC,oGAAoG;oBAClG,4FAA4F;oBAC5F,qEAAqE;gBACzE,CAAC,CAAC,qBAAqB,KAAK,CAAC,YAAY,CAAC,MAAM,kBAAkB,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;oBAChG,oGAAoG;oBACpG,iGAAiG;oBACjG,mGAAmG,CAAC;QAC5G,KAAK,cAAc;YACjB,OAAO,CACL,eAAe,KAAK,CAAC,UAAU,yCAAyC,KAAK,CAAC,UAAU,YAAY;gBACpG,kGAAkG;gBAClG,4DAA4D,CAC7D,CAAC;QACJ,KAAK,OAAO;YACV,OAAO,CACL,gBAAgB,KAAK,CAAC,UAAU,qDAAqD;gBACrF,qFAAqF,CACtF,CAAC;QACJ,KAAK,MAAM;YACT,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBAC3B,CAAC,CAAC,gBAAgB,KAAK,CAAC,UAAU,mDAAmD,KAAK,CAAC,IAAI,KAAK;oBAChG,iBAAiB,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBAC5D,CAAC,CAAC,gBAAgB,KAAK,CAAC,UAAU,mDAAmD,KAAK,CAAC,IAAI,MAAM;oBACjG,qDAAqD,CAAC;QAC9D;YACE,OAAO,CACL,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,qBAAqB,KAAK,CAAC,UAAU,iBAAiB,KAAK,CAAC,IAAI,IAAI;gBACvF,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,gEAAgE;gBACxF,mGAAmG;gBACnG,8DAA8D,CAC/D,CAAC;IACN,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAgB,EAChB,MAAkC,EAClC,cAAuE;IAEvE,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACvF,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,cAAc,CAAC,EAAE,CAAC;QAC7E,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;YAAE,SAAS;QACxC,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,gCAAgC;YACtC,yEAAyE;YACzE,sEAAsE;YACtE,OAAO,EAAE,IAAI,CAAC,EAAE;YAChB,OAAO,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,GAAG,8BAA8B,MAAM,CAAC,KAAK,CAAC,EAAE;SACjG,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * `usecase.requirement-unresolved` — the `#req-` tag that names no requirement\n * of the capability the view is about.\n *\n * The join lives in `core/capabilities/usecase-join.ts` and none of it is\n * repeated here: this module owns the grade and the sentences. Six arms, six\n * fixes, and they are deliberately the same vocabulary\n * `capability.realizes-unknown` uses for the OTHER carrier of this claim — an\n * author who has learned one set of messages has learned both.\n *\n * ERROR, for `usecase.capability-unresolved`'s reason one join deeper: the tag\n * is the architect's claim that a flow satisfies a named business promise, and a\n * claim that resolves to nothing reads exactly like one that does — in the view,\n * in review, and to anyone asking which flow keeps that promise.\n *\n * AN UNRESOLVED CLAIM SUPPRESSES NOTHING. `capability.requirement-unrealized`\n * counts only RESOLVED claims, so a typo'd `#req-` tag leaves the requirement\n * reported as realized by nobody — which is the truth, and is exactly what a\n * broken claim should not be able to hide. The two findings arriving together is\n * the intended reading: one says the tag is wrong, the other says the promise is\n * still unkept.\n */\nimport {\n  REQ_TAG_PREFIX,\n  tagSlug,\n  resolveRequirementTags,\n  type CapabilityClaim,\n  type RequirementClaim,\n} from \"../../../../core/capabilities/usecase-join.js\";\nimport type { ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { viewPlace } from \"./place.js\";\n\n/** A `Requirement-ID` as an author must write it in a tag: `CHK.ONCE (#req-CHK-ONCE)`. */\nfunction idAndTag(id: string): string {\n  return `${id} (#${REQ_TAG_PREFIX}${tagSlug(id)})`;\n}\n\n/**\n * The fix for one unresolved claim. The `unscoped` arm splits in two on the\n * count, because none and several are opposite mistakes: one author forgot to\n * say which capability, the other said two and left the id homeless.\n */\nfunction advice(claim: Exclude<RequirementClaim, { kind: \"resolved\" }>): string {\n  switch (claim.kind) {\n    case \"unscoped\":\n      return claim.capabilities.length === 0\n        ? \"the view carries no `#cap-` tag that resolves to a declared capability, and a `Requirement-ID` is \" +\n            \"unique only inside its own document — so there is nothing for this id to be looked up in. \" +\n            \"Add the `#cap-<slug>` tag naming the capability this flow is about.\"\n        : `the view resolves ${claim.capabilities.length} capabilities (${claim.capabilities.join(\", \")}), ` +\n            \"so nothing says which document the id belongs to. A flow realizing promises from two capabilities \" +\n            \"needs one `#req-` tag per capability to be unambiguous, which the tag grammar cannot express — \" +\n            \"split the flow, or drop the `#req-` tag and let `Realizes:` on the service requirements carry it.\";\n    case \"undocumented\":\n      return (\n        `capability '${claim.capability}' is declared but has no capabilities/${claim.capability}/spec.md, ` +\n        \"so it carries no requirements to satisfy. Write the document — a name alone can be claimed with \" +\n        \"`#cap-`, but only a document has promises a flow can keep.\"\n      );\n    case \"empty\":\n      return (\n        `capabilities/${claim.capability}/spec.md exists and declares no requirements yet — ` +\n        \"add the `## Requirements` section, each requirement carrying its `Requirement-ID:`.\"\n      );\n    case \"none\":\n      return claim.close.length > 0\n        ? `capabilities/${claim.capability}/spec.md declares no requirement flattening to '${claim.slug}'. ` +\n            `Did you mean: ${claim.close.map(idAndTag).join(\", \")}?`\n        : `capabilities/${claim.capability}/spec.md declares no requirement flattening to '${claim.slug}' — ` +\n            \"check the `Requirement-ID:` lines in that document.\";\n    default:\n      return (\n        `${claim.ids.length} requirements of '${claim.capability}' flatten to '${claim.slug}' ` +\n        `(${claim.ids.join(\", \")}) — nothing in the tag can say which promise this flow keeps. ` +\n        \"Rename one of them: a guessed requirement reports the wrong promise as kept and the right one as \" +\n        \"unimplemented, and both answers look exactly like the truth.\"\n      );\n  }\n}\n\n/**\n * One finding per `#req-` tag that does not resolve — never one per view.\n *\n * Several `#req-` tags on one view are legal and normal: a checkout flow that\n * charges once AND honours the price keeps two promises, and there is no honest\n * way to make its author pick one. So a broken tag beside a working one must\n * neither swallow the break nor lose the promise the view genuinely does keep.\n *\n * `claims` is the view's OWN capability verdicts, already resolved by the\n * caller — passed rather than recomputed so the scope this grade uses and the\n * scope `capabilityTagFindings` graded are the same list, and an unresolved\n * `#cap-` tag cannot silently scope a requirement lookup.\n */\nexport function requirementTagFindings(\n  view: ParsedView,\n  claims: readonly CapabilityClaim[],\n  requirementsOf: (capability: string) => ReadonlySet<string> | undefined,\n): Finding[] {\n  const scope = claims.flatMap((claim) => (claim.kind === \"resolved\" ? [claim.id] : []));\n  const findings: Finding[] = [];\n  for (const claim of resolveRequirementTags(view.tags, scope, requirementsOf)) {\n    if (claim.kind === \"resolved\") continue;\n    findings.push({\n      severity: \"error\",\n      code: \"usecase.requirement-unresolved\",\n      // The VIEW, not the tag — a subject is what a reader goes and opens, and\n      // one broken use case counts once however many of its tags are wrong.\n      subject: view.id,\n      message: `${viewPlace(view)} is tagged #${claim.tag}, and it does not resolve: ${advice(claim)}`,\n    });\n  }\n  return findings;\n}\n"]}