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

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/{commands/validate/fleet/usecases → core/usecases/grade}/steps.js

@@ -2,12 +2,21 @@
  * 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/arch.ts`'s `attributeStep` — which declared
+ * 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 three guards that keep
+ * 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
@@ -24,13 +33,19 @@
  * once for the disagreement, and once for whichever candidate happened to carry
  * no operation at all.
  */
-import { attributeStep } from "../../../../core/c4/arch.js";
-import { ACTOR_KINDS } from "../../../../core/vocabulary/maturity.js";
-import { stepPlace } from "../../../../core/usecases/place.js";
-import { viewPlace } from "./place.js";
-/** `…checkout.likec4 — dynamic view 'uc_checkout' step 2 'authorizes the payment'`. */
-function placeOf(hop) {
-    return `${viewPlace(hop.view)} ${stepPlace(hop.step)}`;
+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.
@@ -42,9 +57,9 @@ function placeOf(hop) {
  * 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/arch.ts holds the measurement).
+ * travels (`callPair` in core/c4/resolve/steps.ts holds the measurement).
  */
-function unbackedFinding(hop, attribution) {
+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" };
@@ -52,26 +67,57 @@ function unbackedFinding(hop, attribution) {
         severity: "error",
         code: "usecase.step-unbacked",
         subject: hop.view.id,
-        message: `${placeOf(hop)}: nothing in the model declares ${attribution.from} -> ${attribution.to}, so this hop is ` +
+        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)`, or `(no op)` where the edge declares none. */
+/**
+ * `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 op = rel.op === undefined ? "no op" : `op: ${rel.op}`;
-    return `${rel.source} -> ${rel.target} "${rel.title ?? ""}" (${op})`;
+    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.
+ * 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.
+ * 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
@@ -79,27 +125,32 @@ function candidateLine(rel) {
  * 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) {
+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: `${placeOf(hop)}: ${attribution.rels.length} relationships back ${attribution.from} -> ` +
+        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. Give the candidates one operation, " +
-            "or draw the hop between the elements that name exactly one.",
+            "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 three guards refuses. ALL THREE are mechanical,
+ * 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 three bullets and three `return null`s below and conclude that none of
- * them is surplus: the one a miscount invites deleting is the last, and deleting
- * it puts the warning back on the first hop of almost every flow.
+ * 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
@@ -119,16 +170,31 @@ function contestedFinding(hop, attribution) {
  *    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 `fleet/census.ts`,
- *    `arch-coverage.ts`, `core/gate/partners.ts` and `core/verify/checklist.ts`
+ *    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.
+ * 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)
@@ -138,6 +204,8 @@ function unlinkedProvider(attribution, grading) {
     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;
 }
 /**
@@ -161,13 +229,13 @@ function isActor(id, elements) {
  * 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) {
+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: `${placeOf(hop)}: ${attribution.from} -> ${attribution.to} is backed by ${backing} carrying no ` +
+        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>' }` / " +
@@ -183,14 +251,15 @@ function unlinkedFinding(hop, attribution, provider) {
  */
 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)];
+            return [unbackedFinding(hop, attribution, place)];
         case "contested":
-            return [contestedFinding(hop, attribution)];
+            return [contestedFinding(hop, attribution, place)];
         case "attributed": {
             const provider = unlinkedProvider(attribution, grading);
-            return provider === null ? [] : [unlinkedFinding(hop, attribution, provider)];
+            return provider === null ? [] : [unlinkedFinding(hop, attribution, provider, place)];
         }
     }
 }

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

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

@@ -2,14 +2,26 @@
  * The use-case axis of `validate --all`: the `dynamic view`s a fleet declares,
  * graded as business flows against the model they are drawn over.
  *
+ * IN `core/` SINCE THE FEATURE GATE BECAME ITS SECOND CALLER. It began as
+ * `commands/validate/fleet/usecases/`, the fleet target's own package; the
+ * archive gate and `loam status` both grade a feature through
+ * `core/coherence/`, which may not import a command, so a feature's own flows
+ * archived ungraded and the next `validate --all` convicted them
+ * (`usecase.step-unbacked`, `usecase.requirement-unresolved` — the real-fleet
+ * review, 2026-10-21). One grader for both scopes is the rule this package's
+ * banner already stated for the service target; `./feature.ts` is the third
+ * caller, and `place` on the scope is the one thing each states for itself.
+ *
  * ONLY VIEWS CARRYING A RESERVED TAG ARE GRADED, and that opt-in is what lets
  * this ship into a fleet that already has diagrams. An untagged `dynamic view`
  * is somebody's hand-drawn sequence — drawn to explain something to a person,
  * not to be joined to a model — and grading it would turn every existing docs
