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

package/dist/core/usecases/fleet.js

@@ -13,22 +13,48 @@
  * without starting LikeC4 at all.
  *
  * THE CHEAP GATE IS A BYTE SCAN, and it is sound rather than heuristic. A view
- * is a use case only if it carries a reserved tag — `#cap-<slug>` or
- * `#req-<slug>`, `isUseCase` below is the whole test — and LikeC4 refuses an
- * undeclared tag, so a fleet with a use case has the literal text `cap-` or
- * `req-` in the file that declares the view AND in the file that declares the
- * tag. A document set in which no file contains either substring therefore
- * declares no use case, and `{ views: [] }` is the correct answer, not an
- * evasion. The scan reads bytes rather than decoded text on purpose: it is
- * looking for an ASCII substring, and `readFile(path, "utf8")` on a document
- * that is not UTF-8 would substitute U+FFFD and could hide it.
- *
- * BOTH PREFIXES, because the gate and the predicate answer one question and a
+ * is a use case only if it carries a reserved tag — `#cap-<slug>`,
+ * `#req-<slug>` or `#suite-<name>`, `isUseCase` below is the whole test — and
+ * a view carries a tag only through a REFERENCE written in the document that
+ * declares the view. LikeC4's grammar spells every tag reference `HashId`: the
+ * `#` terminal, then the name. Measured at the 1.59.2 pin, the `#` is
+ * mandatory — a bare `suite-smoke` in a view body fails to resolve, and
+ * `tags #suite-smoke` fails to parse — but LikeC4's four hidden tokens may sit
+ * between the `#` and the name: `# suite-smoke`, a `#` ending one line with
+ * the name on the next, and a block comment in between all parse to the tag
+ * `suite-smoke`. So the scan finds each `#`, skips exactly those tokens
+ * (`referencesReservedTag`), and asks whether a reserved prefix starts there.
+ * A document set in which no file does declares no use case, however badly it
+ * parses, and `{ views: [] }` is the correct answer, not an evasion. A
+ * `tag cap-…` line in a `specification` block is a declaration, not a
+ * reference, and does not open the gate: a tag no view carries opts nothing
+ * in.
+ *
+ * THE `#` IS WHAT KEEPS PROSE OUT. The scan used to look for the bare
+ * substrings, so a view titled 'What the e2e-suite-a job exercises', or a
+ * comment naming `req-` in passing, opened it. At fleet scope that cost one
+ * project load, because a map that does not parse is `landscape.invalid`
+ * whether or not the gate opens; at service scope (`./service/flows.ts`) it
+ * turned an untagged hand-drawn sibling that did not parse into
+ * `usecase.flow-invalid` — an error, exit 1 — over a diagram that opted
+ * nothing in. A `#` followed by a reserved prefix still opens it wherever it
+ * is written, a comment or a description included: that over-scan is
+ * accepted, because it is spelled as the tag syntax, and the scan must never
+ * be narrower than the parser.
+ *
+ * The scan reads bytes rather than decoded text on purpose: it looks for
+ * ASCII, and `readFile(path, "utf8")` on a document that is not UTF-8 would
+ * substitute U+FFFD and could hide it. Decoded as latin1 instead, every byte is
+ * one character, and the bytes of a multi-byte sequence never read as ASCII.
+ *
+ * EVERY PREFIX, because the gate and the predicate answer one question and a
  * gate narrower than the predicate is silence rather than a smaller answer. A
- * fleet whose only flow is tagged `#req-` alone declares `tag req-…` and no
- * `cap-` anywhere, so a `cap-`-only scan returned `false` and none of the five
- * readers ever loaded the project — the widening below would have fixed nothing
- * without this one.
+ * fleet whose only flow is tagged `#req-` alone writes `cap-` nowhere, so a
+ * `cap-`-only scan returned `false` and none of the five readers ever loaded
+ * the project — the widening below would have fixed nothing without this one.
+ * The suite prefix joined for the same reason the day a `#suite-`-only view
+ * became a use case: both now read one list, `USE_CASE_TAG_PREFIXES`, so a
+ * fourth prefix cannot be added to one and not the other.
  *
  * The gate FAILS CLOSED. A document this module cannot open is treated as one
  * that might mention the prefix, so the project load happens and reports the
@@ -39,22 +65,38 @@
 import { readFile } from "node:fs/promises";
 import { CAP_TAG_PREFIX, REQ_TAG_PREFIX } from "../capabilities/usecase-join.js";
 import { architectureProjectDocuments, loadArchitecture } from "../c4/project/architecture.js";
+import { errorText } from "../c4/likec4.js";
 import { serviceResolver } from "../c4/resolve/service.js";
+import { SUITE_TAG_PREFIX } from "./suites/suites.js";
 /**
- * Does any document in the set even mention a reserved tag prefix?
+ * Every reserved prefix that opts a view in — the one list both the byte gate
+ * and `isUseCase` read, so the two cannot disagree about which tags make a use
+ * case. `cap-` and `req-` are spelled by the capability join that resolves
+ * them; `suite-` by `./suites/suites.ts`, which groups by it and resolves
+ * nothing, because a suite name is checked by LikeC4's own undeclared-tag
+ * refusal rather than by a vocabulary.
+ */
+const USE_CASE_TAG_PREFIXES = [CAP_TAG_PREFIX, REQ_TAG_PREFIX, SUITE_TAG_PREFIX];
+/**
+ * Does any document in the set reference a reserved tag — a `#`, then only
+ * LikeC4's hidden tokens, then `cap-`, `req-` or `suite-`?
  *
  * Sequential and short-circuiting ON PURPOSE — the usual "no await in a loop"
  * rule is about independent work that all has to finish, and this loop exists
  * precisely so that a fleet whose first file declares a use case stops reading
  * the other ninety-nine.
  *
- * `req-` is the looser of the two substrings and that is accepted knowingly: a
- * document mentioning it in prose costs one project load loam would otherwise
- * have skipped, which is a slower right answer. Dropping it costs a wrong one.
+ * What the scan lets through costs differently at its two callers, and the
+ * header above names both. A `#req-…` written in a comment opens it: at fleet
+ * scope that is one project load loam could have skipped, a slower right
+ * answer; at service scope it loads a sibling set that may not parse, and a
+ * broken one is then `usecase.flow-invalid` — an error, but over a document
+ * that spelled the tag syntax. Prose without the `#` opens neither. Missing a
+ * reference would cost a wrong answer at both: a use case nobody graded.
  *
  * Exported for the service-scope reader (`./service/flows.ts`), which asks the
  * same question of the `.likec4` files beside one `model.likec4`: a sibling set
- * that mentions neither prefix declares no use case, so a hand-drawn
+ * that references no reserved tag declares no use case, so a hand-drawn
  * `views.likec4` costs that service no LikeC4 workspace. One gate, two callers,
  * because a second byte scan spelled in the service package would be free to
  * disagree with this one about which prefixes opt a view in.
@@ -63,7 +105,7 @@ export async function mentionsTagPrefix(paths) {
     for (const path of paths) {
         try {
             const bytes = await readFile(path);
-            if (bytes.includes(CAP_TAG_PREFIX) || bytes.includes(REQ_TAG_PREFIX))
+            if (referencesReservedTag(bytes.toString("latin1")))
                 return true;
         }
         catch {
@@ -75,14 +117,105 @@ export async function mentionsTagPrefix(paths) {
     }
     return false;
 }
+/**
+ * Is a reserved prefix written as a tag reference anywhere in this text? Every
+ * `#` is tried, wherever it stands — in a view body, a comment, a string —
+ * because the scan may over-approximate the parser and never under-approximate
+ * it.
+ *
+ * A text with no `#`, or with no reserved prefix anywhere in it, cannot answer
+ * yes, so it is answered before the table below is built: that is nearly every
+ * document, and it costs those two native searches and no allocation.
+ *
+ * Exported for its own test (test/usecase-byte-gate.test.ts), which holds it to
+ * the walk the first version made from each `#` over crafted inputs, and holds
+ * its cost to one pass over inputs that walk took minutes on.
+ */
+export function referencesReservedTag(text) {
+    const first = text.indexOf("#");
+    if (first === -1 || !USE_CASE_TAG_PREFIXES.some((prefix) => text.includes(prefix)))
+        return false;
+    const nameAt = hiddenRunEnds(text);
+    for (let hash = first; hash !== -1; hash = text.indexOf("#", hash + 1)) {
+        const name = nameAt[hash + 1];
+        if (USE_CASE_TAG_PREFIXES.some((prefix) => text.startsWith(prefix, name)))
+            return true;
+    }
+    return false;
+}
+/**
+ * For every position in `text`, where the next token LikeC4 would read starts
+ * from there: past whitespace, line breaks, `//` line comments and block
+ * comments — the four terminals the 1.59.2 grammar marks hidden (`WS`, `NL`,
+ * `LINE_COMMENT`, `BLOCK_COMMENT`), which its lexer drops between the `#` of a
+ * tag reference and the name. Index `text.length` is the end itself.
+ *
+ * ONE PASS, FROM THE END, so every answer is built from answers already known
+ * and the whole table costs one visit per character, however the `#`s and the
+ * comments interleave. The first version walked forward from each `#` instead,
+ * and a run of hidden tokens with `#`s inside it was re-walked once per `#`:
+ * `#/*` repeated took 17.6 s on 100 KB (each unclosed opener searched the rest
+ * of the file for a closer), and `#//` repeated on one line, or the same `#/*`
+ * run closed once at its end, were quadratic the same way. Remembering only
+ * where the closer search last failed would have fixed the first of those
+ * three and left the other two; nothing short of reusing every answer fixes
+ * the shape, and this scan runs over every document on every reader's path.
+ *
+ * A hand loop rather than one regular expression: a repeated group of
+ * alternatives that can each consume a comment backtracks exponentially on a
+ * long run of slashes. An UNTERMINATED block comment is not one LikeC4 can lex
+ * as a comment, so only the `/*` itself is stepped over and a name written
+ * after it still counts: that can open the gate more often, never less, and
+ * the document cannot parse anyway — the load the gate opens is what reports
+ * it. The closer is searched from two past the opener, so the `*` of an opener
+ * never doubles as the `*` of its closer, exactly as the lexer reads it.
+ */
+function hiddenRunEnds(text) {
+    const end = new Int32Array(text.length + 1);
+    end[text.length] = text.length;
+    // The nearest line break at or after the position being read, and the
+    // nearest `*/` at or after the NEXT position and the one after that — an
+    // opener at `at` searches from `at + 2`, and the pass meets that position
+    // before it meets `at`. -1 is "none".
+    let lineBreak = text.length;
+    let closeFromNext = -1;
+    let closeFromAfterNext = -1;
+    for (let at = text.length - 1; at >= 0; at -= 1) {
+        const char = text[at];
+        const closeFromHere = char === "*" && text[at + 1] === "/" ? at : closeFromNext;
+        if (char === "\r" || char === "\n")
+            lineBreak = at;
+        if (char === " " || char === "\t" || char === "\r" || char === "\n") {
+            end[at] = end[at + 1];
+        }
+        else if (char === "/" && text[at + 1] === "/") {
+            // The comment runs to the line break and leaves it unread; the break is
+            // whitespace, so the run goes on from there. No break: the text ends.
+            end[at] = end[lineBreak];
+        }
+        else if (char === "/" && text[at + 1] === "*") {
+            end[at] = closeFromAfterNext === -1 ? end[at + 2] : end[closeFromAfterNext + 2];
+        }
+        else {
+            end[at] = at;
+        }
+        closeFromAfterNext = closeFromNext;
+        closeFromNext = closeFromHere;
+    }
+    return end;
+}
 /**
  * Is this a use case at all? — the ONE answer, for `validate` and every reader
  * alike.
  *
- * EITHER RESERVED PREFIX OPTS A VIEW IN. A view carrying `#req-CHK-ONCE` and no
+ * ANY RESERVED PREFIX OPTS A VIEW IN. A view carrying `#req-CHK-ONCE` and no
  * `#cap-` tag is an author who asked to be graded and forgot half the claim; it
  * earns `usecase.requirement-unresolved`'s `unscoped` arm rather than silence,
- * and SCHEMA.md has said so since the tag shipped.
+ * and SCHEMA.md has said so since the tag shipped. A view carrying only
+ * `#suite-<name>` claims no capability and no requirement and is still a use
+ * case — the owner's call, recorded in SCHEMA.md: putting a journey in a suite
+ * is asking for it to be run, and a journey a test stand is provisioned from
+ * must be held to the model hop by hop like any other.
  *
  * It is exported because it was the asymmetry, not the rule, that was the
  * defect. `validate --all` widened here and the readers did not, so a
@@ -93,9 +226,10 @@ export async function mentionsTagPrefix(paths) {
  * that spells `startsWith` itself is a second answer waiting to drift.
  *
  * The parameter is the smallest shape the test needs rather than `ParsedView`,
- * so a caller holding a view-like row does not have to build one to ask. Both
- * prefix tests match their resolver's exactly, case included, so a view can
- * never be opted in here and read as untagged in `resolveCapabilityTags`.
+ * so a caller holding a view-like row does not have to build one to ask. Every
+ * prefix test matches its reader's exactly, case included, so a view can never
+ * be opted in here and read as untagged in `resolveCapabilityTags` or
+ * `suiteNames`.
  *
  * NOT the same question as `flowsClaiming`'s. That one asks which flows claim
  * capability X and matches the whole `cap-<slug>` tag; a `#req-`-only view
@@ -103,7 +237,7 @@ export async function mentionsTagPrefix(paths) {
  * counting as a use case here.
  */
 export function isUseCase(view) {
-    return view.tags.some((tag) => tag.startsWith(CAP_TAG_PREFIX) || tag.startsWith(REQ_TAG_PREFIX));
+    return view.tags.some((tag) => USE_CASE_TAG_PREFIXES.some((prefix) => tag.startsWith(prefix)));
 }
 /**
  * The fleet's declared use cases, with the model they are drawn over.
@@ -132,18 +266,31 @@ export async function readUseCases(req) {
     const documents = await architectureProjectDocuments(req.docsDir);
     if (!(await mentionsTagPrefix(documents)))
         return none;
-    const doc = await loadArchitecture(req.docsDir);
+    return useCasesIn(await loadArchitecture(req.docsDir), req.known);
+}
+/**
+ * The use cases of an `architecture/` project somebody has ALREADY loaded —
+ * `readUseCases` minus its byte gate and its load.
+ *
+ * For a reader that needs the project anyway: the consumer index
+ * (`core/consumers/`) reads the project's edges and its hops off one load, and
+ * going through `readUseCases` there would parse the same documents a second
+ * time behind a gate whose whole purpose is to skip a load that has already
+ * happened. The answer is the same one: a project with no reserved-tag view
+ * yields `read` with no views, exactly what the gate returns without loading.
+ */
+export function useCasesIn(doc, known) {
     // loam's standing rule, at project altitude: errors mean no model. A use-case
     // file with one unresolved element leaves the whole project unusable, and
     // grading a flow against half a map is the wrong answer this refuses to give.
     if (doc.errors.length > 0) {
-        return { kind: "unreadable", errors: doc.errors.map((e) => e.message) };
+        return { kind: "unreadable", errors: doc.errors.map(errorText) };
     }
     return {
         kind: "read",
         views: (doc.views ?? []).filter(isUseCase),
-        model: { elements: doc.elements, relationships: doc.relationships, known: req.known },
-        resolve: serviceResolver(doc.elements, req.known),
+        model: { elements: doc.elements, relationships: doc.relationships, known },
+        resolve: serviceResolver(doc.elements, known),
     };
 }
 //# sourceMappingURL=fleet.js.map

