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

package/dist/core/capabilities/capabilities.js

@@ -0,0 +1,124 @@
+/**
+ * The fleet's capability vocabulary: which business capabilities exist, by
+ * declared name, so a requirement's `Capability:` line resolves or refuses
+ * instead of silently labelling.
+ *
+ * It is a fleet document (`architecture/capabilities.yaml`, beside the
+ * landscape and the permissions vocabulary) because a capability crosses
+ * services by definition — "registration" is realized by requirements in four
+ * repositories, and a per-service copy would be N spellings of one word.
+ *
+ * What this is NOT, deliberately: a domain model, and not an authored prose
+ * layer either. SCHEMA.md rejected a free-text `capability:` label because
+ * nothing could check it; a DECLARED name is different in exactly the way that
+ * mattered there — the id exists in this file or it does not, so an unknown
+ * name is an error with close candidates, a declaration nothing realizes is a
+ * warning, and the vocabulary cannot drift while looking authoritative. The
+ * long-lived capability documents themselves (one page per capability, revised
+ * by features) stay outside loam — that is the roadmap's evidence-gated Later
+ * item, and the rollup built over these names is the evidence that decides it.
+ *
+ * The OPT-IN also differs from the authorization axis, on purpose: there the
+ * `Requires:` line is the opt-in and a missing permissions.yaml is an error at
+ * the line; here the FILE is the opt-in — a fleet with no capabilities.yaml
+ * produces no capability findings at all (`core/capabilities/findings.ts`
+ * holds the rule and the reason).
+ */
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { isRecord } from "../kernel/records.js";
+import { capabilitiesPath } from "../repo/paths.js";
+import { capabilityDocsDir } from "../repo/authored/paths.js";
+import { readCapabilityTree } from "./tree.js";
+const NO_TREE = { present: false, docs: [], undocumented: [] };
+const EMPTY = { present: false, byId: new Map(), tree: NO_TREE };
+/**
+ * Read the vocabulary — exactly `permissions.ts`'s defensive ladder, because
+ * the two files fail the same ways: a missing file is silence, a YAML error or
+ * a non-mapping shape is `invalid` (one finding for the whole run, the family
+ * suppressed behind it), an empty document is a present-and-empty vocabulary,
+ * and a declaration whose body is not a mapping is treated as `{}` rather than
+ * refusing the whole file over one leaf.
+ */
+export async function readCapabilities(path) {
+    if (!existsSync(path))
+        return EMPTY;
+    let doc;
+    try {
+        doc = parseYaml(await readFile(path, "utf8"));
+    }
+    catch (e) {
+        return { ...EMPTY, present: true, invalid: e instanceof Error ? e.message : String(e) };
+    }
+    if (doc === null || doc === undefined)
+        return { ...EMPTY, present: true };
+    if (!isRecord(doc))
+        return { ...EMPTY, present: true, invalid: "the document is not a mapping" };
+    const block = doc["capabilities"];
+    if (block === undefined)
+        return { ...EMPTY, present: true };
+    if (!isRecord(block)) {
+        return { ...EMPTY, present: true, invalid: "`capabilities` is not a mapping of capability id to its declaration" };
+    }
+    const byId = new Map();
+    for (const [id, body] of Object.entries(block)) {
+        const decl = isRecord(body) ? body : {};
+        byId.set(id, {
+            id,
+            source: "yaml",
+            ...(typeof decl["description"] === "string" ? { description: decl["description"] } : {}),
+            ...(typeof decl["owner"] === "string" ? { owner: decl["owner"] } : {}),
+        });
+    }
+    return { ...EMPTY, present: true, byId };
+}
+/**
+ * THE vocabulary — both sides read and merged, and the only shape a grader
+ * should ever be handed.
+ *
+ * `readCapabilities` above stays exported for the one reader that genuinely
+ * means the file alone (its own tests), but nothing that grades a fleet may use
+ * it: a `Capability:` line naming an id the tree declares and the YAML does not
+ * would resolve through the union and fail through the file, so a second
+ * spelling of "the vocabulary" is a second answer to `capability.unknown`.
+ *
+ * WHERE AN ID SITS ON BOTH SIDES THE YAML'S METADATA SURVIVES, and not by
+ * precedence — the document has nothing to overwrite it with. `description` and
+ * `owner` are fields, and this axis's own rule is that an entry without prose
+ * stays a line in YAML; the document's contribution is the narrative and the
+ * requirements, which are prose, and loam reads frontmatter, never prose. So a
+ * capability declared only in the tree has no owner in `loam list
+ * capabilities`, and that is the honest reading rather than a gap: nobody wrote
+ * one down. What the merge adds on that side is `spec` and `source`.
+ *
+ * An UNREADABLE YAML suspends the whole family (`gradableCapabilityIds` in
+ * `./findings.ts` is the one statement of that ladder), and the tree is still
+ * walked and still carried: `capability.doc-missing` is a fact about
+ * directories that no YAML failure makes untrue, and suppressing it behind an
+ * unrelated broken file would hide a half-created capability until somebody
+ * fixed a document it has nothing to do with.
+ */
+export async function readCapabilityVocabulary(docsDir) {
+    const [yaml, tree] = await Promise.all([
+        readCapabilities(capabilitiesPath(docsDir)),
+        readCapabilityTree(capabilityDocsDir(docsDir)),
+    ]);
+    const byId = new Map(yaml.byId);
+    for (const doc of tree.docs) {
+        const declared = byId.get(doc.id);
+        byId.set(doc.id, {
+            ...declared,
+            id: doc.id,
+            source: declared === undefined ? "tree" : "both",
+            spec: doc.spec,
+        });
+    }
+    return {
+        ...yaml,
+        present: yaml.present || tree.present,
+        byId,
+        tree,
+    };
+}
+//# sourceMappingURL=capabilities.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../../src/core/capabilities/capabilities.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet's capability vocabulary: which business capabilities exist, by\n * declared name, so a requirement's `Capability:` line resolves or refuses\n * instead of silently labelling.\n *\n * It is a fleet document (`architecture/capabilities.yaml`, beside the\n * landscape and the permissions vocabulary) because a capability crosses\n * services by definition — \"registration\" is realized by requirements in four\n * repositories, and a per-service copy would be N spellings of one word.\n *\n * What this is NOT, deliberately: a domain model, and not an authored prose\n * layer either. SCHEMA.md rejected a free-text `capability:` label because\n * nothing could check it; a DECLARED name is different in exactly the way that\n * mattered there — the id exists in this file or it does not, so an unknown\n * name is an error with close candidates, a declaration nothing realizes is a\n * warning, and the vocabulary cannot drift while looking authoritative. The\n * long-lived capability documents themselves (one page per capability, revised\n * by features) stay outside loam — that is the roadmap's evidence-gated Later\n * item, and the rollup built over these names is the evidence that decides it.\n *\n * The OPT-IN also differs from the authorization axis, on purpose: there the\n * `Requires:` line is the opt-in and a missing permissions.yaml is an error at\n * the line; here the FILE is the opt-in — a fleet with no capabilities.yaml\n * produces no capability findings at all (`core/capabilities/findings.ts`\n * holds the rule and the reason).\n */\nimport { readFile } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\nimport { parse as parseYaml } from \"yaml\";\nimport { isRecord } from \"../kernel/records.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport { capabilitiesPath } from \"../repo/paths.js\";\nimport { capabilityDocsDir } from \"../repo/authored/paths.js\";\nimport { readCapabilityTree, type CapabilityTree } from \"./tree.js\";\n\n/** One declared capability. The id is the full key, slashes preserved. */\nexport interface Capability {\n  /**\n   * The token a requirement's `Capability:` line writes. Nesting is spelled\n   * INSIDE the id (`payments/refunds`) and never collapsed — the key is\n   * exactly the string a requirement names, greppable as written.\n   */\n  id: string;\n  description?: string;\n  /**\n   * A team or a person — deliberately `owner:`, not permissions' `owned_by:`,\n   * because that field carries \"defining service\" semantics a capability does\n   * not have. Never resolved against anything; a blank is a worse answer than\n   * an unverified one.\n   */\n  owner?: string;\n  /**\n   * Which side declared this id. `yaml` is a name in\n   * `architecture/capabilities.yaml` with no document; `tree` is a\n   * `capabilities/<id>/spec.md` the YAML does not name; `both` is the same id\n   * on both sides, which is normal rather than a duplicate — the YAML declared\n   * the word first and somebody has since written the document for it.\n   *\n   * Recorded rather than derived at each reader, because the two sides carry\n   * different fixes: a `yaml`-only capability is fixed by writing the document,\n   * a `tree`-only one needs no fix at all, and a message that could not tell\n   * them apart would advise editing a file that may not exist.\n   */\n  source: \"yaml\" | \"tree\" | \"both\";\n  /** `capabilities/<id>/spec.md`, absolute, when the tree declares this id. */\n  spec?: string;\n}\n\nexport interface CapabilityVocabulary {\n  /**\n   * False when NEITHER `architecture/capabilities.yaml` nor `capabilities/`\n   * exists. Either one is the axis's opt-in, so a fleet holding neither\n   * produces no capability finding at all, however many `Capability:` lines its\n   * requirements already carry.\n   */\n  present: boolean;\n  /**\n   * Why `architecture/capabilities.yaml` could not be read as a vocabulary,\n   * when it could not. The TREE has no such state: a directory either lists or\n   * it does not, and an unreadable one is a filesystem failure the walk lets\n   * throw rather than a document loam misread.\n   */\n  invalid?: string;\n  /** Declared capabilities, keyed by the full id — the union of both sides. */\n  byId: Map<string, Capability>;\n  /** What the `capabilities/` walk found, for the graders that need the paths. */\n  tree: CapabilityTree;\n}\n\nconst NO_TREE: CapabilityTree = { present: false, docs: [], undocumented: [] };\nconst EMPTY: CapabilityVocabulary = { present: false, byId: new Map(), tree: NO_TREE };\n\n/**\n * Read the vocabulary — exactly `permissions.ts`'s defensive ladder, because\n * the two files fail the same ways: a missing file is silence, a YAML error or\n * a non-mapping shape is `invalid` (one finding for the whole run, the family\n * suppressed behind it), an empty document is a present-and-empty vocabulary,\n * and a declaration whose body is not a mapping is treated as `{}` rather than\n * refusing the whole file over one leaf.\n */\nexport async function readCapabilities(path: string): Promise<CapabilityVocabulary> {\n  if (!existsSync(path)) return EMPTY;\n  let doc: unknown;\n  try {\n    doc = parseYaml(await readFile(path, \"utf8\"));\n  } catch (e) {\n    return { ...EMPTY, present: true, invalid: e instanceof Error ? e.message : String(e) };\n  }\n  if (doc === null || doc === undefined) return { ...EMPTY, present: true };\n  if (!isRecord(doc)) return { ...EMPTY, present: true, invalid: \"the document is not a mapping\" };\n\n  const block = doc[\"capabilities\"];\n  if (block === undefined) return { ...EMPTY, present: true };\n  if (!isRecord(block)) {\n    return { ...EMPTY, present: true, invalid: \"`capabilities` is not a mapping of capability id to its declaration\" };\n  }\n\n  const byId = new Map<string, Capability>();\n  for (const [id, body] of Object.entries(block)) {\n    const decl = isRecord(body) ? body : {};\n    byId.set(id, {\n      id,\n      source: \"yaml\",\n      ...(typeof decl[\"description\"] === \"string\" ? { description: decl[\"description\"] } : {}),\n      ...(typeof decl[\"owner\"] === \"string\" ? { owner: decl[\"owner\"] } : {}),\n    });\n  }\n  return { ...EMPTY, present: true, byId };\n}\n\n/**\n * THE vocabulary — both sides read and merged, and the only shape a grader\n * should ever be handed.\n *\n * `readCapabilities` above stays exported for the one reader that genuinely\n * means the file alone (its own tests), but nothing that grades a fleet may use\n * it: a `Capability:` line naming an id the tree declares and the YAML does not\n * would resolve through the union and fail through the file, so a second\n * spelling of \"the vocabulary\" is a second answer to `capability.unknown`.\n *\n * WHERE AN ID SITS ON BOTH SIDES THE YAML'S METADATA SURVIVES, and not by\n * precedence — the document has nothing to overwrite it with. `description` and\n * `owner` are fields, and this axis's own rule is that an entry without prose\n * stays a line in YAML; the document's contribution is the narrative and the\n * requirements, which are prose, and loam reads frontmatter, never prose. So a\n * capability declared only in the tree has no owner in `loam list\n * capabilities`, and that is the honest reading rather than a gap: nobody wrote\n * one down. What the merge adds on that side is `spec` and `source`.\n *\n * An UNREADABLE YAML suspends the whole family (`gradableCapabilityIds` in\n * `./findings.ts` is the one statement of that ladder), and the tree is still\n * walked and still carried: `capability.doc-missing` is a fact about\n * directories that no YAML failure makes untrue, and suppressing it behind an\n * unrelated broken file would hide a half-created capability until somebody\n * fixed a document it has nothing to do with.\n */\nexport async function readCapabilityVocabulary(docsDir: DocsDir): Promise<CapabilityVocabulary> {\n  const [yaml, tree] = await Promise.all([\n    readCapabilities(capabilitiesPath(docsDir)),\n    readCapabilityTree(capabilityDocsDir(docsDir)),\n  ]);\n  const byId = new Map(yaml.byId);\n  for (const doc of tree.docs) {\n    const declared = byId.get(doc.id);\n    byId.set(doc.id, {\n      ...declared,\n      id: doc.id,\n      source: declared === undefined ? \"tree\" : \"both\",\n      spec: doc.spec,\n    });\n  }\n  return {\n    ...yaml,\n    present: yaml.present || tree.present,\n    byId,\n    tree,\n  };\n}\n"]}

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

