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

package/dist/core/c4/splice/placement.js

@@ -0,0 +1,194 @@
+import {} from "../likec4.js";
+import { elementService, serviceOf } from "../resolve/service.js";
+import { relSortKey } from "./identity/edges.js";
+/** The model's top-level statements in document order, joined to the parsed elements for services. */
+export function topStatements(scan, els) {
+    const topEls = scan.elements.filter((e) => !e.id.includes("."));
+    const bound = new Map(els.map((e) => [e.id, elementService(e)]));
+    const stmts = topEls.map((e) => ({
+        kind: "element",
+        id: e.id,
+        key: "",
+        services: [bound.get(e.id) ?? e.id],
+        start: e.start,
+        end: e.end,
+    }));
+    for (const r of scan.rels) {
+        // A rel declared inside an element's body is not a top-level statement —
+        // anchoring after it would splice into the parent's block.
+        if (topEls.some((e) => r.start > e.start && r.start < e.end))
+            continue;
+        stmts.push({
+            kind: "rel",
+            id: "",
+            key: relSortKey(els, r),
+            // Deliberately no `known` fleet set here: this resolution only decides
+            // WHERE in the file a statement anchors, both sides of every comparison
+            // resolve through the same call, and the merged document is re-parsed
+            // before anything is written — a wrong grouping is cosmetic, never a
+            // wrong merge.
+            services: [serviceOf(els, r.source), serviceOf(els, r.target)],
+            start: r.start,
+            end: r.end,
+        });
+    }
+    return stmts.sort((a, b) => a.start - b.start);
+}
+/**
+ * The trailing walks move in PLACEMENT UNITS, never single statements. A unit
+ * is a service neighborhood: a contiguous run of top-level elements resolving
+ * to one service, or a contiguous cluster of relationships grown around the
+ * statements touching one — keyed by its LEADING statement's id/key. Anchored
+ * inserts extend a neighborhood without changing its head, so the insertion
+ * sort the trailing region maintains is over neighborhood heads, which
+ * archive order cannot reshuffle. Comparing per statement instead let an
+ * anchored insert legally sit a LOWER id/key after a higher one (its anchor
+ * decides where it lives, not its own sort key), and a later trailing walk
+ * then stopped at different statements depending on which archive had run
+ * first — order-DEPENDENT bytes for features touching disjoint services, the
+ * exact regime the scheme guarantees.
+ */
+export function elementSpot(region, id, service) {
+    const { text, stmts, close } = region;
+    let anchor;
+    for (const s of stmts) {
+        if (s.kind === "element" && s.services.includes(service))
+            anchor = s;
+    }
+    if (anchor !== undefined)
+        return spotAfter(text, close, anchor.end);
+    let i = stmts.length - 1;
+    let before;
+    while (i >= 0 && stmts[i].kind === "rel") {
+        before = stmts[i];
+        i -= 1;
+    }
+    while (i >= 0 && stmts[i].kind === "element") {
+        // The same-service run ending here is one unit: skip it whole or stop
+        // before it whole — an anchored member may carry any id, the run's
+        // LEADING id is its sort key.
+        let j = i;
+        while (j > 0 && stmts[j - 1].kind === "element" && stmts[j - 1].services[0] === stmts[i].services[0])
+            j -= 1;
+        if (!(stmts[j].id > id))
+            break;
+        before = stmts[j];
+        i = j - 1;
+    }
+    return before !== undefined ? beforeSpot(text, before) : closeSpot(text, close);
+}
+/**
+ * Each top-level statement's cluster, as the index of the cluster's leading
+ * statement. A relationship whose SOURCE's service some earlier relationship
+ * in the same contiguous stretch already touches is an anchored join — it
+ * belongs to that neighborhood wherever its own key would sort. One whose
+ * source's service nothing before it touches opens a new cluster; sharing
+ * only a TARGET does not join (every trailing edge into a busy hub would
+ * otherwise dissolve into one giant cluster, and the trailing sort with it).
+ * Recomputed from bytes alone, so the next archive sees the same units this
+ * one placed.
+ */
+function relClusterHeads(stmts) {
+    const heads = stmts.map((_, i) => i);
+    let head = -1;
+    let services = null;
+    for (let i = 0; i < stmts.length; i += 1) {
+        const s = stmts[i];
+        if (s.kind !== "rel") {
+            head = -1;
+            services = null;
+            continue;
+        }
+        if (services !== null && services.has(s.services[0])) {
+            for (const svc of s.services)
+                services.add(svc);
+        }
+        else {
+            head = i;
+            services = new Set(s.services);
+        }
+        heads[i] = head;
+    }
+    return heads;
+}
+export function relSpot(region, sourceService, key) {
+    const { text, stmts, close } = region;
+    const heads = relClusterHeads(stmts);
+    let anchorAt = -1;
+    for (let i = 0; i < stmts.length; i += 1) {
+        const s = stmts[i];
+        if (s.kind === "rel" && s.services.includes(sourceService))
+            anchorAt = i;
+    }
+    if (anchorAt !== -1) {
+        // Past the anchor, order among the cluster's OWN members is by key — two
+        // edges anchored to the same statement must order by key, not by which
+        // archived first — but the walk never leaves the cluster: the next
+        // cluster is another neighborhood's, and stepping over it would depend
+        // on which archive put it there.
+        let last = stmts[anchorAt];
+        for (let j = anchorAt + 1; j < stmts.length; j += 1) {
+            const s = stmts[j];
+            if (s.kind !== "rel" || heads[j] !== heads[anchorAt] || s.key >= key)
+                break;
+            last = s;
+        }
+        return spotAfter(text, close, last.end);
+    }
+    let i = stmts.length - 1;
+    let before;
+    while (i >= 0 && stmts[i].kind === "rel") {
+        const j = heads[i];
+        if (!(stmts[j].key > key))
+            break;
+        before = stmts[j];
+        i = j - 1;
+    }
+    return before !== undefined ? beforeSpot(text, before) : closeSpot(text, close);
+}
+/**
+ * Insertion before an existing statement: at the start of its line when only
+ * whitespace precedes it there, at the statement itself — bare, displacing it
+ * onto a fresh line — when other text shares the line (a statement written on
+ * the `model {` line, say). The unguarded line start spliced the block BEFORE
+ * the model keyword, and the parse net refused a perfectly legal landscape.
+ */
+function beforeSpot(text, before) {
+    const ls = lineStartAt(text, before.start);
+    if (/^[ \t]*$/.test(text.slice(ls, before.start)))
+        return { at: ls, bare: false };
+    return { at: before.start, bare: true };
+}
+/** The line following the statement that ends at `end` — clamped to the closing brace's own spot. */
+function spotAfter(text, close, end) {
+    const nl = text.indexOf("\n", end);
+    const at = nl === -1 ? text.length : nl + 1;
+    return at > close ? closeSpot(text, close) : { at, bare: false };
+}
+/** The last resort: directly before the model's closing brace. */
+function closeSpot(text, close) {
+    const ls = lineStartAt(text, close);
+    if (/^[ \t]*$/.test(text.slice(ls, close)))
+        return { at: ls, bare: false };
+    return { at: close, bare: true };
+}
+function lineStartAt(text, at) {
+    return text.lastIndexOf("\n", at - 1) + 1;
+}
+/**
+ * Where a child block enters an existing living parent: before the closing
+ * brace of the parent's body, on its own line at the parent's inner indent —
+ * and a parent that never had a body gains one around the child.
+ */
+export function nestedInsert(text, parent, block) {
+    if (parent.bodyOpen === -1) {
+        return { at: parent.end, insert: ` {\n${block}\n${parent.indent}}` };
+    }
+    const lineStart = text.lastIndexOf("\n", parent.bodyClose - 1) + 1;
+    if (/^[ \t]*$/.test(text.slice(lineStart, parent.bodyClose))) {
+        return { at: lineStart, insert: `${block}\n` };
+    }
+    // `{ ... }` on one line — break the brace onto its own line to make room.
+    return { at: parent.bodyClose, insert: `\n${block}\n${parent.indent}` };
+}
+//# sourceMappingURL=placement.js.map

