@ybotok/loam 0.2.0-alpha.6 → 0.2.0-alpha.9

package/dist/core/c4/locate/unlocated.js

@@ -0,0 +1,150 @@
+/**
+ * What the parsed model declares and the splice map cannot locate — named the
+ * way an author can act on it.
+ *
+ * The archive splices the landscape by its text scan (`../source-scan.ts`) and
+ * refuses rather than splice around a declaration the scan cannot see. That
+ * refusal used to guess its cause: "most often two declarations sharing one
+ * line", whatever the map held. A fleet on 0.2.0-alpha.7 read it over a
+ * standalone declaration on a line of its own — the scan was blind to a second
+ * `model { }` block — and was asked to rewrite a valid map to satisfy a message
+ * that described something else. So the cause is no longer guessed where it can
+ * be read: LikeC4's own locator says on which line the declaration is, the
+ * line itself says whether anything but the declaration's own lead (`Lead`)
+ * precedes it there, and the scan says what it read in that place instead.
+ *
+ * A second parse of the landscape, and it is paid only on the refusal path —
+ * the merge decides THAT something is unlocated from the parse it already has,
+ * and asks this module only for the words.
+ */
+import { LikeC4 } from "likec4";
+import { maskSource } from "../source-mask.js";
+/**
+ * The first declaration of `text` that `scan` does not locate — elements in
+ * the parser's order, then relationships in document order; null when every
+ * one is located.
+ *
+ * An element is located when the scan holds its id. A relationship has no id
+ * the text can carry, so it is located by POSITION: LikeC4 places each edge at
+ * its arrow, and each scanned statement may stand for one edge — the second
+ * arrow inside one scanned span is the edge the scan swallowed.
+ */
+export async function firstUnlocated(text, scan) {
+    const likec4 = await LikeC4.fromSource(text, { logger: false });
+    try {
+        const model = await likec4.parsedModel();
+        const where = placer(text, scan);
+        const scanned = new Set(scan.elements.map((e) => e.id));
+        for (const e of model.elements()) {
+            if (scanned.has(e.id))
+                continue;
+            return { kind: "element", name: e.id, ...where.place(likec4.languageServices.locate({ element: e.id })?.range.start, { kind: e.kind }) };
+        }
+        const edges = [...model.relationships()].map((r) => {
+            const start = likec4.languageServices.locate({ relation: r.id })?.range.start;
+            return { name: `${r.source.id} -> ${r.target.id}`, start, offset: start === undefined ? -1 : where.offset(start) };
+        });
+        const claimed = new Set();
+        for (const edge of edges.sort((a, b) => a.offset - b.offset)) {
+            if (edge.offset === -1)
+                continue;
+            const span = scan.rels.findIndex((s) => edge.offset >= s.start && edge.offset < s.end);
+            if (span !== -1 && !claimed.has(span)) {
+                claimed.add(span);
+                continue;
+            }
+            return { kind: "relationship", name: edge.name, ...where.place(edge.start, "edge") };
+        }
+        // Every located edge has a statement of its own: an unlocated one, if the
+        // count says there is one, is among those the locator could not place.
+        const lost = edges.find((edge) => edge.offset === -1);
+        return lost === undefined ? null : { kind: "relationship", name: lost.name };
+    }
+    finally {
+        await likec4.dispose();
+    }
+}
+/** A whole token — not the tail of a longer id — directly before the anchor, the kind written there. */
+const ELEMENT_LEAD = /(?<![\w.-])([A-Za-z_][\w-]*)\s*$/;
+/** An optional source reference and an optional `-[`, directly before the anchor; always matches, possibly empty. */
+const EDGE_LEAD = /(?<![\w.-])(?:[A-Za-z_][\w.-]*\s*)?(?:-\[\s*)?$/;
+/**
+ * Where the declaration anchored at `at` starts, in the masked `code` of the
+ * line starting at `from`: before its lead when the code there ends in one,
+ * else `at`. Masked, a literal or a URI is blank, so the word before one reads
+ * as an edge's source here exactly as `relationHead` reads it in the scan
+ * (`link https://… -> zulu` is `link -> zulu` to both). Such a line is a
+ * scanned edge of its own, so its edge is unlocated only when an earlier
+ * statement's span ran on over it — and then the line-break explanation is
+ * the one to give, which is what dropping that word leads to.
+ */
+function leadStart(code, span, lead) {
+    const before = code.slice(span.from, span.at);
+    const m = lead === "edge" ? EDGE_LEAD.exec(before) : ELEMENT_LEAD.exec(before);
+    return m === null || (lead !== "edge" && m[1] !== lead.kind) ? span.at : span.from + m.index;
+}
+/**
+ * Reads a position against the text and the scan. Lines are split the way LSP
+ * counts them — `\r\n`, `\r` or `\n` — because that is the count LikeC4's
+ * positions are in. A bare carriage return used to be the one break the scan
+ * did not make, and so the cause the "read it as part of" words were written
+ * for; `statementHead` breaks there too now, and the words stay for whatever
+ * run-on the scan has next.
+ */
+function placer(text, scan) {
+    const starts = [0];
+    for (const m of text.matchAll(/\r\n|\r|\n/g))
+        starts.push(m.index + m[0].length);
+    const lineOf = (offset) => starts.findLastIndex((s) => s <= offset) + 1;
+    const { code } = maskSource(text);
+    const offset = (start) => (starts[start.line] ?? text.length) + start.character;
+    const heads = [
+        ...scan.elements
+            .filter((e) => e.extend !== true)
+            .map((e) => ({ name: `'${e.id}'`, start: e.start, end: e.bodyOpen === -1 ? e.end : e.bodyOpen })),
+        ...scan.rels.map((r) => ({ name: `the edge '${r.source} -> ${r.target}'`, start: r.start, end: r.end })),
+    ];
+    const place = (start, lead) => {
+        if (start === undefined)
+            return {};
+        const at = offset(start);
+        const from = starts[start.line] ?? at;
+        // Measured from where the declaration starts, not from the anchor: its own
+        // kind keyword or source is no other statement (`Lead`).
+        const before = code.slice(from, leadStart(code, { from, at }, lead));
+        // Innermost first: a nested declaration's span lies inside its parent's.
+        const cover = heads.filter((h) => at >= h.start && at < h.end).sort((a, b) => b.start - a.start)[0];
+        return {
+            line: start.line + 1,
+            ...(/\S/.test(before) ? { sharesLine: true } : {}),
+            ...(cover === undefined ? {} : { readAs: { name: cover.name, line: lineOf(cover.start) } }),
+        };
+    };
+    return { place, offset };
+}
+/**
+ * The refusal's words for one unlocated declaration of `file`. A shared line
+ * is named only when the line shows one, and the statement the scan read
+ * instead only when it read one: a guess at the cause is the message this
+ * replaced.
+ */
+export function unlocatedReason(file, gap) {
+    const remedy = "nothing was written; rewrite it on a line of its own as `name = kind 'title' {` (an edge as `a -> b 'title'`) and re-run — " +
+        "and report the original shape: LikeC4 parses it, so it is a form the splice map should read";
+    if (gap === null)
+        return `${file} declares more than placement can locate, and LikeC4's locator could not say where — ${remedy}`;
+    const what = `${file} declares ${gap.kind === "element" ? `'${gap.name}'` : `the relationship '${gap.name}'`}`;
+    const where = gap.line === undefined ? "" : ` at line ${gap.line}`;
+    const read = gap.readAs;
+    if (gap.sharesLine === true) {
+        const other = read === undefined ? "the statement before it" : read.name;
+        return (`${what}${where} in a form placement cannot locate: it shares that line with ${other}, and the splice map reads ` +
+            `one statement per line where LikeC4 accepts two — give each its own line, then re-run`);
+    }
+    if (read !== undefined) {
+        return (`${what}${where} in a form placement cannot locate: the splice map read it as part of ${read.name}, which starts at ` +
+            `line ${read.line} — it ran that statement on past a line break LikeC4 makes — ${remedy}`);
+    }
+    return `${what}${where} in a form placement cannot locate, and the splice map read no statement there — ${remedy}`;
+}
+//# sourceMappingURL=unlocated.js.map

package/dist/core/c4/locate/unlocated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unlocated.js","sourceRoot":"","sources":["../../../../src/core/c4/locate/unlocated.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What the parsed model declares and the splice map cannot locate — named the\n * way an author can act on it.\n *\n * The archive splices the landscape by its text scan (`../source-scan.ts`) and\n * refuses rather than splice around a declaration the scan cannot see. That\n * refusal used to guess its cause: \"most often two declarations sharing one\n * line\", whatever the map held. A fleet on 0.2.0-alpha.7 read it over a\n * standalone declaration on a line of its own — the scan was blind to a second\n * `model { }` block — and was asked to rewrite a valid map to satisfy a message\n * that described something else. So the cause is no longer guessed where it can\n * be read: LikeC4's own locator says on which line the declaration is, the\n * line itself says whether anything but the declaration's own lead (`Lead`)\n * precedes it there, and the scan says what it read in that place instead.\n *\n * A second parse of the landscape, and it is paid only on the refusal path —\n * the merge decides THAT something is unlocated from the parse it already has,\n * and asks this module only for the words.\n */\nimport { LikeC4 } from \"likec4\";\nimport { maskSource } from \"../source-mask.js\";\nimport type { ScannedModel } from \"../source-scan.js\";\n\n/** One declaration the parser has and the scan cannot place. */\nexport interface Unlocated {\n  kind: \"element\" | \"relationship\";\n  /** The element's id, or the relationship as `source -> target`, as the parser resolved them. */\n  name: string;\n  /** 1-based line LikeC4's locator puts the declaration on; absent when it has no answer. */\n  line?: number;\n  /**\n   * Code other than the declaration's own lead precedes it on its own line —\n   * the shared line is then a FACT, not a guess.\n   */\n  sharesLine?: true;\n  /** The scanned statement that covers where the declaration sits, and the line that statement starts on. */\n  readAs?: { name: string; line: number };\n}\n\n/**\n * The first declaration of `text` that `scan` does not locate — elements in\n * the parser's order, then relationships in document order; null when every\n * one is located.\n *\n * An element is located when the scan holds its id. A relationship has no id\n * the text can carry, so it is located by POSITION: LikeC4 places each edge at\n * its arrow, and each scanned statement may stand for one edge — the second\n * arrow inside one scanned span is the edge the scan swallowed.\n */\nexport async function firstUnlocated(text: string, scan: ScannedModel): Promise<Unlocated | null> {\n  const likec4 = await LikeC4.fromSource(text, { logger: false });\n  try {\n    const model = await likec4.parsedModel();\n    const where = placer(text, scan);\n    const scanned = new Set(scan.elements.map((e) => e.id));\n    for (const e of model.elements()) {\n      if (scanned.has(e.id)) continue;\n      return { kind: \"element\", name: e.id, ...where.place(likec4.languageServices.locate({ element: e.id })?.range.start, { kind: e.kind }) };\n    }\n    const edges = [...model.relationships()].map((r) => {\n      const start = likec4.languageServices.locate({ relation: r.id })?.range.start;\n      return { name: `${r.source.id} -> ${r.target.id}`, start, offset: start === undefined ? -1 : where.offset(start) };\n    });\n    const claimed = new Set<number>();\n    for (const edge of edges.sort((a, b) => a.offset - b.offset)) {\n      if (edge.offset === -1) continue;\n      const span = scan.rels.findIndex((s) => edge.offset >= s.start && edge.offset < s.end);\n      if (span !== -1 && !claimed.has(span)) {\n        claimed.add(span);\n        continue;\n      }\n      return { kind: \"relationship\", name: edge.name, ...where.place(edge.start, \"edge\") };\n    }\n    // Every located edge has a statement of its own: an unlocated one, if the\n    // count says there is one, is among those the locator could not place.\n    const lost = edges.find((edge) => edge.offset === -1);\n    return lost === undefined ? null : { kind: \"relationship\", name: lost.name };\n  } finally {\n    await likec4.dispose();\n  }\n}\n\n/** An LSP position: a 0-based line and a character within it. */\ninterface Position {\n  line: number;\n  character: number;\n}\n\n/**\n * The part of a declaration LikeC4's locator leaves BEFORE its anchor. It\n * points an element at its NAME and a relationship at its ARROW — inside\n * `-[…]->`, at the kind — so `container api 'API'` has its kind keyword in\n * front of the anchor and `zulu -> apple` its source. Read as \"code before\n * it\", every unlocated edge and every `kind name` element shared its line with\n * itself, and the line-break explanation `unlocatedReason` holds below the\n * shared-line one was never reached. An element's lead is a token equal to\n * its parsed kind; an edge's is its source reference (`it`, a dotted path or\n * none) and the `-[` opening a bracketed kind.\n */\ntype Lead = { kind: string } | \"edge\";\n\n/** A whole token — not the tail of a longer id — directly before the anchor, the kind written there. */\nconst ELEMENT_LEAD = /(?<![\\w.-])([A-Za-z_][\\w-]*)\\s*$/;\n/** An optional source reference and an optional `-[`, directly before the anchor; always matches, possibly empty. */\nconst EDGE_LEAD = /(?<![\\w.-])(?:[A-Za-z_][\\w.-]*\\s*)?(?:-\\[\\s*)?$/;\n\n/**\n * Where the declaration anchored at `at` starts, in the masked `code` of the\n * line starting at `from`: before its lead when the code there ends in one,\n * else `at`. Masked, a literal or a URI is blank, so the word before one reads\n * as an edge's source here exactly as `relationHead` reads it in the scan\n * (`link https://… -> zulu` is `link -> zulu` to both). Such a line is a\n * scanned edge of its own, so its edge is unlocated only when an earlier\n * statement's span ran on over it — and then the line-break explanation is\n * the one to give, which is what dropping that word leads to.\n */\nfunction leadStart(code: string, span: { from: number; at: number }, lead: Lead): number {\n  const before = code.slice(span.from, span.at);\n  const m = lead === \"edge\" ? EDGE_LEAD.exec(before) : ELEMENT_LEAD.exec(before);\n  return m === null || (lead !== \"edge\" && m[1] !== lead.kind) ? span.at : span.from + m.index;\n}\n\n/** Everything a position tells about a declaration, and the offset arithmetic that is built on. */\ninterface Placer {\n  place: (start: Position | undefined, lead: Lead) => Pick<Unlocated, \"line\" | \"sharesLine\" | \"readAs\">;\n  offset: (start: Position) => number;\n}\n\n/**\n * Reads a position against the text and the scan. Lines are split the way LSP\n * counts them — `\\r\\n`, `\\r` or `\\n` — because that is the count LikeC4's\n * positions are in. A bare carriage return used to be the one break the scan\n * did not make, and so the cause the \"read it as part of\" words were written\n * for; `statementHead` breaks there too now, and the words stay for whatever\n * run-on the scan has next.\n */\nfunction placer(text: string, scan: ScannedModel): Placer {\n  const starts = [0];\n  for (const m of text.matchAll(/\\r\\n|\\r|\\n/g)) starts.push(m.index + m[0].length);\n  const lineOf = (offset: number): number => starts.findLastIndex((s) => s <= offset) + 1;\n  const { code } = maskSource(text);\n  const offset = (start: Position): number => (starts[start.line] ?? text.length) + start.character;\n  const heads = [\n    ...scan.elements\n      .filter((e) => e.extend !== true)\n      .map((e) => ({ name: `'${e.id}'`, start: e.start, end: e.bodyOpen === -1 ? e.end : e.bodyOpen })),\n    ...scan.rels.map((r) => ({ name: `the edge '${r.source} -> ${r.target}'`, start: r.start, end: r.end })),\n  ];\n  const place = (start: Position | undefined, lead: Lead): Pick<Unlocated, \"line\" | \"sharesLine\" | \"readAs\"> => {\n    if (start === undefined) return {};\n    const at = offset(start);\n    const from = starts[start.line] ?? at;\n    // Measured from where the declaration starts, not from the anchor: its own\n    // kind keyword or source is no other statement (`Lead`).\n    const before = code.slice(from, leadStart(code, { from, at }, lead));\n    // Innermost first: a nested declaration's span lies inside its parent's.\n    const cover = heads.filter((h) => at >= h.start && at < h.end).sort((a, b) => b.start - a.start)[0];\n    return {\n      line: start.line + 1,\n      ...(/\\S/.test(before) ? { sharesLine: true as const } : {}),\n      ...(cover === undefined ? {} : { readAs: { name: cover.name, line: lineOf(cover.start) } }),\n    };\n  };\n  return { place, offset };\n}\n\n/**\n * The refusal's words for one unlocated declaration of `file`. A shared line\n * is named only when the line shows one, and the statement the scan read\n * instead only when it read one: a guess at the cause is the message this\n * replaced.\n */\nexport function unlocatedReason(file: string, gap: Unlocated | null): string {\n  const remedy =\n    \"nothing was written; rewrite it on a line of its own as `name = kind 'title' {` (an edge as `a -> b 'title'`) and re-run — \" +\n    \"and report the original shape: LikeC4 parses it, so it is a form the splice map should read\";\n  if (gap === null) return `${file} declares more than placement can locate, and LikeC4's locator could not say where — ${remedy}`;\n  const what = `${file} declares ${gap.kind === \"element\" ? `'${gap.name}'` : `the relationship '${gap.name}'`}`;\n  const where = gap.line === undefined ? \"\" : ` at line ${gap.line}`;\n  const read = gap.readAs;\n  if (gap.sharesLine === true) {\n    const other = read === undefined ? \"the statement before it\" : read.name;\n    return (\n      `${what}${where} in a form placement cannot locate: it shares that line with ${other}, and the splice map reads ` +\n      `one statement per line where LikeC4 accepts two — give each its own line, then re-run`\n    );\n  }\n  if (read !== undefined) {\n    return (\n      `${what}${where} in a form placement cannot locate: the splice map read it as part of ${read.name}, which starts at ` +\n      `line ${read.line} — it ran that statement on past a line break LikeC4 makes — ${remedy}`\n    );\n  }\n  return `${what}${where} in a form placement cannot locate, and the splice map read no statement there — ${remedy}`;\n}\n"]}