@@ -0,0 +1,50 @@
+/**
+ * The capability document's own three grades, applied to a FEATURE'S DELTA.
+ *
+ * `../findings.ts` grades the living `capabilities/<id>/spec.md` and files
+ * Findings for `loam validate`. This is the same three rules shaped as archive
+ * Issues — the twin `capabilityUnknownFindings`/`capabilityUnknownIssues`
+ * already are one directory over, and for the identical reason: severity says
+ * whether the DOCUMENT is valid, gating says whether the MERGE is safe, and the
+ * two questions are asked by two different commands about the same text.
+ *
+ * WITHOUT THIS THE DELTA PATH IS A HOLE THROUGH THE RULE. A capability
+ * requirement carrying `Operations:` is a service requirement filed at the
+ * business altitude — the one thing that makes a second requirements corpus
+ * worth having is that it does not become a second place to write the first
+ * one. Graded only on the living document, that requirement merges cleanly and
+ * earns its error afterwards, against a file whoever reads the finding did not
+ * write and cannot un-merge. So the delta is graded BEFORE the merge, where the
+ * author is still holding the document.
+ *
+ * ADDED AND MODIFIED ONLY. A REMOVED requirement is being retired: demanding a
+ * `Requirement-ID:` on it, or refusing the `Operations:` line it is deleting,
+ * would ask for an edit to text that is about to stop existing. A BASE
+ * requirement is a delta quoting living context, already named by
+ * `delta.requirement-not-merged`, and it merges nothing — two findings for one
+ * mistake is the failure to avoid.
+ *
+ * NO CODES OF ITS OWN, and no message of its own. Every sentence comes from
+ * `capabilityDocFindings`, whose `where` parameter is what points them at the
+ * feature's copy of the document.
+ */
+import { capabilityDocFindings } from "../findings.js";
+/**
+ * The three grades, as archive-gating Issues, over the requirements a
+ * capability delta would actually merge.
+ *
+ * `target.where` is the delta's repo-relative path so a reader is sent to the
+ * file they wrote, and `target.subject` is the capability id so a `--json`
+ * consumer groups by promise rather than by path — the same split every other
+ * capability grade uses.
+ */
+export function capabilityDocIssues(reqs, target) {
+    const merging = reqs.filter((r) => r.kind === "ADDED" || r.kind === "MODIFIED");
+    return capabilityDocFindings(merging, target.subject, target.where).map((f) => ({
+        severity: f.severity,
+        code: f.code,
+        subject: f.subject,
+        message: f.message,
+    }));
+}
+//# sourceMappingURL=doc.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"doc.js","sourceRoot":"","sources":["../../../../src/core/capabilities/delta/doc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,qBAAqB,EAAyB,MAAM,gBAAgB,CAAC;AAI9E;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAmB,EAAE,MAAwB;IAC/E,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;IAChF,OAAO,qBAAqB,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC9E,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,OAAO,EAAE,CAAC,CAAC,OAAO;KACnB,CAAC,CAAC,CAAC;AACN,CAAC","sourcesContent":["/**\n * The capability document's own three grades, applied to a FEATURE'S DELTA.\n *\n * `../findings.ts` grades the living `capabilities/<id>/spec.md` and files\n * Findings for `loam validate`. This is the same three rules shaped as archive\n * Issues — the twin `capabilityUnknownFindings`/`capabilityUnknownIssues`\n * already are one directory over, and for the identical reason: severity says\n * whether the DOCUMENT is valid, gating says whether the MERGE is safe, and the\n * two questions are asked by two different commands about the same text.\n *\n * WITHOUT THIS THE DELTA PATH IS A HOLE THROUGH THE RULE. A capability\n * requirement carrying `Operations:` is a service requirement filed at the\n * business altitude — the one thing that makes a second requirements corpus\n * worth having is that it does not become a second place to write the first\n * one. Graded only on the living document, that requirement merges cleanly and\n * earns its error afterwards, against a file whoever reads the finding did not\n * write and cannot un-merge. So the delta is graded BEFORE the merge, where the\n * author is still holding the document.\n *\n * ADDED AND MODIFIED ONLY. A REMOVED requirement is being retired: demanding a\n * `Requirement-ID:` on it, or refusing the `Operations:` line it is deleting,\n * would ask for an edit to text that is about to stop existing. A BASE\n * requirement is a delta quoting living context, already named by\n * `delta.requirement-not-merged`, and it merges nothing — two findings for one\n * mistake is the failure to avoid.\n *\n * NO CODES OF ITS OWN, and no message of its own. Every sentence comes from\n * `capabilityDocFindings`, whose `where` parameter is what points them at the\n * feature's copy of the document.\n */\nimport { capabilityDocFindings, type CapabilityTarget } from \"../findings.js\";\nimport type { Requirement } from \"../../document/spec.js\";\nimport type { Issue } from \"../../vocabulary/issue.js\";\n\n/**\n * The three grades, as archive-gating Issues, over the requirements a\n * capability delta would actually merge.\n *\n * `target.where` is the delta's repo-relative path so a reader is sent to the\n * file they wrote, and `target.subject` is the capability id so a `--json`\n * consumer groups by promise rather than by path — the same split every other\n * capability grade uses.\n */\nexport function capabilityDocIssues(reqs: Requirement[], target: CapabilityTarget): Issue[] {\n  const merging = reqs.filter((r) => r.kind === \"ADDED\" || r.kind === \"MODIFIED\");\n  return capabilityDocFindings(merging, target.subject, target.where).map((f) => ({\n    severity: f.severity,\n    code: f.code,\n    subject: f.subject,\n    message: f.message,\n  }));\n}\n"]}

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