- * repo red on upgrade over documents nobody promised anything about. A `#cap-`
- * or `#req-` tag is the author saying "this is a use case; hold it to the
- * model", and nothing else says it: a view with no tags and a view whose tags
- * are all somebody's own vocabulary are the same thing here.
+ * repo red on upgrade over documents nobody promised anything about. A `#cap-`,
+ * `#req-` or `#suite-` tag is the author saying "this is a use case; hold it to
+ * the model", and nothing else says it: a view with no tags and a view whose
+ * tags are all somebody's own vocabulary are the same thing here. A
+ * `#suite-`-only view resolves nothing below — it carries no claim — and its
+ * hops are graded like any other's.
  *
  * THE TAG OPTS A VIEW IN WHETHER OR NOT IT RESOLVES. A `#cap-` slug that names
  * no declared capability is a broken claim about the vocabulary, not a withdrawn
@@ -28,13 +40,13 @@
  * than per hop — the per-hop cost is a scan, so anything rebuilt per hop is paid
  * against every hop in the fleet.
  */
-import { compareIds } from "../../../../core/repo/entries.js";
-import { resolveCapabilityTags } from "../../../../core/capabilities/usecase-join.js";
-import { isUseCase } from "../../../../core/usecases/fleet.js";
+import { compareIds } from "../../repo/entries.js";
+import { resolveCapabilityTags } from "../../capabilities/usecase-join.js";
+import { isUseCase } from "../fleet.js";
 import { capabilityTagFindings } from "./capability-tag.js";
 import { requirementTagFindings } from "./requirement-tag.js";
 import { stepFindings } from "./steps.js";
