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

package/dist/core/repo/tree/render/service/views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.js","sourceRoot":"","sources":["../../../../../../src/core/repo/tree/render/service/views.ts"],"names":[],"mappings":"AAkEA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;AAuB9C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,GACV,GAAG,cAAc,+EAA+E;IAChG,iGAAiG;IACjG,gFAAgF;IAChF,0FAA0F,CAAC;AAE7F;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAwB;IACzD,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,KAAK,GAAa,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACtG,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,KAAK,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QAC9C,IAAI,CAAC,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7F,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACjC,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,SAAS,CAAC,OAA2B,EAAE,KAAwB,EAAE,MAAe;IACvF,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IACxB,MAAM,GAAG,GAAG,CAAC,UAAU,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,GAAG,IAAI,EAAE,cAAc,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC;IAChG,IAAI,MAAM;QAAE,GAAG,CAAC,IAAI,CAAC,oBAAoB,mBAAmB,EAAE,CAAC,CAAC;IAChE,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,GAAG,CAAC,IAAI,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;IAC1D,GAAG,CAAC,IAAI,CAAC,oBAAoB,EAAE,kBAAkB,GAAG,EAAE,EAAE,eAAe,GAAG,KAAK,CAAC,CAAC;IACjF,yEAAyE;IACzE,8EAA8E;IAC9E,2EAA2E;IAC3E,yEAAyE;IACzE,2EAA2E;IAC3E,GAAG,CAAC,IAAI,CAAC,eAAe,GAAG,SAAS,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC;IACpD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["/**\n * `architecture/services.likec4` — one generated LikeC4 view per service,\n * showing that service, its own interior, and its links to everything else the\n * fleet map draws.\n *\n * GENERATED, never authored, exactly like the subsystem views beside it:\n * authored bytes stay authored (archive's verbatim-splice promise), `loam\n * subsystem sync` owns this file outright, and staleness against the tree is a\n * content compare and never a parse — a views-only document does not parse\n * standalone, so nothing in loam ever loads it. docs/DESIGN.md rule 26 does not\n * change with a second file: what a view SHOWS stays unread in every document,\n * this one included.\n *\n * ## The recipe, and why the obvious one is wrong\n *\n * Measured at likec4 1.59.2 on a 120-service and a 58-service fleet. Each view\n * is written as\n *\n *     view service_<id> of <fqn> {\n *       title '<subsystem path> / <service id>'\n *       global style services          // only when the map declares the group\n *       include *                      // the service and its own interior\n *       include <peer>                 // one line per peer, id-sorted\n *       exclude * -> *                 // drop the peer-to-peer cross traffic\n *       include -> <fqn>               // its inbound edges\n *       include <fqn> ->               // its outbound edges\n *       include <fqn>.* -> <fqn>.*     // its internal wiring\n *     }\n *\n * Three things in that shape are measurements rather than taste, and each one\n * fails SILENTLY — zero errors, a wrong picture — if it is tidied away:\n *\n *  1. **The peers are named, not wildcarded.** `./peers.ts` carries the\n *     measurement: `include <fqn> -> *` collapses every counterpart to its\n *     GROUP box and yields zero drill-down on any map that nests services.\n *  2. **The edge predicates are UNARY.** `include -> <fqn>` and `include <fqn>\n *     ->`, never the binary `include * -> <fqn>` / `include <fqn> -> *`.\n *     Measured on `payments.svc0` of the 58-service fleet, swapping the two\n *     unary lines for their binary forms takes the view from 11 nodes to 15:\n *     the four parent GROUP boxes of the named peers come back as nodes of\n *     their own, so the view regrows exactly what rule 1 removed. Zero errors\n *     either way, which is what makes it worth a comment.\n *  3. **`exclude * -> *` sits between the includes and the edge lines.** Without\n *     it the named peers bring their own cross traffic with them: on the same\n *     subject, 24 edges instead of 9, on a view about one service.\n *\n * `of <fqn>` is the navigation half and costs one keyword: LikeC4 computes\n * `navigateTo` into a view declared `of` an element from every OTHER view that\n * draws that element, with no authored links. That is what makes the fleet map,\n * every subsystem view and every other service view click-through into a\n * service. Two views of one element are legal — the first document\n * alphabetically wins the default target and both stay reachable, because the\n * subject's own node cycles to the other — so a team's authored element view in\n * `landscape.likec4` keeps precedence over this file, which sorts later.\n *\n * ## What arrives from outside\n *\n * Everything about the TREE — which services exist, what each one's element is,\n * what its title reads — arrives composed, in `ServiceViewSubject`. This package\n * may not import `../views.ts` or `../text.ts`: the parent imports it, and the\n * reverse edge would be the package cycle `scripts/package-graph.mjs` refuses.\n * So the title arrives already through `likec4String` rather than escaped a\n * second time here; a second escaper is how one of the two forgets an\n * apostrophe and ships a fleet-wide parse error.\n */\nimport type { Rel } from \"../../../../c4/likec4.js\";\nimport { GENERATED_MARK } from \"./header.js\";\nimport { peersOf } from \"./peers.js\";\nimport { serviceViewId } from \"./view-id.js\";\n\n/**\n * The global style group these views reference when the map declares one, the\n * exact counterpart of `SUBSYSTEM_STYLE_GROUP` and reserved on the same terms:\n * presence of the DECLARATION is the whole opt-in, because referencing an\n * undeclared style id is a parse error that blanks the entire `architecture/`\n * project in the renderer. The name mirrors the file it styles.\n */\nexport const SERVICE_STYLE_GROUP = \"services\";\n\n/** One service this file draws — resolved against the map, and already escaped. */\nexport interface ServiceViewSubject {\n  /** The `services/<id>/` directory id: the sort key and the view id's source. */\n  id: string;\n  /** The landscape element it resolves to — the view's `of`, and its subject. */\n  fqn: string;\n  /** `<subsystem path> / <service id>`, already through `likec4String`. */\n  title: string;\n}\n\n/** Everything the file render reads, as one record — see the banner on why it arrives composed. */\nexport interface ServiceViewsInput {\n  subjects: readonly ServiceViewSubject[];\n  /** The map's edges, from which each subject's peer set is computed. */\n  relationships: readonly Rel[];\n  /** Emit `global style services` — true only when the map DECLARES that group. */\n  styled: boolean;\n  /** The one file-level comment the render may write, or null. */\n  disclosure: string | null;\n}\n\n/**\n * The header every generated file opens with — stable bytes, part of the\n * content-compare contract, naming the regenerator so a reader who found the\n * file before the docs knows what owns it. `loam subsystem sync` regenerates\n * BOTH generated files, which is why one command is named here and why one\n * finding code (`subsystem.views-stale`) honestly covers both.\n *\n * It OPENS with the shared `GENERATED_MARK` rather than spelling it, because\n * the same bytes are what `loam subsystem sync` reads back off disk to decide\n * whether the file at this reserved path is loam's to rewrite at all\n * (`./header.js`). A second literal here is how a file loam wrote stops being\n * recognised as loam's.\n */\nconst HEADER =\n  `${GENERATED_MARK} — one overview view per service under services/, drawn from the fleet map.\\n` +\n  \"// Do not edit: `loam subsystem sync` regenerates this file from the directories and the map,\\n\" +\n  \"// and `loam validate --all` reports `subsystem.views-stale` when it drifts.\\n\" +\n  \"// A navigation aid, not the fleet's architecture: author your own diagrams elsewhere.\\n\";\n\n/**\n * Render the whole file, or null when no service resolves to a map element —\n * the file must then be ABSENT, so a fleet whose map draws nothing never\n * carries a generated artifact that says nothing.\n *\n * Services sorted by id and peers sorted by id, one `include` per line: the\n * output is byte-reproducible on any machine from the same committed bytes (no\n * timestamps, no absolute paths, no readdir-order dependence), and two\n * concurrent changes to different services touch different lines, so git merges\n * the file without intervention.\n */\nexport function renderServiceViews(input: ServiceViewsInput): string | null {\n  if (input.subjects.length === 0) return null;\n  const lines: string[] = [HEADER, ...(input.disclosure === null ? [] : [input.disclosure]), \"views {\"];\n  const subjects = [...input.subjects].sort((a, b) => (a.id < b.id ? -1 : 1));\n  for (const [i, subject] of subjects.entries()) {\n    if (i > 0) lines.push(\"\");\n    lines.push(...viewLines(subject, peersOf(subject.fqn, input.relationships), input.styled));\n  }\n  lines.push(\"}\");\n  return lines.join(\"\\n\") + \"\\n\";\n}\n\n/**\n * One view, in the order the parser demands: metadata FIRST, and that is a hard\n * constraint rather than a taste — measured, an `include` line followed by\n * `title` is a parse error (\"Expecting token of type '}' but found `title`\"),\n * and one parse error in this file blanks the whole `architecture/` project in\n * the renderer. `global style` sits after `title` and before anything that\n * includes, where the same pin measured it parsing with zero errors.\n */\nfunction viewLines(subject: ServiceViewSubject, peers: readonly string[], styled: boolean): string[] {\n  const { fqn } = subject;\n  const out = [`  view ${serviceViewId(subject.id)} of ${fqn} {`, `    title '${subject.title}'`];\n  if (styled) out.push(`    global style ${SERVICE_STYLE_GROUP}`);\n  out.push(\"    include *\");\n  for (const peer of peers) out.push(`    include ${peer}`);\n  out.push(\"    exclude * -> *\", `    include -> ${fqn}`, `    include ${fqn} ->`);\n  // The interior wiring, last. Measured: `include <fqn>.* -> <fqn>.*` on a\n  // CHILDLESS element is legal — `likec4 validate` reports valid and the export\n  // carries zero errors — so one generated line serves both model shapes: an\n  // EXTENDING model's containers live in the root project and are drawn, a\n  // STANDALONE model's are not in this project and the line matches nothing.\n  out.push(`    include ${fqn}.* -> ${fqn}.*`, \"  }\");\n  return out;\n}\n"]}

package/dist/core/repo/tree/render/stale.js

@@ -16,9 +16,26 @@
  */
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { renderSubsystemViews, viewsAgree } from "./views.js";
+import { renderServiceOverviews, renderSubsystemViews, viewsAgree } from "./views.js";
 export async function viewsState(path, tree, map) {
-    const expected = renderSubsystemViews(tree, map);
+    return stateOf(path, renderSubsystemViews(tree, map));
+}
+/**
+ * The same question about the OTHER generated file, `architecture/services.likec4`.
+ *
+ * A second exported function rather than a `which` parameter, and a second call
+ * at every asker rather than one that answers about both: the two files go stale
+ * for different reasons and are repaired in one command, so a caller that wants
+ * both asks twice and names each file in its own finding —
+ * `subsystem.views-stale` carries the path precisely so one code can honestly
+ * cover two files. Folding them into one state would lose which one drifted,
+ * which is the only thing the message has to say.
+ */
+export async function serviceViewsState(path, tree, map) {
+    return stateOf(path, renderServiceOverviews(tree, map));
+}
+/** Read the file, or record its absence, and compare — the half both askers share. */
+async function stateOf(path, expected) {
     const actual = existsSync(path) ? await readFile(path, "utf8") : null;
     return { actual, expected, agrees: viewsAgree(actual, expected) };
 }

package/dist/core/repo/tree/render/stale.js.map

