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

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

@@ -0,0 +1,123 @@
+/**
+ * The join from a service requirement INTO the authored business tree:
+ * `Realizes: <capability-id>#<Requirement-ID>`.
+ *
+ * This is the axis's load-bearing edge. `Capability:` beside it answers a
+ * different question and neither replaces the other — `Capability: checkout`
+ * claims a theme, `Realizes: checkout#CHECKOUT-CHARGE-ONCE` claims that this
+ * requirement is part of what makes one named promise true. Only the second can
+ * be graded in both directions, and both directions are the point: an entry
+ * that resolves to nothing, and a capability requirement nothing realizes.
+ *
+ * WHO WRITES IT. Not the analyst. The analyst writes the capability and its
+ * requirements and names no service; whoever implements a service requirement
+ * writes the line that says which promise it serves. That is why the line lives
+ * on the SERVICE requirement and not as a back-reference in the capability
+ * document: a business document must not have to be edited every time a fleet
+ * rearranges which service carries which part.
+ *
+ * WHY NO SEPARATE LINE FOR THE API HOP. A capability requirement reaches its
+ * operations by composing this join with the `Operations:` lines that already
+ * exist on the requirements realizing it. A third place to keep in sync would
+ * buy nothing and could disagree with the two.
+ *
+ * DELIBERATELY THE NARROWEST LAYER THAT CAN MEAN IT, exactly as
+ * `../usecase-join.ts` is: no file is read, no finding is emitted, nothing is
+ * thrown, and — the load-bearing part — this package does NOT import
+ * `../capabilities.js`. It takes ids somebody else supplies. That keeps the
+ * package edge one-way (`capabilities` → `capabilities/realizes`), and it keeps
+ * the resolution testable without a filesystem.
+ *
+ * WHAT THE CALLER STILL OWES. The vocabulary ladder in `../findings.ts` — an
+ * absent or unreadable `architecture/capabilities.yaml` means silence, not a
+ * fleet full of unresolved joins — is applied BEFORE calling here, and travels
+ * as `declared: null`.
+ */
+import { closeIds } from "../../c4/arch.js";
+import { splitRealizesPin } from "../../document/spec.js";
+import { compareIds } from "../../repo/entries.js";
+/**
+ * The separator between the two halves of an entry.
+ *
+ * A composite entry rather than two lines because a `Requirement-ID` is unique
+ * only inside its own document: the capability half is not decoration, it is
+ * what makes the target addressable. Two lines would let one requirement name
+ * three capabilities and four ids with nothing saying which belongs to which.
+ */
+export const REALIZES_SEPARATOR = "#";
+/**
+ * Split one entry, or `null` when it has no two halves.
+ *
+ * THE LAST SEPARATOR, NOT THE FIRST, and the asymmetry is the reason: the
+ * requirement half has a strict grammar (`REQUIREMENT_ID_RE` in
+ * `core/document/spec.ts`) that excludes `#`, while the capability half is a
+ * YAML key and a directory name and is constrained nowhere. Splitting at the
+ * last `#` is therefore unambiguous for every capability id there is;
+ * splitting at the first would mis-parse any id containing one, and would do it
+ * silently — the failure mode this whole axis exists to refuse.
+ *
+ * Both halves must be non-empty. `checkout#`, `#CHK-1` and a bare `checkout`
+ * are all one answer — `null` — because the fix for all three is the same
+ * sentence, and inventing three refusals for one mistake helps nobody.
+ */
+export function splitRealizesEntry(entry) {
+    // The pin comes off FIRST. It is a suffix of the whole entry, and leaving it
+    // on would put `@<digest>` inside the requirement half, where it would fail
+    // to resolve against an id that never contained one.
+    const { target, pin } = splitRealizesPin(entry);
+    const at = target.lastIndexOf(REALIZES_SEPARATOR);
+    if (at <= 0 || at === target.length - 1)
+        return null;
+    return { capability: target.slice(0, at), requirement: target.slice(at + 1), pin };
+}
+/**
+ * Resolve every entry, in the order the author wrote them.
+ *
+ * Order preserved and repeats NOT collapsed, matching the `Capability:` line's
+ * behaviour in `../findings.ts` rather than the `#cap-` tag's in
+ * `../usecase-join.ts`. The two siblings differ because a tag set is a set —
+ * LikeC4 hands it over with no authored order to preserve — while a body line
+ * is text somebody typed, and a reader chasing a finding is looking at that
+ * text. Consistency with the line beside it is worth more here than a
+ * deduplication nobody asked for.
+ *
+ * An empty result when `declared` is `null` is the ladder, not an answer: there
+ * is nothing to grade against, so nothing is graded.
+ */
+export function resolveRealizes(entries, index) {
+    const { declared, byCapability, digests } = index;
+    if (declared === null)
+        return [];
+    const known = new Set(declared);
+    return entries.map((entry) => {
+        const target = splitRealizesEntry(entry);
+        if (target === null)
+            return { entry, kind: "malformed" };
+        const { capability, requirement, pin } = target;
+        if (!known.has(capability)) {
+            return { entry, kind: "unknown-capability", capability, close: closeIds(capability, declared) };
+        }
+        const ids = byCapability.get(capability);
+        if (ids === undefined)
+            return { entry, kind: "undocumented-capability", capability };
+        if (ids.size === 0)
+            return { entry, kind: "empty-capability", capability };
+        if (ids.has(requirement)) {
+            // An index with no digest for a resolved id leaves the verdict UNKNOWN
+            // rather than STALE. The two are not the same claim, and a reader who is
+            // told a pin went stale because the grader could not compute the other
+            // side would be told something false.
+            const current = digests.get(capability)?.get(requirement) ?? null;
+            const stale = pin === null || current === null ? null : pin !== current;
+            return { entry, kind: "resolved", capability, requirement, pin, current, stale };
+        }
+        return {
+            entry,
+            kind: "unknown-requirement",
+            capability,
+            requirement,
+            close: closeIds(requirement, [...ids].sort(compareIds)),
+        };
+    });
+}
+//# sourceMappingURL=join.js.map

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

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