@@ -0,0 +1,129 @@
+/**
+ * The fleet's capability vocabulary AS THIS FEATURE'S MERGE WOULD LEAVE IT —
+ * the living declarations unioned with what the feature's own capability deltas
+ * add.
+ *
+ * WHY THIS EXISTS AT ALL. Without it the axis's headline flow is refused by an
+ * error code of its own making. `capabilityRequirementIndex` builds from
+ * `vocab.tree.docs`, the LIVING tree, and `realizesUnknownIssues` runs against
+ * it inside a feature delta as an ERROR that gates archive. So an author who
+ * writes `CHECKOUT-REFUND-ONCE` into
+ * `features/FEAT-9/capabilities/checkout/spec.md` and
+ * `Realizes: checkout#CHECKOUT-REFUND-ONCE` into
+ * `features/FEAT-9/specs/billing/spec.md` — the two halves of one change, in one
+ * feature — is told the target does not exist. It does not exist YET, and the
+ * same archive that would land the pointer lands the promise it points at.
+ *
+ * THE GRADE IS TAKEN AGAINST THE POST-MERGE FLEET, which is the only reading
+ * under which both directions of the join mean anything inside a feature. It is
+ * the same judgement the contract axis already makes one axis over, where
+ * `spec-api.op-undefined` is graded against feature ∪ living rather than living
+ * alone.
+ *
+ * IT WIDENS; IT MUST NOT BLIND. Every entry naming something neither side
+ * declares still fails, with the same message and the same close-name
+ * candidates — now drawn from the widened set, so a typo against a requirement
+ * the same feature is adding gets the useful suggestion rather than a list of
+ * ids the author was not writing about.
+ *
+ * THE LADDER SURVIVES. An unreadable `architecture/capabilities.yaml` is still
+ * `invalid`, and `declared: null` still suspends the whole family: a feature
+ * delta cannot make an unreadable vocabulary readable, and grading a hundred
+ * entries against a file nobody can parse is the cascade `../findings.ts`
+ * suppresses.
+ */
+import { requirementDigest } from "../../document/spec.js";
+/**
+ * The vocabulary a feature's deltas would leave behind: every living
+ * declaration, plus every capability id this feature introduces.
+ *
+ * `present` widens too, and that is the point rather than a side effect: a
+ * feature writing the fleet's FIRST capability document is what creates
+ * `capabilities/`, so it is the act of opting in. Grading its own joins against
+ * the vocabulary it is about to create catches the typo before the merge; the
+ * alternative — silence until the document is living — reports the same typo on
+ * somebody else's next `validate --all`, against a document they did not write.
+ *
+ * `tree` is deliberately NOT widened. It lists the LIVING documents under
+ * `capabilities/`, and `capabilityRequirementIndex` reads every one of them and
+ * declares every non-REMOVED requirement it finds. Splicing a feature's delta
+ * path into that list would apply the living rule to a delta — which is right
+ * for ADDED and wrong for BASE, the kind a delta uses to QUOTE living context
+ * and that the merge never writes. The feature side arrives through
+ * `withFeatureRequirements` below instead, where the delta kinds decide.
+ *
+ * An id a feature introduces is recorded `source: "tree"` with no `spec`: the
+ * tree is the side that will declare it once the merge lands, and there is no
+ * living document to name yet. Nothing in the feature-grading path reads either
+ * field — they exist for the fleet-scope messages, which never see this value.
+ */
+export function withFeatureCapabilities(vocab, ids) {
+    if (ids.length === 0)
+        return vocab;
+    const byId = new Map(vocab.byId);
+    for (const id of ids) {
+        if (byId.has(id))
+            continue;
+        byId.set(id, { id, source: "tree" });
+    }
+    return { ...vocab, present: true, byId };
+}
+/**
+ * The `Realizes:` index a feature's deltas would leave behind: the living
+ * requirement ids per capability, plus the ids this feature ADDS or MODIFIES.
+ *
+ * ADDED and MODIFIED, never REMOVED and never BASE.
+ *
+ * BASE is where the exclusion earns its keep: a `## Requirements` section
+ * inside a delta QUOTES living context for a reader, and the merge never writes
+ * it — so an id appearing only there will not exist after the archive either,
+ * and widening on it would resolve a `Realizes:` in silence and leave the fleet
+ * holding a pointer at a promise nobody ever wrote.
+ *
+ * REMOVED is excluded for honesty rather than for effect. A REMOVED requirement
+ * that names something living is already in the index through the LIVING half,
+ * so leaving it out changes no answer; what it must not do is make a delta that
+ * removes something absent — already `delta.removed-unknown` — look resolvable
+ * on top of that.
+ *
+ * WHAT THIS DOES NOT CLOSE, stated because the shape invites the assumption: a
+ * feature that REMOVES a capability requirement a LIVING service requirement
+ * realizes archives clean, and the next `validate --all` reports
+ * `capability.realizes-unknown` against a service document nobody touched.
+ * Catching that needs the join taken in the other direction — the living
+ * `Realizes:` corpus against this feature's removals — which is the mirror of
+ * the ROADMAP's `capability.uncovered` and belongs with it, not here.
+ *
+ * A capability the feature introduces gets an entry even when its delta adds no
+ * requirements, and the empty set is a real answer rather than a filler: it is
+ * what tells `resolveRealizes` to say "declares no requirements yet" instead of
+ * "has no document at all", which are two different fixes.
+ *
+ * `declared === null` returns the index untouched — the ladder, one level down.
+ */
+export function withFeatureRequirements(index, deltas) {
+    if (index.declared === null || deltas.length === 0)
+        return index;
+    const byCapability = new Map(index.byCapability);
+    const digests = new Map(index.digests);
+    for (const delta of deltas) {
+        const ids = new Set(byCapability.get(delta.id) ?? []);
+        // The delta's OWN digest wins for a MODIFIED id: inside a feature window,
+        // the version a `Realizes:` pin should agree with is the one this feature
+        // is about to merge, not the living one it is replacing. Overwriting is
+        // therefore the point, not a collision.
+        const withDigests = new Map(digests.get(delta.id) ?? []);
+        for (const r of delta.reqs) {
+            if (r.kind !== "ADDED" && r.kind !== "MODIFIED")
+                continue;
+            if (r.id === undefined)
+                continue;
+            ids.add(r.id);
+            withDigests.set(r.id, requirementDigest(r));
+        }
+        byCapability.set(delta.id, ids);
+        digests.set(delta.id, withDigests);
+    }
+    return { declared: index.declared, byCapability, digests };
+}
+//# sourceMappingURL=overlay.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.js","sourceRoot":"","sources":["../../../../src/core/capabilities/delta/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAE,iBAAiB,EAAoB,MAAM,wBAAwB,CAAC;AAY7E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAA2B,EAC3B,GAAsB;IAEtB,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAqB,KAAK,CAAC,IAAI,CAAC,CAAC;IACrD,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,SAAS;QAC3B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAiC,EACjC,MAAyC;IAEzC,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACjE,MAAM,YAAY,GAAG,IAAI,GAAG,CAA8B,KAAK,CAAC,YAAY,CAAC,CAAC;IAC9E,MAAM,OAAO,GAAG,IAAI,GAAG,CAAsC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5E,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QACtD,0EAA0E;QAC1E,0EAA0E;QAC1E,wEAAwE;QACxE,wCAAwC;QACxC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAiB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QACzE,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YAC3B,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU;gBAAE,SAAS;YAC1D,IAAI,CAAC,CAAC,EAAE,KAAK,SAAS;gBAAE,SAAS;YACjC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACd,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9C,CAAC;QACD,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC;AAC7D,CAAC","sourcesContent":["/**\n * The fleet's capability vocabulary AS THIS FEATURE'S MERGE WOULD LEAVE IT —\n * the living declarations unioned with what the feature's own capability deltas\n * add.\n *\n * WHY THIS EXISTS AT ALL. Without it the axis's headline flow is refused by an\n * error code of its own making. `capabilityRequirementIndex` builds from\n * `vocab.tree.docs`, the LIVING tree, and `realizesUnknownIssues` runs against\n * it inside a feature delta as an ERROR that gates archive. So an author who\n * writes `CHECKOUT-REFUND-ONCE` into\n * `features/FEAT-9/capabilities/checkout/spec.md` and\n * `Realizes: checkout#CHECKOUT-REFUND-ONCE` into\n * `features/FEAT-9/specs/billing/spec.md` — the two halves of one change, in one\n * feature — is told the target does not exist. It does not exist YET, and the\n * same archive that would land the pointer lands the promise it points at.\n *\n * THE GRADE IS TAKEN AGAINST THE POST-MERGE FLEET, which is the only reading\n * under which both directions of the join mean anything inside a feature. It is\n * the same judgement the contract axis already makes one axis over, where\n * `spec-api.op-undefined` is graded against feature ∪ living rather than living\n * alone.\n *\n * IT WIDENS; IT MUST NOT BLIND. Every entry naming something neither side\n * declares still fails, with the same message and the same close-name\n * candidates — now drawn from the widened set, so a typo against a requirement\n * the same feature is adding gets the useful suggestion rather than a list of\n * ids the author was not writing about.\n *\n * THE LADDER SURVIVES. An unreadable `architecture/capabilities.yaml` is still\n * `invalid`, and `declared: null` still suspends the whole family: a feature\n * delta cannot make an unreadable vocabulary readable, and grading a hundred\n * entries against a file nobody can parse is the cascade `../findings.ts`\n * suppresses.\n */\nimport { requirementDigest, type Requirement } from \"../../document/spec.js\";\nimport type { Capability, CapabilityVocabulary } from \"../capabilities.js\";\nimport type { CapabilityRequirementIndex } from \"../realizes/join.js\";\n\n/** One capability document a feature's delta carries, already parsed. */\nexport interface FeatureCapabilityDelta {\n  /** The capability id — the directory chain under `features/<FEAT>/capabilities/`. */\n  id: string;\n  /** The delta document's requirements, kinds and all. */\n  reqs: Requirement[];\n}\n\n/**\n * The vocabulary a feature's deltas would leave behind: every living\n * declaration, plus every capability id this feature introduces.\n *\n * `present` widens too, and that is the point rather than a side effect: a\n * feature writing the fleet's FIRST capability document is what creates\n * `capabilities/`, so it is the act of opting in. Grading its own joins against\n * the vocabulary it is about to create catches the typo before the merge; the\n * alternative — silence until the document is living — reports the same typo on\n * somebody else's next `validate --all`, against a document they did not write.\n *\n * `tree` is deliberately NOT widened. It lists the LIVING documents under\n * `capabilities/`, and `capabilityRequirementIndex` reads every one of them and\n * declares every non-REMOVED requirement it finds. Splicing a feature's delta\n * path into that list would apply the living rule to a delta — which is right\n * for ADDED and wrong for BASE, the kind a delta uses to QUOTE living context\n * and that the merge never writes. The feature side arrives through\n * `withFeatureRequirements` below instead, where the delta kinds decide.\n *\n * An id a feature introduces is recorded `source: \"tree\"` with no `spec`: the\n * tree is the side that will declare it once the merge lands, and there is no\n * living document to name yet. Nothing in the feature-grading path reads either\n * field — they exist for the fleet-scope messages, which never see this value.\n */\nexport function withFeatureCapabilities(\n  vocab: CapabilityVocabulary,\n  ids: readonly string[],\n): CapabilityVocabulary {\n  if (ids.length === 0) return vocab;\n  const byId = new Map<string, Capability>(vocab.byId);\n  for (const id of ids) {\n    if (byId.has(id)) continue;\n    byId.set(id, { id, source: \"tree\" });\n  }\n  return { ...vocab, present: true, byId };\n}\n\n/**\n * The `Realizes:` index a feature's deltas would leave behind: the living\n * requirement ids per capability, plus the ids this feature ADDS or MODIFIES.\n *\n * ADDED and MODIFIED, never REMOVED and never BASE.\n *\n * BASE is where the exclusion earns its keep: a `## Requirements` section\n * inside a delta QUOTES living context for a reader, and the merge never writes\n * it — so an id appearing only there will not exist after the archive either,\n * and widening on it would resolve a `Realizes:` in silence and leave the fleet\n * holding a pointer at a promise nobody ever wrote.\n *\n * REMOVED is excluded for honesty rather than for effect. A REMOVED requirement\n * that names something living is already in the index through the LIVING half,\n * so leaving it out changes no answer; what it must not do is make a delta that\n * removes something absent — already `delta.removed-unknown` — look resolvable\n * on top of that.\n *\n * WHAT THIS DOES NOT CLOSE, stated because the shape invites the assumption: a\n * feature that REMOVES a capability requirement a LIVING service requirement\n * realizes archives clean, and the next `validate --all` reports\n * `capability.realizes-unknown` against a service document nobody touched.\n * Catching that needs the join taken in the other direction — the living\n * `Realizes:` corpus against this feature's removals — which is the mirror of\n * the ROADMAP's `capability.uncovered` and belongs with it, not here.\n *\n * A capability the feature introduces gets an entry even when its delta adds no\n * requirements, and the empty set is a real answer rather than a filler: it is\n * what tells `resolveRealizes` to say \"declares no requirements yet\" instead of\n * \"has no document at all\", which are two different fixes.\n *\n * `declared === null` returns the index untouched — the ladder, one level down.\n */\nexport function withFeatureRequirements(\n  index: CapabilityRequirementIndex,\n  deltas: readonly FeatureCapabilityDelta[],\n): CapabilityRequirementIndex {\n  if (index.declared === null || deltas.length === 0) return index;\n  const byCapability = new Map<string, ReadonlySet<string>>(index.byCapability);\n  const digests = new Map<string, ReadonlyMap<string, string>>(index.digests);\n  for (const delta of deltas) {\n    const ids = new Set(byCapability.get(delta.id) ?? []);\n    // The delta's OWN digest wins for a MODIFIED id: inside a feature window,\n    // the version a `Realizes:` pin should agree with is the one this feature\n    // is about to merge, not the living one it is replacing. Overwriting is\n    // therefore the point, not a collision.\n    const withDigests = new Map<string, string>(digests.get(delta.id) ?? []);\n    for (const r of delta.reqs) {\n      if (r.kind !== \"ADDED\" && r.kind !== \"MODIFIED\") continue;\n      if (r.id === undefined) continue;\n      ids.add(r.id);\n      withDigests.set(r.id, requirementDigest(r));\n    }\n    byCapability.set(delta.id, ids);\n    digests.set(delta.id, withDigests);\n  }\n  return { declared: index.declared, byCapability, digests };\n}\n"]}

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

