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

package/dist/core/c4/resolve/external.js

@@ -0,0 +1,51 @@
+/**
+ * The producer OUTSIDE the fleet: the `#external` element the map says sends a
+ * message no `services/<id>/` directory stands for.
+ *
+ * It sits in this package for `./attested.ts`'s reason: it is a question about
+ * the RESOLVED model — which endpoint of a `publishes` edge belongs to no
+ * service — and `serviceResolver` beside it is the one answer every join gives
+ * to that. It moved here from `commands/validate/checks/fleet-shape.ts`, where it
+ * sat beside the other checks that read tags off the drawn map, when a second
+ * reader needed the same answer: the consumer index (`core/consumers/`), which a
+ * `commands/` module can never be imported by.
+ */
+import {} from "../likec4.js";
+import {} from "../../kernel/ids/service.js";
+import { EXTERNAL_TAG } from "../../vocabulary/maturity.js";
+/**
+ * The #external element that declares it PUBLISHES this message, or null —
+ * the landscape-side half of the event spine's fleet question, whose fleet
+ * half is `../../asyncapi/producers.ts` (`spine.message-unproduced`, in
+ * `commands/validate/service/events/message-producers.ts`).
+ *
+ * Positive evidence only: an edge carrying `metadata { publishes '<msg>' }`
+ * whose source element — itself or a declared ancestor, since the edge may
+ * point out of a topic nested inside the broker — is tagged #external and
+ * resolves to no known service directory. The resolution guard is what keeps
+ * a mis-tagged internal service reading as unproduced: a tag is cheap to
+ * write, and a services/<id>/ directory outranks it.
+ */
+export function externalProducerOf(message, land, landSvcOf, known) {
+    if (land === null || land.errors.length > 0 || landSvcOf === null)
+        return null;
+    const knownIds = known;
+    const byId = new Map(land.elements.map((e) => [e.id, e]));
+    for (const r of land.relationships) {
+        if (r.publishes !== message)
+            continue;
+        if (knownIds.has(landSvcOf(r.source)))
+            continue;
+        for (let id = r.source;;) {
+            const e = byId.get(id);
+            if (e !== undefined && e.tags.includes(EXTERNAL_TAG))
+                return e.title;
+            const dot = id.lastIndexOf(".");
+            if (dot === -1)
+                break;
+            id = id.slice(0, dot);
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=external.js.map

package/dist/core/c4/resolve/external.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.js","sourceRoot":"","sources":["../../../../src/core/c4/resolve/external.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAkB,MAAM,cAAc,CAAC;AAC9C,OAAO,EAA2C,MAAM,6BAA6B,CAAC;AACtF,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAe,EACf,IAAsB,EACtB,SAAmD,EACnD,KAAgC;IAEhC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/E,MAAM,QAAQ,GAAwB,KAAK,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,SAAS,KAAK,OAAO;YAAE,SAAS;QACtC,IAAI,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAAE,SAAS;QAChD,KAAK,IAAI,EAAE,GAAG,CAAC,CAAC,MAAM,IAAM,CAAC;YAC3B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACvB,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;gBAAE,OAAO,CAAC,CAAC,KAAK,CAAC;YACrE,MAAM,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YAChC,IAAI,GAAG,KAAK,CAAC,CAAC;gBAAE,MAAM;YACtB,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["/**\n * The producer OUTSIDE the fleet: the `#external` element the map says sends a\n * message no `services/<id>/` directory stands for.\n *\n * It sits in this package for `./attested.ts`'s reason: it is a question about\n * the RESOLVED model — which endpoint of a `publishes` edge belongs to no\n * service — and `serviceResolver` beside it is the one answer every join gives\n * to that. It moved here from `commands/validate/checks/fleet-shape.ts`, where it\n * sat beside the other checks that read tags off the drawn map, when a second\n * reader needed the same answer: the consumer index (`core/consumers/`), which a\n * `commands/` module can never be imported by.\n */\nimport { type LoadedDoc } from \"../likec4.js\";\nimport { type DeclaredService, type RawServiceId } from \"../../kernel/ids/service.js\";\nimport { EXTERNAL_TAG } from \"../../vocabulary/maturity.js\";\n\n/**\n * The #external element that declares it PUBLISHES this message, or null —\n * the landscape-side half of the event spine's fleet question, whose fleet\n * half is `../../asyncapi/producers.ts` (`spine.message-unproduced`, in\n * `commands/validate/service/events/message-producers.ts`).\n *\n * Positive evidence only: an edge carrying `metadata { publishes '<msg>' }`\n * whose source element — itself or a declared ancestor, since the edge may\n * point out of a topic nested inside the broker — is tagged #external and\n * resolves to no known service directory. The resolution guard is what keeps\n * a mis-tagged internal service reading as unproduced: a tag is cheap to\n * write, and a services/<id>/ directory outranks it.\n */\nexport function externalProducerOf(\n  message: string,\n  land: LoadedDoc | null,\n  landSvcOf: ((id: string) => DeclaredService) | null,\n  known: ReadonlySet<RawServiceId>,\n): string | null {\n  if (land === null || land.errors.length > 0 || landSvcOf === null) return null;\n  const knownIds: ReadonlySet<string> = known;\n  const byId = new Map(land.elements.map((e) => [e.id, e]));\n  for (const r of land.relationships) {\n    if (r.publishes !== message) continue;\n    if (knownIds.has(landSvcOf(r.source))) continue;\n    for (let id = r.source; ; ) {\n      const e = byId.get(id);\n      if (e !== undefined && e.tags.includes(EXTERNAL_TAG)) return e.title;\n      const dot = id.lastIndexOf(\".\");\n      if (dot === -1) break;\n      id = id.slice(0, dot);\n    }\n  }\n  return null;\n}\n"]}

package/dist/core/c4/resolve/service.js

@@ -0,0 +1,174 @@
+/**
+ * Which `services/<id>/` directory a modelled element belongs to.
+ *
+ * A distinct subject from loading a document, and a distinct phase: the
+ * loader beside this package (`../likec4.ts`) turns LikeC4's parse output into
+ * loam's neutral `Elem`/`Rel` records, and everything here runs AFTER that, over
+ * those records, answering one question the model itself never states outright.
+ * It is the join every fleet-wide check rests on — the landscape↔services
+ * reconciliation, the spine's edge grouping, `Covers:` resolution, health.yaml's
+ * dependency matching — which is why `docs/DESIGN.md`'s Open-decisions table
+ * audits its call sites as a subject of their own rather than as a detail of the
+ * loader.
+ *
+ * The resolution order below is the whole of it, and its last rung is the one
+ * that lies: read that comment before adding a caller.
+ */
+import { ancestorIds, properAncestorIds } from "../../kernel/ids/fqn/ancestors.js";
+import { declaredService } from "../../kernel/ids/service.js";
+import {} from "../likec4.js";
+/**
+ * The service directory an element stands for: an explicit
+ * `metadata { service '<id>' }` binding wins, the title is the fallback.
+ *
+ * The fallback is what every docs repo written before the binding existed relies
+ * on, and it is also the trap the binding exists to close: matching on the title
+ * means renaming a box in a diagram silently unlinks it from its service, and
+ * every check that joined the two just stops finding anything.
+ */
+export function elementService(e) {
+    return e.service ?? declaredService(e.title);
+}
+/*
+ * `ancestorIds` — every id an endpoint may be filed under, nearest first:
+ * `a.b.c`, `a.b`, `a` — now lives in `core/kernel/ids/fqn/ancestors.ts`, with
+ * the reason it exists at all (a landscape may draw a service's containers, and
+ * an edge into one is still an edge into the service). It moved because five
+ * modules were each walking that chain privately; the kernel is where a leaf
+ * helper goes when the modules that want it are heavier than it is.
+ */
+/**
+ * A memoized `id -> service` resolver over one document.
+ *
+ * Resolution order, and why it is this order:
+ *
+ *  1. the nearest ancestor (the id itself first) carrying an explicit
+ *     `metadata { service '<id>' }` — a binding is a claim somebody wrote down,
+ *     so it outranks every guess;
+ *  2. the nearest ancestor whose title names a REAL `services/<id>/` directory —
+ *     positive evidence from the filesystem, available only to callers that
+ *     hand in `known`;
+ *  3. the element's own title, and finally the raw id — today's fallback, kept
+ *     LAST because it is the one that lies: it happily resolves
+ *     `paymentService.api` to "api", a service that has never existed.
+ *
+ * Built once per document and shared, because it is called inside loops over
+ * every relationship and the walk up the ancestor chain is not free.
+ */
+export function serviceResolver(elements, known) {
+    const byId = new Map(elements.map((e) => [e.id, e]));
+    const memo = new Map();
+    return (id) => {
+        const hit = memo.get(id);
+        if (hit !== undefined)
+            return hit;
+        let answer;
+        for (const candidate of ancestorIds(id)) {
+            const e = byId.get(candidate);
+            if (e?.service !== undefined) {
+                answer = e.service;
+                break;
+            }
+        }
+        if (answer === undefined && known !== undefined) {
+            for (const candidate of ancestorIds(id)) {
+                const e = byId.get(candidate);
+                if (e !== undefined && known.has(e.title)) {
+                    answer = declaredService(e.title);
+                    break;
+                }
+            }
+        }
+        if (answer === undefined) {
+            const self = byId.get(id);
+            answer = self ? elementService(self) : declaredService(id);
+        }
+        memo.set(id, answer);
+        return answer;
+    };
+}
+/**
+ * The service a relationship endpoint belongs to. An id that names no element
+ * resolves to itself, so a partial document degrades to the id rather than
+ * throwing.
+ *
+ * `known` is the set of service directories that actually exist; pass it
+ * wherever the caller has enumerated `services/`, so an edge into a modelled
+ * container resolves to the service that owns it instead of to the container's
+ * own title. Callers with a single document and no repository in hand omit it
+ * and keep the pre-existing behaviour.
+ */
+export function serviceOf(elements, id, known) {
+    return serviceResolver(elements, known)(id);
+}
+/**
+ * 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 both axes that need it keep
+ * that promise — `../arch.ts`'s `coversEdge` and `./steps.ts`'s `resolvedTier`,
+ * each exported and each handed 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();
+export 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;
+}
+/**
+ * The element each service is DRAWN as: for every service the map resolves an
+ * element to, the first service-level one in document order — an element that
+ * resolves to the service while an ancestor does too is a container of it,
+ * never a second box. The same filter and the same "first one" the adopt brief
+ * names (`core/brief/landscape.ts`), so `loam new` and `loam adopt` can never
+ * hand an author two different ids for one box.
+ *
+ * Exists so a scaffold reuses the id the map already spells instead of
+ * guessing one: a feature delta whose context ids differ from the landscape's
+ * does not line up at archive, and a guessed camelCase id on a seeded map
+ * (`svc_<id>`) never matched once.
+ */
+export function drawnServiceElements(elements, known) {
+    const svcOf = serviceResolver(elements, known);
+    const drawn = new Map();
+    for (const e of elements) {
+        const service = svcOf(e.id);
+        if (drawn.has(service) || properAncestorIds(e.id).some((a) => svcOf(a) === service))
+            continue;
+        drawn.set(service, e.id);
+    }
+    return drawn;
+}
+//# sourceMappingURL=service.js.map

package/dist/core/c4/resolve/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../../src/core/c4/resolve/service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which `services/<id>/` directory a modelled element belongs to.\n *\n * A distinct subject from loading a document, and a distinct phase: the\n * loader beside this package (`../likec4.ts`) turns LikeC4's parse output into\n * loam's neutral `Elem`/`Rel` records, and everything here runs AFTER that, over\n * those records, answering one question the model itself never states outright.\n * It is the join every fleet-wide check rests on — the landscape↔services\n * reconciliation, the spine's edge grouping, `Covers:` resolution, health.yaml's\n * dependency matching — which is why `docs/DESIGN.md`'s Open-decisions table\n * audits its call sites as a subject of their own rather than as a detail of the\n * loader.\n *\n * The resolution order below is the whole of it, and its last rung is the one\n * that lies: read that comment before adding a caller.\n */\nimport { ancestorIds, properAncestorIds } from \"../../kernel/ids/fqn/ancestors.js\";\nimport { declaredService, type DeclaredService } from \"../../kernel/ids/service.js\";\nimport { type Elem } from \"../likec4.js\";\n\n/**\n * The service directory an element stands for: an explicit\n * `metadata { service '<id>' }` binding wins, the title is the fallback.\n *\n * The fallback is what every docs repo written before the binding existed relies\n * on, and it is also the trap the binding exists to close: matching on the title\n * means renaming a box in a diagram silently unlinks it from its service, and\n * every check that joined the two just stops finding anything.\n */\nexport function elementService(e: Elem): DeclaredService {\n  return e.service ?? declaredService(e.title);\n}\n\n/*\n * `ancestorIds` — every id an endpoint may be filed under, nearest first:\n * `a.b.c`, `a.b`, `a` — now lives in `core/kernel/ids/fqn/ancestors.ts`, with\n * the reason it exists at all (a landscape may draw a service's containers, and\n * an edge into one is still an edge into the service). It moved because five\n * modules were each walking that chain privately; the kernel is where a leaf\n * helper goes when the modules that want it are heavier than it is.\n */\n\n/**\n * A memoized `id -> service` resolver over one document.\n *\n * Resolution order, and why it is this order:\n *\n *  1. the nearest ancestor (the id itself first) carrying an explicit\n *     `metadata { service '<id>' }` — a binding is a claim somebody wrote down,\n *     so it outranks every guess;\n *  2. the nearest ancestor whose title names a REAL `services/<id>/` directory —\n *     positive evidence from the filesystem, available only to callers that\n *     hand in `known`;\n *  3. the element's own title, and finally the raw id — today's fallback, kept\n *     LAST because it is the one that lies: it happily resolves\n *     `paymentService.api` to \"api\", a service that has never existed.\n *\n * Built once per document and shared, because it is called inside loops over\n * every relationship and the walk up the ancestor chain is not free.\n */\nexport function serviceResolver(\n  elements: Elem[],\n  known?: ReadonlySet<string>,\n): (id: string) => DeclaredService {\n  const byId = new Map(elements.map((e) => [e.id, e]));\n  const memo = new Map<string, DeclaredService>();\n  return (id: string): DeclaredService => {\n    const hit = memo.get(id);\n    if (hit !== undefined) return hit;\n    let answer: DeclaredService | undefined;\n    for (const candidate of ancestorIds(id)) {\n      const e = byId.get(candidate);\n      if (e?.service !== undefined) {\n        answer = e.service;\n        break;\n      }\n    }\n    if (answer === undefined && known !== undefined) {\n      for (const candidate of ancestorIds(id)) {\n        const e = byId.get(candidate);\n        if (e !== undefined && known.has(e.title)) {\n          answer = declaredService(e.title);\n          break;\n        }\n      }\n    }\n    if (answer === undefined) {\n      const self = byId.get(id);\n      answer = self ? elementService(self) : declaredService(id);\n    }\n    memo.set(id, answer);\n    return answer;\n  };\n}\n\n/**\n * The service a relationship endpoint belongs to. An id that names no element\n * resolves to itself, so a partial document degrades to the id rather than\n * throwing.\n *\n * `known` is the set of service directories that actually exist; pass it\n * wherever the caller has enumerated `services/`, so an edge into a modelled\n * container resolves to the service that owns it instead of to the container's\n * own title. Callers with a single document and no repository in hand omit it\n * and keep the pre-existing behaviour.\n */\nexport function serviceOf(elements: Elem[], id: string, known?: ReadonlySet<string>): DeclaredService {\n  return serviceResolver(elements, known)(id);\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 both axes that need it keep\n * that promise — `../arch.ts`'s `coversEdge` and `./steps.ts`'s `resolvedTier`,\n * each exported and each handed only the element 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\nexport function 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/**\n * The element each service is DRAWN as: for every service the map resolves an\n * element to, the first service-level one in document order — an element that\n * resolves to the service while an ancestor does too is a container of it,\n * never a second box. The same filter and the same \"first one\" the adopt brief\n * names (`core/brief/landscape.ts`), so `loam new` and `loam adopt` can never\n * hand an author two different ids for one box.\n *\n * Exists so a scaffold reuses the id the map already spells instead of\n * guessing one: a feature delta whose context ids differ from the landscape's\n * does not line up at archive, and a guessed camelCase id on a seeded map\n * (`svc_<id>`) never matched once.\n */\nexport function drawnServiceElements(elements: Elem[], known?: ReadonlySet<string>): Map<string, string> {\n  const svcOf = serviceResolver(elements, known);\n  const drawn = new Map<string, string>();\n  for (const e of elements) {\n    const service = svcOf(e.id);\n    if (drawn.has(service) || properAncestorIds(e.id).some((a) => svcOf(a) === service)) continue;\n    drawn.set(service, e.id);\n  }\n  return drawn;\n}\n"]}

package/dist/core/c4/resolve/steps.js

@@ -0,0 +1,290 @@
+/**
+ * Which declared relationship backs one hop of a use case, and what it says the
+ * operation is.
+ *
+ * A `dynamic view`'s hop says "web talks to orders". Answering it is the same
+ * shape of join `Covers:` performs for an edge entry one module over — same two
+ * tiers, same cached `serviceResolver` (`./service.ts`'s `resolverFor`, which
+ * both axes share), same "an endpoint names an element or the service it stands
+ * for" rule.
+ *
+ * It lived in `../arch.ts` while that file was the only home the join had, and
+ * moved here when the Covers grammar grew a fourth entry form and the file
+ * reached its line limit. The move changed nothing: the seam was already named
+ * in that file's own header, and this is the package the resolution it depends
+ * on lives in.
+ *
+ * It does NOT live beside the view reader in `../parsed/dynamic-views.ts`, and
+ * that is a rule rather than a preference: a second copy of this join is the
+ * copy that drifts, and that module may read `$data` and nothing else
+ * (docs/DESIGN.md rule 26) — it has no business holding the model join.
+ */
+import {} from "../likec4.js";
+import { resolverFor } from "./service.js";
+/**
+ * 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;
+}
+/**
+ * What a relationship can be picked by: the identifiers it DECLARES — its
+ * `metadata { op }`, and the message it `publishes` or `consumes` — and never
+ * its title, which is prose. An empty value names nothing: `op ''` parses, and
+ * every title starts with the empty string.
+ */
+function declaredNames(rel) {
+    return [rel.op, rel.publishes, rel.consumes].filter((name) => name !== undefined && name !== "");
+}
+/**
+ * The characters an operation id or a message name is spelled with. A name
+ * spelled with these alone ends where the next character is not one of them,
+ * so of two such names where one prefixes the other (`order.placed` and
+ * `order.placed.v2`, `createOrder` and `createOrder-batch`) one title never
+ * picks both. A name spelled with anything else (`orders/create`) still
+ * matches, and where it shares a prefix with another candidate's (`orders`) a
+ * title opening with the longer one picks both and the hop stays contested —
+ * which fails closed rather than guessing.
+ */
+const NAME_CHARACTER = /[A-Za-z0-9_.-]/;
+/** A letter or a digit in any script — what a word of prose starts with. */
+const WORD_CHARACTER = /[\p{L}\p{N}]/u;
+/**
+ * Does `title` open with `name`, set off as a name rather than as the first
+ * word of a sentence?
+ *
+ * Two conditions after the name. The next character must not continue it, so
+ * `createOrderBatch` is not `createOrder`. And the title must end there, or go
+ * on with punctuation — `:`, `(`, `,`, a dash — before any further word:
+ * `'createOrder — places the order'`, `'getOrder(orderId)'` and a bare
+ * `'refundPayment'` name an operation, while `'get the customer's orders'`
+ * does not name `get`. The second condition is what keeps a fleet whose
+ * operationIds are plain verbs from having its existing prose titles read as
+ * picks on the day it upgrades: the first word of a sentence is not an author
+ * naming an operation.
+ */
+function opensWith(title, name) {
+    if (!title.startsWith(name))
+        return false;
+    const rest = title.slice(name.length);
+    if (rest === "")
+        return true;
+    if (NAME_CHARACTER.test(rest.charAt(0)))
+        return false;
+    return !WORD_CHARACTER.test(rest.trimStart().charAt(0));
+}
+/**
+ * The candidates a step's title picks: those that declare the name the title
+ * opens with (`opensWith`). `[]` when the step has no title or its title opens
+ * with no candidate's name.
+ *
+ * This is how an author says which relationship a hop means when the map joins
+ * the pair by several — `orders -> payments 'authorizePayment — authorizes the
+ * payment'` against an `authorizePayment` edge and a `refundPayment` one. It
+ * exists because every other way to say it is closed, and each was MEASURED at
+ * the 1.59.2 pin before this was chosen:
+ *
+ *  - `metadata { op }` on a step is a parse error (the step accepts title,
+ *    `technology`, `description`, `notes`, `navigateTo` and the styling
+ *    properties, and no metadata block), and so are tags on a step;
+ *  - a step's KIND exists only as the arrow `-[kind]->`, which needs a
+ *    `relationship <kind>` in the specification and names a TRANSPORT — the
+ *    reserve, read and release calls one caller makes to one provider are one
+ *    kind, so a kind cannot tell them apart;
+ *  - the repair the warning used to offer alone, drawing the hop between the
+ *    elements that carry exactly one candidate, is closed on a fleet flow
+ *    wherever those elements are containers an extending model declares: a
+ *    hop naming one does not resolve in the `architecture/` project at all
+ *    (SCHEMA.md, "What loam grades is still the `architecture/` project
+ *    alone"), so between two services drawn as single elements on the map
+ *    there was no repair short of changing the map.
+ *
+ * The title is what is left, and it is the native place: a sequence diagram
+ * labels a message with the operation it invokes. The rule is deliberately
+ * narrow, because a guessed operation reads exactly like a right one in every
+ * rollup built over a flow:
+ *
+ *  - the title must START with the name, set off from any prose after it by
+ *    punctuation — a candidate's name later in the sentence ("reads the order
+ *    before release") or as its first word ("read the order") picks nothing,
+ *    since a word in a sentence is not an author naming an operation;
+ *  - it must be a candidate's DECLARED identifier, matched exactly, case
+ *    included — an operationId is case-sensitive, and a relationship's title is
+ *    prose nobody wrote to be matched;
+ *  - it only ever chooses AMONG the candidates the endpoints found, and only
+ *    when they disagree: a title can never back an unbacked hop, move a hop to
+ *    another tier, or overrule candidates that already agree.
+ */
+function pickedByTitle(rels, title) {
+    if (title === undefined)
+        return [];
+    return rels.filter((rel) => declaredNames(rel).some((name) => opensWith(title, name)));
+}
+/**
+ * A title that WOULD settle a disagreement among `rels` — the step's own
+ * `title` behind one candidate's declared name — or `undefined` when no single
+ * name does.
+ *
+ * For the `usecase.step-contested` message, whose example is only worth giving
+ * if pasting it clears the warning. So it is tried through `pickedByTitle`
+ * itself rather than read off a candidate: a name two disagreeing candidates
+ * share, or one the title already opens with to no effect, is skipped instead
+ * of offered. Operation ids are tried before message names, because the
+ * warning is about operations and the hop is more often a call.
+ */
+export function pickingTitle(rels, title) {
+    const names = [...rels.map((rel) => rel.op), ...rels.flatMap((rel) => [rel.publishes, rel.consumes])];
+    for (const name of names) {
+        if (name === undefined || name === "")
+            continue;
+        const spelled = title === undefined ? name : `${name} — ${title}`;
+        if (distinctOps(pickedByTitle(rels, spelled)).length === 1)
+            return spelled;
+    }
+    return undefined;
+}
+/** The `attributed` verdict over candidates already known to agree on `op`. */
+function attributed(pair, tier, rels, op) {
+    return { ...pair, verdict: "attributed", tier, rels, ...(op === undefined ? {} : { op }) };
+}
+/**
+ * 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. The same count decides the title's pick: a title that picks two
+ * candidates still disagreeing — one name declared as one edge's `op` and
+ * another's `publishes` — has said nothing that settles the hop, and the
+ * verdict stays `contested` over every candidate rather than over the two.
+ */
+function verdictOn(pair, tier, rels, title) {
+    if (rels.length === 0)
+        return undefined;
+    const ops = distinctOps(rels);
+    if (ops.length > 1) {
+        const picked = pickedByTitle(rels, title);
+        const pickedOps = distinctOps(picked);
+        if (pickedOps.length === 1)
+            return attributed(pair, tier, picked, pickedOps[0]);
+        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.
+    return attributed(pair, tier, rels, ops[0]);
+}
+/**
+ * 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.
+ *
+ * EMPTY when both endpoints resolve to ONE service, and that is a correction
+ * rather than an optimisation. The service tier exists for a step drawn between
+ * two SERVICES, where "which edge backs it" is answered by collapsing each
+ * side's containers to the service that owns them. Inside one service there is
+ * no service-tier reading: collapsing both sides yields the pair
+ * (svc, svc), which EVERY internal relationship of that service matches —
+ * measured at the 1.59.2 pin on a bound service drawn as three containers:
+ * a hop `api -> db` with no declared edge and two unrelated internal edges
+ * (`api -> workflow`, `workflow -> db`) came back `attributed` on tier 2 with
+ * both edges as candidates, all agreeing on no `op`. So an unbacked hop between
+ * two containers of one service could never earn `usecase.step-unbacked` — the
+ * one grade this join exists to produce — until the moment a fleet drew a
+ * service's flow over its own containers (`core/usecases/service/flows.ts`),
+ * and a landscape that draws a service as containers had the same wrong answer
+ * for the same hop all along.
+ *
+ * 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);
+    if (from === to)
+        return [];
+    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. The step's title is read inside a tier, never across
+ * them: it narrows the tier that answered and cannot reach the other.
+ *
+ * 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, step.title);
+    if (declared !== undefined)
+        return declared;
+    return verdictOn(pair, 2, resolvedTier(pair, scope), step.title) ?? { ...pair, verdict: "unbacked" };
+}
+//# sourceMappingURL=steps.js.map

package/dist/core/c4/resolve/steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../../../src/core/c4/resolve/steps.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which declared relationship backs one hop of a use case, and what it says the\n * operation is.\n *\n * A `dynamic view`'s hop says \"web talks to orders\". Answering it is the same\n * shape of join `Covers:` performs for an edge entry one module over — same two\n * tiers, same cached `serviceResolver` (`./service.ts`'s `resolverFor`, which\n * both axes share), same \"an endpoint names an element or the service it stands\n * for\" rule.\n *\n * It lived in `../arch.ts` while that file was the only home the join had, and\n * moved here when the Covers grammar grew a fourth entry form and the file\n * reached its line limit. The move changed nothing: the seam was already named\n * in that file's own header, and this is the package the resolution it depends\n * on lives in.\n *\n * It does NOT live beside the view reader in `../parsed/dynamic-views.ts`, and\n * that is a rule rather than a preference: a second copy of this join is the\n * copy that drifts, and that module 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 { resolverFor } from \"./service.js\";\nimport type { ParsedStep } from \"../parsed/dynamic-views.js\";\n\n/**\n * The fields an attribution reads off a step, and no more: the endpoints, and\n * the title that may choose between the candidates the endpoints found.\n *\n * Narrower than `ParsedStep` on purpose. Attribution must not depend on the\n * ordinal or the notes, and the title never decides WHETHER a hop is backed —\n * a hop is backed by where it points, never by what the author called it. The\n * title has exactly one job, `pickedByTitle`'s: when the relationships the\n * endpoints found disagree about the operation, a title that opens with one\n * candidate's own declared name narrows them to the ones this hop means. A\n * signature that says so is also a signature a test can satisfy with a literal\n * instead of a parsed document. Derived from `ParsedStep` rather than restated,\n * so a rename upstream is a compile error here instead of a second definition\n * that quietly disagrees.\n *\n * `title` is optional because an untitled step is legal, and that makes it the\n * one field a hand-built literal can leave out and still compile — silently\n * losing the pick. Both callers pass a `ParsedStep`, which carries it.\n */\nexport type StepReading = Pick<ParsedStep, \"source\" | \"target\" | \"isBackward\" | \"title\">;\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, or they disagree and the step's title\n *    picked the ones it means (`pickedByTitle`), in which case `rels` holds the\n *    picked candidates only. `op` is absent when that one operation is *no*\n *    operation: the relationships back the hop but none of them carries\n *    `metadata { op '…' }`.\n *  - `contested` — the candidates disagree and the title picks none of them, so\n *    loam cannot say which operation the hop exercises. `ops` lists the distinct\n *    values in candidate order, `undefined` standing for the candidate that\n *    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. The\n * one exception is an `attributed` verdict the title picked, whose `rels` holds\n * the picked candidates only: the others are what the author said the hop is\n * NOT, and a rollup over `rels` — a message census, the removal victims in\n * `core/usecases/operations.ts` — must not count them as exercised.\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: StepReading): 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 * What a relationship can be picked by: the identifiers it DECLARES — its\n * `metadata { op }`, and the message it `publishes` or `consumes` — and never\n * its title, which is prose. An empty value names nothing: `op ''` parses, and\n * every title starts with the empty string.\n */\nfunction declaredNames(rel: Rel): string[] {\n  return [rel.op, rel.publishes, rel.consumes].filter((name): name is string => name !== undefined && name !== \"\");\n}\n\n/**\n * The characters an operation id or a message name is spelled with. A name\n * spelled with these alone ends where the next character is not one of them,\n * so of two such names where one prefixes the other (`order.placed` and\n * `order.placed.v2`, `createOrder` and `createOrder-batch`) one title never\n * picks both. A name spelled with anything else (`orders/create`) still\n * matches, and where it shares a prefix with another candidate's (`orders`) a\n * title opening with the longer one picks both and the hop stays contested —\n * which fails closed rather than guessing.\n */\nconst NAME_CHARACTER = /[A-Za-z0-9_.-]/;\n\n/** A letter or a digit in any script — what a word of prose starts with. */\nconst WORD_CHARACTER = /[\\p{L}\\p{N}]/u;\n\n/**\n * Does `title` open with `name`, set off as a name rather than as the first\n * word of a sentence?\n *\n * Two conditions after the name. The next character must not continue it, so\n * `createOrderBatch` is not `createOrder`. And the title must end there, or go\n * on with punctuation — `:`, `(`, `,`, a dash — before any further word:\n * `'createOrder — places the order'`, `'getOrder(orderId)'` and a bare\n * `'refundPayment'` name an operation, while `'get the customer's orders'`\n * does not name `get`. The second condition is what keeps a fleet whose\n * operationIds are plain verbs from having its existing prose titles read as\n * picks on the day it upgrades: the first word of a sentence is not an author\n * naming an operation.\n */\nfunction opensWith(title: string, name: string): boolean {\n  if (!title.startsWith(name)) return false;\n  const rest = title.slice(name.length);\n  if (rest === \"\") return true;\n  if (NAME_CHARACTER.test(rest.charAt(0))) return false;\n  return !WORD_CHARACTER.test(rest.trimStart().charAt(0));\n}\n\n/**\n * The candidates a step's title picks: those that declare the name the title\n * opens with (`opensWith`). `[]` when the step has no title or its title opens\n * with no candidate's name.\n *\n * This is how an author says which relationship a hop means when the map joins\n * the pair by several — `orders -> payments 'authorizePayment — authorizes the\n * payment'` against an `authorizePayment` edge and a `refundPayment` one. It\n * exists because every other way to say it is closed, and each was MEASURED at\n * the 1.59.2 pin before this was chosen:\n *\n *  - `metadata { op }` on a step is a parse error (the step accepts title,\n *    `technology`, `description`, `notes`, `navigateTo` and the styling\n *    properties, and no metadata block), and so are tags on a step;\n *  - a step's KIND exists only as the arrow `-[kind]->`, which needs a\n *    `relationship <kind>` in the specification and names a TRANSPORT — the\n *    reserve, read and release calls one caller makes to one provider are one\n *    kind, so a kind cannot tell them apart;\n *  - the repair the warning used to offer alone, drawing the hop between the\n *    elements that carry exactly one candidate, is closed on a fleet flow\n *    wherever those elements are containers an extending model declares: a\n *    hop naming one does not resolve in the `architecture/` project at all\n *    (SCHEMA.md, \"What loam grades is still the `architecture/` project\n *    alone\"), so between two services drawn as single elements on the map\n *    there was no repair short of changing the map.\n *\n * The title is what is left, and it is the native place: a sequence diagram\n * labels a message with the operation it invokes. The rule is deliberately\n * narrow, because a guessed operation reads exactly like a right one in every\n * rollup built over a flow:\n *\n *  - the title must START with the name, set off from any prose after it by\n *    punctuation — a candidate's name later in the sentence (\"reads the order\n *    before release\") or as its first word (\"read the order\") picks nothing,\n *    since a word in a sentence is not an author naming an operation;\n *  - it must be a candidate's DECLARED identifier, matched exactly, case\n *    included — an operationId is case-sensitive, and a relationship's title is\n *    prose nobody wrote to be matched;\n *  - it only ever chooses AMONG the candidates the endpoints found, and only\n *    when they disagree: a title can never back an unbacked hop, move a hop to\n *    another tier, or overrule candidates that already agree.\n */\nfunction pickedByTitle(rels: readonly Rel[], title: string | undefined): Rel[] {\n  if (title === undefined) return [];\n  return rels.filter((rel) => declaredNames(rel).some((name) => opensWith(title, name)));\n}\n\n/**\n * A title that WOULD settle a disagreement among `rels` — the step's own\n * `title` behind one candidate's declared name — or `undefined` when no single\n * name does.\n *\n * For the `usecase.step-contested` message, whose example is only worth giving\n * if pasting it clears the warning. So it is tried through `pickedByTitle`\n * itself rather than read off a candidate: a name two disagreeing candidates\n * share, or one the title already opens with to no effect, is skipped instead\n * of offered. Operation ids are tried before message names, because the\n * warning is about operations and the hop is more often a call.\n */\nexport function pickingTitle(rels: readonly Rel[], title: string | undefined): string | undefined {\n  const names = [...rels.map((rel) => rel.op), ...rels.flatMap((rel) => [rel.publishes, rel.consumes])];\n  for (const name of names) {\n    if (name === undefined || name === \"\") continue;\n    const spelled = title === undefined ? name : `${name} — ${title}`;\n    if (distinctOps(pickedByTitle(rels, spelled)).length === 1) return spelled;\n  }\n  return undefined;\n}\n\n/** The `attributed` verdict over candidates already known to agree on `op`. */\nfunction attributed(pair: CallPair, tier: 1 | 2, rels: readonly Rel[], op: string | undefined): StepAttribution {\n  return { ...pair, verdict: \"attributed\", tier, rels, ...(op === undefined ? {} : { op }) };\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. The same count decides the title's pick: a title that picks two\n * candidates still disagreeing — one name declared as one edge's `op` and\n * another's `publishes` — has said nothing that settles the hop, and the\n * verdict stays `contested` over every candidate rather than over the two.\n */\nfunction verdictOn(\n  pair: CallPair,\n  tier: 1 | 2,\n  rels: readonly Rel[],\n  title: string | undefined,\n): StepAttribution | undefined {\n  if (rels.length === 0) return undefined;\n  const ops = distinctOps(rels);\n  if (ops.length > 1) {\n    const picked = pickedByTitle(rels, title);\n    const pickedOps = distinctOps(picked);\n    if (pickedOps.length === 1) return attributed(pair, tier, picked, pickedOps[0]);\n    return { ...pair, verdict: \"contested\", tier, rels, ops };\n  }\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  return attributed(pair, tier, rels, ops[0]);\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 * EMPTY when both endpoints resolve to ONE service, and that is a correction\n * rather than an optimisation. The service tier exists for a step drawn between\n * two SERVICES, where \"which edge backs it\" is answered by collapsing each\n * side's containers to the service that owns them. Inside one service there is\n * no service-tier reading: collapsing both sides yields the pair\n * (svc, svc), which EVERY internal relationship of that service matches —\n * measured at the 1.59.2 pin on a bound service drawn as three containers:\n * a hop `api -> db` with no declared edge and two unrelated internal edges\n * (`api -> workflow`, `workflow -> db`) came back `attributed` on tier 2 with\n * both edges as candidates, all agreeing on no `op`. So an unbacked hop between\n * two containers of one service could never earn `usecase.step-unbacked` — the\n * one grade this join exists to produce — until the moment a fleet drew a\n * service's flow over its own containers (`core/usecases/service/flows.ts`),\n * and a landscape that draws a service as containers had the same wrong answer\n * for the same hop all along.\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  if (from === to) return [];\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. The step's title is read inside a tier, never across\n * them: it narrows the tier that answered and cannot reach the other.\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: StepReading, 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, step.title);\n  if (declared !== undefined) return declared;\n  return verdictOn(pair, 2, resolvedTier(pair, scope), step.title) ?? { ...pair, verdict: \"unbacked\" };\n}\n"]}