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

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/core/usecases/grade/requirement-tag.js

@@ -0,0 +1,94 @@
+/**
+ * `usecase.requirement-unresolved` — the `#req-` tag that names no requirement
+ * of the capability the view is about.
+ *
+ * The join lives in `core/capabilities/usecase-join.ts` and none of it is
+ * repeated here: this module owns the grade and the sentences. Six arms, six
+ * fixes, and they are deliberately the same vocabulary
+ * `capability.realizes-unknown` uses for the OTHER carrier of this claim — an
+ * author who has learned one set of messages has learned both.
+ *
+ * ERROR, for `usecase.capability-unresolved`'s reason one join deeper: the tag
+ * is the architect's claim that a flow satisfies a named business promise, and a
+ * claim that resolves to nothing reads exactly like one that does — in the view,
+ * in review, and to anyone asking which flow keeps that promise.
+ *
+ * AN UNRESOLVED CLAIM SUPPRESSES NOTHING. `capability.requirement-unrealized`
+ * counts only RESOLVED claims, so a typo'd `#req-` tag leaves the requirement
+ * reported as realized by nobody — which is the truth, and is exactly what a
+ * broken claim should not be able to hide. The two findings arriving together is
+ * the intended reading: one says the tag is wrong, the other says the promise is
+ * still unkept.
+ */
+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)})`;
+}
+/**
+ * The fix for one unresolved claim. The `unscoped` arm splits in two on the
+ * count, because none and several are opposite mistakes: one author forgot to
+ * say which capability, the other said two and left the id homeless.
+ */
+function advice(claim) {
+    switch (claim.kind) {
+        case "unscoped":
+            return claim.capabilities.length === 0
+                ? "the view carries no `#cap-` tag that resolves to a declared capability, and a `Requirement-ID` is " +
+                    "unique only inside its own document — so there is nothing for this id to be looked up in. " +
+                    "Add the `#cap-<slug>` tag naming the capability this flow is about."
+                : `the view resolves ${claim.capabilities.length} capabilities (${claim.capabilities.join(", ")}), ` +
+                    "so nothing says which document the id belongs to. A flow realizing promises from two capabilities " +
+                    "needs one `#req-` tag per capability to be unambiguous, which the tag grammar cannot express — " +
+                    "split the flow, or drop the `#req-` tag and let `Realizes:` on the service requirements carry it.";
+        case "undocumented":
+            return (`capability '${claim.capability}' is declared but has no capabilities/${claim.capability}/spec.md, ` +
+                "so it carries no requirements to satisfy. Write the document — a name alone can be claimed with " +
+                "`#cap-`, but only a document has promises a flow can keep.");
+        case "empty":
+            return (`capabilities/${claim.capability}/spec.md exists and declares no requirements yet — ` +
+                "add the `## Requirements` section, each requirement carrying its `Requirement-ID:`.");
+        case "none":
+            return claim.close.length > 0
+                ? `capabilities/${claim.capability}/spec.md declares no requirement flattening to '${claim.slug}'. ` +
+                    `Did you mean: ${claim.close.map(idAndTag).join(", ")}?`
+                : `capabilities/${claim.capability}/spec.md declares no requirement flattening to '${claim.slug}' — ` +
+                    "check the `Requirement-ID:` lines in that document.";
+        default:
+            return (`${claim.ids.length} requirements of '${claim.capability}' flatten to '${claim.slug}' ` +
+                `(${claim.ids.join(", ")}) — nothing in the tag can say which promise this flow keeps. ` +
+                "Rename one of them: a guessed requirement reports the wrong promise as kept and the right one as " +
+                "unimplemented, and both answers look exactly like the truth.");
+    }
+}
+/**
+ * One finding per `#req-` tag that does not resolve — never one per view.
+ *
+ * Several `#req-` tags on one view are legal and normal: a checkout flow that
+ * charges once AND honours the price keeps two promises, and there is no honest
+ * way to make its author pick one. So a broken tag beside a working one must
+ * neither swallow the break nor lose the promise the view genuinely does keep.
+ *
+ * `claims` is the view's OWN capability verdicts, already resolved by the
+ * caller — passed rather than recomputed so the scope this grade uses and the
+ * scope `capabilityTagFindings` graded are the same list, and an unresolved
+ * `#cap-` tag cannot silently scope a requirement lookup.
+ */
+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)) {
+        if (claim.kind === "resolved")
+            continue;
+        findings.push({
+            severity: "error",
+            code: "usecase.requirement-unresolved",
+            // 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: `${place(view)} is tagged #${claim.tag}, and it does not resolve: ${advice(claim)}`,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=requirement-tag.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-tag.js","sourceRoot":"","sources":["../../../../src/core/usecases/grade/requirement-tag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,cAAc,EACd,OAAO,EACP,sBAAsB,GAGvB,MAAM,oCAAoC,CAAC;AAK5C,0FAA0F;AAC1F,SAAS,QAAQ,CAAC,EAAU;IAC1B,OAAO,GAAG,EAAE,MAAM,cAAc,GAAG,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,SAAS,MAAM,CAAC,KAAsD;IACpE,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,UAAU;YACb,OAAO,KAAK,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC;gBACpC,CAAC,CAAC,oGAAoG;oBAClG,4FAA4F;oBAC5F,qEAAqE;gBACzE,CAAC,CAAC,qBAAqB,KAAK,CAAC,YAAY,CAAC,MAAM,kBAAkB,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;oBAChG,oGAAoG;oBACpG,iGAAiG;oBACjG,mGAAmG,CAAC;QAC5G,KAAK,cAAc;YACjB,OAAO,CACL,eAAe,KAAK,CAAC,UAAU,yCAAyC,KAAK,CAAC,UAAU,YAAY;gBACpG,kGAAkG;gBAClG,4DAA4D,CAC7D,CAAC;QACJ,KAAK,OAAO;YACV,OAAO,CACL,gBAAgB,KAAK,CAAC,UAAU,qDAAqD;gBACrF,qFAAqF,CACtF,CAAC;QACJ,KAAK,MAAM;YACT,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBAC3B,CAAC,CAAC,gBAAgB,KAAK,CAAC,UAAU,mDAAmD,KAAK,CAAC,IAAI,KAAK;oBAChG,iBAAiB,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBAC5D,CAAC,CAAC,gBAAgB,KAAK,CAAC,UAAU,mDAAmD,KAAK,CAAC,IAAI,MAAM;oBACjG,qDAAqD,CAAC;QAC9D;YACE,OAAO,CACL,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,qBAAqB,KAAK,CAAC,UAAU,iBAAiB,KAAK,CAAC,IAAI,IAAI;gBACvF,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,gEAAgE;gBACxF,mGAAmG;gBACnG,8DAA8D,CAC/D,CAAC;IACN,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAgB,EAChB,MAAkC,EAClC,cAAuE,EACvE,KAAgB;IAEhB,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACvF,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,cAAc,CAAC,EAAE,CAAC;QAC7E,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;YAAE,SAAS;QACxC,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,gCAAgC;YACtC,yEAAyE;YACzE,sEAAsE;YACtE,OAAO,EAAE,IAAI,CAAC,EAAE;YAChB,OAAO,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,GAAG,8BAA8B,MAAM,CAAC,KAAK,CAAC,EAAE;SAC7F,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * `usecase.requirement-unresolved` — the `#req-` tag that names no requirement\n * of the capability the view is about.\n *\n * The join lives in `core/capabilities/usecase-join.ts` and none of it is\n * repeated here: this module owns the grade and the sentences. Six arms, six\n * fixes, and they are deliberately the same vocabulary\n * `capability.realizes-unknown` uses for the OTHER carrier of this claim — an\n * author who has learned one set of messages has learned both.\n *\n * ERROR, for `usecase.capability-unresolved`'s reason one join deeper: the tag\n * is the architect's claim that a flow satisfies a named business promise, and a\n * claim that resolves to nothing reads exactly like one that does — in the view,\n * in review, and to anyone asking which flow keeps that promise.\n *\n * AN UNRESOLVED CLAIM SUPPRESSES NOTHING. `capability.requirement-unrealized`\n * counts only RESOLVED claims, so a typo'd `#req-` tag leaves the requirement\n * reported as realized by nobody — which is the truth, and is exactly what a\n * broken claim should not be able to hide. The two findings arriving together is\n * the intended reading: one says the tag is wrong, the other says the promise is\n * still unkept.\n */\nimport {\n  REQ_TAG_PREFIX,\n  tagSlug,\n  resolveRequirementTags,\n  type CapabilityClaim,\n  type RequirementClaim,\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 `Requirement-ID` as an author must write it in a tag: `CHK.ONCE (#req-CHK-ONCE)`. */\nfunction idAndTag(id: string): string {\n  return `${id} (#${REQ_TAG_PREFIX}${tagSlug(id)})`;\n}\n\n/**\n * The fix for one unresolved claim. The `unscoped` arm splits in two on the\n * count, because none and several are opposite mistakes: one author forgot to\n * say which capability, the other said two and left the id homeless.\n */\nfunction advice(claim: Exclude<RequirementClaim, { kind: \"resolved\" }>): string {\n  switch (claim.kind) {\n    case \"unscoped\":\n      return claim.capabilities.length === 0\n        ? \"the view carries no `#cap-` tag that resolves to a declared capability, and a `Requirement-ID` is \" +\n            \"unique only inside its own document — so there is nothing for this id to be looked up in. \" +\n            \"Add the `#cap-<slug>` tag naming the capability this flow is about.\"\n        : `the view resolves ${claim.capabilities.length} capabilities (${claim.capabilities.join(\", \")}), ` +\n            \"so nothing says which document the id belongs to. A flow realizing promises from two capabilities \" +\n            \"needs one `#req-` tag per capability to be unambiguous, which the tag grammar cannot express — \" +\n            \"split the flow, or drop the `#req-` tag and let `Realizes:` on the service requirements carry it.\";\n    case \"undocumented\":\n      return (\n        `capability '${claim.capability}' is declared but has no capabilities/${claim.capability}/spec.md, ` +\n        \"so it carries no requirements to satisfy. Write the document — a name alone can be claimed with \" +\n        \"`#cap-`, but only a document has promises a flow can keep.\"\n      );\n    case \"empty\":\n      return (\n        `capabilities/${claim.capability}/spec.md exists and declares no requirements yet — ` +\n        \"add the `## Requirements` section, each requirement carrying its `Requirement-ID:`.\"\n      );\n    case \"none\":\n      return claim.close.length > 0\n        ? `capabilities/${claim.capability}/spec.md declares no requirement flattening to '${claim.slug}'. ` +\n            `Did you mean: ${claim.close.map(idAndTag).join(\", \")}?`\n        : `capabilities/${claim.capability}/spec.md declares no requirement flattening to '${claim.slug}' — ` +\n            \"check the `Requirement-ID:` lines in that document.\";\n    default:\n      return (\n        `${claim.ids.length} requirements of '${claim.capability}' flatten to '${claim.slug}' ` +\n        `(${claim.ids.join(\", \")}) — nothing in the tag can say which promise this flow keeps. ` +\n        \"Rename one of them: a guessed requirement reports the wrong promise as kept and the right one as \" +\n        \"unimplemented, and both answers look exactly like the truth.\"\n      );\n  }\n}\n\n/**\n * One finding per `#req-` tag that does not resolve — never one per view.\n *\n * Several `#req-` tags on one view are legal and normal: a checkout flow that\n * charges once AND honours the price keeps two promises, and there is no honest\n * way to make its author pick one. So a broken tag beside a working one must\n * neither swallow the break nor lose the promise the view genuinely does keep.\n *\n * `claims` is the view's OWN capability verdicts, already resolved by the\n * caller — passed rather than recomputed so the scope this grade uses and the\n * scope `capabilityTagFindings` graded are the same list, and an unresolved\n * `#cap-` tag cannot silently scope a requirement lookup.\n */\nexport function requirementTagFindings(\n  view: ParsedView,\n  claims: readonly CapabilityClaim[],\n  requirementsOf: (capability: string) => ReadonlySet<string> | undefined,\n  place: ViewPlace,\n): Finding[] {\n  const scope = claims.flatMap((claim) => (claim.kind === \"resolved\" ? [claim.id] : []));\n  const findings: Finding[] = [];\n  for (const claim of resolveRequirementTags(view.tags, scope, requirementsOf)) {\n    if (claim.kind === \"resolved\") continue;\n    findings.push({\n      severity: \"error\",\n      code: \"usecase.requirement-unresolved\",\n      // The VIEW, not the tag — a subject is what a reader goes and opens, and\n      // one broken use case counts once however many of its tags are wrong.\n      subject: view.id,\n      message: `${place(view)} is tagged #${claim.tag}, and it does not resolve: ${advice(claim)}`,\n    });\n  }\n  return findings;\n}\n"]}

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

@@ -0,0 +1,266 @@
+/**
+ * The three grades one hop of a use case can earn: `usecase.step-unbacked`,
+ * `usecase.step-contested` and `usecase.step-unlinked`.
+ *
+ * The attribution itself is `core/c4/resolve/steps.ts`'s `attributeStep` — which declared
+ * relationship backs a hop, oriented on `isBackward` and decided by the
+ * DISTINCT-op count — and none of that reasoning is repeated here. This module
+ * owns three things: which verdict earns which code, the four guards that keep
+ * the warn honest, and the sentences.
+ *
+ * TWO SCOPES, ONE GRADER. The fleet target grades the `architecture/` project's
+ * views and the service target grades a service's own project — every `.likec4`
+ * beside `model.likec4`, read the way the renderer reads it
+ * (`commands/validate/service/usecases/`). Both call `stepFindings` below with
+ * their own `StepGrading`; what differs is only where a finding says the view
+ * is (`place`). A second copy of the verdict→code mapping per scope is the
+ * drift this package's banner forbids, which is why the intra-service case is
+ * a fourth guard here rather than a grader of its own.
+ *
+ * WHY `step-unbacked` IS THE CHECK THAT EARNS THE FEATURE. A hop between two
+ * elements that both exist, with no relationship between them anywhere in the
+ * model, is ZERO LikeC4 errors: a `dynamic view` is allowed to show a call the
+ * model never declared, so the diagram renders, the project parses, and every
+ * other check in loam stays green. The flow reads as fine in every tool the
+ * fleet has. If loam does not convict it, nothing does — which is why it is an
+ * error rather than an advisory.
+ *
+ * ONE BREACH, ONE FINDING, and here that is structural rather than remembered.
+ * `contested` and `attributed` are disjoint verdicts, so deriving
+ * `step-unlinked` from the `attributed` arm — never from the candidate
+ * relationships — is what makes a contested step report once. A grader that
+ * walked `rels` looking for a missing `op` would convict the same hop twice:
+ * once for the disagreement, and once for whichever candidate happened to carry
+ * no operation at all.
+ */
+import { attributeStep, pickingTitle } from "../../c4/resolve/steps.js";
+import { ACTOR_KINDS } from "../../vocabulary/maturity.js";
+import { stepPlace } from "../place.js";
+/**
+ * `…checkout.likec4 — dynamic view 'uc_checkout' step 2 'authorizes the payment'`.
+ *
+ * Spelled once per hop in `stepFindings` and handed to each sentence builder as
+ * a string, rather than recomputed from the grading inside each of them: three
+ * builders reaching for `grading.place` on their own would be three
+ * places for one scope to forget the injection.
+ */
+function placeOf(hop, grading) {
+    return `${grading.place(hop.view)} ${stepPlace(hop.step)}`;
+}
+/**
+ * A hop nothing in the model backs.
+ *
+ * Two fixes, because there are genuinely two mistakes that land here and the
+ * author is the only one who can say which they made: the edge really is
+ * missing, or the hop is a reply written the long way round. The second is
+ * offered as the OTHER spelling of what they already typed — suggesting the
+ * spelling they used would be a hint that restates the defect — and the sentence
+ * says which pair that spelling looks the hop up under, because `<-` attributes
+ * a reply to the CALL it answers rather than to the direction the message
+ * travels (`callPair` in core/c4/resolve/steps.ts holds the measurement).
+ */
+function unbackedFinding(hop, attribution, place) {
+    const other = hop.step.isBackward
+        ? { spelling: `${hop.step.source} -> ${hop.step.target}`, when: "is not a return step" }
+        : { spelling: `${hop.step.target} <- ${hop.step.source}`, when: "is a return step" };
+    return {
+        severity: "error",
+        code: "usecase.step-unbacked",
+        subject: hop.view.id,
+        message: `${place}: nothing in the model declares ${attribution.from} -> ${attribution.to}, so this hop is ` +
+            "backed by no relationship — and LikeC4 reports no error for it, so the view still renders and the " +
+            "project still parses. Draw the edge in `model { }` (with `metadata { op '<operationId>' }` where it is " +
+            `a call), or, if this hop ${other.when}, write it as \`${other.spelling}\` — a reply is attributed to the ` +
+            `call it answers, so that spelling looks the hop up under ${attribution.to} -> ${attribution.from} instead.`,
+    };
+}
+/**
+ * `web -> orders.api "Calls createOrder" (op: createOrder)`, `(publishes: order.Placed)`,
+ * or `(no op)` where the edge declares no name at all.
+ *
+ * Every declared name is printed, the message ones included, because each is
+ * what the step's title can open with to pick this edge — a line that showed
+ * `no op` for a `publishes` edge would hide the one spelling that resolves it.
+ * An empty value is not printed: `op ''` parses, names nothing a title could
+ * open with, and `op: ` would read as a name somebody forgot to finish.
+ */
+function candidateLine(rel) {
+    const names = [
+        ...(rel.op === undefined || rel.op === "" ? [] : [`op: ${rel.op}`]),
+        ...(rel.publishes === undefined || rel.publishes === "" ? [] : [`publishes: ${rel.publishes}`]),
+        ...(rel.consumes === undefined || rel.consumes === "" ? [] : [`consumes: ${rel.consumes}`]),
+    ];
+    return `${rel.source} -> ${rel.target} "${rel.title ?? ""}" (${names.length === 0 ? "no op" : names.join(", ")})`;
+}
+/**
+ * A hop whose candidates disagree about the operation, and whose title picks
+ * none of them.
+ *
+ * WARN, not error, because the model is complete — every candidate is a
+ * relationship somebody drew on purpose — and the honest answer is sometimes
+ * "two paths, one flow". What loam refuses to do is pick: a guessed operation is
+ * indistinguishable from a right one in every rollup built over the use case,
+ * and it stays wrong invisibly. The AUTHOR can pick, by opening the step's
+ * title with the operation id it means (`pickedByTitle` in
+ * core/c4/resolve/steps.ts), and the message leads with that repair because it
+ * is the one that works in every scope. The older "draw the hop between the
+ * elements that name exactly one" is still offered, last and qualified: it works
+ * where the graded project declares those elements — a service's own flow over
+ * its containers, a map that draws a service's containers itself — and is
+ * closed on a fleet flow whose services are single elements on the map, which
+ * is the hop that had no repair at all before the title could pick.
+ *
+ * The example spells the author's own title behind a candidate's declared name,
+ * so the line to write is visible rather than described, and `pickingTitle`
+ * chooses it by trying it — an example that would leave the hop contested is
+ * never offered. Which candidate it names is otherwise arbitrary, the first
+ * that works, and the sentence says "for example" because of it: `details` is
+ * where the author finds the one meant. When no single name settles the
+ * disagreement — every name shared by candidates that still disagree — there is
+ * no example to give, and the sentence goes without one.
+ *
+ * `details` carries every candidate rather than the distinct ops, because the
+ * repair is made on a RELATIONSHIP: the author has to find the edge that names
+ * the wrong operation, and a list of operation names does not say which edge
+ * that is. An absent `metadata { op }` prints as `no op` and is a candidate like
+ * any other — it is exactly as much of a disagreement as a second name.
+ */
+function contestedFinding(hop, attribution, place) {
+    const example = pickingTitle(attribution.rels, hop.step.title);
+    return {
+        severity: "warn",
+        code: "usecase.step-contested",
+        subject: hop.view.id,
+        message: `${place}: ${attribution.rels.length} relationships back ${attribution.from} -> ` +
+            `${attribution.to} and they name ${attribution.ops.length} different operations, so nothing can say ` +
+            "which one this hop exercises. loam names the candidates instead of picking one — a guessed operation " +
+            "reads exactly like a right one in every rollup built over this flow. Say which one the hop means by " +
+            "opening the step's title with that candidate's operation id (or the message it publishes or consumes), " +
+            `then punctuation before any further words${example === undefined ? "" : ` — for example '${example}'`}; ` +
+            "or give the candidates one operation; or, where this project declares the elements behind each " +
+            "candidate, draw the hop between them.",
+        details: attribution.rels.map(candidateLine),
+    };
+}
+/**
+ * The service this hop calls, when the hop is a `step-unlinked` candidate at
+ * all — `null` when any of the four guards refuses. ALL FOUR are mechanical,
+ * and each closes a whole class of warnings that would otherwise be simply
+ * wrong. The count is stated because a reader auditing this function is meant to
+ * find four bullets and four `return null`s below and conclude that none of
+ * them is surplus: the one a miscount invites deleting is the actor guard, and
+ * deleting it puts the warning back on the first hop of almost every flow;
+ * deleting the last puts it on EVERY hop of every flow drawn inside a service.
+ *
+ *  - A `publishes` or `consumes` on ANY candidate means the hop does reach a
+ *    declared API — an AsyncAPI one. The event spine already grades it
+ *    (`spine.message-undefined` and its family), and asking for an `op` as well
+ *    would be loam demanding an HTTP operationId for a Kafka message. Read
+ *    across every candidate rather than the first, because on the service tier
+ *    the candidates are one call drawn as containers.
+ *  - The target must resolve to a real `services/<id>/`. Without it every hop
+ *    into an `#external` system, an actor, a database, a cache or a queue warns
+ *    — none of which owns an `openapi.yaml`, so none of them CAN carry the
+ *    operationId the message would be asking for. Through the shared resolver,
+ *    so "the provider" here and "the provider" in the spine check cannot
+ *    disagree about which element stands for which directory.
+ *  - The CALLER must not be an actor. A person is not a caller: `customer ->
+ *    checkoutWeb 'opens the basket'` is somebody using the app, and the app owes
+ *    no operationId for a click. The guard above does not cover this, because it
+ *    reads the TARGET — and the target here is one of ours, so without this the
+ *    warning fired on the FIRST HOP OF ALMOST EVERY FLOW, which is where a
+ *    sequence diagram puts its actor. Measured on the published example fleet
+ *    before it was added. This is the same exemption `commands/validate/fleet/census.ts`,
+ *    `commands/validate/arch-coverage.ts`, `core/gate/partners.ts` and `core/verify/checklist.ts`
+ *    each already apply, through the same `ACTOR_KINDS` — a person was never a
+ *    participant in any of loam's other censuses either.
+ *  - The CALLER must not resolve to the provider itself. A hop between two
+ *    containers of one service — `api -> db` inside a service's own project,
+ *    or the same pair on a landscape that draws the service as containers —
+ *    names no operation of that service's contract: an operationId is what a
+ *    caller OUTSIDE the boundary uses, and a service owes none to itself. The
+ *    three guards above all pass such a hop (the edge carries no message, the
+ *    target IS a real `services/<id>/`, the caller is a container), so without
+ *    this one the warning fired on every hop of every intra-service flow the
+ *    moment loam started reading them — and the message ("names no operation
+ *    of X's contract") was about X calling X. Through the same shared
+ *    resolver as the provider, so the two sides of the comparison cannot
+ *    disagree about which directory an element stands for.
+ *
+ * The op test reads the ATTRIBUTION rather than the relationships: an
+ * `attributed` verdict with no `op` means every candidate agreed the hop names
+ * no operation, which is the state this warn is about. Candidates that disagree
+ * never reach here at all — that is the suppression, and it is why it cannot be
+ * forgotten. Candidates the step's title picked out of a disagreement do reach
+ * here, as the picked ones only, and a pick never lands on an edge declaring no
+ * name: a title picks by `op`, `publishes` or `consumes`, so a picked verdict
+ * either carries its `op` or is a message hop the first guard lets go.
+ */
+function unlinkedProvider(attribution, grading) {
+    if (attribution.op !== undefined)
+        return null;
+    if (attribution.rels.some((rel) => rel.publishes !== undefined || rel.consumes !== undefined))
+        return null;
+    if (isActor(attribution.from, grading.model.elements))
+        return null;
+    const provider = grading.resolve(attribution.to);
+    if (grading.resolve(attribution.from) === provider)
+        return null;
+    return grading.services.has(provider) ? provider : null;
+}
+/**
+ * Is this endpoint a person rather than a system?
+ *
+ * Exact id, not the ancestor walk the service resolver does: an actor is a
+ * top-level element in every landscape loam has seen, and a nested one would be
+ * a person inside a system, which is not a shape the model has. An endpoint that
+ * names no element cannot occur — a step naming one is a LikeC4 reference error,
+ * so the document never reaches a check.
+ */
+function isActor(id, elements) {
+    const element = elements.find((candidate) => candidate.id === id);
+    return element !== undefined && ACTOR_KINDS.has(element.kind.toLowerCase());
+}
+/**
+ * A hop backed by the model and joined to no contract.
+ *
+ * The mirror of `spine.op-link-missing` at flow altitude: the use case reaches
+ * the fleet map and stops there, so nothing can say which operation of the
+ * provider's contract the step exercises — and the whole point of grading a use
+ * case is that the flow joins through to the API it drives.
+ */
+function unlinkedFinding(hop, attribution, provider, place) {
+    const backing = attribution.rels.length === 1 ? "one relationship" : `${attribution.rels.length} relationships`;
+    return {
+        severity: "warn",
+        code: "usecase.step-unlinked",
+        subject: hop.view.id,
+        message: `${place}: ${attribution.from} -> ${attribution.to} is backed by ${backing} carrying no ` +
+            "`metadata { op }` and no `publishes`/`consumes`, so this hop names no operation of " +
+            `${provider}'s contract — the use case reaches the fleet map and stops there. Add ` +
+            "`metadata { op '<operationId>' }` to the edge in `model { }`, or `metadata { publishes '<message>' }` / " +
+            "`consumes` where the hop is an event.",
+    };
+}
+/**
+ * The findings one hop earns — at most one, whatever is wrong with it.
+ *
+ * A `switch` over the closed verdict union with every arm returning, so a fourth
+ * verdict added upstream is a compile error here rather than a hop that silently
+ * stops being graded.
+ */
+export function stepFindings(hop, grading) {
+    const attribution = attributeStep(hop.step, grading.model);
+    const place = placeOf(hop, grading);
+    switch (attribution.verdict) {
+        case "unbacked":
+            return [unbackedFinding(hop, attribution, place)];
+        case "contested":
+            return [contestedFinding(hop, attribution, place)];
+        case "attributed": {
+            const provider = unlinkedProvider(attribution, grading);
+            return provider === null ? [] : [unlinkedFinding(hop, attribution, provider, place)];
+        }
+    }
+}
+//# sourceMappingURL=steps.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../../../src/core/usecases/grade/steps.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The three grades one hop of a use case can earn: `usecase.step-unbacked`,\n * `usecase.step-contested` and `usecase.step-unlinked`.\n *\n * The attribution itself is `core/c4/resolve/steps.ts`'s `attributeStep` — which declared\n * relationship backs a hop, oriented on `isBackward` and decided by the\n * DISTINCT-op count — and none of that reasoning is repeated here. This module\n * owns three things: which verdict earns which code, the four guards that keep\n * the warn honest, and the sentences.\n *\n * TWO SCOPES, ONE GRADER. The fleet target grades the `architecture/` project's\n * views and the service target grades a service's own project — every `.likec4`\n * beside `model.likec4`, read the way the renderer reads it\n * (`commands/validate/service/usecases/`). Both call `stepFindings` below with\n * their own `StepGrading`; what differs is only where a finding says the view\n * is (`place`). A second copy of the verdict→code mapping per scope is the\n * drift this package's banner forbids, which is why the intra-service case is\n * a fourth guard here rather than a grader of its own.\n *\n * WHY `step-unbacked` IS THE CHECK THAT EARNS THE FEATURE. A hop between two\n * elements that both exist, with no relationship between them anywhere in the\n * model, is ZERO LikeC4 errors: a `dynamic view` is allowed to show a call the\n * model never declared, so the diagram renders, the project parses, and every\n * other check in loam stays green. The flow reads as fine in every tool the\n * fleet has. If loam does not convict it, nothing does — which is why it is an\n * error rather than an advisory.\n *\n * ONE BREACH, ONE FINDING, and here that is structural rather than remembered.\n * `contested` and `attributed` are disjoint verdicts, so deriving\n * `step-unlinked` from the `attributed` arm — never from the candidate\n * relationships — is what makes a contested step report once. A grader that\n * walked `rels` looking for a missing `op` would convict the same hop twice:\n * once for the disagreement, and once for whichever candidate happened to carry\n * no operation at all.\n */\nimport { attributeStep, pickingTitle, type StepAttribution, type StepScope } from \"../../c4/resolve/steps.js\";\nimport type { Elem, Rel } from \"../../c4/likec4.js\";\nimport type { ParsedStep, ParsedView } from \"../../c4/parsed/dynamic-views.js\";\nimport { ACTOR_KINDS } from \"../../vocabulary/maturity.js\";\nimport type { Finding } from \"../../vocabulary/report.js\";\nimport { stepPlace, type ViewPlace } from \"../place.js\";\n\n/** One hop being graded and the view it belongs to — never passed apart. */\nexport interface GradedStep {\n  view: ParsedView;\n  step: ParsedStep;\n}\n\n/**\n * What a hop is graded against, built ONCE per run.\n *\n * `services` and `model.known` are the same set by construction (`./usecases.ts`\n * builds both from one value), which is what stops \"which service is this\n * element\" being answered one way by the attribution and another by the provider\n * guard below. `resolve` is injected for the same reason `fleetShapeFindings`\n * takes it: the fleet target already holds the shared element→service resolver,\n * and a second one built here could not disagree today but would be a second\n * place to change.\n */\nexport interface StepGrading {\n  model: StepScope;\n  /**\n   * The `services/<id>/` directories that exist. The SAME enumerated set in\n   * both scopes — the service target hands over the whole fleet too, never an\n   * empty set — so the documented invariant above (`services` and `model.known`\n   * are one value) holds wherever this grader runs, and the intra-service\n   * exemption is the fourth guard in `unlinkedProvider` rather than a scope\n   * that quietly disables the provider test.\n   */\n  services: ReadonlySet<string>;\n  /** The shared element→service resolver every other edge join uses. */\n  resolve: (id: string) => string;\n  /**\n   * Where a finding says the view is — the opening of every message in this\n   * family. REQUIRED since the graders moved into `core/`: the fleet target's\n   * `landscape: architecture/<file> — dynamic view '<id>'` is `viewPlace` in\n   * `commands/validate/fleet/usecases/place.ts`, command vocabulary core may not\n   * import, so every scope states its own. The feature gate injects the feature's\n   * `usecases/` file (`./feature.ts`), and the service target\n   * injects its own, because a view read out of a service's project carries a\n   * `sourcePath` relative to the SERVICE directory, and the `landscape:`\n   * opening is the fleet target's name — a finding filed on a service must not\n   * claim it (`../place.ts` records why the prefix stayed command vocabulary).\n   */\n  place: ViewPlace;\n}\n\ntype Unbacked = Extract<StepAttribution, { verdict: \"unbacked\" }>;\ntype Contested = Extract<StepAttribution, { verdict: \"contested\" }>;\ntype Attributed = Extract<StepAttribution, { verdict: \"attributed\" }>;\n\n/**\n * `…checkout.likec4 — dynamic view 'uc_checkout' step 2 'authorizes the payment'`.\n *\n * Spelled once per hop in `stepFindings` and handed to each sentence builder as\n * a string, rather than recomputed from the grading inside each of them: three\n * builders reaching for `grading.place` on their own would be three\n * places for one scope to forget the injection.\n */\nfunction placeOf(hop: GradedStep, grading: StepGrading): string {\n  return `${grading.place(hop.view)} ${stepPlace(hop.step)}`;\n}\n\n/**\n * A hop nothing in the model backs.\n *\n * Two fixes, because there are genuinely two mistakes that land here and the\n * author is the only one who can say which they made: the edge really is\n * missing, or the hop is a reply written the long way round. The second is\n * offered as the OTHER spelling of what they already typed — suggesting the\n * spelling they used would be a hint that restates the defect — and the sentence\n * says which pair that spelling looks the hop up under, because `<-` attributes\n * a reply to the CALL it answers rather than to the direction the message\n * travels (`callPair` in core/c4/resolve/steps.ts holds the measurement).\n */\nfunction unbackedFinding(hop: GradedStep, attribution: Unbacked, place: string): Finding {\n  const other = hop.step.isBackward\n    ? { spelling: `${hop.step.source} -> ${hop.step.target}`, when: \"is not a return step\" }\n    : { spelling: `${hop.step.target} <- ${hop.step.source}`, when: \"is a return step\" };\n  return {\n    severity: \"error\",\n    code: \"usecase.step-unbacked\",\n    subject: hop.view.id,\n    message:\n      `${place}: nothing in the model declares ${attribution.from} -> ${attribution.to}, so this hop is ` +\n      \"backed by no relationship — and LikeC4 reports no error for it, so the view still renders and the \" +\n      \"project still parses. Draw the edge in `model { }` (with `metadata { op '<operationId>' }` where it is \" +\n      `a call), or, if this hop ${other.when}, write it as \\`${other.spelling}\\` — a reply is attributed to the ` +\n      `call it answers, so that spelling looks the hop up under ${attribution.to} -> ${attribution.from} instead.`,\n  };\n}\n\n/**\n * `web -> orders.api \"Calls createOrder\" (op: createOrder)`, `(publishes: order.Placed)`,\n * or `(no op)` where the edge declares no name at all.\n *\n * Every declared name is printed, the message ones included, because each is\n * what the step's title can open with to pick this edge — a line that showed\n * `no op` for a `publishes` edge would hide the one spelling that resolves it.\n * An empty value is not printed: `op ''` parses, names nothing a title could\n * open with, and `op: ` would read as a name somebody forgot to finish.\n */\nfunction candidateLine(rel: Rel): string {\n  const names = [\n    ...(rel.op === undefined || rel.op === \"\" ? [] : [`op: ${rel.op}`]),\n    ...(rel.publishes === undefined || rel.publishes === \"\" ? [] : [`publishes: ${rel.publishes}`]),\n    ...(rel.consumes === undefined || rel.consumes === \"\" ? [] : [`consumes: ${rel.consumes}`]),\n  ];\n  return `${rel.source} -> ${rel.target} \"${rel.title ?? \"\"}\" (${names.length === 0 ? \"no op\" : names.join(\", \")})`;\n}\n\n/**\n * A hop whose candidates disagree about the operation, and whose title picks\n * none of them.\n *\n * WARN, not error, because the model is complete — every candidate is a\n * relationship somebody drew on purpose — and the honest answer is sometimes\n * \"two paths, one flow\". What loam refuses to do is pick: a guessed operation is\n * indistinguishable from a right one in every rollup built over the use case,\n * and it stays wrong invisibly. The AUTHOR can pick, by opening the step's\n * title with the operation id it means (`pickedByTitle` in\n * core/c4/resolve/steps.ts), and the message leads with that repair because it\n * is the one that works in every scope. The older \"draw the hop between the\n * elements that name exactly one\" is still offered, last and qualified: it works\n * where the graded project declares those elements — a service's own flow over\n * its containers, a map that draws a service's containers itself — and is\n * closed on a fleet flow whose services are single elements on the map, which\n * is the hop that had no repair at all before the title could pick.\n *\n * The example spells the author's own title behind a candidate's declared name,\n * so the line to write is visible rather than described, and `pickingTitle`\n * chooses it by trying it — an example that would leave the hop contested is\n * never offered. Which candidate it names is otherwise arbitrary, the first\n * that works, and the sentence says \"for example\" because of it: `details` is\n * where the author finds the one meant. When no single name settles the\n * disagreement — every name shared by candidates that still disagree — there is\n * no example to give, and the sentence goes without one.\n *\n * `details` carries every candidate rather than the distinct ops, because the\n * repair is made on a RELATIONSHIP: the author has to find the edge that names\n * the wrong operation, and a list of operation names does not say which edge\n * that is. An absent `metadata { op }` prints as `no op` and is a candidate like\n * any other — it is exactly as much of a disagreement as a second name.\n */\nfunction contestedFinding(hop: GradedStep, attribution: Contested, place: string): Finding {\n  const example = pickingTitle(attribution.rels, hop.step.title);\n  return {\n    severity: \"warn\",\n    code: \"usecase.step-contested\",\n    subject: hop.view.id,\n    message:\n      `${place}: ${attribution.rels.length} relationships back ${attribution.from} -> ` +\n      `${attribution.to} and they name ${attribution.ops.length} different operations, so nothing can say ` +\n      \"which one this hop exercises. loam names the candidates instead of picking one — a guessed operation \" +\n      \"reads exactly like a right one in every rollup built over this flow. Say which one the hop means by \" +\n      \"opening the step's title with that candidate's operation id (or the message it publishes or consumes), \" +\n      `then punctuation before any further words${example === undefined ? \"\" : ` — for example '${example}'`}; ` +\n      \"or give the candidates one operation; or, where this project declares the elements behind each \" +\n      \"candidate, draw the hop between them.\",\n    details: attribution.rels.map(candidateLine),\n  };\n}\n\n/**\n * The service this hop calls, when the hop is a `step-unlinked` candidate at\n * all — `null` when any of the four guards refuses. ALL FOUR are mechanical,\n * and each closes a whole class of warnings that would otherwise be simply\n * wrong. The count is stated because a reader auditing this function is meant to\n * find four bullets and four `return null`s below and conclude that none of\n * them is surplus: the one a miscount invites deleting is the actor guard, and\n * deleting it puts the warning back on the first hop of almost every flow;\n * deleting the last puts it on EVERY hop of every flow drawn inside a service.\n *\n *  - A `publishes` or `consumes` on ANY candidate means the hop does reach a\n *    declared API — an AsyncAPI one. The event spine already grades it\n *    (`spine.message-undefined` and its family), and asking for an `op` as well\n *    would be loam demanding an HTTP operationId for a Kafka message. Read\n *    across every candidate rather than the first, because on the service tier\n *    the candidates are one call drawn as containers.\n *  - The target must resolve to a real `services/<id>/`. Without it every hop\n *    into an `#external` system, an actor, a database, a cache or a queue warns\n *    — none of which owns an `openapi.yaml`, so none of them CAN carry the\n *    operationId the message would be asking for. Through the shared resolver,\n *    so \"the provider\" here and \"the provider\" in the spine check cannot\n *    disagree about which element stands for which directory.\n *  - The CALLER must not be an actor. A person is not a caller: `customer ->\n *    checkoutWeb 'opens the basket'` is somebody using the app, and the app owes\n *    no operationId for a click. The guard above does not cover this, because it\n *    reads the TARGET — and the target here is one of ours, so without this the\n *    warning fired on the FIRST HOP OF ALMOST EVERY FLOW, which is where a\n *    sequence diagram puts its actor. Measured on the published example fleet\n *    before it was added. This is the same exemption `commands/validate/fleet/census.ts`,\n *    `commands/validate/arch-coverage.ts`, `core/gate/partners.ts` and `core/verify/checklist.ts`\n *    each already apply, through the same `ACTOR_KINDS` — a person was never a\n *    participant in any of loam's other censuses either.\n *  - The CALLER must not resolve to the provider itself. A hop between two\n *    containers of one service — `api -> db` inside a service's own project,\n *    or the same pair on a landscape that draws the service as containers —\n *    names no operation of that service's contract: an operationId is what a\n *    caller OUTSIDE the boundary uses, and a service owes none to itself. The\n *    three guards above all pass such a hop (the edge carries no message, the\n *    target IS a real `services/<id>/`, the caller is a container), so without\n *    this one the warning fired on every hop of every intra-service flow the\n *    moment loam started reading them — and the message (\"names no operation\n *    of X's contract\") was about X calling X. Through the same shared\n *    resolver as the provider, so the two sides of the comparison cannot\n *    disagree about which directory an element stands for.\n *\n * The op test reads the ATTRIBUTION rather than the relationships: an\n * `attributed` verdict with no `op` means every candidate agreed the hop names\n * no operation, which is the state this warn is about. Candidates that disagree\n * never reach here at all — that is the suppression, and it is why it cannot be\n * forgotten. Candidates the step's title picked out of a disagreement do reach\n * here, as the picked ones only, and a pick never lands on an edge declaring no\n * name: a title picks by `op`, `publishes` or `consumes`, so a picked verdict\n * either carries its `op` or is a message hop the first guard lets go.\n */\nfunction unlinkedProvider(attribution: Attributed, grading: StepGrading): string | null {\n  if (attribution.op !== undefined) return null;\n  if (attribution.rels.some((rel) => rel.publishes !== undefined || rel.consumes !== undefined)) return null;\n  if (isActor(attribution.from, grading.model.elements)) return null;\n  const provider = grading.resolve(attribution.to);\n  if (grading.resolve(attribution.from) === provider) return null;\n  return grading.services.has(provider) ? provider : null;\n}\n\n/**\n * Is this endpoint a person rather than a system?\n *\n * Exact id, not the ancestor walk the service resolver does: an actor is a\n * top-level element in every landscape loam has seen, and a nested one would be\n * a person inside a system, which is not a shape the model has. An endpoint that\n * names no element cannot occur — a step naming one is a LikeC4 reference error,\n * so the document never reaches a check.\n */\nfunction isActor(id: string, elements: Elem[]): boolean {\n  const element = elements.find((candidate) => candidate.id === id);\n  return element !== undefined && ACTOR_KINDS.has(element.kind.toLowerCase());\n}\n\n/**\n * A hop backed by the model and joined to no contract.\n *\n * The mirror of `spine.op-link-missing` at flow altitude: the use case reaches\n * the fleet map and stops there, so nothing can say which operation of the\n * provider's contract the step exercises — and the whole point of grading a use\n * case is that the flow joins through to the API it drives.\n */\nfunction unlinkedFinding(hop: GradedStep, attribution: Attributed, provider: string, place: string): Finding {\n  const backing =\n    attribution.rels.length === 1 ? \"one relationship\" : `${attribution.rels.length} relationships`;\n  return {\n    severity: \"warn\",\n    code: \"usecase.step-unlinked\",\n    subject: hop.view.id,\n    message:\n      `${place}: ${attribution.from} -> ${attribution.to} is backed by ${backing} carrying no ` +\n      \"`metadata { op }` and no `publishes`/`consumes`, so this hop names no operation of \" +\n      `${provider}'s contract — the use case reaches the fleet map and stops there. Add ` +\n      \"`metadata { op '<operationId>' }` to the edge in `model { }`, or `metadata { publishes '<message>' }` / \" +\n      \"`consumes` where the hop is an event.\",\n  };\n}\n\n/**\n * The findings one hop earns — at most one, whatever is wrong with it.\n *\n * A `switch` over the closed verdict union with every arm returning, so a fourth\n * verdict added upstream is a compile error here rather than a hop that silently\n * stops being graded.\n */\nexport function stepFindings(hop: GradedStep, grading: StepGrading): Finding[] {\n  const attribution = attributeStep(hop.step, grading.model);\n  const place = placeOf(hop, grading);\n  switch (attribution.verdict) {\n    case \"unbacked\":\n      return [unbackedFinding(hop, attribution, place)];\n    case \"contested\":\n      return [contestedFinding(hop, attribution, place)];\n    case \"attributed\": {\n      const provider = unlinkedProvider(attribution, grading);\n      return provider === null ? [] : [unlinkedFinding(hop, attribution, provider, place)];\n    }\n  }\n}\n"]}