@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

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

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

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

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

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

@@ -0,0 +1,160 @@
+/**
+ * The DEPLOYMENT model a document declares — which physical nodes exist, which
+ * containers are instanced where, and what talks to what across them.
+ *
+ * A `deployment { }` block has been legal in a docs repo since LikeC4 could
+ * parse one, and until this reader existed loam saw none of it. The parser
+ * resolved every `instanceOf` — so a container renamed out from under a
+ * deployment node already failed the gate — and after that no requirement could
+ * name a node, no `#obl-` tag on a datacenter was graded, and the context pack
+ * an agent implements from did not mention topology at all. Integrity held at
+ * the level of syntax and was absent at the level of requirements. ROADMAP's
+ * deployment axis and `meta/docs/features/FEAT-1-the-deployment-axis/` are the
+ * item and the specification; this module is its first half.
+ *
+ * ## Why this is a `parsed/` reader and not a package of its own
+ *
+ * It is the same job the three modules beside it do: take one corner of
+ * LikeC4's parse output and hand back a loam-neutral record, defensively, with
+ * its shape assumptions owned outright. `readSpecification`, `readDynamicViews`
+ * and `readViewIds` are all called on the line above `flattenModel(model)` in
+ * each of loam's three loaders, and so is this. FEAT-1's delta said
+ * `src/core/c4/deploy/`; a package holding this alone would be a directory
+ * pretending to be a subject (docs/DESIGN.md), and the delta was corrected
+ * rather than the code bent to it — which is what an unarchived feature is for.
+ *
+ * **`parsed/` is still AT its five-file limit.** The global style-id census
+ * rode into `view-ids.ts` because it IS that module's subject — one more
+ * table asked the same question — and the next reader that is not a census
+ * still needs the split first. The seam to split on is the one this file does
+ * not share: `dynamic-views.ts` and `view-ids.ts` read `$data`, this one and
+ * `specification.ts` read the model surface.
+ *
+ * ## What is read, and what is deliberately left
+ *
+ * Nodes, instances and relationships, with the ids, titles and tags each
+ * carries. MEASURED at the 1.59.2 pin, and every line of it needed measuring
+ * rather than assuming:
+ *
+ *  - `nodes()` returns deployment NODES only — an `instanceOf` is not among
+ *    them, which is why instances are a second list rather than a filter.
+ *  - an instance carries the LOGICAL element it deploys as `element.id`, and
+ *    that is the whole join back to the C4 model: `eu.a.dbA -> orders.db`.
+ *  - both nodes and instances carry `tags`, so `#obl-geo` on a datacenter is
+ *    readable — the fail-open case that made this an item.
+ *  - a relationship carries `tags` and `metadata` DIRECTLY (`r.metadata`, no
+ *    `$relationship` indirection), and both model stages return byte-identical
+ *    results, which is what lets `test/likec4-model-parity.test.ts` cover this
+ *    read with the substitution it already pins.
+ *  - a document with NO `deployment { }` block still returns a deployment
+ *    object whose three iterators are empty. Absent and empty are therefore the
+ *    same answer here, deliberately: no reader may distinguish "declares none"
+ *    from "could not be read", because the second is what the defensive returns
+ *    below produce and a fleet that draws no topology owes loam nothing.
+ *
+ * `metadata` is NOT carried on the records below, and neither is an instance's
+ * `kind`. Both are readable; no check reads them yet, and a field carried
+ * before a caller needs it is a field nobody notices going wrong. Add one with
+ * the check that consumes it.
+ */
+/** No topology — what an absent block and an unreadable one both come back as. */
+export const NO_DEPLOYMENT = { nodes: [], instances: [], relationships: [] };
+/** Is there anything here? The opt-in every deployment check is gated on. */
+export function hasDeployment(d) {
+    return d.nodes.length > 0 || d.instances.length > 0 || d.relationships.length > 0;
+}
+/** A record, or nothing — the parse surface hands back `unknown`. */
+function record(v) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+}
+/** An iterable produced by `name()`, or an empty one when the surface is not what we measured. */
+function iterate(source, name) {
+    const fn = source[name];
+    if (typeof fn !== "function")
+        return [];
+    try {
+        const out = fn.call(source);
+        // A generator satisfies this; so does an array. Anything else is a shape
+        // change upstream, and the honest answer to one is "no topology read".
+        return out !== null && typeof out === "object" && Symbol.iterator in out
+            ? [...out]
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** A string field, or the empty string — never `undefined` leaking into a record. */
+function str(o, key) {
+    const v = o[key];
+    return typeof v === "string" ? v : "";
+}
+/** Tags as loam models them: a plain array of strings, always present. */
+function tags(o) {
+    const v = o["tags"];
+    return Array.isArray(v) ? v.filter((t) => typeof t === "string") : [];
+}
+/**
+ * Read the deployment model off an awaited `parsedModel()`.
+ *
+ * Defensive throughout, in the shape `readViewIds` established: an entry
+ * missing the one field that identifies it is DROPPED rather than reported with
+ * a hole, and a surface that is not what was measured yields an empty model
+ * instead of throwing. A check that cannot see the topology must say
+ * could-not-look through its own silence, never fail the fleet's parse.
+ */
+export function readDeployment(model) {
+    const root = record(model);
+    if (root === undefined)
+        return NO_DEPLOYMENT;
+    const deployment = record(root["deployment"]);
+    if (deployment === undefined)
+        return NO_DEPLOYMENT;
+    const nodes = [];
+    for (const raw of iterate(deployment, "nodes")) {
+        const n = record(raw);
+        if (n === undefined)
+            continue;
+        const id = str(n, "id");
+        if (id === "")
+            continue;
+        nodes.push({ id, kind: str(n, "kind"), title: str(n, "title"), tags: tags(n) });
+    }
+    const instances = [];
+    for (const raw of iterate(deployment, "instances")) {
+        const i = record(raw);
+        if (i === undefined)
+            continue;
+        const id = str(i, "id");
+        // The logical element is the whole point of the record. An instance whose
+        // element cannot be read joins to nothing, so reporting it would put a
+        // deployed thing on the map that no requirement could ever cover.
+        const element = record(i["element"]);
+        if (id === "" || element === undefined)
+            continue;
+        const elementId = str(element, "id");
+        if (elementId === "")
+            continue;
+        instances.push({ id, element: elementId, title: str(i, "title"), tags: tags(i) });
+    }
+    const relationships = [];
+    for (const raw of iterate(deployment, "relationships")) {
+        const r = record(raw);
+        if (r === undefined)
+            continue;
+        const source = record(r["source"]);
+        const target = record(r["target"]);
+        if (source === undefined || target === undefined)
+            continue;
+        const from = str(source, "id");
+        const to = str(target, "id");
+        if (from === "" || to === "")
+            continue;
+        // LikeC4 reports an untitled edge as `title: null` — normalized to the
+        // declared optional exactly as `flattenModel` does for the logical model.
+        const title = typeof r["title"] === "string" ? r["title"] : undefined;
+        relationships.push({ source: from, target: to, ...(title === undefined ? {} : { title }), tags: tags(r) });
+    }
+    return { nodes, instances, relationships };
+}
+//# sourceMappingURL=deployment.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deployment.js","sourceRoot":"","sources":["../../../../src/core/c4/parsed/deployment.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The DEPLOYMENT model a document declares — which physical nodes exist, which\n * containers are instanced where, and what talks to what across them.\n *\n * A `deployment { }` block has been legal in a docs repo since LikeC4 could\n * parse one, and until this reader existed loam saw none of it. The parser\n * resolved every `instanceOf` — so a container renamed out from under a\n * deployment node already failed the gate — and after that no requirement could\n * name a node, no `#obl-` tag on a datacenter was graded, and the context pack\n * an agent implements from did not mention topology at all. Integrity held at\n * the level of syntax and was absent at the level of requirements. ROADMAP's\n * deployment axis and `meta/docs/features/FEAT-1-the-deployment-axis/` are the\n * item and the specification; this module is its first half.\n *\n * ## Why this is a `parsed/` reader and not a package of its own\n *\n * It is the same job the three modules beside it do: take one corner of\n * LikeC4's parse output and hand back a loam-neutral record, defensively, with\n * its shape assumptions owned outright. `readSpecification`, `readDynamicViews`\n * and `readViewIds` are all called on the line above `flattenModel(model)` in\n * each of loam's three loaders, and so is this. FEAT-1's delta said\n * `src/core/c4/deploy/`; a package holding this alone would be a directory\n * pretending to be a subject (docs/DESIGN.md), and the delta was corrected\n * rather than the code bent to it — which is what an unarchived feature is for.\n *\n * **`parsed/` is still AT its five-file limit.** The global style-id census\n * rode into `view-ids.ts` because it IS that module's subject — one more\n * table asked the same question — and the next reader that is not a census\n * still needs the split first. The seam to split on is the one this file does\n * not share: `dynamic-views.ts` and `view-ids.ts` read `$data`, this one and\n * `specification.ts` read the model surface.\n *\n * ## What is read, and what is deliberately left\n *\n * Nodes, instances and relationships, with the ids, titles and tags each\n * carries. MEASURED at the 1.59.2 pin, and every line of it needed measuring\n * rather than assuming:\n *\n *  - `nodes()` returns deployment NODES only — an `instanceOf` is not among\n *    them, which is why instances are a second list rather than a filter.\n *  - an instance carries the LOGICAL element it deploys as `element.id`, and\n *    that is the whole join back to the C4 model: `eu.a.dbA -> orders.db`.\n *  - both nodes and instances carry `tags`, so `#obl-geo` on a datacenter is\n *    readable — the fail-open case that made this an item.\n *  - a relationship carries `tags` and `metadata` DIRECTLY (`r.metadata`, no\n *    `$relationship` indirection), and both model stages return byte-identical\n *    results, which is what lets `test/likec4-model-parity.test.ts` cover this\n *    read with the substitution it already pins.\n *  - a document with NO `deployment { }` block still returns a deployment\n *    object whose three iterators are empty. Absent and empty are therefore the\n *    same answer here, deliberately: no reader may distinguish \"declares none\"\n *    from \"could not be read\", because the second is what the defensive returns\n *    below produce and a fleet that draws no topology owes loam nothing.\n *\n * `metadata` is NOT carried on the records below, and neither is an instance's\n * `kind`. Both are readable; no check reads them yet, and a field carried\n * before a caller needs it is a field nobody notices going wrong. Add one with\n * the check that consumes it.\n */\n\n/** One deployment node — a region, a datacenter, a cluster; the kinds are the fleet's own. */\nexport interface DeployNode {\n  /** The dotted path LikeC4 gives it: `eu.dcA.k8sA`. */\n  id: string;\n  /** The `deploymentNode` kind the specification declares. */\n  kind: string;\n  title: string;\n  tags: string[];\n}\n\n/** One deployed instance of a logical element. */\nexport interface DeployInstance {\n  id: string;\n  /**\n   * The id of the C4 element this instance deploys — the join back to the\n   * logical model, and the only reason an instance is worth reading at all.\n   */\n  element: string;\n  title: string;\n  tags: string[];\n}\n\n/** One edge between deployment objects — replication, failover, a network hop. */\nexport interface DeployRel {\n  source: string;\n  target: string;\n  title?: string;\n  tags: string[];\n}\n\n/** A document's whole deployment model, flattened. */\nexport interface DeploymentModel {\n  nodes: DeployNode[];\n  instances: DeployInstance[];\n  relationships: DeployRel[];\n}\n\n/** No topology — what an absent block and an unreadable one both come back as. */\nexport const NO_DEPLOYMENT: DeploymentModel = { nodes: [], instances: [], relationships: [] };\n\n/** Is there anything here? The opt-in every deployment check is gated on. */\nexport function hasDeployment(d: DeploymentModel): boolean {\n  return d.nodes.length > 0 || d.instances.length > 0 || d.relationships.length > 0;\n}\n\n/** A record, or nothing — the parse surface hands back `unknown`. */\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/** An iterable produced by `name()`, or an empty one when the surface is not what we measured. */\nfunction iterate(source: Record<string, unknown>, name: string): unknown[] {\n  const fn = source[name];\n  if (typeof fn !== \"function\") return [];\n  try {\n    const out: unknown = (fn as () => unknown).call(source);\n    // A generator satisfies this; so does an array. Anything else is a shape\n    // change upstream, and the honest answer to one is \"no topology read\".\n    return out !== null && typeof out === \"object\" && Symbol.iterator in (out as object)\n      ? [...(out as Iterable<unknown>)]\n      : [];\n  } catch {\n    return [];\n  }\n}\n\n/** A string field, or the empty string — never `undefined` leaking into a record. */\nfunction str(o: Record<string, unknown>, key: string): string {\n  const v = o[key];\n  return typeof v === \"string\" ? v : \"\";\n}\n\n/** Tags as loam models them: a plain array of strings, always present. */\nfunction tags(o: Record<string, unknown>): string[] {\n  const v = o[\"tags\"];\n  return Array.isArray(v) ? v.filter((t): t is string => typeof t === \"string\") : [];\n}\n\n/**\n * Read the deployment model off an awaited `parsedModel()`.\n *\n * Defensive throughout, in the shape `readViewIds` established: an entry\n * missing the one field that identifies it is DROPPED rather than reported with\n * a hole, and a surface that is not what was measured yields an empty model\n * instead of throwing. A check that cannot see the topology must say\n * could-not-look through its own silence, never fail the fleet's parse.\n */\nexport function readDeployment(model: unknown): DeploymentModel {\n  const root = record(model);\n  if (root === undefined) return NO_DEPLOYMENT;\n  const deployment = record(root[\"deployment\"]);\n  if (deployment === undefined) return NO_DEPLOYMENT;\n\n  const nodes: DeployNode[] = [];\n  for (const raw of iterate(deployment, \"nodes\")) {\n    const n = record(raw);\n    if (n === undefined) continue;\n    const id = str(n, \"id\");\n    if (id === \"\") continue;\n    nodes.push({ id, kind: str(n, \"kind\"), title: str(n, \"title\"), tags: tags(n) });\n  }\n\n  const instances: DeployInstance[] = [];\n  for (const raw of iterate(deployment, \"instances\")) {\n    const i = record(raw);\n    if (i === undefined) continue;\n    const id = str(i, \"id\");\n    // The logical element is the whole point of the record. An instance whose\n    // element cannot be read joins to nothing, so reporting it would put a\n    // deployed thing on the map that no requirement could ever cover.\n    const element = record(i[\"element\"]);\n    if (id === \"\" || element === undefined) continue;\n    const elementId = str(element, \"id\");\n    if (elementId === \"\") continue;\n    instances.push({ id, element: elementId, title: str(i, \"title\"), tags: tags(i) });\n  }\n\n  const relationships: DeployRel[] = [];\n  for (const raw of iterate(deployment, \"relationships\")) {\n    const r = record(raw);\n    if (r === undefined) continue;\n    const source = record(r[\"source\"]);\n    const target = record(r[\"target\"]);\n    if (source === undefined || target === undefined) continue;\n    const from = str(source, \"id\");\n    const to = str(target, \"id\");\n    if (from === \"\" || to === \"\") continue;\n    // LikeC4 reports an untitled edge as `title: null` — normalized to the\n    // declared optional exactly as `flattenModel` does for the logical model.\n    const title = typeof r[\"title\"] === \"string\" ? r[\"title\"] : undefined;\n    relationships.push({ source: from, target: to, ...(title === undefined ? {} : { title }), tags: tags(r) });\n  }\n\n  return { nodes, instances, relationships };\n}\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"dynamic-views.js","sourceRoot":"","sources":["../../../../src/core/c4/parsed/dynamic-views.ts"],"names":[],"mappings":"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","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"]}
+{"version":3,"file":"dynamic-views.js","sourceRoot":"","sources":["../../../../src/core/c4/parsed/dynamic-views.ts"],"names":[],"mappings":"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","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  /**\n   * The step's label, absent when the author wrote none. Carried verbatim,\n   * because one join reads its opening characters: a title that opens with a\n   * candidate relationship's operation id or message name, set off by\n   * punctuation, picks that relationship where the map joins the pair by\n   * several (`pickedByTitle` in `../resolve/steps.ts`).\n   */\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/values.js

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

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

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

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

@@ -16,8 +16,17 @@
  * safer when each one owns its shape assumptions outright — the same reason
  * `./specification.ts` states.
  *
+ * Two censuses over one record now: view ids off `$data.views`, and since
+ * 2026-09-03 the global style ids off `$data.globals.styles` — the same
+ * question (which authored ids exist, for a collision or a reference) asked of
+ * a second corner, so the generated subsystem views can reference a style
+ * group only when the project actually declares it. The second rode into this
+ * module rather than a file of its own because `parsed/` sits AT its five-file
+ * cap and the census IS this module's subject; `./deployment.ts`'s banner
+ * records the seam the next non-census reader still needs.
+ *
  * Ids only, each with the file that claims it. What the view SHOWS stays
- * unread, in any document, forever.
+ * unread, in any document, forever — and so does what a style group SAYS.
  */
 /**
  * The shape LikeC4 mints for a view its author never named — `view of svc { }`
@@ -72,4 +81,33 @@ export function readViewIds(model) {
     }
     return out;
 }
+/**
+ * Every global style id the document declares, sorted.
+ *
+ * `$data.globals.styles` is keyed by id and holds one entry per `styleGroup`
+ * OR single-rule `style` declared under `global { }` — both forms land in the
+ * one table, measured at the 1.59.2 pin and pinned in
+ * test/likec4-view-shape.test.ts. Keys only: what a group SAYS — its targets
+ * and colours — is a rendering instruction, and docs/DESIGN.md rule 26 keeps
+ * loam out of those on purpose; the one consumer (the generated subsystem
+ * views) asks whether an id is declared, nothing more. Sorted so a document
+ * declaring two groups yields one order under every loader — the parity rule
+ * `readViewIds` states for the minted-id case, applied here to `Object.keys`
+ * order, which is the record's and not the author's.
+ *
+ * Defensive like everything here: a shape this cannot read is ZERO ids, so the
+ * generated views then reference nothing — the same file they rendered before
+ * the read existed, never a reference to a name loam guessed. That direction
+ * is the safe one: a missed declaration costs a palette, while an invented
+ * reference is a parse error that blanks the whole `architecture/` project in
+ * the renderer.
+ */
+export function readGlobalStyleIds(model) {
+    const styles = record(record(record(record(model)?.["$data"])?.["globals"])?.["styles"]);
+    if (!styles)
+        return [];
+    return Object.keys(styles)
+        .filter((id) => id.length > 0)
+        .sort();
+}
 //# sourceMappingURL=view-ids.js.map