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

package/dist/commands/validate/fleet/usecases/steps.js

@@ -5,9 +5,18 @@
  * 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
@@ -28,9 +37,16 @@ import { attributeStep } from "../../../../core/c4/resolve/steps.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)}`;
+/**
+ * `…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 ?? viewPlace` on their own would be three
+ * places for one scope to forget the injection.
+ */
+function placeOf(hop, grading) {
+    return `${(grading.place ?? viewPlace)(hop.view)} ${stepPlace(hop.step)}`;
 }
 /**
  * A hop nothing in the model backs.
@@ -44,7 +60,7 @@ function placeOf(hop) {
  * 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) {
+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,7 +68,7 @@ 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 ` +
@@ -79,12 +95,12 @@ 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) {
     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, " +
@@ -94,12 +110,13 @@ function contestedFinding(hop, attribution) {
 }
 /**
  * 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
@@ -123,6 +140,18 @@ function contestedFinding(hop, attribution) {
  *    `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
@@ -138,6 +167,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 +192,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 +214,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/commands/validate/fleet/usecases/steps.js.map

@@ -1 +1 @@
-{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/usecases/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 three guards that keep\n * the warn honest, and the sentences.\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, type StepAttribution, type StepScope } from \"../../../../core/c4/resolve/steps.js\";\nimport type { Elem, Rel } from \"../../../../core/c4/likec4.js\";\nimport type { ParsedStep, ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport { ACTOR_KINDS } from \"../../../../core/vocabulary/maturity.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { stepPlace } from \"../../../../core/usecases/place.js\";\nimport { 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  /** The `services/<id>/` directories that exist. */\n  services: ReadonlySet<string>;\n  /** The shared element→service resolver every other edge join uses. */\n  resolve: (id: string) => string;\n}\n\ntype Unbacked = Extract<StepAttribution, { verdict: \"unbacked\" }>;\ntype Contested = Extract<StepAttribution, { verdict: \"contested\" }>;\ntype Attributed = Extract<StepAttribution, { verdict: \"attributed\" }>;\n\n/** `…checkout.likec4 — dynamic view 'uc_checkout' step 2 'authorizes the payment'`. */\nfunction placeOf(hop: GradedStep): string {\n  return `${viewPlace(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): 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      `${placeOf(hop)}: 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/** `web -> orders.api \"Calls createOrder\" (op: createOrder)`, or `(no op)` where the edge declares none. */\nfunction candidateLine(rel: Rel): string {\n  const op = rel.op === undefined ? \"no op\" : `op: ${rel.op}`;\n  return `${rel.source} -> ${rel.target} \"${rel.title ?? \"\"}\" (${op})`;\n}\n\n/**\n * A hop whose candidates disagree about the operation.\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.\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): Finding {\n  return {\n    severity: \"warn\",\n    code: \"usecase.step-contested\",\n    subject: hop.view.id,\n    message:\n      `${placeOf(hop)}: ${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. Give the candidates one operation, \" +\n      \"or draw the hop between the elements that name exactly one.\",\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 three guards refuses. ALL THREE 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 three bullets and three `return null`s below and conclude that none of\n * them is surplus: the one a miscount invites deleting is the last, and deleting\n * it puts the warning back on the first hop of almost every flow.\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 `fleet/census.ts`,\n *    `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 *\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.\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  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): 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      `${placeOf(hop)}: ${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  switch (attribution.verdict) {\n    case \"unbacked\":\n      return [unbackedFinding(hop, attribution)];\n    case \"contested\":\n      return [contestedFinding(hop, attribution)];\n    case \"attributed\": {\n      const provider = unlinkedProvider(attribution, grading);\n      return provider === null ? [] : [unlinkedFinding(hop, attribution, provider)];\n    }\n  }\n}\n"]}
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/usecases/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, type StepAttribution, type StepScope } from \"../../../../core/c4/resolve/steps.js\";\nimport type { Elem, Rel } from \"../../../../core/c4/likec4.js\";\nimport type { ParsedStep, ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport { ACTOR_KINDS } from \"../../../../core/vocabulary/maturity.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { stepPlace } from \"../../../../core/usecases/place.js\";\nimport { 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. Defaults to `viewPlace`, the fleet target's\n   * `landscape: architecture/<file> — dynamic view '<id>'`. 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?: (view: ParsedView) => string;\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 ?? viewPlace` 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 ?? viewPlace)(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/** `web -> orders.api \"Calls createOrder\" (op: createOrder)`, or `(no op)` where the edge declares none. */\nfunction candidateLine(rel: Rel): string {\n  const op = rel.op === undefined ? \"no op\" : `op: ${rel.op}`;\n  return `${rel.source} -> ${rel.target} \"${rel.title ?? \"\"}\" (${op})`;\n}\n\n/**\n * A hop whose candidates disagree about the operation.\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.\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  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. Give the candidates one operation, \" +\n      \"or draw the hop between the elements that name exactly one.\",\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 `fleet/census.ts`,\n *    `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.\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/views/fleet-project.js

