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

package/dist/core/c4/likec4.js

@@ -1,11 +1,12 @@
 import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
 import { LikeC4 } from "likec4";
 import { declaredService } from "../kernel/ids/service.js";
 import { readDynamicViews } from "./parsed/dynamic-views.js";
 import { readGlobalStyleIds, readViewIds } from "./parsed/view-ids.js";
 import { readSpecification } from "./parsed/specification.js";
 import { readDeployment } from "./parsed/deployment.js";
-import { descText, metaKey } from "./parsed/values.js";
+import { compareRels, descText, metaKey } from "./parsed/values.js";
 /**
  * The one spelling of a diagnostic loam prints — `L<n>: <message>`, with the
  * line 1-BASED: the number an editor's gutter shows, so an agent told to open
@@ -23,9 +24,115 @@ import { descText, metaKey } from "./parsed/values.js";
  *
  * Four modules used to hand-roll this ternary; they all read this one now, so
  * the base cannot drift between them again.
+ *
+ * The message itself is BOUNDED here too, and for the same reason it lives in
+ * one place: every surface that prints a LikeC4 diagnostic — validate, context,
+ * show, tasks, doctor, gate, archive — prints it through this function, so this
+ * is the one spelling that can keep all of them small. See `boundedMessage`.
  */
 export function errorText(e) {
-    return typeof e.line === "number" ? `L${e.line + 1}: ${e.message}` : e.message;
+    const message = boundedMessage(e.message);
+    return typeof e.line === "number" ? `L${e.line + 1}: ${message}` : message;
+}
+/**
+ * The documents a project's diagnostics name, docs-relative POSIX, deduped and
+ * sorted — the one spelling of "which files broke" behind `landscape.invalid`,
+ * `spine.landscape-invalid`, the brief's unparseable arm, the work packet and
+ * `loam explore`. Those surfaces are read one after another on the same tree,
+ * and an agent has to be able to tell that they name the same file. Given ONE
+ * error it spells that error's document: validate's detail-line prefix.
+ */
+export function brokenDocumentPaths(docsDir, errors) {
+    return [...new Set(errors.map((e) => e.sourceFsPath).filter((p) => p !== undefined))]
+        .map((abs) => relative(docsDir, abs).split(/[\\/]/).join("/"))
+        .sort();
+}
+/**
+ * How many alternatives of a parser's "one of these possible Token sequences"
+ * list a printed diagnostic keeps — the number `likec4 validate` itself prints
+ * before its `...`.
+ */
+const TOKEN_ALTERNATIVES = 4;
+/** The heading line of Chevrotain's no-viable-alternative message, whose numbered list follows it. */
+const TOKEN_SEQUENCES = /possible Token sequences:$/;
+/** One numbered alternative in that list: `  12. [IdTerminal, Dot]`. */
+const ALTERNATIVE = /^\s+\d+\. /;
+/**
+ * A LikeC4 message, with Chevrotain's list of expected token sequences cut to
+ * its first few alternatives and a count of the rest.
+ *
+ * When the parser meets a token no rule can take, Chevrotain lists EVERY token
+ * sequence any rule could have accepted there — and inside a LikeC4 `model { }`
+ * block that is the whole grammar. Measured at the 1.59.2 pin: deleting the
+ * closing quote of one `technology '…'` makes three such messages of about
+ * 6,160 lines each, and `loam validate --service` printed 18,503 lines
+ * (434 KB; 458 KB as `--json`) for one keystroke. `capDetails` bounds how MANY
+ * details a finding prints, never how big one is, and `loam context` has no cap
+ * at all — so a broken feature delta turned a 24 KB briefing into 626 KB for
+ * every agent working on any service the feature touches. An agent in the
+ * check-fix loop gets nothing from alternative 4,000: what it acts on is the
+ * line number and the `but found: '…'` line, which is kept.
+ *
+ * Upstream `likec4 validate` keeps the first five lines of any message and
+ * prints `...`; this cuts the LIST only, so the `but found:` line after it
+ * survives, and says how many alternatives were dropped so nothing reads as
+ * complete when it is not (the convention `capDetails` uses). Any other
+ * message is returned exactly as LikeC4 wrote it.
+ */
+function boundedMessage(message) {
+    const lines = message.split("\n");
+    if (!TOKEN_SEQUENCES.test(lines[0] ?? ""))
+        return message;
+    const alternatives = lines.filter((line) => ALTERNATIVE.test(line)).length;
+    if (alternatives <= TOKEN_ALTERNATIVES)
+        return message;
+    const kept = [];
+    let seen = 0;
+    for (const line of lines) {
+        if (!ALTERNATIVE.test(line))
+            kept.push(line);
+        else if (++seen <= TOKEN_ALTERNATIVES)
+            kept.push(line);
+        else if (seen === TOKEN_ALTERNATIVES + 1)
+            kept.push(`  … (+${alternatives - TOKEN_ALTERNATIVES} more)`);
+    }
+    return kept.join("\n");
+}
+/**
+ * Diagnostics as loam keeps them: each one ONCE, in line order.
+ *
+ * LikeC4 can report one fault more than once: measured at the 1.59.2 pin, one
+ * dropped quote in a service model came back as two byte-identical messages at
+ * the same line — each of them the full token list `boundedMessage` cuts — and
+ * every `details` list printed both. The same message at the same line of the
+ * same file is one fault; the identity includes the file because LikeC4 blames
+ * a duplicate declaration on BOTH documents of a project, and those are two
+ * lines an author has to look at.
+ *
+ * In line order because LikeC4 hands its lexer's errors over before its
+ * parser's: the first location printed for that dropped quote was an
+ * "unexpected character" twelve lines BELOW it, where the runaway string ended,
+ * while the parser's errors two lines below it came after. The sort is stable,
+ * so diagnostics on one line keep LikeC4's order, and a list mixing documents
+ * stays in line order within each of them — every loader groups by document
+ * after this, which is why sorting by line alone is enough. A diagnostic with
+ * no line is about the document as a whole and leads.
+ *
+ * Applied where `getErrors()` is read (`loadSource`, `./workspace.ts`,
+ * `./project/load.ts`), so every loader hands every reader the same list and
+ * test/likec4-batch-parity.test.ts can keep asserting the two modes equal.
+ */
+export function distinctErrors(errors) {
+    const seen = new Set();
+    return errors
+        .filter((e) => {
+        const key = `${e.sourceFsPath ?? ""}\0${e.line ?? ""}\0${e.message}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    })
+        .sort((a, b) => (a.line ?? -1) - (b.line ?? -1));
 }
 /** Flatten a LikeC4 model into loam's neutral `Elem`/`Rel` view. */
 export function flattenModel(model) {
@@ -43,7 +150,8 @@ export function flattenModel(model) {
             tags: [...(e.tags ?? [])],
         };
     });
-    const relationships = [...model.relationships()].map((r) => ({
+    const relationships = [...model.relationships()]
+        .map((r) => ({
         source: r.source.id,
         target: r.target.id,
         // LikeC4 reports an untitled edge as title: null — normalize to the declared `title?: string`.
@@ -52,7 +160,9 @@ export function flattenModel(model) {
         publishes: metaKey(r.metadata, "publishes"),
         consumes: metaKey(r.metadata, "consumes"),
         tags: [...(r.tags ?? [])],
-    }));
+    }))
+        // One order for every run and machine: `compareRels` (./parsed/values.ts) says why LikeC4 gives none.
+        .sort(compareRels);
     return { elements, relationships };
 }
 /**
@@ -79,8 +189,9 @@ export async function loadSource(src) {
         // whose element type is structurally wider than ours, so the compiler can
         // check the shape here. The cast was the only thing standing between a
         // dependency renaming `message` and a build that still succeeded — and the
-        // `?? []` it carried could never fire.
-        const errors = likec4.getErrors();
+        // `?? []` it carried could never fire. Through `distinctErrors`, as every
+        // loader's diagnostics are, so this one agrees with the batch loader.
+        const errors = distinctErrors(likec4.getErrors());
         if (errors.length > 0) {
             return { errors, elements: [], relationships: [] };
         }
@@ -94,19 +205,39 @@ export async function loadSource(src) {
         // a second into minutes. The elements and relationships below are identical
         // either way. The `await` is load-bearing for anything reading `$data`: it is
         // undefined on the unresolved promise.
-        const model = (await likec4.parsedModel());
-        return {
-            errors,
-            specification: readSpecification(model.specification),
-            views: readDynamicViews(model),
-            viewIds: readViewIds(model),
-            globalStyles: readGlobalStyleIds(model),
-            deployment: readDeployment(model),
-            ...flattenModel(model),
-        };
+        return cleanDoc((await likec4.parsedModel()));
     }
     finally {
         await likec4.dispose();
     }
 }
+/**
+ * Everything loam reads out of one document that parsed clean, from LikeC4's
+ * parsed stage. Shared with `./workspace.ts`'s batch loader, which used to
+ * spell the same six reads out again: an adapter wired into one loader and not
+ * the other reads as an absence rather than an error, the failure
+ * test/likec4-batch-parity.test.ts exists to catch. `./project/load.ts`'s
+ * `cleanProjectDoc` wraps the same reads in a project's record, whose error
+ * shape differs and which requires the fields `LoadedDoc` leaves optional.
+ */
+export function cleanDoc(model) {
+    return { errors: [], ...readParsedModel(model) };
+}
+/**
+ * The six reads themselves — one spelling under every loader (`cleanDoc`
+ * above, `./project/load.ts`'s `cleanProjectDoc`), so the parity test guards
+ * one function rather than a convention. The return type is inferred on
+ * purpose: it is `LoadedDoc` minus `errors` with every read PRESENT, which is
+ * what lets a project's record, whose fields are required, spread it.
+ */
+export function readParsedModel(model) {
+    return {
+        specification: readSpecification(model.specification),
+        views: readDynamicViews(model),
+        viewIds: readViewIds(model),
+        globalStyles: readGlobalStyleIds(model),
+        deployment: readDeployment(model),
+        ...flattenModel(model),
+    };
+}
 //# sourceMappingURL=likec4.js.map

package/dist/core/c4/likec4.js.map

@@ -1 +1 @@
-{"version":3,"file":"likec4.js","sourceRoot":"","sources":["../../../src/core/c4/likec4.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { LikeC4 } from \"likec4\";\nimport { declaredService, type DeclaredService } from \"../kernel/ids/service.js\";\nimport { readDynamicViews, type ParsedView } from \"./parsed/dynamic-views.js\";\nimport { readGlobalStyleIds, readViewIds, type ViewIdClaim } from \"./parsed/view-ids.js\";\nimport { readSpecification, type DocSpecification } from \"./parsed/specification.js\";\nimport { readDeployment, type DeploymentModel } from \"./parsed/deployment.js\";\nimport { descText, metaKey } from \"./parsed/values.js\";\n\n/** A parse/validation issue reported by LikeC4. */\nexport interface LikeC4Error {\n  message: string;\n  /** As LikeC4 hands it over: an LSP range line, which starts at 0. Print it through `errorText`. */\n  line?: number;\n  sourceFsPath?: string;\n}\n\n/**\n * The one spelling of a diagnostic loam prints — `L<n>: <message>`, with the\n * line 1-BASED: the number an editor's gutter shows, so an agent told to open\n * it opens the line the fault is on. LikeC4's `getErrors()` copies the LSP\n * range's start line, which counts from 0, and every message used to print that\n * raw number: the named line landed one above the fault every time\n * (verification 2026-09-04, W6).\n *\n * `likec4 validate` DOES NOT AGREE, and that is deliberate rather than\n * unnoticed. Measured at the 1.59.2 pin on a document whose fault is on file\n * line 10: the CLI prints `Line 9:` and loam prints `L10:` for the same\n * diagnostic — it renders the LSP index raw. Copying that would make loam's\n * output wrong in the way the fix above repaired, so the two spellings differ\n * by exactly one and a reader comparing them should expect it.\n *\n * Four modules used to hand-roll this ternary; they all read this one now, so\n * the base cannot drift between them again.\n */\nexport function errorText(e: LikeC4Error): string {\n  return typeof e.line === \"number\" ? `L${e.line + 1}: ${e.message}` : e.message;\n}\n\n/** loam-neutral element view (flattened from the LikeC4 parsed model). */\nexport interface Elem {\n  id: string;\n  kind: string;\n  title: string;\n  description?: string;\n  /**\n   * The `services/<id>` directory this element stands for, from the element's\n   * `metadata { service '...' }`. Absent on the elements nobody has bound —\n   * see `elementService` for the fallback.\n   */\n  service?: DeclaredService;\n  tags: string[];\n}\n\n/** loam-neutral relationship view. */\nexport interface Rel {\n  source: string;\n  target: string;\n  title?: string;\n  /** OpenAPI operationId this call uses, from the relationship's `metadata { op '...' }`. */\n  op?: string;\n  /**\n   * AsyncAPI message this edge PRODUCES, from `metadata { publishes '...' }`.\n   * Resolved against the edge SOURCE's own contract: a service publishes what it\n   * declares an `action: send` for.\n   */\n  publishes?: string;\n  /**\n   * AsyncAPI message this edge CONSUMES, from `metadata { consumes '...' }`.\n   * Two keys rather than one directional `message`, because the async spine is\n   * not symmetric with the HTTP one: there the PROVIDER owns the contract and\n   * every consumer is checked against it, while here the PRODUCER owns the\n   * message and the consumer lives in another repository entirely. Which side of\n   * an edge owes the declaration has to be readable from the edge itself — the\n   * arrow cannot say it, because a Kafka edge points at the broker from both\n   * ends.\n   */\n  consumes?: string;\n  tags: string[];\n}\n\nexport interface LoadedDoc {\n  errors: LikeC4Error[];\n  elements: Elem[];\n  relationships: Rel[];\n  /**\n   * The document's `specification { }` block — what its KINDS declare, as\n   * opposed to what its elements do. Optional because a document that did not\n   * parse has none, and because the several `LoadedDoc` literals standing in for\n   * an absent file (`show`'s missing model.likec4, `unreadableLandscape`) have\n   * nothing to put here: a reader must treat \"absent\" and \"declares nothing\" the\n   * same way. See `./parsed/specification.ts` for why loam reads it at all —\n   * short version: since LikeC4 1.59.0 a kind can carry tags, and only the\n   * specification can tell an inherited tag from an authored one.\n   */\n  specification?: DocSpecification;\n  /**\n   * The `dynamic view`s the document DECLARES — the ordered steps of a use\n   * case, never a rendering (docs/DESIGN.md rule 26). Optional for exactly the\n   * reason `specification` is: a document that did not parse has none, and the\n   * several `LoadedDoc` literals standing in for an absent file have nothing to\n   * put here. Absent and empty mean the same thing to every reader — no views\n   * were declared, or none could be read — and neither is a finding: a fleet\n   * that draws no diagrams owes loam no views block.\n   */\n  views?: ParsedView[];\n  /**\n   * The ids of every view the document AUTHORS, static ones included — a census,\n   * not a read of what any of them shows. Separate from `views` above because\n   * the two answer different questions off different filters (see\n   * `./parsed/view-ids.ts`), and because a static view contributes an id and\n   * nothing else loam may look at.\n   */\n  viewIds?: ViewIdClaim[];\n  /**\n   * The ids of every GLOBAL STYLE the document declares — `global { styleGroup\n   * <id> { … } }` and the single-rule `global { style <id> … }` alike, since\n   * LikeC4 files both under one id table (hence not `styleGroups`). A\n   * declaration census exactly as `viewIds` is: the ids, sorted, and never a\n   * rule inside one (docs/DESIGN.md rule 26 says why a style is a rendering\n   * instruction loam may not read). One consumer — the generated subsystem\n   * views, which reference the group named `subsystems` when it is declared\n   * and nothing otherwise, because a reference to an undeclared id is a parse\n   * error that blanks the whole `architecture/` project in the renderer.\n   * Optional for the reason `views` is: a document that did not parse has\n   * none, and the `LoadedDoc` literals standing in for an absent file have\n   * nothing to put here; absent and empty mean the same thing to every reader.\n   */\n  globalStyles?: string[];\n  /**\n   * The `deployment { }` model the document declares — nodes, instances and the\n   * edges between them (`./parsed/deployment.ts`). Optional for the reason\n   * `views` is, and read the same way by every consumer: absent and empty mean\n   * \"no topology\", and neither is a finding. A fleet that draws no deployment\n   * owes loam none, which is also the whole opt-in the axis has.\n   */\n  deployment?: DeploymentModel;\n}\n\n/**\n * The slice of a LikeC4 model loam reads: elements and relationships, and on\n * each of those only id/kind/title/description/tags/metadata.\n *\n * It is a type of its own, rather than an inline cast at the one call site,\n * because BOTH of LikeC4's model stages expose exactly this slice — which is\n * what makes the cheap stage a safe substitute for the expensive one. The\n * substitution is pinned in test/likec4-model-parity.test.ts, which flattens\n * both stages through `flattenModel` below and compares the results.\n *\n * Views are deliberately NOT in this interface, even though loam does read them.\n * What this interface pins is the two-stage PARITY that makes the cheap stage a\n * safe substitute for the expensive one — and the stages are not claimed to\n * agree about views, nor need to: the parsed stage is the only one rule 26\n * permits. That read has its own adapter, `./parsed/dynamic-views.ts`.\n */\nexport interface ReadableModel {\n  elements: () => Iterable<{\n    id: string;\n    kind: string;\n    title: string;\n    description?: unknown;\n    tags?: readonly string[];\n    metadata?: unknown;\n  }>;\n  relationships: () => Iterable<{\n    source: { id: string };\n    target: { id: string };\n    title?: string | null;\n    tags?: readonly string[];\n    metadata?: unknown;\n  }>;\n  /**\n   * The parsed `specification { }` block. Typed `unknown` and normalized by\n   * `readSpecification` rather than described here, because it is NOT part of\n   * the two-stage parity this interface pins: the shape is LikeC4's internal\n   * record (1.59.2 spells element-kind tags and relationship-kind tags\n   * differently), and writing it out here would be a structural claim about a\n   * dependency's internals that the compiler would then enforce against us.\n   */\n  specification?: unknown;\n}\n\n/** Flatten a LikeC4 model into loam's neutral `Elem`/`Rel` view. */\nexport function flattenModel(model: ReadableModel): { elements: Elem[]; relationships: Rel[] } {\n  const elements: Elem[] = [...model.elements()].map((e) => {\n    // The one crossing between LikeC4's parse output and loam's type system:\n    // a `metadata { service '...' }` binding is text somebody wrote, and this\n    // is where it acquires a type that says so.\n    const bound = metaKey(e.metadata, \"service\");\n    return {\n      id: e.id,\n      kind: e.kind,\n      title: e.title,\n      description: descText(e.description),\n      ...(bound === undefined ? {} : { service: declaredService(bound) }),\n      tags: [...(e.tags ?? [])],\n    };\n  });\n  const relationships: Rel[] = [...model.relationships()].map((r) => ({\n    source: r.source.id,\n    target: r.target.id,\n    // LikeC4 reports an untitled edge as title: null — normalize to the declared `title?: string`.\n    title: r.title ?? undefined,\n    op: metaKey(r.metadata, \"op\"),\n    publishes: metaKey(r.metadata, \"publishes\"),\n    consumes: metaKey(r.metadata, \"consumes\"),\n    tags: [...(r.tags ?? [])],\n  }));\n  return { elements, relationships };\n}\n\n/**\n * Load and validate a single self-contained `.likec4` document, in-process\n * (no external tool, no JVM). Returns validation errors and, if clean, the\n * flattened elements + relationships.\n */\nexport async function loadFile(path: string): Promise<LoadedDoc> {\n  return loadSource(await readFile(path, \"utf8\"));\n}\n\n/**\n * `loadFile` for text that is not (yet) on disk — what the archive merge uses\n * to prove a computed landscape parses BEFORE anything is written.\n */\nexport async function loadSource(src: string): Promise<LoadedDoc> {\n  // LikeC4 owns a Langium workspace and registers a process-exit listener for\n  // it. Validation creates many short-lived instances, so every acquired\n  // instance must be disposed even on an invalid document or a failed model\n  // computation. Its logger is disabled because diagnostics are returned in\n  // LoadedDoc instead of being written out-of-band to stderr.\n  const likec4 = await LikeC4.fromSource(src, { logger: false });\n  try {\n    // Assigned, not cast: LikeC4 declares `getErrors()` as a non-nullable array\n    // whose element type is structurally wider than ours, so the compiler can\n    // check the shape here. The cast was the only thing standing between a\n    // dependency renaming `message` and a build that still succeeded — and the\n    // `?? []` it carried could never fire.\n    const errors: LikeC4Error[] = likec4.getErrors();\n    if (errors.length > 0) {\n      return { errors, elements: [], relationships: [] };\n    }\n\n    // `parsedModel`, not `computedModel`: the computed stage RESOLVES every\n    // view — expanding its predicates against the model and deriving the\n    // ancestor edges a diagram needs (and computing a default view when the\n    // document declares none). loam reads what a view DECLARES and never what a\n    // view SHOWS (docs/DESIGN.md rule 26), so none of that resolution is ever\n    // wanted; it renders nothing. That work is superlinear in the number of\n    // RELATIONSHIPS, so a landscape at fleet shape turned `loam list` from under\n    // a second into minutes. The elements and relationships below are identical\n    // either way. The `await` is load-bearing for anything reading `$data`: it is\n    // undefined on the unresolved promise.\n    const model = (await likec4.parsedModel()) as ReadableModel;\n    return {\n      errors,\n      specification: readSpecification(model.specification),\n      views: readDynamicViews(model),\n      viewIds: readViewIds(model),\n      globalStyles: readGlobalStyleIds(model),\n      deployment: readDeployment(model),\n      ...flattenModel(model),\n    };\n  } finally {\n    await likec4.dispose();\n  }\n}\n"]}
+{"version":3,"file":"likec4.js","sourceRoot":"","sources":["../../../src/core/c4/likec4.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,eAAe,EAAwB,MAAM,0BAA0B,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAmB,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAoB,MAAM,sBAAsB,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAyB,MAAM,2BAA2B,CAAC;AACrF,OAAO,EAAE,cAAc,EAAwB,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAUpE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,SAAS,CAAC,CAAc;IACtC,MAAM,OAAO,GAAG,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC1C,OAAO,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;AAC7E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe,EAAE,MAA8B;IACjF,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC;SAC/F,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;SAC7D,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAE7B,sGAAsG;AACtG,MAAM,eAAe,GAAG,4BAA4B,CAAC;AAErD,wEAAwE;AACxE,MAAM,WAAW,GAAG,YAAY,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAS,cAAc,CAAC,OAAe;IACrC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1D,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IAC3E,IAAI,YAAY,IAAI,kBAAkB;QAAE,OAAO,OAAO,CAAC;IACvD,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;aACxC,IAAI,EAAE,IAAI,IAAI,kBAAkB;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;aAClD,IAAI,IAAI,KAAK,kBAAkB,GAAG,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,SAAS,YAAY,GAAG,kBAAkB,QAAQ,CAAC,CAAC;IAC1G,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,cAAc,CAAwB,MAAoB;IACxE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,MAAM;SACV,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QACZ,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,YAAY,IAAI,EAAE,KAAK,CAAC,CAAC,IAAI,IAAI,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;QACrE,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC;AAiJD,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAAC,KAAoB;IAC/C,MAAM,QAAQ,GAAW,CAAC,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACvD,yEAAyE;QACzE,0EAA0E;QAC1E,4CAA4C;QAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC7C,OAAO;YACL,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC;YACpC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;YACnE,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;SAC1B,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,aAAa,GAAU,CAAC,GAAG,KAAK,CAAC,aAAa,EAAE,CAAC;SACpD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE;QACnB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE;QACnB,+FAA+F;QAC/F,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,SAAS;QAC3B,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC;QAC7B,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,WAAW,CAAC;QAC3C,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC;QACzC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;KAC1B,CAAC,CAAC;QACH,sGAAsG;SACrG,IAAI,CAAC,WAAW,CAAC,CAAC;IACrB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAY;IACzC,OAAO,UAAU,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAW;IAC1C,4EAA4E;IAC5E,uEAAuE;IACvE,0EAA0E;IAC1E,0EAA0E;IAC1E,4DAA4D;IAC5D,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/D,IAAI,CAAC;QACH,4EAA4E;QAC5E,0EAA0E;QAC1E,uEAAuE;QACvE,2EAA2E;QAC3E,0EAA0E;QAC1E,sEAAsE;QACtE,MAAM,MAAM,GAAkB,cAAc,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QACjE,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;QACrD,CAAC;QAED,wEAAwE;QACxE,qEAAqE;QACrE,wEAAwE;QACxE,4EAA4E;QAC5E,0EAA0E;QAC1E,wEAAwE;QACxE,6EAA6E;QAC7E,4EAA4E;QAC5E,8EAA8E;QAC9E,uCAAuC;QACvC,OAAO,QAAQ,CAAC,CAAC,MAAM,MAAM,CAAC,WAAW,EAAE,CAAkB,CAAC,CAAC;IACjE,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAoB;IAC3C,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAoB;IAClD,OAAO;QACL,aAAa,EAAE,iBAAiB,CAAC,KAAK,CAAC,aAAa,CAAC;QACrD,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC;QAC9B,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC;QAC3B,YAAY,EAAE,kBAAkB,CAAC,KAAK,CAAC;QACvC,UAAU,EAAE,cAAc,CAAC,KAAK,CAAC;QACjC,GAAG,YAAY,CAAC,KAAK,CAAC;KACvB,CAAC;AACJ,CAAC","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { relative } from \"node:path\";\nimport { LikeC4 } from \"likec4\";\nimport { declaredService, type DeclaredService } from \"../kernel/ids/service.js\";\nimport { readDynamicViews, type ParsedView } from \"./parsed/dynamic-views.js\";\nimport { readGlobalStyleIds, readViewIds, type ViewIdClaim } from \"./parsed/view-ids.js\";\nimport { readSpecification, type DocSpecification } from \"./parsed/specification.js\";\nimport { readDeployment, type DeploymentModel } from \"./parsed/deployment.js\";\nimport { compareRels, descText, metaKey } from \"./parsed/values.js\";\n\n/** A parse/validation issue reported by LikeC4. */\nexport interface LikeC4Error {\n  message: string;\n  /** As LikeC4 hands it over: an LSP range line, which starts at 0. Print it through `errorText`. */\n  line?: number;\n  sourceFsPath?: string;\n}\n\n/**\n * The one spelling of a diagnostic loam prints — `L<n>: <message>`, with the\n * line 1-BASED: the number an editor's gutter shows, so an agent told to open\n * it opens the line the fault is on. LikeC4's `getErrors()` copies the LSP\n * range's start line, which counts from 0, and every message used to print that\n * raw number: the named line landed one above the fault every time\n * (verification 2026-09-04, W6).\n *\n * `likec4 validate` DOES NOT AGREE, and that is deliberate rather than\n * unnoticed. Measured at the 1.59.2 pin on a document whose fault is on file\n * line 10: the CLI prints `Line 9:` and loam prints `L10:` for the same\n * diagnostic — it renders the LSP index raw. Copying that would make loam's\n * output wrong in the way the fix above repaired, so the two spellings differ\n * by exactly one and a reader comparing them should expect it.\n *\n * Four modules used to hand-roll this ternary; they all read this one now, so\n * the base cannot drift between them again.\n *\n * The message itself is BOUNDED here too, and for the same reason it lives in\n * one place: every surface that prints a LikeC4 diagnostic — validate, context,\n * show, tasks, doctor, gate, archive — prints it through this function, so this\n * is the one spelling that can keep all of them small. See `boundedMessage`.\n */\nexport function errorText(e: LikeC4Error): string {\n  const message = boundedMessage(e.message);\n  return typeof e.line === \"number\" ? `L${e.line + 1}: ${message}` : message;\n}\n\n/**\n * The documents a project's diagnostics name, docs-relative POSIX, deduped and\n * sorted — the one spelling of \"which files broke\" behind `landscape.invalid`,\n * `spine.landscape-invalid`, the brief's unparseable arm, the work packet and\n * `loam explore`. Those surfaces are read one after another on the same tree,\n * and an agent has to be able to tell that they name the same file. Given ONE\n * error it spells that error's document: validate's detail-line prefix.\n */\nexport function brokenDocumentPaths(docsDir: string, errors: readonly LikeC4Error[]): string[] {\n  return [...new Set(errors.map((e) => e.sourceFsPath).filter((p): p is string => p !== undefined))]\n    .map((abs) => relative(docsDir, abs).split(/[\\\\/]/).join(\"/\"))\n    .sort();\n}\n\n/**\n * How many alternatives of a parser's \"one of these possible Token sequences\"\n * list a printed diagnostic keeps — the number `likec4 validate` itself prints\n * before its `...`.\n */\nconst TOKEN_ALTERNATIVES = 4;\n\n/** The heading line of Chevrotain's no-viable-alternative message, whose numbered list follows it. */\nconst TOKEN_SEQUENCES = /possible Token sequences:$/;\n\n/** One numbered alternative in that list: `  12. [IdTerminal, Dot]`. */\nconst ALTERNATIVE = /^\\s+\\d+\\. /;\n\n/**\n * A LikeC4 message, with Chevrotain's list of expected token sequences cut to\n * its first few alternatives and a count of the rest.\n *\n * When the parser meets a token no rule can take, Chevrotain lists EVERY token\n * sequence any rule could have accepted there — and inside a LikeC4 `model { }`\n * block that is the whole grammar. Measured at the 1.59.2 pin: deleting the\n * closing quote of one `technology '…'` makes three such messages of about\n * 6,160 lines each, and `loam validate --service` printed 18,503 lines\n * (434 KB; 458 KB as `--json`) for one keystroke. `capDetails` bounds how MANY\n * details a finding prints, never how big one is, and `loam context` has no cap\n * at all — so a broken feature delta turned a 24 KB briefing into 626 KB for\n * every agent working on any service the feature touches. An agent in the\n * check-fix loop gets nothing from alternative 4,000: what it acts on is the\n * line number and the `but found: '…'` line, which is kept.\n *\n * Upstream `likec4 validate` keeps the first five lines of any message and\n * prints `...`; this cuts the LIST only, so the `but found:` line after it\n * survives, and says how many alternatives were dropped so nothing reads as\n * complete when it is not (the convention `capDetails` uses). Any other\n * message is returned exactly as LikeC4 wrote it.\n */\nfunction boundedMessage(message: string): string {\n  const lines = message.split(\"\\n\");\n  if (!TOKEN_SEQUENCES.test(lines[0] ?? \"\")) return message;\n  const alternatives = lines.filter((line) => ALTERNATIVE.test(line)).length;\n  if (alternatives <= TOKEN_ALTERNATIVES) return message;\n  const kept: string[] = [];\n  let seen = 0;\n  for (const line of lines) {\n    if (!ALTERNATIVE.test(line)) kept.push(line);\n    else if (++seen <= TOKEN_ALTERNATIVES) kept.push(line);\n    else if (seen === TOKEN_ALTERNATIVES + 1) kept.push(`  … (+${alternatives - TOKEN_ALTERNATIVES} more)`);\n  }\n  return kept.join(\"\\n\");\n}\n\n/**\n * Diagnostics as loam keeps them: each one ONCE, in line order.\n *\n * LikeC4 can report one fault more than once: measured at the 1.59.2 pin, one\n * dropped quote in a service model came back as two byte-identical messages at\n * the same line — each of them the full token list `boundedMessage` cuts — and\n * every `details` list printed both. The same message at the same line of the\n * same file is one fault; the identity includes the file because LikeC4 blames\n * a duplicate declaration on BOTH documents of a project, and those are two\n * lines an author has to look at.\n *\n * In line order because LikeC4 hands its lexer's errors over before its\n * parser's: the first location printed for that dropped quote was an\n * \"unexpected character\" twelve lines BELOW it, where the runaway string ended,\n * while the parser's errors two lines below it came after. The sort is stable,\n * so diagnostics on one line keep LikeC4's order, and a list mixing documents\n * stays in line order within each of them — every loader groups by document\n * after this, which is why sorting by line alone is enough. A diagnostic with\n * no line is about the document as a whole and leads.\n *\n * Applied where `getErrors()` is read (`loadSource`, `./workspace.ts`,\n * `./project/load.ts`), so every loader hands every reader the same list and\n * test/likec4-batch-parity.test.ts can keep asserting the two modes equal.\n */\nexport function distinctErrors<E extends LikeC4Error>(errors: readonly E[]): E[] {\n  const seen = new Set<string>();\n  return errors\n    .filter((e) => {\n      const key = `${e.sourceFsPath ?? \"\"}\\0${e.line ?? \"\"}\\0${e.message}`;\n      if (seen.has(key)) return false;\n      seen.add(key);\n      return true;\n    })\n    .sort((a, b) => (a.line ?? -1) - (b.line ?? -1));\n}\n\n/** loam-neutral element view (flattened from the LikeC4 parsed model). */\nexport interface Elem {\n  id: string;\n  kind: string;\n  title: string;\n  description?: string;\n  /**\n   * The `services/<id>` directory this element stands for, from the element's\n   * `metadata { service '...' }`. Absent on the elements nobody has bound —\n   * see `elementService` for the fallback.\n   */\n  service?: DeclaredService;\n  tags: string[];\n}\n\n/** loam-neutral relationship view. */\nexport interface Rel {\n  source: string;\n  target: string;\n  title?: string;\n  /** OpenAPI operationId this call uses, from the relationship's `metadata { op '...' }`. */\n  op?: string;\n  /**\n   * AsyncAPI message this edge PRODUCES, from `metadata { publishes '...' }`.\n   * Resolved against the edge SOURCE's own contract: a service publishes what it\n   * declares an `action: send` for.\n   */\n  publishes?: string;\n  /**\n   * AsyncAPI message this edge CONSUMES, from `metadata { consumes '...' }`.\n   * Two keys rather than one directional `message`, because the async spine is\n   * not symmetric with the HTTP one: there the PROVIDER owns the contract and\n   * every consumer is checked against it, while here the PRODUCER owns the\n   * message and the consumer lives in another repository entirely. Which side of\n   * an edge owes the declaration has to be readable from the edge itself — the\n   * arrow cannot say it, because a Kafka edge points at the broker from both\n   * ends.\n   */\n  consumes?: string;\n  tags: string[];\n}\n\nexport interface LoadedDoc {\n  errors: LikeC4Error[];\n  elements: Elem[];\n  relationships: Rel[];\n  /**\n   * The document's `specification { }` block — what its KINDS declare, as\n   * opposed to what its elements do. Optional because a document that did not\n   * parse has none, and because the several `LoadedDoc` literals standing in for\n   * an absent file (`show`'s missing model.likec4, `unreadableLandscape`) have\n   * nothing to put here: a reader must treat \"absent\" and \"declares nothing\" the\n   * same way. See `./parsed/specification.ts` for why loam reads it at all —\n   * short version: since LikeC4 1.59.0 a kind can carry tags, and only the\n   * specification can tell an inherited tag from an authored one.\n   */\n  specification?: DocSpecification;\n  /**\n   * The `dynamic view`s the document DECLARES — the ordered steps of a use\n   * case, never a rendering (docs/DESIGN.md rule 26). Optional for exactly the\n   * reason `specification` is: a document that did not parse has none, and the\n   * several `LoadedDoc` literals standing in for an absent file have nothing to\n   * put here. Absent and empty mean the same thing to every reader — no views\n   * were declared, or none could be read — and neither is a finding: a fleet\n   * that draws no diagrams owes loam no views block.\n   */\n  views?: ParsedView[];\n  /**\n   * The ids of every view the document AUTHORS, static ones included — a census,\n   * not a read of what any of them shows. Separate from `views` above because\n   * the two answer different questions off different filters (see\n   * `./parsed/view-ids.ts`), and because a static view contributes an id and\n   * nothing else loam may look at.\n   */\n  viewIds?: ViewIdClaim[];\n  /**\n   * The ids of every GLOBAL STYLE the document declares — `global { styleGroup\n   * <id> { … } }` and the single-rule `global { style <id> … }` alike, since\n   * LikeC4 files both under one id table (hence not `styleGroups`). A\n   * declaration census exactly as `viewIds` is: the ids, sorted, and never a\n   * rule inside one (docs/DESIGN.md rule 26 says why a style is a rendering\n   * instruction loam may not read). One consumer — the generated subsystem\n   * views, which reference the group named `subsystems` when it is declared\n   * and nothing otherwise, because a reference to an undeclared id is a parse\n   * error that blanks the whole `architecture/` project in the renderer.\n   * Optional for the reason `views` is: a document that did not parse has\n   * none, and the `LoadedDoc` literals standing in for an absent file have\n   * nothing to put here; absent and empty mean the same thing to every reader.\n   */\n  globalStyles?: string[];\n  /**\n   * The `deployment { }` model the document declares — nodes, instances and the\n   * edges between them (`./parsed/deployment.ts`). Optional for the reason\n   * `views` is, and read the same way by every consumer: absent and empty mean\n   * \"no topology\", and neither is a finding. A fleet that draws no deployment\n   * owes loam none, which is also the whole opt-in the axis has.\n   */\n  deployment?: DeploymentModel;\n}\n\n/**\n * The slice of a LikeC4 model loam reads: elements and relationships, and on\n * each of those only id/kind/title/description/tags/metadata.\n *\n * It is a type of its own, rather than an inline cast at the one call site,\n * because BOTH of LikeC4's model stages expose exactly this slice — which is\n * what makes the cheap stage a safe substitute for the expensive one. The\n * substitution is pinned in test/likec4-model-parity.test.ts, which flattens\n * both stages through `flattenModel` below and compares the results.\n *\n * Views are deliberately NOT in this interface, even though loam does read them.\n * What this interface pins is the two-stage PARITY that makes the cheap stage a\n * safe substitute for the expensive one — and the stages are not claimed to\n * agree about views, nor need to: the parsed stage is the only one rule 26\n * permits. That read has its own adapter, `./parsed/dynamic-views.ts`.\n */\nexport interface ReadableModel {\n  elements: () => Iterable<{\n    id: string;\n    kind: string;\n    title: string;\n    description?: unknown;\n    tags?: readonly string[];\n    metadata?: unknown;\n  }>;\n  relationships: () => Iterable<{\n    source: { id: string };\n    target: { id: string };\n    title?: string | null;\n    tags?: readonly string[];\n    metadata?: unknown;\n  }>;\n  /**\n   * The parsed `specification { }` block. Typed `unknown` and normalized by\n   * `readSpecification` rather than described here, because it is NOT part of\n   * the two-stage parity this interface pins: the shape is LikeC4's internal\n   * record (1.59.2 spells element-kind tags and relationship-kind tags\n   * differently), and writing it out here would be a structural claim about a\n   * dependency's internals that the compiler would then enforce against us.\n   */\n  specification?: unknown;\n}\n\n/** Flatten a LikeC4 model into loam's neutral `Elem`/`Rel` view. */\nexport function flattenModel(model: ReadableModel): { elements: Elem[]; relationships: Rel[] } {\n  const elements: Elem[] = [...model.elements()].map((e) => {\n    // The one crossing between LikeC4's parse output and loam's type system:\n    // a `metadata { service '...' }` binding is text somebody wrote, and this\n    // is where it acquires a type that says so.\n    const bound = metaKey(e.metadata, \"service\");\n    return {\n      id: e.id,\n      kind: e.kind,\n      title: e.title,\n      description: descText(e.description),\n      ...(bound === undefined ? {} : { service: declaredService(bound) }),\n      tags: [...(e.tags ?? [])],\n    };\n  });\n  const relationships: Rel[] = [...model.relationships()]\n    .map((r) => ({\n      source: r.source.id,\n      target: r.target.id,\n      // LikeC4 reports an untitled edge as title: null — normalize to the declared `title?: string`.\n      title: r.title ?? undefined,\n      op: metaKey(r.metadata, \"op\"),\n      publishes: metaKey(r.metadata, \"publishes\"),\n      consumes: metaKey(r.metadata, \"consumes\"),\n      tags: [...(r.tags ?? [])],\n    }))\n    // One order for every run and machine: `compareRels` (./parsed/values.ts) says why LikeC4 gives none.\n    .sort(compareRels);\n  return { elements, relationships };\n}\n\n/**\n * Load and validate a single self-contained `.likec4` document, in-process\n * (no external tool, no JVM). Returns validation errors and, if clean, the\n * flattened elements + relationships.\n */\nexport async function loadFile(path: string): Promise<LoadedDoc> {\n  return loadSource(await readFile(path, \"utf8\"));\n}\n\n/**\n * `loadFile` for text that is not (yet) on disk — what the archive merge uses\n * to prove a computed landscape parses BEFORE anything is written.\n */\nexport async function loadSource(src: string): Promise<LoadedDoc> {\n  // LikeC4 owns a Langium workspace and registers a process-exit listener for\n  // it. Validation creates many short-lived instances, so every acquired\n  // instance must be disposed even on an invalid document or a failed model\n  // computation. Its logger is disabled because diagnostics are returned in\n  // LoadedDoc instead of being written out-of-band to stderr.\n  const likec4 = await LikeC4.fromSource(src, { logger: false });\n  try {\n    // Assigned, not cast: LikeC4 declares `getErrors()` as a non-nullable array\n    // whose element type is structurally wider than ours, so the compiler can\n    // check the shape here. The cast was the only thing standing between a\n    // dependency renaming `message` and a build that still succeeded — and the\n    // `?? []` it carried could never fire. Through `distinctErrors`, as every\n    // loader's diagnostics are, so this one agrees with the batch loader.\n    const errors: LikeC4Error[] = distinctErrors(likec4.getErrors());\n    if (errors.length > 0) {\n      return { errors, elements: [], relationships: [] };\n    }\n\n    // `parsedModel`, not `computedModel`: the computed stage RESOLVES every\n    // view — expanding its predicates against the model and deriving the\n    // ancestor edges a diagram needs (and computing a default view when the\n    // document declares none). loam reads what a view DECLARES and never what a\n    // view SHOWS (docs/DESIGN.md rule 26), so none of that resolution is ever\n    // wanted; it renders nothing. That work is superlinear in the number of\n    // RELATIONSHIPS, so a landscape at fleet shape turned `loam list` from under\n    // a second into minutes. The elements and relationships below are identical\n    // either way. The `await` is load-bearing for anything reading `$data`: it is\n    // undefined on the unresolved promise.\n    return cleanDoc((await likec4.parsedModel()) as ReadableModel);\n  } finally {\n    await likec4.dispose();\n  }\n}\n\n/**\n * Everything loam reads out of one document that parsed clean, from LikeC4's\n * parsed stage. Shared with `./workspace.ts`'s batch loader, which used to\n * spell the same six reads out again: an adapter wired into one loader and not\n * the other reads as an absence rather than an error, the failure\n * test/likec4-batch-parity.test.ts exists to catch. `./project/load.ts`'s\n * `cleanProjectDoc` wraps the same reads in a project's record, whose error\n * shape differs and which requires the fields `LoadedDoc` leaves optional.\n */\nexport function cleanDoc(model: ReadableModel): LoadedDoc {\n  return { errors: [], ...readParsedModel(model) };\n}\n\n/**\n * The six reads themselves — one spelling under every loader (`cleanDoc`\n * above, `./project/load.ts`'s `cleanProjectDoc`), so the parity test guards\n * one function rather than a convention. The return type is inferred on\n * purpose: it is `LoadedDoc` minus `errors` with every read PRESENT, which is\n * what lets a project's record, whose fields are required, spread it.\n */\nexport function readParsedModel(model: ReadableModel) {\n  return {\n    specification: readSpecification(model.specification),\n    views: readDynamicViews(model),\n    viewIds: readViewIds(model),\n    globalStyles: readGlobalStyleIds(model),\n    deployment: readDeployment(model),\n    ...flattenModel(model),\n  };\n}\n"]}

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

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

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

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

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

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

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

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

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

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