package/dist/core/c4/parsed/values.js

@@ -9,7 +9,9 @@
  * (`../likec4.ts`) that calls them, because the adapter is at its line limit and
  * because "decode a value LikeC4 left untyped" is a subject of its own: the
  * specification reader beside this file is the same subject on a different
- * corner of the same object.
+ * corner of the same object. The ORDER relationships come back in is one more
+ * such corner — LikeC4 promises none, and the one it happens to give changes
+ * between runs — so `compareRels` lives here too.
  */
 /**
  * Read one string key out of a LikeC4 `metadata { ... }` block. Four keys carry
@@ -54,4 +56,55 @@ export function descText(d) {
     }
     return undefined;
 }
+/**
+ * The ONE order every loader hands relationships back in: by source, then
+ * target, title, `op`, `publishes`, `consumes` and tags — plain code-unit
+ * compares, so the order is a function of the documents' text alone and never
+ * of the locale, the machine or the run. Two edges equal on every key are equal
+ * in every field `Rel` (`../likec4.ts`) carries, so which of them comes first
+ * cannot be seen. `flattenModel` there sorts with it; it lives here, beside the
+ * other reads of LikeC4's parse output that cannot be taken at face value,
+ * because the adapter is at its line limit.
+ *
+ * LikeC4 does not give one, for two measured reasons (1.59.2). Its parsed
+ * model indexes relations in a plain object keyed by an id HASHED FROM THE
+ * DOCUMENT'S URI — and every loader stages documents under a fresh
+ * crypto-random folder per invocation (`../workspace.ts` says why), so the ids
+ * change on every run. A JavaScript object enumerates integer-like keys
+ * numerically ahead of every other key, so whenever a hash comes out all
+ * digits (about one hash in 2,200) that edge jumps to the front of the list,
+ * on that run only. And inside a project of several documents the base order
+ * is whichever file Langium's concurrent folder walk finished reading first.
+ * The first reason is what failed a scheduled CI run on 2026-09-28:
+ * `loadProjectBatch` and `loadProject` returned one service's two edges in
+ * opposite orders on an unchanged commit — and on a fleet map of a few hundred
+ * edges it would reorder some run's findings far more often than that.
+ *
+ * Declaration order is therefore NOT what a reader gets, and nothing may read
+ * meaning into the position of an edge: what the `Rel` list promises is the
+ * same order for the same documents, which is what the text report and the
+ * `--json` envelope being diffed between runs and machines needs.
+ */
+export function compareRels(a, b) {
+    // An absent field sorts ahead of every present one, the empty string
+    // included, so "no title" and "an empty title" cannot tie. Tags are LikeC4
+    // identifiers, which cannot contain the comma that joins them.
+    const opt = (value) => (value === undefined ? "" : `=${value}`);
+    const keys = (r) => [
+        r.source,
+        r.target,
+        opt(r.title),
+        opt(r.op),
+        opt(r.publishes),
+        opt(r.consumes),
+        r.tags.join(","),
+    ];
+    const ka = keys(a);
+    const kb = keys(b);
+    for (let i = 0; i < ka.length; i++) {
+        if (ka[i] !== kb[i])
+            return ka[i] < kb[i] ? -1 : 1;
+    }
+    return 0;
+}
 //# sourceMappingURL=values.js.map