-import { viewFile } from "../../../../core/usecases/place.js";
+import { viewFile } from "../place.js";
 /**
  * The views that opted in, in a stable order.
  *
@@ -73,6 +85,7 @@ export function useCaseFindings(scope) {
         model: { elements: scope.elements, relationships: scope.relationships, known: scope.services },
         services: scope.services,
         resolve: scope.resolve,
+        place: scope.place,
     };
     const findings = [];
     for (const view of gradedViews(scope.views)) {
@@ -88,8 +101,8 @@ export function useCaseFindings(scope) {
         // the capability axis would be convicted for the axis not existing.
         if (scope.capabilities !== null) {
             const claims = resolveCapabilityTags(view.tags, scope.capabilities);
-            findings.push(...capabilityTagFindings(view, claims));
-            findings.push(...requirementTagFindings(view, claims, scope.requirementsOf));
+            findings.push(...capabilityTagFindings(view, claims, scope.place));
+            findings.push(...requirementTagFindings(view, claims, scope.requirementsOf, scope.place));
         }
         for (const step of view.steps)
             findings.push(...stepFindings({ view, step }, grading));

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

@@ -0,0 +1 @@
+{"version":3,"file":"usecases.js","sourceRoot":"","sources":["../../../../src/core/usecases/grade/usecases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAoB,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAkB,MAAM,aAAa,CAAC;AAkDvD;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,WAAW,CAAC,KAA4B;IAC/C,OAAO,KAAK;SACT,MAAM,CAAC,SAAS,CAAC;SACjB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,KAAmB;IACjD,MAAM,OAAO,GAAgB;QAC3B,mEAAmE;QACnE,0EAA0E;QAC1E,8DAA8D;QAC9D,KAAK,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE;QAC9F,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,KAAK,CAAC,KAAK;KACnB,CAAC;IACF,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,4EAA4E;QAC5E,6EAA6E;QAC7E,sEAAsE;QACtE,gDAAgD;QAChD,EAAE;QACF,wEAAwE;QACxE,2EAA2E;QAC3E,wEAAwE;QACxE,0EAA0E;QAC1E,oEAAoE;QACpE,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;YACpE,QAAQ,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;YACnE,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5F,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * The use-case axis of `validate --all`: the `dynamic view`s a fleet declares,\n * graded as business flows against the model they are drawn over.\n *\n * IN `core/` SINCE THE FEATURE GATE BECAME ITS SECOND CALLER. It began as\n * `commands/validate/fleet/usecases/`, the fleet target's own package; the\n * archive gate and `loam status` both grade a feature through\n * `core/coherence/`, which may not import a command, so a feature's own flows\n * archived ungraded and the next `validate --all` convicted them\n * (`usecase.step-unbacked`, `usecase.requirement-unresolved` — the real-fleet\n * review, 2026-10-21). One grader for both scopes is the rule this package's\n * banner already stated for the service target; `./feature.ts` is the third\n * caller, and `place` on the scope is the one thing each states for itself.\n *\n * ONLY VIEWS CARRYING A RESERVED TAG ARE GRADED, and that opt-in is what lets\n * this ship into a fleet that already has diagrams. An untagged `dynamic view`\n * is somebody's hand-drawn sequence — drawn to explain something to a person,\n * not to be joined to a model — and grading it would turn every existing docs\n * repo red on upgrade over documents nobody promised anything about. A `#cap-`,\n * `#req-` or `#suite-` tag is the author saying \"this is a use case; hold it to\n * the model\", and nothing else says it: a view with no tags and a view whose\n * tags are all somebody's own vocabulary are the same thing here. A\n * `#suite-`-only view resolves nothing below — it carries no claim — and its\n * hops are graded like any other's.\n *\n * THE TAG OPTS A VIEW IN WHETHER OR NOT IT RESOLVES. A `#cap-` slug that names\n * no declared capability is a broken claim about the vocabulary, not a withdrawn\n * one, so its steps are still graded — and the step grades read\n * `architecture/capabilities.yaml` nowhere at all. Coupling them would mean a\n * fleet that has not adopted the capability axis could never have a use case\n * checked, which inverts the adoption order the whole axis is built on: draw the\n * flow first, name the capability when the vocabulary exists.\n *\n * Everything here is LINEAR IN STEPS over documents `validate --all` has already\n * parsed, and nothing in it reads a file or throws — a fleet with no tagged view\n * produces exactly nothing. Linear in steps is not free per step: `attributeStep`\n * scans `relationships` once for the exact tier and again for the resolved one,\n * and `isActor` scans `elements`, so the real shape is O(steps × relationships)\n * plus O(steps × elements). That is why `StepGrading` is built once below rather\n * than per hop — the per-hop cost is a scan, so anything rebuilt per hop is paid\n * against every hop in the fleet.\n */\nimport { compareIds } from \"../../repo/entries.js\";\nimport { resolveCapabilityTags } from \"../../capabilities/usecase-join.js\";\nimport { isUseCase } from \"../fleet.js\";\nimport type { Elem, Rel } from \"../../c4/likec4.js\";\nimport type { ParsedView } from \"../../c4/parsed/dynamic-views.js\";\nimport type { Finding } from \"../../vocabulary/report.js\";\nimport { capabilityTagFindings } from \"./capability-tag.js\";\nimport { requirementTagFindings } from \"./requirement-tag.js\";\nimport { stepFindings, type StepGrading } from \"./steps.js\";\nimport { viewFile, type ViewPlace } from \"../place.js\";\n\n/** What the use-case grades run over: the views, the model they are drawn on, and the fleet. */\nexport interface UseCaseScope {\n  /**\n   * Every `dynamic view` the `architecture/` PROJECT declares, each carrying the\n   * file it was written in.\n   *\n   * The caller must pass views that came from `loadProject` and no others. Only\n   * that loader gives a view a `sourcePath` relative to `architecture/`; the\n   * single-file loaders name every document after themselves (`source.c4`), and\n   * a finding built from one of those would name a file that has never existed\n   * — see `../place.ts`, which is where the path is spelled. A feature's own\n   * flows come from the staged post-merge project (`../delta/overlay.ts`), whose\n   * `sourcePath` is mapped back to the file the author wrote.\n   */\n  views: readonly ParsedView[];\n  elements: Elem[];\n  relationships: Rel[];\n  /** The `services/<id>/` directories that exist. */\n  services: ReadonlySet<string>;\n  /** The shared element→service resolver — the same one every other edge join uses. */\n  resolve: (id: string) => string;\n  /**\n   * The declared capability ids, or `null` when `architecture/capabilities.yaml`\n   * is absent or does not read as a vocabulary.\n   *\n   * `null` and `[]` are deliberately different answers, and the join at\n   * `core/capabilities/usecase-join.ts` says why it cannot tell them apart\n   * itself: an empty list means \"the fleet declares no capabilities\", which is a\n   * real verdict every tag then fails against, while `null` means \"there is no\n   * vocabulary to grade against\" and suspends the tag grade entirely. The\n   * caller applies the ladder because the caller is the one that read the file.\n   */\n  capabilities: readonly string[] | null;\n  /**\n   * The requirement ids one capability's document declares, or `undefined` for a\n   * capability with no document — the scope a `#req-` tag is resolved in.\n   *\n   * A function rather than the map itself, so this package never learns what a\n   * capability document is: the fleet target reads them once\n   * (`capabilityRequirementIndex`) and hands the lookup over. `undefined` and an\n   * empty set are different answers here, exactly as they are one join over —\n   * no document at all, against a document declaring no promises yet.\n   */\n  requirementsOf: (capability: string) => ReadonlySet<string> | undefined;\n  /** Where every finding says its view is — the scope's own spelling (`ViewPlace`). */\n  place: ViewPlace;\n}\n\n/**\n * The views that opted in, in a stable order.\n *\n * The opt-in itself is `isUseCase` in `core/usecases/fleet.ts` and is not\n * restated here. It used to be — the same `startsWith` pair, spelled a second\n * time — and the two spellings drifted: this one took either reserved prefix\n * while the reader-side one took `#cap-` alone, so `validate` graded a\n * `#req-`-only flow that `loam diff`, `delta`, `status`, the packs and `list\n * capabilities` could not see. What is left here is the ORDER, which is this\n * package's own concern.\n *\n * Sorted by (file, view id) rather than reported in LikeC4's own record order:\n * nothing in loam has measured that the parse preserves declaration order, so a\n * report whose row order depends on that would reorder under a dependency bump\n * — the diff-stability rule `core/capabilities/rollup.ts` states for its rows,\n * applied to findings.\n */\nfunction gradedViews(views: readonly ParsedView[]): ParsedView[] {\n  return views\n    .filter(isUseCase)\n    .sort((a, b) => compareIds(viewFile(a), viewFile(b)) || compareIds(a.id, b.id));\n}\n\n/**\n * Every use-case finding a fleet's declared views earn.\n *\n * The grading record is built once and shared across every step of every view:\n * `attributeStep` caches its element→service resolver on the identity of the\n * elements array and the fleet set, so handing it one `StepScope` for the whole\n * run is what keeps the fleet's use cases from rebuilding that id map per hop.\n */\nexport function useCaseFindings(scope: UseCaseScope): Finding[] {\n  const grading: StepGrading = {\n    // `known` and `services` come from ONE value, so the fleet set the\n    // attribution resolves against and the fleet set the provider guard tests\n    // cannot drift apart into two answers about the same element.\n    model: { elements: scope.elements, relationships: scope.relationships, known: scope.services },\n    services: scope.services,\n    resolve: scope.resolve,\n    place: scope.place,\n  };\n  const findings: Finding[] = [];\n  for (const view of gradedViews(scope.views)) {\n    // ONE resolution of this view's capability tags, shared by both grades. The\n    // `#req-` tag is scoped by exactly the capabilities the `#cap-` tags resolve\n    // to, so resolving twice would be two chances to disagree about which\n    // document a `Requirement-ID` is unique inside.\n    //\n    // THE LADDER IS THE `null`, NOT AN EMPTY LIST, and the distinction is a\n    // wrong answer away: a suspended vocabulary handed on as `[]` reads to the\n    // requirement grade as \"this view resolves no capability\", which is its\n    // `unscoped` ERROR — so every `#req-` tag in a fleet that has not adopted\n    // the capability axis would be convicted for the axis not existing.\n    if (scope.capabilities !== null) {\n      const claims = resolveCapabilityTags(view.tags, scope.capabilities);\n      findings.push(...capabilityTagFindings(view, claims, scope.place));\n      findings.push(...requirementTagFindings(view, claims, scope.requirementsOf, scope.place));\n    }\n    for (const step of view.steps) findings.push(...stepFindings({ view, step }, grading));\n  }\n  return findings;\n}\n"]}