@@ -0,0 +1,217 @@
+/**
+ * `c4.fleet-project-invalid` — the one thing no per-document grade can see:
+ * every document loam reads is clean, and the project the RENDERER builds out of
+ * them is not.
+ *
+ * loam grades a fleet document by document, and that is deliberate: a service's
+ * model is graded on its own merits, and one broken model must not blank the
+ * fleet. The renderer has no such rule. Point `npx likec4 start` at the docs
+ * root and it merges every `.likec4` the root project reads into ONE model — the
+ * map, every extending model, and every `.likec4` sitting beside one — so a
+ * declaration made in two of those documents is a duplicate there and nowhere
+ * else. Measured at the 1.59.2 pin: a tags-only `specification { tag req-X }` in
+ * an extending model is legal, and the SAME tag declared in a second extending
+ * model is a duplicate blamed on both files. Two services, two clean grades, and
+ * a renderer that draws nothing.
+ *
+ * So this is one extra load, and it is the renderer's reading rather than
+ * loam's. What it reports is the SET DIFFERENCE: an error already reported where
+ * loam grades that document — the map's own parse, a per-service project's
+ * `c4.invalid`, a service flow project's use-case failure — is not repeated
+ * here, because the fix is one file either way and N copies of one cascade is
+ * the report. What is left over is exactly the class above: errors that exist
+ * only because these documents were merged.
+ *
+ * WHICH DOCUMENTS ARE IN IT is `./root-documents.ts`'s question, and it is a
+ * walk of the docs root rather than a list of the shapes loam knows about: a
+ * `.likec4` in a SUBSYSTEM directory — the parent of service directories — was
+ * in none of the three roots this used to merge, and went unreported while the
+ * renderer refused the whole project over it (verification 2026-09-04, R2). That
+ * module also carries why the generated `architecture/subsystems.likec4`,
+ * every standalone service directory and `features/` stay out.
+ *
+ * `--all` ONLY, and only when at least one model extends the map, the map itself
+ * parses, and the root `exclude` does not hide it. A single-target run has not
+ * enumerated the fleet, so it cannot build the project at all; a fleet whose
+ * models all stand alone has no such project (every one of them is excluded from
+ * the root); and a map that does not parse would report its own cascade here
+ * under a second code while `landscape.invalid` already names the file.
+ *
+ * THE LAST OF THOSE GATES IS THE CASCADE RULE, the one `permissions.invalid` and
+ * `capability.invalid` already state: a grade that resolves against a
+ * document nobody loaded is not a diagnosis. `architectureProjectDocuments`
+ * keeps the map whatever the root `exclude` says — that floor is what stopped
+ * loam asserting a fleet's map declares nothing — but this load has no such
+ * floor ON PURPOSE, because its whole claim is to read what the renderer reads.
+ * So an entry covering `architecture/landscape.likec4` leaves every extending
+ * model in the project with its `extend <fqn>` resolving against nothing:
+ * measured on `examples/docs` with `architecture/*.likec4` in the list, one
+ * authored line came back as 161 warnings under this code. `landscape.excluded`
+ * (`./projects.ts`) is the one finding that names the cause, and it says the
+ * fleet project is not graded until the entry goes. The fact arrives as
+ * `mapExcluded` rather than being re-read here, so the two can never disagree
+ * about which state they are in.
+ *
+ * WHY A WARNING. Nothing loam concludes changes: every model still parses where
+ * loam reads it, every binding still resolves, the spine is unaffected. What is
+ * broken is the picture, which is what `service.likec4-config-missing` and its
+ * three siblings in `./projects.ts` also grade, at the same severity.
+ */
+import { existsSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { errorText } from "../../../../core/c4/likec4.js";
+import { asLoadedDoc, loadProject } from "../../../../core/c4/project/load.js";
+import { FleetContext } from "../../../../core/fleet-context.js";
+import { inOrder } from "../../../../core/kernel/concurrency.js";
+import { servicePathsAt } from "../../../../core/repo/paths.js";
+import { readServiceFlows } from "../../../../core/usecases/service/flows.js";
+import { rootProjectDocuments } from "./root-documents.js";
+export async function fleetProjectFindings(check) {
+    // A map that did not parse is `landscape.invalid`'s, and this load would only
+    // repeat its cascade under a second code.
+    if (check.architecture.errors.length > 0)
+        return { kind: "skipped" };
+    // A map the root `exclude` hides is `landscape.excluded`'s, for the same
+    // reason one line up — see the banner's cascade-rule paragraph. The view-id
+    // census goes with it: `clean` is a claim about a project that parsed, and
+    // there is none.
+    if (check.mapExcluded)
+        return { kind: "skipped" };
+    const shapeOf = (entry) => {
+        const model = servicePathsAt(entry.dir).model;
+        return existsSync(model) ? (check.shapes.get(resolve(model)) ?? null) : null;
+    };
+    const extending = check.entries.filter((entry) => shapeOf(entry) === "extending");
+    if (extending.length === 0)
+        return { kind: "skipped" };
+    const paths = extending.map((entry) => servicePathsAt(entry.dir));
+    // The TREE, not three roots. `./root-documents.ts` carries what comes out of
+    // it and why; the standalone directories are handed in because their shape is
+    // this run's memo and re-reading every model here would be a second scanner.
+    const documents = await rootProjectDocuments(check.docsDir, check.entries.filter((entry) => shapeOf(entry) === "standalone").map((entry) => entry.dir));
+    const project = await loadProject(check.docsDir, documents);
+    if (project.clean) {
+        // The census `subsystem.view-id-collision` needs and could not have until
+        // now: an extending model's authored view ids live in the SAME flat
+        // namespace as the map's, because both documents are in this project. The
+        // claims arrive docs-relative, which is the spelling `viewIdFindings` takes.
+        return { kind: "clean", viewIds: project.viewIds };
+    }
+    const reported = await alreadyReported(check, paths);
+    const findings = [];
+    for (const err of asLoadedDoc(project).errors) {
+        if (reported.has(errorKey(err)))
+            continue;
+        const owner = extending.find((entry) => err.sourceFsPath !== undefined && err.sourceFsPath.startsWith(`${entry.dir}${sep}`));
+        const file = err.sourceFsPath === undefined ? null : relative(check.docsDir, err.sourceFsPath).split(/[\\/]/).join("/");
+        findings.push({
+            severity: "warn",
+            code: "c4.fleet-project-invalid",
+            ...(owner === undefined ? {} : { subject: owner.id }),
+            // The file the error is IN, never the map by default: `locations[0].path`
+            // was `architecture/landscape.likec4` on every one of these, so a reader
+            // acting on the payload opened a document that was not the one at fault
+            // (verification 2026-09-04, D10). Absent when LikeC4 declined to attribute
+            // the error to a document at all — a location loam cannot spell is left
+            // unspelled rather than guessed.
+            ...(file === null ? {} : { locations: [{ path: file, role: "primary" }] }),
+            details: [file === null ? errorText(err) : `${file}: ${errorText(err)}`],
+            message: `fleet project: ${file ?? "the merged project"}: ${errorText(err)} — each document reads clean where ` +
+                "loam grades it, but the renderer merges every `.likec4` the root project reads except the generated " +
+                "subsystems.likec4 — the map, every extending model and every `.likec4` beside one — into ONE project, " +
+                `and that project does not parse. ${remedy(err.message)}`,
+        });
+    }
+    return { kind: "invalid", findings };
+}
+/**
+ * The tail that names WHICH failure this is.
+ *
+ * It used to say "a tag or an element declared in two of those documents is
+ * declared twice there" for every error, including the ones that are not a
+ * double declaration at all (verification 2026-09-04, D10) — an unresolved
+ * reference sent its reader hunting for a second declaration that does not
+ * exist. LikeC4's own wording is the evidence, matched loosely on purpose: an
+ * unrecognised message falls to the third arm, which asserts nothing beyond
+ * where to look.
+ */
+function remedy(message) {
+    if (/duplicat|already (declared|defined)|declared (more than once|twice)/i.test(message)) {
+        return ("A tag or an element declared in two of those documents is declared twice there; declare it once " +
+            "(the map, or the one service that owns it)");
+    }
+    if (/could not resolve|unresolved|unknown/i.test(message)) {
+        return ("A name resolves against ALL of those documents here, so a reference the renderer cannot place is one " +
+            "no document in the project declares; declare it where the reader can see it, or drop the reference");
+    }
+    return "Open the file and line named above — every reader who points a renderer at the docs root sees this";
+}
+/**
+ * Every parse error this run has ALREADY reported against one of these
+ * documents, keyed so the merged project's copy can be recognised.
+ *
+ * Two sources, and both are loads the run made anyway or would make: each
+ * extending model's own per-service project (`c4.invalid` on the service
+ * target) and, where nothing was wrong there, each service's FLOW project
+ * (`readServiceFlows` — the use-case grade names the file). The flow read goes
+ * through that function rather than a second `loadProject` here so the OPT-IN
+ * gate is the same one: a broken sibling that nothing tagged is loaded by
+ * neither, which is exactly why the merged project has to report it.
+ *
+ * Computed only when the merged project actually failed, which is why it is a
+ * function rather than an input: on a healthy fleet this whole file costs one
+ * load and nothing else.
+ *
+ * THE FLOW PROJECTS ARE PARSED AGAIN by `validateService` later in the same run,
+ * and that is accepted rather than unnoticed: it happens only on the path where
+ * the merged project already failed, so a healthy fleet pays nothing, and the
+ * `ServiceModel` half above IS the run's memo. If that path ever becomes hot,
+ * the follow-up is to memoise the flow scan on `FleetContext` beside the
+ * per-service projects — not to hand the scan in here, which would make this
+ * grade depend on an argument the caller has no reason to have loaded.
+ */
+async function alreadyReported(check, paths) {
+    // Both sets reach the same documents through `architectureProjectDocuments`,
+    // which now drops what the root `exclude` covers exactly as the merged load's
+    // own walk does — so a document out of one is out of both, and the generated
+    // `subsystems.likec4` is out of all of them without being remembered twice.
+    //
+    // Pooled rather than awaited one at a time: each entry is an independent
+    // LikeC4 workspace over one service's own documents, which is exactly the
+    // work `inOrder` rations — and a serial loop here made the ONE path that
+    // already costs a fleet its whole set of flow projects pay for them in
+    // sequence.
+    const perService = await inOrder(paths, async (service) => {
+        const model = await check.fleet.serviceModel(check.docsDir, service);
+        const errors = [...model.doc.errors];
+        if (errors.length > 0 || model.mapUnreadable)
+            return errors;
+        // `model.project` is non-null here by construction — these are extending
+        // models whose own load came back clean, which is the arm that carries it —
+        // and the guard is the compiler's rather than an assertion: a null would
+        // mean grading a flow against a document that did not load.
+        if (model.project === null)
+            return [];
+        const flows = await readServiceFlows({
+            paths: service,
+            model: model.doc,
+            known: check.known,
+            extending: { docsDir: check.docsDir, project: model.project },
+        });
+        return flows.kind === "unreadable" ? flows.errors : [];
+    });
+    return new Set(perService.flat().map(errorKey));
+}
+/**
+ * One error's identity across two loads of overlapping document sets: the real
+ * file, the line, and the message.
+ *
+ * There is no id to join on — LikeC4 mints diagnostics per parse — and the
+ * message has to be part of the key: two DIFFERENT problems on one line of one
+ * file are two errors, and collapsing them would let a merged-project-only
+ * failure hide behind a per-service one that happens to share a line.
+ */
+function errorKey(err) {
+    return JSON.stringify([err.sourceFsPath ?? "", err.line ?? -1, err.message]);
+}
+//# sourceMappingURL=fleet-project.js.map

package/dist/commands/validate/fleet/views/fleet-project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-project.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/views/fleet-project.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `c4.fleet-project-invalid` — the one thing no per-document grade can see:\n * every document loam reads is clean, and the project the RENDERER builds out of\n * them is not.\n *\n * loam grades a fleet document by document, and that is deliberate: a service's\n * model is graded on its own merits, and one broken model must not blank the\n * fleet. The renderer has no such rule. Point `npx likec4 start` at the docs\n * root and it merges every `.likec4` the root project reads into ONE model — the\n * map, every extending model, and every `.likec4` sitting beside one — so a\n * declaration made in two of those documents is a duplicate there and nowhere\n * else. Measured at the 1.59.2 pin: a tags-only `specification { tag req-X }` in\n * an extending model is legal, and the SAME tag declared in a second extending\n * model is a duplicate blamed on both files. Two services, two clean grades, and\n * a renderer that draws nothing.\n *\n * So this is one extra load, and it is the renderer's reading rather than\n * loam's. What it reports is the SET DIFFERENCE: an error already reported where\n * loam grades that document — the map's own parse, a per-service project's\n * `c4.invalid`, a service flow project's use-case failure — is not repeated\n * here, because the fix is one file either way and N copies of one cascade is\n * the report. What is left over is exactly the class above: errors that exist\n * only because these documents were merged.\n *\n * WHICH DOCUMENTS ARE IN IT is `./root-documents.ts`'s question, and it is a\n * walk of the docs root rather than a list of the shapes loam knows about: a\n * `.likec4` in a SUBSYSTEM directory — the parent of service directories — was\n * in none of the three roots this used to merge, and went unreported while the\n * renderer refused the whole project over it (verification 2026-09-04, R2). That\n * module also carries why the generated `architecture/subsystems.likec4`,\n * every standalone service directory and `features/` stay out.\n *\n * `--all` ONLY, and only when at least one model extends the map, the map itself\n * parses, and the root `exclude` does not hide it. A single-target run has not\n * enumerated the fleet, so it cannot build the project at all; a fleet whose\n * models all stand alone has no such project (every one of them is excluded from\n * the root); and a map that does not parse would report its own cascade here\n * under a second code while `landscape.invalid` already names the file.\n *\n * THE LAST OF THOSE GATES IS THE CASCADE RULE, the one `permissions.invalid` and\n * `capability.invalid` already state: a grade that resolves against a\n * document nobody loaded is not a diagnosis. `architectureProjectDocuments`\n * keeps the map whatever the root `exclude` says — that floor is what stopped\n * loam asserting a fleet's map declares nothing — but this load has no such\n * floor ON PURPOSE, because its whole claim is to read what the renderer reads.\n * So an entry covering `architecture/landscape.likec4` leaves every extending\n * model in the project with its `extend <fqn>` resolving against nothing:\n * measured on `examples/docs` with `architecture/*.likec4` in the list, one\n * authored line came back as 161 warnings under this code. `landscape.excluded`\n * (`./projects.ts`) is the one finding that names the cause, and it says the\n * fleet project is not graded until the entry goes. The fact arrives as\n * `mapExcluded` rather than being re-read here, so the two can never disagree\n * about which state they are in.\n *\n * WHY A WARNING. Nothing loam concludes changes: every model still parses where\n * loam reads it, every binding still resolves, the spine is unaffected. What is\n * broken is the picture, which is what `service.likec4-config-missing` and its\n * three siblings in `./projects.ts` also grade, at the same severity.\n */\nimport { existsSync } from \"node:fs\";\nimport { relative, resolve, sep } from \"node:path\";\nimport { errorText, type LikeC4Error, type LoadedDoc } from \"../../../../core/c4/likec4.js\";\nimport { asLoadedDoc, loadProject } from \"../../../../core/c4/project/load.js\";\nimport type { ViewIdClaim } from \"../../../../core/c4/parsed/view-ids.js\";\nimport type { ModelShape } from \"../../../../core/c4/service-model/shape.js\";\nimport { FleetContext } from \"../../../../core/fleet-context.js\";\nimport { inOrder } from \"../../../../core/kernel/concurrency.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport type { ServiceEntry } from \"../../../../core/repo/entries.js\";\nimport { servicePathsAt, type ServicePaths } from \"../../../../core/repo/paths.js\";\nimport type { FleetTree } from \"../../../../core/repo/tree/walk.js\";\nimport { readServiceFlows } from \"../../../../core/usecases/service/flows.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { rootProjectDocuments } from \"./root-documents.js\";\n\nexport interface FleetProjectCheck {\n  docsDir: DocsDir;\n  /** The FULL enumeration — the project the renderer builds holds every model, not a narrowed run's subset. */\n  entries: readonly ServiceEntry[];\n  /** Each model's shape, keyed by resolved path (`FleetContext.modelShapes`). */\n  shapes: ReadonlyMap<string, ModelShape>;\n  /** The run's read index: the per-service projects it already parsed are half of the set difference. */\n  fleet: FleetContext;\n  /** The map parsed ALONE — the gate, and the other half of the difference. */\n  architecture: LoadedDoc;\n  /**\n   * Whether the root `exclude` hides the map itself — `landscape.excluded`'s own\n   * condition, computed once in `./projects.ts` and carried here rather than\n   * re-derived. It is a GATE, for the reason the banner's cascade-rule paragraph\n   * gives: this load has no floor under the map, so the entry that hides it\n   * turns one authored line into an unresolved reference in every extending\n   * model.\n   */\n  mapExcluded: boolean;\n  /** The walked tree, for the view-id census this load makes answerable. */\n  tree: FleetTree;\n  /** Every service directory that exists — the flow scan's resolver evidence. */\n  known: ReadonlySet<string>;\n}\n\n/**\n * What the merged load found, as three answers rather than one list — because\n * the caller has a second question to ask of it and the answers are mutually\n * exclusive.\n *\n * `skipped` is \"there is no such project, or loam declines to read one\": no model\n * extends the map, the map does not parse, the root `exclude` hides the map\n * (`landscape.excluded` names that entry and this grade stands down behind it),\n * or the run has no fleet index. `clean` carries the view-id\n * CENSUS, which is the only thing a caller may take from a project that parsed —\n * and the reason this is not just an empty finding list: an empty list and a\n * clean census are the same thing to `.length`, and one of them licenses\n * `subsystem.view-id-collision` to be graded over every extending model's\n * authored ids while the other does not.\n */\nexport type FleetProjectGrade =\n  | { kind: \"skipped\" }\n  | { kind: \"invalid\"; findings: Finding[] }\n  | { kind: \"clean\"; viewIds: ViewIdClaim[] };\n\nexport async function fleetProjectFindings(check: FleetProjectCheck): Promise<FleetProjectGrade> {\n  // A map that did not parse is `landscape.invalid`'s, and this load would only\n  // repeat its cascade under a second code.\n  if (check.architecture.errors.length > 0) return { kind: \"skipped\" };\n  // A map the root `exclude` hides is `landscape.excluded`'s, for the same\n  // reason one line up — see the banner's cascade-rule paragraph. The view-id\n  // census goes with it: `clean` is a claim about a project that parsed, and\n  // there is none.\n  if (check.mapExcluded) return { kind: \"skipped\" };\n  const shapeOf = (entry: ServiceEntry): ModelShape | null => {\n    const model = servicePathsAt(entry.dir).model;\n    return existsSync(model) ? (check.shapes.get(resolve(model)) ?? null) : null;\n  };\n  const extending = check.entries.filter((entry) => shapeOf(entry) === \"extending\");\n  if (extending.length === 0) return { kind: \"skipped\" };\n\n  const paths = extending.map((entry) => servicePathsAt(entry.dir));\n  // The TREE, not three roots. `./root-documents.ts` carries what comes out of\n  // it and why; the standalone directories are handed in because their shape is\n  // this run's memo and re-reading every model here would be a second scanner.\n  const documents = await rootProjectDocuments(\n    check.docsDir,\n    check.entries.filter((entry) => shapeOf(entry) === \"standalone\").map((entry) => entry.dir),\n  );\n  const project = await loadProject(check.docsDir, documents);\n\n  if (project.clean) {\n    // The census `subsystem.view-id-collision` needs and could not have until\n    // now: an extending model's authored view ids live in the SAME flat\n    // namespace as the map's, because both documents are in this project. The\n    // claims arrive docs-relative, which is the spelling `viewIdFindings` takes.\n    return { kind: \"clean\", viewIds: project.viewIds };\n  }\n\n  const reported = await alreadyReported(check, paths);\n  const findings: Finding[] = [];\n  for (const err of asLoadedDoc(project).errors) {\n    if (reported.has(errorKey(err))) continue;\n    const owner = extending.find(\n      (entry) => err.sourceFsPath !== undefined && err.sourceFsPath.startsWith(`${entry.dir}${sep}`),\n    );\n    const file =\n      err.sourceFsPath === undefined ? null : relative(check.docsDir, err.sourceFsPath).split(/[\\\\/]/).join(\"/\");\n    findings.push({\n      severity: \"warn\",\n      code: \"c4.fleet-project-invalid\",\n      ...(owner === undefined ? {} : { subject: owner.id }),\n      // The file the error is IN, never the map by default: `locations[0].path`\n      // was `architecture/landscape.likec4` on every one of these, so a reader\n      // acting on the payload opened a document that was not the one at fault\n      // (verification 2026-09-04, D10). Absent when LikeC4 declined to attribute\n      // the error to a document at all — a location loam cannot spell is left\n      // unspelled rather than guessed.\n      ...(file === null ? {} : { locations: [{ path: file, role: \"primary\" as const }] }),\n      details: [file === null ? errorText(err) : `${file}: ${errorText(err)}`],\n      message:\n        `fleet project: ${file ?? \"the merged project\"}: ${errorText(err)} — each document reads clean where ` +\n        \"loam grades it, but the renderer merges every `.likec4` the root project reads except the generated \" +\n        \"subsystems.likec4 — the map, every extending model and every `.likec4` beside one — into ONE project, \" +\n        `and that project does not parse. ${remedy(err.message)}`,\n    });\n  }\n  return { kind: \"invalid\", findings };\n}\n\n/**\n * The tail that names WHICH failure this is.\n *\n * It used to say \"a tag or an element declared in two of those documents is\n * declared twice there\" for every error, including the ones that are not a\n * double declaration at all (verification 2026-09-04, D10) — an unresolved\n * reference sent its reader hunting for a second declaration that does not\n * exist. LikeC4's own wording is the evidence, matched loosely on purpose: an\n * unrecognised message falls to the third arm, which asserts nothing beyond\n * where to look.\n */\nfunction remedy(message: string): string {\n  if (/duplicat|already (declared|defined)|declared (more than once|twice)/i.test(message)) {\n    return (\n      \"A tag or an element declared in two of those documents is declared twice there; declare it once \" +\n      \"(the map, or the one service that owns it)\"\n    );\n  }\n  if (/could not resolve|unresolved|unknown/i.test(message)) {\n    return (\n      \"A name resolves against ALL of those documents here, so a reference the renderer cannot place is one \" +\n      \"no document in the project declares; declare it where the reader can see it, or drop the reference\"\n    );\n  }\n  return \"Open the file and line named above — every reader who points a renderer at the docs root sees this\";\n}\n\n/**\n * Every parse error this run has ALREADY reported against one of these\n * documents, keyed so the merged project's copy can be recognised.\n *\n * Two sources, and both are loads the run made anyway or would make: each\n * extending model's own per-service project (`c4.invalid` on the service\n * target) and, where nothing was wrong there, each service's FLOW project\n * (`readServiceFlows` — the use-case grade names the file). The flow read goes\n * through that function rather than a second `loadProject` here so the OPT-IN\n * gate is the same one: a broken sibling that nothing tagged is loaded by\n * neither, which is exactly why the merged project has to report it.\n *\n * Computed only when the merged project actually failed, which is why it is a\n * function rather than an input: on a healthy fleet this whole file costs one\n * load and nothing else.\n *\n * THE FLOW PROJECTS ARE PARSED AGAIN by `validateService` later in the same run,\n * and that is accepted rather than unnoticed: it happens only on the path where\n * the merged project already failed, so a healthy fleet pays nothing, and the\n * `ServiceModel` half above IS the run's memo. If that path ever becomes hot,\n * the follow-up is to memoise the flow scan on `FleetContext` beside the\n * per-service projects — not to hand the scan in here, which would make this\n * grade depend on an argument the caller has no reason to have loaded.\n */\nasync function alreadyReported(\n  check: FleetProjectCheck,\n  paths: readonly ServicePaths[],\n): Promise<ReadonlySet<string>> {\n  // Both sets reach the same documents through `architectureProjectDocuments`,\n  // which now drops what the root `exclude` covers exactly as the merged load's\n  // own walk does — so a document out of one is out of both, and the generated\n  // `subsystems.likec4` is out of all of them without being remembered twice.\n  //\n  // Pooled rather than awaited one at a time: each entry is an independent\n  // LikeC4 workspace over one service's own documents, which is exactly the\n  // work `inOrder` rations — and a serial loop here made the ONE path that\n  // already costs a fleet its whole set of flow projects pay for them in\n  // sequence.\n  const perService = await inOrder(paths, async (service) => {\n    const model = await check.fleet.serviceModel(check.docsDir, service);\n    const errors = [...model.doc.errors];\n    if (errors.length > 0 || model.mapUnreadable) return errors;\n    // `model.project` is non-null here by construction — these are extending\n    // models whose own load came back clean, which is the arm that carries it —\n    // and the guard is the compiler's rather than an assertion: a null would\n    // mean grading a flow against a document that did not load.\n    if (model.project === null) return [];\n    const flows = await readServiceFlows({\n      paths: service,\n      model: model.doc,\n      known: check.known,\n      extending: { docsDir: check.docsDir, project: model.project },\n    });\n    return flows.kind === \"unreadable\" ? flows.errors : [];\n  });\n  return new Set(perService.flat().map(errorKey));\n}\n\n/**\n * One error's identity across two loads of overlapping document sets: the real\n * file, the line, and the message.\n *\n * There is no id to join on — LikeC4 mints diagnostics per parse — and the\n * message has to be part of the key: two DIFFERENT problems on one line of one\n * file are two errors, and collapsing them would let a merged-project-only\n * failure hide behind a per-service one that happens to share a line.\n */\nfunction errorKey(err: LikeC4Error): string {\n  return JSON.stringify([err.sourceFsPath ?? \"\", err.line ?? -1, err.message]);\n}\n"]}

