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

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
@@ -38,27 +64,48 @@
  */
 import { readFile } from "node:fs/promises";
 import { CAP_TAG_PREFIX, REQ_TAG_PREFIX } from "../capabilities/usecase-join.js";
-import { architectureDir, loadArchitecture } from "../c4/project/architecture.js";
-import { architectureDocuments } from "../c4/project/documents.js";
+import { architectureProjectDocuments, loadArchitecture } from "../c4/project/architecture.js";
+import { errorText } from "../c4/likec4.js";
 import { serviceResolver } from "../c4/resolve/service.js";
-import { subsystemViewsPath } from "../repo/paths.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 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.
  */
-async function mentionsTagPrefix(paths) {
+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 {
@@ -70,14 +117,105 @@ 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
@@ -88,9 +226,10 @@ 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
@@ -98,7 +237,7 @@ 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.
@@ -116,22 +255,42 @@ export async function readUseCases(req) {
         model: { elements: [], relationships: [], known: req.known },
         resolve: (id) => id,
     };
-    const dir = architectureDir(req.docsDir);
-    const documents = await architectureDocuments(dir, [subsystemViewsPath(req.docsDir)]);
+    // EXACTLY the documents `loadArchitecture` will load two lines down, root
+    // `exclude` and all — `architectureProjectDocuments` is that one answer
+    // (`c4/project/architecture.ts`). The gate used to walk `architecture/` for
+    // itself and skip the exclude, which could only over-scan: the byte gate
+    // reading a document the loader then drops decides "there might be a use
+    // case here" and pays for a project load that finds none. Never a wrong
+    // answer, but two lists that disagree about what the project is, and the
+    // next reader to take the wider one for the project's would be wrong.
+    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":"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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>` 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/arch.js\";\nimport { CAP_TAG_PREFIX, REQ_TAG_PREFIX } from \"../capabilities/usecase-join.js\";\nimport type { ParsedView } from \"../c4/parsed/dynamic-views.js\";\nimport { architectureDir, loadArchitecture } from \"../c4/project/architecture.js\";\nimport { architectureDocuments } from \"../c4/project/documents.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport { subsystemViewsPath } from \"../repo/paths.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 */\nasync 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  const dir = architectureDir(req.docsDir);\n  const documents = await architectureDocuments(dir, [subsystemViewsPath(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/{commands/validate/fleet/usecases → core/usecases/grade}/capability-tag.js

@@ -22,7 +22,7 @@
  * one view's tags are two chances to disagree about which capability a flow is
  * about. The ladder that produces the suppressing `null` is
  * `gradableCapabilityIds` in `core/capabilities/findings.ts` — one function, called by every site that needs the graded id list, this module's
- * caller in `../landscape.ts` included. The FILE is this axis's opt-in, so a
+ * callers in `commands/validate/fleet/map/usecases.ts` and `./feature.ts` included. The FILE is this axis's opt-in, so a
  * fleet with no `architecture/capabilities.yaml` produces no capability finding
  * at all, and an unreadable one is `capability.invalid` alone rather than one
  * unresolved tag per use case in the fleet, which is a cascade and not a
@@ -30,8 +30,7 @@
  * `CapabilityVocabulary` anywhere in this package is the copy that goes stale
  * the day a fourth un-gradable state is added, so call the function.
  */
-import { CAP_TAG_PREFIX, tagSlug, } from "../../../../core/capabilities/usecase-join.js";
-import { viewPlace } from "./place.js";
+import { CAP_TAG_PREFIX, tagSlug, } from "../../capabilities/usecase-join.js";
 /** A capability id as an author must write it in a tag: `identity/tokens (#cap-identity-tokens)`. */
 function idAndTag(id) {
     return `${id} (#${CAP_TAG_PREFIX}${tagSlug(id)})`;
@@ -45,11 +44,11 @@ function idAndTag(id) {
  * LikeC4 refuses to parse. The flattening rule is stated in the same breath so
  * the reader can derive the next one without being told again.
  */
-function noneMessage(view, claim) {
+function noneMessage(where, claim) {
     const hint = claim.close.length > 0
         ? `Did you mean: ${claim.close.map(idAndTag).join(", ")}?`
         : "Declare it there (`capabilities: {<id>: {description, owner}}`), or fix the tag.";
-    return (`${viewPlace(view)} is tagged #${claim.tag}, and no capability declared in ` +
+    return (`${where} is tagged #${claim.tag}, and no capability declared in ` +
         `architecture/capabilities.yaml flattens to '${claim.slug}'. ${hint} ` +
         "A tag spells the id with every character outside `[A-Za-z0-9_-]` flattened to `-`, because that is all a LikeC4 tag name accepts.");
 }
@@ -58,8 +57,8 @@ function noneMessage(view, claim) {
  * message that stopped at the first would be reporting the ambiguity while
  * hiding half of what makes it one.
  */
-function manyMessage(view, claim) {
-    return (`${viewPlace(view)} is tagged #${claim.tag}, and ${claim.ids.length} declared capabilities flatten to ` +
+function manyMessage(where, claim) {
+    return (`${where} is tagged #${claim.tag}, and ${claim.ids.length} declared capabilities flatten to ` +
         `'${claim.slug}' (${claim.ids.join(", ")}) — nothing in the tag can say which one this use case realizes. ` +
         "Rename one of them in architecture/capabilities.yaml: a guessed capability files every hop of the flow, " +
         "and every rollup built over it, under an owner who never claimed it — and the wrong answer looks exactly " +
@@ -74,7 +73,7 @@ function manyMessage(view, claim) {
  * swallow a broken tag beside a working one or lose the capability the view
  * genuinely does realize; one tag, one verdict, one finding keeps both facts.
  */
-export function capabilityTagFindings(view, claims) {
+export function capabilityTagFindings(view, claims, place) {
     const findings = [];
     for (const claim of claims) {
         if (claim.kind === "resolved")
@@ -86,7 +85,7 @@ export function capabilityTagFindings(view, claims) {
             // `subjectsWith` counts one broken use case once however many of its tags
             // are wrong.
             subject: view.id,
-            message: claim.kind === "none" ? noneMessage(view, claim) : manyMessage(view, claim),
+            message: claim.kind === "none" ? noneMessage(place(view), claim) : manyMessage(place(view), claim),
         });
     }
     return findings;

package/dist/core/usecases/grade/capability-tag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-tag.js","sourceRoot":"","sources":["../../../../src/core/usecases/grade/capability-tag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EACL,cAAc,EACd,OAAO,GAER,MAAM,oCAAoC,CAAC;AAK5C,qGAAqG;AACrG,SAAS,QAAQ,CAAC,EAAU;IAC1B,OAAO,GAAG,EAAE,MAAM,cAAc,GAAG,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC;AACpD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,WAAW,CAAC,KAAa,EAAE,KAAiD;IACnF,MAAM,IAAI,GACR,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;QACpB,CAAC,CAAC,iBAAiB,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;QAC1D,CAAC,CAAC,kFAAkF,CAAC;IACzF,OAAO,CACL,GAAG,KAAK,eAAe,KAAK,CAAC,GAAG,kCAAkC;QAClE,+CAA+C,KAAK,CAAC,IAAI,MAAM,IAAI,GAAG;QACtE,mIAAmI,CACpI,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,KAAa,EAAE,KAAiD;IACnF,OAAO,CACL,GAAG,KAAK,eAAe,KAAK,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,CAAC,MAAM,oCAAoC;QAC7F,IAAI,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,mEAAmE;QAC3G,0GAA0G;QAC1G,2GAA2G;QAC3G,qBAAqB,CACtB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAgB,EAAE,MAAkC,EAAE,KAAgB;IAC1G,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;YAAE,SAAS;QACxC,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,+BAA+B;YACrC,wEAAwE;YACxE,0EAA0E;YAC1E,aAAa;YACb,OAAO,EAAE,IAAI,CAAC,EAAE;YAChB,OAAO,EAAE,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;SACnG,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * `usecase.capability-unresolved` — the `#cap-` tag that names no declared\n * capability, or more than one.\n *\n * The join itself lives in `core/capabilities/usecase-join.ts` and none of it is\n * repeated here: this module owns the grade and the sentence, nothing else. That\n * split is why the tag can answer \"many\" at all — the slug is not injective, so\n * `payments/refunds` and `payments-refunds` both flatten to\n * `payments-refunds` — and why the close candidates a message offers are real\n * declared ids rather than loam's flattened spelling of them.\n *\n * ERROR, the same grade `capability.unknown` carries on a `Capability:` line and\n * for its reason: an invented capability reads exactly like a real one. Here it\n * reads that way at flow altitude — the tag is what files a whole business\n * sequence under an owner, so a claim that resolves to nothing produces a use\n * case nobody can find and a capability nobody can see is realized.\n *\n * SUPPRESSED ENTIRELY when the vocabulary is absent or unreadable: the caller\n * resolves no claims at all in that case, so this answers with nothing. The\n * claims are RESOLVED BY THE CALLER rather than here because the `#req-` grade\n * beside this one is scoped by the very same verdicts, and two resolutions of\n * one view's tags are two chances to disagree about which capability a flow is\n * about. The ladder that produces the suppressing `null` is\n * `gradableCapabilityIds` in `core/capabilities/findings.ts` — one function, called by every site that needs the graded id list, this module's\n * callers in `commands/validate/fleet/map/usecases.ts` and `./feature.ts` included. The FILE is this axis's opt-in, so a\n * fleet with no `architecture/capabilities.yaml` produces no capability finding\n * at all, and an unreadable one is `capability.invalid` alone rather than one\n * unresolved tag per use case in the fleet, which is a cascade and not a\n * diagnosis. That rule is not re-decided here: a second reading of\n * `CapabilityVocabulary` anywhere in this package is the copy that goes stale\n * the day a fourth un-gradable state is added, so call the function.\n */\nimport {\n  CAP_TAG_PREFIX,\n  tagSlug,\n  type CapabilityClaim,\n} from \"../../capabilities/usecase-join.js\";\nimport type { ParsedView } from \"../../c4/parsed/dynamic-views.js\";\nimport type { Finding } from \"../../vocabulary/report.js\";\nimport type { ViewPlace } from \"../place.js\";\n\n/** A capability id as an author must write it in a tag: `identity/tokens (#cap-identity-tokens)`. */\nfunction idAndTag(id: string): string {\n  return `${id} (#${CAP_TAG_PREFIX}${tagSlug(id)})`;\n}\n\n/**\n * A tag nothing declares, with the close names spelled as TAGS as well as ids.\n *\n * Both spellings, because either alone sends the author somewhere wrong: the id\n * is what `capabilities.yaml` holds and the tag is what the view must carry, and\n * an author handed only `identity/tokens` writes `#cap-identity/tokens`, which\n * LikeC4 refuses to parse. The flattening rule is stated in the same breath so\n * the reader can derive the next one without being told again.\n */\nfunction noneMessage(where: string, claim: Extract<CapabilityClaim, { kind: \"none\" }>): string {\n  const hint =\n    claim.close.length > 0\n      ? `Did you mean: ${claim.close.map(idAndTag).join(\", \")}?`\n      : \"Declare it there (`capabilities: {<id>: {description, owner}}`), or fix the tag.\";\n  return (\n    `${where} is tagged #${claim.tag}, and no capability declared in ` +\n    `architecture/capabilities.yaml flattens to '${claim.slug}'. ${hint} ` +\n    \"A tag spells the id with every character outside `[A-Za-z0-9_-]` flattened to `-`, because that is all a LikeC4 tag name accepts.\"\n  );\n}\n\n/**\n * A tag two or more declared ids answer to. Every colliding id is named — a\n * message that stopped at the first would be reporting the ambiguity while\n * hiding half of what makes it one.\n */\nfunction manyMessage(where: string, claim: Extract<CapabilityClaim, { kind: \"many\" }>): string {\n  return (\n    `${where} is tagged #${claim.tag}, and ${claim.ids.length} declared capabilities flatten to ` +\n    `'${claim.slug}' (${claim.ids.join(\", \")}) — nothing in the tag can say which one this use case realizes. ` +\n    \"Rename one of them in architecture/capabilities.yaml: a guessed capability files every hop of the flow, \" +\n    \"and every rollup built over it, under an owner who never claimed it — and the wrong answer looks exactly \" +\n    \"like the right one.\"\n  );\n}\n\n/**\n * One finding per `#cap-` tag that does not resolve — never one per view.\n *\n * A view may legitimately carry two capability tags (a checkout flow that also\n * issues the identity token realizes both), and `resolveCapabilityTags` answers\n * each on its own terms for that reason. Collapsing them here would either\n * swallow a broken tag beside a working one or lose the capability the view\n * genuinely does realize; one tag, one verdict, one finding keeps both facts.\n */\nexport function capabilityTagFindings(view: ParsedView, claims: readonly CapabilityClaim[], place: ViewPlace): Finding[] {\n  const findings: Finding[] = [];\n  for (const claim of claims) {\n    if (claim.kind === \"resolved\") continue;\n    findings.push({\n      severity: \"error\",\n      code: \"usecase.capability-unresolved\",\n      // The VIEW, not the tag: a subject is what a reader goes and opens, and\n      // `subjectsWith` counts one broken use case once however many of its tags\n      // are wrong.\n      subject: view.id,\n      message: claim.kind === \"none\" ? noneMessage(place(view), claim) : manyMessage(place(view), claim),\n    });\n  }\n  return findings;\n}\n"]}

package/dist/core/usecases/grade/feature.js

@@ -0,0 +1,88 @@
+/**
+ * A feature's own flows, graded the way `validate --all` will grade them once
+ * the archive has copied them into `architecture/usecases/`.
+ *
+ * WHY THIS EXISTS. The feature gate used to READ a feature's flows — parsed
+ * over the map its own merge would leave (`../delta/overlay.ts`), which is
+ * `usecase.flow-invalid` — and then grade only the promises they keep. Two
+ * flows the very next `validate --all` convicts passed it: one whose hop joins
+ * two services nothing on that map connects (`usecase.step-unbacked`), and one
+ * tagged `#req-` with no `#cap-` to scope it, or with a `#req-` naming no
+ * requirement (`usecase.requirement-unresolved`). Both archived at exit 0 under
+ * "living spec + landscape are now complete + current." (the real-fleet review,
+ * 2026-10-21). SCHEMA.md already said feature flows are graded against the map
+ * the merge leaves behind; for every grade but the parse, they were not.
+ *
+ * THE FLEET'S GRADER, NOT A COPY. `./usecases.ts` is `validate --all`'s own
+ * per-view loop — the opt-in, the capability and requirement tags, every hop —
+ * handed the staged post-merge model, the vocabulary and requirement index the
+ * merge would leave, and a `place` naming the file the author is still editing.
+ * A second verdict→code mapping for this scope would be the drift that
+ * package's banner forbids, and the drift would show up first as the gate
+ * passing what the fleet then fails.
+ *
+ * Issues, because the archive gate files Issues: every finding the grader
+ * writes carries a code the `IssueCode` union admits for exactly this
+ * (`core/vocabulary/issue.ts`). The severities travel unchanged — the two
+ * errors gate the archive, the two hop warnings and nothing else advise.
+ */
+import { relative } from "node:path";
+import { useCaseFindings } from "./usecases.js";
+/**
+ * The codes `useCaseFindings` writes, each mapped to its `IssueCode` member — a
+ * table rather than a cast, so a sixth grade added to the fleet grader is a
+ * thrown error the first time a feature trips it rather than a finding this
+ * gate silently drops.
+ */
+const AS_ISSUE = {
+    "usecase.capability-unresolved": "usecase.capability-unresolved",
+    "usecase.requirement-unresolved": "usecase.requirement-unresolved",
+    "usecase.step-unbacked": "usecase.step-unbacked",
+    "usecase.step-contested": "usecase.step-contested",
+    "usecase.step-unlinked": "usecase.step-unlinked",
+};
+/**
+ * Where a feature flow's finding says the view is:
+ * `features/FEAT-1-split/usecases/checkout.likec4 — dynamic view 'uc_checkout'`.
+ * The staged parse has already mapped `sourcePath` back to the authored file;
+ * this spells it docs-relative, the way every other feature finding names a file.
+ */
+function featurePlace(docsDir) {
+    return (view) => {
+        const file = view.sourcePath === undefined ? "usecases/" : relative(docsDir, view.sourcePath).split(/[\\/]/).join("/");
+        return `${file} — dynamic view '${view.id}'`;
+    };
+}
+function asIssue(finding) {
+    if (finding.severity === "ok")
+        return [];
+    const code = AS_ISSUE[finding.code];
+    if (code === undefined) {
+        throw new Error(`the use-case grader wrote '${finding.code}', which the feature gate has no IssueCode for — add it to AS_ISSUE`);
+    }
+    return [
+        {
+            severity: finding.severity,
+            code,
+            ...(finding.subject === undefined ? {} : { subject: finding.subject }),
+            ...(finding.details === undefined ? {} : { details: finding.details }),
+            message: finding.message,
+        },
+    ];
+}
+export function featureFlowIssues(scope) {
+    const { scan } = scope;
+    if (scan.views.length === 0)
+        return [];
+    return useCaseFindings({
+        views: scan.views,
+        elements: scan.model.elements,
+        relationships: scan.model.relationships,
+        services: scan.model.known,
+        resolve: scan.resolve,
+        capabilities: scope.capabilities,
+        requirementsOf: scope.requirementsOf,
+        place: featurePlace(scope.docsDir),
+    }).flatMap(asIssue);
+}
+//# sourceMappingURL=feature.js.map

package/dist/core/usecases/grade/feature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature.js","sourceRoot":"","sources":["../../../../src/core/usecases/grade/feature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAMrC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAahD;;;;;GAKG;AACH,MAAM,QAAQ,GAAwC;IACpD,+BAA+B,EAAE,+BAA+B;IAChE,gCAAgC,EAAE,gCAAgC;IAClE,uBAAuB,EAAE,uBAAuB;IAChD,wBAAwB,EAAE,wBAAwB;IAClD,uBAAuB,EAAE,uBAAuB;CACjD,CAAC;AAEF;;;;;GAKG;AACH,SAAS,YAAY,CAAC,OAAgB;IACpC,OAAO,CAAC,IAAI,EAAE,EAAE;QACd,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvH,OAAO,GAAG,IAAI,oBAAoB,IAAI,CAAC,EAAE,GAAG,CAAC;IAC/C,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,OAAgB;IAC/B,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACzC,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAO,CAAC,IAAI,qEAAqE,CAAC,CAAC;IACnI,CAAC;IACD,OAAO;QACL;YACE,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,IAAI;YACJ,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;YACtE,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;YACtE,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAuB;IACvD,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IACvB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACvC,OAAO,eAAe,CAAC;QACrB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ;QAC7B,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,aAAa;QACvC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK;QAC1B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC;KACnC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AACtB,CAAC","sourcesContent":["/**\n * A feature's own flows, graded the way `validate --all` will grade them once\n * the archive has copied them into `architecture/usecases/`.\n *\n * WHY THIS EXISTS. The feature gate used to READ a feature's flows — parsed\n * over the map its own merge would leave (`../delta/overlay.ts`), which is\n * `usecase.flow-invalid` — and then grade only the promises they keep. Two\n * flows the very next `validate --all` convicts passed it: one whose hop joins\n * two services nothing on that map connects (`usecase.step-unbacked`), and one\n * tagged `#req-` with no `#cap-` to scope it, or with a `#req-` naming no\n * requirement (`usecase.requirement-unresolved`). Both archived at exit 0 under\n * \"living spec + landscape are now complete + current.\" (the real-fleet review,\n * 2026-10-21). SCHEMA.md already said feature flows are graded against the map\n * the merge leaves behind; for every grade but the parse, they were not.\n *\n * THE FLEET'S GRADER, NOT A COPY. `./usecases.ts` is `validate --all`'s own\n * per-view loop — the opt-in, the capability and requirement tags, every hop —\n * handed the staged post-merge model, the vocabulary and requirement index the\n * merge would leave, and a `place` naming the file the author is still editing.\n * A second verdict→code mapping for this scope would be the drift that\n * package's banner forbids, and the drift would show up first as the gate\n * passing what the fleet then fails.\n *\n * Issues, because the archive gate files Issues: every finding the grader\n * writes carries a code the `IssueCode` union admits for exactly this\n * (`core/vocabulary/issue.ts`). The severities travel unchanged — the two\n * errors gate the archive, the two hop warnings and nothing else advise.\n */\nimport { relative } from \"node:path\";\nimport type { ParsedView } from \"../../c4/parsed/dynamic-views.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport type { Issue, IssueCode } from \"../../vocabulary/issue.js\";\nimport type { Finding } from \"../../vocabulary/report.js\";\nimport type { UseCaseScan } from \"../fleet.js\";\nimport { useCaseFindings } from \"./usecases.js\";\n\n/** What the feature's flows are graded against — everything as the merge would leave it. */\nexport interface FeatureFlowScope {\n  docsDir: DocsDir;\n  /** The feature's flows, parsed over the post-merge map — the readable arm only; unreadable is `usecase.flow-invalid`. */\n  scan: Extract<UseCaseScan, { kind: \"read\" }>;\n  /** The capability ids the merge would leave declared, or `null` when the vocabulary suspends the tag grades. */\n  capabilities: readonly string[] | null;\n  /** The requirement ids each capability document would declare after the merge. */\n  requirementsOf: (capability: string) => ReadonlySet<string> | undefined;\n}\n\n/**\n * The codes `useCaseFindings` writes, each mapped to its `IssueCode` member — a\n * table rather than a cast, so a sixth grade added to the fleet grader is a\n * thrown error the first time a feature trips it rather than a finding this\n * gate silently drops.\n */\nconst AS_ISSUE: Readonly<Record<string, IssueCode>> = {\n  \"usecase.capability-unresolved\": \"usecase.capability-unresolved\",\n  \"usecase.requirement-unresolved\": \"usecase.requirement-unresolved\",\n  \"usecase.step-unbacked\": \"usecase.step-unbacked\",\n  \"usecase.step-contested\": \"usecase.step-contested\",\n  \"usecase.step-unlinked\": \"usecase.step-unlinked\",\n};\n\n/**\n * Where a feature flow's finding says the view is:\n * `features/FEAT-1-split/usecases/checkout.likec4 — dynamic view 'uc_checkout'`.\n * The staged parse has already mapped `sourcePath` back to the authored file;\n * this spells it docs-relative, the way every other feature finding names a file.\n */\nfunction featurePlace(docsDir: DocsDir): (view: ParsedView) => string {\n  return (view) => {\n    const file = view.sourcePath === undefined ? \"usecases/\" : relative(docsDir, view.sourcePath).split(/[\\\\/]/).join(\"/\");\n    return `${file} — dynamic view '${view.id}'`;\n  };\n}\n\nfunction asIssue(finding: Finding): Issue[] {\n  if (finding.severity === \"ok\") return [];\n  const code = AS_ISSUE[finding.code];\n  if (code === undefined) {\n    throw new Error(`the use-case grader wrote '${finding.code}', which the feature gate has no IssueCode for — add it to AS_ISSUE`);\n  }\n  return [\n    {\n      severity: finding.severity,\n      code,\n      ...(finding.subject === undefined ? {} : { subject: finding.subject }),\n      ...(finding.details === undefined ? {} : { details: finding.details }),\n      message: finding.message,\n    },\n  ];\n}\n\nexport function featureFlowIssues(scope: FeatureFlowScope): Issue[] {\n  const { scan } = scope;\n  if (scan.views.length === 0) return [];\n  return useCaseFindings({\n    views: scan.views,\n    elements: scan.model.elements,\n    relationships: scan.model.relationships,\n    services: scan.model.known,\n    resolve: scan.resolve,\n    capabilities: scope.capabilities,\n    requirementsOf: scope.requirementsOf,\n    place: featurePlace(scope.docsDir),\n  }).flatMap(asIssue);\n}\n"]}

package/dist/{commands/validate/fleet/usecases → core/usecases/grade}/requirement-tag.js

@@ -20,8 +20,7 @@
  * the intended reading: one says the tag is wrong, the other says the promise is
  * still unkept.
  */
-import { REQ_TAG_PREFIX, tagSlug, resolveRequirementTags, } from "../../../../core/capabilities/usecase-join.js";
-import { viewPlace } from "./place.js";
+import { REQ_TAG_PREFIX, tagSlug, resolveRequirementTags, } from "../../capabilities/usecase-join.js";
 /** A `Requirement-ID` as an author must write it in a tag: `CHK.ONCE (#req-CHK-ONCE)`. */
 function idAndTag(id) {
     return `${id} (#${REQ_TAG_PREFIX}${tagSlug(id)})`;
@@ -75,7 +74,7 @@ function advice(claim) {
  * scope `capabilityTagFindings` graded are the same list, and an unresolved
  * `#cap-` tag cannot silently scope a requirement lookup.
  */
-export function requirementTagFindings(view, claims, requirementsOf) {
+export function requirementTagFindings(view, claims, requirementsOf, place) {
     const scope = claims.flatMap((claim) => (claim.kind === "resolved" ? [claim.id] : []));
     const findings = [];
     for (const claim of resolveRequirementTags(view.tags, scope, requirementsOf)) {
@@ -87,7 +86,7 @@ export function requirementTagFindings(view, claims, requirementsOf) {
             // The VIEW, not the tag — a subject is what a reader goes and opens, and
             // one broken use case counts once however many of its tags are wrong.
             subject: view.id,
-            message: `${viewPlace(view)} is tagged #${claim.tag}, and it does not resolve: ${advice(claim)}`,
+            message: `${place(view)} is tagged #${claim.tag}, and it does not resolve: ${advice(claim)}`,
         });
     }
     return findings;