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

package/dist/core/c4/parsed/dynamic-views.js

@@ -0,0 +1,132 @@
+/**
+ * The `dynamic view`s a document DECLARES, read off LikeC4's parsed model.
+ *
+ * This is the only module in loam permitted to touch `$data`, and
+ * `scripts/arch-check.mjs` enforces that rather than trusting it (docs/DESIGN.md
+ * rule 26). The confinement is the point: `$data` is public and typed but thinly
+ * documented for this use, so an upstream shape change has a blast radius of one
+ * file, and `test/likec4-view-shape.test.ts` is the tripwire that fires before
+ * the change reaches a check.
+ *
+ * It takes the WHOLE model as `unknown` rather than a `$data` slice handed in by
+ * its caller, and that is not squeamishness — naming `$data` in `../likec4.ts`
+ * would violate the containment scan this module exists behind. Callers pass the
+ * model; every assumption about LikeC4's record shape lives here.
+ *
+ * Everything is defensive, in the same posture as `./specification.ts`: a shape
+ * this reader cannot make sense of degrades to ZERO views, never to a wrong one
+ * and never to a throw inside a validate run. That asymmetry is deliberate and
+ * is loam's standing rule for a suspended axis — a check with no views to grade
+ * reports could-not-look, while a check fed a half-read view would report
+ * nothing-wrong about a flow it never saw.
+ */
+import { descText } from "./values.js";
+/** A record, or nothing — `v` is `unknown` off an untyped parse. */
+function record(v) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+}
+/** The value at `key`, when it is a non-empty string. */
+function str(rec, key) {
+    const v = rec[key];
+    return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+/**
+ * Every leaf step under `entries`, depth-first in author order.
+ *
+ * Steps NEST: a `loop 'until accepted' { ... }` arrives as an entry with
+ * `_type: "loop"`, a title, its own `steps[]`, and NO endpoints and NO `astPath`
+ * of its own (measured). A walk that treated every entry as a hop would read the
+ * bracket as a step and then fail to find a relationship backing it — inventing
+ * a finding out of a grouping the author drew for legibility.
+ *
+ * The test is structural rather than a list of group keywords (`loop`, `par`,
+ * ...): an entry with a nested `steps` array is a group whatever LikeC4 calls
+ * it, and an entry with two string endpoints is a hop. A future group kind
+ * therefore flattens correctly on the day it ships instead of on the day
+ * somebody notices.
+ */
+function leaves(entries, out) {
+    if (!Array.isArray(entries))
+        return;
+    for (const entry of entries) {
+        const rec = record(entry);
+        if (!rec)
+            continue;
+        if (Array.isArray(rec["steps"])) {
+            leaves(rec["steps"], out);
+            continue;
+        }
+        if (typeof rec["source"] === "string" && typeof rec["target"] === "string")
+            out.push(rec);
+    }
+}
+/** One leaf entry as a `ParsedStep`. Every leaf yields one; nothing is dropped. */
+function step(rec, ordinal) {
+    const astPath = str(rec, "astPath");
+    const title = str(rec, "title");
+    const notes = descText(rec["notes"]);
+    return {
+        ordinal,
+        source: rec["source"],
+        target: rec["target"],
+        ...(title === undefined ? {} : { title }),
+        ...(notes === undefined ? {} : { notes }),
+        // Present-and-true is the only truthy form LikeC4 emits; absent means
+        // forward. Read as a boolean rather than carried as `true | undefined` so a
+        // caller cannot accidentally test `=== false` against a key that is never
+        // written.
+        isBackward: rec["isBackward"] === true,
+        ...(astPath === undefined ? {} : { astPath }),
+    };
+}
+/**
+ * The dynamic views one parsed document declares, in the record's own order.
+ *
+ * `model` is the awaited `parsedModel()` result. The `await` matters and is the
+ * mistake every draft of this made: `$data` is `undefined` on the unresolved
+ * promise, so a reader handed the promise reports a document with views as
+ * having none — a silent zero, which is the one wrong answer this module is
+ * written to avoid.
+ *
+ * Two entries are dropped on the way out, for different reasons:
+ *
+ *  - Anything whose `_type` is not `"dynamic"`. LikeC4 synthesises an `index`
+ *    view into EVERY document, including one with no `views` block at all
+ *    (measured), so reporting element views would be reporting a fiction the
+ *    author never wrote. A census that must see authored element views wants the
+ *    other filter rule 26 states — `sourcePath !== undefined` — and must not
+ *    reuse this function to get it.
+ *  - Anything with no `id`. There is nothing to name in a finding, and a view
+ *    loam cannot name is a view it cannot ask anybody to fix.
+ */
+export function readDynamicViews(model) {
+    const data = record(record(model)?.["$data"]);
+    const views = record(data?.["views"]);
+    if (!views)
+        return [];
+    const out = [];
+    for (const raw of Object.values(views)) {
+        const rec = record(raw);
+        if (!rec || rec["_type"] !== "dynamic")
+            continue;
+        const id = str(rec, "id");
+        if (id === undefined)
+            continue;
+        const found = [];
+        leaves(rec["steps"], found);
+        const steps = found.map((leaf, i) => step(leaf, i + 1));
+        const title = str(rec, "title");
+        const description = descText(rec["description"]);
+        const sourcePath = str(rec, "sourcePath");
+        out.push({
+            id,
+            ...(sourcePath === undefined ? {} : { sourcePath }),
+            tags: Array.isArray(rec["tags"]) ? rec["tags"].filter((t) => typeof t === "string") : [],
+            ...(title === undefined ? {} : { title }),
+            ...(description === undefined ? {} : { description }),
+            steps,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=dynamic-views.js.map

package/dist/core/c4/parsed/dynamic-views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-views.js","sourceRoot":"","sources":["../../../../src/core/c4/parsed/dynamic-views.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAsFvC,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,yDAAyD;AACzD,SAAS,GAAG,CAAC,GAA4B,EAAE,GAAW;IACpD,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,MAAM,CAAC,OAAgB,EAAE,GAA8B;IAC9D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO;IACpC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;YAChC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC;YAC1B,SAAS;QACX,CAAC;QACD,IAAI,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,QAAQ;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5F,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,SAAS,IAAI,CAAC,GAA4B,EAAE,OAAe;IACzD,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACrC,OAAO;QACL,OAAO;QACP,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAW;QAC/B,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAW;QAC/B,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;QACzC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;QACzC,sEAAsE;QACtE,4EAA4E;QAC5E,0EAA0E;QAC1E,WAAW;QACX,UAAU,EAAE,GAAG,CAAC,YAAY,CAAC,KAAK,IAAI;QACtC,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAEtB,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,SAAS;YAAE,SAAS;QACjD,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1B,IAAI,EAAE,KAAK,SAAS;YAAE,SAAS;QAE/B,MAAM,KAAK,GAA8B,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC;QAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAExD,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAChC,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;QACjD,MAAM,UAAU,GAAG,GAAG,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QAC1C,GAAG,CAAC,IAAI,CAAC;YACP,EAAE;YACF,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC;YACnD,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE;YACrG,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;YACzC,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;YACrD,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["/**\n * The `dynamic view`s a document DECLARES, read off LikeC4's parsed model.\n *\n * This is the only module in loam permitted to touch `$data`, and\n * `scripts/arch-check.mjs` enforces that rather than trusting it (docs/DESIGN.md\n * rule 26). The confinement is the point: `$data` is public and typed but thinly\n * documented for this use, so an upstream shape change has a blast radius of one\n * file, and `test/likec4-view-shape.test.ts` is the tripwire that fires before\n * the change reaches a check.\n *\n * It takes the WHOLE model as `unknown` rather than a `$data` slice handed in by\n * its caller, and that is not squeamishness — naming `$data` in `../likec4.ts`\n * would violate the containment scan this module exists behind. Callers pass the\n * model; every assumption about LikeC4's record shape lives here.\n *\n * Everything is defensive, in the same posture as `./specification.ts`: a shape\n * this reader cannot make sense of degrades to ZERO views, never to a wrong one\n * and never to a throw inside a validate run. That asymmetry is deliberate and\n * is loam's standing rule for a suspended axis — a check with no views to grade\n * reports could-not-look, while a check fed a half-read view would report\n * nothing-wrong about a flow it never saw.\n */\nimport { descText } from \"./values.js\";\n\n/** One hop of a declared use case: an ordered edge between two elements. */\nexport interface ParsedStep {\n  /**\n   * 1-based pre-order position among the view's LEAF steps — what lets a finding\n   * say \"step 4 of Checkout\". Group wrappers do not consume an ordinal: a\n   * `loop` is a bracket around hops, not a hop, and counting it would shift\n   * every number after it away from what the author sees on the diagram.\n   */\n  ordinal: number;\n  /**\n   * The step's endpoints, ALREADY ORIENTED — see `isBackward`. Dotted FQN\n   * strings naming elements, never relationship ids: a step says who talks to\n   * whom, and which relationship backs that is a join loam performs later.\n   */\n  source: string;\n  target: string;\n  /** The step's label, absent when the author wrote none. */\n  title?: string;\n  /** A `notes '...'` block on the step, decoded from LikeC4's rich-text shape. */\n  notes?: string;\n  /**\n   * True when the author wrote the hop as a reply — `a <- b` rather than\n   * `b -> a`. LOAD-BEARING, and measured: LikeC4 records `a <- b 'reply'` as\n   * `{source: b, target: a, isBackward: true}` — already reversed AND flagged —\n   * while a forward step carries no such key at all. `source`/`target` above are\n   * therefore correct as they stand and need no flipping; the flag is carried so\n   * a check can tell a return hop from a call, and so a message naming the\n   * failing step can suggest the `<-` spelling to an author who wrote the arrow\n   * the long way round.\n   */\n  isBackward: boolean;\n  /**\n   * LikeC4's own path to the step inside the view (`/steps@1/steps@0`), carried\n   * verbatim. It is the only stable handle on a nested step — two hops between\n   * the same pair inside different `loop` blocks are otherwise indistinguishable\n   * — and it is message text, never identity: nothing joins on it.\n   *\n   * OPTIONAL, and that is a deliberate refusal to make it load-bearing. Every\n   * leaf carries one at the 1.59.2 pin, so requiring it would look free — and\n   * would mean that an upstream release which stopped emitting it turned every\n   * use case in the fleet into a view with zero steps. That is the silent wrong\n   * answer this module exists to avoid: a hop loam cannot cite is still a hop it\n   * must grade.\n   */\n  astPath?: string;\n}\n\n/** One declared `dynamic view`, flattened to what rule 26 permits reading. */\nexport interface ParsedView {\n  id: string;\n  /**\n   * The name LikeC4 knows the document by, and it is only a PATH under\n   * `loadProject`: there it is relative to the project root, so\n   * `usecases/checkout.likec4` inside `architecture/`. Under the per-file\n   * loaders it is whatever that loader called the document — `source.c4` for\n   * `loadSource`, the basename for `loadBatch` — because there is no project\n   * for it to be relative to.\n   *\n   * So: name a file with it only when the views came from `loadProject`. That\n   * is the only reader that has one, which is also the only reader that needs\n   * one — a use case lives in a file of its own now, and a finding that cannot\n   * name that file sends its reader to the landscape to look for something\n   * that is not there.\n   *\n   * Absent for anything LikeC4 synthesized rather than read off a file, which\n   * is how the census reader tells the two apart.\n   */\n  sourcePath?: string;\n  /**\n   * The view's declared tags, `[]` when it declares none. Normalized here\n   * because LikeC4 reads an untagged view's tags as `null`, and a caller\n   * testing `.length` on that would throw inside a validate run.\n   *\n   * Tags live on the VIEW and nowhere else: a step cannot carry tags, and\n   * `metadata` on a step is a hard parse error. That is measured, and it is why\n   * a use case is opted in as a whole rather than hop by hop.\n   */\n  tags: string[];\n  title?: string;\n  description?: string;\n  /** The declared hops, in author order, groups flattened away. */\n  steps: ParsedStep[];\n}\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/** The value at `key`, when it is a non-empty string. */\nfunction str(rec: Record<string, unknown>, key: string): string | undefined {\n  const v = rec[key];\n  return typeof v === \"string\" && v.length > 0 ? v : undefined;\n}\n\n/**\n * Every leaf step under `entries`, depth-first in author order.\n *\n * Steps NEST: a `loop 'until accepted' { ... }` arrives as an entry with\n * `_type: \"loop\"`, a title, its own `steps[]`, and NO endpoints and NO `astPath`\n * of its own (measured). A walk that treated every entry as a hop would read the\n * bracket as a step and then fail to find a relationship backing it — inventing\n * a finding out of a grouping the author drew for legibility.\n *\n * The test is structural rather than a list of group keywords (`loop`, `par`,\n * ...): an entry with a nested `steps` array is a group whatever LikeC4 calls\n * it, and an entry with two string endpoints is a hop. A future group kind\n * therefore flattens correctly on the day it ships instead of on the day\n * somebody notices.\n */\nfunction leaves(entries: unknown, out: Record<string, unknown>[]): void {\n  if (!Array.isArray(entries)) return;\n  for (const entry of entries) {\n    const rec = record(entry);\n    if (!rec) continue;\n    if (Array.isArray(rec[\"steps\"])) {\n      leaves(rec[\"steps\"], out);\n      continue;\n    }\n    if (typeof rec[\"source\"] === \"string\" && typeof rec[\"target\"] === \"string\") out.push(rec);\n  }\n}\n\n/** One leaf entry as a `ParsedStep`. Every leaf yields one; nothing is dropped. */\nfunction step(rec: Record<string, unknown>, ordinal: number): ParsedStep {\n  const astPath = str(rec, \"astPath\");\n  const title = str(rec, \"title\");\n  const notes = descText(rec[\"notes\"]);\n  return {\n    ordinal,\n    source: rec[\"source\"] as string,\n    target: rec[\"target\"] as string,\n    ...(title === undefined ? {} : { title }),\n    ...(notes === undefined ? {} : { notes }),\n    // Present-and-true is the only truthy form LikeC4 emits; absent means\n    // forward. Read as a boolean rather than carried as `true | undefined` so a\n    // caller cannot accidentally test `=== false` against a key that is never\n    // written.\n    isBackward: rec[\"isBackward\"] === true,\n    ...(astPath === undefined ? {} : { astPath }),\n  };\n}\n\n/**\n * The dynamic views one parsed document declares, in the record's own order.\n *\n * `model` is the awaited `parsedModel()` result. The `await` matters and is the\n * mistake every draft of this made: `$data` is `undefined` on the unresolved\n * promise, so a reader handed the promise reports a document with views as\n * having none — a silent zero, which is the one wrong answer this module is\n * written to avoid.\n *\n * Two entries are dropped on the way out, for different reasons:\n *\n *  - Anything whose `_type` is not `\"dynamic\"`. LikeC4 synthesises an `index`\n *    view into EVERY document, including one with no `views` block at all\n *    (measured), so reporting element views would be reporting a fiction the\n *    author never wrote. A census that must see authored element views wants the\n *    other filter rule 26 states — `sourcePath !== undefined` — and must not\n *    reuse this function to get it.\n *  - Anything with no `id`. There is nothing to name in a finding, and a view\n *    loam cannot name is a view it cannot ask anybody to fix.\n */\nexport function readDynamicViews(model: unknown): ParsedView[] {\n  const data = record(record(model)?.[\"$data\"]);\n  const views = record(data?.[\"views\"]);\n  if (!views) return [];\n\n  const out: ParsedView[] = [];\n  for (const raw of Object.values(views)) {\n    const rec = record(raw);\n    if (!rec || rec[\"_type\"] !== \"dynamic\") continue;\n    const id = str(rec, \"id\");\n    if (id === undefined) continue;\n\n    const found: Record<string, unknown>[] = [];\n    leaves(rec[\"steps\"], found);\n    const steps = found.map((leaf, i) => step(leaf, i + 1));\n\n    const title = str(rec, \"title\");\n    const description = descText(rec[\"description\"]);\n    const sourcePath = str(rec, \"sourcePath\");\n    out.push({\n      id,\n      ...(sourcePath === undefined ? {} : { sourcePath }),\n      tags: Array.isArray(rec[\"tags\"]) ? rec[\"tags\"].filter((t): t is string => typeof t === \"string\") : [],\n      ...(title === undefined ? {} : { title }),\n      ...(description === undefined ? {} : { description }),\n      steps,\n    });\n  }\n  return out;\n}\n"]}

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"]}