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

package/dist/core/c4/workspace.js

@@ -0,0 +1,166 @@
+/**
+ * Batch loader: many self-contained `.likec4` documents through ONE
+ * LikeC4/Langium workspace.
+ *
+ * `loadFile` pays a fresh workspace per call — ~100ms even warm — which is what
+ * made `validate --all` O(documents) workspace spins (13.7s median over the
+ * 120-service benchmark fixture, docs/BENCHMARKS.md). This module copies every
+ * document into a mkdtemp workspace as one single-file PROJECT each (a
+ * `likec4.config.json` per folder), calls `LikeC4.fromWorkspace` once, splits
+ * `getErrors()` per document, and reads each clean project through the same
+ * `cleanDoc` the per-file path uses. Parity — byte-identical error
+ * messages/lines and identical elements/relationships — is pinned by
+ * test/likec4-batch-parity.test.ts, which is also the tripwire for the exact
+ * likec4 version pin: multi-project workspaces are public API, but this use of
+ * them is not documented, so an upgrade must fail that suite before it lands.
+ *
+ * Isolation is load-bearing, not cosmetic: `fromSource` gives each document a
+ * workspace of its own, so an author-written `import ... from 'name'` can never
+ * resolve. In a shared workspace it COULD — a sibling project is one lucky name
+ * away — so every folder carries one crypto-random per-invocation hex token in
+ * its project name. A document cannot import what it cannot name, and the
+ * parity suite pins that a guessed sibling name errors identically in both
+ * modes.
+ *
+ * Callers own the failure story: a document that cannot be staged (unreadable,
+ * missing) is silently DROPPED from the result so the caller's ordinary
+ * per-path load reproduces today's error, and a batch-infrastructure failure
+ * (tmpdir denied — the sandboxed-runner class ROADMAP documents) rejects the
+ * whole call for the caller to catch and degrade. FleetContext.prefetchLikeC4
+ * does exactly that: findings can never change because a workspace could not be
+ * created, only the speed can.
+ *
+ * This file took core/c4/ to exactly five files, and the seam that note
+ * predicted is now open: `./project/load.ts` loads a DIRECTORY as one project,
+ * which is the opposite isolation contract and belongs beside this one rather
+ * than inside it.
+ */
+import { randomBytes } from "node:crypto";
+import { inOrder } from "../kernel/concurrency.js";
+import { copyFile, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { LikeC4 } from "likec4";
+import { cleanDoc, distinctErrors } from "./likec4.js";
+/**
+ * Stage every readable document as its own single-file project. A copy failure
+ * removes the half-made folder and drops the path — an empty project must not
+ * reach the workspace scan, and the caller's per-path load owns the error. The
+ * copy is `copyFile` (raw bytes), not read/decode/write: BOM, CRLF and even
+ * non-UTF-8 bytes reach LikeC4's own reader exactly as they would from the
+ * original file on disk.
+ */
+async function stage(root, targets) {
+    const token = randomBytes(8).toString("hex");
+    // Concurrent, capped, in input order (kernel/concurrency's contract): the
+    // per-document folders share nothing, and on a network-mounted docs repo
+    // the sequential form paid three round-trips per document. Nulls mark the
+    // drops so indices — and with them the p<i> project names — stay aligned.
+    const results = await inOrder([...targets.entries()], async ([i, path]) => {
+        const project = `p${i}_${token}`;
+        const folder = join(root, project);
+        try {
+            await mkdir(folder);
+            await writeFile(join(folder, "likec4.config.json"), JSON.stringify({ name: project }), "utf8");
+            await copyFile(path, join(folder, basename(path)));
+            return { path, project };
+        }
+        catch {
+            await rm(folder, { recursive: true, force: true });
+            return null;
+        }
+    });
+    return results.filter((r) => r !== null);
+}
+/**
+ * `getErrors()` split per document, each error's `sourceFsPath` rewritten from
+ * the workspace copy to the document's real absolute path.
+ *
+ * Grouping keys on the unique `p<i>_<token>` path SEGMENT, never on a
+ * tmp-root prefix compare: darwin hands back realpathed workspace paths
+ * (`/var/...` becomes `/private/var/...`) in some environments and the literal
+ * mkdtemp path in others, and a prefix compare silently attributes every error
+ * to nobody in exactly one of those two worlds. The segment survives both.
+ *
+ * Read through `distinctErrors` exactly as `loadSource` reads them, so a
+ * document's list is the same one in both modes.
+ */
+function groupErrors(likec4, staged) {
+    const pathOf = new Map(staged.map((doc) => [doc.project, doc.path]));
+    const grouped = new Map();
+    for (const err of distinctErrors(likec4.getErrors())) {
+        const project = err.sourceFsPath.split(/[\\/]/).find((segment) => pathOf.has(segment));
+        if (project === undefined) {
+            // An error this walk cannot attribute would otherwise be DROPPED — and a
+            // dropped error grades its document clean, which is failing open in the
+            // fleet gate. Unreachable at the pinned likec4 version (every corpus
+            // error carries its project folder in sourceFsPath), so the one place a
+            // dependency upgrade could break the attribution is the one place that
+            // must reject the whole batch: the caller degrades to per-path loads,
+            // where the error reappears.
+            throw new Error(`unattributable LikeC4 error in batch workspace: ${err.message}`);
+        }
+        const list = grouped.get(project) ?? [];
+        list.push({ ...err, sourceFsPath: pathOf.get(project) });
+        grouped.set(project, list);
+    }
+    return grouped;
+}
+/**
+ * Load and validate many self-contained `.likec4` documents in one workspace.
+ * Returns `resolve(path)` → LoadedDoc; paths are deduped through the same
+ * resolution, and a path that could not be staged is absent from the result.
+ *
+ * A document with errors keeps `loadSource`'s exact rule — empty elements and
+ * relationships, WITHOUT calling `parsedModel`: the parsed stage succeeds even
+ * over unresolved references, so the "errors mean no model" boundary is loam's
+ * to apply, not LikeC4's. A clean document is flattened from
+ * `parsedModel(project)` — parsed, never computed: the computed stage RESOLVES
+ * every view against the model — which loam never wants, because it reads a
+ * view's DECLARATIONS and never a view's resolved contents (docs/DESIGN.md
+ * rule 26) — and which is superlinear in edge count (see loadSource).
+ */
+export async function loadBatch(paths) {
+    const targets = [...new Set(paths.map((path) => resolve(path)))];
+    const out = new Map();
+    if (targets.length === 0)
+        return out;
+    const root = await mkdtemp(join(tmpdir(), "loam-c4-"));
+    try {
+        const staged = await stage(root, targets);
+        if (staged.length === 0)
+            return out;
+        // One workspace for the whole batch — the entire point. The logger is
+        // disabled exactly as in loadSource: diagnostics are returned per document,
+        // not written out-of-band to stderr (core never prints).
+        const likec4 = await LikeC4.fromWorkspace(root, { logger: false });
+        try {
+            const grouped = groupErrors(likec4, staged);
+            for (const { path, project } of staged) {
+                const errors = grouped.get(project) ?? [];
+                if (errors.length > 0) {
+                    out.set(path, { errors, elements: [], relationships: [] });
+                }
+                else {
+                    // Through `cleanDoc`, the one assembly `loadSource` uses too. The
+                    // specification travels with the batch loader and must: this is the
+                    // loader `validate --all` reads the landscape through, so a kind-tag
+                    // check wired only into `loadSource` would be a check the fleet gate
+                    // — the one run it exists for — never actually ran.
+                    out.set(path, cleanDoc((await likec4.parsedModel(project))));
+                }
+            }
+        }
+        finally {
+            await likec4.dispose();
+        }
+        return out;
+    }
+    finally {
+        // The workspace is this invocation's alone; nothing else may observe it.
+        // A kill between mkdtemp and here can strand a loam-c4-* dir in OS tmp —
+        // never in the docs repo — which docs/DESIGN.md records as accepted.
+        await rm(root, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=workspace.js.map

package/dist/core/c4/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../../src/core/c4/workspace.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Batch loader: many self-contained `.likec4` documents through ONE\n * LikeC4/Langium workspace.\n *\n * `loadFile` pays a fresh workspace per call — ~100ms even warm — which is what\n * made `validate --all` O(documents) workspace spins (13.7s median over the\n * 120-service benchmark fixture, docs/BENCHMARKS.md). This module copies every\n * document into a mkdtemp workspace as one single-file PROJECT each (a\n * `likec4.config.json` per folder), calls `LikeC4.fromWorkspace` once, splits\n * `getErrors()` per document, and reads each clean project through the same\n * `cleanDoc` the per-file path uses. Parity — byte-identical error\n * messages/lines and identical elements/relationships — is pinned by\n * test/likec4-batch-parity.test.ts, which is also the tripwire for the exact\n * likec4 version pin: multi-project workspaces are public API, but this use of\n * them is not documented, so an upgrade must fail that suite before it lands.\n *\n * Isolation is load-bearing, not cosmetic: `fromSource` gives each document a\n * workspace of its own, so an author-written `import ... from 'name'` can never\n * resolve. In a shared workspace it COULD — a sibling project is one lucky name\n * away — so every folder carries one crypto-random per-invocation hex token in\n * its project name. A document cannot import what it cannot name, and the\n * parity suite pins that a guessed sibling name errors identically in both\n * modes.\n *\n * Callers own the failure story: a document that cannot be staged (unreadable,\n * missing) is silently DROPPED from the result so the caller's ordinary\n * per-path load reproduces today's error, and a batch-infrastructure failure\n * (tmpdir denied — the sandboxed-runner class ROADMAP documents) rejects the\n * whole call for the caller to catch and degrade. FleetContext.prefetchLikeC4\n * does exactly that: findings can never change because a workspace could not be\n * created, only the speed can.\n *\n * This file took core/c4/ to exactly five files, and the seam that note\n * predicted is now open: `./project/load.ts` loads a DIRECTORY as one project,\n * which is the opposite isolation contract and belongs beside this one rather\n * than inside it.\n */\nimport { randomBytes } from \"node:crypto\";\nimport { inOrder } from \"../kernel/concurrency.js\";\nimport { copyFile, mkdir, mkdtemp, rm, writeFile } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { basename, join, resolve } from \"node:path\";\nimport { LikeC4 } from \"likec4\";\nimport { cleanDoc, distinctErrors, type LikeC4Error, type LoadedDoc, type ReadableModel } from \"./likec4.js\";\n\n/** A staged document: the real path it came from, and its workspace project. */\ninterface StagedDoc {\n  path: string;\n  project: string;\n}\n\n/**\n * Stage every readable document as its own single-file project. A copy failure\n * removes the half-made folder and drops the path — an empty project must not\n * reach the workspace scan, and the caller's per-path load owns the error. The\n * copy is `copyFile` (raw bytes), not read/decode/write: BOM, CRLF and even\n * non-UTF-8 bytes reach LikeC4's own reader exactly as they would from the\n * original file on disk.\n */\nasync function stage(root: string, targets: string[]): Promise<StagedDoc[]> {\n  const token = randomBytes(8).toString(\"hex\");\n  // Concurrent, capped, in input order (kernel/concurrency's contract): the\n  // per-document folders share nothing, and on a network-mounted docs repo\n  // the sequential form paid three round-trips per document. Nulls mark the\n  // drops so indices — and with them the p<i> project names — stay aligned.\n  const results = await inOrder([...targets.entries()], async ([i, path]) => {\n    const project = `p${i}_${token}`;\n    const folder = join(root, project);\n    try {\n      await mkdir(folder);\n      await writeFile(join(folder, \"likec4.config.json\"), JSON.stringify({ name: project }), \"utf8\");\n      await copyFile(path, join(folder, basename(path)));\n      return { path, project };\n    } catch {\n      await rm(folder, { recursive: true, force: true });\n      return null;\n    }\n  });\n  return results.filter((r): r is StagedDoc => r !== null);\n}\n\n/**\n * `getErrors()` split per document, each error's `sourceFsPath` rewritten from\n * the workspace copy to the document's real absolute path.\n *\n * Grouping keys on the unique `p<i>_<token>` path SEGMENT, never on a\n * tmp-root prefix compare: darwin hands back realpathed workspace paths\n * (`/var/...` becomes `/private/var/...`) in some environments and the literal\n * mkdtemp path in others, and a prefix compare silently attributes every error\n * to nobody in exactly one of those two worlds. The segment survives both.\n *\n * Read through `distinctErrors` exactly as `loadSource` reads them, so a\n * document's list is the same one in both modes.\n */\nfunction groupErrors(likec4: LikeC4, staged: StagedDoc[]): Map<string, LikeC4Error[]> {\n  const pathOf = new Map(staged.map((doc) => [doc.project, doc.path]));\n  const grouped = new Map<string, LikeC4Error[]>();\n  for (const err of distinctErrors(likec4.getErrors())) {\n    const project = err.sourceFsPath.split(/[\\\\/]/).find((segment) => pathOf.has(segment));\n    if (project === undefined) {\n      // An error this walk cannot attribute would otherwise be DROPPED — and a\n      // dropped error grades its document clean, which is failing open in the\n      // fleet gate. Unreachable at the pinned likec4 version (every corpus\n      // error carries its project folder in sourceFsPath), so the one place a\n      // dependency upgrade could break the attribution is the one place that\n      // must reject the whole batch: the caller degrades to per-path loads,\n      // where the error reappears.\n      throw new Error(`unattributable LikeC4 error in batch workspace: ${err.message}`);\n    }\n    const list = grouped.get(project) ?? [];\n    list.push({ ...err, sourceFsPath: pathOf.get(project) });\n    grouped.set(project, list);\n  }\n  return grouped;\n}\n\n/**\n * Load and validate many self-contained `.likec4` documents in one workspace.\n * Returns `resolve(path)` → LoadedDoc; paths are deduped through the same\n * resolution, and a path that could not be staged is absent from the result.\n *\n * A document with errors keeps `loadSource`'s exact rule — empty elements and\n * relationships, WITHOUT calling `parsedModel`: the parsed stage succeeds even\n * over unresolved references, so the \"errors mean no model\" boundary is loam's\n * to apply, not LikeC4's. A clean document is flattened from\n * `parsedModel(project)` — parsed, never computed: the computed stage RESOLVES\n * every view against the model — which loam never wants, because it reads a\n * view's DECLARATIONS and never a view's resolved contents (docs/DESIGN.md\n * rule 26) — and which is superlinear in edge count (see loadSource).\n */\nexport async function loadBatch(paths: string[]): Promise<Map<string, LoadedDoc>> {\n  const targets = [...new Set(paths.map((path) => resolve(path)))];\n  const out = new Map<string, LoadedDoc>();\n  if (targets.length === 0) return out;\n  const root = await mkdtemp(join(tmpdir(), \"loam-c4-\"));\n  try {\n    const staged = await stage(root, targets);\n    if (staged.length === 0) return out;\n    // One workspace for the whole batch — the entire point. The logger is\n    // disabled exactly as in loadSource: diagnostics are returned per document,\n    // not written out-of-band to stderr (core never prints).\n    const likec4 = await LikeC4.fromWorkspace(root, { logger: false });\n    try {\n      const grouped = groupErrors(likec4, staged);\n      for (const { path, project } of staged) {\n        const errors = grouped.get(project) ?? [];\n        if (errors.length > 0) {\n          out.set(path, { errors, elements: [], relationships: [] });\n        } else {\n          // Through `cleanDoc`, the one assembly `loadSource` uses too. The\n          // specification travels with the batch loader and must: this is the\n          // loader `validate --all` reads the landscape through, so a kind-tag\n          // check wired only into `loadSource` would be a check the fleet gate\n          // — the one run it exists for — never actually ran.\n          out.set(path, cleanDoc((await likec4.parsedModel(project)) as ReadableModel));\n        }\n      }\n    } finally {\n      await likec4.dispose();\n    }\n    return out;\n  } finally {\n    // The workspace is this invocation's alone; nothing else may observe it.\n    // A kill between mkdtemp and here can strand a loam-c4-* dir in OS tmp —\n    // never in the docs repo — which docs/DESIGN.md records as accepted.\n    await rm(root, { recursive: true, force: true });\n  }\n}\n"]}

package/dist/core/capabilities/authoring/notes.js

@@ -0,0 +1,141 @@
+/**
+ * What `loam new --capability <id>` says about the capability it just scaffolded
+ * a delta for.
+ *
+ * NOTES, NEVER REFUSALS, and the whole judgement is in that word. A capability
+ * the fleet has never named is exactly what an analyst opening a new business
+ * area types, and it is the case the flag exists for: `--touches <services>`
+ * asks for the services before the business change is written, and inverting
+ * that only works if naming a new promise is the ordinary path rather than the
+ * refused one. The archive that lands this feature is what creates
+ * `capabilities/<id>/spec.md` (`commands/archive/plan/specs.ts`), so there is
+ * nothing to declare first.
+ *
+ * THE OTHER READING STAYS AVAILABLE IN THE MESSAGE. The failure a refusal would
+ * have caught is the typo — `payments/refund` against a living
+ * `payments/refunds` is a second capability created out of nothing, with the
+ * promise filed where nobody looks — so the close names are spelled out
+ * alongside, exactly as `--touches`' own near-miss note spells them, together
+ * with the way back out. That is the same trade `unknownServiceNotes` makes in
+ * `commands/new/new.ts`, and it is deliberate that the two flags behave alike:
+ * "names something that does not exist yet" is legitimate on both.
+ *
+ * THE NEAR-MISS RULE IS `nearestIds`, NOT `closeIds`, and on this axis the two
+ * disagree loudly. `closeIds` matches on substring either way, so
+ * `payments/refunds` reports its own PARENT `payments` as a candidate — nesting
+ * spelled by the tree is the axis's headline shape, and a note telling an author
+ * their new sub-capability is a misspelling of the group it sits in is worse
+ * than no note. `nearestIds` is the edit-distance "did you misspell a directory"
+ * rule, which is the question actually being asked here, and
+ * `core/repo/entries.ts` states that division at its own definition.
+ *
+ * THE WAY OUT NAMES THIS FEATURE'S DIRECTORY, never `features/`. loam ships
+ * instructions people and agents type back; `features/` holds every in-flight
+ * feature in a SHARED docs repo, so an instruction to delete it is an
+ * instruction to destroy other authors' work. `dirName` is threaded in for that
+ * one sentence — the same care `validate/feature.ts` takes to spell
+ * `features/FEAT-1-split/` rather than `features/FEAT-1/`.
+ *
+ * WHAT IT DOES NOT SAY, and why not: which services realize this capability
+ * today. `capabilityRollup` knows, and the line would be useful, but it walks
+ * every service's `spec.md` AND `arch.spec.md` across the whole fleet — a cost
+ * proportional to the service tree, paid by a command whose job is to create
+ * four files, and `loam new` sits in the authoring hot path. `loam list
+ * capabilities` already computes exactly that answer and the note points at it.
+ * The half that IS read here is the one an author cannot write the delta
+ * without — the living document's own requirement ids, which is what a MODIFIED
+ * section addresses and what an ADDED section must not repeat — and that is one
+ * file, the very file this delta diffs against.
+ *
+ * IN CORE, not beside the command, for the rule the command layer is held to:
+ * `commands/` parses arguments, calls core and prints. Which of a fleet's two
+ * vocabularies declared an id, and which of a capability's requirements are
+ * addressable, are questions about the DOCUMENTS — the same questions
+ * `../findings.ts` answers as findings — and the only thing this module does
+ * differently is answer them for a person who has not written anything yet.
+ */
+import { readFile } from "node:fs/promises";
+import { compareIds, nearestIds } from "../../repo/entries.js";
+import { parseRequirements } from "../../document/parse.js";
+import { readCapabilityVocabulary } from "../capabilities.js";
+/**
+ * One note per `--capability` id: is this promise already declared, and if so
+ * what does it already say?
+ *
+ * The vocabulary read is the UNION of `architecture/capabilities.yaml` and the
+ * `capabilities/` tree, never one side, for the reason `capabilities.ts` states:
+ * a second spelling of "the vocabulary" is a second answer to whether an id is
+ * known, and this note and `capability.unknown` must not be able to disagree.
+ */
+export async function capabilityNotes(docsDir, scope) {
+    if (scope.ids.length === 0)
+        return [];
+    const vocab = await readCapabilityVocabulary(docsDir);
+    const declared = [...vocab.byId.keys()].sort(compareIds);
+    const notes = [];
+    for (const id of scope.ids) {
+        const known = vocab.byId.get(id);
+        if (known === undefined) {
+            const near = nearestIds(id, declared);
+            notes.push(`--capability '${id}' is a capability this fleet has not named yet — nothing declares it in ` +
+                `architecture/capabilities.yaml or capabilities/${id}/spec.md. That is legal and often the point: ` +
+                `archiving this feature CREATES capabilities/${id}/spec.md from the delta just scaffolded` +
+                (near.length === 0
+                    ? "."
+                    : `. If you meant an existing one — ${near.map((n) => `'${n}'`).join(" or ")} — rename ` +
+                        `features/${scope.dirName}/capabilities/${id}/ to that spelling, or delete features/${scope.dirName}/ and re-run \`loam new\`.`));
+            continue;
+        }
+        if (known.spec === undefined) {
+            // Declared in the YAML with no document behind it: the ordinary
+            // mid-adoption state, and the one case where this feature is writing the
+            // fleet's first prose for a word it already had.
+            notes.push(`--capability '${id}' is declared in architecture/capabilities.yaml but has no capabilities/${id}/spec.md yet — ` +
+                "this feature's delta is the first prose behind that word, and archiving it writes the document.");
+            continue;
+        }
+        notes.push(livingNote(id, await requirementIds(known.spec)));
+    }
+    return notes;
+}
+/**
+ * The living document's requirement ids, in document order.
+ *
+ * A requirement WITHOUT a `Requirement-ID:` is skipped rather than named by its
+ * heading, matching every other reader on this axis: nothing can address it, so
+ * offering the heading as an address would teach exactly the identity-by-heading
+ * `capability.requirement-unidentified` refuses.
+ *
+ * An unreadable document is NOT fatal here. This is a note printed after the
+ * scaffold has already committed, and the alternative — throwing out of a
+ * successful `loam new` — would report the write as a failure. `loam validate`
+ * owns the diagnosis of a living document nobody can read.
+ */
+async function requirementIds(spec) {
+    try {
+        return parseRequirements(await readFile(spec, "utf8")).flatMap((r) => r.kind === "REMOVED" || r.id === undefined ? [] : [r.id]);
+    }
+    catch {
+        return null;
+    }
+}
+/** The note for a capability that already has a document — what the delta is a diff against. */
+function livingNote(id, ids) {
+    const head = `--capability '${id}' already has capabilities/${id}/spec.md`;
+    if (ids === null)
+        return `${head}, which could not be read — run \`loam validate --all\` before authoring against it.`;
+    if (ids.length === 0) {
+        return (`${head}, and it declares no identified requirements yet — everything in this delta is an ADDED promise. ` +
+            "`loam list capabilities` shows what the fleet already realizes.");
+    }
+    // The ids, not a count: a MODIFIED section addresses one of these and an
+    // ADDED one must not repeat it, so the list IS the thing the author needs in
+    // front of them. Capped, because a long-lived capability can carry dozens and
+    // a note that scrolls is a note nobody reads.
+    const shown = ids.slice(0, 8);
+    return (`${head}, declaring ${ids.length} identified requirement(s): ${shown.join(", ")}` +
+        (ids.length > shown.length ? `, … (\`loam show\` for the rest)` : "") +
+        ". A MODIFIED section addresses one of those ids; an ADDED one must not repeat it. " +
+        "`loam list capabilities` shows which services realize them today.");
+}
+//# sourceMappingURL=notes.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notes.js","sourceRoot":"","sources":["../../../../src/core/capabilities/authoring/notes.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What `loam new --capability <id>` says about the capability it just scaffolded\n * a delta for.\n *\n * NOTES, NEVER REFUSALS, and the whole judgement is in that word. A capability\n * the fleet has never named is exactly what an analyst opening a new business\n * area types, and it is the case the flag exists for: `--touches <services>`\n * asks for the services before the business change is written, and inverting\n * that only works if naming a new promise is the ordinary path rather than the\n * refused one. The archive that lands this feature is what creates\n * `capabilities/<id>/spec.md` (`commands/archive/plan/specs.ts`), so there is\n * nothing to declare first.\n *\n * THE OTHER READING STAYS AVAILABLE IN THE MESSAGE. The failure a refusal would\n * have caught is the typo — `payments/refund` against a living\n * `payments/refunds` is a second capability created out of nothing, with the\n * promise filed where nobody looks — so the close names are spelled out\n * alongside, exactly as `--touches`' own near-miss note spells them, together\n * with the way back out. That is the same trade `unknownServiceNotes` makes in\n * `commands/new/new.ts`, and it is deliberate that the two flags behave alike:\n * \"names something that does not exist yet\" is legitimate on both.\n *\n * THE NEAR-MISS RULE IS `nearestIds`, NOT `closeIds`, and on this axis the two\n * disagree loudly. `closeIds` matches on substring either way, so\n * `payments/refunds` reports its own PARENT `payments` as a candidate — nesting\n * spelled by the tree is the axis's headline shape, and a note telling an author\n * their new sub-capability is a misspelling of the group it sits in is worse\n * than no note. `nearestIds` is the edit-distance \"did you misspell a directory\"\n * rule, which is the question actually being asked here, and\n * `core/repo/entries.ts` states that division at its own definition.\n *\n * THE WAY OUT NAMES THIS FEATURE'S DIRECTORY, never `features/`. loam ships\n * instructions people and agents type back; `features/` holds every in-flight\n * feature in a SHARED docs repo, so an instruction to delete it is an\n * instruction to destroy other authors' work. `dirName` is threaded in for that\n * one sentence — the same care `validate/feature.ts` takes to spell\n * `features/FEAT-1-split/` rather than `features/FEAT-1/`.\n *\n * WHAT IT DOES NOT SAY, and why not: which services realize this capability\n * today. `capabilityRollup` knows, and the line would be useful, but it walks\n * every service's `spec.md` AND `arch.spec.md` across the whole fleet — a cost\n * proportional to the service tree, paid by a command whose job is to create\n * four files, and `loam new` sits in the authoring hot path. `loam list\n * capabilities` already computes exactly that answer and the note points at it.\n * The half that IS read here is the one an author cannot write the delta\n * without — the living document's own requirement ids, which is what a MODIFIED\n * section addresses and what an ADDED section must not repeat — and that is one\n * file, the very file this delta diffs against.\n *\n * IN CORE, not beside the command, for the rule the command layer is held to:\n * `commands/` parses arguments, calls core and prints. Which of a fleet's two\n * vocabularies declared an id, and which of a capability's requirements are\n * addressable, are questions about the DOCUMENTS — the same questions\n * `../findings.ts` answers as findings — and the only thing this module does\n * differently is answer them for a person who has not written anything yet.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { compareIds, nearestIds } from \"../../repo/entries.js\";\nimport { parseRequirements } from \"../../document/parse.js\";\nimport { readCapabilityVocabulary } from \"../capabilities.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\n\n/** Which feature was just scaffolded, and which promises it named. */\nexport interface CapabilityNoteScope {\n  /** The feature's directory NAME (`FEAT-1-split`) — what the way-out sentence spells. */\n  dirName: string;\n  /** The `--capability` ids, in the order they were given. */\n  ids: readonly string[];\n}\n\n/**\n * One note per `--capability` id: is this promise already declared, and if so\n * what does it already say?\n *\n * The vocabulary read is the UNION of `architecture/capabilities.yaml` and the\n * `capabilities/` tree, never one side, for the reason `capabilities.ts` states:\n * a second spelling of \"the vocabulary\" is a second answer to whether an id is\n * known, and this note and `capability.unknown` must not be able to disagree.\n */\nexport async function capabilityNotes(docsDir: DocsDir, scope: CapabilityNoteScope): Promise<string[]> {\n  if (scope.ids.length === 0) return [];\n  const vocab = await readCapabilityVocabulary(docsDir);\n  const declared = [...vocab.byId.keys()].sort(compareIds);\n  const notes: string[] = [];\n  for (const id of scope.ids) {\n    const known = vocab.byId.get(id);\n    if (known === undefined) {\n      const near = nearestIds(id, declared);\n      notes.push(\n        `--capability '${id}' is a capability this fleet has not named yet — nothing declares it in ` +\n          `architecture/capabilities.yaml or capabilities/${id}/spec.md. That is legal and often the point: ` +\n          `archiving this feature CREATES capabilities/${id}/spec.md from the delta just scaffolded` +\n          (near.length === 0\n            ? \".\"\n            : `. If you meant an existing one — ${near.map((n) => `'${n}'`).join(\" or \")} — rename ` +\n              `features/${scope.dirName}/capabilities/${id}/ to that spelling, or delete features/${scope.dirName}/ and re-run \\`loam new\\`.`),\n      );\n      continue;\n    }\n    if (known.spec === undefined) {\n      // Declared in the YAML with no document behind it: the ordinary\n      // mid-adoption state, and the one case where this feature is writing the\n      // fleet's first prose for a word it already had.\n      notes.push(\n        `--capability '${id}' is declared in architecture/capabilities.yaml but has no capabilities/${id}/spec.md yet — ` +\n          \"this feature's delta is the first prose behind that word, and archiving it writes the document.\",\n      );\n      continue;\n    }\n    notes.push(livingNote(id, await requirementIds(known.spec)));\n  }\n  return notes;\n}\n\n/**\n * The living document's requirement ids, in document order.\n *\n * A requirement WITHOUT a `Requirement-ID:` is skipped rather than named by its\n * heading, matching every other reader on this axis: nothing can address it, so\n * offering the heading as an address would teach exactly the identity-by-heading\n * `capability.requirement-unidentified` refuses.\n *\n * An unreadable document is NOT fatal here. This is a note printed after the\n * scaffold has already committed, and the alternative — throwing out of a\n * successful `loam new` — would report the write as a failure. `loam validate`\n * owns the diagnosis of a living document nobody can read.\n */\nasync function requirementIds(spec: string): Promise<string[] | null> {\n  try {\n    return parseRequirements(await readFile(spec, \"utf8\")).flatMap((r) =>\n      r.kind === \"REMOVED\" || r.id === undefined ? [] : [r.id],\n    );\n  } catch {\n    return null;\n  }\n}\n\n/** The note for a capability that already has a document — what the delta is a diff against. */\nfunction livingNote(id: string, ids: string[] | null): string {\n  const head = `--capability '${id}' already has capabilities/${id}/spec.md`;\n  if (ids === null) return `${head}, which could not be read — run \\`loam validate --all\\` before authoring against it.`;\n  if (ids.length === 0) {\n    return (\n      `${head}, and it declares no identified requirements yet — everything in this delta is an ADDED promise. ` +\n      \"`loam list capabilities` shows what the fleet already realizes.\"\n    );\n  }\n  // The ids, not a count: a MODIFIED section addresses one of these and an\n  // ADDED one must not repeat it, so the list IS the thing the author needs in\n  // front of them. Capped, because a long-lived capability can carry dozens and\n  // a note that scrolls is a note nobody reads.\n  const shown = ids.slice(0, 8);\n  return (\n    `${head}, declaring ${ids.length} identified requirement(s): ${shown.join(\", \")}` +\n    (ids.length > shown.length ? `, … (\\`loam show\\` for the rest)` : \"\") +\n    \". A MODIFIED section addresses one of those ids; an ADDED one must not repeat it. \" +\n    \"`loam list capabilities` shows which services realize them today.\"\n  );\n}\n"]}

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.
+ */
+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 is the file alone, and it is private to this
+ * module because 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 */\nasync 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 is the file alone, and it is private to this\n * module because nothing that grades a fleet may use it: a `Capability:` line\n * naming an id the tree declares and the YAML does not would resolve through\n * the union and fail through the file, so a second spelling of \"the\n * 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,47 @@
+/**
+ * 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 filed as archive
+ * Issues — the split `capabilityUnknownIssues` one directory over makes
+ * between its two commands, 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. A grade
+ * is already an Issue in shape (its return type pins severity and code), so
+ * the rules' own objects are returned, not copied field by field.
+ *
+ * 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);
+}
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;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;AACtE,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 filed as archive\n * Issues — the split `capabilityUnknownIssues` one directory over makes\n * between its two commands, 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. A grade\n * is already an Issue in shape (its return type pins severity and code), so\n * the rules' own objects are returned, not copied field by field.\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);\n}\n"]}