package/dist/core/capabilities/rollup.js

@@ -0,0 +1,205 @@
+/**
+ * The fleet total over the capability join, built once and reused by the fleet
+ * grade, `loam list capabilities` and `loam explore --capability` — one walk,
+ * so the unrealized warning and the rollup a reader diffs can never disagree
+ * about what "realized" means.
+ *
+ * Deterministic and diff-stable by construction: rows sorted with compareIds,
+ * realizedBy sorted by (service, file, requirement), statuses' keys sorted —
+ * no timestamps, no absolute paths, no readdir-order dependence. The reader is
+ * INJECTED (`read`) rather than a FleetContext, because fleet-context.ts
+ * imports this package for its memo and an import back would be a package
+ * cycle (see the memo's comment); callers pass `fleet.readRequirements` bound,
+ * so under `validate --all` every parse is already cached from the service
+ * targets and the rollup costs no additional per-service read.
+ *
+ * TWO CORPORA MEET HERE, and neither is derived from the other. A promise is
+ * kept by a service requirement's `Realizes:` line (walked below) or by a
+ * `#cap-`/`#req-` tagged flow (injected as `keptByFlows`, because the module
+ * that computes it imports this one). The rollup carries both on one row for the
+ * reason it carries both `Capability:` joins on one row: `loam list capabilities`
+ * and `capability.requirement-unrealized` must not be able to give different
+ * answers to "is this business promise kept", and they can only give one answer
+ * if they read one row.
+ */
+import { existsSync } from "node:fs";
+import { compareIds } from "../repo/entries.js";
+import { SPEC_AXES, servicePathsAt } from "../repo/paths.js";
+import { splitRealizesEntry } from "./realizes/join.js";
+/**
+ * Walk every service's spec.md and arch.spec.md (existsSync-guarded, exactly
+ * like permissionFindings: an absent OPTIONAL artifact must never take a whole
+ * `--all` run down) and join non-REMOVED requirements' `Capability:` entries to
+ * the declared vocabulary. Rows exist for every DECLARED id — an unrealized
+ * declaration is a row with empty realizedBy, which is what the unrealized
+ * grade and the list's `0 — unrealized` marker both read.
+ */
+export async function capabilityRollup(input) {
+    const { services, vocab, read, keptByFlows } = input;
+    // Rows exist only for DECLARED ids, so an empty vocabulary (absent file, or
+    // present with nothing declared) can build nothing — walking every service's
+    // two spec files to produce zero rows is what a vocabless 120-service fleet
+    // would otherwise pay on every `list`/`explore` that asks.
+    if (vocab.byId.size === 0)
+        return [];
+    const rows = new Map();
+    for (const id of [...vocab.byId.keys()].sort(compareIds)) {
+        const decl = vocab.byId.get(id);
+        rows.set(id, {
+            id,
+            ...(decl.description !== undefined ? { description: decl.description } : {}),
+            ...(decl.owner !== undefined ? { owner: decl.owner } : {}),
+            realizedBy: [],
+            services: [],
+            statuses: {},
+        });
+    }
+    // The documents, before the services, because a `Realizes:` entry can only
+    // land on a requirement row that already exists.
+    for (const doc of vocab.tree.docs) {
+        const row = rows.get(doc.id);
+        if (row === undefined)
+            continue; // unreachable: the tree is one half of byId
+        row.requirements = capabilityRequirementRows(await read(doc.spec));
+    }
+    // Realizations are collected as a SET per row before they become a list, so
+    // the two joins cannot count one requirement twice — see `CapabilityRow.realizedBy`.
+    const claimed = new Map();
+    for (const entry of services) {
+        const paths = servicePathsAt(entry.dir);
+        for (const axis of SPEC_AXES) {
+            const path = paths[axis.key];
+            if (!existsSync(path))
+                continue;
+            for (const r of await read(path)) {
+                if (r.kind === "REMOVED")
+                    continue;
+                const where = { service: entry.id, file: axis.file, requirement: r.name };
+                for (const capability of r.capabilities)
+                    claim(rows, claimed, capability, where);
+                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
+                    // `capability.realizes-unknown`, and inventing a row for it here would
+                    // make a typo look like a promise somebody wrote.
+                    rows
+                        .get(target.capability)
+                        ?.requirements?.find((req) => req.id === target.requirement)
+                        ?.realizedBy.push(where);
+                }
+            }
+        }
+    }
+    for (const row of rows.values()) {
+        row.realizedBy = [...(claimed.get(row)?.values() ?? [])].sort(compareRealizations);
+        row.services = [...new Set(row.realizedBy.map((r) => r.service))].sort(compareIds);
+        const byStatus = {};
+        for (const r of row.realizedBy) {
+            const status = statusOf(services, r.service);
+            byStatus[status] = (byStatus[status] ?? 0) + 1;
+        }
+        row.statuses = Object.fromEntries(Object.entries(byStatus).sort(([a], [b]) => compareIds(a, b)));
+        for (const req of row.requirements ?? []) {
+            req.realizedBy.sort(compareRealizations);
+            // Copied out of the injected map rather than aliased into the row: the row
+            // is a mutable value a caller may sort or splice, and handing it the
+            // caller's own array would let one consumer's edit rewrite the answer the
+            // next one reads. Already sorted upstream — copied, never re-sorted, so
+            // there is exactly one statement of the order.
+            if (keptByFlows !== undefined)
+                req.keptBy = [...(keptByFlows.get(`${row.id}#${req.id}`) ?? [])];
+        }
+    }
+    return [...rows.values()];
+}
+/** Deterministic realization order — the diff-stable rule this module states for its rows. */
+function compareRealizations(a, b) {
+    return (compareIds(a.service, b.service) ||
+        a.file.localeCompare(b.file) ||
+        compareIds(a.requirement, b.requirement));
+}
+/** The service's declared frontmatter status, or `unset` for one nobody has marked. */
+function statusOf(services, id) {
+    return services.find((s) => s.id === id)?.status ?? "unset";
+}
+/** Record one realization of one capability, deduplicated on where it came from. */
+function claim(rows, claimed, capability, where) {
+    const row = rows.get(capability);
+    if (row === undefined)
+        return; // undeclared — capability.unknown's business, not the rollup's
+    const seen = claimed.get(row) ?? new Map();
+    seen.set(`${where.service}\0${where.file}\0${where.requirement}`, where);
+    claimed.set(row, seen);
+}
+/**
+ * A capability document's requirements as rows, keyed by their stable id.
+ *
+ * A requirement WITHOUT a `Requirement-ID:` is dropped rather than keyed by its
+ * heading, and the drop is the honest answer rather than a shortcut: nothing
+ * can address it — `Realizes:` names an id — so a row for it would be a promise
+ * reported as unrealized that no author could ever mark realized.
+ * `capability.requirement-unidentified` is the finding that names it, and it is
+ * an ERROR, so the state does not persist quietly.
+ *
+ * A duplicate id keeps the FIRST, matching `requirementIdProblems`' own
+ * `duplicate` grade: the document already earns an error for it, and picking a
+ * winner here is only about not producing two identical rows.
+ */
+export function capabilityRequirementRows(reqs) {
+    const rows = new Map();
+    for (const r of reqs) {
+        if (r.kind === "REMOVED" || r.id === undefined || rows.has(r.id))
+            continue;
+        rows.set(r.id, { id: r.id, name: r.name, realizedBy: [] });
+    }
+    return [...rows.values()].sort((a, b) => compareIds(a.id, b.id));
+}
+/** The declared ids something realizes — the set the unrealized grade is taken against. */
+export function usedCapabilities(rows) {
+    return new Set(rows.filter(isRealized).map((row) => row.id));
+}
+/**
+ * Does anything in the fleet realize this capability — by EITHER corpus?
+ *
+ * A flow keeping one of a capability's promises realizes part of that
+ * capability as surely as a `Capability:` line does, and the case is not
+ * hypothetical: a capability whose promises are all cross-service can be kept
+ * perfectly by `#cap-`/`#req-` tagged flows and named by no service requirement
+ * at all. Counting only the service corpus told such a fleet its capability was
+ * "a promise nobody implemented or a word nobody adopted" while the fleet's own
+ * use cases said otherwise — one warning, contradicted by loam's own answer two
+ * lines further down the same report.
+ *
+ * ASYMMETRIC WITH `capability.requirement-unrealized`, on purpose. That grade
+ * suspends entirely when the flows cannot be read, because a promise crossing
+ * services often has NO possible realizer but a flow — unreadable flows remove
+ * the only evidence there was. A capability has independent primary evidence in
+ * the `Capability:`/`Realizes:` lines, so unreadable flows leave it answering
+ * from less rather than from nothing, and going silent would lose the warning
+ * for a fleet that has a vocabulary and no fleet map at all — a real and legal
+ * shape, and one where the whole point of the code is to be heard.
+ */
+function isRealized(row) {
+    if (row.realizedBy.length > 0)
+        return true;
+    return (row.requirements ?? []).some((req) => (req.keptBy?.length ?? 0) > 0);
+}
+/**
+ * The requested ids the rollup cannot seed from: undeclared, or declared but
+ * realized by nothing. One list on purpose — explore's contract is 'every miss
+ * is a field', and splitting the two miss kinds waits for a consumer to ask.
+ */
+export function unresolvedCapabilities(rows, requested) {
+    const realized = usedCapabilities(rows);
+    return requested.filter((id) => !realized.has(id));
+}
+//# sourceMappingURL=rollup.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rollup.js","sourceRoot":"","sources":["../../../src/core/capabilities/rollup.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet total over the capability join, built once and reused by the fleet\n * grade, `loam list capabilities` and `loam explore --capability` — one walk,\n * so the unrealized warning and the rollup a reader diffs can never disagree\n * about what \"realized\" means.\n *\n * Deterministic and diff-stable by construction: rows sorted with compareIds,\n * realizedBy sorted by (service, file, requirement), statuses' keys sorted —\n * no timestamps, no absolute paths, no readdir-order dependence. The reader is\n * INJECTED (`read`) rather than a FleetContext, because fleet-context.ts\n * imports this package for its memo and an import back would be a package\n * cycle (see the memo's comment); callers pass `fleet.readRequirements` bound,\n * so under `validate --all` every parse is already cached from the service\n * targets and the rollup costs no additional per-service read.\n *\n * TWO CORPORA MEET HERE, and neither is derived from the other. A promise is\n * kept by a service requirement's `Realizes:` line (walked below) or by a\n * `#cap-`/`#req-` tagged flow (injected as `keptByFlows`, because the module\n * that computes it imports this one). The rollup carries both on one row for the\n * reason it carries both `Capability:` joins on one row: `loam list capabilities`\n * and `capability.requirement-unrealized` must not be able to give different\n * answers to \"is this business promise kept\", and they can only give one answer\n * if they read one row.\n */\nimport { existsSync } from \"node:fs\";\nimport type { Requirement } from \"../document/spec.js\";\nimport { compareIds, type ServiceEntry } from \"../repo/entries.js\";\nimport { SPEC_AXES, servicePathsAt } from \"../repo/paths.js\";\nimport type { CapabilityVocabulary } from \"./capabilities.js\";\nimport { splitRealizesEntry } from \"./realizes/join.js\";\n\n/** One requirement realizing one capability, located exactly. */\nexport interface CapabilityRealization {\n  service: string;\n  file: \"spec.md\" | \"arch.spec.md\";\n  /** The requirement's `### Requirement:` name. */\n  requirement: string;\n}\n\n/** One requirement OF a capability document, and what realizes it. */\nexport interface CapabilityRequirementRow {\n  /** Its `Requirement-ID:`. A requirement without one is absent here — see `capabilityRequirementRows`. */\n  id: string;\n  /** Its `### Requirement:` heading. */\n  name: string;\n  /** Service requirements whose `Realizes:` line names `<capability>#<id>`. */\n  realizedBy: CapabilityRealization[];\n  /**\n   * The ids of the declared flows that keep this promise — a `#cap-`/`#req-`\n   * tagged `dynamic view` whose BOTH tags resolve. THE SECOND CORPUS, and the\n   * only carrier a cross-service promise has: \"I enter a login and a password\n   * and I am in\" belongs to no single service's spec, so a fleet can keep it\n   * perfectly through a flow and realize it by no `Realizes:` line at all.\n   *\n   * Three states, all of them different answers, exactly as `requirements`\n   * itself has three:\n   *   present and non-empty — these flows keep it;\n   *   present and empty     — loam read the flows and none of them keeps it;\n   *   ABSENT                — nobody looked. Either the caller did not ask\n   *                           (`CapabilityRollupInput.keptByFlows` omitted) or\n   *                           it asked and `architecture/` could not be read.\n   * The third must never collapse into the second. \"Kept by no flow\" over a\n   * project that did not parse is the vacuously-green claim the whole use-case\n   * axis exists to refuse, and it is the claim a `[]` default would make.\n   */\n  keptBy?: string[];\n}\n\n/** One declared capability with everything the fleet says about it. */\nexport interface CapabilityRow {\n  id: string;\n  description?: string;\n  owner?: string;\n  /**\n   * Service requirements realizing this capability BY EITHER JOIN, deduplicated\n   * on (service, file, requirement).\n   *\n   * Both joins land here on purpose. `Realizes: checkout#CHK-1` realizes part of\n   * `checkout` as surely as `Capability: checkout` does, and a rollup that\n   * counted only the second would report a capability as realized by nobody\n   * while the fleet pointed at its individual promises — which would then be\n   * one spurious `capability.unrealized` per capability an author had documented\n   * carefully enough to join at requirement level. The deduplication is what\n   * lets a requirement carry both lines, which is the normal shape: the theme\n   * and the promise are different claims.\n   */\n  realizedBy: CapabilityRealization[];\n  /** Distinct realizing services, sorted. */\n  services: string[];\n  /**\n   * Realizing requirements counted by their service's frontmatter status\n   * (`unset` for a service nobody has marked) — the draft/verified split the\n   * roadmap asks the total to answer. Counted over the DEDUPLICATED set above,\n   * so a requirement writing both joins is one requirement.\n   */\n  statuses: Record<string, number>;\n  /**\n   * The capability document's own requirements, each with what realizes it.\n   * Present only for a capability that HAS a document — absent and empty are\n   * different answers, and only the second means \"the document declares none\".\n   */\n  requirements?: CapabilityRequirementRow[];\n}\n\nexport interface CapabilityRollupInput {\n  services: ServiceEntry[];\n  vocab: CapabilityVocabulary;\n  /** The requirement reader — pass a FleetContext's readRequirements, bound. */\n  read: (path: string) => Promise<Requirement[]>;\n  /**\n   * `<capability>#<Requirement-ID>` → the ids of the flows that keep it, from\n   * `core/usecases`' `useCaseRequirementClaims`. Injected as PLAIN DATA, exactly\n   * as `read` is, and for a harder reason than the memo: `core/usecases` imports\n   * this package, so an import back would be a package cycle and\n   * `npm run arch:check` refuses it. What travels is a Map of strings, which\n   * carries no dependency in either direction.\n   *\n   * OMIT IT to answer \"nobody looked\": every `keptBy` above is then absent\n   * rather than empty, which is what keeps a caller that never asked about\n   * flows — `explore`, the context pack, `validate`'s own rollup — from\n   * publishing a `[]` that reads as \"no flow keeps this\". A caller that DID look\n   * and found nothing passes an empty Map; a caller that looked and could not\n   * see must omit it and say so in its own words (`loam list` prints the note\n   * and carries `useCases.unreadable`).\n   */\n  keptByFlows?: ReadonlyMap<string, readonly string[]>;\n}\n\n/**\n * Walk every service's spec.md and arch.spec.md (existsSync-guarded, exactly\n * like permissionFindings: an absent OPTIONAL artifact must never take a whole\n * `--all` run down) and join non-REMOVED requirements' `Capability:` entries to\n * the declared vocabulary. Rows exist for every DECLARED id — an unrealized\n * declaration is a row with empty realizedBy, which is what the unrealized\n * grade and the list's `0 — unrealized` marker both read.\n */\nexport async function capabilityRollup(input: CapabilityRollupInput): Promise<CapabilityRow[]> {\n  const { services, vocab, read, keptByFlows } = input;\n  // Rows exist only for DECLARED ids, so an empty vocabulary (absent file, or\n  // present with nothing declared) can build nothing — walking every service's\n  // two spec files to produce zero rows is what a vocabless 120-service fleet\n  // would otherwise pay on every `list`/`explore` that asks.\n  if (vocab.byId.size === 0) return [];\n  const rows = new Map<string, CapabilityRow>();\n  for (const id of [...vocab.byId.keys()].sort(compareIds)) {\n    const decl = vocab.byId.get(id)!;\n    rows.set(id, {\n      id,\n      ...(decl.description !== undefined ? { description: decl.description } : {}),\n      ...(decl.owner !== undefined ? { owner: decl.owner } : {}),\n      realizedBy: [],\n      services: [],\n      statuses: {},\n    });\n  }\n  // The documents, before the services, because a `Realizes:` entry can only\n  // land on a requirement row that already exists.\n  for (const doc of vocab.tree.docs) {\n    const row = rows.get(doc.id);\n    if (row === undefined) continue; // unreachable: the tree is one half of byId\n    row.requirements = capabilityRequirementRows(await read(doc.spec));\n  }\n\n  // Realizations are collected as a SET per row before they become a list, so\n  // the two joins cannot count one requirement twice — see `CapabilityRow.realizedBy`.\n  const claimed = new Map<CapabilityRow, Map<string, CapabilityRealization>>();\n  for (const entry of services) {\n    const paths = servicePathsAt(entry.dir);\n    for (const axis of SPEC_AXES) {\n      const path = paths[axis.key];\n      if (!existsSync(path)) continue;\n      for (const r of await read(path)) {\n        if (r.kind === \"REMOVED\") continue;\n        const where: CapabilityRealization = { service: entry.id, file: axis.file, requirement: r.name };\n        for (const capability of r.capabilities) claim(rows, claimed, capability, where);\n        for (const target of r.realizes.map(splitRealizesEntry)) {\n          if (target === null) continue; // malformed — capability.realizes-unknown's business\n          // The capability is claimed BEFORE asking whether the requirement id\n          // resolves, and that is deliberate: an entry naming an undeclared id\n          // already earns `capability.realizes-unknown`, and letting it also\n          // leave its capability `capability.unrealized` would be two findings\n          // for one mistake — the second pointing at the analyst's document\n          // rather than at the typo.\n          claim(rows, claimed, target.capability, where);\n          // The requirement-level half. An entry naming an id the document does\n          // not declare lands nowhere, which is exactly right: it is already\n          // `capability.realizes-unknown`, and inventing a row for it here would\n          // make a typo look like a promise somebody wrote.\n          rows\n            .get(target.capability)\n            ?.requirements?.find((req) => req.id === target.requirement)\n            ?.realizedBy.push(where);\n        }\n      }\n    }\n  }\n\n  for (const row of rows.values()) {\n    row.realizedBy = [...(claimed.get(row)?.values() ?? [])].sort(compareRealizations);\n    row.services = [...new Set(row.realizedBy.map((r) => r.service))].sort(compareIds);\n    const byStatus: Record<string, number> = {};\n    for (const r of row.realizedBy) {\n      const status = statusOf(services, r.service);\n      byStatus[status] = (byStatus[status] ?? 0) + 1;\n    }\n    row.statuses = Object.fromEntries(Object.entries(byStatus).sort(([a], [b]) => compareIds(a, b)));\n    for (const req of row.requirements ?? []) {\n      req.realizedBy.sort(compareRealizations);\n      // Copied out of the injected map rather than aliased into the row: the row\n      // is a mutable value a caller may sort or splice, and handing it the\n      // caller's own array would let one consumer's edit rewrite the answer the\n      // next one reads. Already sorted upstream — copied, never re-sorted, so\n      // there is exactly one statement of the order.\n      if (keptByFlows !== undefined) req.keptBy = [...(keptByFlows.get(`${row.id}#${req.id}`) ?? [])];\n    }\n  }\n  return [...rows.values()];\n}\n\n/** Deterministic realization order — the diff-stable rule this module states for its rows. */\nfunction compareRealizations(a: CapabilityRealization, b: CapabilityRealization): number {\n  return (\n    compareIds(a.service, b.service) ||\n    a.file.localeCompare(b.file) ||\n    compareIds(a.requirement, b.requirement)\n  );\n}\n\n/** The service's declared frontmatter status, or `unset` for one nobody has marked. */\nfunction statusOf(services: ServiceEntry[], id: string): string {\n  return services.find((s) => s.id === id)?.status ?? \"unset\";\n}\n\n/** Record one realization of one capability, deduplicated on where it came from. */\nfunction claim(\n  rows: Map<string, CapabilityRow>,\n  claimed: Map<CapabilityRow, Map<string, CapabilityRealization>>,\n  capability: string,\n  where: CapabilityRealization,\n): void {\n  const row = rows.get(capability);\n  if (row === undefined) return; // undeclared — capability.unknown's business, not the rollup's\n  const seen = claimed.get(row) ?? new Map<string, CapabilityRealization>();\n  seen.set(`${where.service}\\0${where.file}\\0${where.requirement}`, where);\n  claimed.set(row, seen);\n}\n\n/**\n * A capability document's requirements as rows, keyed by their stable id.\n *\n * A requirement WITHOUT a `Requirement-ID:` is dropped rather than keyed by its\n * heading, and the drop is the honest answer rather than a shortcut: nothing\n * can address it — `Realizes:` names an id — so a row for it would be a promise\n * reported as unrealized that no author could ever mark realized.\n * `capability.requirement-unidentified` is the finding that names it, and it is\n * an ERROR, so the state does not persist quietly.\n *\n * A duplicate id keeps the FIRST, matching `requirementIdProblems`' own\n * `duplicate` grade: the document already earns an error for it, and picking a\n * winner here is only about not producing two identical rows.\n */\nexport function capabilityRequirementRows(reqs: Requirement[]): CapabilityRequirementRow[] {\n  const rows = new Map<string, CapabilityRequirementRow>();\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\" || r.id === undefined || rows.has(r.id)) continue;\n    rows.set(r.id, { id: r.id, name: r.name, realizedBy: [] });\n  }\n  return [...rows.values()].sort((a, b) => compareIds(a.id, b.id));\n}\n\n/** The declared ids something realizes — the set the unrealized grade is taken against. */\nexport function usedCapabilities(rows: CapabilityRow[]): Set<string> {\n  return new Set(rows.filter(isRealized).map((row) => row.id));\n}\n\n/**\n * Does anything in the fleet realize this capability — by EITHER corpus?\n *\n * A flow keeping one of a capability's promises realizes part of that\n * capability as surely as a `Capability:` line does, and the case is not\n * hypothetical: a capability whose promises are all cross-service can be kept\n * perfectly by `#cap-`/`#req-` tagged flows and named by no service requirement\n * at all. Counting only the service corpus told such a fleet its capability was\n * \"a promise nobody implemented or a word nobody adopted\" while the fleet's own\n * use cases said otherwise — one warning, contradicted by loam's own answer two\n * lines further down the same report.\n *\n * ASYMMETRIC WITH `capability.requirement-unrealized`, on purpose. That grade\n * suspends entirely when the flows cannot be read, because a promise crossing\n * services often has NO possible realizer but a flow — unreadable flows remove\n * the only evidence there was. A capability has independent primary evidence in\n * the `Capability:`/`Realizes:` lines, so unreadable flows leave it answering\n * from less rather than from nothing, and going silent would lose the warning\n * for a fleet that has a vocabulary and no fleet map at all — a real and legal\n * shape, and one where the whole point of the code is to be heard.\n */\nfunction isRealized(row: CapabilityRow): boolean {\n  if (row.realizedBy.length > 0) return true;\n  return (row.requirements ?? []).some((req) => (req.keptBy?.length ?? 0) > 0);\n}\n\n/**\n * The requested ids the rollup cannot seed from: undeclared, or declared but\n * realized by nothing. One list on purpose — explore's contract is 'every miss\n * is a field', and splitting the two miss kinds waits for a consumer to ask.\n */\nexport function unresolvedCapabilities(rows: CapabilityRow[], requested: string[]): string[] {\n  const realized = usedCapabilities(rows);\n  return requested.filter((id) => !realized.has(id));\n}\n"]}

