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

package/dist/core/c4/arch.js

@@ -0,0 +1,190 @@
+/**
+ * The architecture spec axis — the grammar and resolution of `Covers:` — and
+ * the same endpoint join, reused, for the steps of a use case.
+ *
+ * A business spec will never mention the transactional outbox; that is
+ * architecture, and it lives in `arch.spec.md` — same requirement/scenario
+ * grammar as spec.md, same delta algebra, same merge. What is new is the
+ * `Covers:` line: where a business requirement declares the OPERATIONS it
+ * governs, an architecture requirement declares the MODEL OBJECTS its
+ * scenarios exercise, so coverage can be derived mechanically instead of
+ * trusted to an author who was never going to write the outbox down.
+ *
+ * Four entry forms, resolved against the documents loam already reads:
+ *
+ *   paymentService.db               a C4 element id — resolved against the
+ *                                   in-scope elements the way every check joins
+ *                                   them: the id itself, or the service the
+ *                                   element stands for (binding, then title);
+ *   paymentService -> kafka         an edge — each side resolved the same way,
+ *                                   against the declared relationships; the
+ *                                   edge may carry the relationship's kind as
+ *                                   LikeC4 writes it, `paymentService -[async]->
+ *                                   kafka` or `paymentService .async kafka`,
+ *                                   which is read past rather than compared;
+ *   alert:<id> / sli:<id>           a health signal — ids `health.yaml`
+ *                                   declares (core/vocabulary/health.ts);
+ *   node:<id>, node:a -> node:b     a deployment object — a node or an instance
+ *                                   in the landscape's `deployment { }` model,
+ *                                   matched literally. This is the form that
+ *                                   lets a requirement about replication name
+ *                                   the two clusters it is written about
+ *                                   (ROADMAP's deployment axis).
+ *
+ * Resolution never reads code. An entry that resolves to nothing is the typo
+ * guard (`covers.unknown`, warn); the emitters live with the other validate
+ * checks, this module owns only the grammar and the matching.
+ *
+ * `attributeStep` used to sit at the foot of this file and now lives in
+ * `./resolve/steps.ts`. It answers the same shape of question for a different
+ * axis — which declared relationship backs a `dynamic view`'s hop — over the
+ * same two tiers and the same cached resolver, and the seam was named here long
+ * before the line limit forced it. What the two still share is
+ * `./resolve/service.ts`'s `resolverFor`, which is where that cache moved with
+ * it: one id→service resolver per document, serving both axes.
+ */
+import {} from "./likec4.js";
+import { elementService, resolverFor } from "./resolve/service.js";
+/** Parse one comma-separated `Covers:` entry into its form. Never fails: an
+ * unclassifiable string is an element entry that will not resolve, and the
+ * covers.unknown message is a better diagnosis than a parse refusal. */
+export function parseCoversEntry(raw) {
+    const alert = /^alert:\s*(.+)$/.exec(raw);
+    if (alert)
+        return { form: "alert", id: alert[1].trim(), raw };
+    const sli = /^sli:\s*(.+)$/.exec(raw);
+    if (sli)
+        return { form: "sli", id: sli[1].trim(), raw };
+    // An edge may be spelled with its relationship kind, the two ways LikeC4
+    // writes one — `a -[async]-> b`, and `a .async b` for a kind the
+    // specification declares — because that is how the edge itself is written
+    // and an author copies the edge line. The split used to stop at the first
+    // `->`, the one AFTER the `]`, so the bracket form became `a -[async]` ->
+    // `b`, and the dotted form, with no `->` at all, fell through to an element
+    // entry: both were `covers.unknown` while the kind-less spelling of the same
+    // edge resolved. The kind is read past, not compared: loam identifies an
+    // edge by its two endpoints (`flattenModel` keeps no kind), so either kinded
+    // spelling covers exactly what `a -> b` covers. The dotted form needs no
+    // specification to tell it from an element id: an id never holds a space,
+    // so `<id> .<kind> <id>` can be nothing else.
+    const edge = /^(.+?)\s*(?:-\[[^\]]*\])?->\s*(.+)$/.exec(raw) ?? /^(\S+)\s+\.[A-Za-z_][\w-]*\s+(\S+)$/.exec(raw);
+    if (edge) {
+        const source = edge[1].trim();
+        const target = edge[2].trim();
+        const from = nodeId(source);
+        const to = nodeId(target);
+        // BOTH sides, or neither. A mixed entry stays an ordinary edge whose
+        // prefixed side then resolves to nothing — which is the honest answer:
+        // there is no edge in any model with one endpoint in the logical map and
+        // one in the deployment map, so accepting a half-prefixed line would be
+        // inventing a join rather than reading one. The `->` split runs FIRST for
+        // the same reason the alert/sli tests do: `node:a -> node:b` read as a
+        // single id would be one entry that can never resolve.
+        if (from !== undefined && to !== undefined)
+            return { form: "node-edge", source: from, target: to, raw };
+        return { form: "edge", source, target, raw };
+    }
+    const node = nodeId(raw);
+    if (node !== undefined)
+        return { form: "node", id: node, raw };
+    return { form: "element", id: raw, raw };
+}
+/** The id behind a `node:` prefix, or nothing when the entry does not carry one. */
+function nodeId(text) {
+    const m = /^node:\s*(.+)$/.exec(text);
+    return m === null ? undefined : m[1].trim();
+}
+/** Does an element entry name this element? Its id, or the service it stands for. */
+function namesElement(name, e) {
+    return e.id === name || elementService(e) === name;
+}
+/** Does an edge entry's side name this relationship endpoint? */
+function namesEndpoint(name, endpointId, elements, known) {
+    return endpointId === name || resolverFor(elements, known)(endpointId) === name;
+}
+/** Does a Covers entry match this element? (Only element entries can.) */
+export function coversElement(entry, e) {
+    return entry.form === "element" && namesElement(entry.id, e);
+}
+/** Does a Covers entry match this relationship? Endpoints resolved within `elements`, through `known` where the caller has the fleet. */
+export function coversEdge(entry, r, elements, known) {
+    return (entry.form === "edge" &&
+        namesEndpoint(entry.source, r.source, elements, known) &&
+        namesEndpoint(entry.target, r.target, elements, known));
+}
+/** Does a Covers entry name this deployment node or instance? Matched literally — see `entryResolves`. */
+export function coversDeployNode(entry, id) {
+    return entry.form === "node" && entry.id === id;
+}
+/** Does a Covers entry name this deployment edge? Both endpoints, literally. */
+export function coversDeployEdge(entry, source, target) {
+    return entry.form === "node-edge" && entry.source === source && entry.target === target;
+}
+/** Does the entry resolve to ANYTHING in scope? False is `covers.unknown`. */
+export function entryResolves(entry, scope) {
+    switch (entry.form) {
+        case "alert":
+            return scope.health.alerts.includes(entry.id);
+        case "sli":
+            return scope.health.slis.includes(entry.id);
+        case "edge":
+            return scope.relationships.some((r) => coversEdge(entry, r, scope.elements, scope.known));
+        case "element":
+            return scope.elements.some((e) => coversElement(entry, e));
+        case "node":
+            return deployedIds(scope).includes(entry.id);
+        case "node-edge":
+            // Endpoints matched literally, and only literally. The logical forms
+            // resolve a name through `serviceResolver` because an author writes
+            // `checkout-web -> payment-service` about an edge the model draws between
+            // two containers; a deployment id is already the exact path to one place
+            // on the map, there is no coarser name for it, and inventing one would
+            // make `node:eu.dcA` silently match an edge between two clusters inside
+            // it.
+            return (scope.deployment?.relationships ?? []).some((r) => r.source === entry.source && r.target === entry.target);
+    }
+}
+/** Every deployment object a `node:` entry may name: the nodes, and the instances in them. */
+function deployedIds(scope) {
+    const d = scope.deployment;
+    if (d === undefined)
+        return [];
+    return [...d.nodes.map((n) => n.id), ...d.instances.map((i) => i.id)];
+}
+/** Ids a covers.unknown hint may offer for a mistyped entry — always real ones. */
+export function coversCandidates(entry, scope) {
+    switch (entry.form) {
+        case "alert":
+            return closeIds(entry.id, scope.health.alerts).map((id) => `alert:${id}`);
+        case "sli":
+            return closeIds(entry.id, scope.health.slis).map((id) => `sli:${id}`);
+        case "edge":
+        case "node-edge":
+            // Cheap on purpose: no pairwise edge fuzzing — the sides are element
+            // names, so the element hint is the useful one.
+            return [];
+        case "element":
+            return closeIds(entry.id, [...new Set(scope.elements.map((e) => e.id))]);
+        case "node":
+            // Offered WITH the prefix, because that is the line the author has to
+            // type. A hint spelling an id the grammar would then read as an element
+            // entry is a hint that sends the reader round the loop a second time.
+            return closeIds(entry.id, [...new Set(deployedIds(scope))]).map((id) => `node:${id}`);
+    }
+}
+/**
+ * Existing ids near a misspelling — substring containment either way, else a
+ * shared 3-character prefix. Deliberately dumb: no fuzzy library for one hint,
+ * and every id offered is real, so the hint can never point at the typo itself.
+ * (Moved here from validate.ts once `covers.unknown` became its second user.)
+ */
+export function closeIds(typo, ids) {
+    const t = typo.toLowerCase();
+    return ids
+        .filter((id) => {
+        const i = id.toLowerCase();
+        return i.includes(t) || t.includes(i) || (t.length >= 3 && i.startsWith(t.slice(0, 3)));
+    })
+        .slice(0, 5);
+}
+//# sourceMappingURL=arch.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"arch.js","sourceRoot":"","sources":["../../../src/core/c4/arch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The architecture spec axis — the grammar and resolution of `Covers:` — and\n * the same endpoint join, reused, for the steps of a use case.\n *\n * A business spec will never mention the transactional outbox; that is\n * architecture, and it lives in `arch.spec.md` — same requirement/scenario\n * grammar as spec.md, same delta algebra, same merge. What is new is the\n * `Covers:` line: where a business requirement declares the OPERATIONS it\n * governs, an architecture requirement declares the MODEL OBJECTS its\n * scenarios exercise, so coverage can be derived mechanically instead of\n * trusted to an author who was never going to write the outbox down.\n *\n * Four entry forms, resolved against the documents loam already reads:\n *\n *   paymentService.db               a C4 element id — resolved against the\n *                                   in-scope elements the way every check joins\n *                                   them: the id itself, or the service the\n *                                   element stands for (binding, then title);\n *   paymentService -> kafka         an edge — each side resolved the same way,\n *                                   against the declared relationships; the\n *                                   edge may carry the relationship's kind as\n *                                   LikeC4 writes it, `paymentService -[async]->\n *                                   kafka` or `paymentService .async kafka`,\n *                                   which is read past rather than compared;\n *   alert:<id> / sli:<id>           a health signal — ids `health.yaml`\n *                                   declares (core/vocabulary/health.ts);\n *   node:<id>, node:a -> node:b     a deployment object — a node or an instance\n *                                   in the landscape's `deployment { }` model,\n *                                   matched literally. This is the form that\n *                                   lets a requirement about replication name\n *                                   the two clusters it is written about\n *                                   (ROADMAP's deployment axis).\n *\n * Resolution never reads code. An entry that resolves to nothing is the typo\n * guard (`covers.unknown`, warn); the emitters live with the other validate\n * checks, this module owns only the grammar and the matching.\n *\n * `attributeStep` used to sit at the foot of this file and now lives in\n * `./resolve/steps.ts`. It answers the same shape of question for a different\n * axis — which declared relationship backs a `dynamic view`'s hop — over the\n * same two tiers and the same cached resolver, and the seam was named here long\n * before the line limit forced it. What the two still share is\n * `./resolve/service.ts`'s `resolverFor`, which is where that cache moved with\n * it: one id→service resolver per document, serving both axes.\n */\nimport { type Elem, type Rel } from \"./likec4.js\";\nimport type { DeploymentModel } from \"./parsed/deployment.js\";\nimport { elementService, resolverFor } from \"./resolve/service.js\";\nimport type { HealthIds } from \"../vocabulary/health.js\";\n\nexport type CoversEntry =\n  | { form: \"element\"; id: string; raw: string }\n  | { form: \"edge\"; source: string; target: string; raw: string }\n  | { form: \"alert\" | \"sli\"; id: string; raw: string }\n  /**\n   * A deployment object — `node:eu.dcA.k8sA`, and the edge form\n   * `node:a -> node:b`. One prefix covers deployment NODES and the INSTANCES\n   * inside them, because both are places on the same map and a requirement\n   * about replication names an instance as readily as a datacenter. A second\n   * prefix for the second kind would make an author pick between two spellings\n   * for one question, and pick wrong.\n   */\n  | { form: \"node\"; id: string; raw: string }\n  | { form: \"node-edge\"; source: string; target: string; raw: string };\n\n/** Parse one comma-separated `Covers:` entry into its form. Never fails: an\n * unclassifiable string is an element entry that will not resolve, and the\n * covers.unknown message is a better diagnosis than a parse refusal. */\nexport function parseCoversEntry(raw: string): CoversEntry {\n  const alert = /^alert:\\s*(.+)$/.exec(raw);\n  if (alert) return { form: \"alert\", id: alert[1]!.trim(), raw };\n  const sli = /^sli:\\s*(.+)$/.exec(raw);\n  if (sli) return { form: \"sli\", id: sli[1]!.trim(), raw };\n  // An edge may be spelled with its relationship kind, the two ways LikeC4\n  // writes one — `a -[async]-> b`, and `a .async b` for a kind the\n  // specification declares — because that is how the edge itself is written\n  // and an author copies the edge line. The split used to stop at the first\n  // `->`, the one AFTER the `]`, so the bracket form became `a -[async]` ->\n  // `b`, and the dotted form, with no `->` at all, fell through to an element\n  // entry: both were `covers.unknown` while the kind-less spelling of the same\n  // edge resolved. The kind is read past, not compared: loam identifies an\n  // edge by its two endpoints (`flattenModel` keeps no kind), so either kinded\n  // spelling covers exactly what `a -> b` covers. The dotted form needs no\n  // specification to tell it from an element id: an id never holds a space,\n  // so `<id> .<kind> <id>` can be nothing else.\n  const edge =\n    /^(.+?)\\s*(?:-\\[[^\\]]*\\])?->\\s*(.+)$/.exec(raw) ?? /^(\\S+)\\s+\\.[A-Za-z_][\\w-]*\\s+(\\S+)$/.exec(raw);\n  if (edge) {\n    const source = edge[1]!.trim();\n    const target = edge[2]!.trim();\n    const from = nodeId(source);\n    const to = nodeId(target);\n    // BOTH sides, or neither. A mixed entry stays an ordinary edge whose\n    // prefixed side then resolves to nothing — which is the honest answer:\n    // there is no edge in any model with one endpoint in the logical map and\n    // one in the deployment map, so accepting a half-prefixed line would be\n    // inventing a join rather than reading one. The `->` split runs FIRST for\n    // the same reason the alert/sli tests do: `node:a -> node:b` read as a\n    // single id would be one entry that can never resolve.\n    if (from !== undefined && to !== undefined) return { form: \"node-edge\", source: from, target: to, raw };\n    return { form: \"edge\", source, target, raw };\n  }\n  const node = nodeId(raw);\n  if (node !== undefined) return { form: \"node\", id: node, raw };\n  return { form: \"element\", id: raw, raw };\n}\n\n/** The id behind a `node:` prefix, or nothing when the entry does not carry one. */\nfunction nodeId(text: string): string | undefined {\n  const m = /^node:\\s*(.+)$/.exec(text);\n  return m === null ? undefined : m[1]!.trim();\n}\n\n/**\n * What `Covers:` entries resolve against: every element and relationship in\n * view (a service's own model plus the landscape; for a feature, the delta\n * plus both), and the health ids of the service whose spec is being read.\n */\nexport interface CoverageScope {\n  elements: Elem[];\n  relationships: Rel[];\n  /**\n   * The fleet's topology, for the `node:` forms — the LANDSCAPE's deployment\n   * model and no other, even though a service's own `model.likec4` may legally\n   * declare one. Topology is a fleet-level fact for the reason a cross-service\n   * flow is: `architecture/` is the one place that already holds every edge\n   * crossing two services, and a per-service deployment block would let two\n   * documents disagree about where one container runs with nothing able to say\n   * which is right. Absent for every fleet that draws none, which is what makes\n   * a `node:` entry there resolve to nothing and report the typo.\n   */\n  deployment?: DeploymentModel;\n  health: HealthIds;\n  /**\n   * The enumerated fleet (plus the feature's own `specs/` names, where the\n   * caller has them). The Covers matcher resolves edge ENDPOINTS with it, and\n   * it must be the SAME set the caller's own findings resolve with: the finding\n   * says \"write `Covers: checkout-web -> payment-service`\" with the fleet in\n   * hand, and a matcher resolving without it answered that exact line with\n   * `covers.unknown` whenever the edge landed on a modelled container.\n   */\n  known?: ReadonlySet<string>;\n}\n\n/** Does an element entry name this element? Its id, or the service it stands for. */\nfunction namesElement(name: string, e: Elem): boolean {\n  return e.id === name || elementService(e) === name;\n}\n\n/** Does an edge entry's side name this relationship endpoint? */\nfunction namesEndpoint(\n  name: string,\n  endpointId: string,\n  elements: Elem[],\n  known?: ReadonlySet<string>,\n): boolean {\n  return endpointId === name || resolverFor(elements, known)(endpointId) === name;\n}\n\n/** Does a Covers entry match this element? (Only element entries can.) */\nexport function coversElement(entry: CoversEntry, e: Elem): boolean {\n  return entry.form === \"element\" && namesElement(entry.id, e);\n}\n\n/** Does a Covers entry match this relationship? Endpoints resolved within `elements`, through `known` where the caller has the fleet. */\nexport function coversEdge(entry: CoversEntry, r: Rel, elements: Elem[], known?: ReadonlySet<string>): boolean {\n  return (\n    entry.form === \"edge\" &&\n    namesEndpoint(entry.source, r.source, elements, known) &&\n    namesEndpoint(entry.target, r.target, elements, known)\n  );\n}\n\n/** Does a Covers entry name this deployment node or instance? Matched literally — see `entryResolves`. */\nexport function coversDeployNode(entry: CoversEntry, id: string): boolean {\n  return entry.form === \"node\" && entry.id === id;\n}\n\n/** Does a Covers entry name this deployment edge? Both endpoints, literally. */\nexport function coversDeployEdge(entry: CoversEntry, source: string, target: string): boolean {\n  return entry.form === \"node-edge\" && entry.source === source && entry.target === target;\n}\n\n/** Does the entry resolve to ANYTHING in scope? False is `covers.unknown`. */\nexport function entryResolves(entry: CoversEntry, scope: CoverageScope): boolean {\n  switch (entry.form) {\n    case \"alert\":\n      return scope.health.alerts.includes(entry.id);\n    case \"sli\":\n      return scope.health.slis.includes(entry.id);\n    case \"edge\":\n      return scope.relationships.some((r) => coversEdge(entry, r, scope.elements, scope.known));\n    case \"element\":\n      return scope.elements.some((e) => coversElement(entry, e));\n    case \"node\":\n      return deployedIds(scope).includes(entry.id);\n    case \"node-edge\":\n      // Endpoints matched literally, and only literally. The logical forms\n      // resolve a name through `serviceResolver` because an author writes\n      // `checkout-web -> payment-service` about an edge the model draws between\n      // two containers; a deployment id is already the exact path to one place\n      // on the map, there is no coarser name for it, and inventing one would\n      // make `node:eu.dcA` silently match an edge between two clusters inside\n      // it.\n      return (scope.deployment?.relationships ?? []).some(\n        (r) => r.source === entry.source && r.target === entry.target,\n      );\n  }\n}\n\n/** Every deployment object a `node:` entry may name: the nodes, and the instances in them. */\nfunction deployedIds(scope: CoverageScope): string[] {\n  const d = scope.deployment;\n  if (d === undefined) return [];\n  return [...d.nodes.map((n) => n.id), ...d.instances.map((i) => i.id)];\n}\n\n/** Ids a covers.unknown hint may offer for a mistyped entry — always real ones. */\nexport function coversCandidates(entry: CoversEntry, scope: CoverageScope): string[] {\n  switch (entry.form) {\n    case \"alert\":\n      return closeIds(entry.id, scope.health.alerts).map((id) => `alert:${id}`);\n    case \"sli\":\n      return closeIds(entry.id, scope.health.slis).map((id) => `sli:${id}`);\n    case \"edge\":\n    case \"node-edge\":\n      // Cheap on purpose: no pairwise edge fuzzing — the sides are element\n      // names, so the element hint is the useful one.\n      return [];\n    case \"element\":\n      return closeIds(entry.id, [...new Set(scope.elements.map((e) => e.id))]);\n    case \"node\":\n      // Offered WITH the prefix, because that is the line the author has to\n      // type. A hint spelling an id the grammar would then read as an element\n      // entry is a hint that sends the reader round the loop a second time.\n      return closeIds(entry.id, [...new Set(deployedIds(scope))]).map((id) => `node:${id}`);\n  }\n}\n\n/**\n * Existing ids near a misspelling — substring containment either way, else a\n * shared 3-character prefix. Deliberately dumb: no fuzzy library for one hint,\n * and every id offered is real, so the hint can never point at the typo itself.\n * (Moved here from validate.ts once `covers.unknown` became its second user.)\n */\nexport function closeIds(typo: string, ids: readonly string[]): string[] {\n  const t = typo.toLowerCase();\n  return ids\n    .filter((id) => {\n      const i = id.toLowerCase();\n      return i.includes(t) || t.includes(i) || (t.length >= 3 && i.startsWith(t.slice(0, 3)));\n    })\n    .slice(0, 5);\n}\n\n"]}