package/dist/core/c4/splice/placement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../../../../src/core/c4/splice/placement.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Elem } from \"../likec4.js\";\nimport { elementService, serviceOf } from \"../resolve/service.js\";\nimport type { ScannedElement, ScannedModel } from \"../source-scan.js\";\nimport { relSortKey } from \"./identity/edges.js\";\n\n/* ------------------------------------------------------------------ */\n/* Landscape placement — where a top-level addition lands               */\n/* ------------------------------------------------------------------ */\n\n/**\n * The placement scheme, in full. It never moves an authored byte — placement\n * only chooses where NEW spliced blocks go — and it is deterministic in a\n * stronger sense: archiving feature A then feature B (touching different\n * services) yields the SAME final bytes as B then A, which is what lets two\n * concurrent archive PRs merge in git instead of colliding on one shared\n * append point.\n *\n *  - An ELEMENT whose service already has top-level elements in the model\n *    (the elementService join — binding first, title as the fallback) lands\n *    immediately after the last of them: it joins its service's neighborhood.\n *    Two features touching the SAME service therefore land adjacently, and\n *    their concurrent PRs still conflict — expected, and documented\n *    (SCHEMA.md sends that conflict to the PR flow).\n *  - An element opening a NEW service lands in the trailing region before the\n *    model's closing brace: skip the trailing relationship run, then walk left\n *    per same-service RUN, past every run whose leading id is\n *    lexicographically greater — an insertion sort of neighborhood heads\n *    against whatever is already there, which is what makes the region's\n *    final order independent of archive order (see the note on elementSpot:\n *    per-statement comparison was order-dependent).\n *  - A RELATIONSHIP lands after the last top-level relationship touching its\n *    SOURCE's service (either endpoint counts), then past the anchor's own\n *    CLUSTER members with a smaller sort key — two edges anchored to the same\n *    statement must order by key, not by which archived first. With no such\n *    neighborhood it falls to the trailing region, cluster-head-key-sorted\n *    the same insertion-sort way, after the trailing elements.\n *\n * LikeC4 reference resolution is not order-dependent, so a relationship\n * placed before an element it names still parses; the in-memory parse net in\n * landscape-merge.ts's planLandscapeMerge stays as the backstop regardless.\n */\nexport interface Spot {\n  /** Offset into the living text: a line start, or a point inside a shared line. */\n  at: number;\n  /** True when `at` shares its line with other text (the closing brace, or a displaced statement) — the block must bring its own newlines. */\n  bare: boolean;\n}\n\n/** A top-level statement of the living model, with everything placement asks of it. */\nexport interface TopStmt {\n  kind: \"element\" | \"rel\";\n  /** Element: its id. */\n  id: string;\n  /** Relationship: its placement sort key (relSortKey). */\n  key: string;\n  /** The service(s) this statement resolves to — one for an element, both endpoints for a rel. */\n  services: string[];\n  start: number;\n  end: number;\n}\n\n/**\n * The living model as placement reads it: the text being spliced into, its\n * top-level statement layout, and the model block's closing brace. One value\n * because every spot is computed against all three at the same instant — a\n * layout paired with text a splice has since moved would place against a\n * document that no longer exists (see `modelRegion` in landscape-merge.ts's\n * planLandscapeMerge).\n */\nexport interface ModelRegion {\n  text: string;\n  stmts: TopStmt[];\n  close: number;\n}\n\n/** The model's top-level statements in document order, joined to the parsed elements for services. */\nexport function topStatements(scan: ScannedModel, els: Elem[]): TopStmt[] {\n  const topEls = scan.elements.filter((e) => !e.id.includes(\".\"));\n  const bound = new Map(els.map((e) => [e.id, elementService(e)]));\n  const stmts: TopStmt[] = topEls.map((e) => ({\n    kind: \"element\" as const,\n    id: e.id,\n    key: \"\",\n    services: [bound.get(e.id) ?? e.id],\n    start: e.start,\n    end: e.end,\n  }));\n  for (const r of scan.rels) {\n    // A rel declared inside an element's body is not a top-level statement —\n    // anchoring after it would splice into the parent's block.\n    if (topEls.some((e) => r.start > e.start && r.start < e.end)) continue;\n    stmts.push({\n      kind: \"rel\",\n      id: \"\",\n      key: relSortKey(els, r),\n      // Deliberately no `known` fleet set here: this resolution only decides\n      // WHERE in the file a statement anchors, both sides of every comparison\n      // resolve through the same call, and the merged document is re-parsed\n      // before anything is written — a wrong grouping is cosmetic, never a\n      // wrong merge.\n      services: [serviceOf(els, r.source), serviceOf(els, r.target)],\n      start: r.start,\n      end: r.end,\n    });\n  }\n  return stmts.sort((a, b) => a.start - b.start);\n}\n\n\n/**\n * The trailing walks move in PLACEMENT UNITS, never single statements. A unit\n * is a service neighborhood: a contiguous run of top-level elements resolving\n * to one service, or a contiguous cluster of relationships grown around the\n * statements touching one — keyed by its LEADING statement's id/key. Anchored\n * inserts extend a neighborhood without changing its head, so the insertion\n * sort the trailing region maintains is over neighborhood heads, which\n * archive order cannot reshuffle. Comparing per statement instead let an\n * anchored insert legally sit a LOWER id/key after a higher one (its anchor\n * decides where it lives, not its own sort key), and a later trailing walk\n * then stopped at different statements depending on which archive had run\n * first — order-DEPENDENT bytes for features touching disjoint services, the\n * exact regime the scheme guarantees.\n */\nexport function elementSpot(region: ModelRegion, id: string, service: string): Spot {\n  const { text, stmts, close } = region;\n  let anchor: TopStmt | undefined;\n  for (const s of stmts) {\n    if (s.kind === \"element\" && s.services.includes(service)) anchor = s;\n  }\n  if (anchor !== undefined) return spotAfter(text, close, anchor.end);\n  let i = stmts.length - 1;\n  let before: TopStmt | undefined;\n  while (i >= 0 && stmts[i]!.kind === \"rel\") {\n    before = stmts[i];\n    i -= 1;\n  }\n  while (i >= 0 && stmts[i]!.kind === \"element\") {\n    // The same-service run ending here is one unit: skip it whole or stop\n    // before it whole — an anchored member may carry any id, the run's\n    // LEADING id is its sort key.\n    let j = i;\n    while (j > 0 && stmts[j - 1]!.kind === \"element\" && stmts[j - 1]!.services[0] === stmts[i]!.services[0]) j -= 1;\n    if (!(stmts[j]!.id > id)) break;\n    before = stmts[j];\n    i = j - 1;\n  }\n  return before !== undefined ? beforeSpot(text, before) : closeSpot(text, close);\n}\n\n/**\n * Each top-level statement's cluster, as the index of the cluster's leading\n * statement. A relationship whose SOURCE's service some earlier relationship\n * in the same contiguous stretch already touches is an anchored join — it\n * belongs to that neighborhood wherever its own key would sort. One whose\n * source's service nothing before it touches opens a new cluster; sharing\n * only a TARGET does not join (every trailing edge into a busy hub would\n * otherwise dissolve into one giant cluster, and the trailing sort with it).\n * Recomputed from bytes alone, so the next archive sees the same units this\n * one placed.\n */\nfunction relClusterHeads(stmts: TopStmt[]): number[] {\n  const heads = stmts.map((_, i) => i);\n  let head = -1;\n  let services: Set<string> | null = null;\n  for (let i = 0; i < stmts.length; i += 1) {\n    const s = stmts[i]!;\n    if (s.kind !== \"rel\") {\n      head = -1;\n      services = null;\n      continue;\n    }\n    if (services !== null && services.has(s.services[0]!)) {\n      for (const svc of s.services) services.add(svc);\n    } else {\n      head = i;\n      services = new Set(s.services);\n    }\n    heads[i] = head;\n  }\n  return heads;\n}\n\nexport function relSpot(region: ModelRegion, sourceService: string, key: string): Spot {\n  const { text, stmts, close } = region;\n  const heads = relClusterHeads(stmts);\n  let anchorAt = -1;\n  for (let i = 0; i < stmts.length; i += 1) {\n    const s = stmts[i]!;\n    if (s.kind === \"rel\" && s.services.includes(sourceService)) anchorAt = i;\n  }\n  if (anchorAt !== -1) {\n    // Past the anchor, order among the cluster's OWN members is by key — two\n    // edges anchored to the same statement must order by key, not by which\n    // archived first — but the walk never leaves the cluster: the next\n    // cluster is another neighborhood's, and stepping over it would depend\n    // on which archive put it there.\n    let last = stmts[anchorAt]!;\n    for (let j = anchorAt + 1; j < stmts.length; j += 1) {\n      const s = stmts[j]!;\n      if (s.kind !== \"rel\" || heads[j] !== heads[anchorAt] || s.key >= key) break;\n      last = s;\n    }\n    return spotAfter(text, close, last.end);\n  }\n  let i = stmts.length - 1;\n  let before: TopStmt | undefined;\n  while (i >= 0 && stmts[i]!.kind === \"rel\") {\n    const j = heads[i]!;\n    if (!(stmts[j]!.key > key)) break;\n    before = stmts[j];\n    i = j - 1;\n  }\n  return before !== undefined ? beforeSpot(text, before) : closeSpot(text, close);\n}\n\n/**\n * Insertion before an existing statement: at the start of its line when only\n * whitespace precedes it there, at the statement itself — bare, displacing it\n * onto a fresh line — when other text shares the line (a statement written on\n * the `model {` line, say). The unguarded line start spliced the block BEFORE\n * the model keyword, and the parse net refused a perfectly legal landscape.\n */\nfunction beforeSpot(text: string, before: TopStmt): Spot {\n  const ls = lineStartAt(text, before.start);\n  if (/^[ \\t]*$/.test(text.slice(ls, before.start))) return { at: ls, bare: false };\n  return { at: before.start, bare: true };\n}\n\n/** The line following the statement that ends at `end` — clamped to the closing brace's own spot. */\nfunction spotAfter(text: string, close: number, end: number): Spot {\n  const nl = text.indexOf(\"\\n\", end);\n  const at = nl === -1 ? text.length : nl + 1;\n  return at > close ? closeSpot(text, close) : { at, bare: false };\n}\n\n/** The last resort: directly before the model's closing brace. */\nfunction closeSpot(text: string, close: number): Spot {\n  const ls = lineStartAt(text, close);\n  if (/^[ \\t]*$/.test(text.slice(ls, close))) return { at: ls, bare: false };\n  return { at: close, bare: true };\n}\n\nfunction lineStartAt(text: string, at: number): number {\n  return text.lastIndexOf(\"\\n\", at - 1) + 1;\n}\n\n/**\n * Where a child block enters an existing living parent: before the closing\n * brace of the parent's body, on its own line at the parent's inner indent —\n * and a parent that never had a body gains one around the child.\n */\nexport function nestedInsert(text: string, parent: ScannedElement, block: string): { at: number; insert: string } {\n  if (parent.bodyOpen === -1) {\n    return { at: parent.end, insert: ` {\\n${block}\\n${parent.indent}}` };\n  }\n  const lineStart = text.lastIndexOf(\"\\n\", parent.bodyClose - 1) + 1;\n  if (/^[ \\t]*$/.test(text.slice(lineStart, parent.bodyClose))) {\n    return { at: lineStart, insert: `${block}\\n` };\n  }\n  // `{ ... }` on one line — break the brace onto its own line to make room.\n  return { at: parent.bodyClose, insert: `\\n${block}\\n${parent.indent}` };\n}\n"]}