package/dist/core/usecases/fleet.js.map

@@ -1 +1 @@
-{"version":3,"file":"fleet.js","sourceRoot":"","sources":["../../../src/core/usecases/fleet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjF,OAAO,EAAE,4BAA4B,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAC/F,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AA0D3D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAAwB;IAC9D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC;gBAAE,OAAO,IAAI,CAAC;QACpF,CAAC;QAAC,MAAM,CAAC;YACP,2EAA2E;YAC3E,uEAAuE;YACvE,uEAAuE;YACvE,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,SAAS,CAAC,IAAiC;IACzD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC;AACnG,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAmB;IACpD,MAAM,IAAI,GAAgB;QACxB,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,EAAE;QACT,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE;QAC5D,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE;KACpB,CAAC;IACF,0EAA0E;IAC1E,wEAAwE;IACxE,4EAA4E;IAC5E,yEAAyE;IACzE,yEAAyE;IACzE,wEAAwE;IACxE,yEAAyE;IACzE,sEAAsE;IACtE,MAAM,SAAS,GAAG,MAAM,4BAA4B,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAClE,IAAI,CAAC,CAAC,MAAM,iBAAiB,CAAC,SAAS,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvD,MAAM,GAAG,GAAG,MAAM,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAChD,8EAA8E;IAC9E,0EAA0E;IAC1E,8EAA8E;IAC9E,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC1E,CAAC;IACD,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;QAC1C,KAAK,EAAE,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE;QACrF,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC;KAClD,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The fleet's use cases, read once for whoever asks — and NOT read at all when\n * the fleet demonstrably has none.\n *\n * `validate --all` grades use cases as part of a run that was already loading\n * `architecture/` as a LikeC4 project, so it pays nothing extra. Every reader\n * added in phase 4 is in a different position: `loam diff`, `loam delta`,\n * `loam context` and `loam explore` did not load the fleet map as a project\n * before, and `loam delta` in particular sits in `/loam-implement`'s inner loop\n * — a Langium workspace spin-up there is felt on every iteration of somebody's\n * day. So this module's whole job is to answer \"which use cases does the fleet\n * declare?\" and, in the common case where the answer is none, to answer it\n * without starting LikeC4 at all.\n *\n * THE CHEAP GATE IS A BYTE SCAN, and it is sound rather than heuristic. A view\n * is a use case only if it carries a reserved tag — `#cap-<slug>` or\n * `#req-<slug>`, `isUseCase` below is the whole test — and LikeC4 refuses an\n * undeclared tag, so a fleet with a use case has the literal text `cap-` or\n * `req-` in the file that declares the view AND in the file that declares the\n * tag. A document set in which no file contains either substring therefore\n * declares no use case, and `{ views: [] }` is the correct answer, not an\n * evasion. The scan reads bytes rather than decoded text on purpose: it is\n * looking for an ASCII substring, and `readFile(path, \"utf8\")` on a document\n * that is not UTF-8 would substitute U+FFFD and could hide it.\n *\n * BOTH PREFIXES, because the gate and the predicate answer one question and a\n * gate narrower than the predicate is silence rather than a smaller answer. A\n * fleet whose only flow is tagged `#req-` alone declares `tag req-…` and no\n * `cap-` anywhere, so a `cap-`-only scan returned `false` and none of the five\n * readers ever loaded the project — the widening below would have fixed nothing\n * without this one.\n *\n * The gate FAILS CLOSED. A document this module cannot open is treated as one\n * that might mention the prefix, so the project load happens and reports the\n * failure as a hole. The alternative — reading an EACCES as \"no tag here\" — is\n * the fail-open shape docs/CODE-STYLE.md forbids at a validator, arriving in an\n * optimisation.\n */\nimport { readFile } from \"node:fs/promises\";\nimport type { StepScope } from \"../c4/resolve/steps.js\";\nimport { CAP_TAG_PREFIX, REQ_TAG_PREFIX } from \"../capabilities/usecase-join.js\";\nimport type { ParsedView } from \"../c4/parsed/dynamic-views.js\";\nimport { architectureProjectDocuments, loadArchitecture } from \"../c4/project/architecture.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * What the fleet's use cases are, or the honest refusal to say.\n *\n * Two variants rather than a record with an `unreadable` flag, because the\n * fields are not independent: a project that did not parse has no elements to\n * resolve against and no views to grade, and a caller handed\n * `{ views: [], unreadable: true }` is one `.length` check away from printing\n * \"no use cases touch this service\" about a fleet nobody could read. Tagged,\n * that state stops being constructible — every caller has to name the\n * `unreadable` arm to get at the views.\n *\n * `read` with an empty `views` is the ordinary answer for a fleet that draws no\n * use cases, and it is exactly what the cheap gate returns without loading\n * anything: the gate is an optimisation over a question with a known answer,\n * never a third verdict.\n */\nexport type UseCaseScan =\n  | {\n      kind: \"read\";\n      /** The reserved-tag views ONLY — `isUseCase` below is the opt-in, and the only one. */\n      views: readonly ParsedView[];\n      /**\n       * What a hop is attributed against, built ONCE per scan. It carries the\n       * fleet set that `resolve` below was built from, which is what stops\n       * \"which service is this element\" being answered one way by\n       * `attributeStep`'s fallback tier and another by a caller's own join —\n       * the same reason `validate`'s `StepGrading` holds both together.\n       *\n       * `known` is REQUIRED here while `StepScope` leaves it optional, and the\n       * narrowing is load-bearing rather than tidy: every scan is built from a\n       * `UseCaseRequest` that has one, so a consumer reading `model.known` was\n       * writing an `undefined` branch that could not be reached and could not be\n       * tested. A `StepScope` is still what `attributeStep` receives.\n       */\n      model: StepScope & { known: ReadonlySet<string> };\n      /** One element→service resolver for the whole scan, built with the enumerated fleet. */\n      resolve: (id: string) => string;\n    }\n  | {\n      kind: \"unreadable\";\n      /** LikeC4's own messages, so a caller can say WHICH document broke. */\n      errors: string[];\n    };\n\nexport interface UseCaseRequest {\n  docsDir: DocsDir;\n  /**\n   * The enumerated fleet. It rides into the resolver for the reason every other\n   * edge join carries it: without it, a step drawn into a modelled container\n   * `payment.api` resolves to a service called \"api\" that has never existed\n   * (docs/DESIGN.md's serviceResolver-known row).\n   */\n  known: ReadonlySet<string>;\n}\n\n/**\n * Does any document in the set even mention a reserved tag prefix?\n *\n * Sequential and short-circuiting ON PURPOSE — the usual \"no await in a loop\"\n * rule is about independent work that all has to finish, and this loop exists\n * precisely so that a fleet whose first file declares a use case stops reading\n * the other ninety-nine.\n *\n * `req-` is the looser of the two substrings and that is accepted knowingly: a\n * document mentioning it in prose costs one project load loam would otherwise\n * have skipped, which is a slower right answer. Dropping it costs a wrong one.\n *\n * Exported for the service-scope reader (`./service/flows.ts`), which asks the\n * same question of the `.likec4` files beside one `model.likec4`: a sibling set\n * that mentions neither prefix declares no use case, so a hand-drawn\n * `views.likec4` costs that service no LikeC4 workspace. One gate, two callers,\n * because a second byte scan spelled in the service package would be free to\n * disagree with this one about which prefixes opt a view in.\n */\nexport async function mentionsTagPrefix(paths: readonly string[]): Promise<boolean> {\n  for (const path of paths) {\n    try {\n      const bytes = await readFile(path);\n      if (bytes.includes(CAP_TAG_PREFIX) || bytes.includes(REQ_TAG_PREFIX)) return true;\n    } catch {\n      // Unreadable is not \"no tag\": the project load below owns that failure and\n      // will report it as a hole naming the document. Answering `false` here\n      // would let an unopenable file grade the fleet as having no use cases.\n      return true;\n    }\n  }\n  return false;\n}\n\n/**\n * Is this a use case at all? — the ONE answer, for `validate` and every reader\n * alike.\n *\n * EITHER RESERVED PREFIX OPTS A VIEW IN. A view carrying `#req-CHK-ONCE` and no\n * `#cap-` tag is an author who asked to be graded and forgot half the claim; it\n * earns `usecase.requirement-unresolved`'s `unscoped` arm rather than silence,\n * and SCHEMA.md has said so since the tag shipped.\n *\n * It is exported because it was the asymmetry, not the rule, that was the\n * defect. `validate --all` widened here and the readers did not, so a\n * `#req-`-only flow was graded hop by hop by the gate and invisible to `loam\n * diff`, `delta`, `status`, the packs and `list capabilities` — a fleet where\n * the gate and the report disagree about what exists, which is worse than\n * either answer alone. One predicate is what stops that recurring: a caller\n * that spells `startsWith` itself is a second answer waiting to drift.\n *\n * The parameter is the smallest shape the test needs rather than `ParsedView`,\n * so a caller holding a view-like row does not have to build one to ask. Both\n * prefix tests match their resolver's exactly, case included, so a view can\n * never be opted in here and read as untagged in `resolveCapabilityTags`.\n *\n * NOT the same question as `flowsClaiming`'s. That one asks which flows claim\n * capability X and matches the whole `cap-<slug>` tag; a `#req-`-only view\n * claims none, and it is correct for it to stay out of that answer while\n * counting as a use case here.\n */\nexport function isUseCase(view: { tags: readonly string[] }): boolean {\n  return view.tags.some((tag) => tag.startsWith(CAP_TAG_PREFIX) || tag.startsWith(REQ_TAG_PREFIX));\n}\n\n/**\n * The fleet's declared use cases, with the model they are drawn over.\n *\n * Reads only, throws nothing, and refuses nothing: every failure is the\n * `unreadable` arm. Callers memoise this per invocation — nothing is cached\n * here, because a module-level cache keyed on a docsDir would leak across the\n * `chdir`-per-test processes AGENTS.md warns about and, in a long-running host,\n * across invocations.\n */\nexport async function readUseCases(req: UseCaseRequest): Promise<UseCaseScan> {\n  const none: UseCaseScan = {\n    kind: \"read\",\n    views: [],\n    model: { elements: [], relationships: [], known: req.known },\n    resolve: (id) => id,\n  };\n  // EXACTLY the documents `loadArchitecture` will load two lines down, root\n  // `exclude` and all — `architectureProjectDocuments` is that one answer\n  // (`c4/project/architecture.ts`). The gate used to walk `architecture/` for\n  // itself and skip the exclude, which could only over-scan: the byte gate\n  // reading a document the loader then drops decides \"there might be a use\n  // case here\" and pays for a project load that finds none. Never a wrong\n  // answer, but two lists that disagree about what the project is, and the\n  // next reader to take the wider one for the project's would be wrong.\n  const documents = await architectureProjectDocuments(req.docsDir);\n  if (!(await mentionsTagPrefix(documents))) return none;\n\n  const doc = await loadArchitecture(req.docsDir);\n  // loam's standing rule, at project altitude: errors mean no model. A use-case\n  // file with one unresolved element leaves the whole project unusable, and\n  // grading a flow against half a map is the wrong answer this refuses to give.\n  if (doc.errors.length > 0) {\n    return { kind: \"unreadable\", errors: doc.errors.map((e) => e.message) };\n  }\n  return {\n    kind: \"read\",\n    views: (doc.views ?? []).filter(isUseCase),\n    model: { elements: doc.elements, relationships: doc.relationships, known: req.known },\n    resolve: serviceResolver(doc.elements, req.known),\n  };\n}\n"]}
+{"version":3,"file":"fleet.js","sourceRoot":"","sources":["../../../src/core/usecases/fleet.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet's use cases, read once for whoever asks — and NOT read at all when\n * the fleet demonstrably has none.\n *\n * `validate --all` grades use cases as part of a run that was already loading\n * `architecture/` as a LikeC4 project, so it pays nothing extra. Every reader\n * added in phase 4 is in a different position: `loam diff`, `loam delta`,\n * `loam context` and `loam explore` did not load the fleet map as a project\n * before, and `loam delta` in particular sits in `/loam-implement`'s inner loop\n * — a Langium workspace spin-up there is felt on every iteration of somebody's\n * day. So this module's whole job is to answer \"which use cases does the fleet\n * declare?\" and, in the common case where the answer is none, to answer it\n * without starting LikeC4 at all.\n *\n * THE CHEAP GATE IS A BYTE SCAN, and it is sound rather than heuristic. A view\n * is a use case only if it carries a reserved tag — `#cap-<slug>`,\n * `#req-<slug>` or `#suite-<name>`, `isUseCase` below is the whole test — and\n * a view carries a tag only through a REFERENCE written in the document that\n * declares the view. LikeC4's grammar spells every tag reference `HashId`: the\n * `#` terminal, then the name. Measured at the 1.59.2 pin, the `#` is\n * mandatory — a bare `suite-smoke` in a view body fails to resolve, and\n * `tags #suite-smoke` fails to parse — but LikeC4's four hidden tokens may sit\n * between the `#` and the name: `# suite-smoke`, a `#` ending one line with\n * the name on the next, and a block comment in between all parse to the tag\n * `suite-smoke`. So the scan finds each `#`, skips exactly those tokens\n * (`referencesReservedTag`), and asks whether a reserved prefix starts there.\n * A document set in which no file does declares no use case, however badly it\n * parses, and `{ views: [] }` is the correct answer, not an evasion. A\n * `tag cap-…` line in a `specification` block is a declaration, not a\n * reference, and does not open the gate: a tag no view carries opts nothing\n * in.\n *\n * THE `#` IS WHAT KEEPS PROSE OUT. The scan used to look for the bare\n * substrings, so a view titled 'What the e2e-suite-a job exercises', or a\n * comment naming `req-` in passing, opened it. At fleet scope that cost one\n * project load, because a map that does not parse is `landscape.invalid`\n * whether or not the gate opens; at service scope (`./service/flows.ts`) it\n * turned an untagged hand-drawn sibling that did not parse into\n * `usecase.flow-invalid` — an error, exit 1 — over a diagram that opted\n * nothing in. A `#` followed by a reserved prefix still opens it wherever it\n * is written, a comment or a description included: that over-scan is\n * accepted, because it is spelled as the tag syntax, and the scan must never\n * be narrower than the parser.\n *\n * The scan reads bytes rather than decoded text on purpose: it looks for\n * ASCII, and `readFile(path, \"utf8\")` on a document that is not UTF-8 would\n * substitute U+FFFD and could hide it. Decoded as latin1 instead, every byte is\n * one character, and the bytes of a multi-byte sequence never read as ASCII.\n *\n * EVERY PREFIX, because the gate and the predicate answer one question and a\n * gate narrower than the predicate is silence rather than a smaller answer. A\n * fleet whose only flow is tagged `#req-` alone writes `cap-` nowhere, so a\n * `cap-`-only scan returned `false` and none of the five readers ever loaded\n * the project — the widening below would have fixed nothing without this one.\n * The suite prefix joined for the same reason the day a `#suite-`-only view\n * became a use case: both now read one list, `USE_CASE_TAG_PREFIXES`, so a\n * fourth prefix cannot be added to one and not the other.\n *\n * The gate FAILS CLOSED. A document this module cannot open is treated as one\n * that might mention the prefix, so the project load happens and reports the\n * failure as a hole. The alternative — reading an EACCES as \"no tag here\" — is\n * the fail-open shape docs/CODE-STYLE.md forbids at a validator, arriving in an\n * optimisation.\n */\nimport { readFile } from \"node:fs/promises\";\nimport type { StepScope } from \"../c4/resolve/steps.js\";\nimport { CAP_TAG_PREFIX, REQ_TAG_PREFIX } from \"../capabilities/usecase-join.js\";\nimport type { ParsedView } from \"../c4/parsed/dynamic-views.js\";\nimport { architectureProjectDocuments, loadArchitecture } from \"../c4/project/architecture.js\";\nimport { errorText, type LoadedDoc } from \"../c4/likec4.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport { SUITE_TAG_PREFIX } from \"./suites/suites.js\";\n\n/**\n * Every reserved prefix that opts a view in — the one list both the byte gate\n * and `isUseCase` read, so the two cannot disagree about which tags make a use\n * case. `cap-` and `req-` are spelled by the capability join that resolves\n * them; `suite-` by `./suites/suites.ts`, which groups by it and resolves\n * nothing, because a suite name is checked by LikeC4's own undeclared-tag\n * refusal rather than by a vocabulary.\n */\nconst USE_CASE_TAG_PREFIXES: readonly string[] = [CAP_TAG_PREFIX, REQ_TAG_PREFIX, SUITE_TAG_PREFIX];\n\n/**\n * What the fleet's use cases are, or the honest refusal to say.\n *\n * Two variants rather than a record with an `unreadable` flag, because the\n * fields are not independent: a project that did not parse has no elements to\n * resolve against and no views to grade, and a caller handed\n * `{ views: [], unreadable: true }` is one `.length` check away from printing\n * \"no use cases touch this service\" about a fleet nobody could read. Tagged,\n * that state stops being constructible — every caller has to name the\n * `unreadable` arm to get at the views.\n *\n * `read` with an empty `views` is the ordinary answer for a fleet that draws no\n * use cases, and it is exactly what the cheap gate returns without loading\n * anything: the gate is an optimisation over a question with a known answer,\n * never a third verdict.\n */\nexport type UseCaseScan =\n  | {\n      kind: \"read\";\n      /** The reserved-tag views ONLY — `isUseCase` below is the opt-in, and the only one. */\n      views: readonly ParsedView[];\n      /**\n       * What a hop is attributed against, built ONCE per scan. It carries the\n       * fleet set that `resolve` below was built from, which is what stops\n       * \"which service is this element\" being answered one way by\n       * `attributeStep`'s fallback tier and another by a caller's own join —\n       * the same reason `validate`'s `StepGrading` holds both together.\n       *\n       * `known` is REQUIRED here while `StepScope` leaves it optional, and the\n       * narrowing is load-bearing rather than tidy: every scan is built from a\n       * `UseCaseRequest` that has one, so a consumer reading `model.known` was\n       * writing an `undefined` branch that could not be reached and could not be\n       * tested. A `StepScope` is still what `attributeStep` receives.\n       */\n      model: StepScope & { known: ReadonlySet<string> };\n      /** One element→service resolver for the whole scan, built with the enumerated fleet. */\n      resolve: (id: string) => string;\n    }\n  | {\n      kind: \"unreadable\";\n      /**\n       * LikeC4's own messages, so a caller can say WHICH document broke —\n       * spelled through `errorText` like every other diagnostic loam prints.\n       * They used to travel raw, so the 1-based line was missing and one\n       * dropped quote in the map put a 143 KB parser message into the\n       * `useCaseScan.error` of every service's `loam context --json`.\n       */\n      errors: string[];\n    };\n\nexport interface UseCaseRequest {\n  docsDir: DocsDir;\n  /**\n   * The enumerated fleet. It rides into the resolver for the reason every other\n   * edge join carries it: without it, a step drawn into a modelled container\n   * `payment.api` resolves to a service called \"api\" that has never existed\n   * (docs/DESIGN.md's serviceResolver-known row).\n   */\n  known: ReadonlySet<string>;\n}\n\n/**\n * Does any document in the set reference a reserved tag — a `#`, then only\n * LikeC4's hidden tokens, then `cap-`, `req-` or `suite-`?\n *\n * Sequential and short-circuiting ON PURPOSE — the usual \"no await in a loop\"\n * rule is about independent work that all has to finish, and this loop exists\n * precisely so that a fleet whose first file declares a use case stops reading\n * the other ninety-nine.\n *\n * What the scan lets through costs differently at its two callers, and the\n * header above names both. A `#req-…` written in a comment opens it: at fleet\n * scope that is one project load loam could have skipped, a slower right\n * answer; at service scope it loads a sibling set that may not parse, and a\n * broken one is then `usecase.flow-invalid` — an error, but over a document\n * that spelled the tag syntax. Prose without the `#` opens neither. Missing a\n * reference would cost a wrong answer at both: a use case nobody graded.\n *\n * Exported for the service-scope reader (`./service/flows.ts`), which asks the\n * same question of the `.likec4` files beside one `model.likec4`: a sibling set\n * that references no reserved tag declares no use case, so a hand-drawn\n * `views.likec4` costs that service no LikeC4 workspace. One gate, two callers,\n * because a second byte scan spelled in the service package would be free to\n * disagree with this one about which prefixes opt a view in.\n */\nexport async function mentionsTagPrefix(paths: readonly string[]): Promise<boolean> {\n  for (const path of paths) {\n    try {\n      const bytes = await readFile(path);\n      if (referencesReservedTag(bytes.toString(\"latin1\"))) return true;\n    } catch {\n      // Unreadable is not \"no tag\": the project load below owns that failure and\n      // will report it as a hole naming the document. Answering `false` here\n      // would let an unopenable file grade the fleet as having no use cases.\n      return true;\n    }\n  }\n  return false;\n}\n\n/**\n * Is a reserved prefix written as a tag reference anywhere in this text? Every\n * `#` is tried, wherever it stands — in a view body, a comment, a string —\n * because the scan may over-approximate the parser and never under-approximate\n * it.\n *\n * A text with no `#`, or with no reserved prefix anywhere in it, cannot answer\n * yes, so it is answered before the table below is built: that is nearly every\n * document, and it costs those two native searches and no allocation.\n *\n * Exported for its own test (test/usecase-byte-gate.test.ts), which holds it to\n * the walk the first version made from each `#` over crafted inputs, and holds\n * its cost to one pass over inputs that walk took minutes on.\n */\nexport function referencesReservedTag(text: string): boolean {\n  const first = text.indexOf(\"#\");\n  if (first === -1 || !USE_CASE_TAG_PREFIXES.some((prefix) => text.includes(prefix))) return false;\n  const nameAt = hiddenRunEnds(text);\n  for (let hash = first; hash !== -1; hash = text.indexOf(\"#\", hash + 1)) {\n    const name = nameAt[hash + 1]!;\n    if (USE_CASE_TAG_PREFIXES.some((prefix) => text.startsWith(prefix, name))) return true;\n  }\n  return false;\n}\n\n/**\n * For every position in `text`, where the next token LikeC4 would read starts\n * from there: past whitespace, line breaks, `//` line comments and block\n * comments — the four terminals the 1.59.2 grammar marks hidden (`WS`, `NL`,\n * `LINE_COMMENT`, `BLOCK_COMMENT`), which its lexer drops between the `#` of a\n * tag reference and the name. Index `text.length` is the end itself.\n *\n * ONE PASS, FROM THE END, so every answer is built from answers already known\n * and the whole table costs one visit per character, however the `#`s and the\n * comments interleave. The first version walked forward from each `#` instead,\n * and a run of hidden tokens with `#`s inside it was re-walked once per `#`:\n * `#/*` repeated took 17.6 s on 100 KB (each unclosed opener searched the rest\n * of the file for a closer), and `#//` repeated on one line, or the same `#/*`\n * run closed once at its end, were quadratic the same way. Remembering only\n * where the closer search last failed would have fixed the first of those\n * three and left the other two; nothing short of reusing every answer fixes\n * the shape, and this scan runs over every document on every reader's path.\n *\n * A hand loop rather than one regular expression: a repeated group of\n * alternatives that can each consume a comment backtracks exponentially on a\n * long run of slashes. An UNTERMINATED block comment is not one LikeC4 can lex\n * as a comment, so only the `/*` itself is stepped over and a name written\n * after it still counts: that can open the gate more often, never less, and\n * the document cannot parse anyway — the load the gate opens is what reports\n * it. The closer is searched from two past the opener, so the `*` of an opener\n * never doubles as the `*` of its closer, exactly as the lexer reads it.\n */\nfunction hiddenRunEnds(text: string): Int32Array {\n  const end = new Int32Array(text.length + 1);\n  end[text.length] = text.length;\n  // The nearest line break at or after the position being read, and the\n  // nearest `*/` at or after the NEXT position and the one after that — an\n  // opener at `at` searches from `at + 2`, and the pass meets that position\n  // before it meets `at`. -1 is \"none\".\n  let lineBreak = text.length;\n  let closeFromNext = -1;\n  let closeFromAfterNext = -1;\n  for (let at = text.length - 1; at >= 0; at -= 1) {\n    const char = text[at];\n    const closeFromHere = char === \"*\" && text[at + 1] === \"/\" ? at : closeFromNext;\n    if (char === \"\\r\" || char === \"\\n\") lineBreak = at;\n    if (char === \" \" || char === \"\\t\" || char === \"\\r\" || char === \"\\n\") {\n      end[at] = end[at + 1]!;\n    } else if (char === \"/\" && text[at + 1] === \"/\") {\n      // The comment runs to the line break and leaves it unread; the break is\n      // whitespace, so the run goes on from there. No break: the text ends.\n      end[at] = end[lineBreak]!;\n    } else if (char === \"/\" && text[at + 1] === \"*\") {\n      end[at] = closeFromAfterNext === -1 ? end[at + 2]! : end[closeFromAfterNext + 2]!;\n    } else {\n      end[at] = at;\n    }\n    closeFromAfterNext = closeFromNext;\n    closeFromNext = closeFromHere;\n  }\n  return end;\n}\n\n/**\n * Is this a use case at all? — the ONE answer, for `validate` and every reader\n * alike.\n *\n * ANY RESERVED PREFIX OPTS A VIEW IN. A view carrying `#req-CHK-ONCE` and no\n * `#cap-` tag is an author who asked to be graded and forgot half the claim; it\n * earns `usecase.requirement-unresolved`'s `unscoped` arm rather than silence,\n * and SCHEMA.md has said so since the tag shipped. A view carrying only\n * `#suite-<name>` claims no capability and no requirement and is still a use\n * case — the owner's call, recorded in SCHEMA.md: putting a journey in a suite\n * is asking for it to be run, and a journey a test stand is provisioned from\n * must be held to the model hop by hop like any other.\n *\n * It is exported because it was the asymmetry, not the rule, that was the\n * defect. `validate --all` widened here and the readers did not, so a\n * `#req-`-only flow was graded hop by hop by the gate and invisible to `loam\n * diff`, `delta`, `status`, the packs and `list capabilities` — a fleet where\n * the gate and the report disagree about what exists, which is worse than\n * either answer alone. One predicate is what stops that recurring: a caller\n * that spells `startsWith` itself is a second answer waiting to drift.\n *\n * The parameter is the smallest shape the test needs rather than `ParsedView`,\n * so a caller holding a view-like row does not have to build one to ask. Every\n * prefix test matches its reader's exactly, case included, so a view can never\n * be opted in here and read as untagged in `resolveCapabilityTags` or\n * `suiteNames`.\n *\n * NOT the same question as `flowsClaiming`'s. That one asks which flows claim\n * capability X and matches the whole `cap-<slug>` tag; a `#req-`-only view\n * claims none, and it is correct for it to stay out of that answer while\n * counting as a use case here.\n */\nexport function isUseCase(view: { tags: readonly string[] }): boolean {\n  return view.tags.some((tag) => USE_CASE_TAG_PREFIXES.some((prefix) => tag.startsWith(prefix)));\n}\n\n/**\n * The fleet's declared use cases, with the model they are drawn over.\n *\n * Reads only, throws nothing, and refuses nothing: every failure is the\n * `unreadable` arm. Callers memoise this per invocation — nothing is cached\n * here, because a module-level cache keyed on a docsDir would leak across the\n * `chdir`-per-test processes AGENTS.md warns about and, in a long-running host,\n * across invocations.\n */\nexport async function readUseCases(req: UseCaseRequest): Promise<UseCaseScan> {\n  const none: UseCaseScan = {\n    kind: \"read\",\n    views: [],\n    model: { elements: [], relationships: [], known: req.known },\n    resolve: (id) => id,\n  };\n  // EXACTLY the documents `loadArchitecture` will load two lines down, root\n  // `exclude` and all — `architectureProjectDocuments` is that one answer\n  // (`c4/project/architecture.ts`). The gate used to walk `architecture/` for\n  // itself and skip the exclude, which could only over-scan: the byte gate\n  // reading a document the loader then drops decides \"there might be a use\n  // case here\" and pays for a project load that finds none. Never a wrong\n  // answer, but two lists that disagree about what the project is, and the\n  // next reader to take the wider one for the project's would be wrong.\n  const documents = await architectureProjectDocuments(req.docsDir);\n  if (!(await mentionsTagPrefix(documents))) return none;\n\n  return useCasesIn(await loadArchitecture(req.docsDir), req.known);\n}\n\n/**\n * The use cases of an `architecture/` project somebody has ALREADY loaded —\n * `readUseCases` minus its byte gate and its load.\n *\n * For a reader that needs the project anyway: the consumer index\n * (`core/consumers/`) reads the project's edges and its hops off one load, and\n * going through `readUseCases` there would parse the same documents a second\n * time behind a gate whose whole purpose is to skip a load that has already\n * happened. The answer is the same one: a project with no reserved-tag view\n * yields `read` with no views, exactly what the gate returns without loading.\n */\nexport function useCasesIn(doc: LoadedDoc, known: ReadonlySet<string>): UseCaseScan {\n  // loam's standing rule, at project altitude: errors mean no model. A use-case\n  // file with one unresolved element leaves the whole project unusable, and\n  // grading a flow against half a map is the wrong answer this refuses to give.\n  if (doc.errors.length > 0) {\n    return { kind: \"unreadable\", errors: doc.errors.map(errorText) };\n  }\n  return {\n    kind: \"read\",\n    views: (doc.views ?? []).filter(isUseCase),\n    model: { elements: doc.elements, relationships: doc.relationships, known },\n    resolve: serviceResolver(doc.elements, known),\n  };\n}\n"]}