package/dist/core/capabilities/tree.js

@@ -0,0 +1,104 @@
+/**
+ * The capability tree: `capabilities/<id>/spec.md`, and the rule that a
+ * directory holding one IS a declared capability.
+ *
+ * WHY A TREE AND NOT A SECOND LIST IN YAML. `architecture/capabilities.yaml`
+ * declares names; it cannot carry prose, and a capability a business analyst
+ * actually wrote is mostly prose. The alternative — a single vocabulary file
+ * grown to hold paragraphs — is the exact drift `loam init`'s removed
+ * `loam.docs.json` was removed for: a second list nothing keeps current. So the
+ * DIRECTORY is the list, and the general rule it settles is that an entry with
+ * prose gets a file while an entry without prose stays a line in YAML
+ * (`architecture/permissions.yaml` is the principled exception — a
+ * `user/profile:read` pair has no prose, and a document per pair is ceremony).
+ *
+ * THE VOCABULARY IS THE UNION of this tree and the YAML, and the YAML is not
+ * deprecated by it. A fleet that declared twenty names and has written four
+ * documents is the normal state of an adoption, and a tree that refused to
+ * grade the other sixteen would make adopting the axis a cliff.
+ * `./capabilities.ts` merges the two and records which side declared each id.
+ *
+ * PRESENCE CLASSIFIES, one tree over from `isServiceArtifactName`: a directory
+ * holding the document is a capability, and one holding only other directories
+ * is a group the walk descends through. Both at once is legal and normal —
+ * `payments` may be a capability with `payments/refunds` nested inside it —
+ * because a capability id spells its own nesting wherever it is written and the
+ * tree only mirrors that. What is NOT legal is a directory that is neither:
+ * `capability.doc-missing` names it, rather than letting a half-created
+ * capability sit in the tree looking declared.
+ *
+ * The walk reads directories only. It never parses a document — the requirement
+ * reader is injected by whoever grades (`./findings.ts` takes parsed
+ * requirements, `commands/validate/` supplies the fleet's cached reader), for
+ * the reason `./rollup.ts` states: this package is imported by
+ * `core/fleet-context.ts` and may never import it back.
+ */
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { compareIds } from "../repo/entries.js";
+import { capabilityDocPathsAt } from "../repo/authored/paths.js";
+import { entryIs, markDescended, subdirNames } from "../repo/tree/fs.js";
+/**
+ * Read the tree under `root` (`capabilityDocsDir(docsDir)`).
+ *
+ * Cost is one readdir per directory, capability directories included: their own
+ * listing is what classifies them, and it is the same listing that finds the
+ * capabilities nested inside. A fleet is expected to hold tens of these
+ * documents rather than hundreds — the corpus is sized like the landscape, not
+ * like the service tree — which is what keeps a second requirement corpus
+ * reviewable at all, and what makes the walk's cost a non-question.
+ */
+export async function readCapabilityTree(root) {
+    const tree = { present: existsSync(root), docs: [], undocumented: [] };
+    if (!tree.present)
+        return tree;
+    const state = { tree, visited: new Set() };
+    // The same guard `core/repo/tree/walk.ts` carries (`markDescended`), for
+    // the same reason: `entryIs` follows symlinks on purpose.
+    if (markDescended(root, state.visited)) {
+        for (const name of await subdirNames(root)) {
+            await visit({ dir: join(root, name), chain: [name] }, state);
+        }
+    }
+    tree.docs.sort((a, b) => compareIds(a.id, b.id));
+    tree.undocumented.sort(compareIds);
+    return tree;
+}
+/**
+ * Classify one directory and walk what is inside it. Returns whether a
+ * capability was found at or beneath it — the only thing a caller needs, since
+ * a group directory earns no finding for being a group.
+ *
+ * A directory reached a SECOND time through a symlink answers `true` rather
+ * than `false`, and the distinction is a quiet enumeration against a spurious
+ * finding: it was already walked under its first name, so everything in it is
+ * already recorded, and reporting it undocumented would name a directory whose
+ * document loam has in fact already read.
+ */
+async function visit(spot, state) {
+    const entries = (await readdir(spot.dir, { withFileTypes: true })).filter((e) => !e.name.startsWith("."));
+    const paths = capabilityDocPathsAt(spot.dir);
+    const documented = entries.some((e) => join(spot.dir, e.name) === paths.spec && entryIs(spot.dir, e, "file"));
+    if (documented)
+        state.tree.docs.push({ id: spot.chain.join("/"), dir: spot.dir, spec: paths.spec });
+    let beneath = false;
+    if (markDescended(spot.dir, state.visited)) {
+        const dirs = entries.filter((e) => entryIs(spot.dir, e, "dir")).map((e) => e.name).sort();
+        for (const child of dirs) {
+            // Sequential, not Promise.all: the visited set is shared mutable state and
+            // the walk's correctness under symlinks rests on a child being marked
+            // before its sibling asks. These trees are tens of directories at most, so
+            // there is nothing to win by racing them.
+            if (await visit({ dir: join(spot.dir, child), chain: [...spot.chain, child] }, state))
+                beneath = true;
+        }
+    }
+    else {
+        beneath = true;
+    }
+    if (!documented && !beneath)
+        state.tree.undocumented.push(["capabilities", ...spot.chain].join("/"));
+    return documented || beneath;
+}
+//# sourceMappingURL=tree.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../src/core/capabilities/tree.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The capability tree: `capabilities/<id>/spec.md`, and the rule that a\n * directory holding one IS a declared capability.\n *\n * WHY A TREE AND NOT A SECOND LIST IN YAML. `architecture/capabilities.yaml`\n * declares names; it cannot carry prose, and a capability a business analyst\n * actually wrote is mostly prose. The alternative — a single vocabulary file\n * grown to hold paragraphs — is the exact drift `loam init`'s removed\n * `loam.docs.json` was removed for: a second list nothing keeps current. So the\n * DIRECTORY is the list, and the general rule it settles is that an entry with\n * prose gets a file while an entry without prose stays a line in YAML\n * (`architecture/permissions.yaml` is the principled exception — a\n * `user/profile:read` pair has no prose, and a document per pair is ceremony).\n *\n * THE VOCABULARY IS THE UNION of this tree and the YAML, and the YAML is not\n * deprecated by it. A fleet that declared twenty names and has written four\n * documents is the normal state of an adoption, and a tree that refused to\n * grade the other sixteen would make adopting the axis a cliff.\n * `./capabilities.ts` merges the two and records which side declared each id.\n *\n * PRESENCE CLASSIFIES, one tree over from `isServiceArtifactName`: a directory\n * holding the document is a capability, and one holding only other directories\n * is a group the walk descends through. Both at once is legal and normal —\n * `payments` may be a capability with `payments/refunds` nested inside it —\n * because a capability id spells its own nesting wherever it is written and the\n * tree only mirrors that. What is NOT legal is a directory that is neither:\n * `capability.doc-missing` names it, rather than letting a half-created\n * capability sit in the tree looking declared.\n *\n * The walk reads directories only. It never parses a document — the requirement\n * reader is injected by whoever grades (`./findings.ts` takes parsed\n * requirements, `commands/validate/` supplies the fleet's cached reader), for\n * the reason `./rollup.ts` states: this package is imported by\n * `core/fleet-context.ts` and may never import it back.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { compareIds } from \"../repo/entries.js\";\nimport { capabilityDocPathsAt } from \"../repo/authored/paths.js\";\nimport { entryIs, markDescended, subdirNames } from \"../repo/tree/fs.js\";\n\n/** One authored capability: where its directory is, and where its document is. */\nexport interface CapabilityDoc {\n  /** The id — the directory names between `capabilities/` and this one, joined with `/`. */\n  id: string;\n  dir: string;\n  /** `<dir>/spec.md`. Its existence is what made this a capability. */\n  spec: string;\n}\n\nexport interface CapabilityTree {\n  /**\n   * False when `capabilities/` does not exist. The directory's existence is\n   * this half of the axis's opt-in, so a fleet without one produces nothing\n   * here — not an empty tree that then reads as \"the capabilities went\n   * missing\" to anything counting.\n   */\n  present: boolean;\n  /** Every capability found, at any depth, ordered by id. */\n  docs: CapabilityDoc[];\n  /**\n   * Repo-relative paths of directories under `capabilities/` that hold no\n   * document and have no capability beneath them — the half-created capability\n   * `capability.doc-missing` names. Ordered, for a diff-stable finding list.\n   */\n  undocumented: string[];\n}\n\n/** One directory the walk is looking at: where it is, and how it was reached. */\ninterface Spot {\n  dir: string;\n  /** Directory names between `capabilities/` and this one, outermost first, including it. */\n  chain: string[];\n}\n\ninterface WalkState {\n  tree: CapabilityTree;\n  /** Realpaths already DESCENDED into — the symlink-cycle guard. */\n  visited: Set<string>;\n}\n\n/**\n * Read the tree under `root` (`capabilityDocsDir(docsDir)`).\n *\n * Cost is one readdir per directory, capability directories included: their own\n * listing is what classifies them, and it is the same listing that finds the\n * capabilities nested inside. A fleet is expected to hold tens of these\n * documents rather than hundreds — the corpus is sized like the landscape, not\n * like the service tree — which is what keeps a second requirement corpus\n * reviewable at all, and what makes the walk's cost a non-question.\n */\nexport async function readCapabilityTree(root: string): Promise<CapabilityTree> {\n  const tree: CapabilityTree = { present: existsSync(root), docs: [], undocumented: [] };\n  if (!tree.present) return tree;\n  const state: WalkState = { tree, visited: new Set() };\n  // The same guard `core/repo/tree/walk.ts` carries (`markDescended`), for\n  // the same reason: `entryIs` follows symlinks on purpose.\n  if (markDescended(root, state.visited)) {\n    for (const name of await subdirNames(root)) {\n      await visit({ dir: join(root, name), chain: [name] }, state);\n    }\n  }\n  tree.docs.sort((a, b) => compareIds(a.id, b.id));\n  tree.undocumented.sort(compareIds);\n  return tree;\n}\n\n/**\n * Classify one directory and walk what is inside it. Returns whether a\n * capability was found at or beneath it — the only thing a caller needs, since\n * a group directory earns no finding for being a group.\n *\n * A directory reached a SECOND time through a symlink answers `true` rather\n * than `false`, and the distinction is a quiet enumeration against a spurious\n * finding: it was already walked under its first name, so everything in it is\n * already recorded, and reporting it undocumented would name a directory whose\n * document loam has in fact already read.\n */\nasync function visit(spot: Spot, state: WalkState): Promise<boolean> {\n  const entries = (await readdir(spot.dir, { withFileTypes: true })).filter((e) => !e.name.startsWith(\".\"));\n  const paths = capabilityDocPathsAt(spot.dir);\n  const documented = entries.some((e) => join(spot.dir, e.name) === paths.spec && entryIs(spot.dir, e, \"file\"));\n  if (documented) state.tree.docs.push({ id: spot.chain.join(\"/\"), dir: spot.dir, spec: paths.spec });\n\n  let beneath = false;\n  if (markDescended(spot.dir, state.visited)) {\n    const dirs = entries.filter((e) => entryIs(spot.dir, e, \"dir\")).map((e) => e.name).sort();\n    for (const child of dirs) {\n      // Sequential, not Promise.all: the visited set is shared mutable state and\n      // the walk's correctness under symlinks rests on a child being marked\n      // before its sibling asks. These trees are tens of directories at most, so\n      // there is nothing to win by racing them.\n      if (await visit({ dir: join(spot.dir, child), chain: [...spot.chain, child] }, state)) beneath = true;\n    }\n  } else {\n    beneath = true;\n  }\n\n  if (!documented && !beneath) state.tree.undocumented.push([\"capabilities\", ...spot.chain].join(\"/\"));\n  return documented || beneath;\n}\n"]}