@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/dist/core/capabilities/delta/uncovered.js.map

@@ -1 +1 @@
-{"version":3,"file":"uncovered.js","sourceRoot":"","sources":["../../../../src/core/capabilities/delta/uncovered.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The `Realizes:` join taken INSIDE ONE FEATURE, in both directions: a promise\n * this feature makes that nothing in it keeps, and a promise it retires that\n * something outside it still keeps.\n *\n * `../realizes/findings.ts` grades the same join at the two places it can be\n * WRONG — an entry that resolves to nothing, a living requirement nothing\n * realizes. This module grades it at the one place it can silently COME APART:\n * the merge. Both directions are about a change, both are answered from\n * documents the archive gate already has parsed, and neither has any meaning\n * outside a feature — which is why they live together here and not beside their\n * fleet-scope siblings.\n *\n * TWO CODES, NOT ONE, and the decision is worth the paragraph because the shape\n * invites the opposite:\n *\n *   - The FIXES are different. `capability.uncovered` is fixed by writing the\n *     `Realizes:` line the promise is missing; `capability.remove-requirement-realized`\n *     is fixed by retiring the requirement that carries the line, or by dropping\n *     the line from it. A code is what a machine branches on and the branch is\n *     the fix, so a single code covering both would be a code neither caller can\n *     act on.\n *   - The SEVERITIES are different, and they are different for the reason\n *     `../../vocabulary/issue.ts` draws the distinction at all. `capability.uncovered`\n *     is a warning that GATES: the document is legal — writing a business promise\n *     ahead of the fleet is the recorded intended use, which is exactly why\n *     `capability.requirement-unrealized` warns and never gates — while the MERGE\n *     is what is unsafe, because once it lands the only thing that will ever\n *     mention the promise again is a fleet-scope warning nobody reads. The\n *     removal direction has no such legal reading: after that merge a LIVING\n *     service document nobody in the feature touched carries a pointer at\n *     nothing, and `capability.realizes-unknown` is already an ERROR there. So it\n *     is an error here, exactly as `openapi.remove-op-consumed` is one axis over\n *     for the identical shape — this feature retires a thing the living fleet\n *     still uses. One code carrying two severities is a code that says nothing.\n *   - The family already spells every direction of every join as its own code:\n *     `capability.unknown` / `capability.realizes-unknown` name the entry that\n *     resolves to nothing, `capability.unrealized` /\n *     `capability.requirement-unrealized` name the promise nobody keeps. A pair\n *     here is the shape a reader of that list already expects.\n *\n * A `#req-` TAGGED FLOW COUNTS AS COVER, and the reason it did not is worth\n * recording because it was a consequence rather than a policy. A `dynamic view`\n * used to be a fleet document with no feature-delta path, so a `#req-` tag\n * naming a capability requirement that was not living yet was ALREADY\n * `usecase.requirement-unresolved` — an error on `validate --all` — for the\n * whole window before the archive. At the moment this ran, a legal flow claim on\n * a newly-ADDED requirement could not exist, and the message said so: archive\n * with `--approve` first, tag the flow afterwards. That advice lands a promise\n * kept by nothing and relies on somebody coming back.\n *\n * `features/<FEAT>/usecases/` closed that (`core/usecases/delta/flows.ts`), so\n * the claim can now be legal at the moment it is graded, and the third arm of\n * `flows` below is it. What has NOT changed is which claims count: both tags\n * must resolve, against the vocabulary and requirement index this feature's own\n * merge would leave behind. A broken tag of either kind is an error in its own\n * right and must never also mark a promise kept — a typo that silenced this gate\n * would turn a mistake into a green archive.\n *\n * NO FILESYSTEM, deliberately, exactly as `../realizes/join.ts` has none — and\n * that is why the flows arrive as resolved pairs rather than as a docsDir. The\n * living side of the removal direction arrives as a thunk the caller supplies,\n * so the fleet-wide read happens only when this feature retires something, and\n * this module stays testable without a tree.\n */\nimport type { Requirement } from \"../../document/spec.js\";\nimport type { Issue } from \"../../vocabulary/issue.js\";\nimport { splitRealizesEntry } from \"../realizes/join.js\";\nimport { tagSlug } from \"../usecase-join.js\";\n\n/**\n * One requirements document on the SERVICE side of the join, and the two facts\n * that address it: whose it is, and which axis. Both halves of the key are\n * needed because a feature's delta of `payment-service`'s `arch.spec.md`\n * supersedes the living `arch.spec.md` and says nothing at all about the living\n * `spec.md` beside it.\n */\nexport interface RealizingDoc {\n  /** The service id. */\n  service: string;\n  /** The axis's filename — `spec.md` or `arch.spec.md`, as `SPEC_AXES` spells it. */\n  file: string;\n  reqs: readonly Requirement[];\n}\n\n/**\n * One capability document a feature's delta changes, with the living text that\n * delta applies to.\n *\n * `living` is here rather than derived because a REMOVED requirement is exempt\n * from `capability.requirement-unidentified` and so may be spelled by heading\n * alone — the id it retires is then a fact about the LIVING document, and\n * without it the removal direction would silently grade nothing for the\n * commonest way a removal is written. Requirements rather than the delta\n * package's `LivingIndex`: `core/delta` imports this package, so importing it\n * back would be a package cycle the file-level cycle check cannot see.\n */\nexport interface CapabilityDeltaDoc {\n  /** The capability id — the directory chain under `features/<FEAT>/capabilities/`. */\n  id: string;\n  reqs: readonly Requirement[];\n  /** The LIVING `capabilities/<id>/spec.md` requirements, or `[]` when this feature creates it. */\n  living: readonly Requirement[];\n}\n\n/**\n * The `(capability, requirement)` pair, keyed for a Set.\n *\n * NUL — the separator `core/delta/scope.ts`'s claim key already uses — rather\n * than `#`, because a key's separator must be one its halves cannot contain and\n * a capability id is a YAML key and a directory name, constrained nowhere.\n * Re-joining with `#` would make `a#b` + `C` and `a` + `b#C` one key, and the\n * second is unreachable only because the requirement grammar happens to exclude\n * `#` today.\n */\nfunction pairKey(capability: string, requirement: string): string {\n  return `${capability}\\0${requirement}`;\n}\n\n/**\n * The pairs one requirement's `Realizes:` lines name.\n *\n * Through `splitRealizesEntry`, never a local split, and the LAST `#` is what\n * makes it right: the requirement half has a grammar that excludes `#` and the\n * capability half has none, so a first-`#` split mis-parses every id containing\n * one — silently, which is the failure this axis exists to refuse.\n */\nfunction realizedPairs(r: Requirement): string[] {\n  return r.realizes.flatMap((entry) => {\n    const target = splitRealizesEntry(entry);\n    return target === null ? [] : [pairKey(target.capability, target.requirement)];\n  });\n}\n\n/** How a service document is named in a message — the axis only where it is not the default one. */\nfunction docLabel(doc: RealizingDoc): string {\n  return doc.file === \"spec.md\" ? doc.service : `${doc.service} (${doc.file})`;\n}\n\n/**\n * One promise a `#req-` tagged flow in the SAME feature keeps.\n *\n * Structurally typed rather than imported from `core/usecases/delta/claims.ts`,\n * where the caller builds it, and the reason is the package graph rather than\n * taste: `core/usecases/` already imports this package, so importing it back\n * would be a cycle that `import/no-cycle` cannot see — the acyclicity obligation\n * `scripts/package-graph.mjs` exists to hold. The shape is three fields; the\n * RULE that produced them (both tags resolved, or the claim does not count) is\n * that module's, and this one grades what it is handed.\n */\nexport interface KeptByFlow {\n  capability: string;\n  requirement: string;\n  /** The view ids keeping it. Carried for a caller's report; nothing here reads it. */\n  flows: readonly string[];\n}\n\n/**\n * The flow corpus, or the honest statement that there was not one to read.\n *\n * A TRI-STATE and not a possibly-empty list, because the message says what was\n * checked and an empty list would make it say something loam never looked at.\n * \"No flow keeps this\" and \"the flows were not graded\" are different sentences\n * and only one of them is an accusation — the standing rule this axis states\n * everywhere else, applied to the message rather than to a severity.\n *\n * `why` is printed, so it names the cause an author can act on: an\n * `architecture/` that did not parse is one thing, a `capabilities.yaml` that\n * does not read as a vocabulary is another, and inside a feature gate NOTHING\n * ELSE reports the second — `core/coherence/declared.ts` keeps\n * `capability.invalid` for `validate --all`. Without the sentence the run\n * refuses, names the wrong cause, and points at nothing.\n */\nexport type FlowCorpus =\n  | { graded: true; kept: readonly KeptByFlow[] }\n  | { graded: false; why: string };\n\n/**\n * `capability.uncovered` — a capability requirement this feature ADDS that no\n * `Realizes:` line in the same feature's service deltas names.\n *\n * ADDED ONLY. A MODIFIED changes a promise the living fleet may already\n * realize, so demanding a re-declaration would force an edit with nothing to\n * change — the same exemption `c4.uncovered` takes one axis over. A requirement\n * with no `Requirement-ID:` is SKIPPED rather than reported: it is already\n * `capability.requirement-unidentified`, and there is nothing for a `Realizes:`\n * line to address, so two findings for one mistake is the failure to avoid.\n *\n * The covering side is ADDED or MODIFIED, never BASE and never REMOVED. A BASE\n * requirement in a delta quotes living context and the merge never writes it,\n * so a `Realizes:` line there lands nowhere; a REMOVED one is on its way out and\n * cannot keep a promise after it is gone.\n *\n * Feature scope, deliberately. The fleet-scope version already ships as\n * `capability.requirement-unrealized`, and grading a feature-ADDED requirement\n * against the LIVING fleet is vacuous — no living `Realizes:` can name it\n * without being `capability.realizes-unknown` today.\n */\nexport function uncoveredIssues(\n  capabilities: readonly CapabilityDeltaDoc[],\n  services: readonly RealizingDoc[],\n  // REQUIRED, with no default. A default would have to be one of the two arms,\n  // and either choice is wrong for a caller that forgot: `graded: true` with an\n  // empty list makes the message assert a negative, and `graded: false` makes it\n  // quietly stop checking a corpus the caller does have. The compiler asking is\n  // cheaper than either.\n  flows: FlowCorpus,\n): Issue[] {\n  if (capabilities.length === 0) return [];\n  const kept = new Set<string>();\n  for (const doc of services) {\n    for (const r of doc.reqs) {\n      if (r.kind !== \"ADDED\" && r.kind !== \"MODIFIED\") continue;\n      for (const pair of realizedPairs(r)) kept.add(pair);\n    }\n  }\n  // The other carrier, through the SAME `pairKey` as the `Realizes:` side: two\n  // corpora answering one question must not be able to disagree about which\n  // promise a claim addresses. The caller resolved these; a claim whose tags did\n  // not both resolve never reaches here, which is what stops a typo from\n  // silencing the gate.\n  if (flows.graded) for (const flow of flows.kept) kept.add(pairKey(flow.capability, flow.requirement));\n  // What the message may CLAIM about the flow half. Ungraded, it claims nothing\n  // and says so — the `Realizes:` half was still checked and is still worth\n  // gating on, so the finding stands; what must not stand is a sentence\n  // convicting a flow nobody resolved.\n  const flowClause = flows.graded\n    ? \"and no `dynamic view` under this feature's usecases/ resolves a `#req-` tag to it. \"\n    : `and the flow half of the join was NOT checked — ${flows.why}, so a \\`#req-\\` claim could not be resolved either way. `;\n  const issues: Issue[] = [];\n  for (const doc of capabilities) {\n    for (const r of doc.reqs) {\n      if (r.kind !== \"ADDED\" || r.id === undefined) continue;\n      if (kept.has(pairKey(doc.id, r.id))) continue;\n      const entry = `${doc.id}#${r.id}`;\n      issues.push({\n        severity: \"warn\",\n        gates: true,\n        code: \"capability.uncovered\",\n        subject: doc.id,\n        message:\n          `capability ${doc.id}: ADDED requirement '${r.name}' (${r.id}) is realized by nothing this feature changes — ` +\n          `no ADDED or MODIFIED requirement in its specs/ deltas carries \\`Realizes: ${entry}\\`, ` +\n          flowClause +\n          \"The document is legal; the MERGE is what is unsafe: once it lands, the only thing that will ever mention \" +\n          \"this promise again is a fleet-scope warning (capability.requirement-unrealized) nobody reads. \" +\n          `Three ways on: add \\`Realizes: ${entry}\\` to the service requirement that carries part of it; ` +\n          `if the promise CROSSES services, write the flow that keeps it as features/<FEAT>/usecases/<name>.likec4 and ` +\n          `tag its \\`dynamic view\\` \\`#cap-${tagSlug(doc.id)}\\` and \\`#req-${tagSlug(r.id)}\\` — the archive merges it into ` +\n          \"architecture/usecases/ with everything else this feature lands; or archive with --approve to land the promise \" +\n          \"ahead of the fleet and let capability.requirement-unrealized carry it.\",\n      });\n    }\n  }\n  return issues;\n}\n\n/** Everything the removal direction needs, and nothing it would have to read twice. */\nexport interface RemovalJoin {\n  /** This feature's capability deltas, each with the living document it applies to. */\n  capabilities: readonly CapabilityDeltaDoc[];\n  /** This feature's own service delta documents, already parsed by the same walk. */\n  deltas: readonly RealizingDoc[];\n  /**\n   * Every LIVING service requirements document in the fleet. A thunk, called at\n   * most once and only when this feature actually retires a capability\n   * requirement — the overwhelming majority of features retire none, and this\n   * read is the whole fleet's `spec.md` and `arch.spec.md`.\n   */\n  living: () => Promise<readonly RealizingDoc[]>;\n}\n\n/** The living requirements a delta document supersedes — MODIFIED and REMOVED both restate or delete. */\nfunction supersedes(delta: RealizingDoc | undefined, living: Requirement): boolean {\n  if (delta === undefined) return false;\n  return delta.reqs.some((r) => {\n    if (r.kind !== \"MODIFIED\" && r.kind !== \"REMOVED\") return false;\n    return r.id === undefined ? r.name === living.name : r.id === living.id;\n  });\n}\n\n/**\n * `capability.remove-requirement-realized` — this feature retires a capability\n * requirement that something the merge LEAVES BEHIND still realizes.\n *\n * The hole the forward direction does not close, and the one this whole module\n * exists to make impossible: a feature that REMOVES a capability requirement a\n * living service requirement realizes used to archive at exit 0, and the next\n * `loam validate --all` then failed with `capability.realizes-unknown` against a\n * service document nobody had touched. An archive that leaves the fleet red\n * against an untouched document is the exact class of silent damage the product\n * exists to refuse.\n *\n * GRADED AGAINST THE POST-MERGE FLEET, which is the only reading under which\n * the two escape hatches fall out instead of being special-cased. A living\n * requirement that this feature's own delta MODIFIES or REMOVES is gone as\n * written — a MODIFIED carries its FULL new text, so restating the requirement\n * without its `Realizes:` line IS how an author drops the join — and the delta's\n * own ADDED/MODIFIED requirements are what stands in its place. So: retire the\n * realizer in the same change and there is no breach; keep the line and there\n * is.\n *\n * A `#req-` tagged flow realizing the promise is NOT consulted, and that is the\n * other subject rather than a gap: the tag names the requirement directly, so a\n * removal turns it into `usecase.requirement-unresolved` on the living view —\n * loud, in the document that has to change, and nothing here would make it\n * louder.\n *\n * A REMOVED spelled by heading resolves through the living document, so it\n * grades exactly what the merge would delete. One that selects nothing is\n * already `delta.removed-unknown` and retires nothing, so it is skipped here —\n * two findings for one mistake, again.\n */\nexport async function removedRealizedIssues(join: RemovalJoin): Promise<Issue[]> {\n  const retired = new Map<string, { capability: string; id: string; name: string }>();\n  for (const doc of join.capabilities) {\n    for (const r of doc.reqs) {\n      if (r.kind !== \"REMOVED\") continue;\n      const selected = doc.living.filter((l) => (r.id === undefined ? l.name === r.name : l.id === r.id));\n      for (const l of selected) {\n        if (l.id === undefined) continue;\n        retired.set(pairKey(doc.id, l.id), { capability: doc.id, id: l.id, name: l.name });\n      }\n    }\n  }\n  if (retired.size === 0) return [];\n\n  // Who still realizes each retired pair after the merge: the living\n  // requirements this feature does not supersede, plus the requirements its own\n  // deltas add or restate.\n  const realizers = new Map<string, string[]>();\n  const record = (pair: string, who: string): void => {\n    if (!retired.has(pair)) return;\n    const found = realizers.get(pair) ?? [];\n    found.push(who);\n    realizers.set(pair, found);\n  };\n  for (const doc of await join.living()) {\n    const delta = join.deltas.find((d) => d.service === doc.service && d.file === doc.file);\n    for (const r of doc.reqs) {\n      if (supersedes(delta, r)) continue;\n      for (const pair of realizedPairs(r)) record(pair, `${docLabel(doc)}'s living requirement '${r.name}'`);\n    }\n  }\n  for (const doc of join.deltas) {\n    for (const r of doc.reqs) {\n      if (r.kind !== \"ADDED\" && r.kind !== \"MODIFIED\") continue;\n      for (const pair of realizedPairs(r)) record(pair, `this feature's ${docLabel(doc)} delta requirement '${r.name}'`);\n    }\n  }\n\n  const issues: Issue[] = [];\n  for (const [pair, promise] of retired) {\n    const who = realizers.get(pair);\n    if (who === undefined) continue;\n    const entry = `${promise.capability}#${promise.id}`;\n    issues.push({\n      severity: \"error\",\n      code: \"capability.remove-requirement-realized\",\n      subject: promise.capability,\n      message:\n        `capability ${promise.capability}: this feature REMOVES '${promise.name}' (${promise.id}), but ${who.join(\"; \")} ` +\n        `still carries \\`Realizes: ${entry}\\`. After the merge that line points at a promise no document declares, and ` +\n        \"the very next `loam validate --all` reports capability.realizes-unknown against whatever carries it — for a \" +\n        \"LIVING realizer, a service document this feature never touched. Retire the realizing requirement in the same \" +\n        \"feature, or drop its `Realizes:` line (a MODIFIED does that by restating the requirement without it), or \" +\n        \"archive with --approve to break the join deliberately.\",\n    });\n  }\n  return issues;\n}\n"]}
+{"version":3,"file":"uncovered.js","sourceRoot":"","sources":["../../../../src/core/capabilities/delta/uncovered.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The `Realizes:` join taken INSIDE ONE FEATURE, in both directions: a promise\n * this feature makes that nothing in it keeps, and a promise it retires that\n * something outside it still keeps.\n *\n * `../realizes/findings.ts` grades the same join at the two places it can be\n * WRONG — an entry that resolves to nothing, a living requirement nothing\n * realizes. This module grades it at the one place it can silently COME APART:\n * the merge. Both directions are about a change, both are answered from\n * documents the archive gate already has parsed, and neither has any meaning\n * outside a feature — which is why they live together here and not beside their\n * fleet-scope siblings.\n *\n * TWO CODES, NOT ONE, and the decision is worth the paragraph because the shape\n * invites the opposite:\n *\n *   - The FIXES are different. `capability.uncovered` is fixed by writing the\n *     `Realizes:` line the promise is missing; `capability.remove-requirement-realized`\n *     is fixed by retiring the requirement that carries the line, or by dropping\n *     the line from it. A code is what a machine branches on and the branch is\n *     the fix, so a single code covering both would be a code neither caller can\n *     act on.\n *   - The SEVERITIES are different, and they are different for the reason\n *     `../../vocabulary/issue.ts` draws the distinction at all. `capability.uncovered`\n *     is a warning that GATES: the document is legal — writing a business promise\n *     ahead of the fleet is the recorded intended use, which is exactly why\n *     `capability.requirement-unrealized` warns and never gates — while the MERGE\n *     is what is unsafe, because once it lands the only thing that will ever\n *     mention the promise again is a fleet-scope warning nobody reads. The\n *     removal direction has no such legal reading: after that merge a LIVING\n *     service document nobody in the feature touched carries a pointer at\n *     nothing, and `capability.realizes-unknown` is already an ERROR there. So it\n *     is an error here, exactly as `openapi.remove-op-consumed` is one axis over\n *     for the identical shape — this feature retires a thing the living fleet\n *     still uses. One code carrying two severities is a code that says nothing.\n *   - The family already spells every direction of every join as its own code:\n *     `capability.unknown` / `capability.realizes-unknown` name the entry that\n *     resolves to nothing, `capability.unrealized` /\n *     `capability.requirement-unrealized` name the promise nobody keeps. A pair\n *     here is the shape a reader of that list already expects.\n *\n * A `#req-` TAGGED FLOW COUNTS AS COVER, and the reason it did not is worth\n * recording because it was a consequence rather than a policy. A `dynamic view`\n * used to be a fleet document with no feature-delta path, so a `#req-` tag\n * naming a capability requirement that was not living yet was ALREADY\n * `usecase.requirement-unresolved` — an error on `validate --all` — for the\n * whole window before the archive. At the moment this ran, a legal flow claim on\n * a newly-ADDED requirement could not exist, and the message said so: archive\n * with `--approve` first, tag the flow afterwards. That advice lands a promise\n * kept by nothing and relies on somebody coming back.\n *\n * `features/<FEAT>/usecases/` closed that (`core/usecases/delta/flows.ts`), so\n * the claim can now be legal at the moment it is graded, and the third arm of\n * `flows` below is it. What has NOT changed is which claims count: both tags\n * must resolve, against the vocabulary and requirement index this feature's own\n * merge would leave behind. A broken tag of either kind is an error in its own\n * right and must never also mark a promise kept — a typo that silenced this gate\n * would turn a mistake into a green archive.\n *\n * NO FILESYSTEM, deliberately, exactly as `../realizes/join.ts` has none — and\n * that is why the flows arrive as resolved pairs rather than as a docsDir. The\n * living side of the removal direction arrives as a thunk the caller supplies,\n * so the fleet-wide read happens only when this feature retires something, and\n * this module stays testable without a tree.\n */\nimport type { Requirement } from \"../../document/spec.js\";\nimport type { Issue } from \"../../vocabulary/issue.js\";\nimport { splitRealizesEntry } from \"../realizes/join.js\";\nimport { tagSlug } from \"../usecase-join.js\";\n\n/**\n * One requirements document on the SERVICE side of the join, and the two facts\n * that address it: whose it is, and which axis. Both halves of the key are\n * needed because a feature's delta of `payment-service`'s `arch.spec.md`\n * supersedes the living `arch.spec.md` and says nothing at all about the living\n * `spec.md` beside it.\n */\nexport interface RealizingDoc {\n  /** The service id. */\n  service: string;\n  /** The axis's filename — `spec.md` or `arch.spec.md`, as `SPEC_AXES` spells it. */\n  file: string;\n  reqs: readonly Requirement[];\n}\n\n/**\n * One capability document a feature's delta changes, with the living text that\n * delta applies to.\n *\n * `living` is here rather than derived because a REMOVED requirement is exempt\n * from `capability.requirement-unidentified` and so may be spelled by heading\n * alone — the id it retires is then a fact about the LIVING document, and\n * without it the removal direction would silently grade nothing for the\n * commonest way a removal is written. Requirements rather than the delta\n * package's `LivingIndex`: `core/delta` imports this package, so importing it\n * back would be a package cycle the file-level cycle check cannot see.\n */\nexport interface CapabilityDeltaDoc {\n  /** The capability id — the directory chain under `features/<FEAT>/capabilities/`. */\n  id: string;\n  reqs: readonly Requirement[];\n  /** The LIVING `capabilities/<id>/spec.md` requirements, or `[]` when this feature creates it. */\n  living: readonly Requirement[];\n}\n\n/**\n * The `(capability, requirement)` pair, keyed for a Set.\n *\n * NUL — the separator `core/delta/scope.ts`'s claim key already uses — rather\n * than `#`, because a key's separator must be one its halves cannot contain and\n * a capability id is a YAML key and a directory name, constrained nowhere.\n * Re-joining with `#` would make `a#b` + `C` and `a` + `b#C` one key, and the\n * second is unreachable only because the requirement grammar happens to exclude\n * `#` today.\n */\nfunction pairKey(capability: string, requirement: string): string {\n  return `${capability}\\0${requirement}`;\n}\n\n/**\n * The pairs one requirement's `Realizes:` lines name.\n *\n * Through `splitRealizesEntry`, never a local split, and the LAST `#` is what\n * makes it right: the requirement half has a grammar that excludes `#` and the\n * capability half has none, so a first-`#` split mis-parses every id containing\n * one — silently, which is the failure this axis exists to refuse.\n */\nfunction realizedPairs(r: Requirement): string[] {\n  return r.realizes.flatMap((entry) => {\n    const target = splitRealizesEntry(entry);\n    return target === null ? [] : [pairKey(target.capability, target.requirement)];\n  });\n}\n\n/** How a service document is named in a message — the axis only where it is not the default one. */\nfunction docLabel(doc: RealizingDoc): string {\n  return doc.file === \"spec.md\" ? doc.service : `${doc.service} (${doc.file})`;\n}\n\n/**\n * One promise a `#req-` tagged flow in the SAME feature keeps.\n *\n * Structurally typed rather than imported from `core/usecases/delta/claims.ts`,\n * where the caller builds it, and the reason is the package graph rather than\n * taste: `core/usecases/` already imports this package, so importing it back\n * would be a cycle that `import/no-cycle` cannot see — the acyclicity obligation\n * `scripts/package-graph.mjs` exists to hold. The shape is three fields; the\n * RULE that produced them (both tags resolved, or the claim does not count) is\n * that module's, and this one grades what it is handed.\n */\nexport interface KeptByFlow {\n  capability: string;\n  requirement: string;\n  /** The view ids keeping it. Carried for a caller's report; nothing here reads it. */\n  flows: readonly string[];\n}\n\n/**\n * The flow corpus, or the honest statement that there was not one to read.\n *\n * A TRI-STATE and not a possibly-empty list, because the message says what was\n * checked and an empty list would make it say something loam never looked at.\n * \"No flow keeps this\" and \"the flows were not graded\" are different sentences\n * and only one of them is an accusation — the standing rule this axis states\n * everywhere else, applied to the message rather than to a severity.\n *\n * `why` is printed, so it names the cause an author can act on: an\n * `architecture/` that did not parse is one thing, a `capabilities.yaml` that\n * does not read as a vocabulary is another, and inside a feature gate NOTHING\n * ELSE reports the second — `core/coherence/declared.ts` keeps\n * `capability.invalid` for `validate --all`. Without the sentence the run\n * refuses, names the wrong cause, and points at nothing.\n */\nexport type FlowCorpus =\n  | { graded: true; kept: readonly KeptByFlow[] }\n  | { graded: false; why: string };\n\n/**\n * `capability.uncovered` — a capability requirement this feature ADDS that no\n * `Realizes:` line in the same feature's service deltas names.\n *\n * ADDED ONLY. A MODIFIED changes a promise the living fleet may already\n * realize, so demanding a re-declaration would force an edit with nothing to\n * change — the same exemption `c4.uncovered` takes one axis over. A requirement\n * with no `Requirement-ID:` is SKIPPED rather than reported: it is already\n * `capability.requirement-unidentified`, and there is nothing for a `Realizes:`\n * line to address, so two findings for one mistake is the failure to avoid.\n *\n * The covering side is ADDED or MODIFIED, never BASE and never REMOVED. A BASE\n * requirement in a delta quotes living context and the merge never writes it,\n * so a `Realizes:` line there lands nowhere; a REMOVED one is on its way out and\n * cannot keep a promise after it is gone.\n *\n * Feature scope, deliberately. The fleet-scope version already ships as\n * `capability.requirement-unrealized`, and grading a feature-ADDED requirement\n * against the LIVING fleet is vacuous — no living `Realizes:` can name it\n * without being `capability.realizes-unknown` today.\n */\nexport function uncoveredIssues(\n  capabilities: readonly CapabilityDeltaDoc[],\n  services: readonly RealizingDoc[],\n  // REQUIRED, with no default. A default would have to be one of the two arms,\n  // and either choice is wrong for a caller that forgot: `graded: true` with an\n  // empty list makes the message assert a negative, and `graded: false` makes it\n  // quietly stop checking a corpus the caller does have. The compiler asking is\n  // cheaper than either.\n  flows: FlowCorpus,\n): Issue[] {\n  if (capabilities.length === 0) return [];\n  const kept = new Set<string>();\n  for (const doc of services) {\n    for (const r of doc.reqs) {\n      if (r.kind !== \"ADDED\" && r.kind !== \"MODIFIED\") continue;\n      for (const pair of realizedPairs(r)) kept.add(pair);\n    }\n  }\n  // The other carrier, through the SAME `pairKey` as the `Realizes:` side: two\n  // corpora answering one question must not be able to disagree about which\n  // promise a claim addresses. The caller resolved these; a claim whose tags did\n  // not both resolve never reaches here, which is what stops a typo from\n  // silencing the gate.\n  if (flows.graded) for (const flow of flows.kept) kept.add(pairKey(flow.capability, flow.requirement));\n  // What the message may CLAIM about the flow half. Ungraded, it claims nothing\n  // and says so — the `Realizes:` half was still checked and is still worth\n  // gating on, so the finding stands; what must not stand is a sentence\n  // convicting a flow nobody resolved.\n  const flowClause = flows.graded\n    ? \"and no `dynamic view` under this feature's usecases/ resolves a `#req-` tag to it. \"\n    : `and the flow half of the join was NOT checked — ${flows.why}, so a \\`#req-\\` claim could not be resolved either way. `;\n  const issues: Issue[] = [];\n  for (const doc of capabilities) {\n    for (const r of doc.reqs) {\n      if (r.kind !== \"ADDED\" || r.id === undefined) continue;\n      if (kept.has(pairKey(doc.id, r.id))) continue;\n      const entry = `${doc.id}#${r.id}`;\n      issues.push({\n        severity: \"warn\",\n        gates: true,\n        code: \"capability.uncovered\",\n        subject: doc.id,\n        message:\n          `capability ${doc.id}: ADDED requirement '${r.name}' (${r.id}) is realized by nothing this feature changes — ` +\n          `no ADDED or MODIFIED requirement in its specs/ deltas carries \\`Realizes: ${entry}\\`, ` +\n          flowClause +\n          \"The document is legal; the MERGE is what is unsafe: once it lands, the only thing that will ever mention \" +\n          \"this promise again is a fleet-scope warning (capability.requirement-unrealized) nobody reads. \" +\n          `Three ways on: add \\`Realizes: ${entry}\\` to the service requirement that carries part of it; ` +\n          `if the promise CROSSES services, write the flow that keeps it as features/<FEAT>/usecases/<name>.likec4 and ` +\n          `tag its \\`dynamic view\\` \\`#cap-${tagSlug(doc.id)}\\` and \\`#req-${tagSlug(r.id)}\\` — the archive merges it into ` +\n          \"architecture/usecases/ with everything else this feature lands; or archive with --approve to land the promise \" +\n          \"ahead of the fleet and let capability.requirement-unrealized carry it.\",\n      });\n    }\n  }\n  return issues;\n}\n\n/** Everything the removal direction needs, and nothing it would have to read twice. */\nexport interface RemovalJoin {\n  /** This feature's capability deltas, each with the living document it applies to. */\n  capabilities: readonly CapabilityDeltaDoc[];\n  /** This feature's own service delta documents, already parsed by the same walk. */\n  deltas: readonly RealizingDoc[];\n  /**\n   * Every LIVING service requirements document in the fleet. A thunk, called at\n   * most once and only when this feature actually retires a capability\n   * requirement — the overwhelming majority of features retire none, and this\n   * read is the whole fleet's `spec.md` and `arch.spec.md`.\n   */\n  living: () => Promise<readonly RealizingDoc[]>;\n}\n\n/** The living requirements a delta document supersedes — MODIFIED and REMOVED both restate or delete. */\nfunction supersedes(delta: RealizingDoc | undefined, living: Requirement): boolean {\n  if (delta === undefined) return false;\n  return delta.reqs.some((r) => {\n    if (r.kind !== \"MODIFIED\" && r.kind !== \"REMOVED\") return false;\n    return r.id === undefined ? r.name === living.name : r.id === living.id;\n  });\n}\n\n/**\n * `capability.remove-requirement-realized` — this feature retires a capability\n * requirement that something the merge LEAVES BEHIND still realizes.\n *\n * The hole the forward direction does not close, and the one this whole module\n * exists to make impossible: a feature that REMOVES a capability requirement a\n * living service requirement realizes used to archive at exit 0, and the next\n * `loam validate --all` then failed with `capability.realizes-unknown` against a\n * service document nobody had touched. An archive that leaves the fleet red\n * against an untouched document is the exact class of silent damage the product\n * exists to refuse.\n *\n * GRADED AGAINST THE POST-MERGE FLEET, which is the only reading under which\n * the two escape hatches fall out instead of being special-cased. A living\n * requirement that this feature's own delta MODIFIES or REMOVES is gone as\n * written — a MODIFIED carries its FULL new text, so restating the requirement\n * without its `Realizes:` line IS how an author drops the join — and the delta's\n * own ADDED/MODIFIED requirements are what stands in its place. So: retire the\n * realizer in the same change and there is no breach; keep the line and there\n * is.\n *\n * A `#req-` tagged flow realizing the promise is NOT consulted, and that is the\n * other subject rather than a gap: the tag names the requirement directly, so a\n * removal turns it into `usecase.requirement-unresolved` on the living view —\n * an error the delta walk raises before the archive, naming that view\n * (`core/usecases/delta/modified.ts`), and nothing here would make it louder.\n *\n * A REMOVED spelled by heading resolves through the living document, so it\n * grades exactly what the merge would delete. One that selects nothing is\n * already `delta.removed-unknown` and retires nothing, so it is skipped here —\n * two findings for one mistake, again.\n */\nexport async function removedRealizedIssues(join: RemovalJoin): Promise<Issue[]> {\n  const retired = new Map<string, { capability: string; id: string; name: string }>();\n  for (const doc of join.capabilities) {\n    for (const r of doc.reqs) {\n      if (r.kind !== \"REMOVED\") continue;\n      const selected = doc.living.filter((l) => (r.id === undefined ? l.name === r.name : l.id === r.id));\n      for (const l of selected) {\n        if (l.id === undefined) continue;\n        retired.set(pairKey(doc.id, l.id), { capability: doc.id, id: l.id, name: l.name });\n      }\n    }\n  }\n  if (retired.size === 0) return [];\n\n  // Who still realizes each retired pair after the merge: the living\n  // requirements this feature does not supersede, plus the requirements its own\n  // deltas add or restate.\n  const realizers = new Map<string, string[]>();\n  const record = (pair: string, who: string): void => {\n    if (!retired.has(pair)) return;\n    const found = realizers.get(pair) ?? [];\n    found.push(who);\n    realizers.set(pair, found);\n  };\n  for (const doc of await join.living()) {\n    const delta = join.deltas.find((d) => d.service === doc.service && d.file === doc.file);\n    for (const r of doc.reqs) {\n      if (supersedes(delta, r)) continue;\n      for (const pair of realizedPairs(r)) record(pair, `${docLabel(doc)}'s living requirement '${r.name}'`);\n    }\n  }\n  for (const doc of join.deltas) {\n    for (const r of doc.reqs) {\n      if (r.kind !== \"ADDED\" && r.kind !== \"MODIFIED\") continue;\n      for (const pair of realizedPairs(r)) record(pair, `this feature's ${docLabel(doc)} delta requirement '${r.name}'`);\n    }\n  }\n\n  const issues: Issue[] = [];\n  for (const [pair, promise] of retired) {\n    const who = realizers.get(pair);\n    if (who === undefined) continue;\n    const entry = `${promise.capability}#${promise.id}`;\n    issues.push({\n      severity: \"error\",\n      code: \"capability.remove-requirement-realized\",\n      subject: promise.capability,\n      message:\n        `capability ${promise.capability}: this feature REMOVES '${promise.name}' (${promise.id}), but ${who.join(\"; \")} ` +\n        `still carries \\`Realizes: ${entry}\\`. After the merge that line points at a promise no document declares, and ` +\n        \"the very next `loam validate --all` reports capability.realizes-unknown against whatever carries it — for a \" +\n        \"LIVING realizer, a service document this feature never touched. Retire the realizing requirement in the same \" +\n        \"feature, or drop its `Realizes:` line (a MODIFIED does that by restating the requirement without it), or \" +\n        \"archive with --approve to break the join deliberately.\",\n    });\n  }\n  return issues;\n}\n"]}