package/dist/core/usecases/operations.js

@@ -7,24 +7,28 @@
  * requirement is a heading in somebody else's spec, while "step 4 of Checkout
  * stops working" is the fact a human weighs a pull request against. This module
  * is the join that produces that sentence, and it produces NOTHING ELSE — no
- * finding, no code, no severity. `core/diff/victims.ts` folds its answers into
- * the `details[]` of the two codes that already exist.
+ * finding, no code, no severity. `core/consumers/consumers.ts` folds its
+ * answers into the `details[]` of the two codes that already exist.
  *
  * ## Attributed is a victim; contested is a suspension
  *
  * The distinction is the whole reason this module is careful rather than a
- * filter. `attributeStep` (core/c4/arch.ts) grades a hop by the DISTINCT-op
+ * filter. `attributeStep` (core/c4/resolve/steps.ts) grades a hop by the DISTINCT-op
  * count across the relationships backing it:
  *
  *  - `attributed` with `op === X` means every relationship behind the hop agrees
- *    the hop exercises X. Remove X and the flow breaks at that hop. That is
- *    positive evidence, and it is a victim.
- *  - `contested` means the relationships DISAGREE, so loam does not know which
- *    operation the hop exercises. It must not claim the flow breaks — a guessed
- *    victim reads exactly like a real one and turns a warn into an error on
- *    somebody's PR — and it must not go silent either, because silence here is
- *    the fail-open shape `ConsumerScan.suspended` exists to forbid. It is a
- *    suspension: loam says it could not answer.
+ *    the hop exercises X, or they disagree and the step's title opens with a
+ *    name declared by candidates that agree on X — the author naming the one
+ *    the hop means, by its op or by the message that edge also carries. Remove
+ *    X and the flow breaks at that hop. That is positive evidence, and it is a
+ *    victim.
+ *  - `contested` means the relationships DISAGREE and the title names none of
+ *    them, so loam does not know which operation the hop exercises. It must not
+ *    claim the flow breaks — a guessed victim reads exactly like a real one and
+ *    turns a warn into an error on somebody's PR — and it must not go silent
+ *    either, because silence here is the fail-open shape
+ *    `ConsumerScan.suspended` exists to forbid. It is a suspension: loam says it
+ *    could not answer.
  *
  * A contested hop is suspended only when X is among its candidate operations.
  * That is not a noise trade, it is the honest boundary: the candidates ARE the