package/dist/core/c4/parsed/values.js.map

@@ -1 +1 @@
-{"version":3,"file":"values.js","sourceRoot":"","sources":["../../../../src/core/c4/parsed/values.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,OAAO,CAAC,CAAU,EAAE,GAAW;IAC7C,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAI,CAA6B,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC;QACpC,4EAA4E;QAC5E,2EAA2E;QAC3E,8EAA8E;QAC9E,4EAA4E;QAC5E,2EAA2E;QAC3E,wEAAwE;QACxE,kDAAkD;QAClD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,QAAQ,CAAC,CAAU;IACjC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,CAA4B,CAAC;QACvC,KAAK,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;YACjD,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YACjB,IAAI,OAAO,CAAC,KAAK,QAAQ;gBAAE,OAAO,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["/**\n * The corners of LikeC4's parse output that are typed `unknown`, decoded.\n *\n * LikeC4 models `metadata { ... }` values and a `description` as open shapes —\n * a value may be a string, an array, or a rich-text object, and the declared\n * type says none of that. Every one of those crossings needs a defensive read\n * that answers \"not present\" rather than throwing, and each read encodes a\n * defect somebody hit. They live together here, one module below the adapter\n * (`../likec4.ts`) that calls them, because the adapter is at its line limit and\n * because \"decode a value LikeC4 left untyped\" is a subject of its own: the\n * specification reader beside this file is the same subject on a different\n * corner of the same object.\n */\n\n/**\n * Read one string key out of a LikeC4 `metadata { ... }` block. Four keys carry\n * loam's spines: `op` on a relationship (the OpenAPI operationId it calls),\n * `publishes`/`consumes` on a relationship (the AsyncAPI message it produces or\n * receives), and `service` on an element (the services/<id> directory it stands\n * for). Every one of them is read by BOTH model readers — the parsed one\n * (`flattenModel` in `../likec4.ts`, which calls this) and the text scanner\n * `scanModel` uses for archive's splice map — because a key only one of them\n * sees is a key the merge silently drops. Elements with no metadata come back as\n * `{}`, so a missing key is indistinguishable from a missing block — both mean\n * \"not bound\".\n */\nexport function metaKey(m: unknown, key: string): string | undefined {\n  if (m && typeof m === \"object\") {\n    const v = (m as Record<string, unknown>)[key];\n    if (typeof v === \"string\") return v;\n    // A key written TWICE in one block comes back as an array, accepted with no\n    // error, and reading only the string form dropped every value — so an edge\n    // naming two operations reported as naming none, `c4.op-link-missing` telling\n    // the author the opposite of what they wrote. First wins, matching the text\n    // scanner's `keyedLiteral`: the two readers disagreeing about a binding is\n    // exactly what the paragraph above exists to prevent. Later values stay\n    // dropped — one id per key per edge is the model.\n    if (Array.isArray(v) && typeof v[0] === \"string\") return v[0];\n  }\n  return undefined;\n}\n\n/** LikeC4 descriptions can be a string or a rich-text object ({ txt } / { text } / { md }). */\nexport function descText(d: unknown): string | undefined {\n  if (typeof d === \"string\") return d;\n  if (d && typeof d === \"object\") {\n    const o = d as Record<string, unknown>;\n    for (const key of [\"txt\", \"text\", \"md\", \"value\"]) {\n      const v = o[key];\n      if (typeof v === \"string\") return v;\n    }\n  }\n  return undefined;\n}\n"]}
+{"version":3,"file":"values.js","sourceRoot":"","sources":["../../../../src/core/c4/parsed/values.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,OAAO,CAAC,CAAU,EAAE,GAAW;IAC7C,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAI,CAA6B,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC;QACpC,4EAA4E;QAC5E,2EAA2E;QAC3E,8EAA8E;QAC9E,4EAA4E;QAC5E,2EAA2E;QAC3E,wEAAwE;QACxE,kDAAkD;QAClD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,QAAQ,CAAC,CAAU;IACjC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,CAAC,GAAG,CAA4B,CAAC;QACvC,KAAK,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;YACjD,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YACjB,IAAI,OAAO,CAAC,KAAK,QAAQ;gBAAE,OAAO,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,WAAW,CAAC,CAAU,EAAE,CAAU;IAChD,qEAAqE;IACrE,2EAA2E;IAC3E,+DAA+D;IAC/D,MAAM,GAAG,GAAG,CAAC,KAAyB,EAAU,EAAE,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC;IAC5F,MAAM,IAAI,GAAG,CAAC,CAAU,EAAY,EAAE,CAAC;QACrC,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,MAAM;QACR,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;QACZ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACT,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QAChB,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;QACf,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;KACjB,CAAC;IACF,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAAE,OAAO,EAAE,CAAC,CAAC,CAAE,GAAG,EAAE,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC","sourcesContent":["/**\n * The corners of LikeC4's parse output that are typed `unknown`, decoded.\n *\n * LikeC4 models `metadata { ... }` values and a `description` as open shapes —\n * a value may be a string, an array, or a rich-text object, and the declared\n * type says none of that. Every one of those crossings needs a defensive read\n * that answers \"not present\" rather than throwing, and each read encodes a\n * defect somebody hit. They live together here, one module below the adapter\n * (`../likec4.ts`) that calls them, because the adapter is at its line limit and\n * because \"decode a value LikeC4 left untyped\" is a subject of its own: the\n * specification reader beside this file is the same subject on a different\n * corner of the same object. The ORDER relationships come back in is one more\n * such corner — LikeC4 promises none, and the one it happens to give changes\n * between runs — so `compareRels` lives here too.\n */\n\n/**\n * Read one string key out of a LikeC4 `metadata { ... }` block. Four keys carry\n * loam's spines: `op` on a relationship (the OpenAPI operationId it calls),\n * `publishes`/`consumes` on a relationship (the AsyncAPI message it produces or\n * receives), and `service` on an element (the services/<id> directory it stands\n * for). Every one of them is read by BOTH model readers — the parsed one\n * (`flattenModel` in `../likec4.ts`, which calls this) and the text scanner\n * `scanModel` uses for archive's splice map — because a key only one of them\n * sees is a key the merge silently drops. Elements with no metadata come back as\n * `{}`, so a missing key is indistinguishable from a missing block — both mean\n * \"not bound\".\n */\nexport function metaKey(m: unknown, key: string): string | undefined {\n  if (m && typeof m === \"object\") {\n    const v = (m as Record<string, unknown>)[key];\n    if (typeof v === \"string\") return v;\n    // A key written TWICE in one block comes back as an array, accepted with no\n    // error, and reading only the string form dropped every value — so an edge\n    // naming two operations reported as naming none, `c4.op-link-missing` telling\n    // the author the opposite of what they wrote. First wins, matching the text\n    // scanner's `keyedLiteral`: the two readers disagreeing about a binding is\n    // exactly what the paragraph above exists to prevent. Later values stay\n    // dropped — one id per key per edge is the model.\n    if (Array.isArray(v) && typeof v[0] === \"string\") return v[0];\n  }\n  return undefined;\n}\n\n/** LikeC4 descriptions can be a string or a rich-text object ({ txt } / { text } / { md }). */\nexport function descText(d: unknown): string | undefined {\n  if (typeof d === \"string\") return d;\n  if (d && typeof d === \"object\") {\n    const o = d as Record<string, unknown>;\n    for (const key of [\"txt\", \"text\", \"md\", \"value\"]) {\n      const v = o[key];\n      if (typeof v === \"string\") return v;\n    }\n  }\n  return undefined;\n}\n\n/**\n * The fields of a relationship its order is decided on — `Rel` in\n * `../likec4.ts`, stated structurally because that module imports this one and\n * a type imported back would close a cycle.\n */\nexport interface RelKeys {\n  readonly source: string;\n  readonly target: string;\n  readonly title?: string;\n  readonly op?: string;\n  readonly publishes?: string;\n  readonly consumes?: string;\n  readonly tags: readonly string[];\n}\n\n/**\n * The ONE order every loader hands relationships back in: by source, then\n * target, title, `op`, `publishes`, `consumes` and tags — plain code-unit\n * compares, so the order is a function of the documents' text alone and never\n * of the locale, the machine or the run. Two edges equal on every key are equal\n * in every field `Rel` (`../likec4.ts`) carries, so which of them comes first\n * cannot be seen. `flattenModel` there sorts with it; it lives here, beside the\n * other reads of LikeC4's parse output that cannot be taken at face value,\n * because the adapter is at its line limit.\n *\n * LikeC4 does not give one, for two measured reasons (1.59.2). Its parsed\n * model indexes relations in a plain object keyed by an id HASHED FROM THE\n * DOCUMENT'S URI — and every loader stages documents under a fresh\n * crypto-random folder per invocation (`../workspace.ts` says why), so the ids\n * change on every run. A JavaScript object enumerates integer-like keys\n * numerically ahead of every other key, so whenever a hash comes out all\n * digits (about one hash in 2,200) that edge jumps to the front of the list,\n * on that run only. And inside a project of several documents the base order\n * is whichever file Langium's concurrent folder walk finished reading first.\n * The first reason is what failed a scheduled CI run on 2026-09-28:\n * `loadProjectBatch` and `loadProject` returned one service's two edges in\n * opposite orders on an unchanged commit — and on a fleet map of a few hundred\n * edges it would reorder some run's findings far more often than that.\n *\n * Declaration order is therefore NOT what a reader gets, and nothing may read\n * meaning into the position of an edge: what the `Rel` list promises is the\n * same order for the same documents, which is what the text report and the\n * `--json` envelope being diffed between runs and machines needs.\n */\nexport function compareRels(a: RelKeys, b: RelKeys): number {\n  // An absent field sorts ahead of every present one, the empty string\n  // included, so \"no title\" and \"an empty title\" cannot tie. Tags are LikeC4\n  // identifiers, which cannot contain the comma that joins them.\n  const opt = (value: string | undefined): string => (value === undefined ? \"\" : `=${value}`);\n  const keys = (r: RelKeys): string[] => [\n    r.source,\n    r.target,\n    opt(r.title),\n    opt(r.op),\n    opt(r.publishes),\n    opt(r.consumes),\n    r.tags.join(\",\"),\n  ];\n  const ka = keys(a);\n  const kb = keys(b);\n  for (let i = 0; i < ka.length; i++) {\n    if (ka[i] !== kb[i]) return ka[i]! < kb[i]! ? -1 : 1;\n  }\n  return 0;\n}\n"]}

package/dist/core/c4/prefetch/fleet.js

@@ -24,20 +24,12 @@
  * cannot leak one docs repo into the next.
  */
 import { resolve } from "node:path";
+import { memo } from "../../kernel/concurrency.js";
 import { loadArchitecture } from "../project/architecture.js";
 import { asLoadedDoc, loadProject } from "../project/load.js";
 import { modelProjectDocuments } from "../service-model/documents.js";
 import { batchServiceProjects, serviceModelAt, } from "../service-model/load.js";
 import { readModelShape, readModelShapes } from "../service-model/shape.js";
-/** One in-flight promise per key, created on first ask — the memo idiom, once. */
-function memo(store, k, make) {
-    let pending = store.get(k);
-    if (pending === undefined) {
-        pending = make();
-        store.set(k, pending);
-    }
-    return pending;
-}
 export class ServiceModels {
     deps;
     architectures = new Map();

package/dist/core/c4/prefetch/fleet.js.map

@@ -1 +1 @@
-{"version":3,"file":"fleet.js","sourceRoot":"","sources":["../../../../src/core/c4/prefetch/fleet.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Every service model ONE command invocation has read, memoised — the fleet\n * map, each model's shape, each per-service project, and each assembled\n * `ServiceModel`.\n *\n * A package of its own rather than four more maps on `core/fleet-context.ts`,\n * and the seam is the one that module's banner already states for its leaves:\n * the rules being memoised here are `../service-model/`'s (which shape a file\n * has, which documents its project holds, how a failed batch degrades), and a\n * memo whose rules live an import away is a memo somebody fills under the wrong\n * key. The read index keeps what it owns — the document parses, the\n * enumerations — and hands them in. It also keeps that file under its line\n * limit, which is the honest second reason: this axis is four memos and a batch\n * plan, and it arrived at a module that was already 336 lines of other axes.\n *\n * The direction is one-way and load-bearing: `fleet-context.ts` imports this,\n * never the reverse. Everything this class needs from the read index arrives as\n * a function on the request (`ModelRead`), so nothing here knows that a\n * FleetContext exists — which is what keeps `core/` → `core/c4/` acyclic.\n *\n * REQUEST-SCOPED exactly as `FleetContext` is: one instance per invocation,\n * dropped when the command finishes. No module-level state, so a later run\n * cannot observe an earlier one's answer, and a `chdir` between two tests\n * cannot leak one docs repo into the next.\n */\nimport { resolve } from \"node:path\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport type { ServicePaths } from \"../../repo/paths.js\";\nimport type { LoadedDoc } from \"../likec4.js\";\nimport { loadArchitecture } from \"../project/architecture.js\";\nimport { asLoadedDoc, loadProject } from \"../project/load.js\";\nimport { modelProjectDocuments } from \"../service-model/documents.js\";\nimport {\n  batchServiceProjects,\n  serviceModelAt,\n  type ServiceModel,\n} from \"../service-model/load.js\";\nimport { readModelShape, readModelShapes, type ModelShape } from \"../service-model/shape.js\";\n\n/**\n * The three things this memo cannot know for itself, supplied once by whoever\n * owns it. Functions rather than values because each is itself memoised on the\n * caller's side: asking again is what makes an answer shared rather than\n * copied.\n */\nexport interface ModelDeps {\n  /** Fires once per per-service project actually parsed, batched or not — the caller owns its counters. */\n  onProjectLoad: () => void;\n  /** The service directories that exist — the caller has enumerated them; this package must not enumerate them again. */\n  known: (docsDir: DocsDir) => Promise<ReadonlySet<string>>;\n  /** Parse one `.likec4` document ALONE, through the caller's own document memo, so a prefetched parse is a hit. */\n  standalone: (path: string) => Promise<LoadedDoc>;\n}\n\n/** One in-flight promise per key, created on first ask — the memo idiom, once. */\nfunction memo<T>(store: Map<string, Promise<T>>, k: string, make: () => Promise<T>): Promise<T> {\n  let pending = store.get(k);\n  if (pending === undefined) {\n    pending = make();\n    store.set(k, pending);\n  }\n  return pending;\n}\n\nexport class ServiceModels {\n  private readonly architectures = new Map<string, Promise<LoadedDoc>>();\n  private readonly shapeOf = new Map<string, Promise<ModelShape>>();\n  private readonly projects = new Map<string, Promise<LoadedDoc>>();\n  private readonly models = new Map<string, Promise<ServiceModel>>();\n\n  constructor(private readonly deps: ModelDeps) {}\n\n  /**\n   * The fleet map as the PROJECT it is (`../project/architecture.ts`). Read\n   * twice over for every service now rather than once for the run — it is the\n   * gate on whether an extending model can be read at all, and the other half\n   * of the diff that decides what such a model actually declares — so the memo\n   * is what keeps a fleet run to one parse of it.\n   *\n   * Filled ONLY when somebody asks. `model` below hands `loadServiceModel` a\n   * thunk rather than an awaited value, so a fleet whose models all stand alone\n   * never parses this project at all — a standalone model is read as one file,\n   * and paying for the map (and inheriting its failures) for `loam show` or the\n   * adopt brief was cost and risk for an answer nobody used.\n   */\n  architecture(docsDir: DocsDir): Promise<LoadedDoc> {\n    return memo(this.architectures, resolve(docsDir), () => loadArchitecture(docsDir));\n  }\n\n  /**\n   * Which shape each model has, keyed by resolved path — ONE read of each\n   * file's bytes per invocation, however many questions are asked of it.\n   *\n   * The bulk form is the primary one because every caller asks in bulk: the\n   * fleet target needs the shapes of the WHOLE enumeration before it can grade\n   * a single renderer-file finding, and the prefetch needs them before it can\n   * decide which workspace each model belongs in.\n   */\n  async shapes(paths: readonly string[]): Promise<Map<string, ModelShape>> {\n    const keys = [...new Set(paths.map((path) => resolve(path)))];\n    const missing = keys.filter((k) => !this.shapeOf.has(k));\n    for (const [k, shape] of await readModelShapes(missing)) {\n      // A concurrent read's promise stays authoritative — it is the one another\n      // caller is already holding — so a second scan of the same bytes can\n      // never replace it with a duplicate.\n      if (!this.shapeOf.has(k)) this.shapeOf.set(k, Promise.resolve(shape));\n    }\n    const answered = await Promise.all(keys.map(async (k) => [k, await this.shape(k)] as const));\n    return new Map(answered);\n  }\n\n  /** One model's shape, out of the same memo the bulk form fills. */\n  shape(modelPath: string): Promise<ModelShape> {\n    return memo(this.shapeOf, resolve(modelPath), () => readModelShape(modelPath));\n  }\n\n  /** A service's model, read the way its own shape demands. Memoised per model PATH, which is what identifies the file. */\n  model(docsDir: DocsDir, paths: ServicePaths): Promise<ServiceModel> {\n    return memo(this.models, resolve(paths.model), async () =>\n      serviceModelAt({\n        docsDir,\n        paths,\n        shape: await this.shape(paths.model),\n        known: await this.deps.known(docsDir),\n        // A thunk, so a standalone model never spins the map's workspace: the\n        // memo makes the extending case one parse for the run either way.\n        architecture: () => this.architecture(docsDir),\n        standalone: () => this.deps.standalone(paths.model),\n        project: () => this.project(docsDir, paths.model),\n      }),\n    );\n  }\n\n  /**\n   * Prepare every EXTENDING model's project in one workspace, and answer with\n   * the STANDALONE models' paths for the caller to prefetch through its own\n   * document batch — the two shapes need different workspaces, and only the\n   * caller has the memo the second one seeds.\n   *\n   * Purely an accelerator: a batch that could not be created seeds nothing and\n   * every reader falls back to its own load, so findings can never change\n   * because of a tmpdir — only the speed can.\n   */\n  async prefetch(docsDir: DocsDir, paths: readonly ServicePaths[]): Promise<string[]> {\n    const shapes = await this.shapes(paths.map((p) => p.model));\n    const models = (shape: ModelShape): string[] =>\n      [...shapes].filter(([, found]) => found === shape).map(([model]) => model);\n    const extending = models(\"extending\").filter((model) => !this.projects.has(model));\n    for (const [k, doc] of await batchServiceProjects(docsDir, extending)) {\n      // A concurrent load's promise stays authoritative: it is the one every\n      // reader is already holding, and replacing it would count the parse twice.\n      if (this.projects.has(k)) continue;\n      this.deps.onProjectLoad();\n      this.projects.set(k, Promise.resolve(doc));\n    }\n    return models(\"standalone\");\n  }\n\n  /**\n   * One service's project — the architecture documents and its model, parsed\n   * together. Keyed on the model, which is what `prefetch` seeds above, so a\n   * batched fleet run and a single-service run answer out of the same memo.\n   */\n  private project(docsDir: DocsDir, modelPath: string): Promise<LoadedDoc> {\n    return memo(this.projects, resolve(modelPath), async () => {\n      this.deps.onProjectLoad();\n      return asLoadedDoc(await loadProject(docsDir, await modelProjectDocuments(docsDir, modelPath)));\n    });\n  }\n}\n"]}
+{"version":3,"file":"fleet.js","sourceRoot":"","sources":["../../../../src/core/c4/prefetch/fleet.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Every service model ONE command invocation has read, memoised — the fleet\n * map, each model's shape, each per-service project, and each assembled\n * `ServiceModel`.\n *\n * A package of its own rather than four more maps on `core/fleet-context.ts`,\n * and the seam is the one that module's banner already states for its leaves:\n * the rules being memoised here are `../service-model/`'s (which shape a file\n * has, which documents its project holds, how a failed batch degrades), and a\n * memo whose rules live an import away is a memo somebody fills under the wrong\n * key. The read index keeps what it owns — the document parses, the\n * enumerations — and hands them in. It also keeps that file under its line\n * limit, which is the honest second reason: this axis is four memos and a batch\n * plan, and it arrived at a module that was already 336 lines of other axes.\n *\n * The direction is one-way and load-bearing: `fleet-context.ts` imports this,\n * never the reverse. Everything this class needs from the read index arrives as\n * a function on the request (`ModelRead`), so nothing here knows that a\n * FleetContext exists — which is what keeps `core/` → `core/c4/` acyclic.\n *\n * REQUEST-SCOPED exactly as `FleetContext` is: one instance per invocation,\n * dropped when the command finishes. No module-level state, so a later run\n * cannot observe an earlier one's answer, and a `chdir` between two tests\n * cannot leak one docs repo into the next.\n */\nimport { resolve } from \"node:path\";\nimport { memo } from \"../../kernel/concurrency.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport type { ServicePaths } from \"../../repo/paths.js\";\nimport type { LoadedDoc } from \"../likec4.js\";\nimport { loadArchitecture } from \"../project/architecture.js\";\nimport { asLoadedDoc, loadProject } from \"../project/load.js\";\nimport { modelProjectDocuments } from \"../service-model/documents.js\";\nimport {\n  batchServiceProjects,\n  serviceModelAt,\n  type ServiceModel,\n} from \"../service-model/load.js\";\nimport { readModelShape, readModelShapes, type ModelShape } from \"../service-model/shape.js\";\n\n/**\n * The three things this memo cannot know for itself, supplied once by whoever\n * owns it. Functions rather than values because each is itself memoised on the\n * caller's side: asking again is what makes an answer shared rather than\n * copied.\n */\nexport interface ModelDeps {\n  /** Fires once per per-service project actually parsed, batched or not — the caller owns its counters. */\n  onProjectLoad: () => void;\n  /** The service directories that exist — the caller has enumerated them; this package must not enumerate them again. */\n  known: (docsDir: DocsDir) => Promise<ReadonlySet<string>>;\n  /** Parse one `.likec4` document ALONE, through the caller's own document memo, so a prefetched parse is a hit. */\n  standalone: (path: string) => Promise<LoadedDoc>;\n}\n\nexport class ServiceModels {\n  private readonly architectures = new Map<string, Promise<LoadedDoc>>();\n  private readonly shapeOf = new Map<string, Promise<ModelShape>>();\n  private readonly projects = new Map<string, Promise<LoadedDoc>>();\n  private readonly models = new Map<string, Promise<ServiceModel>>();\n\n  constructor(private readonly deps: ModelDeps) {}\n\n  /**\n   * The fleet map as the PROJECT it is (`../project/architecture.ts`). Read\n   * twice over for every service now rather than once for the run — it is the\n   * gate on whether an extending model can be read at all, and the other half\n   * of the diff that decides what such a model actually declares — so the memo\n   * is what keeps a fleet run to one parse of it.\n   *\n   * Filled ONLY when somebody asks. `model` below hands `loadServiceModel` a\n   * thunk rather than an awaited value, so a fleet whose models all stand alone\n   * never parses this project at all — a standalone model is read as one file,\n   * and paying for the map (and inheriting its failures) for `loam show` or the\n   * adopt brief was cost and risk for an answer nobody used.\n   */\n  architecture(docsDir: DocsDir): Promise<LoadedDoc> {\n    return memo(this.architectures, resolve(docsDir), () => loadArchitecture(docsDir));\n  }\n\n  /**\n   * Which shape each model has, keyed by resolved path — ONE read of each\n   * file's bytes per invocation, however many questions are asked of it.\n   *\n   * The bulk form is the primary one because every caller asks in bulk: the\n   * fleet target needs the shapes of the WHOLE enumeration before it can grade\n   * a single renderer-file finding, and the prefetch needs them before it can\n   * decide which workspace each model belongs in.\n   */\n  async shapes(paths: readonly string[]): Promise<Map<string, ModelShape>> {\n    const keys = [...new Set(paths.map((path) => resolve(path)))];\n    const missing = keys.filter((k) => !this.shapeOf.has(k));\n    for (const [k, shape] of await readModelShapes(missing)) {\n      // A concurrent read's promise stays authoritative — it is the one another\n      // caller is already holding — so a second scan of the same bytes can\n      // never replace it with a duplicate.\n      if (!this.shapeOf.has(k)) this.shapeOf.set(k, Promise.resolve(shape));\n    }\n    const answered = await Promise.all(keys.map(async (k) => [k, await this.shape(k)] as const));\n    return new Map(answered);\n  }\n\n  /** One model's shape, out of the same memo the bulk form fills. */\n  shape(modelPath: string): Promise<ModelShape> {\n    return memo(this.shapeOf, resolve(modelPath), () => readModelShape(modelPath));\n  }\n\n  /** A service's model, read the way its own shape demands. Memoised per model PATH, which is what identifies the file. */\n  model(docsDir: DocsDir, paths: ServicePaths): Promise<ServiceModel> {\n    return memo(this.models, resolve(paths.model), async () =>\n      serviceModelAt({\n        docsDir,\n        paths,\n        shape: await this.shape(paths.model),\n        known: await this.deps.known(docsDir),\n        // A thunk, so a standalone model never spins the map's workspace: the\n        // memo makes the extending case one parse for the run either way.\n        architecture: () => this.architecture(docsDir),\n        standalone: () => this.deps.standalone(paths.model),\n        project: () => this.project(docsDir, paths.model),\n      }),\n    );\n  }\n\n  /**\n   * Prepare every EXTENDING model's project in one workspace, and answer with\n   * the STANDALONE models' paths for the caller to prefetch through its own\n   * document batch — the two shapes need different workspaces, and only the\n   * caller has the memo the second one seeds.\n   *\n   * Purely an accelerator: a batch that could not be created seeds nothing and\n   * every reader falls back to its own load, so findings can never change\n   * because of a tmpdir — only the speed can.\n   */\n  async prefetch(docsDir: DocsDir, paths: readonly ServicePaths[]): Promise<string[]> {\n    const shapes = await this.shapes(paths.map((p) => p.model));\n    const models = (shape: ModelShape): string[] =>\n      [...shapes].filter(([, found]) => found === shape).map(([model]) => model);\n    const extending = models(\"extending\").filter((model) => !this.projects.has(model));\n    for (const [k, doc] of await batchServiceProjects(docsDir, extending)) {\n      // A concurrent load's promise stays authoritative: it is the one every\n      // reader is already holding, and replacing it would count the parse twice.\n      if (this.projects.has(k)) continue;\n      this.deps.onProjectLoad();\n      this.projects.set(k, Promise.resolve(doc));\n    }\n    return models(\"standalone\");\n  }\n\n  /**\n   * One service's project — the architecture documents and its model, parsed\n   * together. Keyed on the model, which is what `prefetch` seeds above, so a\n   * batched fleet run and a single-service run answer out of the same memo.\n   */\n  private project(docsDir: DocsDir, modelPath: string): Promise<LoadedDoc> {\n    return memo(this.projects, resolve(modelPath), async () => {\n      this.deps.onProjectLoad();\n      return asLoadedDoc(await loadProject(docsDir, await modelProjectDocuments(docsDir, modelPath)));\n    });\n  }\n}\n"]}

package/dist/core/c4/project/architecture.js

@@ -9,9 +9,9 @@
  * `core/` may not import from `commands/` (AGENTS.md), so the choice was a second
  * copy of the two-line composition or one copy one level down. A second copy is
  * the copy that drifts, and the thing that would drift is which documents are in
- * the project: the generated `architecture/subsystems.likec4` exclusion is a
- * correctness rule (see `./documents.ts`), not a preference, and a reader that
- * forgot it would blank a fleet's whole map over a stale generated file.
+ * the project: the GENERATED documents' exclusion is a correctness rule (see
+ * `./documents.ts`), not a preference, and a reader that forgot it would blank a
+ * fleet's whole map over a stale generated file.
  *
  * So the wrapper moved here and `validate`'s own module kept the landscape
  * CONTAINMENT — `readLandscape` / `unreadableLandscape` — which is genuinely
@@ -22,11 +22,33 @@ import { join, relative, resolve } from "node:path";
 import { excludingPath, readRootExclude } from "../root-project/exclude.js";
 import { architectureDocuments } from "./documents.js";
 import { asLoadedDoc, loadProject } from "./load.js";
-import { landscapePath, subsystemViewsPath } from "../../repo/paths.js";
+import { GENERATED_ARCHITECTURE_FILES, landscapePath } from "../../repo/paths.js";
 /** `<docsDir>/architecture` — the LikeC4 project root, spelled once. */
 export function architectureDir(docsDir) {
     return join(docsDir, "architecture");
 }
+/**
+ * Every document inside `architecture/` that LOAM GENERATES, absolute — the ONE
+ * answer four project reads have to agree on, and the reason it is a SET rather
+ * than the single path it used to be.
+ *
+ * There are two generated files now (`subsystems.likec4` and `services.likec4`,
+ * both written by `loam subsystem sync`), and every one of these readers must
+ * drop BOTH: this module's own project list, the merge-preview staging beside it
+ * (`./staged.ts`), and the renderer's-eye load `c4.fleet-project-invalid` builds
+ * (`commands/validate/fleet/views/root-documents.ts`). A views-only document
+ * does not parse standalone — its `include` lines name elements the landscape
+ * declares — so a reader that keeps one loads a document whose only fault may be
+ * that `sync` has not run yet, and ONE parse error in a project blanks the model
+ * for every document in it. A file listed by one reader and forgotten by another
+ * fails silently in exactly that direction, which is why the NAMES live in one
+ * table (`repo/paths.ts`'s `GENERATED_ARCHITECTURE_FILES`) and the join to a
+ * docsDir lives here, once, rather than as one `…ViewsPath(docsDir)` call per
+ * reader that somebody has to remember to extend.
+ */
+export function generatedArchitectureDocuments(docsDir) {
+    return Object.keys(GENERATED_ARCHITECTURE_FILES).map((name) => join(architectureDir(docsDir), name));
+}
 /**
  * Exactly the documents `loadArchitecture` puts in the fleet map's project, as
  * one named answer.
@@ -35,10 +57,10 @@ export function architectureDir(docsDir) {
  * model that extends the map is parsed beside it (`c4/service-model/`), and the
  * set it must be staged with is this one plus the model. Two spellings of "the
  * architecture project's documents" would be two chances to forget the
- * generated `subsystems.likec4` exclusion — a correctness rule, not an
- * optimisation (`./documents.ts` says what it prevents) — and the reader that
- * forgot it would blank a service's whole model over a stale generated file it
- * has nothing to do with.
+ * generated documents' exclusion — a correctness rule, not an optimisation
+ * (`./documents.ts` says what it prevents) — and the reader that forgot it would
+ * blank a service's whole model over a stale generated file it has nothing to do
+ * with.
  *
  * THE ROOT `exclude` IS HONOURED HERE, and that is the second correctness rule
  * this one list carries. A `.likec4` under `architecture/` that the root project
@@ -68,7 +90,7 @@ export function architectureDir(docsDir) {
  * renderer drops.
  */
 export async function architectureProjectDocuments(docsDir) {
-    const paths = await architectureDocuments(architectureDir(docsDir), [subsystemViewsPath(docsDir)]);
+    const paths = await architectureDocuments(architectureDir(docsDir), generatedArchitectureDocuments(docsDir));
     const exclude = await readRootExclude(docsDir);
     if (exclude === null || exclude.length === 0)
         return paths;

package/dist/core/c4/project/architecture.js.map

@@ -1 +1 @@
-{"version":3,"file":"architecture.js","sourceRoot":"","sources":["../../../../src/core/c4/project/architecture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAExE,wEAAwE;AACxE,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,OAAgB;IACjE,MAAM,KAAK,GAAG,MAAM,qBAAqB,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACnG,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5C,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;AACnH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAgB;IACrD,OAAO,WAAW,CAAC,MAAM,WAAW,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,4BAA4B,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC/G,CAAC","sourcesContent":["/**\n * `architecture/` as ONE LikeC4 project — the docsDir-aware wrapper over the two\n * modules beside it.\n *\n * It lived in `commands/validate/fleet/load.ts` until the use-case axis grew a\n * second reader. That was the right home while `validate --all` was the only\n * caller: the command layer is where a `DocsDir` becomes paths. It stopped being\n * the right home the moment `core/usecases/fleet.ts` needed the same load —\n * `core/` may not import from `commands/` (AGENTS.md), so the choice was a second\n * copy of the two-line composition or one copy one level down. A second copy is\n * the copy that drifts, and the thing that would drift is which documents are in\n * the project: the generated `architecture/subsystems.likec4` exclusion is a\n * correctness rule (see `./documents.ts`), not a preference, and a reader that\n * forgot it would blank a fleet's whole map over a stale generated file.\n *\n * So the wrapper moved here and `validate`'s own module kept the landscape\n * CONTAINMENT — `readLandscape` / `unreadableLandscape` — which is genuinely\n * command-layer business: it is about which validate target a failed read is\n * filed against.\n */\nimport { join, relative, resolve } from \"node:path\";\nimport type { LoadedDoc } from \"../likec4.js\";\nimport { excludingPath, readRootExclude } from \"../root-project/exclude.js\";\nimport { architectureDocuments } from \"./documents.js\";\nimport { asLoadedDoc, loadProject } from \"./load.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport { landscapePath, subsystemViewsPath } from \"../../repo/paths.js\";\n\n/** `<docsDir>/architecture` — the LikeC4 project root, spelled once. */\nexport function architectureDir(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\");\n}\n\n/**\n * Exactly the documents `loadArchitecture` puts in the fleet map's project, as\n * one named answer.\n *\n * It exists because a SECOND project now has to contain the same set: a service\n * model that extends the map is parsed beside it (`c4/service-model/`), and the\n * set it must be staged with is this one plus the model. Two spellings of \"the\n * architecture project's documents\" would be two chances to forget the\n * generated `subsystems.likec4` exclusion — a correctness rule, not an\n * optimisation (`./documents.ts` says what it prevents) — and the reader that\n * forgot it would blank a service's whole model over a stale generated file it\n * has nothing to do with.\n *\n * THE ROOT `exclude` IS HONOURED HERE, and that is the second correctness rule\n * this one list carries. A `.likec4` under `architecture/` that the root project\n * excludes is a document the RENDERER never loads, so a global style group\n * declared in one is a name the fleet project cannot resolve — and until this\n * filter existed the generated subsystem views referenced it anyway: `likec4\n * validate` Invalid on every run, `loam validate --all` at 0 errors, `doctor`\n * healthy and `sync` \"current\" (verification 2026-09-04, W5). A root config loam\n * cannot read an `exclude` list out of filters nothing: asserting an exclusion on\n * evidence loam does not have is worse than loading one document too many.\n *\n * THE MAP ITSELF IS THE FLOOR, and it is not a special case for tidiness. The\n * filter had none, so an entry covering `architecture/landscape.likec4` — an\n * `architecture/*.likec4` a team wrote for a palette, say — left this list\n * EMPTY, and an empty project parses with zero errors. Every reader then took\n * that for \"the map declares nothing\": `validate --all` reported\n * `landscape.service-unmodelled` naming the very file that models the service\n * and `c4.invalid` on every extending model, `subsystem sync` rewrote a good\n * generated file down to a title, and nothing in either run mentioned the\n * `exclude` entry that caused it (verification 2026-09-04, review C). Keeping\n * the landscape is the tolerant direction this same banner already chooses for\n * an unreadable config: loam grades one document the renderer may skip, rather\n * than asserting a fleet's whole architecture says nothing. The entry is NAMED\n * to its author one target over — `landscape.excluded`, in\n * `commands/validate/fleet/views/projects.ts`, which reads this same list\n * through this same matcher so the two can never disagree about which file the\n * renderer drops.\n */\nexport async function architectureProjectDocuments(docsDir: DocsDir): Promise<string[]> {\n  const paths = await architectureDocuments(architectureDir(docsDir), [subsystemViewsPath(docsDir)]);\n  const exclude = await readRootExclude(docsDir);\n  if (exclude === null || exclude.length === 0) return paths;\n  const map = resolve(landscapePath(docsDir));\n  return paths.filter((path) => resolve(path) === map || excludingPath(exclude, relative(docsDir, path)) === null);\n}\n\n/**\n * The fleet map, read as the PROJECT it actually is.\n *\n * `architecture/landscape.likec4` plus every `architecture/usecases/*.likec4`,\n * merged the way the renderer merges them — because a use case declares views\n * over the landscape's elements and does not parse standalone (measured: five\n * errors). `architectureDocuments` owns which files are in and why the\n * generated one is not.\n *\n * A fleet with no use cases loads exactly the landscape and behaves as it\n * always did, which is what keeps this a widening rather than a change.\n */\nexport async function loadArchitecture(docsDir: DocsDir): Promise<LoadedDoc> {\n  return asLoadedDoc(await loadProject(architectureDir(docsDir), await architectureProjectDocuments(docsDir)));\n}\n"]}
+{"version":3,"file":"architecture.js","sourceRoot":"","sources":["../../../../src/core/c4/project/architecture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EAAE,4BAA4B,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAElF,wEAAwE;AACxE,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,8BAA8B,CAAC,OAAgB;IAC7D,OAAO,MAAM,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;AACvG,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,OAAgB;IACjE,MAAM,KAAK,GAAG,MAAM,qBAAqB,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,8BAA8B,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7G,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5C,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;AACnH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAgB;IACrD,OAAO,WAAW,CAAC,MAAM,WAAW,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,4BAA4B,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC/G,CAAC","sourcesContent":["/**\n * `architecture/` as ONE LikeC4 project — the docsDir-aware wrapper over the two\n * modules beside it.\n *\n * It lived in `commands/validate/fleet/load.ts` until the use-case axis grew a\n * second reader. That was the right home while `validate --all` was the only\n * caller: the command layer is where a `DocsDir` becomes paths. It stopped being\n * the right home the moment `core/usecases/fleet.ts` needed the same load —\n * `core/` may not import from `commands/` (AGENTS.md), so the choice was a second\n * copy of the two-line composition or one copy one level down. A second copy is\n * the copy that drifts, and the thing that would drift is which documents are in\n * the project: the GENERATED documents' exclusion is a correctness rule (see\n * `./documents.ts`), not a preference, and a reader that forgot it would blank a\n * fleet's whole map over a stale generated file.\n *\n * So the wrapper moved here and `validate`'s own module kept the landscape\n * CONTAINMENT — `readLandscape` / `unreadableLandscape` — which is genuinely\n * command-layer business: it is about which validate target a failed read is\n * filed against.\n */\nimport { join, relative, resolve } from \"node:path\";\nimport type { LoadedDoc } from \"../likec4.js\";\nimport { excludingPath, readRootExclude } from \"../root-project/exclude.js\";\nimport { architectureDocuments } from \"./documents.js\";\nimport { asLoadedDoc, loadProject } from \"./load.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport { GENERATED_ARCHITECTURE_FILES, landscapePath } from \"../../repo/paths.js\";\n\n/** `<docsDir>/architecture` — the LikeC4 project root, spelled once. */\nexport function architectureDir(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\");\n}\n\n/**\n * Every document inside `architecture/` that LOAM GENERATES, absolute — the ONE\n * answer four project reads have to agree on, and the reason it is a SET rather\n * than the single path it used to be.\n *\n * There are two generated files now (`subsystems.likec4` and `services.likec4`,\n * both written by `loam subsystem sync`), and every one of these readers must\n * drop BOTH: this module's own project list, the merge-preview staging beside it\n * (`./staged.ts`), and the renderer's-eye load `c4.fleet-project-invalid` builds\n * (`commands/validate/fleet/views/root-documents.ts`). A views-only document\n * does not parse standalone — its `include` lines name elements the landscape\n * declares — so a reader that keeps one loads a document whose only fault may be\n * that `sync` has not run yet, and ONE parse error in a project blanks the model\n * for every document in it. A file listed by one reader and forgotten by another\n * fails silently in exactly that direction, which is why the NAMES live in one\n * table (`repo/paths.ts`'s `GENERATED_ARCHITECTURE_FILES`) and the join to a\n * docsDir lives here, once, rather than as one `…ViewsPath(docsDir)` call per\n * reader that somebody has to remember to extend.\n */\nexport function generatedArchitectureDocuments(docsDir: DocsDir): string[] {\n  return Object.keys(GENERATED_ARCHITECTURE_FILES).map((name) => join(architectureDir(docsDir), name));\n}\n\n/**\n * Exactly the documents `loadArchitecture` puts in the fleet map's project, as\n * one named answer.\n *\n * It exists because a SECOND project now has to contain the same set: a service\n * model that extends the map is parsed beside it (`c4/service-model/`), and the\n * set it must be staged with is this one plus the model. Two spellings of \"the\n * architecture project's documents\" would be two chances to forget the\n * generated documents' exclusion — a correctness rule, not an optimisation\n * (`./documents.ts` says what it prevents) — and the reader that forgot it would\n * blank a service's whole model over a stale generated file it has nothing to do\n * with.\n *\n * THE ROOT `exclude` IS HONOURED HERE, and that is the second correctness rule\n * this one list carries. A `.likec4` under `architecture/` that the root project\n * excludes is a document the RENDERER never loads, so a global style group\n * declared in one is a name the fleet project cannot resolve — and until this\n * filter existed the generated subsystem views referenced it anyway: `likec4\n * validate` Invalid on every run, `loam validate --all` at 0 errors, `doctor`\n * healthy and `sync` \"current\" (verification 2026-09-04, W5). A root config loam\n * cannot read an `exclude` list out of filters nothing: asserting an exclusion on\n * evidence loam does not have is worse than loading one document too many.\n *\n * THE MAP ITSELF IS THE FLOOR, and it is not a special case for tidiness. The\n * filter had none, so an entry covering `architecture/landscape.likec4` — an\n * `architecture/*.likec4` a team wrote for a palette, say — left this list\n * EMPTY, and an empty project parses with zero errors. Every reader then took\n * that for \"the map declares nothing\": `validate --all` reported\n * `landscape.service-unmodelled` naming the very file that models the service\n * and `c4.invalid` on every extending model, `subsystem sync` rewrote a good\n * generated file down to a title, and nothing in either run mentioned the\n * `exclude` entry that caused it (verification 2026-09-04, review C). Keeping\n * the landscape is the tolerant direction this same banner already chooses for\n * an unreadable config: loam grades one document the renderer may skip, rather\n * than asserting a fleet's whole architecture says nothing. The entry is NAMED\n * to its author one target over — `landscape.excluded`, in\n * `commands/validate/fleet/views/projects.ts`, which reads this same list\n * through this same matcher so the two can never disagree about which file the\n * renderer drops.\n */\nexport async function architectureProjectDocuments(docsDir: DocsDir): Promise<string[]> {\n  const paths = await architectureDocuments(architectureDir(docsDir), generatedArchitectureDocuments(docsDir));\n  const exclude = await readRootExclude(docsDir);\n  if (exclude === null || exclude.length === 0) return paths;\n  const map = resolve(landscapePath(docsDir));\n  return paths.filter((path) => resolve(path) === map || excludingPath(exclude, relative(docsDir, path)) === null);\n}\n\n/**\n * The fleet map, read as the PROJECT it actually is.\n *\n * `architecture/landscape.likec4` plus every `architecture/usecases/*.likec4`,\n * merged the way the renderer merges them — because a use case declares views\n * over the landscape's elements and does not parse standalone (measured: five\n * errors). `architectureDocuments` owns which files are in and why the\n * generated one is not.\n *\n * A fleet with no use cases loads exactly the landscape and behaves as it\n * always did, which is what keeps this a widening rather than a change.\n */\nexport async function loadArchitecture(docsDir: DocsDir): Promise<LoadedDoc> {\n  return asLoadedDoc(await loadProject(architectureDir(docsDir), await architectureProjectDocuments(docsDir)));\n}\n"]}

package/dist/core/c4/project/documents.js

@@ -9,8 +9,8 @@
  * that STANDS ALONE — one `services/<tree>/**` entry per standalone model,
  * never the whole subtree (`c4/service-model/renderer.ts` owns that list, and
  * is the one place loam reads that file). loam's own answer here is all of them
- * EXCEPT the generated `architecture/subsystems.likec4`, and that exception is
- * not an optimisation:
+ * EXCEPT the documents loam GENERATES there (`architecture/subsystems.likec4`
+ * and `architecture/services.likec4`), and that exception is not an optimisation:
  *
  *  - docs/DESIGN.md rule 26 excludes the generated file from every read loam
  *    performs. Its staleness is a byte compare (`subsystem.views-stale`) and
@@ -22,11 +22,12 @@
  *    whose only problem is a stale generated file would lose its whole map
  *    instead of getting the one finding that names the repair.
  *
- * The skip is passed in by the caller rather than spelled here, so the filename
- * stays written in `repo/paths.ts` alone.
+ * The skip is passed in by the caller rather than spelled here, so the filenames
+ * stay written in `repo/paths.ts` alone, and every reader takes the same SET out
+ * (`./architecture.ts` holds the one join).
  */
 import { readdir } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { join, relative, resolve } from "node:path";
 /**
  * Every `.likec4` file under `dir`, recursively, minus `skip`, in a stable
  * order.
@@ -40,24 +41,49 @@ import { join, resolve } from "node:path";
  */
 export async function architectureDocuments(dir, skip = []) {
     const excluded = new Set(skip.map((path) => resolve(path)));
+    return likec4DocumentsUnder(dir, { keeps: (path) => !excluded.has(resolve(path)) });
+}
+/**
+ * `architectureDocuments(dir)`, each beside its path inside `dir`,
+ * `/`-separated — the id a feature-local document axis keys on (a feature's
+ * `usecases/` flows, its `deployment/` topology), spelled once for both.
+ */
+export async function relativeDocuments(dir) {
+    const base = resolve(dir);
+    return (await architectureDocuments(dir)).map((path) => ({ rel: relative(base, path).split(/[\\/]/).join("/"), path }));
+}
+/**
+ * The walk under `architectureDocuments` and the renderer root project's
+ * enumeration (`commands/validate/fleet/views/root-documents.ts`): every
+ * `.likec4` under `dir`, recursively, absolute and sorted for the reason
+ * above. A directory that cannot be read contributes nothing, never a throw —
+ * for the missing-`architecture/` reason above, and because the root walk
+ * runs inside `validate --all` over a whole fleet, where the one behaviour it
+ * may never have is failing the run it was added to.
+ */
+export async function likec4DocumentsUnder(dir, walk) {
     const found = [];
-    const walk = async (at) => {
+    const visit = async (at) => {
         let entries;
         try {
             entries = await readdir(at, { withFileTypes: true });
         }
         catch {
+            // Absent or unreadable: nothing to load from here (see above).
             return;
         }
         for (const entry of entries) {
             const path = join(at, entry.name);
-            if (entry.isDirectory())
-                await walk(path);
-            else if (entry.name.endsWith(".likec4") && !excluded.has(resolve(path)))
+            if (entry.isDirectory()) {
+                if (walk.enters?.(entry.name) ?? true)
+                    await visit(path);
+            }
+            else if (entry.name.endsWith(".likec4") && (walk.keeps?.(path) ?? true)) {
                 found.push(path);
+            }
         }
     };
-    await walk(resolve(dir));
+    await visit(resolve(dir));
     return found.sort();
 }
 //# sourceMappingURL=documents.js.map

package/dist/core/c4/project/documents.js.map

@@ -1 +1 @@
-{"version":3,"file":"documents.js","sourceRoot":"","sources":["../../../../src/core/c4/project/documents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,GAAW,EAAE,IAAI,GAAa,EAAE;IAC1E,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,KAAK,EAAE,EAAU,EAAiB,EAAE;QAC/C,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,KAAK,CAAC,WAAW,EAAE;gBAAE,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;iBACrC,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC,CAAC;IACF,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC","sourcesContent":["/**\n * Which `.likec4` documents in a docs repo's `architecture/` loam loads as one\n * project.\n *\n * The renderer's answer is \"all of them\". The root `likec4.config.json` no\n * longer excludes `services/**`: the root project holds the map AND every\n * service model that EXTENDS it, because such a model is only readable beside\n * the map, and `loam subsystem sync` excludes only the directory of each model\n * that STANDS ALONE — one `services/<tree>/**` entry per standalone model,\n * never the whole subtree (`c4/service-model/renderer.ts` owns that list, and\n * is the one place loam reads that file). loam's own answer here is all of them\n * EXCEPT the generated `architecture/subsystems.likec4`, and that exception is\n * not an optimisation:\n *\n *  - docs/DESIGN.md rule 26 excludes the generated file from every read loam\n *    performs. Its staleness is a byte compare (`subsystem.views-stale`) and\n *    nothing anywhere reads its contents.\n *  - Including it would invent a failure mode. Its `include` lines name\n *    landscape element ids, so a file that has drifted — a service removed\n *    since the last `loam subsystem sync` — would be a parse error, and a parse\n *    error in one project document blanks the model for all of them. A fleet\n *    whose only problem is a stale generated file would lose its whole map\n *    instead of getting the one finding that names the repair.\n *\n * The skip is passed in by the caller rather than spelled here, so the filename\n * stays written in `repo/paths.ts` alone.\n */\nimport { readdir } from \"node:fs/promises\";\nimport { join, resolve } from \"node:path\";\n\n/**\n * Every `.likec4` file under `dir`, recursively, minus `skip`, in a stable\n * order.\n *\n * Sorted because it decides the staging order and therefore nothing at all —\n * LikeC4 merges a project regardless — but a stable list makes a failure\n * reproducible and a diff of one readable. A directory that does not exist is\n * an empty list, never a throw: a fleet with no `architecture/` is a fleet with\n * nothing to load, which is already `landscape.missing`'s question, not this\n * function's.\n */\nexport async function architectureDocuments(dir: string, skip: string[] = []): Promise<string[]> {\n  const excluded = new Set(skip.map((path) => resolve(path)));\n  const found: string[] = [];\n  const walk = async (at: string): Promise<void> => {\n    let entries;\n    try {\n      entries = await readdir(at, { withFileTypes: true });\n    } catch {\n      return;\n    }\n    for (const entry of entries) {\n      const path = join(at, entry.name);\n      if (entry.isDirectory()) await walk(path);\n      else if (entry.name.endsWith(\".likec4\") && !excluded.has(resolve(path))) found.push(path);\n    }\n  };\n  await walk(resolve(dir));\n  return found.sort();\n}\n"]}
+{"version":3,"file":"documents.js","sourceRoot":"","sources":["../../../../src/core/c4/project/documents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,GAAW,EAAE,IAAI,GAAa,EAAE;IAC1E,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5D,OAAO,oBAAoB,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;AACtF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,GAAW;IACjD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,CAAC,MAAM,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AAC1H,CAAC;AAQD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,GAAW,EAAE,IAAkB;IACxE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAG,KAAK,EAAE,EAAU,EAAiB,EAAE;QAChD,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,+DAA+D;YAC/D,OAAO;QACT,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI;oBAAE,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;YAC3D,CAAC;iBAAM,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC;gBAC1E,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IACF,MAAM,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC","sourcesContent":["/**\n * Which `.likec4` documents in a docs repo's `architecture/` loam loads as one\n * project.\n *\n * The renderer's answer is \"all of them\". The root `likec4.config.json` no\n * longer excludes `services/**`: the root project holds the map AND every\n * service model that EXTENDS it, because such a model is only readable beside\n * the map, and `loam subsystem sync` excludes only the directory of each model\n * that STANDS ALONE — one `services/<tree>/**` entry per standalone model,\n * never the whole subtree (`c4/service-model/renderer.ts` owns that list, and\n * is the one place loam reads that file). loam's own answer here is all of them\n * EXCEPT the documents loam GENERATES there (`architecture/subsystems.likec4`\n * and `architecture/services.likec4`), and that exception is not an optimisation:\n *\n *  - docs/DESIGN.md rule 26 excludes the generated file from every read loam\n *    performs. Its staleness is a byte compare (`subsystem.views-stale`) and\n *    nothing anywhere reads its contents.\n *  - Including it would invent a failure mode. Its `include` lines name\n *    landscape element ids, so a file that has drifted — a service removed\n *    since the last `loam subsystem sync` — would be a parse error, and a parse\n *    error in one project document blanks the model for all of them. A fleet\n *    whose only problem is a stale generated file would lose its whole map\n *    instead of getting the one finding that names the repair.\n *\n * The skip is passed in by the caller rather than spelled here, so the filenames\n * stay written in `repo/paths.ts` alone, and every reader takes the same SET out\n * (`./architecture.ts` holds the one join).\n */\nimport { readdir } from \"node:fs/promises\";\nimport { join, relative, resolve } from \"node:path\";\n\n/**\n * Every `.likec4` file under `dir`, recursively, minus `skip`, in a stable\n * order.\n *\n * Sorted because it decides the staging order and therefore nothing at all —\n * LikeC4 merges a project regardless — but a stable list makes a failure\n * reproducible and a diff of one readable. A directory that does not exist is\n * an empty list, never a throw: a fleet with no `architecture/` is a fleet with\n * nothing to load, which is already `landscape.missing`'s question, not this\n * function's.\n */\nexport async function architectureDocuments(dir: string, skip: string[] = []): Promise<string[]> {\n  const excluded = new Set(skip.map((path) => resolve(path)));\n  return likec4DocumentsUnder(dir, { keeps: (path) => !excluded.has(resolve(path)) });\n}\n\n/**\n * `architectureDocuments(dir)`, each beside its path inside `dir`,\n * `/`-separated — the id a feature-local document axis keys on (a feature's\n * `usecases/` flows, its `deployment/` topology), spelled once for both.\n */\nexport async function relativeDocuments(dir: string): Promise<{ rel: string; path: string }[]> {\n  const base = resolve(dir);\n  return (await architectureDocuments(dir)).map((path) => ({ rel: relative(base, path).split(/[\\\\/]/).join(\"/\"), path }));\n}\n\n/** What one walk leaves out: directories it never enters (by name), documents it never collects (by path). */\nexport interface DocumentWalk {\n  enters?: (name: string) => boolean;\n  keeps?: (path: string) => boolean;\n}\n\n/**\n * The walk under `architectureDocuments` and the renderer root project's\n * enumeration (`commands/validate/fleet/views/root-documents.ts`): every\n * `.likec4` under `dir`, recursively, absolute and sorted for the reason\n * above. A directory that cannot be read contributes nothing, never a throw —\n * for the missing-`architecture/` reason above, and because the root walk\n * runs inside `validate --all` over a whole fleet, where the one behaviour it\n * may never have is failing the run it was added to.\n */\nexport async function likec4DocumentsUnder(dir: string, walk: DocumentWalk): Promise<string[]> {\n  const found: string[] = [];\n  const visit = async (at: string): Promise<void> => {\n    let entries;\n    try {\n      entries = await readdir(at, { withFileTypes: true });\n    } catch {\n      // Absent or unreadable: nothing to load from here (see above).\n      return;\n    }\n    for (const entry of entries) {\n      const path = join(at, entry.name);\n      if (entry.isDirectory()) {\n        if (walk.enters?.(entry.name) ?? true) await visit(path);\n      } else if (entry.name.endsWith(\".likec4\") && (walk.keeps?.(path) ?? true)) {\n        found.push(path);\n      }\n    }\n  };\n  await visit(resolve(dir));\n  return found.sort();\n}\n"]}