package/dist/core/capabilities/findings.js

@@ -3,9 +3,13 @@
  * entry the vocabulary does not declare, a vocabulary nobody can read, a
  * declared capability no living requirement realizes, a directory that declares
  * nothing, and the two rules an authored capability document itself must keep.
- * Values only — core never prints — and the join rule shaped twice (Finding for
- * validate, Issue for coherence), both spelled with literal codes so
- * test/codes-drift.test.ts can collect them.
+ * Values only — core never prints — and the join rule written ONCE, as the
+ * Issue coherence gates on, which validate files as a Finding unchanged (an
+ * Issue is assignable to a Finding), with a literal code so
+ * test/codes-drift.test.ts can collect it. It used to be shaped twice, a
+ * Finding twin and an Issue twin with byte-identical bodies; one function over
+ * one message builder is what keeps the finding an author reads at the service
+ * target and the refusal they hit at `loam archive` from drifting apart.
  *
  * The opt-in rule lives here, and it deliberately DIVERGES from `Requires:`.
  * There the LINE is the opt-in: a `Requires:` entry against a missing
@@ -31,8 +35,9 @@ import { requirementDigest } from "../document/spec.js";
  *
  * Exported because the suppression is not this module's private business — the
  * use-case axis asks the same question about the same file
- * (`commands/validate/fleet/landscape.ts` hands the answer to
- * `usecases/capability-tag.ts`), and a hand-rolled
+ * (`commands/validate/fleet/map/usecases.ts` hands the answer to
+ * `core/usecases/grade/capability-tag.ts`, and `core/usecases/delta/claims.ts`
+ * to the same grader for a feature's own flows), and a hand-rolled
  * `present && invalid === undefined ? [...byId.keys()] : null` at each site is
  * three copies of one rule. The failure that costs is not hypothetical: the next
  * un-gradable state added to `CapabilityVocabulary` — "present but partially
@@ -77,23 +82,14 @@ function unknownMessage(where, u) {
             : ". Declare it in either — a name alone is a `capabilities: {<id>: {description, owner}}` entry, a name with prose behind it is the document — or fix the spelling"));
 }
 /**
- * `capability.unknown` as validate sees it — an ERROR, the same grade as
- * `Requires:` and for its reason: an invented capability reads exactly like a
- * real one in the requirement and in every rollup built over it.
- */
-export function capabilityUnknownFindings(reqs, target, vocab) {
-    return unknownEntries(reqs, vocab).map((u) => ({
-        severity: "error",
-        code: "capability.unknown",
-        subject: target.subject,
-        message: unknownMessage(target.where, u),
-    }));
-}
-/**
- * The same rule shaped as coherence Issues, for a feature's delta documents: a
- * delta requirement naming an undeclared capability would merge a join that
- * resolves to nothing, so it gates `loam archive` like other errors and stays
- * `--approve`-overridable. The one new archive gate of this axis.
+ * `capability.unknown` — an ERROR, the same grade as `Requires:` and for its
+ * reason: an invented capability reads exactly like a real one in the
+ * requirement and in every rollup built over it. Validate files it as a
+ * Finding at the service target. For a feature's delta documents it is a
+ * coherence Issue: a delta requirement naming an undeclared capability would
+ * merge a join that resolves to nothing, so it gates `loam archive` like other
+ * errors and stays `--approve`-overridable. The one new archive gate of this
+ * axis.
  */
 export function capabilityUnknownIssues(reqs, target, vocab) {
     return unknownEntries(reqs, vocab).map((u) => ({

package/dist/core/capabilities/findings.js.map

@@ -1 +1 @@
-{"version":3,"file":"findings.js","sourceRoot":"","sources":["../../../src/core/capabilities/findings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The capability grades, in every direction the axis is graded: a `Capability:`\n * entry the vocabulary does not declare, a vocabulary nobody can read, a\n * declared capability no living requirement realizes, a directory that declares\n * nothing, and the two rules an authored capability document itself must keep.\n * Values only — core never prints — and the join rule shaped twice (Finding for\n * validate, Issue for coherence), both spelled with literal codes so\n * test/codes-drift.test.ts can collect them.\n *\n * The opt-in rule lives here, and it deliberately DIVERGES from `Requires:`.\n * There the LINE is the opt-in: a `Requires:` entry against a missing\n * permissions.yaml errors, because an authorization join that resolves against\n * nothing is the failure that axis exists to prevent. Here the FLEET'S OWN\n * FILES are the opt-in — `architecture/capabilities.yaml`, the `capabilities/`\n * tree, or both — so a fleet holding neither stays finding-free however many\n * `Capability:` lines its requirements already carry. (The roadmap's exit\n * criterion was written when the YAML was the only side and says 'a fleet with\n * no architecture/capabilities.yaml produces no capability findings at all';\n * the authored tree is the second way to opt in, and `CapabilityVocabulary.present`\n * is where the two are combined.) An INVALID vocabulary is also silence for the\n * per-entry grades — `capability.invalid` is the honest finding there, and\n * grading a hundred entries against a file nobody can read is the cascade that\n * suppression exists to stop.\n */\nimport { closeIds } from \"../c4/arch.js\";\nimport { compareIds } from \"../repo/entries.js\";\nimport { requirementDigest, type Requirement } from \"../document/spec.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport type { CapabilityDocCode, Issue } from \"../vocabulary/issue.js\";\nimport type { CapabilityVocabulary } from \"./capabilities.js\";\nimport type { CapabilityTree } from \"./tree.js\";\nimport type { CapabilityRequirementIndex } from \"./realizes/join.js\";\n\n/** Which document is being graded, and under whose name the finding is filed. */\nexport interface CapabilityTarget {\n  where: string;\n  subject: string;\n}\n\n/**\n * THE LADDER, and the only place it is applied: the declared capability ids when\n * the vocabulary can be graded against at all, `null` when it cannot.\n *\n * Exported because the suppression is not this module's private business — the\n * use-case axis asks the same question about the same file\n * (`commands/validate/fleet/landscape.ts` hands the answer to\n * `usecases/capability-tag.ts`), and a hand-rolled\n * `present && invalid === undefined ? [...byId.keys()] : null` at each site is\n * three copies of one rule. The failure that costs is not hypothetical: the next\n * un-gradable state added to `CapabilityVocabulary` — \"present but partially\n * readable\" is the obvious one, since `readCapabilities` already treats a\n * non-mapping declaration body as `{}` — gets fixed wherever the greps land, and\n * any copy left behind answers with the whole key set. A half-read vocabulary\n * then reads as a complete one, and every `#cap-` tag whose capability lived in\n * the unreadable half becomes one `usecase.capability-unresolved` ERROR per\n * view: the cascade this ladder exists to prevent, arriving through the ladder.\n *\n * `null` rather than `[]`, and the two are never interchangeable: an empty list\n * is the real verdict \"this fleet declares no capabilities\" and every entry\n * fails against it, while `null` says there is nothing to grade against and\n * suspends the family. Callers that only need the boolean read `=== null`.\n */\nexport function gradableCapabilityIds(vocab: CapabilityVocabulary): readonly string[] | null {\n  if (!vocab.present || vocab.invalid !== undefined) return null;\n  return [...vocab.byId.keys()];\n}\n\n/** One unresolved entry: the requirement that wrote it, the entry, the close names. */\ninterface UnknownEntry {\n  requirement: string;\n  entry: string;\n  close: string[];\n}\n\n/** Non-REMOVED requirements' entries the vocabulary does not declare — or nothing, per the opt-in rule above. */\nfunction unknownEntries(reqs: Requirement[], vocab: CapabilityVocabulary): UnknownEntry[] {\n  const known = gradableCapabilityIds(vocab);\n  if (known === null) return [];\n  const out: UnknownEntry[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const entry of r.capabilities) {\n      if (vocab.byId.has(entry)) continue;\n      out.push({ requirement: r.name, entry, close: closeIds(entry, known) });\n    }\n  }\n  return out;\n}\n\nfunction unknownMessage(where: string, u: UnknownEntry): string {\n  return (\n    `${where}: requirement '${u.requirement}' — Capability: '${u.entry}' is declared neither in architecture/capabilities.yaml nor as capabilities/${u.entry}/spec.md` +\n    (u.close.length > 0\n      ? `. Did you mean: ${u.close.join(\", \")}?`\n      : \". Declare it in either — a name alone is a `capabilities: {<id>: {description, owner}}` entry, a name with prose behind it is the document — or fix the spelling\")\n  );\n}\n\n/**\n * `capability.unknown` as validate sees it — an ERROR, the same grade as\n * `Requires:` and for its reason: an invented capability reads exactly like a\n * real one in the requirement and in every rollup built over it.\n */\nexport function capabilityUnknownFindings(\n  reqs: Requirement[],\n  target: CapabilityTarget,\n  vocab: CapabilityVocabulary,\n): Finding[] {\n  return unknownEntries(reqs, vocab).map((u) => ({\n    severity: \"error\" as const,\n    code: \"capability.unknown\",\n    subject: target.subject,\n    message: unknownMessage(target.where, u),\n  }));\n}\n\n/**\n * The same rule shaped as coherence Issues, for a feature's delta documents: a\n * delta requirement naming an undeclared capability would merge a join that\n * resolves to nothing, so it gates `loam archive` like other errors and stays\n * `--approve`-overridable. The one new archive gate of this axis.\n */\nexport function capabilityUnknownIssues(\n  reqs: Requirement[],\n  target: CapabilityTarget,\n  vocab: CapabilityVocabulary,\n): Issue[] {\n  return unknownEntries(reqs, vocab).map((u) => ({\n    severity: \"error\" as const,\n    code: \"capability.unknown\" as const,\n    subject: target.subject,\n    message: unknownMessage(target.where, u),\n  }));\n}\n\n/**\n * `capability.invalid` — the whole run's ONE finding about an unreadable\n * vocabulary, spelling the expected shape. Every grade that RESOLVES AGAINST\n * the vocabulary stays suspended behind it (see the module comment); the\n * authored tree's own grades do not, because none of them consults it — a\n * directory holding no document, a requirement without a stable id and a\n * requirement carrying a service-level join are facts about files that a broken\n * YAML does not make untrue, and hiding them until an unrelated file parses is\n * suppression without the cascade that justifies it.\n */\nexport function invalidVocabularyFinding(vocab: CapabilityVocabulary): Finding | null {\n  if (vocab.invalid === undefined) return null;\n  return {\n    severity: \"error\",\n    code: \"capability.invalid\",\n    message:\n      `landscape: architecture/capabilities.yaml does not read as a vocabulary — ${vocab.invalid}. ` +\n      \"Every `Capability:` line in the fleet resolves against this file, so the whole capability family is suspended until it parses — fix the YAML first. \" +\n      \"The shape is `capabilities: {<id>: {description, owner}}`, ids flat keys with `/` allowed for nesting.\",\n  };\n}\n\n/**\n * `capability.unrealized` — ONE warn per declared capability no living\n * non-REMOVED requirement names, subject = the id, sorted with compareIds.\n * Per capability rather than one rollup finding with details[] (the\n * permissions.unenforced shape) because the roadmap's own exit criterion is\n * 'one warning per capability, not one per service' — each is a distinct\n * promise nobody implemented, or a distinct word nobody adopted.\n */\nexport function unrealizedFindings(vocab: CapabilityVocabulary, used: ReadonlySet<string>): Finding[] {\n  const declared = gradableCapabilityIds(vocab);\n  if (declared === null) return [];\n  return declared\n    .filter((id) => !used.has(id))\n    .sort(compareIds)\n    .map((id) => ({\n      severity: \"warn\" as const,\n      code: \"capability.unrealized\",\n      subject: id,\n      message:\n        `landscape: capability '${id}' is declared in ${declaredIn(vocab, id)} and nothing in the fleet realizes it — ` +\n        \"no living requirement names it with `Capability:` or `Realizes:`, and no `#cap-`/`#req-` tagged flow keeps one of its promises. \" +\n        \"Either a promise nobody implemented or a word nobody adopted; write the requirement that realizes it, draw the flow that keeps it, or drop the declaration\",\n    }));\n}\n\n/**\n * Where an id was declared, spelled for a message. The fix differs by side —\n * a YAML line is deleted, a document is deleted with its directory — and a\n * message naming the wrong file sends its reader to edit something that is not\n * there. `both` names both because either alone would leave the id declared.\n */\nfunction declaredIn(vocab: CapabilityVocabulary, id: string): string {\n  const source = vocab.byId.get(id)?.source;\n  if (source === \"tree\") return `capabilities/${id}/spec.md`;\n  if (source === \"both\") return `architecture/capabilities.yaml and capabilities/${id}/spec.md`;\n  return \"architecture/capabilities.yaml\";\n}\n\n/* ------------------------------------------------------------------ */\n/* The authored tree — the documents themselves, graded on their own    */\n/* terms rather than on the join any requirement makes to them.         */\n/* ------------------------------------------------------------------ */\n\n/**\n * `capability.doc-missing` — a directory in a `capabilities/` tree that holds no\n * `spec.md` and has no capability beneath it.\n *\n * WARN, not error, and the severity is the whole judgement: the state it names\n * is what `mkdir` leaves behind halfway through creating a capability, and a\n * half-finished authoring step must not fail somebody else's `loam validate`\n * on the same tree. What makes it worth a finding at all is that the directory\n * LOOKS declared — a reader browsing `capabilities/` counts it, and a\n * `Capability:` line naming it still reports `capability.unknown`, which is the\n * confusing pair this warning exists to join up.\n *\n * BOTH TREES EARN IT, and `featureDirName` is which one. The same walk reads\n * `features/<dir>/capabilities/`, so the same `mkdir` leaves the same shape\n * there — quieter, not louder: an empty directory is not a delta, so the delta\n * algebra, the merge and `loam show` alike do not see it and the business change\n * ships as nothing at exit 0. One code, one mistake; two messages, because the\n * path and the fix differ. It is the DIRECTORY name and not the feature id\n * (`FEAT-1-split` is where the directory is), and `undocumented` is spelled from\n * the WALK'S root — literally `capabilities/…` on both sides — so a feature's\n * entry is re-rooted here or the message names a path nobody can open.\n */\nexport function docMissingFindings(tree: CapabilityTree, featureDirName?: string): Finding[] {\n  return tree.undocumented.map((walked) => {\n    const path = featureDirName === undefined ? walked : `features/${featureDirName}/${walked}`;\n    const rest =\n      featureDirName === undefined\n        ? \"so this one declares nothing and a requirement naming it still reports capability.unknown. \" +\n          `Write ${path}/spec.md (the narrative, then \\`## Requirements\\`), or remove the directory.`\n        : \"so this one changes nothing — the archive merges the capability deltas the walk FINDS, and an empty directory is not one. \" +\n          `Write ${path}/spec.md (a \\`## ADDED Requirements\\` section), or remove the directory.`;\n    return {\n      severity: \"warn\" as const,\n      code: \"capability.doc-missing\",\n      subject: path,\n      message: `${path}/ holds no spec.md and no capability beneath it — a directory under capabilities/ is a capability only when it holds the document, ${rest}`,\n    };\n  });\n}\n\n/**\n * The service-level joins, and the whole of what \"names no service\" is checked\n * as. Each entry is a `Requirement` field that is non-empty exactly when the\n * requirement wrote the line and named something in it.\n *\n * THE PROSE RULE IS NOT CHECKED AND MUST NOT BE FAKED. \"A capability\n * requirement names no service\" is an authoring rule about wording, and the\n * only mechanical reading of it — scanning the text for a declared service id —\n * is a heuristic that convicts a payments capability for the word \"payments\".\n * loam refuses that class of check everywhere else and refuses it here; PR\n * review holds the prose. What IS exact is the structural half: these four\n * lines resolve against a SERVICE's contract and model, so a requirement\n * carrying one has already left the business altitude whatever its wording\n * says. `Requires:` is deliberately absent — a permission is a domain fact\n * (\"who may see a profile\"), observable outside the fleet, and gating a\n * capability requirement on one is legitimate.\n */\nconst SERVICE_JOINS = [\n  { field: \"operations\", line: \"Operations:\", names: \"an operationId in a service's openapi.yaml\" },\n  { field: \"covers\", line: \"Covers:\", names: \"a C4 element, edge or health signal\" },\n  { field: \"publishes\", line: \"Publishes:\", names: \"an AsyncAPI message a service produces\" },\n  { field: \"consumes\", line: \"Consumes:\", names: \"an AsyncAPI message a service consumes\" },\n] as const satisfies ReadonlyArray<{ field: keyof Requirement; line: string; names: string }>;\n\n/**\n * The two joins that point INTO the capability tree, and are therefore inert\n * written inside it.\n *\n * Not \"wrong at this altitude\" like the four above — these are the axis's own\n * lines. They are refused here because nothing reads them: `capabilityRollup`\n * joins SERVICE requirements to capabilities, so a `Capability:` line in a\n * capability document is a requirement claiming the document it is already in,\n * and a `Realizes:` line there points at a promise loam will never see anybody\n * keep. Both parse, both look exactly like the working joins one directory\n * over, and both would sit in a reviewed document meaning nothing.\n *\n * A capability realizing ANOTHER capability's requirement — a nested\n * `payments/refunds` serving a promise made by `payments` — is a real idea and\n * is deliberately not being smuggled in as a line that happens to parse. It\n * would need a design: a second corpus of joins, its own cycle rule, and an\n * answer for what `capability.requirement-unrealized` means when the realizer\n * is itself unrealized. Refusing the line now is what keeps that decision open.\n */\nconst INTERNAL_JOINS = [\n  {\n    field: \"capabilities\",\n    line: \"Capability:\",\n    why: \"the rollup joins SERVICE requirements to capabilities, so written here it claims the document it is already in\",\n  },\n  {\n    field: \"realizes\",\n    line: \"Realizes:\",\n    why: \"a capability requirement is what gets realized, not what realizes — nothing reads this line inside the tree\",\n  },\n] as const satisfies ReadonlyArray<{ field: keyof Requirement; line: string; why: string }>;\n\n/**\n * Both grades a capability document earns on its own: every requirement needs\n * a stable id, and none may carry a service-level join.\n *\n * `where` is the document's repo-relative path and `subject` the capability id,\n * so a `--json` consumer can group by capability while a reader gets the file.\n * The two grades ride one walk because they ask about the same requirements and\n * a second pass is a second chance to disagree about which ones are graded.\n *\n * `where` DEFAULTS to the living spelling; `capabilities/delta/doc.ts` overrides\n * it to grade the same requirements inside a feature's own capability delta and\n * file them as archive Issues. A parameter rather than a second function because\n * these messages are what a reader acts on, and two copies drift. The return type\n * states severity and code exactly for that caller: the Finding→Issue conversion\n * needs no cast, and a fourth grade added here cannot silently stop gating.\n */\ntype DocGrade = Finding & { severity: \"error\"; code: CapabilityDocCode };\n\nexport function capabilityDocFindings(reqs: Requirement[], id: string, where = `capabilities/${id}/spec.md`): DocGrade[] {\n  const findings: DocGrade[] = [];\n  for (const r of reqs) {\n    if (r.id === undefined) {\n      findings.push({\n        severity: \"error\",\n        code: \"capability.requirement-unidentified\",\n        subject: id,\n        message:\n          `${where}: requirement '${r.name}' has no \\`Requirement-ID:\\` line. ` +\n          \"A capability document outlives every service that realizes it, so its requirements are identified by a stable id rather than by their heading — \" +\n          \"without one, rewording the heading is a removal and an addition, and every join made to it breaks silently. \" +\n          \"Add `Requirement-ID: <id>` as the first body line.\",\n      });\n    }\n    for (const join of SERVICE_JOINS) {\n      if (r[join.field].length === 0) continue;\n      findings.push({\n        severity: \"error\",\n        code: \"capability.requirement-service-scoped\",\n        subject: id,\n        message:\n          `${where}: requirement '${r.name}' carries \\`${join.line}\\`, which names ${join.names}. ` +\n          \"A capability requirement must be observable outside the fleet — a promise a customer could check — and these lines resolve against one service's own contract, \" +\n          \"so a requirement carrying one is a service requirement filed at the wrong altitude. \" +\n          \"Move it into that service's spec.md, where the line resolves; what belongs here is the promise, not the mechanism.\",\n      });\n    }\n    for (const join of INTERNAL_JOINS) {\n      if (r[join.field].length === 0) continue;\n      findings.push({\n        severity: \"error\",\n        code: \"capability.requirement-inert-join\",\n        subject: id,\n        message:\n          `${where}: requirement '${r.name}' carries \\`${join.line}\\`, which does nothing in a capability document — ` +\n          `${join.why}. It parses and reads exactly like the working join one directory over, which is why it is refused ` +\n          \"rather than ignored. Delete the line; the join that matters is written on the SERVICE requirement, as \" +\n          `\\`Realizes: ${id}#${r.id ?? \"<Requirement-ID>\"}\\`.`,\n      });\n    }\n  }\n  return findings;\n}\n\n/**\n * The requirement ids each capability document declares, with THE LADDER\n * already applied — the one shape `Realizes:` is ever resolved against.\n *\n * Built here rather than at the three call sites for the reason\n * `gradableCapabilityIds` above is exported: the suppression rule and the index\n * it guards belong together. A caller that composed them itself would be a\n * fourth place where \"can this be graded at all\" is decided, and the first one\n * to be forgotten when a fifth un-gradable vocabulary state arrives.\n *\n * A requirement with no `Requirement-ID:` is absent from the index, so a\n * `Realizes:` entry naming its heading does not resolve. That is deliberate and\n * not a gap: an unidentified capability requirement is already an ERROR\n * (`capability.requirement-unidentified`), and letting a heading work as an\n * address would quietly reintroduce the identity-by-heading the tree exists to\n * refuse. REMOVED is skipped for the reason every other reader skips it.\n *\n * The reads are NOT wrapped: a `capabilities/<id>/spec.md` that cannot be\n * decoded takes the run down exactly as a service spec does — the rule\n * `capabilityFleetFindings` already states one directory over.\n */\nexport async function capabilityRequirementIndex(\n  vocab: CapabilityVocabulary,\n  read: (path: string) => Promise<Requirement[]>,\n): Promise<CapabilityRequirementIndex> {\n  const declared = gradableCapabilityIds(vocab);\n  const byCapability = new Map<string, ReadonlySet<string>>();\n  const digests = new Map<string, ReadonlyMap<string, string>>();\n  if (declared === null) return { declared, byCapability, digests };\n  for (const doc of vocab.tree.docs) {\n    const reqs = await read(doc.spec);\n    // ONE pass fills both, which is what keeps them from disagreeing: an id\n    // reaches the set and the digest map in the same iteration or reaches\n    // neither. The skip rule is stated once, above the loop body it guards.\n    const kept = reqs.filter((r) => r.kind !== \"REMOVED\" && r.id !== undefined);\n    byCapability.set(doc.id, new Set(kept.map((r) => r.id!)));\n    digests.set(doc.id, new Map(kept.map((r) => [r.id!, requirementDigest(r)])));\n  }\n  return { declared, byCapability, digests };\n}\n"]}
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../../../src/core/capabilities/findings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The capability grades, in every direction the axis is graded: a `Capability:`\n * entry the vocabulary does not declare, a vocabulary nobody can read, a\n * declared capability no living requirement realizes, a directory that declares\n * nothing, and the two rules an authored capability document itself must keep.\n * Values only — core never prints — and the join rule written ONCE, as the\n * Issue coherence gates on, which validate files as a Finding unchanged (an\n * Issue is assignable to a Finding), with a literal code so\n * test/codes-drift.test.ts can collect it. It used to be shaped twice, a\n * Finding twin and an Issue twin with byte-identical bodies; one function over\n * one message builder is what keeps the finding an author reads at the service\n * target and the refusal they hit at `loam archive` from drifting apart.\n *\n * The opt-in rule lives here, and it deliberately DIVERGES from `Requires:`.\n * There the LINE is the opt-in: a `Requires:` entry against a missing\n * permissions.yaml errors, because an authorization join that resolves against\n * nothing is the failure that axis exists to prevent. Here the FLEET'S OWN\n * FILES are the opt-in — `architecture/capabilities.yaml`, the `capabilities/`\n * tree, or both — so a fleet holding neither stays finding-free however many\n * `Capability:` lines its requirements already carry. (The roadmap's exit\n * criterion was written when the YAML was the only side and says 'a fleet with\n * no architecture/capabilities.yaml produces no capability findings at all';\n * the authored tree is the second way to opt in, and `CapabilityVocabulary.present`\n * is where the two are combined.) An INVALID vocabulary is also silence for the\n * per-entry grades — `capability.invalid` is the honest finding there, and\n * grading a hundred entries against a file nobody can read is the cascade that\n * suppression exists to stop.\n */\nimport { closeIds } from \"../c4/arch.js\";\nimport { compareIds } from \"../repo/entries.js\";\nimport { requirementDigest, type Requirement } from \"../document/spec.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport type { CapabilityDocCode, Issue } from \"../vocabulary/issue.js\";\nimport type { CapabilityVocabulary } from \"./capabilities.js\";\nimport type { CapabilityTree } from \"./tree.js\";\nimport type { CapabilityRequirementIndex } from \"./realizes/join.js\";\n\n/** Which document is being graded, and under whose name the finding is filed. */\nexport interface CapabilityTarget {\n  where: string;\n  subject: string;\n}\n\n/**\n * THE LADDER, and the only place it is applied: the declared capability ids when\n * the vocabulary can be graded against at all, `null` when it cannot.\n *\n * Exported because the suppression is not this module's private business — the\n * use-case axis asks the same question about the same file\n * (`commands/validate/fleet/map/usecases.ts` hands the answer to\n * `core/usecases/grade/capability-tag.ts`, and `core/usecases/delta/claims.ts`\n * to the same grader for a feature's own flows), and a hand-rolled\n * `present && invalid === undefined ? [...byId.keys()] : null` at each site is\n * three copies of one rule. The failure that costs is not hypothetical: the next\n * un-gradable state added to `CapabilityVocabulary` — \"present but partially\n * readable\" is the obvious one, since `readCapabilities` already treats a\n * non-mapping declaration body as `{}` — gets fixed wherever the greps land, and\n * any copy left behind answers with the whole key set. A half-read vocabulary\n * then reads as a complete one, and every `#cap-` tag whose capability lived in\n * the unreadable half becomes one `usecase.capability-unresolved` ERROR per\n * view: the cascade this ladder exists to prevent, arriving through the ladder.\n *\n * `null` rather than `[]`, and the two are never interchangeable: an empty list\n * is the real verdict \"this fleet declares no capabilities\" and every entry\n * fails against it, while `null` says there is nothing to grade against and\n * suspends the family. Callers that only need the boolean read `=== null`.\n */\nexport function gradableCapabilityIds(vocab: CapabilityVocabulary): readonly string[] | null {\n  if (!vocab.present || vocab.invalid !== undefined) return null;\n  return [...vocab.byId.keys()];\n}\n\n/** One unresolved entry: the requirement that wrote it, the entry, the close names. */\ninterface UnknownEntry {\n  requirement: string;\n  entry: string;\n  close: string[];\n}\n\n/** Non-REMOVED requirements' entries the vocabulary does not declare — or nothing, per the opt-in rule above. */\nfunction unknownEntries(reqs: Requirement[], vocab: CapabilityVocabulary): UnknownEntry[] {\n  const known = gradableCapabilityIds(vocab);\n  if (known === null) return [];\n  const out: UnknownEntry[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const entry of r.capabilities) {\n      if (vocab.byId.has(entry)) continue;\n      out.push({ requirement: r.name, entry, close: closeIds(entry, known) });\n    }\n  }\n  return out;\n}\n\nfunction unknownMessage(where: string, u: UnknownEntry): string {\n  return (\n    `${where}: requirement '${u.requirement}' — Capability: '${u.entry}' is declared neither in architecture/capabilities.yaml nor as capabilities/${u.entry}/spec.md` +\n    (u.close.length > 0\n      ? `. Did you mean: ${u.close.join(\", \")}?`\n      : \". Declare it in either — a name alone is a `capabilities: {<id>: {description, owner}}` entry, a name with prose behind it is the document — or fix the spelling\")\n  );\n}\n\n/**\n * `capability.unknown` — an ERROR, the same grade as `Requires:` and for its\n * reason: an invented capability reads exactly like a real one in the\n * requirement and in every rollup built over it. Validate files it as a\n * Finding at the service target. For a feature's delta documents it is a\n * coherence Issue: a delta requirement naming an undeclared capability would\n * merge a join that resolves to nothing, so it gates `loam archive` like other\n * errors and stays `--approve`-overridable. The one new archive gate of this\n * axis.\n */\nexport function capabilityUnknownIssues(\n  reqs: Requirement[],\n  target: CapabilityTarget,\n  vocab: CapabilityVocabulary,\n): Issue[] {\n  return unknownEntries(reqs, vocab).map((u) => ({\n    severity: \"error\" as const,\n    code: \"capability.unknown\" as const,\n    subject: target.subject,\n    message: unknownMessage(target.where, u),\n  }));\n}\n\n/**\n * `capability.invalid` — the whole run's ONE finding about an unreadable\n * vocabulary, spelling the expected shape. Every grade that RESOLVES AGAINST\n * the vocabulary stays suspended behind it (see the module comment); the\n * authored tree's own grades do not, because none of them consults it — a\n * directory holding no document, a requirement without a stable id and a\n * requirement carrying a service-level join are facts about files that a broken\n * YAML does not make untrue, and hiding them until an unrelated file parses is\n * suppression without the cascade that justifies it.\n */\nexport function invalidVocabularyFinding(vocab: CapabilityVocabulary): Finding | null {\n  if (vocab.invalid === undefined) return null;\n  return {\n    severity: \"error\",\n    code: \"capability.invalid\",\n    message:\n      `landscape: architecture/capabilities.yaml does not read as a vocabulary — ${vocab.invalid}. ` +\n      \"Every `Capability:` line in the fleet resolves against this file, so the whole capability family is suspended until it parses — fix the YAML first. \" +\n      \"The shape is `capabilities: {<id>: {description, owner}}`, ids flat keys with `/` allowed for nesting.\",\n  };\n}\n\n/**\n * `capability.unrealized` — ONE warn per declared capability no living\n * non-REMOVED requirement names, subject = the id, sorted with compareIds.\n * Per capability rather than one rollup finding with details[] (the\n * permissions.unenforced shape) because the roadmap's own exit criterion is\n * 'one warning per capability, not one per service' — each is a distinct\n * promise nobody implemented, or a distinct word nobody adopted.\n */\nexport function unrealizedFindings(vocab: CapabilityVocabulary, used: ReadonlySet<string>): Finding[] {\n  const declared = gradableCapabilityIds(vocab);\n  if (declared === null) return [];\n  return declared\n    .filter((id) => !used.has(id))\n    .sort(compareIds)\n    .map((id) => ({\n      severity: \"warn\" as const,\n      code: \"capability.unrealized\",\n      subject: id,\n      message:\n        `landscape: capability '${id}' is declared in ${declaredIn(vocab, id)} and nothing in the fleet realizes it — ` +\n        \"no living requirement names it with `Capability:` or `Realizes:`, and no `#cap-`/`#req-` tagged flow keeps one of its promises. \" +\n        \"Either a promise nobody implemented or a word nobody adopted; write the requirement that realizes it, draw the flow that keeps it, or drop the declaration\",\n    }));\n}\n\n/**\n * Where an id was declared, spelled for a message. The fix differs by side —\n * a YAML line is deleted, a document is deleted with its directory — and a\n * message naming the wrong file sends its reader to edit something that is not\n * there. `both` names both because either alone would leave the id declared.\n */\nfunction declaredIn(vocab: CapabilityVocabulary, id: string): string {\n  const source = vocab.byId.get(id)?.source;\n  if (source === \"tree\") return `capabilities/${id}/spec.md`;\n  if (source === \"both\") return `architecture/capabilities.yaml and capabilities/${id}/spec.md`;\n  return \"architecture/capabilities.yaml\";\n}\n\n/* ------------------------------------------------------------------ */\n/* The authored tree — the documents themselves, graded on their own    */\n/* terms rather than on the join any requirement makes to them.         */\n/* ------------------------------------------------------------------ */\n\n/**\n * `capability.doc-missing` — a directory in a `capabilities/` tree that holds no\n * `spec.md` and has no capability beneath it.\n *\n * WARN, not error, and the severity is the whole judgement: the state it names\n * is what `mkdir` leaves behind halfway through creating a capability, and a\n * half-finished authoring step must not fail somebody else's `loam validate`\n * on the same tree. What makes it worth a finding at all is that the directory\n * LOOKS declared — a reader browsing `capabilities/` counts it, and a\n * `Capability:` line naming it still reports `capability.unknown`, which is the\n * confusing pair this warning exists to join up.\n *\n * BOTH TREES EARN IT, and `featureDirName` is which one. The same walk reads\n * `features/<dir>/capabilities/`, so the same `mkdir` leaves the same shape\n * there — quieter, not louder: an empty directory is not a delta, so the delta\n * algebra, the merge and `loam show` alike do not see it and the business change\n * ships as nothing at exit 0. One code, one mistake; two messages, because the\n * path and the fix differ. It is the DIRECTORY name and not the feature id\n * (`FEAT-1-split` is where the directory is), and `undocumented` is spelled from\n * the WALK'S root — literally `capabilities/…` on both sides — so a feature's\n * entry is re-rooted here or the message names a path nobody can open.\n */\nexport function docMissingFindings(tree: CapabilityTree, featureDirName?: string): Finding[] {\n  return tree.undocumented.map((walked) => {\n    const path = featureDirName === undefined ? walked : `features/${featureDirName}/${walked}`;\n    const rest =\n      featureDirName === undefined\n        ? \"so this one declares nothing and a requirement naming it still reports capability.unknown. \" +\n          `Write ${path}/spec.md (the narrative, then \\`## Requirements\\`), or remove the directory.`\n        : \"so this one changes nothing — the archive merges the capability deltas the walk FINDS, and an empty directory is not one. \" +\n          `Write ${path}/spec.md (a \\`## ADDED Requirements\\` section), or remove the directory.`;\n    return {\n      severity: \"warn\" as const,\n      code: \"capability.doc-missing\",\n      subject: path,\n      message: `${path}/ holds no spec.md and no capability beneath it — a directory under capabilities/ is a capability only when it holds the document, ${rest}`,\n    };\n  });\n}\n\n/**\n * The service-level joins, and the whole of what \"names no service\" is checked\n * as. Each entry is a `Requirement` field that is non-empty exactly when the\n * requirement wrote the line and named something in it.\n *\n * THE PROSE RULE IS NOT CHECKED AND MUST NOT BE FAKED. \"A capability\n * requirement names no service\" is an authoring rule about wording, and the\n * only mechanical reading of it — scanning the text for a declared service id —\n * is a heuristic that convicts a payments capability for the word \"payments\".\n * loam refuses that class of check everywhere else and refuses it here; PR\n * review holds the prose. What IS exact is the structural half: these four\n * lines resolve against a SERVICE's contract and model, so a requirement\n * carrying one has already left the business altitude whatever its wording\n * says. `Requires:` is deliberately absent — a permission is a domain fact\n * (\"who may see a profile\"), observable outside the fleet, and gating a\n * capability requirement on one is legitimate.\n */\nconst SERVICE_JOINS = [\n  { field: \"operations\", line: \"Operations:\", names: \"an operationId in a service's openapi.yaml\" },\n  { field: \"covers\", line: \"Covers:\", names: \"a C4 element, edge or health signal\" },\n  { field: \"publishes\", line: \"Publishes:\", names: \"an AsyncAPI message a service produces\" },\n  { field: \"consumes\", line: \"Consumes:\", names: \"an AsyncAPI message a service consumes\" },\n] as const satisfies ReadonlyArray<{ field: keyof Requirement; line: string; names: string }>;\n\n/**\n * The two joins that point INTO the capability tree, and are therefore inert\n * written inside it.\n *\n * Not \"wrong at this altitude\" like the four above — these are the axis's own\n * lines. They are refused here because nothing reads them: `capabilityRollup`\n * joins SERVICE requirements to capabilities, so a `Capability:` line in a\n * capability document is a requirement claiming the document it is already in,\n * and a `Realizes:` line there points at a promise loam will never see anybody\n * keep. Both parse, both look exactly like the working joins one directory\n * over, and both would sit in a reviewed document meaning nothing.\n *\n * A capability realizing ANOTHER capability's requirement — a nested\n * `payments/refunds` serving a promise made by `payments` — is a real idea and\n * is deliberately not being smuggled in as a line that happens to parse. It\n * would need a design: a second corpus of joins, its own cycle rule, and an\n * answer for what `capability.requirement-unrealized` means when the realizer\n * is itself unrealized. Refusing the line now is what keeps that decision open.\n */\nconst INTERNAL_JOINS = [\n  {\n    field: \"capabilities\",\n    line: \"Capability:\",\n    why: \"the rollup joins SERVICE requirements to capabilities, so written here it claims the document it is already in\",\n  },\n  {\n    field: \"realizes\",\n    line: \"Realizes:\",\n    why: \"a capability requirement is what gets realized, not what realizes — nothing reads this line inside the tree\",\n  },\n] as const satisfies ReadonlyArray<{ field: keyof Requirement; line: string; why: string }>;\n\n/**\n * Both grades a capability document earns on its own: every requirement needs\n * a stable id, and none may carry a service-level join.\n *\n * `where` is the document's repo-relative path and `subject` the capability id,\n * so a `--json` consumer can group by capability while a reader gets the file.\n * The two grades ride one walk because they ask about the same requirements and\n * a second pass is a second chance to disagree about which ones are graded.\n *\n * `where` DEFAULTS to the living spelling; `capabilities/delta/doc.ts` overrides\n * it to grade the same requirements inside a feature's own capability delta and\n * file them as archive Issues. A parameter rather than a second function because\n * these messages are what a reader acts on, and two copies drift. The return type\n * states severity and code exactly for that caller: the Finding→Issue hand-off is\n * a plain assignment — no cast, no copy — and a fourth grade added here cannot\n * silently stop gating.\n */\ntype DocGrade = Finding & { severity: \"error\"; code: CapabilityDocCode };\n\nexport function capabilityDocFindings(reqs: Requirement[], id: string, where = `capabilities/${id}/spec.md`): DocGrade[] {\n  const findings: DocGrade[] = [];\n  for (const r of reqs) {\n    if (r.id === undefined) {\n      findings.push({\n        severity: \"error\",\n        code: \"capability.requirement-unidentified\",\n        subject: id,\n        message:\n          `${where}: requirement '${r.name}' has no \\`Requirement-ID:\\` line. ` +\n          \"A capability document outlives every service that realizes it, so its requirements are identified by a stable id rather than by their heading — \" +\n          \"without one, rewording the heading is a removal and an addition, and every join made to it breaks silently. \" +\n          \"Add `Requirement-ID: <id>` as the first body line.\",\n      });\n    }\n    for (const join of SERVICE_JOINS) {\n      if (r[join.field].length === 0) continue;\n      findings.push({\n        severity: \"error\",\n        code: \"capability.requirement-service-scoped\",\n        subject: id,\n        message:\n          `${where}: requirement '${r.name}' carries \\`${join.line}\\`, which names ${join.names}. ` +\n          \"A capability requirement must be observable outside the fleet — a promise a customer could check — and these lines resolve against one service's own contract, \" +\n          \"so a requirement carrying one is a service requirement filed at the wrong altitude. \" +\n          \"Move it into that service's spec.md, where the line resolves; what belongs here is the promise, not the mechanism.\",\n      });\n    }\n    for (const join of INTERNAL_JOINS) {\n      if (r[join.field].length === 0) continue;\n      findings.push({\n        severity: \"error\",\n        code: \"capability.requirement-inert-join\",\n        subject: id,\n        message:\n          `${where}: requirement '${r.name}' carries \\`${join.line}\\`, which does nothing in a capability document — ` +\n          `${join.why}. It parses and reads exactly like the working join one directory over, which is why it is refused ` +\n          \"rather than ignored. Delete the line; the join that matters is written on the SERVICE requirement, as \" +\n          `\\`Realizes: ${id}#${r.id ?? \"<Requirement-ID>\"}\\`.`,\n      });\n    }\n  }\n  return findings;\n}\n\n/**\n * The requirement ids each capability document declares, with THE LADDER\n * already applied — the one shape `Realizes:` is ever resolved against.\n *\n * Built here rather than at the three call sites for the reason\n * `gradableCapabilityIds` above is exported: the suppression rule and the index\n * it guards belong together. A caller that composed them itself would be a\n * fourth place where \"can this be graded at all\" is decided, and the first one\n * to be forgotten when a fifth un-gradable vocabulary state arrives.\n *\n * A requirement with no `Requirement-ID:` is absent from the index, so a\n * `Realizes:` entry naming its heading does not resolve. That is deliberate and\n * not a gap: an unidentified capability requirement is already an ERROR\n * (`capability.requirement-unidentified`), and letting a heading work as an\n * address would quietly reintroduce the identity-by-heading the tree exists to\n * refuse. REMOVED is skipped for the reason every other reader skips it.\n *\n * The reads are NOT wrapped: a `capabilities/<id>/spec.md` that cannot be\n * decoded takes the run down exactly as a service spec does — the rule\n * `capabilityFleetFindings` already states one directory over.\n */\nexport async function capabilityRequirementIndex(\n  vocab: CapabilityVocabulary,\n  read: (path: string) => Promise<Requirement[]>,\n): Promise<CapabilityRequirementIndex> {\n  const declared = gradableCapabilityIds(vocab);\n  const byCapability = new Map<string, ReadonlySet<string>>();\n  const digests = new Map<string, ReadonlyMap<string, string>>();\n  if (declared === null) return { declared, byCapability, digests };\n  for (const doc of vocab.tree.docs) {\n    const reqs = await read(doc.spec);\n    // ONE pass fills both, which is what keeps them from disagreeing: an id\n    // reaches the set and the digest map in the same iteration or reaches\n    // neither. The skip rule is stated once, above the loop body it guards.\n    const kept = reqs.filter((r) => r.kind !== \"REMOVED\" && r.id !== undefined);\n    byCapability.set(doc.id, new Set(kept.map((r) => r.id!)));\n    digests.set(doc.id, new Map(kept.map((r) => [r.id!, requirementDigest(r)])));\n  }\n  return { declared, byCapability, digests };\n}\n"]}

package/dist/core/capabilities/realizes/findings.js

@@ -2,12 +2,13 @@
  * The `Realizes:` grades, both directions: an entry that resolves to nothing,
  * and a capability requirement nothing realizes.
  *
- * Values only — core never prints — and the join rule shaped twice (Finding for
- * validate, Issue for coherence) from ONE message builder, exactly as
- * `../findings.ts` does for `capability.unknown`. Two shapes over one sentence
- * is the only arrangement in which a finding an author reads at the service
- * target and the refusal they hit at `loam archive` cannot describe the same
- * breach differently.
+ * Values only — core never prints — and the join rule written ONCE, as the
+ * Issue coherence gates on, which validate files as a Finding unchanged,
+ * exactly as `../findings.ts` does for `capability.unknown`. One function over
+ * ONE message builder is the only arrangement in which a finding an author
+ * reads at the service target and the refusal they hit at `loam archive`
+ * cannot describe the same breach differently — the Finding and Issue twins
+ * it replaced had byte-identical bodies.
  *
  * WHY THE DELTA SIDE GATES ARCHIVE. A delta requirement whose `Realizes:` entry
  * resolves to nothing would merge a join pointing at a promise that does not
@@ -72,20 +73,12 @@ function unresolvedEntries(reqs, index) {
     return out;
 }
 /**
- * `capability.realizes-unknown` as validate sees it — an ERROR, the grade its
- * two siblings already carry: a join that resolves to nothing reads exactly
- * like a working one in the requirement, in the rollup and in every answer
- * built over either.
+ * `capability.realizes-unknown` — an ERROR, the grade its two siblings already
+ * carry: a join that resolves to nothing reads exactly like a working one in
+ * the requirement, in the rollup and in every answer built over either. One
+ * function for validate's service target and a feature's delta documents —
+ * see the module comment.
  */
-export function realizesUnknownFindings(reqs, target, index) {
-    return unresolvedEntries(reqs, index).map((u) => ({
-        severity: "error",
-        code: "capability.realizes-unknown",
-        subject: target.subject,
-        message: unresolvedMessage(target.where, u.requirement, u.claim),
-    }));
-}
-/** The same rule shaped as coherence Issues, for a feature's delta documents — see the module comment. */
 export function realizesUnknownIssues(reqs, target, index) {
     return unresolvedEntries(reqs, index).map((u) => ({
         severity: "error",

package/dist/core/capabilities/realizes/findings.js.map

@@ -1 +1 @@
-{"version":3,"file":"findings.js","sourceRoot":"","sources":["../../../../src/core/capabilities/realizes/findings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAInD,OAAO,EAAE,eAAe,EAAuD,MAAM,WAAW,CAAC;AAgBjG;;;GAGG;AACH,SAAS,MAAM,CAAC,KAAsB;IACpC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,WAAW;YACd,OAAO,CACL,8FAA8F;gBAC9F,sGAAsG;gBACtG,4EAA4E,CAC7E,CAAC;QACJ,KAAK,oBAAoB;YACvB,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBAC3B,CAAC,CAAC,iDAAiD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBAC5E,CAAC,CAAC,iFAAiF;oBAC/E,sBAAsB,KAAK,CAAC,UAAU,+BAA+B,CAAC;QAC9E,KAAK,yBAAyB;YAC5B,OAAO,CACL,eAAe,KAAK,CAAC,UAAU,yCAAyC,KAAK,CAAC,UAAU,YAAY;gBACpG,kGAAkG;gBAClG,oDAAoD,CACrD,CAAC;QACJ,KAAK,kBAAkB;YACrB,OAAO,CACL,gBAAgB,KAAK,CAAC,UAAU,qDAAqD;gBACrF,oFAAoF,CACrF,CAAC;QACJ,KAAK,qBAAqB;YACxB,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBAC3B,CAAC,CAAC,gBAAgB,KAAK,CAAC,UAAU,gEAAgE,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBAC3H,CAAC,CAAC,gBAAgB,KAAK,CAAC,UAAU,kDAAkD;oBAChF,oDAAoD,CAAC;IAC/D,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAa,EAAE,WAAmB,EAAE,KAAsB;IACnF,OAAO,GAAG,KAAK,kBAAkB,WAAW,kBAAkB,KAAK,CAAC,KAAK,uBAAuB,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAClH,CAAC;AAQD;;;;;;;;;GASG;AACH,SAAS,iBAAiB,CAAC,IAAmB,EAAE,KAAiC;IAC/E,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QACnC,KAAK,MAAM,KAAK,IAAI,eAAe,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;YACvD,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;gBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAmB,EACnB,MAAyB,EACzB,KAAiC;IAEjC,OAAO,iBAAiB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAChD,QAAQ,EAAE,OAAgB;QAC1B,IAAI,EAAE,6BAA6B;QACnC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC;KACjE,CAAC,CAAC,CAAC;AACN,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,qBAAqB,CACnC,IAAmB,EACnB,MAAyB,EACzB,KAAiC;IAEjC,OAAO,iBAAiB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAChD,QAAQ,EAAE,OAAgB;QAC1B,IAAI,EAAE,6BAAsC;QAC5C,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC;KACjE,CAAC,CAAC,CAAC;AACN,CAAC;AAYD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAmB,EACnB,MAAyB,EACzB,KAAiC;IAEjC,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QACnC,KAAK,MAAM,KAAK,IAAI,eAAe,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;YACvD,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI;gBAAE,SAAS;YAChE,KAAK,CAAC,IAAI,CAAC;gBACT,WAAW,EAAE,CAAC,CAAC,IAAI;gBACnB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,UAAU,EAAE,KAAK,CAAC,UAAU;gBAC5B,MAAM,EAAE,KAAK,CAAC,WAAW;gBACzB,GAAG,EAAE,KAAK,CAAC,GAAI;gBACf,OAAO,EAAE,KAAK,CAAC,OAAQ;aACxB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACvB,QAAQ,EAAE,MAAe;QACzB,IAAI,EAAE,2BAA2B;QACjC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EACL,GAAG,MAAM,CAAC,KAAK,kBAAkB,CAAC,CAAC,WAAW,cAAc,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,MAAM,IAAI;YACxF,gEAAgE,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,OAAO,KAAK;YAC5F,0EAA0E;YAC1E,wBAAwB,CAAC,CAAC,UAAU,+CAA+C;YACnF,gFAAgF;KACnF,CAAC,CAAC,CAAC;AACN,CAAC;AAWD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,6BAA6B,CAAC,UAAmC;IAC/E,OAAO,CAAC,GAAG,UAAU,CAAC;SACnB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;SAChF,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,QAAQ,EAAE,MAAe;QACzB,IAAI,EAAE,mCAAmC;QACzC,OAAO,EAAE,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,EAAE,EAAE;QAClC,OAAO,EACL,2BAA2B,CAAC,CAAC,UAAU,eAAe,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,0CAA0C;YAChH,yCAAyC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,EAAE,IAAI;YACjE,sGAAsG;YACtG,kEAAkE;KACrE,CAAC,CAAC,CAAC;AACR,CAAC","sourcesContent":["/**\n * The `Realizes:` grades, both directions: an entry that resolves to nothing,\n * and a capability requirement nothing realizes.\n *\n * Values only — core never prints — and the join rule shaped twice (Finding for\n * validate, Issue for coherence) from ONE message builder, exactly as\n * `../findings.ts` does for `capability.unknown`. Two shapes over one sentence\n * is the only arrangement in which a finding an author reads at the service\n * target and the refusal they hit at `loam archive` cannot describe the same\n * breach differently.\n *\n * WHY THE DELTA SIDE GATES ARCHIVE. A delta requirement whose `Realizes:` entry\n * resolves to nothing would merge a join pointing at a promise that does not\n * exist, and the living document would then carry it looking exactly like a\n * working join — the same argument that made `capability.unknown` a gate.\n * `--approve` overrides it like any other error.\n */\nimport { compareIds } from \"../../repo/entries.js\";\nimport type { Requirement } from \"../../document/spec.js\";\nimport type { Finding } from \"../../vocabulary/report.js\";\nimport type { Issue } from \"../../vocabulary/issue.js\";\nimport { resolveRealizes, type CapabilityRequirementIndex, type RealizesClaim } from \"./join.js\";\n\n/** Which document is being graded, and under whose name the finding is filed. */\nexport interface RealizesTargetDoc {\n  where: string;\n  subject: string;\n}\n\n/**\n * An entry that did NOT resolve. Spelled as an exclusion rather than as a\n * second union so the arms cannot drift: adding a failure kind to\n * `RealizesClaim` makes `advice` below fail to compile until it says what to do\n * about it, which is exactly the reminder a new failure mode deserves.\n */\ntype UnresolvedClaim = Exclude<RealizesClaim, { kind: \"resolved\" }>;\n\n/**\n * The fix for one unresolved entry, as a sentence. Five arms, five different\n * repairs — the whole reason `RealizesClaim` is not collapsed to a boolean.\n */\nfunction advice(claim: UnresolvedClaim): string {\n  switch (claim.kind) {\n    case \"malformed\":\n      return (\n        \"an entry names a capability requirement and is spelled `<capability-id>#<Requirement-ID>` — \" +\n        \"the capability half addresses the document, because a Requirement-ID is unique only inside its own. \" +\n        \"To claim a theme rather than a promise, use the `Capability:` line instead\"\n      );\n    case \"unknown-capability\":\n      return claim.close.length > 0\n        ? `no such capability is declared. Did you mean: ${claim.close.join(\", \")}?`\n        : \"no such capability is declared — declare it in architecture/capabilities.yaml, \" +\n            `write capabilities/${claim.capability}/spec.md, or fix the spelling`;\n    case \"undocumented-capability\":\n      return (\n        `capability '${claim.capability}' is declared but has no capabilities/${claim.capability}/spec.md, ` +\n        \"so it carries no requirements to realize. Write the document — a name alone can be claimed with \" +\n        \"`Capability:`, but only a document can be realized\"\n      );\n    case \"empty-capability\":\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 \"unknown-requirement\":\n      return claim.close.length > 0\n        ? `capabilities/${claim.capability}/spec.md declares no requirement with that id. Did you mean: ${claim.close.join(\", \")}?`\n        : `capabilities/${claim.capability}/spec.md declares no requirement with that id — ` +\n            \"check the `Requirement-ID:` lines in that document\";\n  }\n}\n\nfunction unresolvedMessage(where: string, requirement: string, claim: UnresolvedClaim): string {\n  return `${where}: requirement '${requirement}' — Realizes: '${claim.entry}' does not resolve: ${advice(claim)}`;\n}\n\n/** One unresolved entry, with the requirement that wrote it. */\ninterface Unresolved {\n  requirement: string;\n  claim: UnresolvedClaim;\n}\n\n/**\n * Non-REMOVED requirements' entries that do not resolve — or nothing at all\n * when the vocabulary cannot be graded against, which `resolveRealizes` answers\n * by returning no claims.\n *\n * REMOVED is skipped for the reason its `Capability:` sibling skips it: a\n * requirement on its way out of the living document is not making a claim about\n * the future, and grading its joins would refuse the very change that removes\n * the last consumer of a retired capability requirement.\n */\nfunction unresolvedEntries(reqs: Requirement[], index: CapabilityRequirementIndex): Unresolved[] {\n  const out: Unresolved[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const claim of resolveRealizes(r.realizes, index)) {\n      if (claim.kind !== \"resolved\") out.push({ requirement: r.name, claim });\n    }\n  }\n  return out;\n}\n\n/**\n * `capability.realizes-unknown` as validate sees it — an ERROR, the grade its\n * two siblings already carry: a join that resolves to nothing reads exactly\n * like a working one in the requirement, in the rollup and in every answer\n * built over either.\n */\nexport function realizesUnknownFindings(\n  reqs: Requirement[],\n  target: RealizesTargetDoc,\n  index: CapabilityRequirementIndex,\n): Finding[] {\n  return unresolvedEntries(reqs, index).map((u) => ({\n    severity: \"error\" as const,\n    code: \"capability.realizes-unknown\",\n    subject: target.subject,\n    message: unresolvedMessage(target.where, u.requirement, u.claim),\n  }));\n}\n\n/** The same rule shaped as coherence Issues, for a feature's delta documents — see the module comment. */\nexport function realizesUnknownIssues(\n  reqs: Requirement[],\n  target: RealizesTargetDoc,\n  index: CapabilityRequirementIndex,\n): Issue[] {\n  return unresolvedEntries(reqs, index).map((u) => ({\n    severity: \"error\" as const,\n    code: \"capability.realizes-unknown\" as const,\n    subject: target.subject,\n    message: unresolvedMessage(target.where, u.requirement, u.claim),\n  }));\n}\n\n/** One resolved entry whose pin no longer matches the promise it points at. */\ninterface StaleEntry {\n  requirement: string;\n  entry: string;\n  capability: string;\n  target: string;\n  pin: string;\n  current: string;\n}\n\n/**\n * `capability.realizes-stale` — ONE warn per pinned entry whose target has been\n * rewritten since the pin was stamped.\n *\n * THE ONLY CHECK IN THE PRODUCT THAT NOTICES A LIVING DOCUMENT DECAYING. Every\n * other join here is an EXISTENCE constraint: `capability.realizes-unknown`\n * fires when the target is gone, and stays silent when the target is merely\n * different. That silence is the failure this axis was missing — an analyst\n * narrows a promise, and every service requirement claiming to keep it goes on\n * claiming so, in a corpus loam rewrote itself, with nothing anywhere to say\n * the claim was made about different words.\n *\n * WARN, AND IT MUST STAY A WARN. A pin going stale is not a defect: it is the\n * fleet being told that a promise moved and somebody should re-read the\n * requirements standing on it. The re-read is a human act with three legitimate\n * outcomes — change the requirement, change the promise, or decide neither\n * needed to change — and only the third is `loam rebase --living` on its own.\n * An error would make the middle outcome unavailable without `--approve`, and a\n * gate would make an analyst's ordinary edit break other teams' builds.\n *\n * Unpinned entries produce nothing, forever. A corpus that has never been\n * pinned grades exactly as it did before pins existed, which is what lets this\n * land without a migration.\n */\nexport function realizesStaleFindings(\n  reqs: Requirement[],\n  target: RealizesTargetDoc,\n  index: CapabilityRequirementIndex,\n): Finding[] {\n  const stale: StaleEntry[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const claim of resolveRealizes(r.realizes, index)) {\n      if (claim.kind !== \"resolved\" || claim.stale !== true) continue;\n      stale.push({\n        requirement: r.name,\n        entry: claim.entry,\n        capability: claim.capability,\n        target: claim.requirement,\n        pin: claim.pin!,\n        current: claim.current!,\n      });\n    }\n  }\n  return stale.map((s) => ({\n    severity: \"warn\" as const,\n    code: \"capability.realizes-stale\",\n    subject: target.subject,\n    message:\n      `${target.where}: requirement '${s.requirement}' realizes ${s.capability}#${s.target}, ` +\n      `which has been rewritten since this claim was pinned (pinned ${s.pin}, now ${s.current}). ` +\n      \"The join still resolves — what changed is the promise, not its address. \" +\n      `Re-read capabilities/${s.capability}/spec.md and decide which side is now wrong; ` +\n      \"when this requirement is right as it stands, `loam rebase --living` re-pins it\",\n  }));\n}\n\n/** One capability requirement nothing realizes, located exactly. */\nexport interface UnrealizedRequirement {\n  capability: string;\n  /** Its `Requirement-ID:`. */\n  id: string;\n  /** Its `### Requirement:` heading, for a reader who has the document open. */\n  name: string;\n}\n\n/**\n * `capability.requirement-unrealized` — ONE warn per capability requirement no\n * living service requirement's `Realizes:` line names.\n *\n * The sharper half of the axis, and the reason the join was worth building.\n * `capability.unrealized` already says a whole capability is claimed by nobody,\n * which is the loud case somebody notices; this says the fleet claims the\n * capability and has left one named promise inside it unimplemented — the case\n * that survives every rollup, because the capability's OTHER requirements make\n * its row look healthy.\n *\n * Warn rather than error, and per requirement rather than one rollup finding\n * with details[]: an analyst writing next quarter's promises before anybody\n * implements them is the normal, intended use of the document, and a corpus\n * that fails the gate the moment it is written ahead of the fleet is a corpus\n * nobody writes ahead. Subject is `<capability>#<id>` — the entry an author\n * would type to fix it, which is the string they should be able to copy.\n */\nexport function requirementUnrealizedFindings(unrealized: UnrealizedRequirement[]): Finding[] {\n  return [...unrealized]\n    .sort((a, b) => compareIds(a.capability, b.capability) || compareIds(a.id, b.id))\n    .map((u) => ({\n      severity: \"warn\" as const,\n      code: \"capability.requirement-unrealized\",\n      subject: `${u.capability}#${u.id}`,\n      message:\n        `landscape: capabilities/${u.capability}/spec.md — '${u.name}' (${u.id}) is realized by no living requirement: ` +\n        `no service's \\`Realizes:\\` line names ${u.capability}#${u.id}. ` +\n        \"Either the promise is not implemented yet, or the requirements that implement it have not said so — \" +\n        \"add the line to each service requirement that carries part of it\",\n    }));\n}\n"]}
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../../../../src/core/capabilities/realizes/findings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The `Realizes:` grades, both directions: an entry that resolves to nothing,\n * and a capability requirement nothing realizes.\n *\n * Values only — core never prints — and the join rule written ONCE, as the\n * Issue coherence gates on, which validate files as a Finding unchanged,\n * exactly as `../findings.ts` does for `capability.unknown`. One function over\n * ONE message builder is the only arrangement in which a finding an author\n * reads at the service target and the refusal they hit at `loam archive`\n * cannot describe the same breach differently — the Finding and Issue twins\n * it replaced had byte-identical bodies.\n *\n * WHY THE DELTA SIDE GATES ARCHIVE. A delta requirement whose `Realizes:` entry\n * resolves to nothing would merge a join pointing at a promise that does not\n * exist, and the living document would then carry it looking exactly like a\n * working join — the same argument that made `capability.unknown` a gate.\n * `--approve` overrides it like any other error.\n */\nimport { compareIds } from \"../../repo/entries.js\";\nimport type { Requirement } from \"../../document/spec.js\";\nimport type { Finding } from \"../../vocabulary/report.js\";\nimport type { Issue } from \"../../vocabulary/issue.js\";\nimport { resolveRealizes, type CapabilityRequirementIndex, type RealizesClaim } from \"./join.js\";\n\n/** Which document is being graded, and under whose name the finding is filed. */\nexport interface RealizesTargetDoc {\n  where: string;\n  subject: string;\n}\n\n/**\n * An entry that did NOT resolve. Spelled as an exclusion rather than as a\n * second union so the arms cannot drift: adding a failure kind to\n * `RealizesClaim` makes `advice` below fail to compile until it says what to do\n * about it, which is exactly the reminder a new failure mode deserves.\n */\ntype UnresolvedClaim = Exclude<RealizesClaim, { kind: \"resolved\" }>;\n\n/**\n * The fix for one unresolved entry, as a sentence. Five arms, five different\n * repairs — the whole reason `RealizesClaim` is not collapsed to a boolean.\n */\nfunction advice(claim: UnresolvedClaim): string {\n  switch (claim.kind) {\n    case \"malformed\":\n      return (\n        \"an entry names a capability requirement and is spelled `<capability-id>#<Requirement-ID>` — \" +\n        \"the capability half addresses the document, because a Requirement-ID is unique only inside its own. \" +\n        \"To claim a theme rather than a promise, use the `Capability:` line instead\"\n      );\n    case \"unknown-capability\":\n      return claim.close.length > 0\n        ? `no such capability is declared. Did you mean: ${claim.close.join(\", \")}?`\n        : \"no such capability is declared — declare it in architecture/capabilities.yaml, \" +\n            `write capabilities/${claim.capability}/spec.md, or fix the spelling`;\n    case \"undocumented-capability\":\n      return (\n        `capability '${claim.capability}' is declared but has no capabilities/${claim.capability}/spec.md, ` +\n        \"so it carries no requirements to realize. Write the document — a name alone can be claimed with \" +\n        \"`Capability:`, but only a document can be realized\"\n      );\n    case \"empty-capability\":\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 \"unknown-requirement\":\n      return claim.close.length > 0\n        ? `capabilities/${claim.capability}/spec.md declares no requirement with that id. Did you mean: ${claim.close.join(\", \")}?`\n        : `capabilities/${claim.capability}/spec.md declares no requirement with that id — ` +\n            \"check the `Requirement-ID:` lines in that document\";\n  }\n}\n\nfunction unresolvedMessage(where: string, requirement: string, claim: UnresolvedClaim): string {\n  return `${where}: requirement '${requirement}' — Realizes: '${claim.entry}' does not resolve: ${advice(claim)}`;\n}\n\n/** One unresolved entry, with the requirement that wrote it. */\ninterface Unresolved {\n  requirement: string;\n  claim: UnresolvedClaim;\n}\n\n/**\n * Non-REMOVED requirements' entries that do not resolve — or nothing at all\n * when the vocabulary cannot be graded against, which `resolveRealizes` answers\n * by returning no claims.\n *\n * REMOVED is skipped for the reason its `Capability:` sibling skips it: a\n * requirement on its way out of the living document is not making a claim about\n * the future, and grading its joins would refuse the very change that removes\n * the last consumer of a retired capability requirement.\n */\nfunction unresolvedEntries(reqs: Requirement[], index: CapabilityRequirementIndex): Unresolved[] {\n  const out: Unresolved[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const claim of resolveRealizes(r.realizes, index)) {\n      if (claim.kind !== \"resolved\") out.push({ requirement: r.name, claim });\n    }\n  }\n  return out;\n}\n\n/**\n * `capability.realizes-unknown` — an ERROR, the grade its two siblings already\n * carry: a join that resolves to nothing reads exactly like a working one in\n * the requirement, in the rollup and in every answer built over either. One\n * function for validate's service target and a feature's delta documents —\n * see the module comment.\n */\nexport function realizesUnknownIssues(\n  reqs: Requirement[],\n  target: RealizesTargetDoc,\n  index: CapabilityRequirementIndex,\n): Issue[] {\n  return unresolvedEntries(reqs, index).map((u) => ({\n    severity: \"error\" as const,\n    code: \"capability.realizes-unknown\" as const,\n    subject: target.subject,\n    message: unresolvedMessage(target.where, u.requirement, u.claim),\n  }));\n}\n\n/** One resolved entry whose pin no longer matches the promise it points at. */\ninterface StaleEntry {\n  requirement: string;\n  entry: string;\n  capability: string;\n  target: string;\n  pin: string;\n  current: string;\n}\n\n/**\n * `capability.realizes-stale` — ONE warn per pinned entry whose target has been\n * rewritten since the pin was stamped.\n *\n * THE ONLY CHECK IN THE PRODUCT THAT NOTICES A LIVING DOCUMENT DECAYING. Every\n * other join here is an EXISTENCE constraint: `capability.realizes-unknown`\n * fires when the target is gone, and stays silent when the target is merely\n * different. That silence is the failure this axis was missing — an analyst\n * narrows a promise, and every service requirement claiming to keep it goes on\n * claiming so, in a corpus loam rewrote itself, with nothing anywhere to say\n * the claim was made about different words.\n *\n * WARN, AND IT MUST STAY A WARN. A pin going stale is not a defect: it is the\n * fleet being told that a promise moved and somebody should re-read the\n * requirements standing on it. The re-read is a human act with three legitimate\n * outcomes — change the requirement, change the promise, or decide neither\n * needed to change — and only the third is `loam rebase --living` on its own.\n * An error would make the middle outcome unavailable without `--approve`, and a\n * gate would make an analyst's ordinary edit break other teams' builds.\n *\n * Unpinned entries produce nothing, forever. A corpus that has never been\n * pinned grades exactly as it did before pins existed, which is what lets this\n * land without a migration.\n */\nexport function realizesStaleFindings(\n  reqs: Requirement[],\n  target: RealizesTargetDoc,\n  index: CapabilityRequirementIndex,\n): Finding[] {\n  const stale: StaleEntry[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const claim of resolveRealizes(r.realizes, index)) {\n      if (claim.kind !== \"resolved\" || claim.stale !== true) continue;\n      stale.push({\n        requirement: r.name,\n        entry: claim.entry,\n        capability: claim.capability,\n        target: claim.requirement,\n        pin: claim.pin!,\n        current: claim.current!,\n      });\n    }\n  }\n  return stale.map((s) => ({\n    severity: \"warn\" as const,\n    code: \"capability.realizes-stale\",\n    subject: target.subject,\n    message:\n      `${target.where}: requirement '${s.requirement}' realizes ${s.capability}#${s.target}, ` +\n      `which has been rewritten since this claim was pinned (pinned ${s.pin}, now ${s.current}). ` +\n      \"The join still resolves — what changed is the promise, not its address. \" +\n      `Re-read capabilities/${s.capability}/spec.md and decide which side is now wrong; ` +\n      \"when this requirement is right as it stands, `loam rebase --living` re-pins it\",\n  }));\n}\n\n/** One capability requirement nothing realizes, located exactly. */\nexport interface UnrealizedRequirement {\n  capability: string;\n  /** Its `Requirement-ID:`. */\n  id: string;\n  /** Its `### Requirement:` heading, for a reader who has the document open. */\n  name: string;\n}\n\n/**\n * `capability.requirement-unrealized` — ONE warn per capability requirement no\n * living service requirement's `Realizes:` line names.\n *\n * The sharper half of the axis, and the reason the join was worth building.\n * `capability.unrealized` already says a whole capability is claimed by nobody,\n * which is the loud case somebody notices; this says the fleet claims the\n * capability and has left one named promise inside it unimplemented — the case\n * that survives every rollup, because the capability's OTHER requirements make\n * its row look healthy.\n *\n * Warn rather than error, and per requirement rather than one rollup finding\n * with details[]: an analyst writing next quarter's promises before anybody\n * implements them is the normal, intended use of the document, and a corpus\n * that fails the gate the moment it is written ahead of the fleet is a corpus\n * nobody writes ahead. Subject is `<capability>#<id>` — the entry an author\n * would type to fix it, which is the string they should be able to copy.\n */\nexport function requirementUnrealizedFindings(unrealized: UnrealizedRequirement[]): Finding[] {\n  return [...unrealized]\n    .sort((a, b) => compareIds(a.capability, b.capability) || compareIds(a.id, b.id))\n    .map((u) => ({\n      severity: \"warn\" as const,\n      code: \"capability.requirement-unrealized\",\n      subject: `${u.capability}#${u.id}`,\n      message:\n        `landscape: capabilities/${u.capability}/spec.md — '${u.name}' (${u.id}) is realized by no living requirement: ` +\n        `no service's \\`Realizes:\\` line names ${u.capability}#${u.id}. ` +\n        \"Either the promise is not implemented yet, or the requirements that implement it have not said so — \" +\n        \"add the line to each service requirement that carries part of it\",\n    }));\n}\n"]}

package/dist/core/capabilities/realizes/join.js

@@ -120,24 +120,4 @@ export function resolveRealizes(entries, index) {
         };
     });
 }
-/**
- * The capabilities an entry list CLAIMS, whether or not each entry resolves.
- *
- * Used to widen the set `capability.unrealized` is taken against, and the
- * widening is a correctness fix rather than a convenience: realizing a
- * capability's requirement IS realizing part of that capability, so an author
- * who wrote only `Realizes:` lines would otherwise be warned that a capability
- * demonstrably realized by their fleet is realized by nobody.
- *
- * Claims from UNRESOLVED entries count too, and that is deliberate. The entry
- * already earns `capability.realizes-unknown`; letting it also produce a
- * spurious `capability.unrealized` would be two findings for one mistake, and
- * the second would point at the analyst's document rather than at the typo.
- */
-export function capabilitiesClaimedByRealizes(entries) {
-    return entries.flatMap((entry) => {
-        const target = splitRealizesEntry(entry);
-        return target === null ? [] : [target.capability];
-    });
-}
 //# sourceMappingURL=join.js.map

package/dist/core/capabilities/realizes/join.js.map

@@ -1 +1 @@
-{"version":3,"file":"join.js","sourceRoot":"","sources":["../../../../src/core/capabilities/realizes/join.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The join from a service requirement INTO the authored business tree:\n * `Realizes: <capability-id>#<Requirement-ID>`.\n *\n * This is the axis's load-bearing edge. `Capability:` beside it answers a\n * different question and neither replaces the other — `Capability: checkout`\n * claims a theme, `Realizes: checkout#CHECKOUT-CHARGE-ONCE` claims that this\n * requirement is part of what makes one named promise true. Only the second can\n * be graded in both directions, and both directions are the point: an entry\n * that resolves to nothing, and a capability requirement nothing realizes.\n *\n * WHO WRITES IT. Not the analyst. The analyst writes the capability and its\n * requirements and names no service; whoever implements a service requirement\n * writes the line that says which promise it serves. That is why the line lives\n * on the SERVICE requirement and not as a back-reference in the capability\n * document: a business document must not have to be edited every time a fleet\n * rearranges which service carries which part.\n *\n * WHY NO SEPARATE LINE FOR THE API HOP. A capability requirement reaches its\n * operations by composing this join with the `Operations:` lines that already\n * exist on the requirements realizing it. A third place to keep in sync would\n * buy nothing and could disagree with the two.\n *\n * DELIBERATELY THE NARROWEST LAYER THAT CAN MEAN IT, exactly as\n * `../usecase-join.ts` is: no file is read, no finding is emitted, nothing is\n * thrown, and — the load-bearing part — this package does NOT import\n * `../capabilities.js`. It takes ids somebody else supplies. That keeps the\n * package edge one-way (`capabilities` → `capabilities/realizes`), and it keeps\n * the resolution testable without a filesystem.\n *\n * WHAT THE CALLER STILL OWES. The vocabulary ladder in `../findings.ts` — an\n * absent or unreadable `architecture/capabilities.yaml` means silence, not a\n * fleet full of unresolved joins — is applied BEFORE calling here, and travels\n * as `declared: null`.\n */\nimport { closeIds } from \"../../c4/arch.js\";\nimport { splitRealizesPin } from \"../../document/spec.js\";\nimport { compareIds } from \"../../repo/entries.js\";\n\n/**\n * The separator between the two halves of an entry.\n *\n * A composite entry rather than two lines because a `Requirement-ID` is unique\n * only inside its own document: the capability half is not decoration, it is\n * what makes the target addressable. Two lines would let one requirement name\n * three capabilities and four ids with nothing saying which belongs to which.\n */\nexport const REALIZES_SEPARATOR = \"#\";\n\n/** The two halves of one entry, plus the version it was written against. */\nexport interface RealizesTarget {\n  capability: string;\n  requirement: string;\n  /**\n   * The digest of the capability requirement this claim was last pinned to, or\n   * `null` for an unpinned entry. Written by `loam rebase --living`, never by\n   * hand; `null` is the normal state of a corpus that has not been pinned and\n   * grades exactly as it did before pins existed.\n   */\n  pin: string | null;\n}\n\n/**\n * Split one entry, or `null` when it has no two halves.\n *\n * THE LAST SEPARATOR, NOT THE FIRST, and the asymmetry is the reason: the\n * requirement half has a strict grammar (`REQUIREMENT_ID_RE` in\n * `core/document/spec.ts`) that excludes `#`, while the capability half is a\n * YAML key and a directory name and is constrained nowhere. Splitting at the\n * last `#` is therefore unambiguous for every capability id there is;\n * splitting at the first would mis-parse any id containing one, and would do it\n * silently — the failure mode this whole axis exists to refuse.\n *\n * Both halves must be non-empty. `checkout#`, `#CHK-1` and a bare `checkout`\n * are all one answer — `null` — because the fix for all three is the same\n * sentence, and inventing three refusals for one mistake helps nobody.\n */\nexport function splitRealizesEntry(entry: string): RealizesTarget | null {\n  // The pin comes off FIRST. It is a suffix of the whole entry, and leaving it\n  // on would put `@<digest>` inside the requirement half, where it would fail\n  // to resolve against an id that never contained one.\n  const { target, pin } = splitRealizesPin(entry);\n  const at = target.lastIndexOf(REALIZES_SEPARATOR);\n  if (at <= 0 || at === target.length - 1) return null;\n  return { capability: target.slice(0, at), requirement: target.slice(at + 1), pin };\n}\n\n/**\n * What the tree declares, as the resolution needs it.\n *\n * The two fields answer different questions and both are needed to tell the\n * failures apart: `declared` is every capability id the fleet knows — the union\n * of the YAML and the tree — while `byCapability` holds only those with a\n * document, since only a document can carry requirements. A capability in\n * `declared` and absent from `byCapability` is declared-but-undocumented, which\n * is a real and common mid-adoption state with a fix of its own.\n */\nexport interface CapabilityRequirementIndex {\n  /**\n   * Every declared capability id, or `null` when the vocabulary cannot be\n   * graded against at all. `null` and `[]` are never interchangeable — the same\n   * distinction `gradableCapabilityIds` draws, for the same reason.\n   */\n  declared: readonly string[] | null;\n  /** Requirement ids per capability that HAS a document. Present-and-empty is a real answer. */\n  byCapability: ReadonlyMap<string, ReadonlySet<string>>;\n  /**\n   * The current `requirementDigest` of each id in `byCapability`, for the pin\n   * comparison and nothing else.\n   *\n   * A second collection over the same keys, which is a shape this codebase\n   * otherwise refuses — the justification is that the alternative is worse.\n   * Widening `byCapability`'s values to a Map would change what `[...ids]`\n   * iterates at four call sites that legitimately want the ids alone, and a\n   * silent change of meaning in an existing iteration is a far more expensive\n   * mistake than a redundant map built in the same loop. The invariant — same\n   * capabilities, same ids, both sides — is asserted by\n   * `test/capability-realizes-pin.test.ts` rather than left to a comment.\n   */\n  digests: ReadonlyMap<string, ReadonlyMap<string, string>>;\n}\n\n/**\n * What one `Realizes:` entry joins to. Branch on `kind`; every arm carries the\n * entry it is about, so a message can name it without re-deriving it.\n *\n * Five arms because there are five different fixes. Collapsing them would be\n * cheaper to write and worse to read: \"does not resolve\" tells an author\n * nothing about whether to declare a capability, write a document, add a\n * requirements section, or correct four characters.\n */\nexport type RealizesClaim =\n  /**\n   * Both halves resolve. `stale` is the pin verdict, and it is a THIRD state\n   * rather than a boolean: `null` means the entry carries no pin, which is not\n   * the same answer as a pin that still matches. Only `true` is a finding.\n   */\n  | {\n      entry: string;\n      kind: \"resolved\";\n      capability: string;\n      requirement: string;\n      pin: string | null;\n      /** The target's digest now, or `null` when the index could not supply one. */\n      current: string | null;\n      stale: boolean | null;\n    }\n  /** No usable separator — the fix is the spelling of the entry itself. */\n  | { entry: string; kind: \"malformed\" }\n  /** Nothing declares the capability half. `close` holds real declared ids. */\n  | { entry: string; kind: \"unknown-capability\"; capability: string; close: string[] }\n  /** Declared, but with no `capabilities/<id>/spec.md` — so it has no requirements at all. */\n  | { entry: string; kind: \"undocumented-capability\"; capability: string }\n  /** The document exists and declares no requirements yet. */\n  | { entry: string; kind: \"empty-capability\"; capability: string }\n  /** The document exists and declares requirements, but not this one. */\n  | { entry: string; kind: \"unknown-requirement\"; capability: string; requirement: string; close: string[] };\n\n/**\n * Resolve every entry, in the order the author wrote them.\n *\n * Order preserved and repeats NOT collapsed, matching the `Capability:` line's\n * behaviour in `../findings.ts` rather than the `#cap-` tag's in\n * `../usecase-join.ts`. The two siblings differ because a tag set is a set —\n * LikeC4 hands it over with no authored order to preserve — while a body line\n * is text somebody typed, and a reader chasing a finding is looking at that\n * text. Consistency with the line beside it is worth more here than a\n * deduplication nobody asked for.\n *\n * An empty result when `declared` is `null` is the ladder, not an answer: there\n * is nothing to grade against, so nothing is graded.\n */\nexport function resolveRealizes(\n  entries: readonly string[],\n  index: CapabilityRequirementIndex,\n): RealizesClaim[] {\n  const { declared, byCapability, digests } = index;\n  if (declared === null) return [];\n  const known = new Set(declared);\n\n  return entries.map((entry): RealizesClaim => {\n    const target = splitRealizesEntry(entry);\n    if (target === null) return { entry, kind: \"malformed\" };\n    const { capability, requirement, pin } = target;\n    if (!known.has(capability)) {\n      return { entry, kind: \"unknown-capability\", capability, close: closeIds(capability, declared) };\n    }\n    const ids = byCapability.get(capability);\n    if (ids === undefined) return { entry, kind: \"undocumented-capability\", capability };\n    if (ids.size === 0) return { entry, kind: \"empty-capability\", capability };\n    if (ids.has(requirement)) {\n      // An index with no digest for a resolved id leaves the verdict UNKNOWN\n      // rather than STALE. The two are not the same claim, and a reader who is\n      // told a pin went stale because the grader could not compute the other\n      // side would be told something false.\n      const current = digests.get(capability)?.get(requirement) ?? null;\n      const stale = pin === null || current === null ? null : pin !== current;\n      return { entry, kind: \"resolved\", capability, requirement, pin, current, stale };\n    }\n    return {\n      entry,\n      kind: \"unknown-requirement\",\n      capability,\n      requirement,\n      close: closeIds(requirement, [...ids].sort(compareIds)),\n    };\n  });\n}\n\n/**\n * The capabilities an entry list CLAIMS, whether or not each entry resolves.\n *\n * Used to widen the set `capability.unrealized` is taken against, and the\n * widening is a correctness fix rather than a convenience: realizing a\n * capability's requirement IS realizing part of that capability, so an author\n * who wrote only `Realizes:` lines would otherwise be warned that a capability\n * demonstrably realized by their fleet is realized by nobody.\n *\n * Claims from UNRESOLVED entries count too, and that is deliberate. The entry\n * already earns `capability.realizes-unknown`; letting it also produce a\n * spurious `capability.unrealized` would be two findings for one mistake, and\n * the second would point at the analyst's document rather than at the typo.\n */\nexport function capabilitiesClaimedByRealizes(entries: readonly string[]): string[] {\n  return entries.flatMap((entry) => {\n    const target = splitRealizesEntry(entry);\n    return target === null ? [] : [target.capability];\n  });\n}\n"]}
+{"version":3,"file":"join.js","sourceRoot":"","sources":["../../../../src/core/capabilities/realizes/join.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAetC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,6EAA6E;IAC7E,4EAA4E;IAC5E,qDAAqD;IACrD,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAChD,MAAM,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC;IAClD,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;AACrF,CAAC;AAyED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA0B,EAC1B,KAAiC;IAEjC,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAClD,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IAEhC,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAiB,EAAE;QAC1C,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;QACzD,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC;QAChD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3B,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,CAAC;QAClG,CAAC;QACD,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,yBAAyB,EAAE,UAAU,EAAE,CAAC;QACrF,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,kBAAkB,EAAE,UAAU,EAAE,CAAC;QAC3E,IAAI,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YACzB,uEAAuE;YACvE,yEAAyE;YACzE,uEAAuE;YACvE,sCAAsC;YACtC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC;YAClE,MAAM,KAAK,GAAG,GAAG,KAAK,IAAI,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,OAAO,CAAC;YACxE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACnF,CAAC;QACD,OAAO;YACL,KAAK;YACL,IAAI,EAAE,qBAAqB;YAC3B,UAAU;YACV,WAAW;YACX,KAAK,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;SACxD,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * The join from a service requirement INTO the authored business tree:\n * `Realizes: <capability-id>#<Requirement-ID>`.\n *\n * This is the axis's load-bearing edge. `Capability:` beside it answers a\n * different question and neither replaces the other — `Capability: checkout`\n * claims a theme, `Realizes: checkout#CHECKOUT-CHARGE-ONCE` claims that this\n * requirement is part of what makes one named promise true. Only the second can\n * be graded in both directions, and both directions are the point: an entry\n * that resolves to nothing, and a capability requirement nothing realizes.\n *\n * WHO WRITES IT. Not the analyst. The analyst writes the capability and its\n * requirements and names no service; whoever implements a service requirement\n * writes the line that says which promise it serves. That is why the line lives\n * on the SERVICE requirement and not as a back-reference in the capability\n * document: a business document must not have to be edited every time a fleet\n * rearranges which service carries which part.\n *\n * WHY NO SEPARATE LINE FOR THE API HOP. A capability requirement reaches its\n * operations by composing this join with the `Operations:` lines that already\n * exist on the requirements realizing it. A third place to keep in sync would\n * buy nothing and could disagree with the two.\n *\n * DELIBERATELY THE NARROWEST LAYER THAT CAN MEAN IT, exactly as\n * `../usecase-join.ts` is: no file is read, no finding is emitted, nothing is\n * thrown, and — the load-bearing part — this package does NOT import\n * `../capabilities.js`. It takes ids somebody else supplies. That keeps the\n * package edge one-way (`capabilities` → `capabilities/realizes`), and it keeps\n * the resolution testable without a filesystem.\n *\n * WHAT THE CALLER STILL OWES. The vocabulary ladder in `../findings.ts` — an\n * absent or unreadable `architecture/capabilities.yaml` means silence, not a\n * fleet full of unresolved joins — is applied BEFORE calling here, and travels\n * as `declared: null`.\n */\nimport { closeIds } from \"../../c4/arch.js\";\nimport { splitRealizesPin } from \"../../document/spec.js\";\nimport { compareIds } from \"../../repo/entries.js\";\n\n/**\n * The separator between the two halves of an entry.\n *\n * A composite entry rather than two lines because a `Requirement-ID` is unique\n * only inside its own document: the capability half is not decoration, it is\n * what makes the target addressable. Two lines would let one requirement name\n * three capabilities and four ids with nothing saying which belongs to which.\n */\nexport const REALIZES_SEPARATOR = \"#\";\n\n/** The two halves of one entry, plus the version it was written against. */\nexport interface RealizesTarget {\n  capability: string;\n  requirement: string;\n  /**\n   * The digest of the capability requirement this claim was last pinned to, or\n   * `null` for an unpinned entry. Written by `loam rebase --living`, never by\n   * hand; `null` is the normal state of a corpus that has not been pinned and\n   * grades exactly as it did before pins existed.\n   */\n  pin: string | null;\n}\n\n/**\n * Split one entry, or `null` when it has no two halves.\n *\n * THE LAST SEPARATOR, NOT THE FIRST, and the asymmetry is the reason: the\n * requirement half has a strict grammar (`REQUIREMENT_ID_RE` in\n * `core/document/spec.ts`) that excludes `#`, while the capability half is a\n * YAML key and a directory name and is constrained nowhere. Splitting at the\n * last `#` is therefore unambiguous for every capability id there is;\n * splitting at the first would mis-parse any id containing one, and would do it\n * silently — the failure mode this whole axis exists to refuse.\n *\n * Both halves must be non-empty. `checkout#`, `#CHK-1` and a bare `checkout`\n * are all one answer — `null` — because the fix for all three is the same\n * sentence, and inventing three refusals for one mistake helps nobody.\n */\nexport function splitRealizesEntry(entry: string): RealizesTarget | null {\n  // The pin comes off FIRST. It is a suffix of the whole entry, and leaving it\n  // on would put `@<digest>` inside the requirement half, where it would fail\n  // to resolve against an id that never contained one.\n  const { target, pin } = splitRealizesPin(entry);\n  const at = target.lastIndexOf(REALIZES_SEPARATOR);\n  if (at <= 0 || at === target.length - 1) return null;\n  return { capability: target.slice(0, at), requirement: target.slice(at + 1), pin };\n}\n\n/**\n * What the tree declares, as the resolution needs it.\n *\n * The two fields answer different questions and both are needed to tell the\n * failures apart: `declared` is every capability id the fleet knows — the union\n * of the YAML and the tree — while `byCapability` holds only those with a\n * document, since only a document can carry requirements. A capability in\n * `declared` and absent from `byCapability` is declared-but-undocumented, which\n * is a real and common mid-adoption state with a fix of its own.\n */\nexport interface CapabilityRequirementIndex {\n  /**\n   * Every declared capability id, or `null` when the vocabulary cannot be\n   * graded against at all. `null` and `[]` are never interchangeable — the same\n   * distinction `gradableCapabilityIds` draws, for the same reason.\n   */\n  declared: readonly string[] | null;\n  /** Requirement ids per capability that HAS a document. Present-and-empty is a real answer. */\n  byCapability: ReadonlyMap<string, ReadonlySet<string>>;\n  /**\n   * The current `requirementDigest` of each id in `byCapability`, for the pin\n   * comparison and nothing else.\n   *\n   * A second collection over the same keys, which is a shape this codebase\n   * otherwise refuses — the justification is that the alternative is worse.\n   * Widening `byCapability`'s values to a Map would change what `[...ids]`\n   * iterates at four call sites that legitimately want the ids alone, and a\n   * silent change of meaning in an existing iteration is a far more expensive\n   * mistake than a redundant map built in the same loop. The invariant — same\n   * capabilities, same ids, both sides — is asserted by\n   * `test/capability-realizes-pin.test.ts` rather than left to a comment.\n   */\n  digests: ReadonlyMap<string, ReadonlyMap<string, string>>;\n}\n\n/**\n * What one `Realizes:` entry joins to. Branch on `kind`; every arm carries the\n * entry it is about, so a message can name it without re-deriving it.\n *\n * Five arms because there are five different fixes. Collapsing them would be\n * cheaper to write and worse to read: \"does not resolve\" tells an author\n * nothing about whether to declare a capability, write a document, add a\n * requirements section, or correct four characters.\n */\nexport type RealizesClaim =\n  /**\n   * Both halves resolve. `stale` is the pin verdict, and it is a THIRD state\n   * rather than a boolean: `null` means the entry carries no pin, which is not\n   * the same answer as a pin that still matches. Only `true` is a finding.\n   */\n  | {\n      entry: string;\n      kind: \"resolved\";\n      capability: string;\n      requirement: string;\n      pin: string | null;\n      /** The target's digest now, or `null` when the index could not supply one. */\n      current: string | null;\n      stale: boolean | null;\n    }\n  /** No usable separator — the fix is the spelling of the entry itself. */\n  | { entry: string; kind: \"malformed\" }\n  /** Nothing declares the capability half. `close` holds real declared ids. */\n  | { entry: string; kind: \"unknown-capability\"; capability: string; close: string[] }\n  /** Declared, but with no `capabilities/<id>/spec.md` — so it has no requirements at all. */\n  | { entry: string; kind: \"undocumented-capability\"; capability: string }\n  /** The document exists and declares no requirements yet. */\n  | { entry: string; kind: \"empty-capability\"; capability: string }\n  /** The document exists and declares requirements, but not this one. */\n  | { entry: string; kind: \"unknown-requirement\"; capability: string; requirement: string; close: string[] };\n\n/**\n * Resolve every entry, in the order the author wrote them.\n *\n * Order preserved and repeats NOT collapsed, matching the `Capability:` line's\n * behaviour in `../findings.ts` rather than the `#cap-` tag's in\n * `../usecase-join.ts`. The two siblings differ because a tag set is a set —\n * LikeC4 hands it over with no authored order to preserve — while a body line\n * is text somebody typed, and a reader chasing a finding is looking at that\n * text. Consistency with the line beside it is worth more here than a\n * deduplication nobody asked for.\n *\n * An empty result when `declared` is `null` is the ladder, not an answer: there\n * is nothing to grade against, so nothing is graded.\n */\nexport function resolveRealizes(\n  entries: readonly string[],\n  index: CapabilityRequirementIndex,\n): RealizesClaim[] {\n  const { declared, byCapability, digests } = index;\n  if (declared === null) return [];\n  const known = new Set(declared);\n\n  return entries.map((entry): RealizesClaim => {\n    const target = splitRealizesEntry(entry);\n    if (target === null) return { entry, kind: \"malformed\" };\n    const { capability, requirement, pin } = target;\n    if (!known.has(capability)) {\n      return { entry, kind: \"unknown-capability\", capability, close: closeIds(capability, declared) };\n    }\n    const ids = byCapability.get(capability);\n    if (ids === undefined) return { entry, kind: \"undocumented-capability\", capability };\n    if (ids.size === 0) return { entry, kind: \"empty-capability\", capability };\n    if (ids.has(requirement)) {\n      // An index with no digest for a resolved id leaves the verdict UNKNOWN\n      // rather than STALE. The two are not the same claim, and a reader who is\n      // told a pin went stale because the grader could not compute the other\n      // side would be told something false.\n      const current = digests.get(capability)?.get(requirement) ?? null;\n      const stale = pin === null || current === null ? null : pin !== current;\n      return { entry, kind: \"resolved\", capability, requirement, pin, current, stale };\n    }\n    return {\n      entry,\n      kind: \"unknown-requirement\",\n      capability,\n      requirement,\n      close: closeIds(requirement, [...ids].sort(compareIds)),\n    };\n  });\n}\n"]}

package/dist/core/capabilities/rollup.js

@@ -80,6 +80,12 @@ export async function capabilityRollup(input) {
                 for (const target of r.realizes.map(splitRealizesEntry)) {
                     if (target === null)
                         continue; // malformed — capability.realizes-unknown's business
+                    // The capability is claimed BEFORE asking whether the requirement id
+                    // resolves, and that is deliberate: an entry naming an undeclared id
+                    // already earns `capability.realizes-unknown`, and letting it also
+                    // leave its capability `capability.unrealized` would be two findings
+                    // for one mistake — the second pointing at the analyst's document
+                    // rather than at the typo.
                     claim(rows, claimed, target.capability, where);
                     // The requirement-level half. An entry naming an id the document does
                     // not declare lands nowhere, which is exactly right: it is already