@@ -38,7 +42,7 @@
  * that convicts it, and repeating that here would file a modelling defect
  * against whoever happened to remove an endpoint.
  */
-import { attributeStep } from "../c4/arch.js";
+import { attributeStep } from "../c4/resolve/steps.js";
 import { hopPlace } from "./place.js";
 const EMPTY = { breaks: [], unsure: [] };
 /** Every hop of every graded use case, view order preserved, so output is stable. */
@@ -49,8 +53,9 @@ function hops(scan) {
  * The flows one removed operation breaks, and the ones loam cannot answer for.
  *
  * An `unreadable` scan contributes NOTHING — neither break nor suspension — and
- * that is `core/diff/victims.ts`'s own landscape doctrine applied one axis over:
- * an unreadable fleet map proves nothing either way, `landscape.invalid` is
+ * that is the consumer index's own landscape doctrine (`livingMap` in
+ * `core/consumers/current.ts`, which reads the map for every consumer
+ * question) applied one axis over: an unreadable fleet map proves nothing either way, `landscape.invalid` is
  * validate's finding to make, and inventing doubt out of a parse error would
  * point the reviewer at a file their change never touched. The caller reports
  * the hole; this join stays quiet about it.
@@ -68,6 +73,13 @@ export function hopsExercising(scan, removed) {
         // payment-service rather than against a service called "api".
         if (scan.resolve(attribution.to) !== removed.provider)
             continue;
+        // And the CALLER, through the same resolver: a hop whose two endpoints
+        // resolve to one service is that service calling itself, which owes no
+        // operationId of its own contract — `usecase.step-unlinked`'s fourth guard,
+        // applied to the victim join. Without it an internal hop was a break of the
+        // provider's own removal (verification 2026-09-04, R3).
+        if (scan.resolve(attribution.from) === removed.provider)
+            continue;
         if (attribution.verdict === "attributed") {
             if (attribution.op === removed.op)
                 out.breaks.push(hopPlace(view, step));

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"place.js","sourceRoot":"","sources":["../../../src/core/usecases/place.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAgB;IACvC,OAAO,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,gBAAgB,IAAI,CAAC,UAAU,EAAE,CAAC;AAC7F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,IAAgB;IACxC,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,KAAK,GAAG,CAAC;AACpG,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAgB,EAAE,IAAgB;IACzD,OAAO,aAAa,IAAI,CAAC,EAAE,KAAK,SAAS,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;AACxE,CAAC","sourcesContent":["/**\n * Where a use case lives and where one of its hops sits — the two spellings\n * every surface that mentions a use case has to agree on.\n *\n * They began in `commands/validate/fleet/usecases/place.ts`, beside the four\n * `usecase.*` graders that were their only reader. `loam diff` naming the flow a\n * removal breaks is the second reader and `loam delta`/`loam context` are the\n * third and fourth, and `core/` may not import from `commands/` (AGENTS.md), so\n * the alternative was a second spelling of `architecture/<sourcePath>` in core.\n * The two would drift silently and in the worst possible direction: a file path\n * in a message that no longer names the file the view is in is how the next\n * reader stops looking (docs/CODE-STYLE.md).\n *\n * What did NOT move is `viewPlace`, the `landscape: …` opening the validate\n * findings carry. That prefix is the name of a validate TARGET, so it is command\n * vocabulary — a `loam diff` finding is filed against a service, not against the\n * fleet map, and borrowing validate's prefix there would claim a target that run\n * does not have.\n */\nimport type { ParsedStep, ParsedView } from \"../c4/parsed/dynamic-views.js\";\n\n/**\n * The document the view was written in, spelled repo-relative.\n *\n * `sourcePath` is relative to the LikeC4 PROJECT root, which for\n * `loadArchitecture` is `architecture/`, so the prefix is added here and nowhere\n * else. The caller owes one thing in exchange: only views that came from\n * `loadProject` may be spelled with this, because the single-file loaders name\n * every document after themselves (`source.c4`) and this function would then\n * spell a path that has never existed.\n *\n * An ABSENT `sourcePath` names the directory rather than guessing a file.\n * LikeC4 synthesizes only element views and `readDynamicViews` drops those, so\n * nothing at the 1.59.2 pin reaches this arm; if a release ever stopped emitting\n * the field, falling back to `architecture/landscape.likec4` would put a false\n * cross-reference in a message.\n */\nexport function viewFile(view: ParsedView): string {\n  return view.sourcePath === undefined ? \"architecture/\" : `architecture/${view.sourcePath}`;\n}\n\n/**\n * `step 4 'confirms the order'`, or `step 4` where the author labelled nothing.\n *\n * The ordinal is the view's own leaf numbering (`ParsedStep.ordinal`), which\n * skips group brackets — so it counts what the author sees on the diagram, and\n * a message naming step 4 is naming the fourth arrow.\n */\nexport function stepPlace(step: ParsedStep): string {\n  return step.title === undefined ? `step ${step.ordinal}` : `step ${step.ordinal} '${step.title}'`;\n}\n\n/**\n * A use case and one of its hops, named the way a reader outside `validate`\n * meets them: `use case 'uc_checkout' step 4 'authorizes the payment'\n * (architecture/usecases/checkout.likec4)`.\n *\n * The file goes LAST here and first in validate's `viewPlace`, and that is not\n * an inconsistency to tidy away. A validate finding is a line in a report about\n * documents, so it leads with the document; a diff victim is one entry in a\n * `details[]` list whose other entries name edges and requirements, so it has to\n * lead with the thing that broke and carry the file as the place to go fix it.\n */\nexport function hopPlace(view: ParsedView, step: ParsedStep): string {\n  return `use case '${view.id}' ${stepPlace(step)} (${viewFile(view)})`;\n}\n"]}
+{"version":3,"file":"place.js","sourceRoot":"","sources":["../../../src/core/usecases/place.ts"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAgB;IACvC,OAAO,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,gBAAgB,IAAI,CAAC,UAAU,EAAE,CAAC;AAC7F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,IAAgB;IACxC,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,KAAK,GAAG,CAAC;AACpG,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAgB,EAAE,IAAgB;IACzD,OAAO,aAAa,IAAI,CAAC,EAAE,KAAK,SAAS,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;AACxE,CAAC","sourcesContent":["/**\n * Where a use case lives and where one of its hops sits — the two spellings\n * every surface that mentions a use case has to agree on.\n *\n * They began in `commands/validate/fleet/usecases/place.ts`, beside the four\n * `usecase.*` graders that were their only reader. `loam diff` naming the flow a\n * removal breaks is the second reader and `loam delta`/`loam context` are the\n * third and fourth, and `core/` may not import from `commands/` (AGENTS.md), so\n * the alternative was a second spelling of `architecture/<sourcePath>` in core.\n * The two would drift silently and in the worst possible direction: a file path\n * in a message that no longer names the file the view is in is how the next\n * reader stops looking (docs/CODE-STYLE.md).\n *\n * What did NOT move is `viewPlace`, the `landscape: …` opening the validate\n * findings carry. That prefix is the name of a validate TARGET, so it is command\n * vocabulary — a `loam diff` finding is filed against a service, not against the\n * fleet map, and borrowing validate's prefix there would claim a target that run\n * does not have.\n */\nimport type { ParsedStep, ParsedView } from \"../c4/parsed/dynamic-views.js\";\n\n/**\n * Where a use-case FINDING says its view is — the opening of every message the\n * graders in `./grade/` write. A function each scope supplies rather than one\n * spelling, because the three scopes file a view three ways: the fleet target\n * as `landscape: architecture/<file> — dynamic view '<id>'` (`viewPlace`, which\n * stayed command vocabulary for the reason above), the service target against\n * its own directory, and the feature gate against the feature's `usecases/`\n * file the view is still written in.\n */\nexport type ViewPlace = (view: ParsedView) => string;\n\n/**\n * The document the view was written in, spelled repo-relative.\n *\n * `sourcePath` is relative to the LikeC4 PROJECT root, which for\n * `loadArchitecture` is `architecture/`, so the prefix is added here and nowhere\n * else. The caller owes one thing in exchange: only views that came from\n * `loadProject` may be spelled with this, because the single-file loaders name\n * every document after themselves (`source.c4`) and this function would then\n * spell a path that has never existed.\n *\n * An ABSENT `sourcePath` names the directory rather than guessing a file.\n * LikeC4 synthesizes only element views and `readDynamicViews` drops those, so\n * nothing at the 1.59.2 pin reaches this arm; if a release ever stopped emitting\n * the field, falling back to `architecture/landscape.likec4` would put a false\n * cross-reference in a message.\n */\nexport function viewFile(view: ParsedView): string {\n  return view.sourcePath === undefined ? \"architecture/\" : `architecture/${view.sourcePath}`;\n}\n\n/**\n * `step 4 'confirms the order'`, or `step 4` where the author labelled nothing.\n *\n * The ordinal is the view's own leaf numbering (`ParsedStep.ordinal`), which\n * skips group brackets — so it counts what the author sees on the diagram, and\n * a message naming step 4 is naming the fourth arrow.\n */\nexport function stepPlace(step: ParsedStep): string {\n  return step.title === undefined ? `step ${step.ordinal}` : `step ${step.ordinal} '${step.title}'`;\n}\n\n/**\n * A use case and one of its hops, named the way a reader outside `validate`\n * meets them: `use case 'uc_checkout' step 4 'authorizes the payment'\n * (architecture/usecases/checkout.likec4)`.\n *\n * The file goes LAST here and first in validate's `viewPlace`, and that is not\n * an inconsistency to tidy away. A validate finding is a line in a report about\n * documents, so it leads with the document; a diff victim is one entry in a\n * `details[]` list whose other entries name edges and requirements, so it has to\n * lead with the thing that broke and carry the file as the place to go fix it.\n */\nexport function hopPlace(view: ParsedView, step: ParsedStep): string {\n  return `use case '${view.id}' ${stepPlace(step)} (${viewFile(view)})`;\n}\n"]}