@@ -1 +1 @@
-{"version":3,"file":"stale.js","sourceRoot":"","sources":["../../../../../src/core/repo/tree/render/stale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAiB,oBAAoB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgB7E,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,IAAe,EAAE,GAAa;IAC3E,MAAM,QAAQ,GAAG,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;AACpE,CAAC","sourcesContent":["/**\n * Is the generated file on disk what this tree and this map render to?\n *\n * One function, because the question now has three askers — `validate --all`\n * (which turns a disagreement into `subsystem.views-stale`), `loam subsystem\n * sync` and the write verbs (which repair it), and `loam archive` (which must\n * not report a repo current when it has just made the file stale). Three\n * private compares would be three chances to answer differently about one\n * file, and the module that mints the bytes is the one that owes the answer.\n *\n * The PATH arrives as a parameter rather than a `DocsDir`: `repo/paths.ts`\n * owns the spelling of every file in a docs repo, and importing it here would\n * close the package cycle `repo → repo/tree → repo/tree/render → repo` that\n * `scripts/package-graph.mjs` exists to refuse. `walk.ts` pays the same price\n * for the same reason and says so.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport type { FleetTree } from \"../walk.js\";\nimport { type MapFacts, renderSubsystemViews, viewsAgree } from \"./views.js\";\n\n/**\n * The three states, kept apart: absent, must-be-absent, and\n * present-but-different are three different sentences, and a fleet whose views\n * file does not exist is not a fleet whose views file is blank.\n */\nexport interface ViewsState {\n  /** The bytes on disk, or null when the file is not there. */\n  actual: string | null;\n  /** The bytes the tree renders to, or null when the file must be absent. */\n  expected: string | null;\n  /** Do the two say the same thing? Content, not bytes — `viewsAgree` says why. */\n  agrees: boolean;\n}\n\nexport async function viewsState(path: string, tree: FleetTree, map: MapFacts): Promise<ViewsState> {\n  const expected = renderSubsystemViews(tree, map);\n  const actual = existsSync(path) ? await readFile(path, \"utf8\") : null;\n  return { actual, expected, agrees: viewsAgree(actual, expected) };\n}\n"]}
+{"version":3,"file":"stale.js","sourceRoot":"","sources":["../../../../../src/core/repo/tree/render/stale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAiB,sBAAsB,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgBrG,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,IAAe,EAAE,GAAa;IAC3E,OAAO,OAAO,CAAC,IAAI,EAAE,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAY,EAAE,IAAe,EAAE,GAAa;IAClF,OAAO,OAAO,CAAC,IAAI,EAAE,sBAAsB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED,sFAAsF;AACtF,KAAK,UAAU,OAAO,CAAC,IAAY,EAAE,QAAuB;IAC1D,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;AACpE,CAAC","sourcesContent":["/**\n * Is the generated file on disk what this tree and this map render to?\n *\n * One function, because the question now has three askers — `validate --all`\n * (which turns a disagreement into `subsystem.views-stale`), `loam subsystem\n * sync` and the write verbs (which repair it), and `loam archive` (which must\n * not report a repo current when it has just made the file stale). Three\n * private compares would be three chances to answer differently about one\n * file, and the module that mints the bytes is the one that owes the answer.\n *\n * The PATH arrives as a parameter rather than a `DocsDir`: `repo/paths.ts`\n * owns the spelling of every file in a docs repo, and importing it here would\n * close the package cycle `repo → repo/tree → repo/tree/render → repo` that\n * `scripts/package-graph.mjs` exists to refuse. `walk.ts` pays the same price\n * for the same reason and says so.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport type { FleetTree } from \"../walk.js\";\nimport { type MapFacts, renderServiceOverviews, renderSubsystemViews, viewsAgree } from \"./views.js\";\n\n/**\n * The three states, kept apart: absent, must-be-absent, and\n * present-but-different are three different sentences, and a fleet whose views\n * file does not exist is not a fleet whose views file is blank.\n */\nexport interface ViewsState {\n  /** The bytes on disk, or null when the file is not there. */\n  actual: string | null;\n  /** The bytes the tree renders to, or null when the file must be absent. */\n  expected: string | null;\n  /** Do the two say the same thing? Content, not bytes — `viewsAgree` says why. */\n  agrees: boolean;\n}\n\nexport async function viewsState(path: string, tree: FleetTree, map: MapFacts): Promise<ViewsState> {\n  return stateOf(path, renderSubsystemViews(tree, map));\n}\n\n/**\n * The same question about the OTHER generated file, `architecture/services.likec4`.\n *\n * A second exported function rather than a `which` parameter, and a second call\n * at every asker rather than one that answers about both: the two files go stale\n * for different reasons and are repaired in one command, so a caller that wants\n * both asks twice and names each file in its own finding —\n * `subsystem.views-stale` carries the path precisely so one code can honestly\n * cover two files. Folding them into one state would lose which one drifted,\n * which is the only thing the message has to say.\n */\nexport async function serviceViewsState(path: string, tree: FleetTree, map: MapFacts): Promise<ViewsState> {\n  return stateOf(path, renderServiceOverviews(tree, map));\n}\n\n/** Read the file, or record its absence, and compare — the half both askers share. */\nasync function stateOf(path: string, expected: string | null): Promise<ViewsState> {\n  const actual = existsSync(path) ? await readFile(path, \"utf8\") : null;\n  return { actual, expected, agrees: viewsAgree(actual, expected) };\n}\n"]}

package/dist/core/repo/tree/render/views.js

@@ -49,6 +49,9 @@
  */
 import {} from "../../../c4/likec4.js";
 import { renderContext, viewBody } from "./body.js";
+import { GENERATED_MARK } from "./service/header.js";
+import { escapeViewIdSegment } from "./service/view-id.js";
+import { renderServiceViews, SERVICE_STYLE_GROUP, } from "./service/views.js";
 import { likec4String, viewTitle } from "./text.js";
 /**
  * The global style group a generated view references when the map declares
@@ -75,8 +78,14 @@ export const SUBSYSTEM_STYLE_GROUP = "subsystems";
  * The header every generated file opens with — stable bytes, part of the
  * byte-compare contract, naming the regenerator so a reader who found the
  * file first knows what owns it.
+ *
+ * It OPENS with the shared `GENERATED_MARK` rather than spelling it, because
+ * the same bytes are what `loam subsystem sync` reads back off disk to decide
+ * whether the file standing at this reserved path is loam's to rewrite at all
+ * (`./service/header.ts` carries the whole reason). A second literal here is
+ * how a file loam wrote stops being recognised as loam's.
  */
-const HEADER = "// generated by loam — the subsystem tree under services/, one view per subsystem.\n" +
+const HEADER = `${GENERATED_MARK} — the subsystem tree under services/, one view per subsystem.\n` +
     "// Do not edit: `loam subsystem sync` regenerates this file from the directories,\n" +
     "// and `loam validate --all` reports `subsystem.views-stale` when it drifts.\n" +
     "// A scoping aid, not the fleet's architecture: author your own diagrams elsewhere.\n";
@@ -89,12 +98,16 @@ const HEADER = "// generated by loam — the subsystem tree under services/, one
  * generated views ignore it. Silent when the map declares no group at all: a
  * fleet with no palette is owed no sentence about one. Ids go unescaped
  * because LikeC4's grammar admits only identifier bytes in a style id.
+ *
+ * The group is a PARAMETER because there are two generated files now and each
+ * reserves its own name (`subsystems`, `services`); a map declaring one and not
+ * the other must get the sentence in exactly the file that went unstyled.
  */
-function stylesDisclosure(declared) {
-    if (declared.length === 0 || declared.includes(SUBSYSTEM_STYLE_GROUP))
+function stylesDisclosure(declared, group) {
+    if (declared.length === 0 || declared.includes(group))
         return null;
     return (`// styles: the project declares global style group(s) ${[...declared].sort().join(", ")}, ` +
-        `and none named \`${SUBSYSTEM_STYLE_GROUP}\` — these views carry the renderer's defaults until one is.`);
+        `and none named \`${group}\` — these views carry the renderer's defaults until one is.`);
 }
 /**
  * Render the views file for a walked tree, or null when the tree has no
@@ -107,7 +120,7 @@ export function renderSubsystemViews(tree, map) {
     const ctx = renderContext(tree, map.elements);
     const declared = map.globalStyles ?? [];
     const styled = declared.includes(SUBSYSTEM_STYLE_GROUP);
-    const disclosure = stylesDisclosure(declared);
+    const disclosure = stylesDisclosure(declared, SUBSYSTEM_STYLE_GROUP);
     const lines = [HEADER, ...(disclosure === null ? [] : [disclosure]), "views {"];
     const subsystems = [...tree.subsystems].sort((a, b) => (pathKey(a) < pathKey(b) ? -1 : 1));
     for (const [i, sub] of subsystems.entries()) {
@@ -117,13 +130,23 @@ export function renderSubsystemViews(tree, map) {
         const body = viewBody(ctx, sub);
         if (body.disclosure !== null)
             lines.push(`  // ${body.disclosure}`);
-        lines.push(`  view ${subsystemViewId(sub)} {`);
+        // `of <ancestor>` when — and only when — the map holds an element that owns
+        // exactly this subsystem's members (`../render/body.ts` argues the
+        // "exactly"). It is the same one keyword the per-service views spend, and it
+        // buys the same thing: LikeC4 computes `navigateTo` into this view from
+        // every other view that draws that element, so the fleet map's group boxes
+        // become click-through and a neighbouring group box inside one subsystem
+        // view opens THAT subsystem's view. Measured at 58 services in 11 groups,
+        // 12 of 14 nodes navigable. With no owning ancestor there is no element to
+        // be `of`, so there is no navigation — honest, and one more reason to nest
+        // the map that loam already discloses one line above.
+        lines.push(`  view ${subsystemViewId(sub)}${body.of === null ? "" : ` of ${body.of}`} {`);
         // Metadata FIRST, and that ordering is a hard constraint rather than a
         // taste: measured, an `include` OR a `group { … }` line followed by
         // `title` is a parse error ("Expecting token of type '}' but found
         // `title`"), and one parse error in this file blanks the whole
         // `architecture/` project in the renderer.
-        lines.push(`    title '${viewTitle(titleChain(tree, sub))}'`);
+        lines.push(`    title '${viewTitle(titleChain(tree, sub.path))}'`);
         const description = likec4String(sub.meta.description ?? "");
         if (description !== "")
             lines.push(`    description '${description}'`);
@@ -142,8 +165,62 @@ export function renderSubsystemViews(tree, map) {
     return lines.join("\n") + "\n";
 }
 /**
- * This subsystem and every MARKED ancestor above it, outermost first — the
- * chain `viewTitle` composes a path out of.
+ * The GENERATED per-service overviews — `architecture/services.likec4`, one
+ * view per service the map resolves. Null when it resolves none, so the file is
+ * then absent exactly as `subsystems.likec4` is for a tree with no subsystems.
+ *
+ * This function is the composer and nothing else: `./service/` owns the view
+ * shape and its measurements, and everything about the TREE is resolved here,
+ * because that package may not import `./body.ts` or `./text.ts` (the edge runs
+ * the other way — `./service/views.ts` says why) and duplicating either would
+ * put a second element→service join and a second string escaper in the tree.
+ *
+ * Emission is gated on the SAME join the subsystem views use: a service the map
+ * does not draw is omitted rather than invented, because that omission is
+ * already `landscape.service-unmodelled` and rendering only what the committed
+ * map resolves keeps the output a function of committed bytes alone.
+ */
+export function renderServiceOverviews(tree, map) {
+    const ctx = renderContext(tree, map.elements);
+    const declared = map.globalStyles ?? [];
+    const subjects = [];
+    for (const service of tree.services) {
+        const fqn = ctx.elementOf.get(service.id);
+        if (fqn === undefined)
+            continue;
+        subjects.push({ id: service.id, fqn, title: serviceViewTitle(tree, service.subsystem, service.id) });
+    }
+    return renderServiceViews({
+        subjects,
+        relationships: map.relationships,
+        styled: declared.includes(SERVICE_STYLE_GROUP),
+        disclosure: stylesDisclosure(declared, SERVICE_STYLE_GROUP),
+    });
+}
+/**
+ * A per-service view's title: its subsystem path and then its own id, joined
+ * with ` / ` — `Platform / order-flow / checkout-web`, or bare `checkout-web`
+ * for a service filed directly under `services/`.
+ *
+ * LikeC4 reads that as a folder path (`./text.ts` measured it), so a service's
+ * overview lands in the SAME browser folder as its subsystem's view rather than
+ * in a flat list of fifty-eight titles — which is the whole readability answer
+ * at fleet scale, and it costs the same helpers the subsystem views already use.
+ *
+ * The leaf is the service's `services/<id>/` DIRECTORY id and deliberately not
+ * the map element's title: it is the name every loam command addresses the
+ * service by, it cannot drift when somebody renames a box on the map, and a
+ * directory name cannot contain `/`, so it needs no folder-separator
+ * substitution of its own. It still goes through `likec4String` — an id is a
+ * directory name, and a directory name is somebody else's word.
+ */
+function serviceViewTitle(tree, subsystem, id) {
+    return [viewTitle(titleChain(tree, subsystem)), likec4String(id)].filter((part) => part !== "").join(" / ");
+}
+/**
+ * The MARKED subsystems along a path, outermost first — the chain `viewTitle`
+ * composes a folder path out of, for a subsystem's own view and for the view of
+ * a service filed beneath it alike.
  *
  * Marked, because an intermediate directory holding no `subsystem.yaml` is
  * `subsystem.unmarked`, an error the walk already names: it is not a group,
@@ -151,9 +228,9 @@ export function renderSubsystemViews(tree, map) {
  * rather than off the path segments, so what the title says and what the
  * finding says about the same directory cannot disagree.
  */
-function titleChain(tree, sub) {
+function titleChain(tree, path) {
     return tree.subsystems
-        .filter((s) => s.path.length <= sub.path.length && s.path.every((name, i) => sub.path[i] === name))
+        .filter((s) => s.path.length <= path.length && s.path.every((name, i) => path[i] === name))
         .sort((a, b) => a.path.length - b.path.length);
 }
 /** The sort key and the comment spelling: the subsystem's path from services/, joined. */
@@ -164,31 +241,23 @@ function pathKey(sub) {
  * A LikeC4 identifier for the view, derived from the subsystem's path so
  * nesting reads in the name — and INJECTIVE over every path the name grammar
  * admits, because the renderer refuses the whole `architecture/` project over
- * a duplicate view id. The naive folding (every non-identifier byte and the
- * join separator alike becoming `_`) collided three DISTINCT healthy names
- * onto one identifier — `a_b`, and `b` under `a`, both rendered
- * `subsystem_a_b` — so `validate --all` was green while the renderer refused
- * the fleet map; `subsystem.name-collision` never fires because the flat
- * namespace really is intact. Hence the encoding: an identifier byte
- * (`[A-Za-z0-9]`) passes through, any other byte becomes `_` + two lowercase
- * hex digits (`.` → `_2e`, `-` → `_2d`, `_` itself → `_5f` — the underscore
- * must be escaped precisely because it is BOTH legal in a name and the
- * separator), and segments join on `__`. Underscore runs then decode
- * uniquely — one is an escape, two a separator, three a separator followed
- * by an escape — so no two distinct legal paths share an identifier. A name
- * `subsystem.name-invalid` already flagged may hold a code point above 0xff
- * whose longer hex could in principle re-collide; it is deterministic still,
- * and that directory is already an error finding by name.
- *
- * EXPORTED, with its prefix, because `subsystem.view-id-collision` has to ask
- * the generator what it mints rather than re-deriving it. A check carrying its
- * own copy of the escaping above would go quiet the day the encoding changed,
- * and going quiet is the failure this whole family exists to prevent.
+ * a duplicate view id.
+ *
+ * The per-BYTE encoding, the collision it was written against, and the reason
+ * segments join on `__` all live with the encoder in `./service/view-id.ts` —
+ * which is also where the per-service ids are minted, so the two generated
+ * files cannot drift into two spellings of the same escape. That module sits
+ * BELOW this one on purpose: it is the leaf, and the import may only run
+ * downward (`./service/views.ts`'s banner records the package direction).
+ *
+ * EXPORTED here still, with its prefix, because `subsystem.view-id-collision`
+ * has to ask the generator what it mints rather than re-deriving it. A check
+ * carrying its own copy of the escaping would go quiet the day the encoding
+ * changed, and going quiet is the failure this whole family exists to prevent.
  */
 export const SUBSYSTEM_VIEW_PREFIX = "subsystem_";
 export function subsystemViewId(sub) {
-    const segment = (name) => [...name].map((ch) => (/[A-Za-z0-9]/.test(ch) ? ch : `_${ch.codePointAt(0).toString(16).padStart(2, "0")}`)).join("");
-    return `subsystem_${sub.path.map(segment).join("__")}`;
+    return `${SUBSYSTEM_VIEW_PREFIX}${sub.path.map(escapeViewIdSegment).join("__")}`;
 }
 /**
  * Does the file on disk already SAY what `renderSubsystemViews` renders?

package/dist/core/repo/tree/render/views.js.map

@@ -1 +1 @@
-{"version":3,"file":"views.js","sourceRoot":"","sources":["../../../../../src/core/repo/tree/render/views.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The generated views file: `architecture/subsystems.likec4`, one LikeC4 view\n * per subsystem enumerating the services beneath it. GENERATED, never\n * authored — authored bytes stay authored (archive's verbatim-splice promise),\n * so the tree is mirrored into a file of its own that `loam subsystem sync`\n * owns outright, and staleness against the tree is a byte compare\n * (`subsystem.views-stale` in `validate --all`), never a parse: a spike\n * confirmed a views-only document does NOT parse standalone (its `include`\n * lines reference elements the landscape defines), so nothing in loam ever\n * loads this file (and rule 26 does not change that: this file is GENERATED and\n * holds STATIC views, whose contents loam may not read in any document) — only\n * the LikeC4 renderer, which merges the whole `architecture/` project per\n * likec4.config.json, resolves it.\n *\n * Each view opens with the LABEL a human reads — `title`, and `description`\n * when the marker carries one — because this file exists only to be rendered\n * and an unlabelled view is shown by its id, which is hex-escaped for\n * injectivity and reads as `subsystem_platform__order_2dflow`. Both\n * strings are somebody else's words and go through `likec4String`, which\n * records what a raw one does.\n *\n * The output is deterministic and line-oriented, and both halves are the\n * contract: subsystems sorted by path, members sorted by id, ONE `include`\n * per line — so two concurrent moves into different groups touch different\n * lines and git merges the file without intervention, exactly as the\n * service-grouped landscape splice already achieves. Byte-reproducible on any\n * machine: no timestamps, no absolute paths, no readdir-order dependence (the\n * walk sorts, and every list is re-sorted here). Plain lexicographic sorts on\n * purpose — the ids' own grammar is ASCII, an INVALID name is still ordered\n * deterministically, and `compareIds`' numeric tokenizing lives in `repo/`,\n * which this package must not import (`walk.ts` says why the edge only points\n * the other way).\n *\n * Membership is TRANSITIVE: a subsystem's view includes every service beneath\n * it at any depth, so a parent's view is the whole group's map rather than an\n * empty frame around its children. An empty view body is legal LikeC4 (same\n * spike), so an empty subsystem renders as one — `subsystem new` must be\n * usable before anything moves in.\n *\n * Include lines name the landscape ELEMENT id, resolved through the same\n * element→service join `validate` uses (`serviceResolver`: explicit\n * `metadata { service }` binding first, then a title naming a real service) —\n * because element ids in real landscapes are not service ids, and a view of\n * raw service ids would silently render empty for every such fleet. A member\n * with no landscape element is omitted from the includes: the omission is\n * already an error (`landscape.service-unmodelled`), and rendering only what\n * the committed landscape resolves keeps the output a function of committed\n * bytes alone.\n */\nimport { type LoadedDoc } from \"../../../c4/likec4.js\";\nimport { renderContext, viewBody } from \"./body.js\";\nimport { likec4String, viewTitle } from \"./text.js\";\nimport type { FleetTree, SubsystemEntry } from \"../walk.js\";\n\n/**\n * The global style group a generated view references when the map declares\n * one: `global { styleGroup subsystems { … } }` (or the single-rule form\n * `global { style subsystems … }` — LikeC4 files both under one id table).\n * Presence is the opt-in and it is read off a DECLARATION, never a view: a\n * generated view cannot carry an inline `style` rule of its own (the file is\n * regenerated wholesale), and the one mechanism LikeC4 offers a view for\n * borrowing a repository's palette is a reference to a global style by id.\n * Referencing one that is not declared is a parse error that blanks the whole\n * `architecture/` project in the renderer, which is why the line is written\n * only when the id is declared and why its absence leaves the file exactly\n * what it was before this constant existed.\n *\n * One conventional name rather than \"the single declared group\": a second\n * group somebody declares for a hand-drawn view would otherwise silently\n * switch the generated views' styling OFF and restale the file on a change\n * that touched no subsystem — behaviour flipping on an unrelated declaration\n * is the shape `body.ts` calls \"a picture that looks the same whether or not\n * the two agree\". The name mirrors the file it styles.\n */\nexport const SUBSYSTEM_STYLE_GROUP = \"subsystems\";\n\n/**\n * What the render reads off the parsed map: the elements the member join\n * resolves, and the global style ids a view may reference. A record rather\n * than a third parameter because the two come out of ONE parsed document, and\n * passing them apart would make an inconsistent pair representable. Every\n * `LoadedDoc` is structurally a `MapFacts`, so a caller holding the document\n * passes the document.\n */\nexport type MapFacts = Pick<LoadedDoc, \"elements\" | \"globalStyles\">;\n\n/**\n * The header every generated file opens with — stable bytes, part of the\n * byte-compare contract, naming the regenerator so a reader who found the\n * file first knows what owns it.\n */\nconst HEADER =\n  \"// generated by loam — the subsystem tree under services/, one view per subsystem.\\n\" +\n  \"// Do not edit: `loam subsystem sync` regenerates this file from the directories,\\n\" +\n  \"// and `loam validate --all` reports `subsystem.views-stale` when it drifts.\\n\" +\n  \"// A scoping aid, not the fleet's architecture: author your own diagrams elsewhere.\\n\";\n\n/**\n * The one file-level comment the render may write: the map declares global\n * style groups, and none is the conventional one. Written between `HEADER`\n * and `views {` — outside every view body, graded by nothing — so a team\n * that already declared a palette under another name reads the fix in the\n * diff of the sync that regenerated the file, instead of wondering why the\n * generated views ignore it. Silent when the map declares no group at all: a\n * fleet with no palette is owed no sentence about one. Ids go unescaped\n * because LikeC4's grammar admits only identifier bytes in a style id.\n */\nfunction stylesDisclosure(declared: readonly string[]): string | null {\n  if (declared.length === 0 || declared.includes(SUBSYSTEM_STYLE_GROUP)) return null;\n  return (\n    `// styles: the project declares global style group(s) ${[...declared].sort().join(\", \")}, ` +\n    `and none named \\`${SUBSYSTEM_STYLE_GROUP}\\` — these views carry the renderer's defaults until one is.`\n  );\n}\n\n/**\n * Render the views file for a walked tree, or null when the tree has no\n * subsystems — the file must then be ABSENT, so a flat fleet never carries a\n * generated artifact that says nothing.\n */\nexport function renderSubsystemViews(tree: FleetTree, map: MapFacts): string | null {\n  if (tree.subsystems.length === 0) return null;\n  const ctx = renderContext(tree, map.elements);\n  const declared = map.globalStyles ?? [];\n  const styled = declared.includes(SUBSYSTEM_STYLE_GROUP);\n  const disclosure = stylesDisclosure(declared);\n  const lines: string[] = [HEADER, ...(disclosure === null ? [] : [disclosure]), \"views {\"];\n  const subsystems = [...tree.subsystems].sort((a, b) => (pathKey(a) < pathKey(b) ? -1 : 1));\n  for (const [i, sub] of subsystems.entries()) {\n    if (i > 0) lines.push(\"\");\n    lines.push(`  // services/${pathKey(sub)}`);\n    const body = viewBody(ctx, sub);\n    if (body.disclosure !== null) lines.push(`  // ${body.disclosure}`);\n    lines.push(`  view ${subsystemViewId(sub)} {`);\n    // Metadata FIRST, and that ordering is a hard constraint rather than a\n    // taste: measured, an `include` OR a `group { … }` line followed by\n    // `title` is a parse error (\"Expecting token of type '}' but found\n    // `title`\"), and one parse error in this file blanks the whole\n    // `architecture/` project in the renderer.\n    lines.push(`    title '${viewTitle(titleChain(tree, sub))}'`);\n    const description = likec4String(sub.meta.description ?? \"\");\n    if (description !== \"\") lines.push(`    description '${description}'`);\n    // After the label, before anything that includes: measured at the pin\n    // (test/likec4-view-shape.test.ts), a `global style <id>` line here\n    // parses with zero errors, while the same line before `title` is the\n    // parse error the comment above records. The palette is the map's own —\n    // the group is declared in the same project this file renders into — so\n    // the reference resolves exactly when the presence test says it does.\n    if (styled) lines.push(`    global style ${SUBSYSTEM_STYLE_GROUP}`);\n    lines.push(...body.lines);\n    lines.push(\"  }\");\n  }\n  lines.push(\"}\");\n  return lines.join(\"\\n\") + \"\\n\";\n}\n\n/**\n * This subsystem and every MARKED ancestor above it, outermost first — the\n * chain `viewTitle` composes a path out of.\n *\n * Marked, because an intermediate directory holding no `subsystem.yaml` is\n * `subsystem.unmarked`, an error the walk already names: it is not a group,\n * so it contributes no folder level here either. Read off the walked tree\n * rather than off the path segments, so what the title says and what the\n * finding says about the same directory cannot disagree.\n */\nfunction titleChain(tree: FleetTree, sub: SubsystemEntry): SubsystemEntry[] {\n  return tree.subsystems\n    .filter((s) => s.path.length <= sub.path.length && s.path.every((name, i) => sub.path[i] === name))\n    .sort((a, b) => a.path.length - b.path.length);\n}\n\n/** The sort key and the comment spelling: the subsystem's path from services/, joined. */\nfunction pathKey(sub: SubsystemEntry): string {\n  return sub.path.join(\"/\");\n}\n\n/**\n * A LikeC4 identifier for the view, derived from the subsystem's path so\n * nesting reads in the name — and INJECTIVE over every path the name grammar\n * admits, because the renderer refuses the whole `architecture/` project over\n * a duplicate view id. The naive folding (every non-identifier byte and the\n * join separator alike becoming `_`) collided three DISTINCT healthy names\n * onto one identifier — `a_b`, and `b` under `a`, both rendered\n * `subsystem_a_b` — so `validate --all` was green while the renderer refused\n * the fleet map; `subsystem.name-collision` never fires because the flat\n * namespace really is intact. Hence the encoding: an identifier byte\n * (`[A-Za-z0-9]`) passes through, any other byte becomes `_` + two lowercase\n * hex digits (`.` → `_2e`, `-` → `_2d`, `_` itself → `_5f` — the underscore\n * must be escaped precisely because it is BOTH legal in a name and the\n * separator), and segments join on `__`. Underscore runs then decode\n * uniquely — one is an escape, two a separator, three a separator followed\n * by an escape — so no two distinct legal paths share an identifier. A name\n * `subsystem.name-invalid` already flagged may hold a code point above 0xff\n * whose longer hex could in principle re-collide; it is deterministic still,\n * and that directory is already an error finding by name.\n *\n * EXPORTED, with its prefix, because `subsystem.view-id-collision` has to ask\n * the generator what it mints rather than re-deriving it. A check carrying its\n * own copy of the escaping above would go quiet the day the encoding changed,\n * and going quiet is the failure this whole family exists to prevent.\n */\nexport const SUBSYSTEM_VIEW_PREFIX = \"subsystem_\";\n\nexport function subsystemViewId(sub: SubsystemEntry): string {\n  const segment = (name: string): string =>\n    [...name].map((ch) => (/[A-Za-z0-9]/.test(ch) ? ch : `_${ch.codePointAt(0)!.toString(16).padStart(2, \"0\")}`)).join(\"\");\n  return `subsystem_${sub.path.map(segment).join(\"__\")}`;\n}\n\n/**\n * Does the file on disk already SAY what `renderSubsystemViews` renders?\n *\n * The generator above only ever emits LF. `core.autocrlf=true` is Git for\n * Windows' installer default and a docs repo ships no `.gitattributes`, so an\n * ordinary Windows clone hands the file back with CRLF and not one fact\n * changed. Four call sites asked this question with a byte equality and all\n * four answered \"stale\" on such a clone: `loam validate` reported an error,\n * `loam subsystem sync` reported `updated` and rewrote with LF, git then showed\n * the file permanently modified, and the next checkout restored the CRLF. That\n * is a loop rather than a diagnosis, which is why the comparison lives here\n * now — the module that mints the bytes is the one that owes an answer about\n * them, and three near-copies of this rule would go stale one at a time.\n *\n * Still never a parse: a views-only document does not parse standalone, and no\n * check anywhere reads this file's content. The narrowing is from BYTES to\n * CONTENT, which is what `subsystem.views-stale`'s own message (\"does not match\n * the tree\") already claims. The symmetric cost is accepted and is the one\n * `core/verify/pins/pin.ts` documents for `pinnedDigest`: a pure line-ending\n * change is invisible, correctly, because it is not a change to what the file\n * says.\n *\n * `null` is carried through as itself rather than collapsing into `\"\"`: absent,\n * must-be-absent and present-but-different are three distinct states with three\n * distinct messages, and a fleet whose views file does not exist is not a fleet\n * whose views file is blank.\n */\nexport function viewsAgree(actual: string | null, expected: string | null): boolean {\n  const lf = (text: string | null): string | null => (text === null ? null : text.replace(/\\r\\n|\\r/g, \"\\n\"));\n  return lf(actual) === lf(expected);\n}\n"]}
+{"version":3,"file":"views.js","sourceRoot":"","sources":["../../../../../src/core/repo/tree/render/views.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The generated views file: `architecture/subsystems.likec4`, one LikeC4 view\n * per subsystem enumerating the services beneath it. GENERATED, never\n * authored — authored bytes stay authored (archive's verbatim-splice promise),\n * so the tree is mirrored into a file of its own that `loam subsystem sync`\n * owns outright, and staleness against the tree is a byte compare\n * (`subsystem.views-stale` in `validate --all`), never a parse: a spike\n * confirmed a views-only document does NOT parse standalone (its `include`\n * lines reference elements the landscape defines), so nothing in loam ever\n * loads this file (and rule 26 does not change that: this file is GENERATED and\n * holds STATIC views, whose contents loam may not read in any document) — only\n * the LikeC4 renderer, which merges the whole `architecture/` project per\n * likec4.config.json, resolves it.\n *\n * Each view opens with the LABEL a human reads — `title`, and `description`\n * when the marker carries one — because this file exists only to be rendered\n * and an unlabelled view is shown by its id, which is hex-escaped for\n * injectivity and reads as `subsystem_platform__order_2dflow`. Both\n * strings are somebody else's words and go through `likec4String`, which\n * records what a raw one does.\n *\n * The output is deterministic and line-oriented, and both halves are the\n * contract: subsystems sorted by path, members sorted by id, ONE `include`\n * per line — so two concurrent moves into different groups touch different\n * lines and git merges the file without intervention, exactly as the\n * service-grouped landscape splice already achieves. Byte-reproducible on any\n * machine: no timestamps, no absolute paths, no readdir-order dependence (the\n * walk sorts, and every list is re-sorted here). Plain lexicographic sorts on\n * purpose — the ids' own grammar is ASCII, an INVALID name is still ordered\n * deterministically, and `compareIds`' numeric tokenizing lives in `repo/`,\n * which this package must not import (`walk.ts` says why the edge only points\n * the other way).\n *\n * Membership is TRANSITIVE: a subsystem's view includes every service beneath\n * it at any depth, so a parent's view is the whole group's map rather than an\n * empty frame around its children. An empty view body is legal LikeC4 (same\n * spike), so an empty subsystem renders as one — `subsystem new` must be\n * usable before anything moves in.\n *\n * Include lines name the landscape ELEMENT id, resolved through the same\n * element→service join `validate` uses (`serviceResolver`: explicit\n * `metadata { service }` binding first, then a title naming a real service) —\n * because element ids in real landscapes are not service ids, and a view of\n * raw service ids would silently render empty for every such fleet. A member\n * with no landscape element is omitted from the includes: the omission is\n * already an error (`landscape.service-unmodelled`), and rendering only what\n * the committed landscape resolves keeps the output a function of committed\n * bytes alone.\n */\nimport { type LoadedDoc } from \"../../../c4/likec4.js\";\nimport { renderContext, viewBody } from \"./body.js\";\nimport { GENERATED_MARK } from \"./service/header.js\";\nimport { escapeViewIdSegment } from \"./service/view-id.js\";\nimport {\n  renderServiceViews,\n  SERVICE_STYLE_GROUP,\n  type ServiceViewSubject,\n} from \"./service/views.js\";\nimport { likec4String, viewTitle } from \"./text.js\";\nimport type { FleetTree, SubsystemEntry } from \"../walk.js\";\n\n/**\n * The global style group a generated view references when the map declares\n * one: `global { styleGroup subsystems { … } }` (or the single-rule form\n * `global { style subsystems … }` — LikeC4 files both under one id table).\n * Presence is the opt-in and it is read off a DECLARATION, never a view: a\n * generated view cannot carry an inline `style` rule of its own (the file is\n * regenerated wholesale), and the one mechanism LikeC4 offers a view for\n * borrowing a repository's palette is a reference to a global style by id.\n * Referencing one that is not declared is a parse error that blanks the whole\n * `architecture/` project in the renderer, which is why the line is written\n * only when the id is declared and why its absence leaves the file exactly\n * what it was before this constant existed.\n *\n * One conventional name rather than \"the single declared group\": a second\n * group somebody declares for a hand-drawn view would otherwise silently\n * switch the generated views' styling OFF and restale the file on a change\n * that touched no subsystem — behaviour flipping on an unrelated declaration\n * is the shape `body.ts` calls \"a picture that looks the same whether or not\n * the two agree\". The name mirrors the file it styles.\n */\nexport const SUBSYSTEM_STYLE_GROUP = \"subsystems\";\n\n/**\n * What the render reads off the parsed map: the elements the member join\n * resolves, the RELATIONSHIPS a per-service view computes its peer set from,\n * and the global style ids a view may reference. A record rather than three\n * threaded parameters because all three come out of ONE parsed document, and\n * passing them apart would make an inconsistent pair representable. Every\n * `LoadedDoc` is structurally a `MapFacts`, so a caller holding the document\n * passes the document.\n *\n * `relationships` is REQUIRED, and that is the type doing work rather than a\n * shape falling out of `LoadedDoc`. It was optional once, on the reasoning that\n * the `LoadedDoc` literals standing in for a map that is absent or did not parse\n * have no edges to offer — and the consequence of omitting it is SILENT: every\n * per-service view renders with NO peers, the service and its own interior and\n * nothing it touches, with no error anywhere. Two independent readers found the\n * same caller composing a literal without the field beside a document that\n * carried one (`commands/subsystem/txn/views.ts`'s landscape-only fallback), so\n * documenting the hazard was measurably not enough: a caller with no edges must\n * now say `relationships: []` and mean it, and a caller holding a parsed\n * document passes the document.\n *\n * `globalStyles` stays optional because `LoadedDoc` declares it so and its\n * absence is not silent in the same way: a missing palette costs one `global\n * style` line, which the file-level disclosure comment then names.\n */\nexport type MapFacts = Pick<LoadedDoc, \"elements\" | \"relationships\" | \"globalStyles\">;\n\n/**\n * The header every generated file opens with — stable bytes, part of the\n * byte-compare contract, naming the regenerator so a reader who found the\n * file first knows what owns it.\n *\n * It OPENS with the shared `GENERATED_MARK` rather than spelling it, because\n * the same bytes are what `loam subsystem sync` reads back off disk to decide\n * whether the file standing at this reserved path is loam's to rewrite at all\n * (`./service/header.ts` carries the whole reason). A second literal here is\n * how a file loam wrote stops being recognised as loam's.\n */\nconst HEADER =\n  `${GENERATED_MARK} — the subsystem tree under services/, one view per subsystem.\\n` +\n  \"// Do not edit: `loam subsystem sync` regenerates this file from the directories,\\n\" +\n  \"// and `loam validate --all` reports `subsystem.views-stale` when it drifts.\\n\" +\n  \"// A scoping aid, not the fleet's architecture: author your own diagrams elsewhere.\\n\";\n\n/**\n * The one file-level comment the render may write: the map declares global\n * style groups, and none is the conventional one. Written between `HEADER`\n * and `views {` — outside every view body, graded by nothing — so a team\n * that already declared a palette under another name reads the fix in the\n * diff of the sync that regenerated the file, instead of wondering why the\n * generated views ignore it. Silent when the map declares no group at all: a\n * fleet with no palette is owed no sentence about one. Ids go unescaped\n * because LikeC4's grammar admits only identifier bytes in a style id.\n *\n * The group is a PARAMETER because there are two generated files now and each\n * reserves its own name (`subsystems`, `services`); a map declaring one and not\n * the other must get the sentence in exactly the file that went unstyled.\n */\nfunction stylesDisclosure(declared: readonly string[], group: string): string | null {\n  if (declared.length === 0 || declared.includes(group)) return null;\n  return (\n    `// styles: the project declares global style group(s) ${[...declared].sort().join(\", \")}, ` +\n    `and none named \\`${group}\\` — these views carry the renderer's defaults until one is.`\n  );\n}\n\n/**\n * Render the views file for a walked tree, or null when the tree has no\n * subsystems — the file must then be ABSENT, so a flat fleet never carries a\n * generated artifact that says nothing.\n */\nexport function renderSubsystemViews(tree: FleetTree, map: MapFacts): string | null {\n  if (tree.subsystems.length === 0) return null;\n  const ctx = renderContext(tree, map.elements);\n  const declared = map.globalStyles ?? [];\n  const styled = declared.includes(SUBSYSTEM_STYLE_GROUP);\n  const disclosure = stylesDisclosure(declared, SUBSYSTEM_STYLE_GROUP);\n  const lines: string[] = [HEADER, ...(disclosure === null ? [] : [disclosure]), \"views {\"];\n  const subsystems = [...tree.subsystems].sort((a, b) => (pathKey(a) < pathKey(b) ? -1 : 1));\n  for (const [i, sub] of subsystems.entries()) {\n    if (i > 0) lines.push(\"\");\n    lines.push(`  // services/${pathKey(sub)}`);\n    const body = viewBody(ctx, sub);\n    if (body.disclosure !== null) lines.push(`  // ${body.disclosure}`);\n    // `of <ancestor>` when — and only when — the map holds an element that owns\n    // exactly this subsystem's members (`../render/body.ts` argues the\n    // \"exactly\"). It is the same one keyword the per-service views spend, and it\n    // buys the same thing: LikeC4 computes `navigateTo` into this view from\n    // every other view that draws that element, so the fleet map's group boxes\n    // become click-through and a neighbouring group box inside one subsystem\n    // view opens THAT subsystem's view. Measured at 58 services in 11 groups,\n    // 12 of 14 nodes navigable. With no owning ancestor there is no element to\n    // be `of`, so there is no navigation — honest, and one more reason to nest\n    // the map that loam already discloses one line above.\n    lines.push(`  view ${subsystemViewId(sub)}${body.of === null ? \"\" : ` of ${body.of}`} {`);\n    // Metadata FIRST, and that ordering is a hard constraint rather than a\n    // taste: measured, an `include` OR a `group { … }` line followed by\n    // `title` is a parse error (\"Expecting token of type '}' but found\n    // `title`\"), and one parse error in this file blanks the whole\n    // `architecture/` project in the renderer.\n    lines.push(`    title '${viewTitle(titleChain(tree, sub.path))}'`);\n    const description = likec4String(sub.meta.description ?? \"\");\n    if (description !== \"\") lines.push(`    description '${description}'`);\n    // After the label, before anything that includes: measured at the pin\n    // (test/likec4-view-shape.test.ts), a `global style <id>` line here\n    // parses with zero errors, while the same line before `title` is the\n    // parse error the comment above records. The palette is the map's own —\n    // the group is declared in the same project this file renders into — so\n    // the reference resolves exactly when the presence test says it does.\n    if (styled) lines.push(`    global style ${SUBSYSTEM_STYLE_GROUP}`);\n    lines.push(...body.lines);\n    lines.push(\"  }\");\n  }\n  lines.push(\"}\");\n  return lines.join(\"\\n\") + \"\\n\";\n}\n\n/**\n * The GENERATED per-service overviews — `architecture/services.likec4`, one\n * view per service the map resolves. Null when it resolves none, so the file is\n * then absent exactly as `subsystems.likec4` is for a tree with no subsystems.\n *\n * This function is the composer and nothing else: `./service/` owns the view\n * shape and its measurements, and everything about the TREE is resolved here,\n * because that package may not import `./body.ts` or `./text.ts` (the edge runs\n * the other way — `./service/views.ts` says why) and duplicating either would\n * put a second element→service join and a second string escaper in the tree.\n *\n * Emission is gated on the SAME join the subsystem views use: a service the map\n * does not draw is omitted rather than invented, because that omission is\n * already `landscape.service-unmodelled` and rendering only what the committed\n * map resolves keeps the output a function of committed bytes alone.\n */\nexport function renderServiceOverviews(tree: FleetTree, map: MapFacts): string | null {\n  const ctx = renderContext(tree, map.elements);\n  const declared = map.globalStyles ?? [];\n  const subjects: ServiceViewSubject[] = [];\n  for (const service of tree.services) {\n    const fqn = ctx.elementOf.get(service.id);\n    if (fqn === undefined) continue;\n    subjects.push({ id: service.id, fqn, title: serviceViewTitle(tree, service.subsystem, service.id) });\n  }\n  return renderServiceViews({\n    subjects,\n    relationships: map.relationships,\n    styled: declared.includes(SERVICE_STYLE_GROUP),\n    disclosure: stylesDisclosure(declared, SERVICE_STYLE_GROUP),\n  });\n}\n\n/**\n * A per-service view's title: its subsystem path and then its own id, joined\n * with ` / ` — `Platform / order-flow / checkout-web`, or bare `checkout-web`\n * for a service filed directly under `services/`.\n *\n * LikeC4 reads that as a folder path (`./text.ts` measured it), so a service's\n * overview lands in the SAME browser folder as its subsystem's view rather than\n * in a flat list of fifty-eight titles — which is the whole readability answer\n * at fleet scale, and it costs the same helpers the subsystem views already use.\n *\n * The leaf is the service's `services/<id>/` DIRECTORY id and deliberately not\n * the map element's title: it is the name every loam command addresses the\n * service by, it cannot drift when somebody renames a box on the map, and a\n * directory name cannot contain `/`, so it needs no folder-separator\n * substitution of its own. It still goes through `likec4String` — an id is a\n * directory name, and a directory name is somebody else's word.\n */\nfunction serviceViewTitle(tree: FleetTree, subsystem: string[], id: string): string {\n  return [viewTitle(titleChain(tree, subsystem)), likec4String(id)].filter((part) => part !== \"\").join(\" / \");\n}\n\n/**\n * The MARKED subsystems along a path, outermost first — the chain `viewTitle`\n * composes a folder path out of, for a subsystem's own view and for the view of\n * a service filed beneath it alike.\n *\n * Marked, because an intermediate directory holding no `subsystem.yaml` is\n * `subsystem.unmarked`, an error the walk already names: it is not a group,\n * so it contributes no folder level here either. Read off the walked tree\n * rather than off the path segments, so what the title says and what the\n * finding says about the same directory cannot disagree.\n */\nfunction titleChain(tree: FleetTree, path: readonly string[]): SubsystemEntry[] {\n  return tree.subsystems\n    .filter((s) => s.path.length <= path.length && s.path.every((name, i) => path[i] === name))\n    .sort((a, b) => a.path.length - b.path.length);\n}\n\n/** The sort key and the comment spelling: the subsystem's path from services/, joined. */\nfunction pathKey(sub: SubsystemEntry): string {\n  return sub.path.join(\"/\");\n}\n\n/**\n * A LikeC4 identifier for the view, derived from the subsystem's path so\n * nesting reads in the name — and INJECTIVE over every path the name grammar\n * admits, because the renderer refuses the whole `architecture/` project over\n * a duplicate view id.\n *\n * The per-BYTE encoding, the collision it was written against, and the reason\n * segments join on `__` all live with the encoder in `./service/view-id.ts` —\n * which is also where the per-service ids are minted, so the two generated\n * files cannot drift into two spellings of the same escape. That module sits\n * BELOW this one on purpose: it is the leaf, and the import may only run\n * downward (`./service/views.ts`'s banner records the package direction).\n *\n * EXPORTED here still, with its prefix, because `subsystem.view-id-collision`\n * has to ask the generator what it mints rather than re-deriving it. A check\n * carrying its own copy of the escaping would go quiet the day the encoding\n * changed, and going quiet is the failure this whole family exists to prevent.\n */\nexport const SUBSYSTEM_VIEW_PREFIX = \"subsystem_\";\n\nexport function subsystemViewId(sub: SubsystemEntry): string {\n  return `${SUBSYSTEM_VIEW_PREFIX}${sub.path.map(escapeViewIdSegment).join(\"__\")}`;\n}\n\n/**\n * Does the file on disk already SAY what `renderSubsystemViews` renders?\n *\n * The generator above only ever emits LF. `core.autocrlf=true` is Git for\n * Windows' installer default and a docs repo ships no `.gitattributes`, so an\n * ordinary Windows clone hands the file back with CRLF and not one fact\n * changed. Four call sites asked this question with a byte equality and all\n * four answered \"stale\" on such a clone: `loam validate` reported an error,\n * `loam subsystem sync` reported `updated` and rewrote with LF, git then showed\n * the file permanently modified, and the next checkout restored the CRLF. That\n * is a loop rather than a diagnosis, which is why the comparison lives here\n * now — the module that mints the bytes is the one that owes an answer about\n * them, and three near-copies of this rule would go stale one at a time.\n *\n * Still never a parse: a views-only document does not parse standalone, and no\n * check anywhere reads this file's content. The narrowing is from BYTES to\n * CONTENT, which is what `subsystem.views-stale`'s own message (\"does not match\n * the tree\") already claims. The symmetric cost is accepted and is the one\n * `core/verify/pins/pin.ts` documents for `pinnedDigest`: a pure line-ending\n * change is invisible, correctly, because it is not a change to what the file\n * says.\n *\n * `null` is carried through as itself rather than collapsing into `\"\"`: absent,\n * must-be-absent and present-but-different are three distinct states with three\n * distinct messages, and a fleet whose views file does not exist is not a fleet\n * whose views file is blank.\n */\nexport function viewsAgree(actual: string | null, expected: string | null): boolean {\n  const lf = (text: string | null): string | null => (text === null ? null : text.replace(/\\r\\n|\\r/g, \"\\n\"));\n  return lf(actual) === lf(expected);\n}\n"]}

package/dist/core/repo/tree/walk.js

@@ -43,13 +43,12 @@
  * for the symlink-cycle guard — `entryIs` follows symlinks on purpose, and a
  * followed cycle without the visited-set is an unbounded recursion.
  */
-import { realpathSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { serviceDirOf, serviceTreePath } from "../../kernel/ids/dirs.js";
 import { rawServiceId } from "../../kernel/ids/service.js";
 import { subsystemNameProblem } from "../../kernel/ids/subsystem.js";
-import { entryIs } from "./fs.js";
+import { entryIs, markDescended, subdirNames } from "./fs.js";
 import { readSubsystemMarker, SUBSYSTEM_MARKER } from "./marker.js";
 /**
  * The subdirectory names SCHEMA's service layout reserves for a service's own
@@ -82,39 +81,13 @@ export async function walkServicesTree(request) {
         names: new Map(),
     };
     const root = join(request.docsDir, "services");
-    guardDescent(root, ctx);
+    markDescended(root, ctx.visited);
     for (const name of await subdirNames(root)) {
         await visitDir({ dir: join(root, name), name, chain: [] }, ctx);
     }
     namespaceFindings(ctx);
     return ctx.tree;
 }
-/**
- * Mark a directory as descended-into; false when it (or another name for it)
- * already was. Guards SUBTREES, not entries: a directory reachable under two
- * names is classified twice — both names exist and hiding the second would be
- * the silent shrink this module refuses — but its children are enumerated
- * once, so a symlink cycle terminates instead of recursing forever. A path
- * realpath cannot resolve is one whose children cannot be read either.
- */
-function guardDescent(dir, ctx) {
-    let real;
-    try {
-        real = realpathSync(dir);
-    }
-    catch {
-        return false;
-    }
-    if (ctx.visited.has(real))
-        return false;
-    ctx.visited.add(real);
-    return true;
-}
-/** Sorted non-dot subdirectory names — the walk's deterministic child order. */
-async function subdirNames(dir) {
-    const entries = await readdir(dir, { withFileTypes: true });
-    return entries.filter((e) => !e.name.startsWith(".") && entryIs(dir, e, "dir")).map((e) => e.name).sort();
-}
 /** Classify one directory and, for the group kinds, walk what is inside it. */
 async function visitDir(spot, ctx) {
     const rel = ["services", ...spot.chain, spot.name].join("/");
@@ -219,7 +192,12 @@ async function visitSubsystem(spot, at, ctx) {
  */
 async function descendInto(spot, dirs, ctx) {
     const before = ctx.tree.services.length;
-    if (guardDescent(spot.dir, ctx)) {
+    // The guard (`./fs.ts`'s `markDescended`) protects SUBTREES, not entries: a
+    // directory reachable under two names is classified twice — both names
+    // exist and hiding the second would be the silent shrink this module
+    // refuses — but its children are enumerated once, so a symlink cycle
+    // terminates instead of recursing forever.
+    if (markDescended(spot.dir, ctx.visited)) {
         for (const child of dirs) {
             await visitDir({ dir: join(spot.dir, child), name: child, chain: [...spot.chain, spot.name] }, ctx);
         }

package/dist/core/repo/tree/walk.js.map

@@ -1 +1 @@
-{"version":3,"file":"walk.js","sourceRoot":"","sources":["../../../../src/core/repo/tree/walk.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The tree read model: three-way classification of everything under\n * `services/`, in one walk.\n *\n * A directory holding `subsystem.yaml` is a SUBSYSTEM and is walked; one\n * holding any service artifact is a SERVICE and is not walked deeper — unless\n * a marker sits BESIDE the artifacts, where the walk descends anyway (the\n * marker says a group was here, and its members must not vanish); one holding\n * neither while containing subdirectories is an ERROR that still names every\n * service found beneath it. The third branch is the whole point:\n * two-way classification loses a service silently on an ordinary clean merge —\n * one branch deletes an emptied subsystem's marker while another moves a\n * service into it, and the group directory is then read as a service whose\n * real services vanish from the fleet with no finding. No directory under\n * `services/` may ever be reinterpreted as a different kind without saying so,\n * and the fleet is never reported smaller: the walk descends into the broken\n * group precisely so the stranded services stay enumerated and named.\n *\n * The package direction is `repo → repo/tree`, never back. That is why the\n * artifact-name question arrives INJECTED (`TreeWalkRequest.isServiceArtifact`\n * — `repo/paths.ts` owns the spellings and `repo/repo.ts` builds the request):\n * importing `paths.ts` from here while `repo.ts` delegates its enumeration to\n * this walk would close the exact package cycle `scripts/package-graph.mjs`\n * exists to refuse.\n *\n * A SERVICE'S OWN SUBDIRECTORIES ARE NEVER CLASSIFIED (`RESERVED_INTERIOR`).\n * That is a different question from `isServiceArtifact`, which asks whether a\n * name makes the directory holding it a service; this asks whether a child\n * directory may be READ as one at all, and the two answers diverged the moment\n * SCHEMA's service layout grew a slot the artifact table does not carry. A\n * `services/<svc>/` holding only the documented `usecases/` flow directory was\n * classified as a group: the walk descended, filed `usecases` as a service, and\n * one `loam validate --all` reported `subsystem.unmarked`,\n * `landscape.service-unmodelled` for `services/<svc>/usecases/` and\n * `landscape.binding-unknown` for the real service — three errors whose text\n * says the fleet is losing services, earned by following the instruction `loam\n * init` had just scaffolded (verification 2026-09-04). The names are SCHEMA's\n * service layout, and a directory named for one is service interior wherever it\n * sits, so no branch of the classification descends into one.\n *\n * Cost: exactly one readdir per directory walked, service directories included\n * (their own listing is what classifies them), plus one realpath per directory\n * for the symlink-cycle guard — `entryIs` follows symlinks on purpose, and a\n * followed cycle without the visited-set is an unbounded recursion.\n */\nimport { realpathSync } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { serviceDirOf, serviceTreePath, type DocsDir, type ServiceDir } from \"../../kernel/ids/dirs.js\";\nimport { rawServiceId, type RawServiceId } from \"../../kernel/ids/service.js\";\nimport { subsystemNameProblem } from \"../../kernel/ids/subsystem.js\";\nimport type { Finding } from \"../../vocabulary/report.js\";\nimport { entryIs } from \"./fs.js\";\nimport { readSubsystemMarker, SUBSYSTEM_MARKER, type SubsystemMeta } from \"./marker.js\";\n\n/**\n * The subdirectory names SCHEMA's service layout reserves for a service's own\n * interior (`SCHEMA.md`, \"services/<svc>/\"): `adrs/` the decisions, `usecases/`\n * the flows drawn over its containers, `ui/` the page-specs. A directory with\n * one of these names is never a service and never a subsystem — it is inside\n * one — so the walk neither classifies it nor counts it as a subdirectory that\n * makes its parent a group.\n *\n * Kept here rather than folded into `isServiceArtifact` because the two\n * questions are not the same one: `adrs/` answers both (it is an artifact AND\n * interior) and `usecases/` answers only this one today. Widening the injected\n * artifact table instead would also make a lone `usecases/` classify its parent\n * as a service by ARTIFACT, which hides a real service filed beside it — the\n * silent shrink this module refuses.\n *\n * Exported for the one other reader of this rule: `core/diff/base-state.ts`\n * classifies a base git ref's tree listing, which no walk can readdir, and its\n * banner already commits it to restating this module's branches rather than\n * inventing its own. It shares the SET for the reason it shares the artifact\n * table — a name respelled there is the drift both modules are written to\n * avoid.\n */\nexport const RESERVED_INTERIOR: ReadonlySet<string> = new Set([\"adrs\", \"usecases\", \"ui\"]);\n\nexport interface WalkedService {\n  id: RawServiceId;\n  dir: ServiceDir;\n  /**\n   * Names of the directories between `services/` and the service, outermost\n   * first. Empty = unfiled — directly under `services/`, which is permanent,\n   * normal and SILENT. For a service stranded under an unmarked group the\n   * chain still records the physical placement: the path is a fact even while\n   * `subsystem.unmarked` says the grouping is broken.\n   */\n  subsystem: string[];\n}\n\nexport interface SubsystemEntry {\n  /** The directory name — the subsystem's name in the flat namespace. */\n  name: string;\n  /** Names from `services/` down to and including this one. */\n  path: string[];\n  /** Absolute path of the subsystem directory. */\n  dir: string;\n  meta: SubsystemMeta;\n}\n\nexport interface FleetTree {\n  services: WalkedService[];\n  subsystems: SubsystemEntry[];\n  findings: Finding[];\n}\n\nexport interface TreeWalkRequest {\n  docsDir: DocsDir;\n  /** Does this entry name a service artifact? `repo/paths.ts`'s table, injected — the module doc says why. */\n  isServiceArtifact: (name: string, kind: \"file\" | \"dir\") => boolean;\n}\n\ninterface WalkContext {\n  request: TreeWalkRequest;\n  tree: FleetTree;\n  /** Realpaths already DESCENDED into — the symlink-cycle guard. */\n  visited: Set<string>;\n  /** Every name in the flat namespace → the directories that claim it. */\n  names: Map<string, string[]>;\n}\n\n/** One directory the walk is looking at: where it is, and how it is reached. */\ninterface Spot {\n  dir: string;\n  name: string;\n  /** Directory names between `services/` and this one, outermost first. */\n  chain: string[];\n}\n\nexport async function walkServicesTree(request: TreeWalkRequest): Promise<FleetTree> {\n  const ctx: WalkContext = {\n    request,\n    tree: { services: [], subsystems: [], findings: [] },\n    visited: new Set(),\n    names: new Map(),\n  };\n  const root = join(request.docsDir, \"services\");\n  guardDescent(root, ctx);\n  for (const name of await subdirNames(root)) {\n    await visitDir({ dir: join(root, name), name, chain: [] }, ctx);\n  }\n  namespaceFindings(ctx);\n  return ctx.tree;\n}\n\n/**\n * Mark a directory as descended-into; false when it (or another name for it)\n * already was. Guards SUBTREES, not entries: a directory reachable under two\n * names is classified twice — both names exist and hiding the second would be\n * the silent shrink this module refuses — but its children are enumerated\n * once, so a symlink cycle terminates instead of recursing forever. A path\n * realpath cannot resolve is one whose children cannot be read either.\n */\nfunction guardDescent(dir: string, ctx: WalkContext): boolean {\n  let real: string;\n  try {\n    real = realpathSync(dir);\n  } catch {\n    return false;\n  }\n  if (ctx.visited.has(real)) return false;\n  ctx.visited.add(real);\n  return true;\n}\n\n/** Sorted non-dot subdirectory names — the walk's deterministic child order. */\nasync function subdirNames(dir: string): Promise<string[]> {\n  const entries = await readdir(dir, { withFileTypes: true });\n  return entries.filter((e) => !e.name.startsWith(\".\") && entryIs(dir, e, \"dir\")).map((e) => e.name).sort();\n}\n\n/** Classify one directory and, for the group kinds, walk what is inside it. */\nasync function visitDir(spot: Spot, ctx: WalkContext): Promise<void> {\n  const rel = [\"services\", ...spot.chain, spot.name].join(\"/\");\n  const entries = (await readdir(spot.dir, { withFileTypes: true })).filter((e) => !e.name.startsWith(\".\"));\n  const files = entries.filter((e) => entryIs(spot.dir, e, \"file\")).map((e) => e.name);\n  const all = entries.filter((e) => entryIs(spot.dir, e, \"dir\")).map((e) => e.name).sort();\n  // The classifiable children — a service's own interior removed once, here, so\n  // every branch below agrees about it (see `RESERVED_INTERIOR`). `all` is still\n  // what the artifact probe reads: `adrs/` makes its parent a service, and\n  // `usecases/` is interior the parent may hold without becoming a group.\n  const dirs = all.filter((d) => !RESERVED_INTERIOR.has(d));\n  const marker = files.includes(SUBSYSTEM_MARKER);\n  const artifact =\n    files.some((f) => ctx.request.isServiceArtifact(f, \"file\")) ||\n    all.some((d) => ctx.request.isServiceArtifact(d, \"dir\"));\n\n  if (marker && artifact) {\n    // Artifacts win the classification: the documents are somebody's work and\n    // the marker is one stray file, so the directory stays an addressable\n    // service and the finding names the contradiction instead of the walk\n    // quietly picking a reading. But the walk STILL descends (the module\n    // invariant: no reinterpretation may shrink the fleet) — the marker says\n    // a GROUP was here, and returning without walking made every service\n    // beneath it vanish with only this finding to hint why. Child directories\n    // that are themselves artifacts (`adrs/`) are service interior, not walked.\n    recordService(spot, ctx);\n    const stranded = await descendInto(spot, dirs.filter((d) => !ctx.request.isServiceArtifact(d, \"dir\")), ctx);\n    ctx.tree.findings.push({\n      severity: \"error\",\n      code: \"subsystem.marker-misplaced\",\n      subject: spot.name,\n      message:\n        `${rel}/ holds ${SUBSYSTEM_MARKER} BESIDE service artifacts — a directory is a subsystem or a service, never both. ` +\n        `It stays classified as a service; delete ${rel}/${SUBSYSTEM_MARKER}, ` +\n        `or move the artifacts into a service directory of their own inside the group.` +\n        (stranded.length > 0 ? ` ${stranded.length} service(s) beneath it stay enumerated meanwhile: ${stranded.map((s) => s.id).join(\", \")}.` : \"\"),\n      ...(stranded.length > 0 ? { details: stranded.map(serviceTreePath) } : {}),\n    });\n    return;\n  }\n  if (marker) {\n    await visitSubsystem(spot, { rel, dirs }, ctx);\n    return;\n  }\n  if (artifact) {\n    recordService(spot, ctx);\n    return;\n  }\n  if (dirs.length > 0) {\n    await visitUnmarked(spot, { rel, dirs }, ctx);\n    return;\n  }\n  // Neither marker nor artifact, and nothing beneath: today's flat behaviour —\n  // an empty (or not-yet-adopted) directory under services/ is a service.\n  recordService(spot, ctx);\n}\n\nfunction recordService(spot: Spot, ctx: WalkContext): void {\n  ctx.tree.services.push({\n    id: rawServiceId(spot.name),\n    dir: serviceDirOf(spot.dir),\n    subsystem: spot.chain,\n  });\n  claimName(spot, ctx);\n}\n\n/** A subsystem: record it, report a broken marker or an illegal name, walk in. */\nasync function visitSubsystem(spot: Spot, at: { rel: string; dirs: string[] }, ctx: WalkContext): Promise<void> {\n  const meta = await readSubsystemMarker(join(spot.dir, SUBSYSTEM_MARKER));\n  if (meta.invalid !== undefined) {\n    // Exactly one finding per marker file: presence already classified the\n    // directory, so the content failure is metadata, not identity.\n    ctx.tree.findings.push({\n      severity: \"error\",\n      code: \"subsystem.invalid\",\n      subject: at.rel,\n      message:\n        `${at.rel}/${SUBSYSTEM_MARKER} cannot be read as subsystem metadata — ${meta.invalid}. ` +\n        `The directory still counts as a subsystem (presence classifies; content is metadata). ` +\n        `Fix the file: a YAML mapping with optional title, description and owner — an empty file is also a valid marker.`,\n    });\n  }\n  const problem = subsystemNameProblem(spot.name, \"subsystem directory name\");\n  if (problem !== null) {\n    // Walked anyway, mirroring how an illegal service id stays enumerated\n    // (`idProblem`): the directory exists and hiding its subtree would shrink\n    // the fleet over a naming mistake.\n    ctx.tree.findings.push({\n      severity: \"error\",\n      code: \"subsystem.name-invalid\",\n      subject: spot.name,\n      message: `${at.rel}/ — ${problem} Rename the directory; its services stay enumerated meanwhile.`,\n    });\n  }\n  ctx.tree.subsystems.push({\n    name: spot.name,\n    path: [...spot.chain, spot.name],\n    dir: spot.dir,\n    meta,\n  });\n  claimName(spot, ctx);\n  await descendInto(spot, at.dirs, ctx);\n}\n\n/**\n * Walk the children of a group directory (symlink-cycle guarded), returning\n * the services newly recorded beneath it — the ONE spelling of descent, so\n * the three descending branches agree about the guard and the chain.\n */\nasync function descendInto(spot: Spot, dirs: string[], ctx: WalkContext): Promise<WalkedService[]> {\n  const before = ctx.tree.services.length;\n  if (guardDescent(spot.dir, ctx)) {\n    for (const child of dirs) {\n      await visitDir({ dir: join(spot.dir, child), name: child, chain: [...spot.chain, spot.name] }, ctx);\n    }\n  }\n  return ctx.tree.services.slice(before);\n}\n\n/**\n * The refusal branch — a group directory nothing marks. The walk STILL\n * descends, so the services beneath stay in the enumeration and the finding\n * can name them: the fleet must never be reported smaller than it is.\n */\nasync function visitUnmarked(spot: Spot, at: { rel: string; dirs: string[] }, ctx: WalkContext): Promise<void> {\n  const stranded = await descendInto(spot, at.dirs, ctx);\n  ctx.tree.findings.push({\n    severity: \"error\",\n    code: \"subsystem.unmarked\",\n    subject: at.rel,\n    message:\n      `${at.rel}/ is neither a subsystem (no ${SUBSYSTEM_MARKER}) nor a service (no service artifact), ` +\n      `but ${stranded.length} service(s) sit beneath it` +\n      (stranded.length > 0 ? `: ${stranded.map((s) => s.id).join(\", \")}. ` : `. `) +\n      `Without the marker this directory would be read as a service and everything under it would vanish from the fleet — ` +\n      `the shape an ordinary merge produces when one branch deletes an emptied subsystem's marker while another moves a service in. ` +\n      `Restore ${at.rel}/${SUBSYSTEM_MARKER} (an empty file is a valid marker), or move the directories out.`,\n    ...(stranded.length > 0 ? { details: stranded.map(serviceTreePath) } : {}),\n  });\n}\n\nfunction claimName(spot: Spot, ctx: WalkContext): void {\n  const rel = [\"services\", ...spot.chain, spot.name].join(\"/\");\n  ctx.names.set(spot.name, [...(ctx.names.get(spot.name) ?? []), rel]);\n}\n\n/**\n * One flat namespace: every subsystem name and service id, unique across the\n * whole tree at any depth, never colliding with each other. The identity\n * decision demands it — a service id is its leaf directory name ALONE, so two\n * leaves spelling one name are one identity claimed twice, wherever they sit.\n * One finding per name, naming every claimant, so the fix is a choice rather\n * than a scavenger hunt.\n */\nfunction namespaceFindings(ctx: WalkContext): void {\n  for (const [name, dirs] of [...ctx.names].sort(([a], [b]) => (a < b ? -1 : 1))) {\n    if (dirs.length < 2) continue;\n    ctx.tree.findings.push({\n      severity: \"error\",\n      code: \"subsystem.name-collision\",\n      subject: name,\n      message:\n        `'${name}' is claimed by ${dirs.length} directories in the services/ tree: ${dirs.join(\", \")} — ` +\n        `service ids and subsystem names share one flat namespace, unique at any depth, ` +\n        `because a service's identity is its leaf directory name alone and placement never disambiguates it. ` +\n        `Rename all but one.`,\n      details: dirs,\n    });\n  }\n}\n"]}
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../../../../src/core/repo/tree/walk.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The tree read model: three-way classification of everything under\n * `services/`, in one walk.\n *\n * A directory holding `subsystem.yaml` is a SUBSYSTEM and is walked; one\n * holding any service artifact is a SERVICE and is not walked deeper — unless\n * a marker sits BESIDE the artifacts, where the walk descends anyway (the\n * marker says a group was here, and its members must not vanish); one holding\n * neither while containing subdirectories is an ERROR that still names every\n * service found beneath it. The third branch is the whole point:\n * two-way classification loses a service silently on an ordinary clean merge —\n * one branch deletes an emptied subsystem's marker while another moves a\n * service into it, and the group directory is then read as a service whose\n * real services vanish from the fleet with no finding. No directory under\n * `services/` may ever be reinterpreted as a different kind without saying so,\n * and the fleet is never reported smaller: the walk descends into the broken\n * group precisely so the stranded services stay enumerated and named.\n *\n * The package direction is `repo → repo/tree`, never back. That is why the\n * artifact-name question arrives INJECTED (`TreeWalkRequest.isServiceArtifact`\n * — `repo/paths.ts` owns the spellings and `repo/repo.ts` builds the request):\n * importing `paths.ts` from here while `repo.ts` delegates its enumeration to\n * this walk would close the exact package cycle `scripts/package-graph.mjs`\n * exists to refuse.\n *\n * A SERVICE'S OWN SUBDIRECTORIES ARE NEVER CLASSIFIED (`RESERVED_INTERIOR`).\n * That is a different question from `isServiceArtifact`, which asks whether a\n * name makes the directory holding it a service; this asks whether a child\n * directory may be READ as one at all, and the two answers diverged the moment\n * SCHEMA's service layout grew a slot the artifact table does not carry. A\n * `services/<svc>/` holding only the documented `usecases/` flow directory was\n * classified as a group: the walk descended, filed `usecases` as a service, and\n * one `loam validate --all` reported `subsystem.unmarked`,\n * `landscape.service-unmodelled` for `services/<svc>/usecases/` and\n * `landscape.binding-unknown` for the real service — three errors whose text\n * says the fleet is losing services, earned by following the instruction `loam\n * init` had just scaffolded (verification 2026-09-04). The names are SCHEMA's\n * service layout, and a directory named for one is service interior wherever it\n * sits, so no branch of the classification descends into one.\n *\n * Cost: exactly one readdir per directory walked, service directories included\n * (their own listing is what classifies them), plus one realpath per directory\n * for the symlink-cycle guard — `entryIs` follows symlinks on purpose, and a\n * followed cycle without the visited-set is an unbounded recursion.\n */\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { serviceDirOf, serviceTreePath, type DocsDir, type ServiceDir } from \"../../kernel/ids/dirs.js\";\nimport { rawServiceId, type RawServiceId } from \"../../kernel/ids/service.js\";\nimport { subsystemNameProblem } from \"../../kernel/ids/subsystem.js\";\nimport type { Finding } from \"../../vocabulary/report.js\";\nimport { entryIs, markDescended, subdirNames } from \"./fs.js\";\nimport { readSubsystemMarker, SUBSYSTEM_MARKER, type SubsystemMeta } from \"./marker.js\";\n\n/**\n * The subdirectory names SCHEMA's service layout reserves for a service's own\n * interior (`SCHEMA.md`, \"services/<svc>/\"): `adrs/` the decisions, `usecases/`\n * the flows drawn over its containers, `ui/` the page-specs. A directory with\n * one of these names is never a service and never a subsystem — it is inside\n * one — so the walk neither classifies it nor counts it as a subdirectory that\n * makes its parent a group.\n *\n * Kept here rather than folded into `isServiceArtifact` because the two\n * questions are not the same one: `adrs/` answers both (it is an artifact AND\n * interior) and `usecases/` answers only this one today. Widening the injected\n * artifact table instead would also make a lone `usecases/` classify its parent\n * as a service by ARTIFACT, which hides a real service filed beside it — the\n * silent shrink this module refuses.\n *\n * Exported for the one other reader of this rule: `core/diff/base-state.ts`\n * classifies a base git ref's tree listing, which no walk can readdir, and its\n * banner already commits it to restating this module's branches rather than\n * inventing its own. It shares the SET for the reason it shares the artifact\n * table — a name respelled there is the drift both modules are written to\n * avoid.\n */\nexport const RESERVED_INTERIOR: ReadonlySet<string> = new Set([\"adrs\", \"usecases\", \"ui\"]);\n\nexport interface WalkedService {\n  id: RawServiceId;\n  dir: ServiceDir;\n  /**\n   * Names of the directories between `services/` and the service, outermost\n   * first. Empty = unfiled — directly under `services/`, which is permanent,\n   * normal and SILENT. For a service stranded under an unmarked group the\n   * chain still records the physical placement: the path is a fact even while\n   * `subsystem.unmarked` says the grouping is broken.\n   */\n  subsystem: string[];\n}\n\nexport interface SubsystemEntry {\n  /** The directory name — the subsystem's name in the flat namespace. */\n  name: string;\n  /** Names from `services/` down to and including this one. */\n  path: string[];\n  /** Absolute path of the subsystem directory. */\n  dir: string;\n  meta: SubsystemMeta;\n}\n\nexport interface FleetTree {\n  services: WalkedService[];\n  subsystems: SubsystemEntry[];\n  findings: Finding[];\n}\n\nexport interface TreeWalkRequest {\n  docsDir: DocsDir;\n  /** Does this entry name a service artifact? `repo/paths.ts`'s table, injected — the module doc says why. */\n  isServiceArtifact: (name: string, kind: \"file\" | \"dir\") => boolean;\n}\n\ninterface WalkContext {\n  request: TreeWalkRequest;\n  tree: FleetTree;\n  /** Realpaths already DESCENDED into — the symlink-cycle guard. */\n  visited: Set<string>;\n  /** Every name in the flat namespace → the directories that claim it. */\n  names: Map<string, string[]>;\n}\n\n/** One directory the walk is looking at: where it is, and how it is reached. */\ninterface Spot {\n  dir: string;\n  name: string;\n  /** Directory names between `services/` and this one, outermost first. */\n  chain: string[];\n}\n\nexport async function walkServicesTree(request: TreeWalkRequest): Promise<FleetTree> {\n  const ctx: WalkContext = {\n    request,\n    tree: { services: [], subsystems: [], findings: [] },\n    visited: new Set(),\n    names: new Map(),\n  };\n  const root = join(request.docsDir, \"services\");\n  markDescended(root, ctx.visited);\n  for (const name of await subdirNames(root)) {\n    await visitDir({ dir: join(root, name), name, chain: [] }, ctx);\n  }\n  namespaceFindings(ctx);\n  return ctx.tree;\n}\n\n/** Classify one directory and, for the group kinds, walk what is inside it. */\nasync function visitDir(spot: Spot, ctx: WalkContext): Promise<void> {\n  const rel = [\"services\", ...spot.chain, spot.name].join(\"/\");\n  const entries = (await readdir(spot.dir, { withFileTypes: true })).filter((e) => !e.name.startsWith(\".\"));\n  const files = entries.filter((e) => entryIs(spot.dir, e, \"file\")).map((e) => e.name);\n  const all = entries.filter((e) => entryIs(spot.dir, e, \"dir\")).map((e) => e.name).sort();\n  // The classifiable children — a service's own interior removed once, here, so\n  // every branch below agrees about it (see `RESERVED_INTERIOR`). `all` is still\n  // what the artifact probe reads: `adrs/` makes its parent a service, and\n  // `usecases/` is interior the parent may hold without becoming a group.\n  const dirs = all.filter((d) => !RESERVED_INTERIOR.has(d));\n  const marker = files.includes(SUBSYSTEM_MARKER);\n  const artifact =\n    files.some((f) => ctx.request.isServiceArtifact(f, \"file\")) ||\n    all.some((d) => ctx.request.isServiceArtifact(d, \"dir\"));\n\n  if (marker && artifact) {\n    // Artifacts win the classification: the documents are somebody's work and\n    // the marker is one stray file, so the directory stays an addressable\n    // service and the finding names the contradiction instead of the walk\n    // quietly picking a reading. But the walk STILL descends (the module\n    // invariant: no reinterpretation may shrink the fleet) — the marker says\n    // a GROUP was here, and returning without walking made every service\n    // beneath it vanish with only this finding to hint why. Child directories\n    // that are themselves artifacts (`adrs/`) are service interior, not walked.\n    recordService(spot, ctx);\n    const stranded = await descendInto(spot, dirs.filter((d) => !ctx.request.isServiceArtifact(d, \"dir\")), ctx);\n    ctx.tree.findings.push({\n      severity: \"error\",\n      code: \"subsystem.marker-misplaced\",\n      subject: spot.name,\n      message:\n        `${rel}/ holds ${SUBSYSTEM_MARKER} BESIDE service artifacts — a directory is a subsystem or a service, never both. ` +\n        `It stays classified as a service; delete ${rel}/${SUBSYSTEM_MARKER}, ` +\n        `or move the artifacts into a service directory of their own inside the group.` +\n        (stranded.length > 0 ? ` ${stranded.length} service(s) beneath it stay enumerated meanwhile: ${stranded.map((s) => s.id).join(\", \")}.` : \"\"),\n      ...(stranded.length > 0 ? { details: stranded.map(serviceTreePath) } : {}),\n    });\n    return;\n  }\n  if (marker) {\n    await visitSubsystem(spot, { rel, dirs }, ctx);\n    return;\n  }\n  if (artifact) {\n    recordService(spot, ctx);\n    return;\n  }\n  if (dirs.length > 0) {\n    await visitUnmarked(spot, { rel, dirs }, ctx);\n    return;\n  }\n  // Neither marker nor artifact, and nothing beneath: today's flat behaviour —\n  // an empty (or not-yet-adopted) directory under services/ is a service.\n  recordService(spot, ctx);\n}\n\nfunction recordService(spot: Spot, ctx: WalkContext): void {\n  ctx.tree.services.push({\n    id: rawServiceId(spot.name),\n    dir: serviceDirOf(spot.dir),\n    subsystem: spot.chain,\n  });\n  claimName(spot, ctx);\n}\n\n/** A subsystem: record it, report a broken marker or an illegal name, walk in. */\nasync function visitSubsystem(spot: Spot, at: { rel: string; dirs: string[] }, ctx: WalkContext): Promise<void> {\n  const meta = await readSubsystemMarker(join(spot.dir, SUBSYSTEM_MARKER));\n  if (meta.invalid !== undefined) {\n    // Exactly one finding per marker file: presence already classified the\n    // directory, so the content failure is metadata, not identity.\n    ctx.tree.findings.push({\n      severity: \"error\",\n      code: \"subsystem.invalid\",\n      subject: at.rel,\n      message:\n        `${at.rel}/${SUBSYSTEM_MARKER} cannot be read as subsystem metadata — ${meta.invalid}. ` +\n        `The directory still counts as a subsystem (presence classifies; content is metadata). ` +\n        `Fix the file: a YAML mapping with optional title, description and owner — an empty file is also a valid marker.`,\n    });\n  }\n  const problem = subsystemNameProblem(spot.name, \"subsystem directory name\");\n  if (problem !== null) {\n    // Walked anyway, mirroring how an illegal service id stays enumerated\n    // (`idProblem`): the directory exists and hiding its subtree would shrink\n    // the fleet over a naming mistake.\n    ctx.tree.findings.push({\n      severity: \"error\",\n      code: \"subsystem.name-invalid\",\n      subject: spot.name,\n      message: `${at.rel}/ — ${problem} Rename the directory; its services stay enumerated meanwhile.`,\n    });\n  }\n  ctx.tree.subsystems.push({\n    name: spot.name,\n    path: [...spot.chain, spot.name],\n    dir: spot.dir,\n    meta,\n  });\n  claimName(spot, ctx);\n  await descendInto(spot, at.dirs, ctx);\n}\n\n/**\n * Walk the children of a group directory (symlink-cycle guarded), returning\n * the services newly recorded beneath it — the ONE spelling of descent, so\n * the three descending branches agree about the guard and the chain.\n */\nasync function descendInto(spot: Spot, dirs: string[], ctx: WalkContext): Promise<WalkedService[]> {\n  const before = ctx.tree.services.length;\n  // The guard (`./fs.ts`'s `markDescended`) protects SUBTREES, not entries: a\n  // directory reachable under two names is classified twice — both names\n  // exist and hiding the second would be the silent shrink this module\n  // refuses — but its children are enumerated once, so a symlink cycle\n  // terminates instead of recursing forever.\n  if (markDescended(spot.dir, ctx.visited)) {\n    for (const child of dirs) {\n      await visitDir({ dir: join(spot.dir, child), name: child, chain: [...spot.chain, spot.name] }, ctx);\n    }\n  }\n  return ctx.tree.services.slice(before);\n}\n\n/**\n * The refusal branch — a group directory nothing marks. The walk STILL\n * descends, so the services beneath stay in the enumeration and the finding\n * can name them: the fleet must never be reported smaller than it is.\n */\nasync function visitUnmarked(spot: Spot, at: { rel: string; dirs: string[] }, ctx: WalkContext): Promise<void> {\n  const stranded = await descendInto(spot, at.dirs, ctx);\n  ctx.tree.findings.push({\n    severity: \"error\",\n    code: \"subsystem.unmarked\",\n    subject: at.rel,\n    message:\n      `${at.rel}/ is neither a subsystem (no ${SUBSYSTEM_MARKER}) nor a service (no service artifact), ` +\n      `but ${stranded.length} service(s) sit beneath it` +\n      (stranded.length > 0 ? `: ${stranded.map((s) => s.id).join(\", \")}. ` : `. `) +\n      `Without the marker this directory would be read as a service and everything under it would vanish from the fleet — ` +\n      `the shape an ordinary merge produces when one branch deletes an emptied subsystem's marker while another moves a service in. ` +\n      `Restore ${at.rel}/${SUBSYSTEM_MARKER} (an empty file is a valid marker), or move the directories out.`,\n    ...(stranded.length > 0 ? { details: stranded.map(serviceTreePath) } : {}),\n  });\n}\n\nfunction claimName(spot: Spot, ctx: WalkContext): void {\n  const rel = [\"services\", ...spot.chain, spot.name].join(\"/\");\n  ctx.names.set(spot.name, [...(ctx.names.get(spot.name) ?? []), rel]);\n}\n\n/**\n * One flat namespace: every subsystem name and service id, unique across the\n * whole tree at any depth, never colliding with each other. The identity\n * decision demands it — a service id is its leaf directory name ALONE, so two\n * leaves spelling one name are one identity claimed twice, wherever they sit.\n * One finding per name, naming every claimant, so the fix is a choice rather\n * than a scavenger hunt.\n */\nfunction namespaceFindings(ctx: WalkContext): void {\n  for (const [name, dirs] of [...ctx.names].sort(([a], [b]) => (a < b ? -1 : 1))) {\n    if (dirs.length < 2) continue;\n    ctx.tree.findings.push({\n      severity: \"error\",\n      code: \"subsystem.name-collision\",\n      subject: name,\n      message:\n        `'${name}' is claimed by ${dirs.length} directories in the services/ tree: ${dirs.join(\", \")} — ` +\n        `service ids and subsystem names share one flat namespace, unique at any depth, ` +\n        `because a service's identity is its leaf directory name alone and placement never disambiguates it. ` +\n        `Rename all but one.`,\n      details: dirs,\n    });\n  }\n}\n"]}