@@ -0,0 +1,57 @@
+/**
+ * What one feature's capability deltas CHANGE, summarized once for the two
+ * commands a person reads before an archive.
+ *
+ * `loam show <FEAT>` and `loam delta <FEAT>` mentioned the business corpus
+ * nowhere, and the consequence was the worst shape an informational surface can
+ * have: a feature carrying ONLY a capability delta — which is the first thing an
+ * analyst writes, and exactly what `loam new --capability` now scaffolds —
+ * displayed as a feature that carries nothing. The two surfaces a reader
+ * consults before running `loam archive` therefore disagreed with the archive
+ * that would refuse it.
+ *
+ * ONE SHAPE FOR BOTH, and that is the reason this lives in core rather than in
+ * either command. `show` needs the counts (its service rows are `+N ~N -N`) and
+ * `delta` needs the promises themselves (it is a task brief, and the id in
+ * `Realizes: <capability>#<id>` is the one thing the implementer has to copy
+ * exactly). Two derivations would be two answers to "what does this feature
+ * change here", from the two commands most likely to be read side by side.
+ *
+ * THE READER IS INJECTED, exactly as `../rollup.ts`'s is and for the same
+ * package-graph reason: `core/fleet-context.ts` imports this package for its
+ * memo, so nothing under `src/core/capabilities/` may import it back.
+ *
+ * BASE requirements are counted by neither. A delta's `## Requirements` section
+ * QUOTES living context for a reader and the merge never writes it, so counting
+ * one as a change would report a feature as touching a promise it only cites.
+ * `delta.requirement-not-merged` is the grade for BASE requirements the author
+ * did NOT mean to quote — it exempts `## Requirements` precisely because that
+ * heading is the deliberate quotation — and this module owes the same reading:
+ * quoted or stranded, a BASE requirement merges nothing, so it is no part of
+ * what this feature changes.
+ */
+import { compareIds } from "../../repo/entries.js";
+/**
+ * Summarize each capability delta, ordered by capability id.
+ *
+ * `docs` comes from `featureCapabilityDeltas` (or a `FleetContext`'s memo of
+ * it), so it is already `compareIds`-ordered by the walk; the sort here is the
+ * statement that the order is part of the answer rather than a property of
+ * whoever happened to call.
+ */
+export async function capabilityDeltaSummaries(docs, read) {
+    const out = [];
+    for (const doc of docs) {
+        const reqs = await read(doc.spec);
+        out.push({
+            id: doc.id,
+            spec: doc.spec,
+            added: reqs.filter((r) => r.kind === "ADDED").length,
+            modified: reqs.filter((r) => r.kind === "MODIFIED").length,
+            removed: reqs.filter((r) => r.kind === "REMOVED").length,
+            promises: reqs.flatMap((r) => r.kind === "BASE" ? [] : [{ kind: r.kind, id: r.id ?? null, name: r.name }]),
+        });
+    }
+    return out.sort((a, b) => compareIds(a.id, b.id));
+}
+//# sourceMappingURL=summary.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../../../src/core/capabilities/delta/summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAgCnD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,IAA8B,EAC9B,IAA8C;IAE9C,MAAM,GAAG,GAA6B,EAAE,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,GAAG,CAAC,IAAI,CAAC;YACP,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,MAAM;YACpD,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,MAAM;YAC1D,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,MAAM;YACxD,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAC3B,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAC5E;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACpD,CAAC","sourcesContent":["/**\n * What one feature's capability deltas CHANGE, summarized once for the two\n * commands a person reads before an archive.\n *\n * `loam show <FEAT>` and `loam delta <FEAT>` mentioned the business corpus\n * nowhere, and the consequence was the worst shape an informational surface can\n * have: a feature carrying ONLY a capability delta — which is the first thing an\n * analyst writes, and exactly what `loam new --capability` now scaffolds —\n * displayed as a feature that carries nothing. The two surfaces a reader\n * consults before running `loam archive` therefore disagreed with the archive\n * that would refuse it.\n *\n * ONE SHAPE FOR BOTH, and that is the reason this lives in core rather than in\n * either command. `show` needs the counts (its service rows are `+N ~N -N`) and\n * `delta` needs the promises themselves (it is a task brief, and the id in\n * `Realizes: <capability>#<id>` is the one thing the implementer has to copy\n * exactly). Two derivations would be two answers to \"what does this feature\n * change here\", from the two commands most likely to be read side by side.\n *\n * THE READER IS INJECTED, exactly as `../rollup.ts`'s is and for the same\n * package-graph reason: `core/fleet-context.ts` imports this package for its\n * memo, so nothing under `src/core/capabilities/` may import it back.\n *\n * BASE requirements are counted by neither. A delta's `## Requirements` section\n * QUOTES living context for a reader and the merge never writes it, so counting\n * one as a change would report a feature as touching a promise it only cites.\n * `delta.requirement-not-merged` is the grade for BASE requirements the author\n * did NOT mean to quote — it exempts `## Requirements` precisely because that\n * heading is the deliberate quotation — and this module owes the same reading:\n * quoted or stranded, a BASE requirement merges nothing, so it is no part of\n * what this feature changes.\n */\nimport { compareIds } from \"../../repo/entries.js\";\nimport type { Requirement } from \"../../document/spec.js\";\nimport type { CapabilityDoc } from \"../tree.js\";\n\n/** One promise a delta adds, restates or retires — the `Realizes:` target it creates or removes. */\nexport interface CapabilityDeltaPromise {\n  kind: \"ADDED\" | \"MODIFIED\" | \"REMOVED\";\n  /**\n   * Its `Requirement-ID:`, or null when the delta wrote none. Null rather than\n   * absent because it is a real and reportable state, not a missing field: an\n   * unidentified capability requirement is an ERROR\n   * (`capability.requirement-unidentified`) that gates the archive, and a brief\n   * that silently dropped the row would hide the requirement the author has to\n   * fix.\n   */\n  id: string | null;\n  /** Its `### Requirement:` heading. */\n  name: string;\n}\n\n/** One capability document a feature's delta carries, and what it would merge. */\nexport interface CapabilityDeltaSummary {\n  id: string;\n  /** The delta document, absolute. Callers make it repo-relative for their own payload. */\n  spec: string;\n  added: number;\n  modified: number;\n  removed: number;\n  /** Every non-BASE requirement, in document order — the promises this delta moves. */\n  promises: CapabilityDeltaPromise[];\n}\n\n/**\n * Summarize each capability delta, ordered by capability id.\n *\n * `docs` comes from `featureCapabilityDeltas` (or a `FleetContext`'s memo of\n * it), so it is already `compareIds`-ordered by the walk; the sort here is the\n * statement that the order is part of the answer rather than a property of\n * whoever happened to call.\n */\nexport async function capabilityDeltaSummaries(\n  docs: readonly CapabilityDoc[],\n  read: (path: string) => Promise<Requirement[]>,\n): Promise<CapabilityDeltaSummary[]> {\n  const out: CapabilityDeltaSummary[] = [];\n  for (const doc of docs) {\n    const reqs = await read(doc.spec);\n    out.push({\n      id: doc.id,\n      spec: doc.spec,\n      added: reqs.filter((r) => r.kind === \"ADDED\").length,\n      modified: reqs.filter((r) => r.kind === \"MODIFIED\").length,\n      removed: reqs.filter((r) => r.kind === \"REMOVED\").length,\n      promises: reqs.flatMap((r) =>\n        r.kind === \"BASE\" ? [] : [{ kind: r.kind, id: r.id ?? null, name: r.name }],\n      ),\n    });\n  }\n  return out.sort((a, b) => compareIds(a.id, b.id));\n}\n"]}

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