package/dist/core/usecases/operations.js

@@ -7,8 +7,8 @@
  * requirement is a heading in somebody else's spec, while "step 4 of Checkout
  * stops working" is the fact a human weighs a pull request against. This module
  * is the join that produces that sentence, and it produces NOTHING ELSE — no
- * finding, no code, no severity. `core/diff/victims.ts` folds its answers into
- * the `details[]` of the two codes that already exist.
+ * finding, no code, no severity. `core/consumers/consumers.ts` folds its
+ * answers into the `details[]` of the two codes that already exist.
  *
  * ## Attributed is a victim; contested is a suspension
  *
@@ -49,8 +49,9 @@ function hops(scan) {
  * The flows one removed operation breaks, and the ones loam cannot answer for.
  *
  * An `unreadable` scan contributes NOTHING — neither break nor suspension — and
- * that is `core/diff/victims.ts`'s own landscape doctrine applied one axis over:
- * an unreadable fleet map proves nothing either way, `landscape.invalid` is
+ * that is the consumer index's own landscape doctrine (`livingMap` in
+ * `core/consumers/current.ts`, which reads the map for every consumer
+ * question) applied one axis over: an unreadable fleet map proves nothing either way, `landscape.invalid` is
  * validate's finding to make, and inventing doubt out of a parse error would
  * point the reviewer at a file their change never touched. The caller reports
  * the hole; this join stays quiet about it.

