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

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"]}

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

@@ -0,0 +1,154 @@
+/**
+ * Which drawn elements are SERVICES — asked of a feature's delta, the way the
+ * fleet census asks it of the map.
+ *
+ * The census (`commands/validate/fleet/census.ts`, `drawnSystems`) is the one
+ * answer `validate --all` gives: an element is graded as a service when no
+ * ancestor already stands for one, unless it is a person, somebody else's
+ * system (`#external`), infrastructure the fleet runs, or a GROUPING — an
+ * element that contains a service rather than being one. The feature-scope
+ * graders asked a narrower question of their own. `service.no-requirement-delta`
+ * asked only "is it a `softwareSystem`", so a delta's `#external` producer was
+ * called a new service that owes a requirement delta; the checklist's
+ * `service.exists` asked "is its id dotted", so the same producer became a unit
+ * of work in `loam tasks`, a top-level grouping became a service called after
+ * its title, and the new service FEAT-101 draws inside the map's own group
+ * became a container nobody had to build (the real-fleet review, 2026-10-21).
+ * After the archive, the fleet called every one of those differently.
+ *
+ * It lives in core because those graders do (`core/coherence/`,
+ * `core/verify/`), and core may not import the census. `standsForService`
+ * below is the census's own predicate rung for rung, and the census still
+ * spells its copy: the two must keep answering alike until it imports this
+ * one.
+ *
+ * THREE DELIBERATE NARROWINGS against the census, all because a delta is not a
+ * whole map. An element is looked at only through ancestors the delta DECLARES
+ * and that are themselves groupings — the map's domain or boundary drawn around
+ * the services it re-declares. A level the delta does not declare may be a
+ * living service's own element, and one that stands for no service yet groups
+ * none — a new system's box, an `#external` vendor — is what its children
+ * belong to: a container of a service with no directory yet is that service's,
+ * and an endpoint inside a vendor is the vendor's (`core/gate/partners.ts`
+ * reads it so). And a grouping must stand for no service itself: an element
+ * bound to a service IS one, whatever it contains — the census's answer too
+ * wherever it matters, since a bound or directory-titled element never reaches
+ * its undocumented pass.
+ *
+ * WHAT THE DELTA'S TAGS CANNOT SAY. A delta re-declares the living elements it
+ * attaches to as stubs, usually untagged and always without their living tags,
+ * and the merge keeps the living element's tags — so "is this #external" is a
+ * question about the map the merge leaves, not about the stub. For an element
+ * no directory answers for, `readDeltaSystem` finds the living element it
+ * stands for and asks it the same question.
+ */
+import { existsSync } from "node:fs";
+import {} from "../likec4.js";
+import { properAncestorIds } from "../../kernel/ids/fqn/ancestors.js";
+import { ACTOR_KINDS, EXTERNAL_TAG, INFRA_KINDS } from "../../vocabulary/maturity.js";
+import { drawnServiceElements, elementService } from "./service.js";
+/**
+ * Does this element stand for a `services/<id>/` directory — an explicit
+ * `metadata { service }` binding, or a title naming one `known` holds?
+ */
+function standsForService(e, known) {
+    return e.service !== undefined || known.has(e.title);
+}
+/**
+ * A GROUPING: an element that stands for no service and contains one that
+ * does — a domain, a boundary, an enterprise. There is nothing to bind on it,
+ * no requirement for it to carry and no repository that builds it; the
+ * services under it answer for themselves.
+ */
+export function groupsServices(e, elements, known) {
+    if (standsForService(e, known))
+        return false;
+    const prefix = `${e.id}.`;
+    return elements.some((c) => c.id.startsWith(prefix) && standsForService(c, known));
+}
+/**
+ * Is this element a service-level SYSTEM of ours in the document `elements`
+ * comes from: not a person, not `#external`, not unbound infrastructure, not a
+ * grouping, and drawn only inside groupings that document declares.
+ */
+function isServiceSystem(e, elements, known) {
+    const kind = e.kind.toLowerCase();
+    if (ACTOR_KINDS.has(kind) || e.tags.includes(EXTERNAL_TAG))
+        return false;
+    if (INFRA_KINDS.has(kind) && !standsForService(e, known))
+        return false;
+    const byId = new Map(elements.map((el) => [el.id, el]));
+    for (const id of properAncestorIds(e.id)) {
+        const parent = byId.get(id);
+        if (parent === undefined || !groupsServices(parent, elements, known))
+            return false;
+    }
+    return !groupsServices(e, elements, known);
+}
+/**
+ * What a tagged delta element will be on the map the merge leaves:
+ *
+ * - `none` — not a service: the delta draws it as a person, somebody else's
+ *   system, infrastructure, a grouping or something inside another element —
+ *   or it is the stub of a living element the map draws as one of those;
+ * - `living` — the stub of a service that already has a `services/<id>/`:
+ *   this feature changes it, it does not introduce it;
+ * - `drawn` — a service with no directory that the living map ALREADY draws,
+ *   so this feature re-declares it rather than introducing it either;
+ * - `service` — a service this feature introduces: its directory is the
+ *   feature's own `specs/<id>/`, or nothing has drawn it before.
+ *
+ * The living map is read only for an element no directory answers for — the
+ * one case where the stub's missing tags can be the whole answer — so the
+ * common delta, whose new services all have `specs/`, never parses it. A map
+ * that is absent or does not parse leaves the delta to answer alone, which is
+ * how every element was read before the map was asked.
+ */
+export async function readDeltaSystem(e, scope) {
+    const { elements, known } = scope;
+    if (!isServiceSystem(e, elements, known))
+        return "none";
+    const service = elementService(e);
+    if (scope.living.has(service))
+        return "living";
+    if (known.has(service))
+        return "service";
+    const map = await scope.livingMap();
+    const counterpart = map === null ? undefined : livingCounterpart(e, map, known);
+    if (map === null || counterpart === undefined)
+        return "service";
+    return isServiceSystem(counterpart, map.elements, known) ? "drawn" : "none";
+}
+/**
+ * The living map as `readDeltaSystem` reads it — the caller's
+ * `architecture/landscape.likec4` (`landscapePath`; the path arrives as an
+ * argument because `core/repo/` already imports this package), parsed at most
+ * once per reader and only when first asked; null when there is none or it
+ * does not parse. One reader for every grader that asks, so two of them can
+ * never see different maps for one element.
+ */
+export function livingMapOf(path, load) {
+    let read;
+    return () => (read ??= (async () => {
+        if (!existsSync(path))
+            return null;
+        const doc = await load(path);
+        return doc.errors.length === 0 ? doc : null;
+    })());
+}
+/**
+ * The element of the living map a delta element stands for: the same id, else
+ * the box the map DRAWS for the same service (`drawnServiceElements` — never a
+ * container of some other service that happens to share a title). Undefined
+ * when the map draws nothing of the kind, which for an element no directory
+ * answers for is what makes it new.
+ */
+function livingCounterpart(e, living, known) {
+    const byId = new Map(living.elements.map((el) => [el.id, el]));
+    const same = byId.get(e.id);
+    if (same !== undefined)
+        return same;
+    const drawn = drawnServiceElements(living.elements, known).get(elementService(e));
+    return drawn === undefined ? undefined : byId.get(drawn);
+}
+//# sourceMappingURL=systems.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"systems.js","sourceRoot":"","sources":["../../../../src/core/c4/resolve/systems.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which drawn elements are SERVICES — asked of a feature's delta, the way the\n * fleet census asks it of the map.\n *\n * The census (`commands/validate/fleet/census.ts`, `drawnSystems`) is the one\n * answer `validate --all` gives: an element is graded as a service when no\n * ancestor already stands for one, unless it is a person, somebody else's\n * system (`#external`), infrastructure the fleet runs, or a GROUPING — an\n * element that contains a service rather than being one. The feature-scope\n * graders asked a narrower question of their own. `service.no-requirement-delta`\n * asked only \"is it a `softwareSystem`\", so a delta's `#external` producer was\n * called a new service that owes a requirement delta; the checklist's\n * `service.exists` asked \"is its id dotted\", so the same producer became a unit\n * of work in `loam tasks`, a top-level grouping became a service called after\n * its title, and the new service FEAT-101 draws inside the map's own group\n * became a container nobody had to build (the real-fleet review, 2026-10-21).\n * After the archive, the fleet called every one of those differently.\n *\n * It lives in core because those graders do (`core/coherence/`,\n * `core/verify/`), and core may not import the census. `standsForService`\n * below is the census's own predicate rung for rung, and the census still\n * spells its copy: the two must keep answering alike until it imports this\n * one.\n *\n * THREE DELIBERATE NARROWINGS against the census, all because a delta is not a\n * whole map. An element is looked at only through ancestors the delta DECLARES\n * and that are themselves groupings — the map's domain or boundary drawn around\n * the services it re-declares. A level the delta does not declare may be a\n * living service's own element, and one that stands for no service yet groups\n * none — a new system's box, an `#external` vendor — is what its children\n * belong to: a container of a service with no directory yet is that service's,\n * and an endpoint inside a vendor is the vendor's (`core/gate/partners.ts`\n * reads it so). And a grouping must stand for no service itself: an element\n * bound to a service IS one, whatever it contains — the census's answer too\n * wherever it matters, since a bound or directory-titled element never reaches\n * its undocumented pass.\n *\n * WHAT THE DELTA'S TAGS CANNOT SAY. A delta re-declares the living elements it\n * attaches to as stubs, usually untagged and always without their living tags,\n * and the merge keeps the living element's tags — so \"is this #external\" is a\n * question about the map the merge leaves, not about the stub. For an element\n * no directory answers for, `readDeltaSystem` finds the living element it\n * stands for and asks it the same question.\n */\nimport { existsSync } from \"node:fs\";\nimport { type Elem, type LoadedDoc } from \"../likec4.js\";\nimport { properAncestorIds } from \"../../kernel/ids/fqn/ancestors.js\";\nimport { ACTOR_KINDS, EXTERNAL_TAG, INFRA_KINDS } from \"../../vocabulary/maturity.js\";\nimport { drawnServiceElements, elementService } from \"./service.js\";\n\n/**\n * Does this element stand for a `services/<id>/` directory — an explicit\n * `metadata { service }` binding, or a title naming one `known` holds?\n */\nfunction standsForService(e: Elem, known: ReadonlySet<string>): boolean {\n  return e.service !== undefined || known.has(e.title);\n}\n\n/**\n * A GROUPING: an element that stands for no service and contains one that\n * does — a domain, a boundary, an enterprise. There is nothing to bind on it,\n * no requirement for it to carry and no repository that builds it; the\n * services under it answer for themselves.\n */\nexport function groupsServices(e: Elem, elements: readonly Elem[], known: ReadonlySet<string>): boolean {\n  if (standsForService(e, known)) return false;\n  const prefix = `${e.id}.`;\n  return elements.some((c) => c.id.startsWith(prefix) && standsForService(c, known));\n}\n\n/**\n * Is this element a service-level SYSTEM of ours in the document `elements`\n * comes from: not a person, not `#external`, not unbound infrastructure, not a\n * grouping, and drawn only inside groupings that document declares.\n */\nfunction isServiceSystem(e: Elem, elements: readonly Elem[], known: ReadonlySet<string>): boolean {\n  const kind = e.kind.toLowerCase();\n  if (ACTOR_KINDS.has(kind) || e.tags.includes(EXTERNAL_TAG)) return false;\n  if (INFRA_KINDS.has(kind) && !standsForService(e, known)) return false;\n  const byId = new Map(elements.map((el) => [el.id, el]));\n  for (const id of properAncestorIds(e.id)) {\n    const parent = byId.get(id);\n    if (parent === undefined || !groupsServices(parent, elements, known)) return false;\n  }\n  return !groupsServices(e, elements, known);\n}\n\n/** What `readDeltaSystem` reads a tagged delta element against. */\nexport interface DeltaSystemScope {\n  /** Every element the delta declares — where its ancestors and children are looked up. */\n  elements: readonly Elem[];\n  /** The directories the merge leaves: the enumerated fleet plus the feature's own `specs/`. */\n  known: ReadonlySet<string>;\n  /** The enumerated fleet alone — the services that already have a `services/<id>/`. */\n  living: ReadonlySet<string>;\n  /** The living map (`livingMapOf`), read only when no directory answers for an element. */\n  livingMap: () => Promise<LoadedDoc | null>;\n}\n\n/**\n * What a tagged delta element will be on the map the merge leaves:\n *\n * - `none` — not a service: the delta draws it as a person, somebody else's\n *   system, infrastructure, a grouping or something inside another element —\n *   or it is the stub of a living element the map draws as one of those;\n * - `living` — the stub of a service that already has a `services/<id>/`:\n *   this feature changes it, it does not introduce it;\n * - `drawn` — a service with no directory that the living map ALREADY draws,\n *   so this feature re-declares it rather than introducing it either;\n * - `service` — a service this feature introduces: its directory is the\n *   feature's own `specs/<id>/`, or nothing has drawn it before.\n *\n * The living map is read only for an element no directory answers for — the\n * one case where the stub's missing tags can be the whole answer — so the\n * common delta, whose new services all have `specs/`, never parses it. A map\n * that is absent or does not parse leaves the delta to answer alone, which is\n * how every element was read before the map was asked.\n */\nexport async function readDeltaSystem(e: Elem, scope: DeltaSystemScope): Promise<\"none\" | \"living\" | \"drawn\" | \"service\"> {\n  const { elements, known } = scope;\n  if (!isServiceSystem(e, elements, known)) return \"none\";\n  const service = elementService(e);\n  if (scope.living.has(service)) return \"living\";\n  if (known.has(service)) return \"service\";\n  const map = await scope.livingMap();\n  const counterpart = map === null ? undefined : livingCounterpart(e, map, known);\n  if (map === null || counterpart === undefined) return \"service\";\n  return isServiceSystem(counterpart, map.elements, known) ? \"drawn\" : \"none\";\n}\n\n/**\n * The living map as `readDeltaSystem` reads it — the caller's\n * `architecture/landscape.likec4` (`landscapePath`; the path arrives as an\n * argument because `core/repo/` already imports this package), parsed at most\n * once per reader and only when first asked; null when there is none or it\n * does not parse. One reader for every grader that asks, so two of them can\n * never see different maps for one element.\n */\nexport function livingMapOf(path: string, load: (path: string) => Promise<LoadedDoc>): () => Promise<LoadedDoc | null> {\n  let read: Promise<LoadedDoc | null> | undefined;\n  return () =>\n    (read ??= (async () => {\n      if (!existsSync(path)) return null;\n      const doc = await load(path);\n      return doc.errors.length === 0 ? doc : null;\n    })());\n}\n\n/**\n * The element of the living map a delta element stands for: the same id, else\n * the box the map DRAWS for the same service (`drawnServiceElements` — never a\n * container of some other service that happens to share a title). Undefined\n * when the map draws nothing of the kind, which for an element no directory\n * answers for is what makes it new.\n */\nfunction livingCounterpart(e: Elem, living: LoadedDoc, known: ReadonlySet<string>): Elem | undefined {\n  const byId = new Map(living.elements.map((el) => [el.id, el]));\n  const same = byId.get(e.id);\n  if (same !== undefined) return same;\n  const drawn = drawnServiceElements(living.elements, known).get(elementService(e));\n  return drawn === undefined ? undefined : byId.get(drawn);\n}\n"]}