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

package/dist/core/c4/arch.js

@@ -0,0 +1,282 @@
+/**
+ * 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.
+ *
+ * Three 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;
+ *   alert:<id> / sli:<id>           a health signal — ids `health.yaml`
+ *                                   declares (core/vocabulary/health.ts).
+ *
+ * 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` at the foot of the file answers the same shape of question for
+ * a different axis. A `dynamic view`'s hop says "web talks to orders"; which
+ * declared relationship backs that hop, and what that relationship says the
+ * operation is, is the join `coversEdge` already performs — same two tiers, same
+ * cached `serviceResolver`, same "an endpoint names an element or the service it
+ * stands for" rule. It lives here rather than beside the view reader in
+ * `parsed/` because a second copy of that join is the copy that drifts, and
+ * because `parsed/dynamic-views.ts` may read `$data` and nothing else
+ * (docs/DESIGN.md rule 26) — it has no business holding the model join.
+ */
+import {} from "./likec4.js";
+import { elementService, serviceResolver } 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 };
+    const edge = /^(.+?)\s*->\s*(.+)$/.exec(raw);
+    if (edge)
+        return { form: "edge", source: edge[1].trim(), target: edge[2].trim(), raw };
+    return { form: "element", id: raw, raw };
+}
+/** 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;
+}
+/**
+ * One `id -> service` resolver per document, not one per lookup.
+ *
+ * `serviceOf` builds a fresh id map on every call, and this axis calls it twice
+ * for every relationship in scope — inside loops that already run over every
+ * relationship a service can see. `serviceResolver`'s own doc says it is "built
+ * once per document and shared"; this is where the Covers axis keeps that
+ * promise, since `coversEdge` is exported and its callers hold only the element
+ * array.
+ *
+ * A module-level cache is normally the wrong shape here, because a command runs
+ * against whatever directory it was invoked in. This one is safe: the key is the
+ * per-invocation `Elem[]` a parse produced, its value is a pure function of that
+ * key alone, and nothing in it is derived from the working directory — so two
+ * runs can never see each other's answer, and the entry dies with the document.
+ * Nothing mutates an `Elem[]` after parse.
+ *
+ * Two tiers because the fleet set is part of the answer: the same document
+ * resolves differently with and without `known`, so a cache keyed on the
+ * elements alone handed a with-fleet caller the without-fleet resolver.
+ * Callers build ONE set per run and pass the same instance through, which is
+ * what lets the inner WeakMap key on the set's identity.
+ */
+const RESOLVERS = new WeakMap();
+const FLEET_RESOLVERS = new WeakMap();
+function resolverFor(elements, known) {
+    if (known === undefined) {
+        const cached = RESOLVERS.get(elements);
+        if (cached !== undefined)
+            return cached;
+        const resolver = serviceResolver(elements);
+        RESOLVERS.set(elements, resolver);
+        return resolver;
+    }
+    let perSet = FLEET_RESOLVERS.get(elements);
+    if (perSet === undefined) {
+        perSet = new WeakMap();
+        FLEET_RESOLVERS.set(elements, perSet);
+    }
+    const cached = perSet.get(known);
+    if (cached !== undefined)
+        return cached;
+    const resolver = serviceResolver(elements, known);
+    perSet.set(known, resolver);
+    return resolver;
+}
+/** 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 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));
+    }
+}
+/** 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":
+            // 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))]);
+    }
+}
+/**
+ * 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);
+}
+/**
+ * The pair a step's backing relationship is looked up under. This is the half
+ * that mis-grades the whole fleet if it is wrong, because a reply arrow is the
+ * commonest step in any sequence diagram.
+ *
+ * MEASURED at the `likec4@1.59.2` pin, and `test/likec4-view-shape.test.ts` holds
+ * the raw form: a reply written `a <- b 'reply'` parses as
+ * `{source: "b", target: "a", isBackward: true}` — LikeC4 has ALREADY reversed
+ * the endpoints and set the flag — while the forward `b -> a` yields that same
+ * pair with no `isBackward` key at all (ABSENT, not false). So the endpoints as
+ * parsed describe the direction the MESSAGE travels, and the flag records which
+ * arrow the author typed.
+ *
+ * loam attributes a reply to the CALL it answers, so the reversal is undone
+ * here. A landscape declares `web -> orders` because that edge is the
+ * dependency; a mirror `orders -> web` for each response is not something a
+ * fleet writes down. Reading a reply hop under the message's own direction would
+ * report every return hop against such a landscape as `unbacked`, and where a
+ * fleet does draw the mirror edge it would file the two halves of one call under
+ * two operations — the call under `op 'createOrder'`, its reply under none.
+ *
+ * That is deliberately NOT what LikeC4's own computed stage does, and the
+ * difference is measured rather than assumed: that stage resolves a backward
+ * step's `relations` from the UNFLIPPED pair, so at this pin a `web <- orders`
+ * step computes to `relations: []` when only `web -> orders` exists, and to the
+ * mirror edge when only `orders -> web` does. It is answering which arrow to
+ * draw; loam is answering which operation the hop exercises, and reads what a
+ * view DECLARES rather than what it shows — which is why loam never reaches that
+ * stage at all (docs/DESIGN.md rule 26, enforced by `scripts/arch-check.mjs`).
+ * The consequence to know before changing this: where
+ * a fleet declares BOTH directions, the mirror edge is not what backs the reply
+ * here — the call is, and the mirror edge backs only a hop drawn forward along
+ * it.
+ */
+function callPair(step) {
+    return step.isBackward ? { from: step.target, to: step.source } : { from: step.source, to: step.target };
+}
+/**
+ * The distinct `op` values across candidates, first-seen order preserved.
+ *
+ * Absent is a VALUE here, not a gap to skip: a relationship carrying no `op` and
+ * one carrying `createOrder` disagree about the operation just as surely as two
+ * different ops do, and skipping the absent one would silently promote that
+ * disagreement to a confident answer. `includes` rather than a `Set` because a
+ * candidate list is the handful of relationships between one pair of endpoints,
+ * and it keeps `undefined` comparing the way the rest of this file expects.
+ */
+function distinctOps(rels) {
+    const out = [];
+    for (const r of rels)
+        if (!out.includes(r.op))
+            out.push(r.op);
+    return out;
+}
+/**
+ * The verdict one tier's candidates imply, or `undefined` when that tier found
+ * nothing and is therefore not the tier that answers.
+ *
+ * The count that decides is the DISTINCT-OP count, never the candidate count.
+ * That distinction is what makes the service tier safe: once a service is drawn
+ * as containers, `a.api -> b` and `a.worker -> b` both carrying
+ * `op 'createOrder'` are two relationships and one operation, and a verdict read
+ * off `rels.length` would convict a perfectly consistent model of contesting
+ * itself.
+ */
+function verdictOn(pair, tier, rels) {
+    if (rels.length === 0)
+        return undefined;
+    const ops = distinctOps(rels);
+    if (ops.length > 1)
+        return { ...pair, verdict: "contested", tier, rels, ops };
+    // Length is exactly one here, so the single distinct value is the answer —
+    // and `undefined` is a legitimate answer: every candidate agreed that this
+    // hop names no operation.
+    const [only] = ops;
+    return { ...pair, verdict: "attributed", tier, rels, ...(only === undefined ? {} : { op: only }) };
+}
+/**
+ * Relationships whose ENDPOINTS resolve to the same two services as the pair —
+ * the fallback tier, and the reason a step drawn between two services matches an
+ * edge drawn between two containers.
+ *
+ * Through the module's cached `resolverFor`, not a fresh `serviceResolver`: this
+ * runs once per step of every use case in the fleet, and building the id map per
+ * step is the cost that comment above `RESOLVERS` exists to prevent.
+ */
+function resolvedTier(pair, scope) {
+    const resolve = resolverFor(scope.elements, scope.known);
+    const from = resolve(pair.from);
+    const to = resolve(pair.to);
+    return scope.relationships.filter((r) => resolve(r.source) === from && resolve(r.target) === to);
+}
+/**
+ * Which relationship in the model backs one hop of a use case, and what it says
+ * the operation is.
+ *
+ * Two tiers, and the second runs ONLY when the first is empty. That ordering is
+ * load-bearing rather than an optimisation: the service tier necessarily
+ * re-finds every exact match — an endpoint that matches literally resolves to
+ * the same service trivially — so running it unconditionally would let a
+ * container-level edge with a different `op` contest a step the model already
+ * answers exactly, turning an `attributed` verdict into a `contested` one on a
+ * document nobody changed.
+ *
+ * Relationship `kind` is deliberately not part of the match, and that is
+ * measured too: at this pin `a -[http]-> b` without a `relationship http` in the
+ * `specification` block is "Could not resolve reference to RelationshipKind
+ * named 'http'" — a parse error, which under loam's standing rule means no model
+ * at all — and `test/helpers/harness.ts`'s own `LANDSCAPE` declares no
+ * relationship kinds. So narrowing by kind would mean a fix message asking an
+ * author to write a line their document does not parse.
+ */
+export function attributeStep(step, scope) {
+    const pair = callPair(step);
+    const exact = scope.relationships.filter((r) => r.source === pair.from && r.target === pair.to);
+    const declared = verdictOn(pair, 1, exact);
+    if (declared !== undefined)
+        return declared;
+    return verdictOn(pair, 2, resolvedTier(pair, scope)) ?? { ...pair, verdict: "unbacked" };
+}
+//# 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 * Three 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;\n *   alert:<id> / sli:<id>           a health signal — ids `health.yaml`\n *                                   declares (core/vocabulary/health.ts).\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` at the foot of the file answers the same shape of question for\n * a different axis. A `dynamic view`'s hop says \"web talks to orders\"; which\n * declared relationship backs that hop, and what that relationship says the\n * operation is, is the join `coversEdge` already performs — same two tiers, same\n * cached `serviceResolver`, same \"an endpoint names an element or the service it\n * stands for\" rule. It lives here rather than beside the view reader in\n * `parsed/` because a second copy of that join is the copy that drifts, and\n * because `parsed/dynamic-views.ts` may read `$data` and nothing else\n * (docs/DESIGN.md rule 26) — it has no business holding the model join.\n */\nimport { type Elem, type Rel } from \"./likec4.js\";\nimport { elementService, serviceResolver } from \"./resolve/service.js\";\nimport type { ParsedStep } from \"./parsed/dynamic-views.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/** 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  const edge = /^(.+?)\\s*->\\s*(.+)$/.exec(raw);\n  if (edge) return { form: \"edge\", source: edge[1]!.trim(), target: edge[2]!.trim(), raw };\n  return { form: \"element\", id: raw, raw };\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  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/**\n * One `id -> service` resolver per document, not one per lookup.\n *\n * `serviceOf` builds a fresh id map on every call, and this axis calls it twice\n * for every relationship in scope — inside loops that already run over every\n * relationship a service can see. `serviceResolver`'s own doc says it is \"built\n * once per document and shared\"; this is where the Covers axis keeps that\n * promise, since `coversEdge` is exported and its callers hold only the element\n * array.\n *\n * A module-level cache is normally the wrong shape here, because a command runs\n * against whatever directory it was invoked in. This one is safe: the key is the\n * per-invocation `Elem[]` a parse produced, its value is a pure function of that\n * key alone, and nothing in it is derived from the working directory — so two\n * runs can never see each other's answer, and the entry dies with the document.\n * Nothing mutates an `Elem[]` after parse.\n *\n * Two tiers because the fleet set is part of the answer: the same document\n * resolves differently with and without `known`, so a cache keyed on the\n * elements alone handed a with-fleet caller the without-fleet resolver.\n * Callers build ONE set per run and pass the same instance through, which is\n * what lets the inner WeakMap key on the set's identity.\n */\nconst RESOLVERS = new WeakMap<Elem[], (id: string) => string>();\nconst FLEET_RESOLVERS = new WeakMap<Elem[], WeakMap<ReadonlySet<string>, (id: string) => string>>();\n\nfunction resolverFor(elements: Elem[], known?: ReadonlySet<string>): (id: string) => string {\n  if (known === undefined) {\n    const cached = RESOLVERS.get(elements);\n    if (cached !== undefined) return cached;\n    const resolver = serviceResolver(elements);\n    RESOLVERS.set(elements, resolver);\n    return resolver;\n  }\n  let perSet = FLEET_RESOLVERS.get(elements);\n  if (perSet === undefined) {\n    perSet = new WeakMap();\n    FLEET_RESOLVERS.set(elements, perSet);\n  }\n  const cached = perSet.get(known);\n  if (cached !== undefined) return cached;\n  const resolver = serviceResolver(elements, known);\n  perSet.set(known, resolver);\n  return resolver;\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 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  }\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      // 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  }\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/**\n * The three fields an attribution reads off a step, and no more.\n *\n * Narrower than `ParsedStep` on purpose. Attribution must not depend on the\n * ordinal, the title or the notes — a hop is graded by where it points, never by\n * what the author called it — and a signature that says so is also a signature a\n * test can satisfy with a literal instead of a parsed document. Derived from\n * `ParsedStep` rather than restated, so a rename upstream is a compile error\n * here instead of a second definition that quietly disagrees.\n */\nexport type StepEndpoints = Pick<ParsedStep, \"source\" | \"target\" | \"isBackward\">;\n\n/**\n * What a step is attributed against: the model in view, plus the enumerated\n * fleet where the caller has it.\n *\n * A deliberate subset of `CoverageScope` rather than a reuse of it — an\n * attribution never reads `health`, and demanding one would make every caller\n * fabricate an empty `HealthIds` to ask a question that has nothing to do with\n * alerts. A `CoverageScope` is still structurally assignable here, so a caller\n * already holding the fuller scope passes it through unchanged.\n */\nexport interface StepScope {\n  elements: Elem[];\n  relationships: Rel[];\n  /** As `CoverageScope.known`, for the same reason: one set per run, shared. */\n  known?: ReadonlySet<string>;\n}\n\n/** The oriented pair a verdict is about — see `callPair` for which way round. */\ninterface CallPair {\n  from: string;\n  to: string;\n}\n\n/**\n * What the model says about one hop of a use case.\n *\n * Three variants rather than one record with optional fields, because the fields\n * are not independent: `op` is meaningful only when exactly one operation was\n * implied, `ops` only when more than one was, and an unbacked step has neither\n * and no tier either. Tagged, those states stop being constructible.\n *\n *  - `attributed` — the candidates on the matched tier agree, so the hop\n *    exercises exactly one operation. `op` is absent when that one agreed\n *    operation is *no* operation: the relationships back the hop but none of\n *    them carries `metadata { op '…' }`.\n *  - `contested` — the candidates disagree, so loam cannot say which operation\n *    the hop exercises. `ops` lists the distinct values in candidate order,\n *    `undefined` standing for the candidate that declared none.\n *  - `unbacked` — nothing in the model backs the hop on either tier. The pair is\n *    still carried, because a message about it has to be able to name the edge\n *    the author would have to draw.\n *\n * `rels` carries every candidate on the matched tier, not just the first: an\n * `attributed` verdict over two relationships is the normal shape once a service\n * is drawn as containers, and a caller pinning evidence needs all of them.\n */\nexport type StepAttribution =\n  | (CallPair & { verdict: \"attributed\"; tier: 1 | 2; rels: readonly Rel[]; op?: string })\n  | (CallPair & { verdict: \"contested\"; tier: 1 | 2; rels: readonly Rel[]; ops: readonly (string | undefined)[] })\n  | (CallPair & { verdict: \"unbacked\" });\n\n/**\n * The pair a step's backing relationship is looked up under. This is the half\n * that mis-grades the whole fleet if it is wrong, because a reply arrow is the\n * commonest step in any sequence diagram.\n *\n * MEASURED at the `likec4@1.59.2` pin, and `test/likec4-view-shape.test.ts` holds\n * the raw form: a reply written `a <- b 'reply'` parses as\n * `{source: \"b\", target: \"a\", isBackward: true}` — LikeC4 has ALREADY reversed\n * the endpoints and set the flag — while the forward `b -> a` yields that same\n * pair with no `isBackward` key at all (ABSENT, not false). So the endpoints as\n * parsed describe the direction the MESSAGE travels, and the flag records which\n * arrow the author typed.\n *\n * loam attributes a reply to the CALL it answers, so the reversal is undone\n * here. A landscape declares `web -> orders` because that edge is the\n * dependency; a mirror `orders -> web` for each response is not something a\n * fleet writes down. Reading a reply hop under the message's own direction would\n * report every return hop against such a landscape as `unbacked`, and where a\n * fleet does draw the mirror edge it would file the two halves of one call under\n * two operations — the call under `op 'createOrder'`, its reply under none.\n *\n * That is deliberately NOT what LikeC4's own computed stage does, and the\n * difference is measured rather than assumed: that stage resolves a backward\n * step's `relations` from the UNFLIPPED pair, so at this pin a `web <- orders`\n * step computes to `relations: []` when only `web -> orders` exists, and to the\n * mirror edge when only `orders -> web` does. It is answering which arrow to\n * draw; loam is answering which operation the hop exercises, and reads what a\n * view DECLARES rather than what it shows — which is why loam never reaches that\n * stage at all (docs/DESIGN.md rule 26, enforced by `scripts/arch-check.mjs`).\n * The consequence to know before changing this: where\n * a fleet declares BOTH directions, the mirror edge is not what backs the reply\n * here — the call is, and the mirror edge backs only a hop drawn forward along\n * it.\n */\nfunction callPair(step: StepEndpoints): CallPair {\n  return step.isBackward ? { from: step.target, to: step.source } : { from: step.source, to: step.target };\n}\n\n/**\n * The distinct `op` values across candidates, first-seen order preserved.\n *\n * Absent is a VALUE here, not a gap to skip: a relationship carrying no `op` and\n * one carrying `createOrder` disagree about the operation just as surely as two\n * different ops do, and skipping the absent one would silently promote that\n * disagreement to a confident answer. `includes` rather than a `Set` because a\n * candidate list is the handful of relationships between one pair of endpoints,\n * and it keeps `undefined` comparing the way the rest of this file expects.\n */\nfunction distinctOps(rels: readonly Rel[]): (string | undefined)[] {\n  const out: (string | undefined)[] = [];\n  for (const r of rels) if (!out.includes(r.op)) out.push(r.op);\n  return out;\n}\n\n/**\n * The verdict one tier's candidates imply, or `undefined` when that tier found\n * nothing and is therefore not the tier that answers.\n *\n * The count that decides is the DISTINCT-OP count, never the candidate count.\n * That distinction is what makes the service tier safe: once a service is drawn\n * as containers, `a.api -> b` and `a.worker -> b` both carrying\n * `op 'createOrder'` are two relationships and one operation, and a verdict read\n * off `rels.length` would convict a perfectly consistent model of contesting\n * itself.\n */\nfunction verdictOn(pair: CallPair, tier: 1 | 2, rels: readonly Rel[]): StepAttribution | undefined {\n  if (rels.length === 0) return undefined;\n  const ops = distinctOps(rels);\n  if (ops.length > 1) return { ...pair, verdict: \"contested\", tier, rels, ops };\n  // Length is exactly one here, so the single distinct value is the answer —\n  // and `undefined` is a legitimate answer: every candidate agreed that this\n  // hop names no operation.\n  const [only] = ops;\n  return { ...pair, verdict: \"attributed\", tier, rels, ...(only === undefined ? {} : { op: only }) };\n}\n\n/**\n * Relationships whose ENDPOINTS resolve to the same two services as the pair —\n * the fallback tier, and the reason a step drawn between two services matches an\n * edge drawn between two containers.\n *\n * Through the module's cached `resolverFor`, not a fresh `serviceResolver`: this\n * runs once per step of every use case in the fleet, and building the id map per\n * step is the cost that comment above `RESOLVERS` exists to prevent.\n */\nfunction resolvedTier(pair: CallPair, scope: StepScope): Rel[] {\n  const resolve = resolverFor(scope.elements, scope.known);\n  const from = resolve(pair.from);\n  const to = resolve(pair.to);\n  return scope.relationships.filter((r) => resolve(r.source) === from && resolve(r.target) === to);\n}\n\n/**\n * Which relationship in the model backs one hop of a use case, and what it says\n * the operation is.\n *\n * Two tiers, and the second runs ONLY when the first is empty. That ordering is\n * load-bearing rather than an optimisation: the service tier necessarily\n * re-finds every exact match — an endpoint that matches literally resolves to\n * the same service trivially — so running it unconditionally would let a\n * container-level edge with a different `op` contest a step the model already\n * answers exactly, turning an `attributed` verdict into a `contested` one on a\n * document nobody changed.\n *\n * Relationship `kind` is deliberately not part of the match, and that is\n * measured too: at this pin `a -[http]-> b` without a `relationship http` in the\n * `specification` block is \"Could not resolve reference to RelationshipKind\n * named 'http'\" — a parse error, which under loam's standing rule means no model\n * at all — and `test/helpers/harness.ts`'s own `LANDSCAPE` declares no\n * relationship kinds. So narrowing by kind would mean a fix message asking an\n * author to write a line their document does not parse.\n */\nexport function attributeStep(step: StepEndpoints, scope: StepScope): StepAttribution {\n  const pair = callPair(step);\n  const exact = scope.relationships.filter((r) => r.source === pair.from && r.target === pair.to);\n  const declared = verdictOn(pair, 1, exact);\n  if (declared !== undefined) return declared;\n  return verdictOn(pair, 2, resolvedTier(pair, scope)) ?? { ...pair, verdict: \"unbacked\" };\n}\n"]}