package/dist/core/c4/direction/direction.js

@@ -0,0 +1,114 @@
+/**
+ * How loam reads which way a relationship points: which end each event key
+ * binds, and which endpoints are infrastructure, whose direction carries no
+ * meaning. SCHEMA.md's "Which way an edge points" lists every reader; the two
+ * rules here are the ones more than one reader shares.
+ *
+ * `metadata { publishes }` binds the edge's SOURCE: a service produces what its
+ * own asyncapi.yaml declares an `action: send` for. `metadata { consumes }`
+ * binds its TARGET. THE ARROW FOLLOWS THE MESSAGE, producer to topic and topic
+ * to consumer, and the event spine is not the only reader of that arrow: review
+ * order's fan-in (`core/dependencies/fanin.ts`) and a use case's hop backing
+ * read the same drawing. That is why a key on the wrong end is REPORTED rather
+ * than re-bound to whichever end happens to be a service. Re-binding a reversed
+ * consume edge to its source would make the spine agree with a drawing every
+ * other reader still takes the opposite way, and on an edge between two fleet
+ * services nothing can tell which end the author meant.
+ *
+ * Through 0.2.0-alpha.10 a key on the wrong end was skipped without a word, at
+ * service scope and feature scope alike. The document validated, the metadata
+ * parsed, and the spine graded one link fewer; the `event.covered` count was
+ * the only trace. `spine.message-unbound` names that silence. Both scopes read
+ * the binding from `eventKeys` below, so the rule is written down once.
+ *
+ * It is a question about the resolved model (which endpoint of an edge a key
+ * belongs to, and what kind of thing that endpoint is), which is why it sat in
+ * `../resolve/` beside `external.ts` until that package reached six files. It
+ * was the one module there that resolves no service itself: the caller's
+ * `serviceResolver` (`../resolve/service.ts`) is what turns an endpoint into a
+ * service, so the edge reading stands as a package of its own.
+ */
+import { ancestorIds } from "../../kernel/ids/fqn/ancestors.js";
+import { INFRA_KINDS } from "../../vocabulary/maturity.js";
+import {} from "../likec4.js";
+/**
+ * Every event key a relationship carries, each with the endpoint it binds. One
+ * edge may carry both keys: a producer drawn straight to its consumer, with no
+ * broker on the map, publishes from its source and is consumed at its target.
+ */
+export function eventKeys(r) {
+    const keys = [];
+    if (r.publishes !== undefined)
+        keys.push({ direction: "publishes", message: r.publishes, bound: r.source, other: r.target });
+    if (r.consumes !== undefined)
+        keys.push({ direction: "consumes", message: r.consumes, bound: r.target, other: r.source });
+    return keys;
+}
+/**
+ * The infrastructure kind an endpoint belongs to — its own, or the nearest
+ * ancestor's among `INFRA_KINDS` — or undefined for any other element. A table
+ * nested in a `database` is part of the database, so the ancestors count.
+ *
+ * Infrastructure never initiates and never decides anything: a database, a
+ * topic or a bucket neither calls nor publishes nor consumes. That one fact
+ * answers two readers. The consumer census reads an edge between a service and
+ * infrastructure as the service USING it, whichever way the arrow points. And
+ * an event key bound to infrastructure is a key on the wrong end of its edge,
+ * since a topic is the thing between a producer and a consumer and never
+ * either of them.
+ *
+ * The limitation is `INFRA_KINDS`'s own: the hook is a kind NAME, so a broker
+ * drawn as a plain `softwareSystem` is not infrastructure here, exactly as it
+ * is not for `landscape.service-undocumented`. Callers pass the elements that
+ * may count. The census leaves out an element that stands for a service, which
+ * is a service whatever its kind.
+ */
+export function infrastructureKind(elements) {
+    const kinds = new Map();
+    for (const e of elements) {
+        const kind = e.kind.toLowerCase();
+        if (INFRA_KINDS.has(kind))
+            kinds.set(e.id, kind);
+    }
+    return (id) => {
+        for (const a of ancestorIds(id)) {
+            const kind = kinds.get(a);
+            if (kind !== undefined)
+                return kind;
+        }
+        return undefined;
+    };
+}
+/**
+ * Why a key binds nothing and how the edge is drawn so it does. A caller raises
+ * it only when the bound end is infrastructure (`infrastructureKind`) and the
+ * other end is a service of the fleet. Both halves of that test matter, and the
+ * first is deliberately narrower than "the bound end is no service". An
+ * `#external` system at the bound end is a party outside the fleet, and a key
+ * there says something true: `crm -> billingService` carrying `publishes` is an
+ * outside producer, which the producer question accepts
+ * (`./external.ts`, `spine.message-external`), and a `consumes` on an outside
+ * system is an outside consumer. Turning either round would be wrong. An edge
+ * whose bound end IS a service is graded against that service's contract, so a
+ * wrong drawing there already surfaces as `spine.message-undefined`.
+ *
+ * The fix is the same reversal for both keys: `consumes` wants the consumer at
+ * the target and `publishes` wants the producer at the source, so the edge as
+ * it should be drawn is the drawn edge turned round. Unless the edge carries
+ * BOTH keys: a service that publishes one message to a topic and consumes
+ * another from it, drawn as one arrow, always has one key on the topic, so
+ * turning the arrow round only moves the warning to the other key. The key at
+ * fault then goes onto an edge of its own, and the sentence says so.
+ */
+export function unboundSentence(r, key, kind) {
+    const end = key.direction === "publishes" ? "SOURCE" : "TARGET";
+    const both = r.publishes !== undefined && r.consumes !== undefined;
+    const fix = both
+        ? `the edge carries both keys, so one arrow cannot serve them: move ${key.direction} '${key.message}' onto an ` +
+            `edge of its own, ${r.target} -> ${r.source}`
+        : `draw it ${r.target} -> ${r.source}`;
+    return (`edge ${r.source} -> ${r.target} carries ${key.direction} '${key.message}', but \`${key.direction}\` binds the ` +
+        `edge's ${end}, and ${key.bound} is a ${kind}, which neither publishes nor consumes. The key binds nothing, so ` +
+        `no contract is checked against it. The arrow follows the message (producer to topic, topic to consumer): ${fix}`);
+}
+//# sourceMappingURL=direction.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"direction.js","sourceRoot":"","sources":["../../../../src/core/c4/direction/direction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAuB,MAAM,cAAc,CAAC;AAYnD;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,CAAM;IAC9B,MAAM,IAAI,GAAe,EAAE,CAAC;IAC5B,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7H,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1H,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAyB;IAC1D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAClC,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,CAAC,EAAU,EAAsB,EAAE;QACxC,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC;QACtC,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,CAAM,EAAE,GAAa,EAAE,IAAY;IACjE,MAAM,GAAG,GAAG,GAAG,CAAC,SAAS,KAAK,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;IAChE,MAAM,IAAI,GAAG,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC;IACnE,MAAM,GAAG,GAAG,IAAI;QACd,CAAC,CAAC,oEAAoE,GAAG,CAAC,SAAS,KAAK,GAAG,CAAC,OAAO,YAAY;YAC7G,oBAAoB,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,MAAM,EAAE;QAC/C,CAAC,CAAC,WAAW,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC;IACzC,OAAO,CACL,QAAQ,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,MAAM,YAAY,GAAG,CAAC,SAAS,KAAK,GAAG,CAAC,OAAO,YAAY,GAAG,CAAC,SAAS,eAAe;QAChH,UAAU,GAAG,SAAS,GAAG,CAAC,KAAK,SAAS,IAAI,oEAAoE;QAChH,4GAA4G,GAAG,EAAE,CAClH,CAAC;AACJ,CAAC","sourcesContent":["/**\n * How loam reads which way a relationship points: which end each event key\n * binds, and which endpoints are infrastructure, whose direction carries no\n * meaning. SCHEMA.md's \"Which way an edge points\" lists every reader; the two\n * rules here are the ones more than one reader shares.\n *\n * `metadata { publishes }` binds the edge's SOURCE: a service produces what its\n * own asyncapi.yaml declares an `action: send` for. `metadata { consumes }`\n * binds its TARGET. THE ARROW FOLLOWS THE MESSAGE, producer to topic and topic\n * to consumer, and the event spine is not the only reader of that arrow: review\n * order's fan-in (`core/dependencies/fanin.ts`) and a use case's hop backing\n * read the same drawing. That is why a key on the wrong end is REPORTED rather\n * than re-bound to whichever end happens to be a service. Re-binding a reversed\n * consume edge to its source would make the spine agree with a drawing every\n * other reader still takes the opposite way, and on an edge between two fleet\n * services nothing can tell which end the author meant.\n *\n * Through 0.2.0-alpha.10 a key on the wrong end was skipped without a word, at\n * service scope and feature scope alike. The document validated, the metadata\n * parsed, and the spine graded one link fewer; the `event.covered` count was\n * the only trace. `spine.message-unbound` names that silence. Both scopes read\n * the binding from `eventKeys` below, so the rule is written down once.\n *\n * It is a question about the resolved model (which endpoint of an edge a key\n * belongs to, and what kind of thing that endpoint is), which is why it sat in\n * `../resolve/` beside `external.ts` until that package reached six files. It\n * was the one module there that resolves no service itself: the caller's\n * `serviceResolver` (`../resolve/service.ts`) is what turns an endpoint into a\n * service, so the edge reading stands as a package of its own.\n */\nimport { ancestorIds } from \"../../kernel/ids/fqn/ancestors.js\";\nimport { INFRA_KINDS } from \"../../vocabulary/maturity.js\";\nimport { type Elem, type Rel } from \"../likec4.js\";\n\n/** One event key on one edge, with the endpoint it binds and the one it does not. */\nexport interface EventKey {\n  direction: \"publishes\" | \"consumes\";\n  message: string;\n  /** The endpoint the key binds: the source for `publishes`, the target for `consumes`. */\n  bound: string;\n  /** The other endpoint. */\n  other: string;\n}\n\n/**\n * Every event key a relationship carries, each with the endpoint it binds. One\n * edge may carry both keys: a producer drawn straight to its consumer, with no\n * broker on the map, publishes from its source and is consumed at its target.\n */\nexport function eventKeys(r: Rel): EventKey[] {\n  const keys: EventKey[] = [];\n  if (r.publishes !== undefined) keys.push({ direction: \"publishes\", message: r.publishes, bound: r.source, other: r.target });\n  if (r.consumes !== undefined) keys.push({ direction: \"consumes\", message: r.consumes, bound: r.target, other: r.source });\n  return keys;\n}\n\n/**\n * The infrastructure kind an endpoint belongs to — its own, or the nearest\n * ancestor's among `INFRA_KINDS` — or undefined for any other element. A table\n * nested in a `database` is part of the database, so the ancestors count.\n *\n * Infrastructure never initiates and never decides anything: a database, a\n * topic or a bucket neither calls nor publishes nor consumes. That one fact\n * answers two readers. The consumer census reads an edge between a service and\n * infrastructure as the service USING it, whichever way the arrow points. And\n * an event key bound to infrastructure is a key on the wrong end of its edge,\n * since a topic is the thing between a producer and a consumer and never\n * either of them.\n *\n * The limitation is `INFRA_KINDS`'s own: the hook is a kind NAME, so a broker\n * drawn as a plain `softwareSystem` is not infrastructure here, exactly as it\n * is not for `landscape.service-undocumented`. Callers pass the elements that\n * may count. The census leaves out an element that stands for a service, which\n * is a service whatever its kind.\n */\nexport function infrastructureKind(elements: readonly Elem[]): (id: string) => string | undefined {\n  const kinds = new Map<string, string>();\n  for (const e of elements) {\n    const kind = e.kind.toLowerCase();\n    if (INFRA_KINDS.has(kind)) kinds.set(e.id, kind);\n  }\n  return (id: string): string | undefined => {\n    for (const a of ancestorIds(id)) {\n      const kind = kinds.get(a);\n      if (kind !== undefined) return kind;\n    }\n    return undefined;\n  };\n}\n\n/**\n * Why a key binds nothing and how the edge is drawn so it does. A caller raises\n * it only when the bound end is infrastructure (`infrastructureKind`) and the\n * other end is a service of the fleet. Both halves of that test matter, and the\n * first is deliberately narrower than \"the bound end is no service\". An\n * `#external` system at the bound end is a party outside the fleet, and a key\n * there says something true: `crm -> billingService` carrying `publishes` is an\n * outside producer, which the producer question accepts\n * (`./external.ts`, `spine.message-external`), and a `consumes` on an outside\n * system is an outside consumer. Turning either round would be wrong. An edge\n * whose bound end IS a service is graded against that service's contract, so a\n * wrong drawing there already surfaces as `spine.message-undefined`.\n *\n * The fix is the same reversal for both keys: `consumes` wants the consumer at\n * the target and `publishes` wants the producer at the source, so the edge as\n * it should be drawn is the drawn edge turned round. Unless the edge carries\n * BOTH keys: a service that publishes one message to a topic and consumes\n * another from it, drawn as one arrow, always has one key on the topic, so\n * turning the arrow round only moves the warning to the other key. The key at\n * fault then goes onto an edge of its own, and the sentence says so.\n */\nexport function unboundSentence(r: Rel, key: EventKey, kind: string): string {\n  const end = key.direction === \"publishes\" ? \"SOURCE\" : \"TARGET\";\n  const both = r.publishes !== undefined && r.consumes !== undefined;\n  const fix = both\n    ? `the edge carries both keys, so one arrow cannot serve them: move ${key.direction} '${key.message}' onto an ` +\n      `edge of its own, ${r.target} -> ${r.source}`\n    : `draw it ${r.target} -> ${r.source}`;\n  return (\n    `edge ${r.source} -> ${r.target} carries ${key.direction} '${key.message}', but \\`${key.direction}\\` binds the ` +\n    `edge's ${end}, and ${key.bound} is a ${kind}, which neither publishes nor consumes. The key binds nothing, so ` +\n    `no contract is checked against it. The arrow follows the message (producer to topic, topic to consumer): ${fix}`\n  );\n}\n"]}

