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

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

@@ -0,0 +1,78 @@
+/**
+ * The `specification { ... }` block, read off LikeC4's parsed model.
+ *
+ * loam reads a model for what it MEANS, and until LikeC4 1.59.0 the
+ * specification carried nothing loam had to mean anything by: it declared which
+ * kinds and tags exist, and LikeC4 itself enforced that every use was declared.
+ * 1.59.0 added **tags on kinds** — `specification { element softwareSystem {
+ * #external } }` — and LikeC4 applies those tags to every element of the kind
+ * before loam ever sees it. So `Elem.tags` stopped answering the question loam
+ * was actually asking of it.
+ *
+ * That distinction is what this module exists for. loam does not need the
+ * specification to SEE an inherited tag — the tag is already on the element, and
+ * `flattenModel` has always copied it faithfully. It needs the specification to
+ * tell an inherited tag from one somebody wrote on the element, because loam
+ * gives two tags grading meaning (`#external` exempts an element from the
+ * landscape↔services reconciliation, `#platform` silences a hub warning) and a
+ * kind-wide declaration of either switches that grading off for every element of
+ * the kind at once. Six words in the specification block turned a fleet gate
+ * green over a fleet it had stopped checking; `kindTagFindings`
+ * (commands/validate/fleet/kind-tags.ts) is the check that refuses that, and this
+ * is the reader it is built on.
+ *
+ * Everything here is defensive. The specification is not part of the model API
+ * loam's `ReadableModel` slice pins, and 1.59.2 already spells the two kind
+ * tables differently — element kinds carry `tags` at the top of the kind record,
+ * relationship kinds carry theirs under `style` — which is exactly the kind of
+ * internal detail that moves between releases. Both positions are read for both
+ * tables, so a shape that swaps degrades to "no kind tags" (the pre-1.59.0
+ * answer) rather than throwing inside a validate run.
+ */
+/** Every string in `v`, or `[]` — `v` is `unknown` off an untyped parse. */
+function stringList(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+/**
+ * The tags one kind record declares. 1.59.2 puts an element kind's under `tags`
+ * and a relationship kind's under `style.tags`; both are read for both, because
+ * which one a given kind table uses is LikeC4's internal business and a check
+ * that silently stopped seeing tags would fail OPEN — the exact failure this
+ * module was added to close.
+ */
+function kindTags(kind) {
+    if (!kind || typeof kind !== "object")
+        return [];
+    const rec = kind;
+    const style = rec["style"];
+    const nested = style && typeof style === "object" ? style["tags"] : undefined;
+    return [...new Set([...stringList(rec["tags"]), ...stringList(nested)])];
+}
+/** `{ kind: [tag, ...] }` for every kind in one of the specification's kind tables. */
+function tagTable(table) {
+    if (!table || typeof table !== "object")
+        return {};
+    const out = {};
+    for (const [name, kind] of Object.entries(table)) {
+        const tags = kindTags(kind);
+        if (tags.length > 0)
+            out[name] = tags;
+    }
+    return out;
+}
+/**
+ * Normalize the `specification` LikeC4 hangs off its parsed model. Takes the
+ * whole untyped value so every shape assumption lives in this file: callers get
+ * `DocSpecification` or nothing, and never touch `unknown`.
+ */
+export function readSpecification(spec) {
+    if (!spec || typeof spec !== "object")
+        return undefined;
+    const rec = spec;
+    return {
+        elementKindTags: tagTable(rec["elements"]),
+        relationshipKindTags: tagTable(rec["relationships"]),
+        metadataKeys: stringList(rec["metadataKeys"]),
+    };
+}
+//# sourceMappingURL=specification.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"specification.js","sourceRoot":"","sources":["../../../../src/core/c4/parsed/specification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAwBH,4EAA4E;AAC5E,SAAS,UAAU,CAAC,CAAU;IAC5B,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACrF,CAAC;AAED;;;;;;GAMG;AACH,SAAS,QAAQ,CAAC,IAAa;IAC7B,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACjD,MAAM,GAAG,GAAG,IAA+B,CAAC;IAC5C,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,MAAM,MAAM,GAAG,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAE,KAAiC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3G,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,uFAAuF;AACvF,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACnD,MAAM,GAAG,GAA6B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QAC5E,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAa;IAC7C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACxD,MAAM,GAAG,GAAG,IAA+B,CAAC;IAC5C,OAAO;QACL,eAAe,EAAE,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC1C,oBAAoB,EAAE,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QACpD,YAAY,EAAE,UAAU,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;KAC9C,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The `specification { ... }` block, read off LikeC4's parsed model.\n *\n * loam reads a model for what it MEANS, and until LikeC4 1.59.0 the\n * specification carried nothing loam had to mean anything by: it declared which\n * kinds and tags exist, and LikeC4 itself enforced that every use was declared.\n * 1.59.0 added **tags on kinds** — `specification { element softwareSystem {\n * #external } }` — and LikeC4 applies those tags to every element of the kind\n * before loam ever sees it. So `Elem.tags` stopped answering the question loam\n * was actually asking of it.\n *\n * That distinction is what this module exists for. loam does not need the\n * specification to SEE an inherited tag — the tag is already on the element, and\n * `flattenModel` has always copied it faithfully. It needs the specification to\n * tell an inherited tag from one somebody wrote on the element, because loam\n * gives two tags grading meaning (`#external` exempts an element from the\n * landscape↔services reconciliation, `#platform` silences a hub warning) and a\n * kind-wide declaration of either switches that grading off for every element of\n * the kind at once. Six words in the specification block turned a fleet gate\n * green over a fleet it had stopped checking; `kindTagFindings`\n * (commands/validate/fleet/kind-tags.ts) is the check that refuses that, and this\n * is the reader it is built on.\n *\n * Everything here is defensive. The specification is not part of the model API\n * loam's `ReadableModel` slice pins, and 1.59.2 already spells the two kind\n * tables differently — element kinds carry `tags` at the top of the kind record,\n * relationship kinds carry theirs under `style` — which is exactly the kind of\n * internal detail that moves between releases. Both positions are read for both\n * tables, so a shape that swaps degrades to \"no kind tags\" (the pre-1.59.0\n * answer) rather than throwing inside a validate run.\n */\n\n/** The slice of a LikeC4 `specification { ... }` block loam reads, normalized. */\nexport interface DocSpecification {\n  /** Tag names each ELEMENT kind declares, by kind name. Kinds declaring none are absent. */\n  elementKindTags: Record<string, string[]>;\n  /**\n   * Tag names each RELATIONSHIP kind declares, by kind name.\n   *\n   * Read and carried even though no check grades relationship tags today: the\n   * feature tag on an edge is what `loam archive` splices on, and a kind-wide\n   * declaration of one is the same defect on the write path. Dropping the table\n   * here would make that a second reader's problem to rediscover.\n   */\n  relationshipKindTags: Record<string, string[]>;\n  /**\n   * The sorted union of every `metadata { }` key used anywhere in the document,\n   * computed by LikeC4 for free. loam's own binding vocabulary is four keys —\n   * `service`, `op`, `publishes`, `consumes` — and a near miss (`ops`,\n   * `serviceId`) parses clean, binds nothing, and reports nothing.\n   */\n  metadataKeys: string[];\n}\n\n/** Every string in `v`, or `[]` — `v` is `unknown` off an untyped parse. */\nfunction stringList(v: unknown): string[] {\n  return Array.isArray(v) ? v.filter((x): x is string => typeof x === \"string\") : [];\n}\n\n/**\n * The tags one kind record declares. 1.59.2 puts an element kind's under `tags`\n * and a relationship kind's under `style.tags`; both are read for both, because\n * which one a given kind table uses is LikeC4's internal business and a check\n * that silently stopped seeing tags would fail OPEN — the exact failure this\n * module was added to close.\n */\nfunction kindTags(kind: unknown): string[] {\n  if (!kind || typeof kind !== \"object\") return [];\n  const rec = kind as Record<string, unknown>;\n  const style = rec[\"style\"];\n  const nested = style && typeof style === \"object\" ? (style as Record<string, unknown>)[\"tags\"] : undefined;\n  return [...new Set([...stringList(rec[\"tags\"]), ...stringList(nested)])];\n}\n\n/** `{ kind: [tag, ...] }` for every kind in one of the specification's kind tables. */\nfunction tagTable(table: unknown): Record<string, string[]> {\n  if (!table || typeof table !== \"object\") return {};\n  const out: Record<string, string[]> = {};\n  for (const [name, kind] of Object.entries(table as Record<string, unknown>)) {\n    const tags = kindTags(kind);\n    if (tags.length > 0) out[name] = tags;\n  }\n  return out;\n}\n\n/**\n * Normalize the `specification` LikeC4 hangs off its parsed model. Takes the\n * whole untyped value so every shape assumption lives in this file: callers get\n * `DocSpecification` or nothing, and never touch `unknown`.\n */\nexport function readSpecification(spec: unknown): DocSpecification | undefined {\n  if (!spec || typeof spec !== \"object\") return undefined;\n  const rec = spec as Record<string, unknown>;\n  return {\n    elementKindTags: tagTable(rec[\"elements\"]),\n    relationshipKindTags: tagTable(rec[\"relationships\"]),\n    metadataKeys: stringList(rec[\"metadataKeys\"]),\n  };\n}\n"]}

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

@@ -0,0 +1,57 @@
+/**
+ * The corners of LikeC4's parse output that are typed `unknown`, decoded.
+ *
+ * LikeC4 models `metadata { ... }` values and a `description` as open shapes —
+ * a value may be a string, an array, or a rich-text object, and the declared
+ * type says none of that. Every one of those crossings needs a defensive read
+ * that answers "not present" rather than throwing, and each read encodes a
+ * defect somebody hit. They live together here, one module below the adapter
+ * (`../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.
+ */
+/**
+ * Read one string key out of a LikeC4 `metadata { ... }` block. Four keys carry
+ * loam's spines: `op` on a relationship (the OpenAPI operationId it calls),
+ * `publishes`/`consumes` on a relationship (the AsyncAPI message it produces or
+ * receives), and `service` on an element (the services/<id> directory it stands
+ * for). Every one of them is read by BOTH model readers — the parsed one
+ * (`flattenModel` in `../likec4.ts`, which calls this) and the text scanner
+ * `scanModel` uses for archive's splice map — because a key only one of them
+ * sees is a key the merge silently drops. Elements with no metadata come back as
+ * `{}`, so a missing key is indistinguishable from a missing block — both mean
+ * "not bound".
+ */
+export function metaKey(m, key) {
+    if (m && typeof m === "object") {
+        const v = m[key];
+        if (typeof v === "string")
+            return v;
+        // A key written TWICE in one block comes back as an array, accepted with no
+        // error, and reading only the string form dropped every value — so an edge
+        // naming two operations reported as naming none, `c4.op-link-missing` telling
+        // the author the opposite of what they wrote. First wins, matching the text
+        // scanner's `keyedLiteral`: the two readers disagreeing about a binding is
+        // exactly what the paragraph above exists to prevent. Later values stay
+        // dropped — one id per key per edge is the model.
+        if (Array.isArray(v) && typeof v[0] === "string")
+            return v[0];
+    }
+    return undefined;
+}
+/** LikeC4 descriptions can be a string or a rich-text object ({ txt } / { text } / { md }). */
+export function descText(d) {
+    if (typeof d === "string")
+        return d;
+    if (d && typeof d === "object") {
+        const o = d;
+        for (const key of ["txt", "text", "md", "value"]) {
+            const v = o[key];
+            if (typeof v === "string")
+                return v;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=values.js.map

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

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

package/dist/core/c4/parsed/view-ids.js

@@ -0,0 +1,75 @@
+/**
+ * The ids of every view a document AUTHORS — the census read, as distinct from
+ * `./dynamic-views.ts`'s use-case read.
+ *
+ * Two readers over one record, because docs/DESIGN.md rule 26 states two
+ * filters and they are not interchangeable. A use-case reader wants dynamic
+ * views and filters on `_type === "dynamic"`. A census must see authored
+ * ELEMENT views too — a `view fleet { include * }` claims an id exactly as
+ * firmly as a dynamic one does — so it filters on `sourcePath !== undefined`
+ * instead. Measured: the `index` view LikeC4 synthesizes into every document is
+ * `_type: "element"` AND carries no `sourcePath`, so each filter drops it, and a
+ * reader that learned only the other one would report a fiction.
+ *
+ * Kept as its own module rather than a second export beside the use-case reader:
+ * the two share nothing but the reach into `$data`, and a defensive adapter is
+ * safer when each one owns its shape assumptions outright — the same reason
+ * `./specification.ts` states.
+ *
+ * Ids only, each with the file that claims it. What the view SHOWS stays
+ * unread, in any document, forever.
+ */
+/**
+ * The shape LikeC4 mints for a view its author never named — `view of svc { }`
+ * becomes `view_1yu7e9n`.
+ *
+ * Excluded from the census, and this is a correctness rule rather than
+ * tidiness: such an id is not a claim anybody wrote, and MEASURED at the
+ * 1.59.2 pin it is not even stable across loam's own two loaders — the same
+ * document yields `view_1yu7e9n` through `loadFile` and `view_zmkx82` through
+ * `loadBatch`, because the mint hashes the document URI and the batch stages
+ * into a temp workspace. Reporting it would put a value in `LoadedDoc` that
+ * depends on which loader ran, which is the one thing
+ * test/fleet-context-parity.test.ts exists to forbid; it also cannot collide
+ * with anything loam generates, since every generated id loam mints carries a
+ * prefix of its own.
+ *
+ * The cost is exact and small: an author who literally writes
+ * `view view_abc { }` loses that id from the census. It is a name nobody
+ * chooses, and no check reads the census for anything but collisions against
+ * loam's own generated prefixes, which this shape can never match.
+ */
+const MINTED_ID = /^view_[0-9a-z]+$/;
+/** A record, or nothing — `v` is `unknown` off an untyped parse. */
+function record(v) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+}
+/**
+ * Every view id the document declares, in the record's own order.
+ *
+ * `model` is the AWAITED `parsedModel()` result; `$data` is undefined on the
+ * unresolved promise, so a caller that forgets the await gets an empty census
+ * rather than a throw. Empty is also what a malformed record yields — this runs
+ * inside `validate --all` over every C4 document a fleet has, and the one
+ * behaviour it may never have is failing the run it was added to.
+ */
+export function readViewIds(model) {
+    const views = record(record(record(model)?.["$data"])?.["views"]);
+    if (!views)
+        return [];
+    const out = [];
+    for (const raw of Object.values(views)) {
+        const rec = record(raw);
+        // Authored, which is what `sourcePath` means here. The synthesized entry
+        // has none, and reporting a collision against a view nobody wrote would be
+        // a false error on every fleet in existence.
+        const sourcePath = rec?.["sourcePath"];
+        if (!rec || typeof sourcePath !== "string")
+            continue;
+        const id = rec["id"];
+        if (typeof id === "string" && id.length > 0 && !MINTED_ID.test(id))
+            out.push({ id, sourcePath });
+    }
+    return out;
+}
+//# sourceMappingURL=view-ids.js.map

package/dist/core/c4/parsed/view-ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-ids.js","sourceRoot":"","sources":["../../../../src/core/c4/parsed/view-ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,SAAS,GAAG,kBAAkB,CAAC;AAErC,oEAAoE;AACpE,SAAS,MAAM,CAAC,CAAU;IACxB,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAA6B,CAAC,CAAC,CAAC,SAAS,CAAC;AACtG,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAClE,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,MAAM,GAAG,GAAkB,EAAE,CAAC;IAC9B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,yEAAyE;QACzE,2EAA2E;QAC3E,6CAA6C;QAC7C,MAAM,UAAU,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,CAAC;QACvC,IAAI,CAAC,GAAG,IAAI,OAAO,UAAU,KAAK,QAAQ;YAAE,SAAS;QACrD,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QACrB,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;IACnG,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["/**\n * The ids of every view a document AUTHORS — the census read, as distinct from\n * `./dynamic-views.ts`'s use-case read.\n *\n * Two readers over one record, because docs/DESIGN.md rule 26 states two\n * filters and they are not interchangeable. A use-case reader wants dynamic\n * views and filters on `_type === \"dynamic\"`. A census must see authored\n * ELEMENT views too — a `view fleet { include * }` claims an id exactly as\n * firmly as a dynamic one does — so it filters on `sourcePath !== undefined`\n * instead. Measured: the `index` view LikeC4 synthesizes into every document is\n * `_type: \"element\"` AND carries no `sourcePath`, so each filter drops it, and a\n * reader that learned only the other one would report a fiction.\n *\n * Kept as its own module rather than a second export beside the use-case reader:\n * the two share nothing but the reach into `$data`, and a defensive adapter is\n * safer when each one owns its shape assumptions outright — the same reason\n * `./specification.ts` states.\n *\n * Ids only, each with the file that claims it. What the view SHOWS stays\n * unread, in any document, forever.\n */\n\n/** One authored view id, and the document that claims it. */\nexport interface ViewIdClaim {\n  id: string;\n  /** As LikeC4 spells it: relative to the project root. */\n  sourcePath: string;\n}\n\n/**\n * The shape LikeC4 mints for a view its author never named — `view of svc { }`\n * becomes `view_1yu7e9n`.\n *\n * Excluded from the census, and this is a correctness rule rather than\n * tidiness: such an id is not a claim anybody wrote, and MEASURED at the\n * 1.59.2 pin it is not even stable across loam's own two loaders — the same\n * document yields `view_1yu7e9n` through `loadFile` and `view_zmkx82` through\n * `loadBatch`, because the mint hashes the document URI and the batch stages\n * into a temp workspace. Reporting it would put a value in `LoadedDoc` that\n * depends on which loader ran, which is the one thing\n * test/fleet-context-parity.test.ts exists to forbid; it also cannot collide\n * with anything loam generates, since every generated id loam mints carries a\n * prefix of its own.\n *\n * The cost is exact and small: an author who literally writes\n * `view view_abc { }` loses that id from the census. It is a name nobody\n * chooses, and no check reads the census for anything but collisions against\n * loam's own generated prefixes, which this shape can never match.\n */\nconst MINTED_ID = /^view_[0-9a-z]+$/;\n\n/** A record, or nothing — `v` is `unknown` off an untyped parse. */\nfunction record(v: unknown): Record<string, unknown> | undefined {\n  return v && typeof v === \"object\" && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;\n}\n\n/**\n * Every view id the document declares, in the record's own order.\n *\n * `model` is the AWAITED `parsedModel()` result; `$data` is undefined on the\n * unresolved promise, so a caller that forgets the await gets an empty census\n * rather than a throw. Empty is also what a malformed record yields — this runs\n * inside `validate --all` over every C4 document a fleet has, and the one\n * behaviour it may never have is failing the run it was added to.\n */\nexport function readViewIds(model: unknown): ViewIdClaim[] {\n  const views = record(record(record(model)?.[\"$data\"])?.[\"views\"]);\n  if (!views) return [];\n  const out: ViewIdClaim[] = [];\n  for (const raw of Object.values(views)) {\n    const rec = record(raw);\n    // Authored, which is what `sourcePath` means here. The synthesized entry\n    // has none, and reporting a collision against a view nobody wrote would be\n    // a false error on every fleet in existence.\n    const sourcePath = rec?.[\"sourcePath\"];\n    if (!rec || typeof sourcePath !== \"string\") continue;\n    const id = rec[\"id\"];\n    if (typeof id === \"string\" && id.length > 0 && !MINTED_ID.test(id)) out.push({ id, sourcePath });\n  }\n  return out;\n}\n"]}

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

@@ -0,0 +1,45 @@
+/**
+ * `architecture/` as ONE LikeC4 project — the docsDir-aware wrapper over the two
+ * modules beside it.
+ *
+ * It lived in `commands/validate/fleet/load.ts` until the use-case axis grew a
+ * second reader. That was the right home while `validate --all` was the only
+ * caller: the command layer is where a `DocsDir` becomes paths. It stopped being
+ * the right home the moment `core/usecases/fleet.ts` needed the same load —
+ * `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.
+ *
+ * So the wrapper moved here and `validate`'s own module kept the landscape
+ * CONTAINMENT — `readLandscape` / `unreadableLandscape` — which is genuinely
+ * command-layer business: it is about which validate target a failed read is
+ * filed against.
+ */
+import { join } from "node:path";
+import { architectureDocuments } from "./documents.js";
+import { asLoadedDoc, loadProject } from "./load.js";
+import { subsystemViewsPath } from "../../repo/paths.js";
+/** `<docsDir>/architecture` — the LikeC4 project root, spelled once. */
+export function architectureDir(docsDir) {
+    return join(docsDir, "architecture");
+}
+/**
+ * The fleet map, read as the PROJECT it actually is.
+ *
+ * `architecture/landscape.likec4` plus every `architecture/usecases/*.likec4`,
+ * merged the way the renderer merges them — because a use case declares views
+ * over the landscape's elements and does not parse standalone (measured: five
+ * errors). `architectureDocuments` owns which files are in and why the
+ * generated one is not.
+ *
+ * A fleet with no use cases loads exactly the landscape and behaves as it
+ * always did, which is what keeps this a widening rather than a change.
+ */
+export async function loadArchitecture(docsDir) {
+    const dir = architectureDir(docsDir);
+    return asLoadedDoc(await loadProject(dir, await architectureDocuments(dir, [subsystemViewsPath(docsDir)])));
+}
+//# sourceMappingURL=architecture.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"architecture.js","sourceRoot":"","sources":["../../../../src/core/c4/project/architecture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,wEAAwE;AACxE,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAgB;IACrD,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO,WAAW,CAAC,MAAM,WAAW,CAAC,GAAG,EAAE,MAAM,qBAAqB,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9G,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 } from \"node:path\";\nimport type { LoadedDoc } from \"../likec4.js\";\nimport { architectureDocuments } from \"./documents.js\";\nimport { asLoadedDoc, loadProject } from \"./load.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport { 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 * 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  const dir = architectureDir(docsDir);\n  return asLoadedDoc(await loadProject(dir, await architectureDocuments(dir, [subsystemViewsPath(docsDir)])));\n}\n"]}

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

@@ -0,0 +1,58 @@
+/**
+ * Which `.likec4` documents in a docs repo's `architecture/` loam loads as one
+ * project.
+ *
+ * The renderer's answer is "all of them" — `likec4.config.json` scopes the root
+ * LikeC4 project to everything but `services/**` and `features/**`. loam's
+ * answer is all of them EXCEPT the generated `architecture/subsystems.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
+ *    nothing anywhere reads its contents.
+ *  - Including it would invent a failure mode. Its `include` lines name
+ *    landscape element ids, so a file that has drifted — a service removed
+ *    since the last `loam subsystem sync` — would be a parse error, and a parse
+ *    error in one project document blanks the model for all of them. A fleet
+ *    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.
+ */
+import { readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+/**
+ * Every `.likec4` file under `dir`, recursively, minus `skip`, in a stable
+ * order.
+ *
+ * Sorted because it decides the staging order and therefore nothing at all —
+ * LikeC4 merges a project regardless — but a stable list makes a failure
+ * reproducible and a diff of one readable. A directory that does not exist is
+ * an empty list, never a throw: a fleet with no `architecture/` is a fleet with
+ * nothing to load, which is already `landscape.missing`'s question, not this
+ * function's.
+ */
+export async function architectureDocuments(dir, skip = []) {
+    const excluded = new Set(skip.map((path) => resolve(path)));
+    const found = [];
+    const walk = async (at) => {
+        let entries;
+        try {
+            entries = await readdir(at, { withFileTypes: true });
+        }
+        catch {
+            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)))
+                found.push(path);
+        }
+    };
+    await walk(resolve(dir));
+    return found.sort();
+}
+//# sourceMappingURL=documents.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"documents.js","sourceRoot":"","sources":["../../../../src/core/c4/project/documents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;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\" — `likec4.config.json` scopes the root\n * LikeC4 project to everything but `services/**` and `features/**`. loam's\n * answer is all of them EXCEPT the generated `architecture/subsystems.likec4`,\n * 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 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"]}

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