package/dist/core/c4/workspace.js

@@ -0,0 +1,172 @@
+/**
+ * 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 flattens each clean project through the same
+ * `flattenModel` 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 { flattenModel } from "./likec4.js";
+import { readDynamicViews } from "./parsed/dynamic-views.js";
+import { readViewIds } from "./parsed/view-ids.js";
+import { readSpecification } from "./parsed/specification.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.
+ */
+function groupErrors(likec4, staged) {
+    const pathOf = new Map(staged.map((doc) => [doc.project, doc.path]));
+    const grouped = new Map();
+    for (const err of 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 {
+                    const model = (await likec4.parsedModel(project));
+                    // The specification travels with the batch loader too, 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, {
+                        errors,
+                        specification: readSpecification(model.specification),
+                        views: readDynamicViews(model),
+                        viewIds: readViewIds(model),
+                        ...flattenModel(model),
+                    });
+                }
+            }
+        }
+        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 flattens each clean project through the same\n * `flattenModel` 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 { flattenModel, type LikeC4Error, type LoadedDoc, type ReadableModel } from \"./likec4.js\";\nimport { readDynamicViews } from \"./parsed/dynamic-views.js\";\nimport { readViewIds } from \"./parsed/view-ids.js\";\nimport { readSpecification } from \"./parsed/specification.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 */\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 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          const model = (await likec4.parsedModel(project)) as ReadableModel;\n          // The specification travels with the batch loader too, and must: this\n          // is the loader `validate --all` reads the landscape through, so a\n          // kind-tag check wired only into `loadSource` would be a check the\n          // fleet gate — the one run it exists for — never actually ran.\n          out.set(path, {\n            errors,\n            specification: readSpecification(model.specification),\n            views: readDynamicViews(model),\n            viewIds: readViewIds(model),\n            ...flattenModel(model),\n          });\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"]}