package/dist/core/c4/likec4.js

@@ -0,0 +1,243 @@
+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 { 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
+ * it opens the line the fault is on. LikeC4's `getErrors()` copies the LSP
+ * range's start line, which counts from 0, and every message used to print that
+ * raw number: the named line landed one above the fault every time
+ * (verification 2026-09-04, W6).
+ *
+ * `likec4 validate` DOES NOT AGREE, and that is deliberate rather than
+ * unnoticed. Measured at the 1.59.2 pin on a document whose fault is on file
+ * line 10: the CLI prints `Line 9:` and loam prints `L10:` for the same
+ * diagnostic — it renders the LSP index raw. Copying that would make loam's
+ * output wrong in the way the fix above repaired, so the two spellings differ
+ * by exactly one and a reader comparing them should expect it.
+ *
+ * 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) {
+    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) {
+    const elements = [...model.elements()].map((e) => {
+        // The one crossing between LikeC4's parse output and loam's type system:
+        // a `metadata { service '...' }` binding is text somebody wrote, and this
+        // is where it acquires a type that says so.
+        const bound = metaKey(e.metadata, "service");
+        return {
+            id: e.id,
+            kind: e.kind,
+            title: e.title,
+            description: descText(e.description),
+            ...(bound === undefined ? {} : { service: declaredService(bound) }),
+            tags: [...(e.tags ?? [])],
+        };
+    });
+    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`.
+        title: r.title ?? undefined,
+        op: metaKey(r.metadata, "op"),
+        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 };
+}
+/**
+ * Load and validate a single self-contained `.likec4` document, in-process
+ * (no external tool, no JVM). Returns validation errors and, if clean, the
+ * flattened elements + relationships.
+ */
+export async function loadFile(path) {
+    return loadSource(await readFile(path, "utf8"));
+}
+/**
+ * `loadFile` for text that is not (yet) on disk — what the archive merge uses
+ * to prove a computed landscape parses BEFORE anything is written.
+ */
+export async function loadSource(src) {
+    // LikeC4 owns a Langium workspace and registers a process-exit listener for
+    // it. Validation creates many short-lived instances, so every acquired
+    // instance must be disposed even on an invalid document or a failed model
+    // computation. Its logger is disabled because diagnostics are returned in
+    // LoadedDoc instead of being written out-of-band to stderr.
+    const likec4 = await LikeC4.fromSource(src, { logger: false });
+    try {
+        // Assigned, not cast: LikeC4 declares `getErrors()` as a non-nullable array
+        // 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. 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: [] };
+        }
+        // `parsedModel`, not `computedModel`: the computed stage RESOLVES every
+        // view — expanding its predicates against the model and deriving the
+        // ancestor edges a diagram needs (and computing a default view when the
+        // document declares none). loam reads what a view DECLARES and never what a
+        // view SHOWS (docs/DESIGN.md rule 26), so none of that resolution is ever
+        // wanted; it renders nothing. That work is superlinear in the number of
+        // RELATIONSHIPS, so a landscape at fleet shape turned `loam list` from under
+        // 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.
+        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