@@ -0,0 +1,183 @@
+/**
+ * One directory of `.likec4` documents, loaded as ONE LikeC4 project — the way
+ * the renderer already reads `architecture/`.
+ *
+ * A package of its own rather than more of `../workspace.ts`, and the seam is
+ * the isolation rule, not the line count. That module stages every document as
+ * its own single-file project ON PURPOSE, so an author-written `import` can
+ * never resolve against a sibling; this one does the opposite deliberately, for
+ * the set of documents that are meant to see each other. Two loaders with
+ * opposite contracts should not share a file: the next reader has to be able to
+ * tell at a glance which one they are looking at.
+ */
+import { randomBytes } from "node:crypto";
+import { copyFile, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { LikeC4 } from "likec4";
+import { inOrder } from "../../kernel/concurrency.js";
+import { flattenModel } from "../likec4.js";
+import { readDynamicViews } from "../parsed/dynamic-views.js";
+import { readSpecification } from "../parsed/specification.js";
+import { readViewIds } from "../parsed/view-ids.js";
+/**
+ * Stage a set of documents as ONE project, mirroring their paths relative to
+ * `base`.
+ *
+ * The relative structure is preserved rather than flattened to basenames, and
+ * that is load-bearing twice over: two use cases named `checkout.likec4` in
+ * different subdirectories would overwrite each other on copy, and LikeC4
+ * reports a view's `sourcePath` relative to the project root — so flattening
+ * would make every finding name a file the author cannot find.
+ */
+async function stageProject(root, base, targets) {
+    const project = `arch_${randomBytes(8).toString("hex")}`;
+    const folder = join(root, project);
+    await mkdir(folder, { recursive: true });
+    await writeFile(join(folder, "likec4.config.json"), JSON.stringify({ name: project }), "utf8");
+    // rel -> real path, so an error carrying the staged path can be handed back
+    // spelled the way the author wrote it.
+    const byRel = new Map();
+    await inOrder(targets, async (path) => {
+        const rel = relative(base, path).split(/[\\/]/).join("/");
+        const dest = join(folder, ...rel.split("/"));
+        try {
+            await mkdir(dirname(dest), { recursive: true });
+            await copyFile(path, dest);
+            byRel.set(rel, path);
+        }
+        catch {
+            // Dropped, exactly as `stage` drops one: the caller's ordinary per-path
+            // load owns the error, and a project missing one document still answers
+            // about the rest.
+        }
+        return null;
+    });
+    return byRel;
+}
+/**
+ * Load a directory of `.likec4` documents as ONE LikeC4 project — the way the
+ * renderer already reads `architecture/`, and the only way a document that
+ * declares views over ANOTHER file's elements can be read at all.
+ *
+ * Measured at the 1.59.2 pin: a views-only `usecases/checkout.likec4` parsed
+ * alone is five errors (unresolved tag, unresolved elements); the same file
+ * beside its landscape in one project is zero, and each view comes back with
+ * its own `sourcePath`. That is the whole reason this function exists — a use
+ * case lives in a file of its own, and `loadBatch`'s one-project-per-document
+ * isolation makes such a file unreadable by construction.
+ *
+ * Two rules the caller must know, because both invert what holds elsewhere:
+ *
+ *  - **Exactly one document in the set declares the `specification` block.**
+ *    Every `.likec4` file loam parses alone must declare its own; inside one
+ *    project a second declaration is a duplicate error blamed on BOTH files
+ *    (measured).
+ *  - **Errors are per document, but the MODEL is all-or-nothing.** A typo in
+ *    one file is attributed to that file — so the finding names it, which is
+ *    better than today, where a use case in the landscape would blame the
+ *    landscape — but loam's standing rule is that errors mean no model, and
+ *    here the model is the project's. `clean` says which case the caller is in.
+ *
+ * The generated `architecture/subsystems.likec4` must NOT be in `targets`:
+ * docs/DESIGN.md rule 26 keeps it a byte compare, and a stale one whose
+ * `include` names a removed element would otherwise be a parse error that
+ * blanks the whole fleet map.
+ */
+export async function loadProject(base, paths) {
+    const empty = (errors, clean) => ({
+        errors,
+        clean,
+        elements: [],
+        relationships: [],
+        views: [],
+        viewIds: [],
+    });
+    const targets = [...new Set(paths.map((path) => resolve(path)))];
+    if (targets.length === 0)
+        return empty(new Map(), true);
+    const root = await mkdtemp(join(tmpdir(), "loam-c4-"));
+    try {
+        const byRel = await stageProject(root, resolve(base), targets);
+        if (byRel.size === 0)
+            return empty(new Map(), true);
+        const likec4 = await LikeC4.fromWorkspace(root, { logger: false });
+        try {
+            const errors = groupProjectErrors(likec4, byRel);
+            if (errors.size > 0)
+                return empty(errors, false);
+            const model = (await likec4.parsedModel());
+            return {
+                errors,
+                clean: true,
+                specification: readSpecification(model.specification),
+                views: readDynamicViews(model),
+                viewIds: readViewIds(model),
+                ...flattenModel(model),
+            };
+        }
+        finally {
+            await likec4.dispose();
+        }
+    }
+    finally {
+        await rm(root, { recursive: true, force: true });
+    }
+}
+/**
+ * `getErrors()` split per DOCUMENT inside one project, each error's
+ * `sourceFsPath` rewritten to the document's real absolute path.
+ *
+ * `groupErrors` above keys on the project folder segment, which cannot work
+ * here — every document shares one project. This keys on the staged relative
+ * path instead, longest first so `usecases/checkout.likec4` is matched before a
+ * hypothetical `checkout.likec4` at the root. An error nobody can attribute
+ * throws for the same reason it does there: a dropped error grades its document
+ * clean, which is failing open in the fleet gate.
+ */
+function groupProjectErrors(likec4, byRel) {
+    const rels = [...byRel.keys()].sort((a, b) => b.length - a.length);
+    const grouped = new Map();
+    for (const err of likec4.getErrors()) {
+        const spelled = err.sourceFsPath.split(/[\\/]/).join("/");
+        const rel = rels.find((candidate) => spelled.endsWith(`/${candidate}`) || spelled === candidate);
+        if (rel === undefined) {
+            throw new Error(`unattributable LikeC4 error in project workspace: ${err.message}`);
+        }
+        const real = byRel.get(rel);
+        const list = grouped.get(real) ?? [];
+        list.push({ ...err, sourceFsPath: real });
+        grouped.set(real, list);
+    }
+    return grouped;
+}
+/**
+ * A `ProjectDoc` in the shape every existing landscape reader already takes.
+ *
+ * The per-file error map flattens into one list, which loses nothing: each
+ * error still carries the real path of the document that raised it, so a
+ * finding can name the file even though the list is flat. Sorted by that path
+ * so a project with two broken documents reports them in a stable order —
+ * `getErrors()` returns whatever order the workspace scan produced.
+ *
+ * The model travels only when the project is clean, which is loam's standing
+ * rule (`errors mean no model`) applied at project altitude: a use-case file
+ * with an unresolved element leaves the landscape unusable, and pretending
+ * otherwise would grade a fleet against half a map.
+ */
+export function asLoadedDoc(doc) {
+    const errors = [...doc.errors]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .flatMap(([, list]) => list);
+    if (!doc.clean)
+        return { errors, elements: [], relationships: [] };
+    return {
+        errors,
+        ...(doc.specification === undefined ? {} : { specification: doc.specification }),
+        views: doc.views,
+        viewIds: doc.viewIds,
+        elements: doc.elements,
+        relationships: doc.relationships,
+    };
+}
+//# sourceMappingURL=load.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../../../src/core/c4/project/load.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One directory of `.likec4` documents, loaded as ONE LikeC4 project — the way\n * the renderer already reads `architecture/`.\n *\n * A package of its own rather than more of `../workspace.ts`, and the seam is\n * the isolation rule, not the line count. That module stages every document as\n * its own single-file project ON PURPOSE, so an author-written `import` can\n * never resolve against a sibling; this one does the opposite deliberately, for\n * the set of documents that are meant to see each other. Two loaders with\n * opposite contracts should not share a file: the next reader has to be able to\n * tell at a glance which one they are looking at.\n */\nimport { randomBytes } from \"node:crypto\";\nimport { copyFile, mkdir, mkdtemp, rm, writeFile } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { dirname, join, relative, resolve } from \"node:path\";\nimport { LikeC4 } from \"likec4\";\nimport { inOrder } from \"../../kernel/concurrency.js\";\nimport { flattenModel, type Elem, type LikeC4Error, type LoadedDoc, type ReadableModel, type Rel } from \"../likec4.js\";\nimport { readDynamicViews, type ParsedView } from \"../parsed/dynamic-views.js\";\nimport { readSpecification, type DocSpecification } from \"../parsed/specification.js\";\nimport { readViewIds, type ViewIdClaim } from \"../parsed/view-ids.js\";\n\n/** A directory of `.likec4` documents loaded as one LikeC4 project. */\nexport interface ProjectDoc {\n  /** Errors by the REAL absolute path of the document that raised them. */\n  errors: Map<string, LikeC4Error[]>;\n  /** True when no document in the project raised one — loam's \"errors mean no model\" gate. */\n  clean: boolean;\n  elements: Elem[];\n  relationships: Rel[];\n  specification?: DocSpecification;\n  /** Every dynamic view the project declares, each carrying the file it is written in. */\n  views: ParsedView[];\n  /** Every authored view id the project claims, each with its file. */\n  viewIds: ViewIdClaim[];\n}\n\n/**\n * Stage a set of documents as ONE project, mirroring their paths relative to\n * `base`.\n *\n * The relative structure is preserved rather than flattened to basenames, and\n * that is load-bearing twice over: two use cases named `checkout.likec4` in\n * different subdirectories would overwrite each other on copy, and LikeC4\n * reports a view's `sourcePath` relative to the project root — so flattening\n * would make every finding name a file the author cannot find.\n */\nasync function stageProject(root: string, base: string, targets: string[]): Promise<Map<string, string>> {\n  const project = `arch_${randomBytes(8).toString(\"hex\")}`;\n  const folder = join(root, project);\n  await mkdir(folder, { recursive: true });\n  await writeFile(join(folder, \"likec4.config.json\"), JSON.stringify({ name: project }), \"utf8\");\n  // rel -> real path, so an error carrying the staged path can be handed back\n  // spelled the way the author wrote it.\n  const byRel = new Map<string, string>();\n  await inOrder(targets, async (path) => {\n    const rel = relative(base, path).split(/[\\\\/]/).join(\"/\");\n    const dest = join(folder, ...rel.split(\"/\"));\n    try {\n      await mkdir(dirname(dest), { recursive: true });\n      await copyFile(path, dest);\n      byRel.set(rel, path);\n    } catch {\n      // Dropped, exactly as `stage` drops one: the caller's ordinary per-path\n      // load owns the error, and a project missing one document still answers\n      // about the rest.\n    }\n    return null;\n  });\n  return byRel;\n}\n\n/**\n * Load a directory of `.likec4` documents as ONE LikeC4 project — the way the\n * renderer already reads `architecture/`, and the only way a document that\n * declares views over ANOTHER file's elements can be read at all.\n *\n * Measured at the 1.59.2 pin: a views-only `usecases/checkout.likec4` parsed\n * alone is five errors (unresolved tag, unresolved elements); the same file\n * beside its landscape in one project is zero, and each view comes back with\n * its own `sourcePath`. That is the whole reason this function exists — a use\n * case lives in a file of its own, and `loadBatch`'s one-project-per-document\n * isolation makes such a file unreadable by construction.\n *\n * Two rules the caller must know, because both invert what holds elsewhere:\n *\n *  - **Exactly one document in the set declares the `specification` block.**\n *    Every `.likec4` file loam parses alone must declare its own; inside one\n *    project a second declaration is a duplicate error blamed on BOTH files\n *    (measured).\n *  - **Errors are per document, but the MODEL is all-or-nothing.** A typo in\n *    one file is attributed to that file — so the finding names it, which is\n *    better than today, where a use case in the landscape would blame the\n *    landscape — but loam's standing rule is that errors mean no model, and\n *    here the model is the project's. `clean` says which case the caller is in.\n *\n * The generated `architecture/subsystems.likec4` must NOT be in `targets`:\n * docs/DESIGN.md rule 26 keeps it a byte compare, and a stale one whose\n * `include` names a removed element would otherwise be a parse error that\n * blanks the whole fleet map.\n */\nexport async function loadProject(base: string, paths: string[]): Promise<ProjectDoc> {\n  const empty = (errors: Map<string, LikeC4Error[]>, clean: boolean): ProjectDoc => ({\n    errors,\n    clean,\n    elements: [],\n    relationships: [],\n    views: [],\n    viewIds: [],\n  });\n  const targets = [...new Set(paths.map((path) => resolve(path)))];\n  if (targets.length === 0) return empty(new Map(), true);\n  const root = await mkdtemp(join(tmpdir(), \"loam-c4-\"));\n  try {\n    const byRel = await stageProject(root, resolve(base), targets);\n    if (byRel.size === 0) return empty(new Map(), true);\n    const likec4 = await LikeC4.fromWorkspace(root, { logger: false });\n    try {\n      const errors = groupProjectErrors(likec4, byRel);\n      if (errors.size > 0) return empty(errors, false);\n      const model = (await likec4.parsedModel()) as ReadableModel;\n      return {\n        errors,\n        clean: true,\n        specification: readSpecification(model.specification),\n        views: readDynamicViews(model),\n        viewIds: readViewIds(model),\n        ...flattenModel(model),\n      };\n    } finally {\n      await likec4.dispose();\n    }\n  } finally {\n    await rm(root, { recursive: true, force: true });\n  }\n}\n\n/**\n * `getErrors()` split per DOCUMENT inside one project, each error's\n * `sourceFsPath` rewritten to the document's real absolute path.\n *\n * `groupErrors` above keys on the project folder segment, which cannot work\n * here — every document shares one project. This keys on the staged relative\n * path instead, longest first so `usecases/checkout.likec4` is matched before a\n * hypothetical `checkout.likec4` at the root. An error nobody can attribute\n * throws for the same reason it does there: a dropped error grades its document\n * clean, which is failing open in the fleet gate.\n */\nfunction groupProjectErrors(likec4: LikeC4, byRel: Map<string, string>): Map<string, LikeC4Error[]> {\n  const rels = [...byRel.keys()].sort((a, b) => b.length - a.length);\n  const grouped = new Map<string, LikeC4Error[]>();\n  for (const err of likec4.getErrors()) {\n    const spelled = err.sourceFsPath.split(/[\\\\/]/).join(\"/\");\n    const rel = rels.find((candidate) => spelled.endsWith(`/${candidate}`) || spelled === candidate);\n    if (rel === undefined) {\n      throw new Error(`unattributable LikeC4 error in project workspace: ${err.message}`);\n    }\n    const real = byRel.get(rel)!;\n    const list = grouped.get(real) ?? [];\n    list.push({ ...err, sourceFsPath: real });\n    grouped.set(real, list);\n  }\n  return grouped;\n}\n\n/**\n * A `ProjectDoc` in the shape every existing landscape reader already takes.\n *\n * The per-file error map flattens into one list, which loses nothing: each\n * error still carries the real path of the document that raised it, so a\n * finding can name the file even though the list is flat. Sorted by that path\n * so a project with two broken documents reports them in a stable order —\n * `getErrors()` returns whatever order the workspace scan produced.\n *\n * The model travels only when the project is clean, which is loam's standing\n * rule (`errors mean no model`) applied at project altitude: a use-case file\n * with an unresolved element leaves the landscape unusable, and pretending\n * otherwise would grade a fleet against half a map.\n */\nexport function asLoadedDoc(doc: ProjectDoc): LoadedDoc {\n  const errors = [...doc.errors]\n    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))\n    .flatMap(([, list]) => list);\n  if (!doc.clean) return { errors, elements: [], relationships: [] };\n  return {\n    errors,\n    ...(doc.specification === undefined ? {} : { specification: doc.specification }),\n    views: doc.views,\n    viewIds: doc.viewIds,\n    elements: doc.elements,\n    relationships: doc.relationships,\n  };\n}\n"]}