package/dist/core/c4/likec4.js

@@ -0,0 +1,88 @@
+import { readFile } from "node:fs/promises";
+import { LikeC4 } from "likec4";
+import { declaredService } from "../kernel/ids/service.js";
+import { readDynamicViews } from "./parsed/dynamic-views.js";
+import { readViewIds } from "./parsed/view-ids.js";
+import { readSpecification } from "./parsed/specification.js";
+import { descText, metaKey } from "./parsed/values.js";
+/** 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 ?? [])],
+    }));
+    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.
+        const errors = 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.
+        const model = (await likec4.parsedModel());
+        return {
+            errors,
+            specification: readSpecification(model.specification),
+            views: readDynamicViews(model),
+            viewIds: readViewIds(model),
+            ...flattenModel(model),
+        };
+    }
+    finally {
+        await likec4.dispose();
+    }
+}
+//# sourceMappingURL=likec4.js.map

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

@@ -0,0 +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 { readViewIds, type ViewIdClaim } from \"./parsed/view-ids.js\";\nimport { readSpecification, type DocSpecification } from \"./parsed/specification.js\";\nimport { descText, metaKey } from \"./parsed/values.js\";\n\n/** A parse/validation issue reported by LikeC4. */\nexport interface LikeC4Error {\n  message: string;\n  line?: number;\n  sourceFsPath?: string;\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\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      ...flattenModel(model),\n    };\n  } finally {\n    await likec4.dispose();\n  }\n}\n"]}

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

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

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

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