package/dist/commands/validate/fleet/views/ids.js

@@ -1,10 +1,10 @@
 import { SUBSYSTEM_VIEW_PREFIX, subsystemViewId } from "../../../../core/repo/tree/render/views.js";
 /**
- * `authored` is every view id the `architecture/` project claims, each with the
- * file that claims it — static views included, because a static view claims an
- * id exactly as firmly as a dynamic one. Absent (the document did not parse, or
- * an older loader did not read them) is treated as "nothing to compare", never
- * as "nothing collides".
+ * `authored` is every view id the project claims, each with the DOCS-RELATIVE
+ * path of the file that claims it — static views included, because a static view
+ * claims an id exactly as firmly as a dynamic one. Absent (the document did not
+ * parse, or an older loader did not read them) is treated as "nothing to
+ * compare", never as "nothing collides".
  */
 export function viewIdFindings(authored, tree) {
     if (authored === undefined || authored.length === 0)
@@ -32,11 +32,15 @@ export function viewIdFindings(authored, tree) {
             // the one the report's target fallback gets wrong: it files this under
             // the landscape, which is exactly the file a reader must NOT rename the
             // view in when the claim came from a document of their own.
-            locations: [{ path: `architecture/${file}`, role: "primary" }],
-            message: `subsystems: architecture/${file} declares \`view ${id}\`, which is the id loam generates ` +
+            locations: [{ path: file, role: "primary" }],
+            message: `subsystems: ${file} declares \`view ${id}\`, which is the id loam generates ` +
                 `into architecture/subsystems.likec4 for services/${owner}/ — LikeC4 merges both files into one project, ` +
-                `so it refuses the whole architecture/ project and renders nothing. ` +
-                `Rename the view in architecture/${file}; ids beginning \`${SUBSYSTEM_VIEW_PREFIX}\` are loam's ` +
+                // The ROOT project, not `architecture/`: the claimant may be a model's
+                // own view now (an extending model is a document of the root project),
+                // and telling that author the `architecture/` project is refused sends
+                // them to look for the breakage in a directory they never touched.
+                `so it refuses the whole root project and renders nothing. ` +
+                `Rename the view in ${file}; ids beginning \`${SUBSYSTEM_VIEW_PREFIX}\` are loam's ` +
                 "to mint, and architecture/subsystems.likec4 is generated (`loam subsystem sync`) and must never be hand-edited.",
         });
     }

