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

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

@@ -0,0 +1,222 @@
+import { splitRealizesEntry } from "../realizes/join.js";
+import { tagSlug } from "../usecase-join.js";
+/**
+ * The `(capability, requirement)` pair, keyed for a Set.
+ *
+ * NUL — the separator `core/delta/scope.ts`'s claim key already uses — rather
+ * than `#`, because a key's separator must be one its halves cannot contain and
+ * a capability id is a YAML key and a directory name, constrained nowhere.
+ * Re-joining with `#` would make `a#b` + `C` and `a` + `b#C` one key, and the
+ * second is unreachable only because the requirement grammar happens to exclude
+ * `#` today.
+ */
+function pairKey(capability, requirement) {
+    return `${capability}\0${requirement}`;
+}
+/**
+ * The pairs one requirement's `Realizes:` lines name.
+ *
+ * Through `splitRealizesEntry`, never a local split, and the LAST `#` is what
+ * makes it right: the requirement half has a grammar that excludes `#` and the
+ * capability half has none, so a first-`#` split mis-parses every id containing
+ * one — silently, which is the failure this axis exists to refuse.
+ */
+function realizedPairs(r) {
+    return r.realizes.flatMap((entry) => {
+        const target = splitRealizesEntry(entry);
+        return target === null ? [] : [pairKey(target.capability, target.requirement)];
+    });
+}
+/** How a service document is named in a message — the axis only where it is not the default one. */
+function docLabel(doc) {
+    return doc.file === "spec.md" ? doc.service : `${doc.service} (${doc.file})`;
+}
+/**
+ * `capability.uncovered` — a capability requirement this feature ADDS that no
+ * `Realizes:` line in the same feature's service deltas names.
+ *
+ * ADDED ONLY. A MODIFIED changes a promise the living fleet may already
+ * realize, so demanding a re-declaration would force an edit with nothing to
+ * change — the same exemption `c4.uncovered` takes one axis over. A requirement
+ * with no `Requirement-ID:` is SKIPPED rather than reported: it is already
+ * `capability.requirement-unidentified`, and there is nothing for a `Realizes:`
+ * line to address, so two findings for one mistake is the failure to avoid.
+ *
+ * The covering side is ADDED or MODIFIED, never BASE and never REMOVED. A BASE
+ * requirement in a delta quotes living context and the merge never writes it,
+ * so a `Realizes:` line there lands nowhere; a REMOVED one is on its way out and
+ * cannot keep a promise after it is gone.
+ *
+ * Feature scope, deliberately. The fleet-scope version already ships as
+ * `capability.requirement-unrealized`, and grading a feature-ADDED requirement
+ * against the LIVING fleet is vacuous — no living `Realizes:` can name it
+ * without being `capability.realizes-unknown` today.
+ */
+export function uncoveredIssues(capabilities, services, 
+// REQUIRED, with no default. A default would have to be one of the two arms,
+// and either choice is wrong for a caller that forgot: `graded: true` with an
+// empty list makes the message assert a negative, and `graded: false` makes it
+// quietly stop checking a corpus the caller does have. The compiler asking is
+// cheaper than either.
+flows) {
+    if (capabilities.length === 0)
+        return [];
+    const kept = new Set();
+    for (const doc of services) {
+        for (const r of doc.reqs) {
+            if (r.kind !== "ADDED" && r.kind !== "MODIFIED")
+                continue;
+            for (const pair of realizedPairs(r))
+                kept.add(pair);
+        }
+    }
+    // The other carrier, through the SAME `pairKey` as the `Realizes:` side: two
+    // corpora answering one question must not be able to disagree about which
+    // promise a claim addresses. The caller resolved these; a claim whose tags did
+    // not both resolve never reaches here, which is what stops a typo from
+    // silencing the gate.
+    if (flows.graded)
+        for (const flow of flows.kept)
+            kept.add(pairKey(flow.capability, flow.requirement));
+    // What the message may CLAIM about the flow half. Ungraded, it claims nothing
+    // and says so — the `Realizes:` half was still checked and is still worth
+    // gating on, so the finding stands; what must not stand is a sentence
+    // convicting a flow nobody resolved.
+    const flowClause = flows.graded
+        ? "and no `dynamic view` under this feature's usecases/ resolves a `#req-` tag to it. "
+        : `and the flow half of the join was NOT checked — ${flows.why}, so a \`#req-\` claim could not be resolved either way. `;
+    const issues = [];
+    for (const doc of capabilities) {
+        for (const r of doc.reqs) {
+            if (r.kind !== "ADDED" || r.id === undefined)
+                continue;
+            if (kept.has(pairKey(doc.id, r.id)))
+                continue;
+            const entry = `${doc.id}#${r.id}`;
+            issues.push({
+                severity: "warn",
+                gates: true,
+                code: "capability.uncovered",
+                subject: doc.id,
+                message: `capability ${doc.id}: ADDED requirement '${r.name}' (${r.id}) is realized by nothing this feature changes — ` +
+                    `no ADDED or MODIFIED requirement in its specs/ deltas carries \`Realizes: ${entry}\`, ` +
+                    flowClause +
+                    "The document is legal; the MERGE is what is unsafe: once it lands, the only thing that will ever mention " +
+                    "this promise again is a fleet-scope warning (capability.requirement-unrealized) nobody reads. " +
+                    `Three ways on: add \`Realizes: ${entry}\` to the service requirement that carries part of it; ` +
+                    `if the promise CROSSES services, write the flow that keeps it as features/<FEAT>/usecases/<name>.likec4 and ` +
+                    `tag its \`dynamic view\` \`#cap-${tagSlug(doc.id)}\` and \`#req-${tagSlug(r.id)}\` — the archive merges it into ` +
+                    "architecture/usecases/ with everything else this feature lands; or archive with --approve to land the promise " +
+                    "ahead of the fleet and let capability.requirement-unrealized carry it.",
+            });
+        }
+    }
+    return issues;
+}
+/** The living requirements a delta document supersedes — MODIFIED and REMOVED both restate or delete. */
+function supersedes(delta, living) {
+    if (delta === undefined)
+        return false;
+    return delta.reqs.some((r) => {
+        if (r.kind !== "MODIFIED" && r.kind !== "REMOVED")
+            return false;
+        return r.id === undefined ? r.name === living.name : r.id === living.id;
+    });
+}
+/**
+ * `capability.remove-requirement-realized` — this feature retires a capability
+ * requirement that something the merge LEAVES BEHIND still realizes.
+ *
+ * The hole the forward direction does not close, and the one this whole module
+ * exists to make impossible: a feature that REMOVES a capability requirement a
+ * living service requirement realizes used to archive at exit 0, and the next
+ * `loam validate --all` then failed with `capability.realizes-unknown` against a
+ * service document nobody had touched. An archive that leaves the fleet red
+ * against an untouched document is the exact class of silent damage the product
+ * exists to refuse.
+ *
+ * GRADED AGAINST THE POST-MERGE FLEET, which is the only reading under which
+ * the two escape hatches fall out instead of being special-cased. A living
+ * requirement that this feature's own delta MODIFIES or REMOVES is gone as
+ * written — a MODIFIED carries its FULL new text, so restating the requirement
+ * without its `Realizes:` line IS how an author drops the join — and the delta's
+ * own ADDED/MODIFIED requirements are what stands in its place. So: retire the
+ * realizer in the same change and there is no breach; keep the line and there
+ * is.
+ *
+ * A `#req-` tagged flow realizing the promise is NOT consulted, and that is the
+ * other subject rather than a gap: the tag names the requirement directly, so a
+ * removal turns it into `usecase.requirement-unresolved` on the living view —
+ * loud, in the document that has to change, and nothing here would make it
+ * louder.
+ *
+ * A REMOVED spelled by heading resolves through the living document, so it
+ * grades exactly what the merge would delete. One that selects nothing is
+ * already `delta.removed-unknown` and retires nothing, so it is skipped here —
+ * two findings for one mistake, again.
+ */
+export async function removedRealizedIssues(join) {
+    const retired = new Map();
+    for (const doc of join.capabilities) {
+        for (const r of doc.reqs) {
+            if (r.kind !== "REMOVED")
+                continue;
+            const selected = doc.living.filter((l) => (r.id === undefined ? l.name === r.name : l.id === r.id));
+            for (const l of selected) {
+                if (l.id === undefined)
+                    continue;
+                retired.set(pairKey(doc.id, l.id), { capability: doc.id, id: l.id, name: l.name });
+            }
+        }
+    }
+    if (retired.size === 0)
+        return [];
+    // Who still realizes each retired pair after the merge: the living
+    // requirements this feature does not supersede, plus the requirements its own
+    // deltas add or restate.
+    const realizers = new Map();
+    const record = (pair, who) => {
+        if (!retired.has(pair))
+            return;
+        const found = realizers.get(pair) ?? [];
+        found.push(who);
+        realizers.set(pair, found);
+    };
+    for (const doc of await join.living()) {
+        const delta = join.deltas.find((d) => d.service === doc.service && d.file === doc.file);
+        for (const r of doc.reqs) {
+            if (supersedes(delta, r))
+                continue;
+            for (const pair of realizedPairs(r))
+                record(pair, `${docLabel(doc)}'s living requirement '${r.name}'`);
+        }
+    }
+    for (const doc of join.deltas) {
+        for (const r of doc.reqs) {
+            if (r.kind !== "ADDED" && r.kind !== "MODIFIED")
+                continue;
+            for (const pair of realizedPairs(r))
+                record(pair, `this feature's ${docLabel(doc)} delta requirement '${r.name}'`);
+        }
+    }
+    const issues = [];
+    for (const [pair, promise] of retired) {
+        const who = realizers.get(pair);
+        if (who === undefined)
+            continue;
+        const entry = `${promise.capability}#${promise.id}`;
+        issues.push({
+            severity: "error",
+            code: "capability.remove-requirement-realized",
+            subject: promise.capability,
+            message: `capability ${promise.capability}: this feature REMOVES '${promise.name}' (${promise.id}), but ${who.join("; ")} ` +
+                `still carries \`Realizes: ${entry}\`. After the merge that line points at a promise no document declares, and ` +
+                "the very next `loam validate --all` reports capability.realizes-unknown against whatever carries it — for a " +
+                "LIVING realizer, a service document this feature never touched. Retire the realizing requirement in the same " +
+                "feature, or drop its `Realizes:` line (a MODIFIED does that by restating the requirement without it), or " +
+                "archive with --approve to break the join deliberately.",
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=uncovered.js.map

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

@@ -0,0 +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"]}

package/dist/core/capabilities/findings.js

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