package/dist/core/usecases/operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../src/core/usecases/operations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which hops of which business flows a contract removal breaks.\n *\n * `loam diff --base` already answers \"who still depends on this operation\" with\n * landscape edges and other services' living requirements. Both are true and\n * neither is the sentence a reviewer wants: an edge is a line in a diagram and a\n * requirement is a heading in somebody else's spec, while \"step 4 of Checkout\n * stops working\" is the fact a human weighs a pull request against. This module\n * is the join that produces that sentence, and it produces NOTHING ELSE — no\n * finding, no code, no severity. `core/diff/victims.ts` folds its answers into\n * the `details[]` of the two codes that already exist.\n *\n * ## Attributed is a victim; contested is a suspension\n *\n * The distinction is the whole reason this module is careful rather than a\n * filter. `attributeStep` (core/c4/resolve/steps.ts) grades a hop by the DISTINCT-op\n * count across the relationships backing it:\n *\n *  - `attributed` with `op === X` means every relationship behind the hop agrees\n *    the hop exercises X. Remove X and the flow breaks at that hop. That is\n *    positive evidence, and it is a victim.\n *  - `contested` means the relationships DISAGREE, so loam does not know which\n *    operation the hop exercises. It must not claim the flow breaks — a guessed\n *    victim reads exactly like a real one and turns a warn into an error on\n *    somebody's PR — and it must not go silent either, because silence here is\n *    the fail-open shape `ConsumerScan.suspended` exists to forbid. It is a\n *    suspension: loam says it could not answer.\n *\n * A contested hop is suspended only when X is among its candidate operations.\n * That is not a noise trade, it is the honest boundary: the candidates ARE the\n * relationships backing the hop, so an operation none of them names is an\n * operation the hop cannot be exercising under any reading of the disagreement.\n * Suspending every contested hop in the fleet on every removal would report\n * doubt loam does not actually have.\n *\n * An `unbacked` hop is neither. Nothing in the model backs it, so it names no\n * operation of anybody's contract — `usecase.step-unbacked` is already the error\n * that convicts it, and repeating that here would file a modelling defect\n * against whoever happened to remove an endpoint.\n */\nimport { attributeStep } from \"../c4/resolve/steps.js\";\nimport type { ParsedStep, ParsedView } from \"../c4/parsed/dynamic-views.js\";\nimport { hopPlace } from \"./place.js\";\nimport type { UseCaseScan } from \"./fleet.js\";\n\n/**\n * What one contract removal does to the fleet's use cases.\n *\n * Two lists rather than `victims`/`suspended` — the vocabulary\n * `core/diff/victims.ts` uses — because this module answers about FLOWS and that\n * one answers about consumers. The caller does the folding, and naming the two\n * differently is what stops a reader taking this for a second implementation of\n * `ConsumerScan` (it is not: it never scans a document, and it cannot be\n * unreadable — the scan it runs over was already graded).\n */\nexport interface UseCaseHits {\n  /** Hops the removal breaks, each spelled by `hopPlace`. */\n  breaks: string[];\n  /** Hops loam refuses to grade, each saying why in its own sentence. */\n  unsure: string[];\n}\n\n/** The one removal a scan is being asked about. */\nexport interface RemovedOperation {\n  /** The service dropping it — the same id the diff files its findings under. */\n  provider: string;\n  /** The operationId leaving the contract. */\n  op: string;\n}\n\nconst EMPTY: UseCaseHits = { breaks: [], unsure: [] };\n\n/** Every hop of every graded use case, view order preserved, so output is stable. */\nfunction hops(scan: Extract<UseCaseScan, { kind: \"read\" }>): Array<{ view: ParsedView; step: ParsedStep }> {\n  return scan.views.flatMap((view) => view.steps.map((step) => ({ view, step })));\n}\n\n/**\n * The flows one removed operation breaks, and the ones loam cannot answer for.\n *\n * An `unreadable` scan contributes NOTHING — neither break nor suspension — and\n * that is `core/diff/victims.ts`'s own landscape doctrine applied one axis over:\n * an unreadable fleet map proves nothing either way, `landscape.invalid` is\n * validate's finding to make, and inventing doubt out of a parse error would\n * point the reviewer at a file their change never touched. The caller reports\n * the hole; this join stays quiet about it.\n */\nexport function hopsExercising(scan: UseCaseScan, removed: RemovedOperation): UseCaseHits {\n  if (scan.kind !== \"read\") return EMPTY;\n  const out: UseCaseHits = { breaks: [], unsure: [] };\n  for (const { view, step } of hops(scan)) {\n    const attribution = attributeStep(step, scan.model);\n    if (attribution.verdict === \"unbacked\") continue;\n    // The callee, through the SAME resolver every other join in this run uses,\n    // so a hop drawn into a modelled container `payment.api` is filed against\n    // payment-service rather than against a service called \"api\".\n    if (scan.resolve(attribution.to) !== removed.provider) continue;\n    // And the CALLER, through the same resolver: a hop whose two endpoints\n    // resolve to one service is that service calling itself, which owes no\n    // operationId of its own contract — `usecase.step-unlinked`'s fourth guard,\n    // applied to the victim join. Without it an internal hop was a break of the\n    // provider's own removal (verification 2026-09-04, R3).\n    if (scan.resolve(attribution.from) === removed.provider) continue;\n    if (attribution.verdict === \"attributed\") {\n      if (attribution.op === removed.op) out.breaks.push(hopPlace(view, step));\n      continue;\n    }\n    if (!attribution.ops.includes(removed.op)) continue;\n    out.unsure.push(\n      `${hopPlace(view, step)} — ${attribution.rels.length} relationships back ` +\n        `${attribution.from} -> ${attribution.to} and they name different operations, so whether this hop ` +\n        `exercises '${removed.op}' could not be answered`,\n    );\n  }\n  return out;\n}\n\n/** The one message removal a scan is being asked about. */\nexport interface RemovedMessage {\n  /** The service dropping the declaration — the diff's own subject. */\n  provider: string;\n  /** The AsyncAPI message name leaving the contract. */\n  name: string;\n}\n\n/**\n * The flows one removed message breaks.\n *\n * No suspension arm, and the asymmetry is a fact about the model rather than an\n * omission: `attributeStep` contests OPERATIONS, because that is where two\n * relationships between one pair of endpoints can disagree. A `consumes` edge\n * names a message outright, so a hop either is backed by one or is not — there\n * is no disagreement for loam to refuse to resolve.\n *\n * The provider exclusion mirrors `messageConsumers` exactly: an edge INTO the\n * provider is the provider's own consumption, which leaves with the same change,\n * so a hop backed only by that edge is not a victim of it.\n */\nexport function hopsConsuming(scan: UseCaseScan, removed: RemovedMessage): string[] {\n  if (scan.kind !== \"read\") return [];\n  const out: string[] = [];\n  for (const { view, step } of hops(scan)) {\n    const attribution = attributeStep(step, scan.model);\n    if (attribution.verdict === \"unbacked\") continue;\n    const consumes = attribution.rels.some(\n      (rel) => rel.consumes === removed.name && scan.resolve(rel.target) !== removed.provider,\n    );\n    if (consumes) out.push(hopPlace(view, step));\n  }\n  return out;\n}\n"]}
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../src/core/usecases/operations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which hops of which business flows a contract removal breaks.\n *\n * `loam diff --base` already answers \"who still depends on this operation\" with\n * landscape edges and other services' living requirements. Both are true and\n * neither is the sentence a reviewer wants: an edge is a line in a diagram and a\n * requirement is a heading in somebody else's spec, while \"step 4 of Checkout\n * stops working\" is the fact a human weighs a pull request against. This module\n * is the join that produces that sentence, and it produces NOTHING ELSE — no\n * finding, no code, no severity. `core/consumers/consumers.ts` folds its\n * answers into the `details[]` of the two codes that already exist.\n *\n * ## Attributed is a victim; contested is a suspension\n *\n * The distinction is the whole reason this module is careful rather than a\n * filter. `attributeStep` (core/c4/resolve/steps.ts) grades a hop by the DISTINCT-op\n * count across the relationships backing it:\n *\n *  - `attributed` with `op === X` means every relationship behind the hop agrees\n *    the hop exercises X. Remove X and the flow breaks at that hop. That is\n *    positive evidence, and it is a victim.\n *  - `contested` means the relationships DISAGREE, so loam does not know which\n *    operation the hop exercises. It must not claim the flow breaks — a guessed\n *    victim reads exactly like a real one and turns a warn into an error on\n *    somebody's PR — and it must not go silent either, because silence here is\n *    the fail-open shape `ConsumerScan.suspended` exists to forbid. It is a\n *    suspension: loam says it could not answer.\n *\n * A contested hop is suspended only when X is among its candidate operations.\n * That is not a noise trade, it is the honest boundary: the candidates ARE the\n * relationships backing the hop, so an operation none of them names is an\n * operation the hop cannot be exercising under any reading of the disagreement.\n * Suspending every contested hop in the fleet on every removal would report\n * doubt loam does not actually have.\n *\n * An `unbacked` hop is neither. Nothing in the model backs it, so it names no\n * operation of anybody's contract — `usecase.step-unbacked` is already the error\n * that convicts it, and repeating that here would file a modelling defect\n * against whoever happened to remove an endpoint.\n */\nimport { attributeStep } from \"../c4/resolve/steps.js\";\nimport type { ParsedStep, ParsedView } from \"../c4/parsed/dynamic-views.js\";\nimport { hopPlace } from \"./place.js\";\nimport type { UseCaseScan } from \"./fleet.js\";\n\n/**\n * What one contract removal does to the fleet's use cases.\n *\n * Two lists rather than `victims`/`suspended` — the vocabulary\n * `core/consumers/consumers.ts` uses — because this module answers about FLOWS\n * and that one answers about consumers. The caller does the folding, and naming the two\n * differently is what stops a reader taking this for a second implementation of\n * `ConsumerScan` (it is not: it never scans a document, and it cannot be\n * unreadable — the scan it runs over was already graded).\n */\nexport interface UseCaseHits {\n  /** Hops the removal breaks, each spelled by `hopPlace`. */\n  breaks: string[];\n  /** Hops loam refuses to grade, each saying why in its own sentence. */\n  unsure: string[];\n}\n\n/** The one removal a scan is being asked about. */\nexport interface RemovedOperation {\n  /** The service dropping it — the same id the diff files its findings under. */\n  provider: string;\n  /** The operationId leaving the contract. */\n  op: string;\n}\n\nconst EMPTY: UseCaseHits = { breaks: [], unsure: [] };\n\n/** Every hop of every graded use case, view order preserved, so output is stable. */\nfunction hops(scan: Extract<UseCaseScan, { kind: \"read\" }>): Array<{ view: ParsedView; step: ParsedStep }> {\n  return scan.views.flatMap((view) => view.steps.map((step) => ({ view, step })));\n}\n\n/**\n * The flows one removed operation breaks, and the ones loam cannot answer for.\n *\n * An `unreadable` scan contributes NOTHING — neither break nor suspension — and\n * that is the consumer index's own landscape doctrine (`livingMap` in\n * `core/consumers/current.ts`, which reads the map for every consumer\n * question) applied one axis over: an unreadable fleet map proves nothing either way, `landscape.invalid` is\n * validate's finding to make, and inventing doubt out of a parse error would\n * point the reviewer at a file their change never touched. The caller reports\n * the hole; this join stays quiet about it.\n */\nexport function hopsExercising(scan: UseCaseScan, removed: RemovedOperation): UseCaseHits {\n  if (scan.kind !== \"read\") return EMPTY;\n  const out: UseCaseHits = { breaks: [], unsure: [] };\n  for (const { view, step } of hops(scan)) {\n    const attribution = attributeStep(step, scan.model);\n    if (attribution.verdict === \"unbacked\") continue;\n    // The callee, through the SAME resolver every other join in this run uses,\n    // so a hop drawn into a modelled container `payment.api` is filed against\n    // payment-service rather than against a service called \"api\".\n    if (scan.resolve(attribution.to) !== removed.provider) continue;\n    // And the CALLER, through the same resolver: a hop whose two endpoints\n    // resolve to one service is that service calling itself, which owes no\n    // operationId of its own contract — `usecase.step-unlinked`'s fourth guard,\n    // applied to the victim join. Without it an internal hop was a break of the\n    // provider's own removal (verification 2026-09-04, R3).\n    if (scan.resolve(attribution.from) === removed.provider) continue;\n    if (attribution.verdict === \"attributed\") {\n      if (attribution.op === removed.op) out.breaks.push(hopPlace(view, step));\n      continue;\n    }\n    if (!attribution.ops.includes(removed.op)) continue;\n    out.unsure.push(\n      `${hopPlace(view, step)} — ${attribution.rels.length} relationships back ` +\n        `${attribution.from} -> ${attribution.to} and they name different operations, so whether this hop ` +\n        `exercises '${removed.op}' could not be answered`,\n    );\n  }\n  return out;\n}\n\n/** The one message removal a scan is being asked about. */\nexport interface RemovedMessage {\n  /** The service dropping the declaration — the diff's own subject. */\n  provider: string;\n  /** The AsyncAPI message name leaving the contract. */\n  name: string;\n}\n\n/**\n * The flows one removed message breaks.\n *\n * No suspension arm, and the asymmetry is a fact about the model rather than an\n * omission: `attributeStep` contests OPERATIONS, because that is where two\n * relationships between one pair of endpoints can disagree. A `consumes` edge\n * names a message outright, so a hop either is backed by one or is not — there\n * is no disagreement for loam to refuse to resolve.\n *\n * The provider exclusion mirrors `messageConsumers` exactly: an edge INTO the\n * provider is the provider's own consumption, which leaves with the same change,\n * so a hop backed only by that edge is not a victim of it.\n */\nexport function hopsConsuming(scan: UseCaseScan, removed: RemovedMessage): string[] {\n  if (scan.kind !== \"read\") return [];\n  const out: string[] = [];\n  for (const { view, step } of hops(scan)) {\n    const attribution = attributeStep(step, scan.model);\n    if (attribution.verdict === \"unbacked\") continue;\n    const consumes = attribution.rels.some(\n      (rel) => rel.consumes === removed.name && scan.resolve(rel.target) !== removed.provider,\n    );\n    if (consumes) out.push(hopPlace(view, step));\n  }\n  return out;\n}\n"]}