@@ -0,0 +1,43 @@
+/**
+ * A feature's own capability deltas: `features/<FEAT>/capabilities/<id>/spec.md`.
+ *
+ * The business axis's answer to `specs/<svc>/spec.md`. A capability document is
+ * a requirements document like any other, so a feature that changes one writes
+ * a DELTA against it rather than editing the living text in place — which buys
+ * the three things the living tree has never had: a `Based-On:` pin, so two PRs
+ * touching one capability collide loudly instead of silently overwriting each
+ * other; the delta algebra's refusals (`delta.added-duplicate`,
+ * `delta.modified-unknown`, …), so a diff that lands nothing says so; and a
+ * business change that ships and unships with the feature that made it.
+ *
+ * BOTH LIFECYCLES COEXIST AND MUST. Nothing here makes a direct edit of
+ * `capabilities/<id>/spec.md` illegal — a fleet mid-adoption edits the document
+ * and always has. What a feature-local delta adds is a second, safer route, and
+ * a direct edit racing one surfaces as `delta.baseline-stale` instead of as
+ * today's silent loss.
+ *
+ * ONE CALL, because the walk is already written: `readCapabilityTree`
+ * implements the presence-classifies rule, the symlink-cycle guard and the
+ * `compareIds` ordering over any root. Re-deriving it here for the feature side
+ * would be two walks free to disagree about what a capability directory is.
+ *
+ * NO `FleetContext` PARAMETER, and that is load-bearing rather than stylistic:
+ * `core/fleet-context.ts` imports `../capabilities.js`, so nothing under
+ * `src/core/capabilities/` may import it back — a core-root↔capabilities
+ * package cycle `import/no-cycle` cannot see. The memo lives on the class and
+ * calls this; callers holding a context use `context.featureCapabilityDeltas`.
+ */
+import { readCapabilityTree } from "../tree.js";
+import { featureCapabilityDeltasDir } from "../../repo/authored/paths.js";
+/**
+ * The capability documents one feature's delta carries, ordered by id.
+ *
+ * `present: false` — and zero readdirs — when the feature has no
+ * `capabilities/` directory, which is every feature in a fleet that has not
+ * adopted the axis. That short-circuit is `readCapabilityTree`'s own
+ * `existsSync` and it is the whole cost such a fleet pays.
+ */
+export function featureCapabilityDeltas(featureDir) {
+    return readCapabilityTree(featureCapabilityDeltasDir(featureDir));
+}
+//# sourceMappingURL=tree.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../../src/core/capabilities/delta/tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,kBAAkB,EAAuB,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAG1E;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAAsB;IAC5D,OAAO,kBAAkB,CAAC,0BAA0B,CAAC,UAAU,CAAC,CAAC,CAAC;AACpE,CAAC","sourcesContent":["/**\n * A feature's own capability deltas: `features/<FEAT>/capabilities/<id>/spec.md`.\n *\n * The business axis's answer to `specs/<svc>/spec.md`. A capability document is\n * a requirements document like any other, so a feature that changes one writes\n * a DELTA against it rather than editing the living text in place — which buys\n * the three things the living tree has never had: a `Based-On:` pin, so two PRs\n * touching one capability collide loudly instead of silently overwriting each\n * other; the delta algebra's refusals (`delta.added-duplicate`,\n * `delta.modified-unknown`, …), so a diff that lands nothing says so; and a\n * business change that ships and unships with the feature that made it.\n *\n * BOTH LIFECYCLES COEXIST AND MUST. Nothing here makes a direct edit of\n * `capabilities/<id>/spec.md` illegal — a fleet mid-adoption edits the document\n * and always has. What a feature-local delta adds is a second, safer route, and\n * a direct edit racing one surfaces as `delta.baseline-stale` instead of as\n * today's silent loss.\n *\n * ONE CALL, because the walk is already written: `readCapabilityTree`\n * implements the presence-classifies rule, the symlink-cycle guard and the\n * `compareIds` ordering over any root. Re-deriving it here for the feature side\n * would be two walks free to disagree about what a capability directory is.\n *\n * NO `FleetContext` PARAMETER, and that is load-bearing rather than stylistic:\n * `core/fleet-context.ts` imports `../capabilities.js`, so nothing under\n * `src/core/capabilities/` may import it back — a core-root↔capabilities\n * package cycle `import/no-cycle` cannot see. The memo lives on the class and\n * calls this; callers holding a context use `context.featureCapabilityDeltas`.\n */\nimport { readCapabilityTree, type CapabilityTree } from \"../tree.js\";\nimport { featureCapabilityDeltasDir } from \"../../repo/authored/paths.js\";\nimport type { FeatureDir } from \"../../kernel/ids/dirs.js\";\n\n/**\n * The capability documents one feature's delta carries, ordered by id.\n *\n * `present: false` — and zero readdirs — when the feature has no\n * `capabilities/` directory, which is every feature in a fleet that has not\n * adopted the axis. That short-circuit is `readCapabilityTree`'s own\n * `existsSync` and it is the whole cost such a fleet pays.\n */\nexport function featureCapabilityDeltas(featureDir: FeatureDir): Promise<CapabilityTree> {\n  return readCapabilityTree(featureCapabilityDeltasDir(featureDir));\n}\n"]}