package/dist/commands/validate/fleet/views/ids.js.map

@@ -1 +1 @@
-{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/views/ids.ts"],"names":[],"mappings":"AAsCA,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAIpG;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAmC,EAAE,IAAe;IACjF,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC/D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACpG,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,8EAA8E;IAC9E,+EAA+E;IAC/E,2EAA2E;IAC3E,iDAAiD;IACjD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,KAAK,MAAM,KAAK,IAAI,QAAQ;QAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACtG,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,6BAA6B;YACnC,OAAO,EAAE,EAAE;YACX,wEAAwE;YACxE,uEAAuE;YACvE,wEAAwE;YACxE,4DAA4D;YAC5D,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,gBAAgB,IAAI,EAAE,EAAE,IAAI,EAAE,SAAkB,EAAE,CAAC;YACvE,OAAO,EACL,4BAA4B,IAAI,oBAAoB,EAAE,qCAAqC;gBAC3F,oDAAoD,KAAK,iDAAiD;gBAC1G,qEAAqE;gBACrE,mCAAmC,IAAI,qBAAqB,qBAAqB,gBAAgB;gBACjG,iHAAiH;SACpH,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * An authored view id that collides with one loam GENERATES into\n * `architecture/subsystems.likec4`.\n *\n * This closes a green-while-broken hole, and the shape of it is measured rather\n * than argued. The LikeC4 renderer merges every `.likec4` file in a project into\n * one model, and `likec4.config.json` scopes the root project to\n * `architecture/` — so `landscape.likec4` and the generated `subsystems.likec4`\n * share ONE flat view-id namespace. Author `view subsystem_commerce { }` in the\n * landscape while the tree has a `commerce` subsystem and the renderer refuses\n * the ENTIRE `architecture/` project with two `Duplicate view` diagnostics, one\n * per file — while `loam validate --all` printed `landscape: N service(s)\n * modelled — architecture/landscape.likec4 and services/ agree`. Reproduced at\n * the 1.59.2 pin.\n *\n * Nothing else in a loam repo can produce this. A duplicate INSIDE one document\n * is already 2 LikeC4 errors, so `landscape.invalid` has it (measured). A\n * service's `model.likec4` and a feature's `delta.likec4` are each their own\n * LikeC4 project — `likec4.config.json` excludes `services/**` and\n * `features/**` from the root — so their view ids cannot collide with the\n * landscape's, and a delta's views never travel through `archive` anyway. That\n * leaves exactly one pair, which is why this check compares exactly one pair\n * rather than taking a census across every document loam parses.\n *\n * ONLY the real collision is refused, never the merely reserved-looking name.\n * A landscape view called `subsystem_overview` with no `overview` subsystem\n * breaks nothing today, and refusing it would be loam inventing a rule about a\n * name that harms no one. The latent case is not lost: the moment somebody\n * creates that subsystem, the generator mints the id, and this same check fires\n * on the same run. The message names the reservation anyway, so an author fixing\n * one collision learns not to make the next.\n *\n * Graded on `validate --all` only, and the caller holds that gate together with\n * the landscape-parsed one: under a single-target run the fleet tree is not\n * walked and the generated ids are unknown, so the question is unanswerable and\n * the check stays silent rather than half-answering.\n */\nimport type { ViewIdClaim } from \"../../../../core/c4/parsed/view-ids.js\";\nimport { SUBSYSTEM_VIEW_PREFIX, subsystemViewId } from \"../../../../core/repo/tree/render/views.js\";\nimport type { FleetTree } from \"../../../../core/repo/tree/walk.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\n\n/**\n * `authored` is every view id the `architecture/` project claims, each with the\n * file that claims it — static views included, because a static view claims an\n * id exactly as firmly as a dynamic one. Absent (the document did not parse, or\n * an older loader did not read them) is treated as \"nothing to compare\", never\n * as \"nothing collides\".\n */\nexport function viewIdFindings(authored: ViewIdClaim[] | undefined, tree: FleetTree): Finding[] {\n  if (authored === undefined || authored.length === 0) return [];\n  const generated = new Map(tree.subsystems.map((sub) => [subsystemViewId(sub), sub.path.join(\"/\")]));\n  const findings: Finding[] = [];\n  // Sorted and de-duplicated by id so a project claiming the same id twice —\n  // itself already a parse error, but reachable through a partial read — yields\n  // one finding per id rather than one per occurrence. The first claimant's file\n  // is the one named: with a duplicate the project does not parse at all, so\n  // there is never a second one to choose between.\n  const claimants = new Map<string, string>();\n  for (const claim of authored) if (!claimants.has(claim.id)) claimants.set(claim.id, claim.sourcePath);\n  for (const [id, file] of [...claimants].sort(([a], [b]) => (a < b ? -1 : 1))) {\n    const owner = generated.get(id);\n    if (owner === undefined) continue;\n    findings.push({\n      severity: \"error\",\n      code: \"subsystem.view-id-collision\",\n      subject: id,\n      // The CLAIMANT file — the one the message tells the reader to edit, and\n      // the one the report's target fallback gets wrong: it files this under\n      // the landscape, which is exactly the file a reader must NOT rename the\n      // view in when the claim came from a document of their own.\n      locations: [{ path: `architecture/${file}`, role: \"primary\" as const }],\n      message:\n        `subsystems: architecture/${file} declares \\`view ${id}\\`, which is the id loam generates ` +\n        `into architecture/subsystems.likec4 for services/${owner}/ — LikeC4 merges both files into one project, ` +\n        `so it refuses the whole architecture/ project and renders nothing. ` +\n        `Rename the view in architecture/${file}; ids beginning \\`${SUBSYSTEM_VIEW_PREFIX}\\` are loam's ` +\n        \"to mint, and architecture/subsystems.likec4 is generated (`loam subsystem sync`) and must never be hand-edited.\",\n    });\n  }\n  return findings;\n}\n"]}
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/views/ids.ts"],"names":[],"mappings":"AAqDA,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAIpG;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAmC,EAAE,IAAe;IACjF,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC/D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACpG,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,8EAA8E;IAC9E,+EAA+E;IAC/E,2EAA2E;IAC3E,iDAAiD;IACjD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,KAAK,MAAM,KAAK,IAAI,QAAQ;QAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACtG,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,6BAA6B;YACnC,OAAO,EAAE,EAAE;YACX,wEAAwE;YACxE,uEAAuE;YACvE,wEAAwE;YACxE,4DAA4D;YAC5D,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAkB,EAAE,CAAC;YACrD,OAAO,EACL,eAAe,IAAI,oBAAoB,EAAE,qCAAqC;gBAC9E,oDAAoD,KAAK,iDAAiD;gBAC1G,uEAAuE;gBACvE,uEAAuE;gBACvE,uEAAuE;gBACvE,mEAAmE;gBACnE,4DAA4D;gBAC5D,sBAAsB,IAAI,qBAAqB,qBAAqB,gBAAgB;gBACpF,iHAAiH;SACpH,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * An authored view id that collides with one loam GENERATES into\n * `architecture/subsystems.likec4`.\n *\n * This closes a green-while-broken hole, and the shape of it is measured rather\n * than argued. The LikeC4 renderer merges every `.likec4` file in a project into\n * one model, and `architecture/landscape.likec4` and the generated\n * `architecture/subsystems.likec4` are two documents of the ROOT project — so\n * they share ONE flat view-id namespace. (This file used to say the reason was\n * that `likec4.config.json` scopes the root project to `architecture/`; it does\n * not, and never had to for the collision to exist. The scaffold's `exclude`\n * names `features/**` and node_modules, and a fleet whose models extend the map\n * has `services/` in the root project too — see `./fleet-project.ts`.) Author\n * `view subsystem_commerce { }` in the landscape while the tree has a `commerce`\n * subsystem and the renderer refuses the ENTIRE root project with two\n * `Duplicate view` diagnostics, one per file — while `loam validate --all`\n * printed `landscape: N service(s) modelled — architecture/landscape.likec4 and\n * services/ agree`. Reproduced at the 1.59.2 pin.\n *\n * WHICH DOCUMENTS CLAIM IDS IN THAT NAMESPACE, corrected. A duplicate INSIDE one\n * document is already 2 LikeC4 errors, so `landscape.invalid` has it (measured).\n * A feature's `delta.likec4` is its own LikeC4 project — the root excludes\n * `features/**` — and a delta's views never travel through `archive` anyway. A\n * service's `model.likec4` used to be in the same position and no longer is:\n * this file's original premise, that `likec4.config.json` excludes `services/**`\n * so a model's view ids cannot collide with the landscape's, holds only for a\n * model that STANDS ALONE. A model that EXTENDS the map lives in the root\n * project beside it, so its authored view ids — and those of every `.likec4`\n * beside it — share exactly this namespace. That census is made by the merged\n * load in `./fleet-project.ts` and handed here; the landscape's own claims are\n * still graded from the `architecture/` project, which is the only census a run\n * with no extending model can make.\n *\n * The claims therefore arrive spelled DOCS-RELATIVE, and the caller does the\n * spelling: the `architecture/` project reports a view's `sourcePath` relative\n * to `architecture/`, the merged project reports it relative to the docs root,\n * and a prefix pasted on here would name `architecture/services/…` for every\n * model. The message and the location both print the path verbatim.\n *\n * ONLY the real collision is refused, never the merely reserved-looking name.\n * A landscape view called `subsystem_overview` with no `overview` subsystem\n * breaks nothing today, and refusing it would be loam inventing a rule about a\n * name that harms no one. The latent case is not lost: the moment somebody\n * creates that subsystem, the generator mints the id, and this same check fires\n * on the same run. The message names the reservation anyway, so an author fixing\n * one collision learns not to make the next.\n *\n * Graded on `validate --all` only, and the caller holds that gate together with\n * the landscape-parsed one: under a single-target run the fleet tree is not\n * walked and the generated ids are unknown, so the question is unanswerable and\n * the check stays silent rather than half-answering.\n */\nimport type { ViewIdClaim } from \"../../../../core/c4/parsed/view-ids.js\";\nimport { SUBSYSTEM_VIEW_PREFIX, subsystemViewId } from \"../../../../core/repo/tree/render/views.js\";\nimport type { FleetTree } from \"../../../../core/repo/tree/walk.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\n\n/**\n * `authored` is every view id the project claims, each with the DOCS-RELATIVE\n * path of the file that claims it — static views included, because a static view\n * claims an id exactly as firmly as a dynamic one. Absent (the document did not\n * parse, or an older loader did not read them) is treated as \"nothing to\n * compare\", never as \"nothing collides\".\n */\nexport function viewIdFindings(authored: ViewIdClaim[] | undefined, tree: FleetTree): Finding[] {\n  if (authored === undefined || authored.length === 0) return [];\n  const generated = new Map(tree.subsystems.map((sub) => [subsystemViewId(sub), sub.path.join(\"/\")]));\n  const findings: Finding[] = [];\n  // Sorted and de-duplicated by id so a project claiming the same id twice —\n  // itself already a parse error, but reachable through a partial read — yields\n  // one finding per id rather than one per occurrence. The first claimant's file\n  // is the one named: with a duplicate the project does not parse at all, so\n  // there is never a second one to choose between.\n  const claimants = new Map<string, string>();\n  for (const claim of authored) if (!claimants.has(claim.id)) claimants.set(claim.id, claim.sourcePath);\n  for (const [id, file] of [...claimants].sort(([a], [b]) => (a < b ? -1 : 1))) {\n    const owner = generated.get(id);\n    if (owner === undefined) continue;\n    findings.push({\n      severity: \"error\",\n      code: \"subsystem.view-id-collision\",\n      subject: id,\n      // The CLAIMANT file — the one the message tells the reader to edit, and\n      // the one the report's target fallback gets wrong: it files this under\n      // the landscape, which is exactly the file a reader must NOT rename the\n      // view in when the claim came from a document of their own.\n      locations: [{ path: file, role: \"primary\" as const }],\n      message:\n        `subsystems: ${file} declares \\`view ${id}\\`, which is the id loam generates ` +\n        `into architecture/subsystems.likec4 for services/${owner}/ — LikeC4 merges both files into one project, ` +\n        // The ROOT project, not `architecture/`: the claimant may be a model's\n        // own view now (an extending model is a document of the root project),\n        // and telling that author the `architecture/` project is refused sends\n        // them to look for the breakage in a directory they never touched.\n        `so it refuses the whole root project and renders nothing. ` +\n        `Rename the view in ${file}; ids beginning \\`${SUBSYSTEM_VIEW_PREFIX}\\` are loam's ` +\n        \"to mint, and architecture/subsystems.likec4 is generated (`loam subsystem sync`) and must never be hand-edited.\",\n    });\n  }\n  return findings;\n}\n"]}