package/dist/core/usecases/service/flows.js

@@ -55,12 +55,15 @@
  *     (`core/usecases/place.ts` records the rule) and an extending model's carry
  *     their docs-relative path, so the file is spelled here, where it is known,
  *     for both: `model.likec4`;
- *  2. siblings, no tagged view in the model, and no reserved prefix in any
- *     document (`mentionsTagPrefix`, the fleet's own byte gate) → nothing opted
- *     in, no workspace. An untagged `views.likec4` is somebody's hand-drawn
- *     diagram, never graded, exactly as an untagged fleet view is — and its
- *     parse errors are the renderer's business until a view opts the project
- *     in;
+ *  2. siblings, no tagged view in the model, and no reserved tag REFERENCED in
+ *     any document — a `#` then `cap-`, `req-` or `suite-` (`mentionsTagPrefix`,
+ *     the fleet's own byte gate) → nothing opted in, no workspace. An untagged
+ *     `views.likec4` is somebody's hand-drawn diagram, never graded, exactly as
+ *     an untagged fleet view is — and its parse errors are the renderer's
+ *     business until a view opts the project in. That includes one whose prose
+ *     names a prefix without the `#` (a title about an e2e-suite job): the gate
+ *     used to open on the bare substring, and such a sibling that did not parse
+ *     became `usecase.flow-invalid` over a diagram that opted nothing in;
  *  3. otherwise `loadProject` over model + siblings, the way the renderer reads
  *     them. `own` and the project's views are never merged: when siblings
  *     exist the project is the whole answer, which is what keeps one view from

package/dist/core/usecases/service/flows.js.map

@@ -1 +1 @@
-{"version":3,"file":"flows.js","sourceRoot":"","sources":["../../../../src/core/usecases/service/flows.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A service's OWN use cases: the `dynamic view`s its LikeC4 project declares,\n * read the way the renderer reads that project.\n *\n * THE SLOT IS THE PROJECT. `loam subsystem sync` writes a\n * `services/<…>/<svc>/likec4.config.json` that registers every `.likec4` under\n * the service directory as one LikeC4 project, so the renderer already shows a\n * `views.likec4` beside the model, or a `usecases/<name>.likec4` under it. loam\n * reads exactly that set — `model.likec4` plus every sibling, recursively, minus\n * whatever that project file's own `exclude` drops (`./exclude.ts`) — and\n * nothing else, because a slot narrower than the renderer's would leave a flow\n * that renders and is graded by nothing, which is the report this module\n * answers: an intra-service flow behind an `arch.spec.md` requirement whose\n * `Covers:` names containers had no home. `architecture/usecases/` is a\n * separate project that cannot resolve a container (one such file turned a\n * whole fleet `landscape.invalid`), and the author's workaround beside the\n * model was invisible to every check. The read is NOT gated on the project\n * file's presence: that file is create-only and a team may delete it, its\n * absence has a warning of its own (`service.likec4-config-missing`), and a\n * flow the renderer cannot show yet is still a flow loam can grade.\n *\n * MODEL FACTS STAY SINGLE-FILE. `c4.valid`'s counts, `Covers:` resolution,\n * `health.dependency-unmodelled` and every other model reader keep the\n * single-file load the service target already made; the project is loaded here\n * for the VIEWS and their `sourcePath` only, and only when there is something\n * to grade. A sibling that declares elements extends what a hop may name, and\n * that is the renderer's reading too.\n *\n * TWO SHAPES, ONE SLOT. A model that stands alone is a project of its own\n * directory, exactly as above. A model that EXTENDS the fleet map is not: its\n * containers are declared inside an element the map owns, so a flow beside it\n * naming one of those containers only resolves in a project that also holds the\n * map (`c4/service-model/documents.ts`, `serviceFlowDocuments`). That project is\n * staged from the DOCS ROOT, so every view comes back spelled\n * `services/<tree>/usecases/x.likec4` — and the service prefix is stripped here,\n * because every finding this scan feeds names a file relative to the service\n * directory and a reader must not have to work out which spelling they were\n * given. The same prefix is the FILTER: the map's own `architecture/usecases/`\n * flows are in that project too, and without it every service in the fleet would\n * be graded for every fleet-level use case.\n *\n * THE CHEAP GATE, in order, so a fleet without the axis pays one recursive\n * readdir per service and nothing else:\n *\n *  1. no sibling → nothing new is loaded, and the model's own tagged views are\n *     graded at zero cost against the project the model was READ in. For a\n *     standalone model that is the single-file load already in hand, which IS\n *     its whole project; for an extending one it is `ServiceModel.project`, the\n *     map and this model together — NOT the service's own slice of it, which is\n *     what the caller passes as `model` and what every count and `Covers:` line\n *     is answered from. A hop backed by a map edge is backed wherever the view\n *     is written, and grading the two arms against different documents made one\n *     view `usecase.step-unbacked` in model.likec4 and clean in a sibling. A\n *     standalone model's views came back named `source.c4`\n *     (`core/usecases/place.ts` records the rule) and an extending model's carry\n *     their docs-relative path, so the file is spelled here, where it is known,\n *     for both: `model.likec4`;\n *  2. siblings, no tagged view in the model, and no reserved prefix in any\n *     document (`mentionsTagPrefix`, the fleet's own byte gate) → nothing opted\n *     in, no workspace. An untagged `views.likec4` is somebody's hand-drawn\n *     diagram, never graded, exactly as an untagged fleet view is — and its\n *     parse errors are the renderer's business until a view opts the project\n *     in;\n *  3. otherwise `loadProject` over model + siblings, the way the renderer reads\n *     them. `own` and the project's views are never merged: when siblings\n *     exist the project is the whole answer, which is what keeps one view from\n *     being graded twice.\n *\n * A REQUEST RECORD rather than three parameters, for the reason\n * docs/CODE-STYLE.md gives: the paths, the single-file doc and the fleet set\n * are only ever passed together, and a caller handing in a doc loaded from\n * some other path is exactly the inconsistent pair a record makes\n * unrepresentable.\n */\nimport { relative } from \"node:path\";\nimport type { LikeC4Error, LoadedDoc } from \"../../c4/likec4.js\";\nimport type { ParsedView } from \"../../c4/parsed/dynamic-views.js\";\nimport { architectureDocuments } from \"../../c4/project/documents.js\";\nimport { asLoadedDoc, loadProject } from \"../../c4/project/load.js\";\nimport { serviceFlowDocuments } from \"../../c4/service-model/documents.js\";\nimport type { StepScope } from \"../../c4/resolve/steps.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport { ARTIFACT_FILES, type ServicePaths } from \"../../repo/paths.js\";\nimport { isUseCase, mentionsTagPrefix } from \"../fleet.js\";\nimport { keepIncluded, serviceProjectExclude } from \"./exclude.js\";\n\nexport interface ServiceFlowRequest {\n  paths: ServicePaths;\n  /**\n   * The single-file load the service target already made and has verified\n   * parses. Its views are the project when no sibling exists; its elements are\n   * the model a no-sibling flow is graded over.\n   */\n  model: LoadedDoc;\n  /** The enumerated fleet, for `serviceResolver`'s reason: without it a container resolves to a service that has never existed. */\n  known: ReadonlySet<string>;\n  /**\n   * Set only when this model EXTENDS the fleet map, and then both halves of it\n   * — a record rather than two optional fields, for docs/CODE-STYLE.md's reason:\n   * they are only ever passed together, and a caller that supplied one without\n   * the other is exactly the inconsistent pair a record makes unrepresentable.\n   *\n   * `docsDir` decides which documents the sibling project holds (the map as\n   * well, or the directory alone) and which root they are staged from, and\n   * therefore how LikeC4 spells every `sourcePath` that comes back.\n   *\n   * `project` is the per-service project the model was READ in — the map plus\n   * this model (`ServiceModel.project`) — and it is the scope a hop resolves\n   * against when there is no sibling file. `model` above is then the service's\n   * own SLICE of that project, which is the right answer for every count and\n   * every `Covers:` line and the wrong one here: a hop backed by a MAP edge is\n   * backed, and grading it against the slice reported `usecase.step-unbacked`\n   * (exit 1) for a view in model.likec4 that was clean the moment the same view\n   * moved to a sibling file, where the loaded project holds the map. One\n   * question, two answers, decided by which file the author happened to write\n   * the view in.\n   *\n   * Absent means the standalone shape — the service directory is the project and\n   * the single-file load IS that project, exactly as it has always been.\n   */\n  extending?: { docsDir: DocsDir; project: LoadedDoc };\n}\n\n/**\n * What a service's flows are, or the honest refusal to say.\n *\n * Three variants rather than a record with flags, for `UseCaseScan`'s reason\n * one package up: a project that did not parse has no elements to resolve\n * against and no views to grade, and a caller handed `{ views: [], unreadable:\n * true }` is one `.length` check away from reporting a service as flow-free\n * when nobody could read it. `none` is the gate's answer — nothing opted in,\n * nothing was loaded — and it is distinct from `read` with no views (a project\n * that mentions a prefix in prose and declares no tagged view), because only\n * the second one cost a workspace.\n */\nexport type ServiceFlowScan =\n  | { kind: \"none\" }\n  | {\n      kind: \"read\";\n      /** The reserved-tag views ONLY, each carrying a `sourcePath` relative to the SERVICE directory. */\n      views: ParsedView[];\n      /** What a hop is attributed against — `known` required, as `UseCaseScan.model` requires it. */\n      model: StepScope & { known: ReadonlySet<string> };\n    }\n  | {\n      kind: \"unreadable\";\n      /**\n       * Every error the project raised, each carrying the real absolute path of\n       * the document that raised it, sorted by that path — so a caller can name\n       * the file, and a project with two broken documents reports them in a\n       * stable order.\n       */\n      errors: LikeC4Error[];\n    };\n\n/**\n * The service's declared use cases, with the model they are drawn over.\n *\n * Reads only, throws nothing: every failure is the `unreadable` arm. The caller\n * has already established that `model.likec4` parses on its own — a project\n * whose model is broken is `c4.invalid`'s business, and loading it again here\n * would only repeat that cascade under a second code.\n */\nexport async function readServiceFlows(req: ServiceFlowRequest): Promise<ServiceFlowScan> {\n  const found = await architectureDocuments(req.paths.dir, [req.paths.model]);\n  // What the RENDERER holds, for the standalone shape where this directory's\n  // own `likec4.config.json` IS the project config: a sibling its `exclude`\n  // covers is in no project loam may claim to be reading (`./exclude.ts`). The\n  // extending shape reads the root project instead, so its list does not apply\n  // — a per-service config beside an extending model is `service.likec4-config-stray`.\n  const siblings =\n    req.extending === undefined\n      ? keepIncluded(req.paths.dir, await serviceProjectExclude(req.paths.dir), found)\n      : found;\n  // The scope of the no-sibling arm, and it is the PROJECT for both shapes: the\n  // single-file load for a standalone model (which is its whole project), and\n  // the map-plus-model load for an extending one. Reading `req.model` there for\n  // an extending model read its own slice instead, so one view was graded two\n  // different ways depending on which file it was written in.\n  const alone = req.extending?.project ?? req.model;\n  const scope = { elements: alone.elements, relationships: alone.relationships, known: req.known };\n  const own = (req.model.views ?? []).filter(isUseCase);\n  if (siblings.length === 0) {\n    if (own.length === 0) return { kind: \"none\" };\n    return { kind: \"read\", views: own.map((view) => ({ ...view, sourcePath: ARTIFACT_FILES.model })), model: scope };\n  }\n  if (own.length === 0 && !(await mentionsTagPrefix(siblings))) return { kind: \"none\" };\n\n  const base = req.extending?.docsDir ?? req.paths.dir;\n  const documents =\n    req.extending === undefined\n      ? [req.paths.model, ...siblings]\n      : await serviceFlowDocuments(req.extending.docsDir, req.paths);\n  const project = await loadProject(base, documents);\n  if (!project.clean) {\n    // Each error already carries the real path of its document (`loadProject`\n    // rewrites the staged path back), and the flattening is `asLoadedDoc`'s —\n    // the fleet's own path-sorted order, taken from the one place it is\n    // spelled rather than re-spelled here: the caller names the FIRST broken\n    // file, and a second sort rule would let the service target name a\n    // different first file than the fleet target names for the same project.\n    return { kind: \"unreadable\", errors: asLoadedDoc(project).errors };\n  }\n  // The prefix the service's own documents are spelled under inside this\n  // project: empty for a standalone model (the project IS the directory, so\n  // every view in it is this service's) and `services/<tree>/` for an extending\n  // one, whose project also holds the whole fleet map.\n  const prefix = req.extending === undefined ? \"\" : `${relative(base, req.paths.dir).split(/[\\\\/]/).join(\"/\")}/`;\n  return {\n    kind: \"read\",\n    views: rebase(project.views.filter(isUseCase), prefix),\n    model: { elements: project.elements, relationships: project.relationships, known: req.known },\n  };\n}\n\n/**\n * The views this SERVICE declares, spelled relative to its own directory.\n *\n * With an empty prefix — the standalone shape — this is the identity, including\n * for a view whose `sourcePath` is absent: that project holds nothing but the\n * service's own files, so there is nothing to attribute and nothing to strip.\n *\n * With a prefix, it is both the filter and the rebase, and both halves are one\n * rule about which document belongs to whom. The project also holds the fleet\n * map, so `architecture/usecases/checkout.likec4` is in it — and without the\n * filter every service in the fleet would be graded for every fleet-level use\n * case. A view carrying no `sourcePath` cannot be attributed at all and is\n * dropped for the same reason: the path is the only evidence there is.\n */\nfunction rebase(views: readonly ParsedView[], prefix: string): ParsedView[] {\n  if (prefix === \"\") return [...views];\n  return views\n    .filter((view) => view.sourcePath?.startsWith(prefix) === true)\n    .map((view) => ({ ...view, sourcePath: (view.sourcePath ?? \"\").slice(prefix.length) }));\n}\n"]}
+{"version":3,"file":"flows.js","sourceRoot":"","sources":["../../../../src/core/usecases/service/flows.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A service's OWN use cases: the `dynamic view`s its LikeC4 project declares,\n * read the way the renderer reads that project.\n *\n * THE SLOT IS THE PROJECT. `loam subsystem sync` writes a\n * `services/<…>/<svc>/likec4.config.json` that registers every `.likec4` under\n * the service directory as one LikeC4 project, so the renderer already shows a\n * `views.likec4` beside the model, or a `usecases/<name>.likec4` under it. loam\n * reads exactly that set — `model.likec4` plus every sibling, recursively, minus\n * whatever that project file's own `exclude` drops (`./exclude.ts`) — and\n * nothing else, because a slot narrower than the renderer's would leave a flow\n * that renders and is graded by nothing, which is the report this module\n * answers: an intra-service flow behind an `arch.spec.md` requirement whose\n * `Covers:` names containers had no home. `architecture/usecases/` is a\n * separate project that cannot resolve a container (one such file turned a\n * whole fleet `landscape.invalid`), and the author's workaround beside the\n * model was invisible to every check. The read is NOT gated on the project\n * file's presence: that file is create-only and a team may delete it, its\n * absence has a warning of its own (`service.likec4-config-missing`), and a\n * flow the renderer cannot show yet is still a flow loam can grade.\n *\n * MODEL FACTS STAY SINGLE-FILE. `c4.valid`'s counts, `Covers:` resolution,\n * `health.dependency-unmodelled` and every other model reader keep the\n * single-file load the service target already made; the project is loaded here\n * for the VIEWS and their `sourcePath` only, and only when there is something\n * to grade. A sibling that declares elements extends what a hop may name, and\n * that is the renderer's reading too.\n *\n * TWO SHAPES, ONE SLOT. A model that stands alone is a project of its own\n * directory, exactly as above. A model that EXTENDS the fleet map is not: its\n * containers are declared inside an element the map owns, so a flow beside it\n * naming one of those containers only resolves in a project that also holds the\n * map (`c4/service-model/documents.ts`, `serviceFlowDocuments`). That project is\n * staged from the DOCS ROOT, so every view comes back spelled\n * `services/<tree>/usecases/x.likec4` — and the service prefix is stripped here,\n * because every finding this scan feeds names a file relative to the service\n * directory and a reader must not have to work out which spelling they were\n * given. The same prefix is the FILTER: the map's own `architecture/usecases/`\n * flows are in that project too, and without it every service in the fleet would\n * be graded for every fleet-level use case.\n *\n * THE CHEAP GATE, in order, so a fleet without the axis pays one recursive\n * readdir per service and nothing else:\n *\n *  1. no sibling → nothing new is loaded, and the model's own tagged views are\n *     graded at zero cost against the project the model was READ in. For a\n *     standalone model that is the single-file load already in hand, which IS\n *     its whole project; for an extending one it is `ServiceModel.project`, the\n *     map and this model together — NOT the service's own slice of it, which is\n *     what the caller passes as `model` and what every count and `Covers:` line\n *     is answered from. A hop backed by a map edge is backed wherever the view\n *     is written, and grading the two arms against different documents made one\n *     view `usecase.step-unbacked` in model.likec4 and clean in a sibling. A\n *     standalone model's views came back named `source.c4`\n *     (`core/usecases/place.ts` records the rule) and an extending model's carry\n *     their docs-relative path, so the file is spelled here, where it is known,\n *     for both: `model.likec4`;\n *  2. siblings, no tagged view in the model, and no reserved tag REFERENCED in\n *     any document — a `#` then `cap-`, `req-` or `suite-` (`mentionsTagPrefix`,\n *     the fleet's own byte gate) → nothing opted in, no workspace. An untagged\n *     `views.likec4` is somebody's hand-drawn diagram, never graded, exactly as\n *     an untagged fleet view is — and its parse errors are the renderer's\n *     business until a view opts the project in. That includes one whose prose\n *     names a prefix without the `#` (a title about an e2e-suite job): the gate\n *     used to open on the bare substring, and such a sibling that did not parse\n *     became `usecase.flow-invalid` over a diagram that opted nothing in;\n *  3. otherwise `loadProject` over model + siblings, the way the renderer reads\n *     them. `own` and the project's views are never merged: when siblings\n *     exist the project is the whole answer, which is what keeps one view from\n *     being graded twice.\n *\n * A REQUEST RECORD rather than three parameters, for the reason\n * docs/CODE-STYLE.md gives: the paths, the single-file doc and the fleet set\n * are only ever passed together, and a caller handing in a doc loaded from\n * some other path is exactly the inconsistent pair a record makes\n * unrepresentable.\n */\nimport { relative } from \"node:path\";\nimport type { LikeC4Error, LoadedDoc } from \"../../c4/likec4.js\";\nimport type { ParsedView } from \"../../c4/parsed/dynamic-views.js\";\nimport { architectureDocuments } from \"../../c4/project/documents.js\";\nimport { asLoadedDoc, loadProject } from \"../../c4/project/load.js\";\nimport { serviceFlowDocuments } from \"../../c4/service-model/documents.js\";\nimport type { StepScope } from \"../../c4/resolve/steps.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport { ARTIFACT_FILES, type ServicePaths } from \"../../repo/paths.js\";\nimport { isUseCase, mentionsTagPrefix } from \"../fleet.js\";\nimport { keepIncluded, serviceProjectExclude } from \"./exclude.js\";\n\nexport interface ServiceFlowRequest {\n  paths: ServicePaths;\n  /**\n   * The single-file load the service target already made and has verified\n   * parses. Its views are the project when no sibling exists; its elements are\n   * the model a no-sibling flow is graded over.\n   */\n  model: LoadedDoc;\n  /** The enumerated fleet, for `serviceResolver`'s reason: without it a container resolves to a service that has never existed. */\n  known: ReadonlySet<string>;\n  /**\n   * Set only when this model EXTENDS the fleet map, and then both halves of it\n   * — a record rather than two optional fields, for docs/CODE-STYLE.md's reason:\n   * they are only ever passed together, and a caller that supplied one without\n   * the other is exactly the inconsistent pair a record makes unrepresentable.\n   *\n   * `docsDir` decides which documents the sibling project holds (the map as\n   * well, or the directory alone) and which root they are staged from, and\n   * therefore how LikeC4 spells every `sourcePath` that comes back.\n   *\n   * `project` is the per-service project the model was READ in — the map plus\n   * this model (`ServiceModel.project`) — and it is the scope a hop resolves\n   * against when there is no sibling file. `model` above is then the service's\n   * own SLICE of that project, which is the right answer for every count and\n   * every `Covers:` line and the wrong one here: a hop backed by a MAP edge is\n   * backed, and grading it against the slice reported `usecase.step-unbacked`\n   * (exit 1) for a view in model.likec4 that was clean the moment the same view\n   * moved to a sibling file, where the loaded project holds the map. One\n   * question, two answers, decided by which file the author happened to write\n   * the view in.\n   *\n   * Absent means the standalone shape — the service directory is the project and\n   * the single-file load IS that project, exactly as it has always been.\n   */\n  extending?: { docsDir: DocsDir; project: LoadedDoc };\n}\n\n/**\n * What a service's flows are, or the honest refusal to say.\n *\n * Three variants rather than a record with flags, for `UseCaseScan`'s reason\n * one package up: a project that did not parse has no elements to resolve\n * against and no views to grade, and a caller handed `{ views: [], unreadable:\n * true }` is one `.length` check away from reporting a service as flow-free\n * when nobody could read it. `none` is the gate's answer — nothing opted in,\n * nothing was loaded — and it is distinct from `read` with no views (a project\n * that writes a reserved tag reference only outside a view — in a comment, or\n * on an element — and so declares no tagged view), because only the second one\n * cost a workspace.\n */\nexport type ServiceFlowScan =\n  | { kind: \"none\" }\n  | {\n      kind: \"read\";\n      /** The reserved-tag views ONLY, each carrying a `sourcePath` relative to the SERVICE directory. */\n      views: ParsedView[];\n      /** What a hop is attributed against — `known` required, as `UseCaseScan.model` requires it. */\n      model: StepScope & { known: ReadonlySet<string> };\n    }\n  | {\n      kind: \"unreadable\";\n      /**\n       * Every error the project raised, each carrying the real absolute path of\n       * the document that raised it, sorted by that path — so a caller can name\n       * the file, and a project with two broken documents reports them in a\n       * stable order.\n       */\n      errors: LikeC4Error[];\n    };\n\n/**\n * The service's declared use cases, with the model they are drawn over.\n *\n * Reads only, throws nothing: every failure is the `unreadable` arm. The caller\n * has already established that `model.likec4` parses on its own — a project\n * whose model is broken is `c4.invalid`'s business, and loading it again here\n * would only repeat that cascade under a second code.\n */\nexport async function readServiceFlows(req: ServiceFlowRequest): Promise<ServiceFlowScan> {\n  const found = await architectureDocuments(req.paths.dir, [req.paths.model]);\n  // What the RENDERER holds, for the standalone shape where this directory's\n  // own `likec4.config.json` IS the project config: a sibling its `exclude`\n  // covers is in no project loam may claim to be reading (`./exclude.ts`). The\n  // extending shape reads the root project instead, so its list does not apply\n  // — a per-service config beside an extending model is `service.likec4-config-stray`.\n  const siblings =\n    req.extending === undefined\n      ? keepIncluded(req.paths.dir, await serviceProjectExclude(req.paths.dir), found)\n      : found;\n  // The scope of the no-sibling arm, and it is the PROJECT for both shapes: the\n  // single-file load for a standalone model (which is its whole project), and\n  // the map-plus-model load for an extending one. Reading `req.model` there for\n  // an extending model read its own slice instead, so one view was graded two\n  // different ways depending on which file it was written in.\n  const alone = req.extending?.project ?? req.model;\n  const scope = { elements: alone.elements, relationships: alone.relationships, known: req.known };\n  const own = (req.model.views ?? []).filter(isUseCase);\n  if (siblings.length === 0) {\n    if (own.length === 0) return { kind: \"none\" };\n    return { kind: \"read\", views: own.map((view) => ({ ...view, sourcePath: ARTIFACT_FILES.model })), model: scope };\n  }\n  if (own.length === 0 && !(await mentionsTagPrefix(siblings))) return { kind: \"none\" };\n\n  const base = req.extending?.docsDir ?? req.paths.dir;\n  const documents =\n    req.extending === undefined\n      ? [req.paths.model, ...siblings]\n      : await serviceFlowDocuments(req.extending.docsDir, req.paths);\n  const project = await loadProject(base, documents);\n  if (!project.clean) {\n    // Each error already carries the real path of its document (`loadProject`\n    // rewrites the staged path back), and the flattening is `asLoadedDoc`'s —\n    // the fleet's own path-sorted order, taken from the one place it is\n    // spelled rather than re-spelled here: the caller names the FIRST broken\n    // file, and a second sort rule would let the service target name a\n    // different first file than the fleet target names for the same project.\n    return { kind: \"unreadable\", errors: asLoadedDoc(project).errors };\n  }\n  // The prefix the service's own documents are spelled under inside this\n  // project: empty for a standalone model (the project IS the directory, so\n  // every view in it is this service's) and `services/<tree>/` for an extending\n  // one, whose project also holds the whole fleet map.\n  const prefix = req.extending === undefined ? \"\" : `${relative(base, req.paths.dir).split(/[\\\\/]/).join(\"/\")}/`;\n  return {\n    kind: \"read\",\n    views: rebase(project.views.filter(isUseCase), prefix),\n    model: { elements: project.elements, relationships: project.relationships, known: req.known },\n  };\n}\n\n/**\n * The views this SERVICE declares, spelled relative to its own directory.\n *\n * With an empty prefix — the standalone shape — this is the identity, including\n * for a view whose `sourcePath` is absent: that project holds nothing but the\n * service's own files, so there is nothing to attribute and nothing to strip.\n *\n * With a prefix, it is both the filter and the rebase, and both halves are one\n * rule about which document belongs to whom. The project also holds the fleet\n * map, so `architecture/usecases/checkout.likec4` is in it — and without the\n * filter every service in the fleet would be graded for every fleet-level use\n * case. A view carrying no `sourcePath` cannot be attributed at all and is\n * dropped for the same reason: the path is the only evidence there is.\n */\nfunction rebase(views: readonly ParsedView[], prefix: string): ParsedView[] {\n  if (prefix === \"\") return [...views];\n  return views\n    .filter((view) => view.sourcePath?.startsWith(prefix) === true)\n    .map((view) => ({ ...view, sourcePath: (view.sourcePath ?? \"\").slice(prefix.length) }));\n}\n"]}