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

package/dist/core/repo/repo.js

@@ -7,14 +7,14 @@
  * a repo to walk at all in `state.ts`.
  */
 import { existsSync } from "node:fs";
-import { readdir } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { listField, readFrontmatter, stringField } from "../document/frontmatter.js";
+import { contentStamp, listField, movedUnderVouch, readFrontmatter, stringField, } from "../document/frontmatter.js";
 import { featureDirOf } from "../kernel/ids/dirs.js";
 import { rawServiceId, serviceIdProblem } from "../kernel/ids/service.js";
 import { readVouchScope } from "../provenance/sample/scope.js";
 import { compareIds, featureIdFromDirName } from "./entries.js";
-import { ARCHIVE_DIR, featurePaths, featuresDir, fleetAdrsDir, isServiceArtifactName, servicePathsAt } from "./paths.js";
+import { ARCHIVE_DIR, featurePaths, featuresDir, fleetAdrsDir, isServiceArtifactName, servicePathsAt, SPEC_AXES, } from "./paths.js";
 import { requireDocsRepo } from "./state.js";
 import { countMarkdown, entryIs } from "./tree/fs.js";
 import { walkServicesTree } from "./tree/walk.js";
@@ -93,6 +93,33 @@ async function archHeader(path) {
         return { present: false, malformed: false, data: {}, body: "" };
     }
 }
+/**
+ * The spec files whose body moved under their vouch — `content.stale`'s
+ * question, asked through the one predicate `loam validate` grades with
+ * (`movedUnderVouch`) so the fleet listing and the finding cannot disagree
+ * about one file. Only a header that carries a stamp (`contentStamp`) costs the
+ * second read: the frontmatter read already answered whether there is anything
+ * to compare, and on a fleet mid-adoption most headers do not. The body is
+ * read exactly as the finding reads it, as UTF-8 text, because the stamp is
+ * byte-exact.
+ */
+async function filesMovedUnderVouch(axes) {
+    const moved = await Promise.all(axes.map(async ({ file, path, header }) => contentStamp(header) !== undefined && movedUnderVouch(header, await readFile(path, "utf8")) ? [file] : []));
+    return moved.flat();
+}
+/**
+ * `ServiceEntry.adoption`, read off one living spec.md's frontmatter — the one
+ * spelling of the marker's test, for the enumeration below and for the adopt
+ * brief, which must not call a partial adoption finished. Any value but
+ * `partial` reads as absent (SCHEMA.md).
+ */
+export function adoptionOf(fm) {
+    return stringField(fm, "adoption") === "partial" ? "partial" : null;
+}
+/** `adoptionOf` for a spec.md by path; an absent file is no marker. */
+export async function specAdoption(specPath) {
+    return adoptionOf(await readFrontmatter(specPath));
+}
 export async function serviceEntries(tree) {
     const entries = await Promise.all(tree.services.map(async (svc) => {
         const p = servicePathsAt(svc.dir);
@@ -103,6 +130,7 @@ export async function serviceEntries(tree) {
         // sampled. `readFrontmatter` answers "absent" for a file that is not
         // there, so a service without the second axis pays one existsSync.
         const [fm, archFm] = await Promise.all([readFrontmatter(p.spec), archHeader(p.archSpec)]);
+        const headers = { spec: fm, archSpec: archFm };
         const idProblem = serviceIdProblem(svc.id, "directory name");
         return {
             id: svc.id,
@@ -119,6 +147,7 @@ export async function serviceEntries(tree) {
             },
             adrs: await countMarkdown(p.adrsDir),
             status: stringField(fm, "status") ?? null,
+            adoption: adoptionOf(fm),
             sources: {
                 declared: listField(fm, "sources").length > 0,
                 stamped: stringField(fm, "sources_digest") !== undefined,
@@ -129,6 +158,10 @@ export async function serviceEntries(tree) {
             // listing is the last place a mangled field should be able to buy
             // itself a full-trust row.
             vouchScope: [fm, archFm].some((header) => readVouchScope(header).kind !== "none") ? "sampled" : null,
+            // Both axes again, for the scope's reason: a stamp is per FILE, and an
+            // arch.spec.md edited under its vouch is a service part of whose
+            // documentation nobody has re-read.
+            contentStale: await filesMovedUnderVouch(SPEC_AXES.map((axis) => ({ file: axis.file, path: p[axis.key], header: headers[axis.key] }))),
         };
     }));
     return entries.sort((a, b) => compareIds(a.id, b.id) || compareIds(a.dir, b.dir));
@@ -148,6 +181,42 @@ export async function serviceEntries(tree) {
 export async function fleetAdrCount(docsDir) {
     return countMarkdown(fleetAdrsDir(docsDir));
 }
+/**
+ * What a feature is CALLED, for a person: intent.md's `title:`, else its first
+ * `# ` heading with the feature id peeled off the front, else null.
+ *
+ * Every row that names a feature used to print the id alone, and an id is a
+ * key, not a name — a newcomer looking at `ready  FEAT-101` could not tell
+ * which change it was without opening the directory. Read on demand rather
+ * than carried on `FeatureEntry`, because the enumeration runs under every
+ * command and only the views a person reads need the words. A missing or
+ * unreadable intent.md is simply no title: the row still prints its id, and
+ * whether intent.md is owed is `status`'s question, not this one's.
+ */
+export async function featureTitle(feature) {
+    let fm;
+    try {
+        fm = await readFrontmatter(featurePaths(feature.dir).intent);
+    }
+    catch {
+        // A directory in intent.md's place, a permission: unreadable is no title.
+        // `readFrontmatter` folds only the encoding failure into a flag, and before
+        // this read the views that print a title never opened intent.md at all —
+        // so letting the error escape would hand `loam status` and `loam list`
+        // whole to `repository-unavailable` over a label. Whether intent.md is
+        // fine is the intent row's and `validate`'s question.
+        return null;
+    }
+    const declared = stringField(fm, "title")?.trim();
+    if (declared !== undefined && declared !== "")
+        return declared;
+    const heading = fm.body.split(/\r?\n/).find((l) => l.startsWith("# "));
+    if (heading === undefined)
+        return null;
+    const words = heading.slice(2).trim();
+    const bare = words.startsWith(feature.id) ? words.slice(feature.id.length).replace(/^[\s:—–-]+/, "") : words;
+    return bare === "" ? null : bare;
+}
 async function readFeature(dir, dirName, archived) {
     const p = featurePaths(dir);
     return {
@@ -201,7 +270,8 @@ export async function listFeatures(docsDir, opts = {}, context) {
  * directory over `FEAT-5-slug`, whose id is also `FEAT-5`), and under "include"
  * an active feature wins over an archived one. Ties among equally-exact
  * candidates go to the first by name — deterministic, unlike the raw readdir
- * order this replaces; `ambiguousFeatureMessage` lists them for the caller.
+ * order this replaces; `featureCandidates` returns every one of them, for a
+ * caller that must see the tie (`loam status` names the colliding directories).
  */
 export async function resolveFeature(docsDir, arg, archived, context) {
     return (await featureCandidates(docsDir, arg, archived, context))[0] ?? null;
@@ -220,16 +290,6 @@ export async function featureCandidates(docsDir, arg, archived, context) {
         Number(a.archived) - Number(b.archived) ||
         compareIds(a.dirName, b.dirName));
 }
-/**
- * The message for an argument that names more than one feature — two directories
- * carrying the same id (`FEAT-6-aaa` and `FEAT-6-zzz`). `resolveFeature` still
- * picks one deterministically, but a command that is about to WRITE should say
- * which directories collided and make the caller spell one out.
- */
-export function ambiguousFeatureMessage(arg, candidates) {
-    return (`'${arg}' names ${candidates.length} features: ${candidates.map((c) => c.dirName).join(", ")}. ` +
-        "Pass the directory name you mean.");
-}
 /**
  * The message for an exclude-mode miss. When the feature exists under
  * `features/archive/`, "no feature" is a lie the caller would have to debug —

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

@@ -1 +1 @@
-{"version":3,"file":"repo.js","sourceRoot":"","sources":["../../../src/core/repo/repo.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Read model of the docs repo — enumeration, and only by the filesystem.\n *\n * Files are the source of truth, so `services/` IS the list of services and\n * there is no manifest that can disagree with it. The shapes this hands back\n * live in `entries.ts`, the layout it walks in `paths.ts`, and whether there is\n * a repo to walk at all in `state.ts`.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { listField, readFrontmatter, stringField, type Frontmatter } from \"../document/frontmatter.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { featureDirOf, type DocsDir, type FeatureDir } from \"../kernel/ids/dirs.js\";\nimport { rawServiceId, serviceIdProblem, type RawServiceId } from \"../kernel/ids/service.js\";\nimport { readVouchScope } from \"../provenance/sample/scope.js\";\nimport { compareIds, featureIdFromDirName, type FeatureEntry, type ServiceEntry } from \"./entries.js\";\nimport { ARCHIVE_DIR, featurePaths, featuresDir, fleetAdrsDir, isServiceArtifactName, servicePathsAt } from \"./paths.js\";\nimport { requireDocsRepo } from \"./state.js\";\nimport { countMarkdown, entryIs } from \"./tree/fs.js\";\nimport { walkServicesTree, type FleetTree } from \"./tree/walk.js\";\n\n/* ------------------------------------------------------------------ */\n/* Enumeration                                                         */\n/* ------------------------------------------------------------------ */\n\n/**\n * Sorted names of the real subdirectories of `dir` (dot-dirs and files skipped).\n * A missing `dir` is an empty list — the swallow is deliberate but narrow: it\n * only ever runs INSIDE a docs repo that `requireDocsRepo` has already\n * confirmed, where an absent `features/` or `specs/` means \"none yet\" and\n * nothing else.\n */\nasync function subdirs(dir: string): Promise<string[]> {\n  if (!existsSync(dir)) return [];\n  const entries = await readdir(dir, { withFileTypes: true });\n  return entries\n    .filter((e) => !e.name.startsWith(\".\") && entryIs(dir, e, \"dir\"))\n    .map((e) => e.name)\n    .sort(compareIds);\n}\n\n/** Services a feature carries a delta for, ordered — the subdirs of its specs/. */\nexport async function featureSpecServices(\n  featureDir: FeatureDir,\n  context?: FleetContext,\n): Promise<RawServiceId[]> {\n  if (context !== undefined) return context.featureSpecServices(featureDir);\n  return (await subdirs(featurePaths(featureDir).specsDir)).map(rawServiceId);\n}\n\n/**\n * The classified `services/` tree — services at any depth, the subsystems\n * grouping them, and the walk's own findings (`subsystem.*`). The walk itself\n * lives in `./tree/walk.ts` and never imports back into this package; this\n * function is where its two injected dependencies are built — the docs-repo\n * precondition and the artifact-name table `paths.ts` owns.\n */\nexport async function listFleetTree(docsDir: DocsDir, context?: FleetContext): Promise<FleetTree> {\n  if (context !== undefined) return context.fleetTree(docsDir);\n  requireDocsRepo(docsDir, [\"ok\"]);\n  return walkServicesTree({ docsDir, isServiceArtifact: isServiceArtifactName });\n}\n\n/** Every service in the docs repo, at any depth of the tree, ordered by id. */\nexport async function listServices(docsDir: DocsDir, context?: FleetContext): Promise<ServiceEntry[]> {\n  if (context !== undefined) return context.listServices(docsDir);\n  return serviceEntries(await listFleetTree(docsDir));\n}\n\n/**\n * The full entries for a walked tree — frontmatter, artifact presence, ADR\n * count. Split from `listServices` so `FleetContext` can derive its services\n * memo from its tree memo: one walk per invocation answers both questions.\n * Ordering is `compareIds` over the id wherever the service sits — placement\n * is never part of any identity, and `--json` consumers diff this order — with\n * the directory as the tiebreak so a duplicated id (its own error finding)\n * still lists deterministically.\n */\n/**\n * The second spec axis's header, or an empty one when nobody could read it.\n *\n * `readFrontmatter` folds a decode failure into a flag but still THROWS when\n * the path exists and cannot be read as a file at all — a directory named\n * `arch.spec.md`, which test/gate-command.test.ts builds on purpose. This is\n * the fleet ENUMERATION, where one service's bad byte must cost one subject\n * and not the listing of the other 119, so the throw stops here.\n *\n * The distinction between \"no scope\" and \"nobody could look\" is not lost by\n * swallowing it: a path that exists and cannot be read is `service.unreadable`\n * — an ERROR that fails `loam validate` and `loam gate` — which is a louder\n * signal than any row of a listing, and it names the file this cannot.\n */\nasync function archHeader(path: string): Promise<Frontmatter> {\n  try {\n    return await readFrontmatter(path);\n  } catch {\n    return { present: false, malformed: false, data: {}, body: \"\" };\n  }\n}\n\nexport async function serviceEntries(tree: FleetTree): Promise<ServiceEntry[]> {\n  const entries = await Promise.all(\n    tree.services.map(async (svc): Promise<ServiceEntry> => {\n      const p = servicePathsAt(svc.dir);\n      // Both spec axes, because a sample is per FILE: one `--sample 3` run can\n      // read a short spec.md in full and stamp a scope on a long arch.spec.md\n      // beside it, and a fleet row that reported only spec.md's header would\n      // print that service as fully vouched while `loam validate` reported it\n      // sampled. `readFrontmatter` answers \"absent\" for a file that is not\n      // there, so a service without the second axis pays one existsSync.\n      const [fm, archFm] = await Promise.all([readFrontmatter(p.spec), archHeader(p.archSpec)]);\n      const idProblem = serviceIdProblem(svc.id, \"directory name\");\n      return {\n        id: svc.id,\n        dir: svc.dir,\n        subsystem: svc.subsystem,\n        ...(idProblem === null ? {} : { idProblem }),\n        has: {\n          model: existsSync(p.model),\n          spec: existsSync(p.spec),\n          openapi: existsSync(p.openapi),\n          asyncapi: existsSync(p.asyncapi),\n          runbook: existsSync(p.runbook),\n          health: existsSync(p.health),\n        },\n        adrs: await countMarkdown(p.adrsDir),\n        status: stringField(fm, \"status\") ?? null,\n        sources: {\n          declared: listField(fm, \"sources\").length > 0,\n          stamped: stringField(fm, \"sources_digest\") !== undefined,\n        },\n        // Either axis makes the SERVICE sampled, and presence is the test, not\n        // decodability: an unreadable scope is still a stamped partial read\n        // (core/provenance/sample/scope.ts's `readVouchScope`), and the fleet\n        // listing is the last place a mangled field should be able to buy\n        // itself a full-trust row.\n        vouchScope: [fm, archFm].some((header) => readVouchScope(header).kind !== \"none\") ? \"sampled\" : null,\n      };\n    }),\n  );\n  return entries.sort((a, b) => compareIds(a.id, b.id) || compareIds(a.dir, b.dir));\n}\n\n/**\n * How many fleet-level ADRs `architecture/adrs/` holds — the same number, by the\n * same rule (`countMarkdown`), that `ServiceEntry.adrs` carries one altitude\n * down. One shape for one question: a second spelling of \"count the decisions\"\n * is how `list` and `show` once reported different ADR counts for one service.\n *\n * A count and never a finding. The directory is optional, an absent one is 0,\n * and nothing in loam grades either — see `fleetAdrsDir` for why that is the\n * whole design rather than an unfinished half of it. No `FleetContext` overload:\n * one caller asks this once per invocation, and a memo whose key is the docsDir\n * would be a cache nobody reads twice.\n */\nexport async function fleetAdrCount(docsDir: DocsDir): Promise<number> {\n  return countMarkdown(fleetAdrsDir(docsDir));\n}\n\nasync function readFeature(dir: FeatureDir, dirName: string, archived: boolean): Promise<FeatureEntry> {\n  const p = featurePaths(dir);\n  return {\n    id: featureIdFromDirName(dirName),\n    dirName,\n    dir,\n    archived,\n    services: (await subdirs(p.specsDir)).map(rawServiceId),\n    has: { intent: existsSync(p.intent), delta: existsSync(p.delta) },\n  };\n}\n\n/**\n * Features in the docs repo, ordered by id (active and archived interleaved when\n * both are asked for). `features/archive/` is the archive, never a feature.\n */\nexport async function listFeatures(\n  docsDir: DocsDir,\n  opts: { includeArchived?: boolean } = {},\n  context?: FleetContext,\n): Promise<FeatureEntry[]> {\n  if (context !== undefined) return context.listFeatures(docsDir, opts);\n  // \"no-services\" is tolerated here on purpose: a docs repo whose services/ is\n  // gone is broken, but it is `listServices` (and `loam doctor`) that says so.\n  // Refusing here too would turn one diagnosis into two contradictory ones.\n  requireDocsRepo(docsDir, [\"ok\", \"no-services\"]);\n  const root = featuresDir(docsDir);\n  const active = (await subdirs(root)).filter((n) => n !== ARCHIVE_DIR);\n  // Branded at the join: the name came off this readdir, onto the features\n  // root it was listed under — the provenance `FeatureDir` records.\n  const out = await Promise.all(active.map((n) => readFeature(featureDirOf(join(root, n)), n, false)));\n\n  if (opts.includeArchived) {\n    const archiveRoot = join(root, ARCHIVE_DIR);\n    const archived = await subdirs(archiveRoot);\n    out.push(...(await Promise.all(archived.map((n) => readFeature(featureDirOf(join(archiveRoot, n)), n, true)))));\n  }\n\n  return out.sort((a, b) => compareIds(a.id, b.id) || compareIds(a.dirName, b.dirName));\n}\n\n/**\n * Which side of `features/archive/` a lookup may land on. The policy is an\n * argument, not a default, so every command's stance on shipped features is\n * visible at its call site: delta/validate/archive work on in-flight features\n * (\"exclude\"), show/verify/new read shipped ones too (\"include\"), unarchive\n * takes back nothing else (\"only\").\n */\nexport type ArchivedPolicy = \"exclude\" | \"include\" | \"only\";\n\n/**\n * Resolve a feature argument — a canonical id (`FEAT-5`) or an exact directory\n * name (`FEAT-5-slug`) — to its entry. The entry's `id` is the canonical\n * spelling, and it is the only name a caller may use from here on: tag filters,\n * coherence, and the cross-feature self-exclusion scans all compare against\n * `feature.id`, never against the raw argument.\n *\n * Matching is EXACT, on one of two spellings: the directory name as it is on\n * disk, or the canonical id derived from it. It used to also match any dirName\n * starting with `arg + \"-\"`, which made the argument a prefix query in\n * disguise: with FEAT-401 and FEAT-402 in flight, `loam archive FEAT` archived\n * whichever sorted first, and `loam delta billing` reached into\n * `billing-7-rewrite`. A destructive command must never pick a target the\n * caller did not name, so a prefix now resolves to nothing at all.\n *\n * An exact directory name still wins over the id spelling (`FEAT-5` the\n * directory over `FEAT-5-slug`, whose id is also `FEAT-5`), and under \"include\"\n * an active feature wins over an archived one. Ties among equally-exact\n * candidates go to the first by name — deterministic, unlike the raw readdir\n * order this replaces; `ambiguousFeatureMessage` lists them for the caller.\n */\nexport async function resolveFeature(\n  docsDir: DocsDir,\n  arg: string,\n  archived: ArchivedPolicy,\n  context?: FleetContext,\n): Promise<FeatureEntry | null> {\n  return (await featureCandidates(docsDir, arg, archived, context))[0] ?? null;\n}\n\n/**\n * Every feature the argument names exactly, best first. Split out of\n * `resolveFeature` so a caller that wants to REFUSE an ambiguous argument can\n * see the tie instead of inheriting the winner.\n */\nexport async function featureCandidates(\n  docsDir: DocsDir,\n  arg: string,\n  archived: ArchivedPolicy,\n  context?: FleetContext,\n): Promise<FeatureEntry[]> {\n  const all = await listFeatures(docsDir, { includeArchived: archived !== \"exclude\" }, context);\n  return all\n    .filter((f) => archived === \"include\" || f.archived === (archived === \"only\"))\n    .filter((f) => f.dirName === arg || f.id === arg)\n    .sort(\n      (a, b) =>\n        Number(b.dirName === arg) - Number(a.dirName === arg) ||\n        Number(a.archived) - Number(b.archived) ||\n        compareIds(a.dirName, b.dirName),\n    );\n}\n\n/**\n * The message for an argument that names more than one feature — two directories\n * carrying the same id (`FEAT-6-aaa` and `FEAT-6-zzz`). `resolveFeature` still\n * picks one deterministically, but a command that is about to WRITE should say\n * which directories collided and make the caller spell one out.\n */\nexport function ambiguousFeatureMessage(arg: string, candidates: FeatureEntry[]): string {\n  return (\n    `'${arg}' names ${candidates.length} features: ${candidates.map((c) => c.dirName).join(\", \")}. ` +\n    \"Pass the directory name you mean.\"\n  );\n}\n\n/**\n * The message for an exclude-mode miss. When the feature exists under\n * `features/archive/`, \"no feature\" is a lie the caller would have to debug —\n * the honest answer is \"already archived\", plus how to look at it. The `--json`\n * code stays `unknown-target` either way: the target is unknown to the command\n * that asked, and the prose carries the diagnosis.\n */\nexport async function missingFeatureMessage(\n  docsDir: DocsDir,\n  arg: string,\n  context?: FleetContext,\n): Promise<string> {\n  const shipped = await resolveFeature(docsDir, arg, \"only\", context);\n  if (shipped !== null) {\n    return (\n      `Feature '${shipped.id}' is already archived (features/archive/${shipped.dirName}) — ` +\n      `\\`loam show ${shipped.id}\\` reads it, \\`loam unarchive ${shipped.id}\\` re-opens it.`\n    );\n  }\n  return `No feature '${arg}' under ${featuresDir(docsDir)}.`;\n}\n"]}
+{"version":3,"file":"repo.js","sourceRoot":"","sources":["../../../src/core/repo/repo.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Read model of the docs repo — enumeration, and only by the filesystem.\n *\n * Files are the source of truth, so `services/` IS the list of services and\n * there is no manifest that can disagree with it. The shapes this hands back\n * live in `entries.ts`, the layout it walks in `paths.ts`, and whether there is\n * a repo to walk at all in `state.ts`.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir, readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport {\n  contentStamp,\n  listField,\n  movedUnderVouch,\n  readFrontmatter,\n  stringField,\n  type Frontmatter,\n} from \"../document/frontmatter.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { featureDirOf, type DocsDir, type FeatureDir } from \"../kernel/ids/dirs.js\";\nimport { rawServiceId, serviceIdProblem, type RawServiceId } from \"../kernel/ids/service.js\";\nimport { readVouchScope } from \"../provenance/sample/scope.js\";\nimport { compareIds, featureIdFromDirName, type FeatureEntry, type ServiceEntry } from \"./entries.js\";\nimport {\n  ARCHIVE_DIR,\n  featurePaths,\n  featuresDir,\n  fleetAdrsDir,\n  isServiceArtifactName,\n  servicePathsAt,\n  SPEC_AXES,\n} from \"./paths.js\";\nimport { requireDocsRepo } from \"./state.js\";\nimport { countMarkdown, entryIs } from \"./tree/fs.js\";\nimport { walkServicesTree, type FleetTree } from \"./tree/walk.js\";\n\n/* ------------------------------------------------------------------ */\n/* Enumeration                                                         */\n/* ------------------------------------------------------------------ */\n\n/**\n * Sorted names of the real subdirectories of `dir` (dot-dirs and files skipped).\n * A missing `dir` is an empty list — the swallow is deliberate but narrow: it\n * only ever runs INSIDE a docs repo that `requireDocsRepo` has already\n * confirmed, where an absent `features/` or `specs/` means \"none yet\" and\n * nothing else.\n */\nasync function subdirs(dir: string): Promise<string[]> {\n  if (!existsSync(dir)) return [];\n  const entries = await readdir(dir, { withFileTypes: true });\n  return entries\n    .filter((e) => !e.name.startsWith(\".\") && entryIs(dir, e, \"dir\"))\n    .map((e) => e.name)\n    .sort(compareIds);\n}\n\n/** Services a feature carries a delta for, ordered — the subdirs of its specs/. */\nexport async function featureSpecServices(\n  featureDir: FeatureDir,\n  context?: FleetContext,\n): Promise<RawServiceId[]> {\n  if (context !== undefined) return context.featureSpecServices(featureDir);\n  return (await subdirs(featurePaths(featureDir).specsDir)).map(rawServiceId);\n}\n\n/**\n * The classified `services/` tree — services at any depth, the subsystems\n * grouping them, and the walk's own findings (`subsystem.*`). The walk itself\n * lives in `./tree/walk.ts` and never imports back into this package; this\n * function is where its two injected dependencies are built — the docs-repo\n * precondition and the artifact-name table `paths.ts` owns.\n */\nexport async function listFleetTree(docsDir: DocsDir, context?: FleetContext): Promise<FleetTree> {\n  if (context !== undefined) return context.fleetTree(docsDir);\n  requireDocsRepo(docsDir, [\"ok\"]);\n  return walkServicesTree({ docsDir, isServiceArtifact: isServiceArtifactName });\n}\n\n/** Every service in the docs repo, at any depth of the tree, ordered by id. */\nexport async function listServices(docsDir: DocsDir, context?: FleetContext): Promise<ServiceEntry[]> {\n  if (context !== undefined) return context.listServices(docsDir);\n  return serviceEntries(await listFleetTree(docsDir));\n}\n\n/**\n * The full entries for a walked tree — frontmatter, artifact presence, ADR\n * count. Split from `listServices` so `FleetContext` can derive its services\n * memo from its tree memo: one walk per invocation answers both questions.\n * Ordering is `compareIds` over the id wherever the service sits — placement\n * is never part of any identity, and `--json` consumers diff this order — with\n * the directory as the tiebreak so a duplicated id (its own error finding)\n * still lists deterministically.\n */\n/**\n * The second spec axis's header, or an empty one when nobody could read it.\n *\n * `readFrontmatter` folds a decode failure into a flag but still THROWS when\n * the path exists and cannot be read as a file at all — a directory named\n * `arch.spec.md`, which test/gate-command.test.ts builds on purpose. This is\n * the fleet ENUMERATION, where one service's bad byte must cost one subject\n * and not the listing of the other 119, so the throw stops here.\n *\n * The distinction between \"no scope\" and \"nobody could look\" is not lost by\n * swallowing it: a path that exists and cannot be read is `service.unreadable`\n * — an ERROR that fails `loam validate` and `loam gate` — which is a louder\n * signal than any row of a listing, and it names the file this cannot.\n */\nasync function archHeader(path: string): Promise<Frontmatter> {\n  try {\n    return await readFrontmatter(path);\n  } catch {\n    return { present: false, malformed: false, data: {}, body: \"\" };\n  }\n}\n\n/**\n * The spec files whose body moved under their vouch — `content.stale`'s\n * question, asked through the one predicate `loam validate` grades with\n * (`movedUnderVouch`) so the fleet listing and the finding cannot disagree\n * about one file. Only a header that carries a stamp (`contentStamp`) costs the\n * second read: the frontmatter read already answered whether there is anything\n * to compare, and on a fleet mid-adoption most headers do not. The body is\n * read exactly as the finding reads it, as UTF-8 text, because the stamp is\n * byte-exact.\n */\nasync function filesMovedUnderVouch(\n  axes: readonly { file: string; path: string; header: Frontmatter }[],\n): Promise<string[]> {\n  const moved = await Promise.all(\n    axes.map(async ({ file, path, header }) =>\n      contentStamp(header) !== undefined && movedUnderVouch(header, await readFile(path, \"utf8\")) ? [file] : [],\n    ),\n  );\n  return moved.flat();\n}\n\n/**\n * `ServiceEntry.adoption`, read off one living spec.md's frontmatter — the one\n * spelling of the marker's test, for the enumeration below and for the adopt\n * brief, which must not call a partial adoption finished. Any value but\n * `partial` reads as absent (SCHEMA.md).\n */\nexport function adoptionOf(fm: Frontmatter): \"partial\" | null {\n  return stringField(fm, \"adoption\") === \"partial\" ? \"partial\" : null;\n}\n\n/** `adoptionOf` for a spec.md by path; an absent file is no marker. */\nexport async function specAdoption(specPath: string): Promise<\"partial\" | null> {\n  return adoptionOf(await readFrontmatter(specPath));\n}\n\nexport async function serviceEntries(tree: FleetTree): Promise<ServiceEntry[]> {\n  const entries = await Promise.all(\n    tree.services.map(async (svc): Promise<ServiceEntry> => {\n      const p = servicePathsAt(svc.dir);\n      // Both spec axes, because a sample is per FILE: one `--sample 3` run can\n      // read a short spec.md in full and stamp a scope on a long arch.spec.md\n      // beside it, and a fleet row that reported only spec.md's header would\n      // print that service as fully vouched while `loam validate` reported it\n      // sampled. `readFrontmatter` answers \"absent\" for a file that is not\n      // there, so a service without the second axis pays one existsSync.\n      const [fm, archFm] = await Promise.all([readFrontmatter(p.spec), archHeader(p.archSpec)]);\n      const headers = { spec: fm, archSpec: archFm };\n      const idProblem = serviceIdProblem(svc.id, \"directory name\");\n      return {\n        id: svc.id,\n        dir: svc.dir,\n        subsystem: svc.subsystem,\n        ...(idProblem === null ? {} : { idProblem }),\n        has: {\n          model: existsSync(p.model),\n          spec: existsSync(p.spec),\n          openapi: existsSync(p.openapi),\n          asyncapi: existsSync(p.asyncapi),\n          runbook: existsSync(p.runbook),\n          health: existsSync(p.health),\n        },\n        adrs: await countMarkdown(p.adrsDir),\n        status: stringField(fm, \"status\") ?? null,\n        adoption: adoptionOf(fm),\n        sources: {\n          declared: listField(fm, \"sources\").length > 0,\n          stamped: stringField(fm, \"sources_digest\") !== undefined,\n        },\n        // Either axis makes the SERVICE sampled, and presence is the test, not\n        // decodability: an unreadable scope is still a stamped partial read\n        // (core/provenance/sample/scope.ts's `readVouchScope`), and the fleet\n        // listing is the last place a mangled field should be able to buy\n        // itself a full-trust row.\n        vouchScope: [fm, archFm].some((header) => readVouchScope(header).kind !== \"none\") ? \"sampled\" : null,\n        // Both axes again, for the scope's reason: a stamp is per FILE, and an\n        // arch.spec.md edited under its vouch is a service part of whose\n        // documentation nobody has re-read.\n        contentStale: await filesMovedUnderVouch(\n          SPEC_AXES.map((axis) => ({ file: axis.file, path: p[axis.key], header: headers[axis.key] })),\n        ),\n      };\n    }),\n  );\n  return entries.sort((a, b) => compareIds(a.id, b.id) || compareIds(a.dir, b.dir));\n}\n\n/**\n * How many fleet-level ADRs `architecture/adrs/` holds — the same number, by the\n * same rule (`countMarkdown`), that `ServiceEntry.adrs` carries one altitude\n * down. One shape for one question: a second spelling of \"count the decisions\"\n * is how `list` and `show` once reported different ADR counts for one service.\n *\n * A count and never a finding. The directory is optional, an absent one is 0,\n * and nothing in loam grades either — see `fleetAdrsDir` for why that is the\n * whole design rather than an unfinished half of it. No `FleetContext` overload:\n * one caller asks this once per invocation, and a memo whose key is the docsDir\n * would be a cache nobody reads twice.\n */\nexport async function fleetAdrCount(docsDir: DocsDir): Promise<number> {\n  return countMarkdown(fleetAdrsDir(docsDir));\n}\n\n/**\n * What a feature is CALLED, for a person: intent.md's `title:`, else its first\n * `# ` heading with the feature id peeled off the front, else null.\n *\n * Every row that names a feature used to print the id alone, and an id is a\n * key, not a name — a newcomer looking at `ready  FEAT-101` could not tell\n * which change it was without opening the directory. Read on demand rather\n * than carried on `FeatureEntry`, because the enumeration runs under every\n * command and only the views a person reads need the words. A missing or\n * unreadable intent.md is simply no title: the row still prints its id, and\n * whether intent.md is owed is `status`'s question, not this one's.\n */\nexport async function featureTitle(feature: FeatureEntry): Promise<string | null> {\n  let fm: Frontmatter;\n  try {\n    fm = await readFrontmatter(featurePaths(feature.dir).intent);\n  } catch {\n    // A directory in intent.md's place, a permission: unreadable is no title.\n    // `readFrontmatter` folds only the encoding failure into a flag, and before\n    // this read the views that print a title never opened intent.md at all —\n    // so letting the error escape would hand `loam status` and `loam list`\n    // whole to `repository-unavailable` over a label. Whether intent.md is\n    // fine is the intent row's and `validate`'s question.\n    return null;\n  }\n  const declared = stringField(fm, \"title\")?.trim();\n  if (declared !== undefined && declared !== \"\") return declared;\n  const heading = fm.body.split(/\\r?\\n/).find((l) => l.startsWith(\"# \"));\n  if (heading === undefined) return null;\n  const words = heading.slice(2).trim();\n  const bare = words.startsWith(feature.id) ? words.slice(feature.id.length).replace(/^[\\s:—–-]+/, \"\") : words;\n  return bare === \"\" ? null : bare;\n}\n\nasync function readFeature(dir: FeatureDir, dirName: string, archived: boolean): Promise<FeatureEntry> {\n  const p = featurePaths(dir);\n  return {\n    id: featureIdFromDirName(dirName),\n    dirName,\n    dir,\n    archived,\n    services: (await subdirs(p.specsDir)).map(rawServiceId),\n    has: { intent: existsSync(p.intent), delta: existsSync(p.delta) },\n  };\n}\n\n/**\n * Features in the docs repo, ordered by id (active and archived interleaved when\n * both are asked for). `features/archive/` is the archive, never a feature.\n */\nexport async function listFeatures(\n  docsDir: DocsDir,\n  opts: { includeArchived?: boolean } = {},\n  context?: FleetContext,\n): Promise<FeatureEntry[]> {\n  if (context !== undefined) return context.listFeatures(docsDir, opts);\n  // \"no-services\" is tolerated here on purpose: a docs repo whose services/ is\n  // gone is broken, but it is `listServices` (and `loam doctor`) that says so.\n  // Refusing here too would turn one diagnosis into two contradictory ones.\n  requireDocsRepo(docsDir, [\"ok\", \"no-services\"]);\n  const root = featuresDir(docsDir);\n  const active = (await subdirs(root)).filter((n) => n !== ARCHIVE_DIR);\n  // Branded at the join: the name came off this readdir, onto the features\n  // root it was listed under — the provenance `FeatureDir` records.\n  const out = await Promise.all(active.map((n) => readFeature(featureDirOf(join(root, n)), n, false)));\n\n  if (opts.includeArchived) {\n    const archiveRoot = join(root, ARCHIVE_DIR);\n    const archived = await subdirs(archiveRoot);\n    out.push(...(await Promise.all(archived.map((n) => readFeature(featureDirOf(join(archiveRoot, n)), n, true)))));\n  }\n\n  return out.sort((a, b) => compareIds(a.id, b.id) || compareIds(a.dirName, b.dirName));\n}\n\n/**\n * Which side of `features/archive/` a lookup may land on. The policy is an\n * argument, not a default, so every command's stance on shipped features is\n * visible at its call site: delta/validate/archive work on in-flight features\n * (\"exclude\"), show/verify/new read shipped ones too (\"include\"), unarchive\n * takes back nothing else (\"only\").\n */\nexport type ArchivedPolicy = \"exclude\" | \"include\" | \"only\";\n\n/**\n * Resolve a feature argument — a canonical id (`FEAT-5`) or an exact directory\n * name (`FEAT-5-slug`) — to its entry. The entry's `id` is the canonical\n * spelling, and it is the only name a caller may use from here on: tag filters,\n * coherence, and the cross-feature self-exclusion scans all compare against\n * `feature.id`, never against the raw argument.\n *\n * Matching is EXACT, on one of two spellings: the directory name as it is on\n * disk, or the canonical id derived from it. It used to also match any dirName\n * starting with `arg + \"-\"`, which made the argument a prefix query in\n * disguise: with FEAT-401 and FEAT-402 in flight, `loam archive FEAT` archived\n * whichever sorted first, and `loam delta billing` reached into\n * `billing-7-rewrite`. A destructive command must never pick a target the\n * caller did not name, so a prefix now resolves to nothing at all.\n *\n * An exact directory name still wins over the id spelling (`FEAT-5` the\n * directory over `FEAT-5-slug`, whose id is also `FEAT-5`), and under \"include\"\n * an active feature wins over an archived one. Ties among equally-exact\n * candidates go to the first by name — deterministic, unlike the raw readdir\n * order this replaces; `featureCandidates` returns every one of them, for a\n * caller that must see the tie (`loam status` names the colliding directories).\n */\nexport async function resolveFeature(\n  docsDir: DocsDir,\n  arg: string,\n  archived: ArchivedPolicy,\n  context?: FleetContext,\n): Promise<FeatureEntry | null> {\n  return (await featureCandidates(docsDir, arg, archived, context))[0] ?? null;\n}\n\n/**\n * Every feature the argument names exactly, best first. Split out of\n * `resolveFeature` so a caller that wants to REFUSE an ambiguous argument can\n * see the tie instead of inheriting the winner.\n */\nexport async function featureCandidates(\n  docsDir: DocsDir,\n  arg: string,\n  archived: ArchivedPolicy,\n  context?: FleetContext,\n): Promise<FeatureEntry[]> {\n  const all = await listFeatures(docsDir, { includeArchived: archived !== \"exclude\" }, context);\n  return all\n    .filter((f) => archived === \"include\" || f.archived === (archived === \"only\"))\n    .filter((f) => f.dirName === arg || f.id === arg)\n    .sort(\n      (a, b) =>\n        Number(b.dirName === arg) - Number(a.dirName === arg) ||\n        Number(a.archived) - Number(b.archived) ||\n        compareIds(a.dirName, b.dirName),\n    );\n}\n\n/**\n * The message for an exclude-mode miss. When the feature exists under\n * `features/archive/`, \"no feature\" is a lie the caller would have to debug —\n * the honest answer is \"already archived\", plus how to look at it. The `--json`\n * code stays `unknown-target` either way: the target is unknown to the command\n * that asked, and the prose carries the diagnosis.\n */\nexport async function missingFeatureMessage(\n  docsDir: DocsDir,\n  arg: string,\n  context?: FleetContext,\n): Promise<string> {\n  const shipped = await resolveFeature(docsDir, arg, \"only\", context);\n  if (shipped !== null) {\n    return (\n      `Feature '${shipped.id}' is already archived (features/archive/${shipped.dirName}) — ` +\n      `\\`loam show ${shipped.id}\\` reads it, \\`loam unarchive ${shipped.id}\\` re-opens it.`\n    );\n  }\n  return `No feature '${arg}' under ${featuresDir(docsDir)}.`;\n}\n"]}

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

@@ -26,9 +26,18 @@ export function findInTree(tree, name) {
 export function treeNames(tree) {
     return [...tree.services.map((s) => s.id), ...tree.subsystems.map((s) => s.name)];
 }
-/** The near-miss hints a refusal offers, over whichever pool the verb resolves against. */
-export function nearestTreeNames(name, pool) {
-    return closeIds(name, pool);
+/**
+ * The near-miss tail a refusal appends to its "no such name" sentence, over
+ * whichever pool the verb resolves against: the close names when there are
+ * any, else `otherwise` — the verb's own pointer at what exists, or "" for
+ * none. Eight refusals across `subsystem`, `adopt --subsystem` and
+ * `list --subsystem` end this way, and each spelled the conditional itself;
+ * the lead sentence and the fallback stay theirs, because those are what
+ * differ.
+ */
+export function closeNamesHint(name, pool, otherwise) {
+    const close = closeIds(name, pool);
+    return close.length > 0 ? ` Close names: ${close.join(", ")}.` : otherwise;
 }
 /**
  * Does the subsystem at `subPath` contain `path` — itself, or anywhere beneath

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

@@ -1 +1 @@
-{"version":3,"file":"find.js","sourceRoot":"","sources":["../../../../src/core/repo/tree/find.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAS5C;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAe,EAAE,IAAY;IACtD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC;IACzD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAC/D,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAC/D,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;IACrE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,SAAS,CAAC,IAAe;IACvC,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACpF,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,IAAc;IAC3D,OAAO,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,OAAiB,EAAE,IAAc;IAC/D,OAAO,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;AACvF,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,aAAa,CAAC,IAAe,EAAE,GAAmB;IAChE,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,eAAe,CAAC,IAAe,EAAE,GAAmB;IAClE,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,GAAG,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACvF,CAAC","sourcesContent":["/**\n * Name resolution over a walked tree — the questions every `loam subsystem`\n * verb asks before it acts: what does this name denote, what sits beneath a\n * subsystem, and which names come close to a miss. One module so `move`,\n * `rm`, `new` and `history` cannot grow four private spellings of \"the flat\n * namespace\" — the walk already enforces one namespace, and resolution must\n * read it the same way.\n */\nimport { closeIds } from \"../../c4/arch.js\";\nimport type { FleetTree, SubsystemEntry, WalkedService } from \"./walk.js\";\n\n/** What a name denotes in the tree — a service, a subsystem, or nothing. */\nexport type TreeHit =\n  | { kind: \"service\"; service: WalkedService }\n  | { kind: \"subsystem\"; subsystem: SubsystemEntry }\n  | null;\n\n/**\n * Resolve one name against the flat namespace. Services win a tie on\n * purpose: a tie IS `subsystem.name-collision`, already an error finding,\n * and while it stands the service reading keeps every id-addressed command\n * coherent.\n */\nexport function findInTree(tree: FleetTree, name: string): TreeHit {\n  const service = tree.services.find((s) => s.id === name);\n  if (service !== undefined) return { kind: \"service\", service };\n  const subsystem = tree.subsystems.find((s) => s.name === name);\n  if (subsystem !== undefined) return { kind: \"subsystem\", subsystem };\n  return null;\n}\n\n/** Every name the flat namespace holds — service ids and subsystem names together. */\nexport function treeNames(tree: FleetTree): string[] {\n  return [...tree.services.map((s) => s.id), ...tree.subsystems.map((s) => s.name)];\n}\n\n/** The near-miss hints a refusal offers, over whichever pool the verb resolves against. */\nexport function nearestTreeNames(name: string, pool: string[]): string[] {\n  return closeIds(name, pool);\n}\n\n/**\n * Does the subsystem at `subPath` contain `path` — itself, or anywhere beneath\n * it? The move-into-own-subtree refusal. The parameter is the name chain, not\n * a `SubsystemEntry`, because a chain is all this comparison reads — the one\n * caller outside this module (`move`) has a chain it just composed and no\n * entry to hand, and a structural parameter it never reads would force a\n * placeholder there.\n */\nexport function withinSubsystem(subPath: string[], path: string[]): boolean {\n  return subPath.length <= path.length && subPath.every((name, i) => path[i] === name);\n}\n\n/** Services anywhere beneath a subsystem — the transitive membership the views and counts share. */\nexport function servicesUnder(tree: FleetTree, sub: SubsystemEntry): WalkedService[] {\n  return tree.services.filter((s) => sub.path.every((name, i) => s.subsystem[i] === name));\n}\n\n/** Child subsystems anywhere beneath one — `rm`'s other half of \"empty\". */\nexport function subsystemsUnder(tree: FleetTree, sub: SubsystemEntry): SubsystemEntry[] {\n  return tree.subsystems.filter((c) => c !== sub && withinSubsystem(sub.path, c.path));\n}\n"]}
+{"version":3,"file":"find.js","sourceRoot":"","sources":["../../../../src/core/repo/tree/find.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAS5C;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAe,EAAE,IAAY;IACtD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC;IACzD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAC/D,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAC/D,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;IACrE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,SAAS,CAAC,IAAe;IACvC,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,IAAc,EAAE,SAAiB;IAC5E,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,OAAiB,EAAE,IAAc;IAC/D,OAAO,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;AACvF,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,aAAa,CAAC,IAAe,EAAE,GAAmB;IAChE,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,eAAe,CAAC,IAAe,EAAE,GAAmB;IAClE,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,GAAG,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACvF,CAAC","sourcesContent":["/**\n * Name resolution over a walked tree — the questions every `loam subsystem`\n * verb asks before it acts: what does this name denote, what sits beneath a\n * subsystem, and which names come close to a miss. One module so `move`,\n * `rm`, `new` and `history` cannot grow four private spellings of \"the flat\n * namespace\" — the walk already enforces one namespace, and resolution must\n * read it the same way.\n */\nimport { closeIds } from \"../../c4/arch.js\";\nimport type { FleetTree, SubsystemEntry, WalkedService } from \"./walk.js\";\n\n/** What a name denotes in the tree — a service, a subsystem, or nothing. */\nexport type TreeHit =\n  | { kind: \"service\"; service: WalkedService }\n  | { kind: \"subsystem\"; subsystem: SubsystemEntry }\n  | null;\n\n/**\n * Resolve one name against the flat namespace. Services win a tie on\n * purpose: a tie IS `subsystem.name-collision`, already an error finding,\n * and while it stands the service reading keeps every id-addressed command\n * coherent.\n */\nexport function findInTree(tree: FleetTree, name: string): TreeHit {\n  const service = tree.services.find((s) => s.id === name);\n  if (service !== undefined) return { kind: \"service\", service };\n  const subsystem = tree.subsystems.find((s) => s.name === name);\n  if (subsystem !== undefined) return { kind: \"subsystem\", subsystem };\n  return null;\n}\n\n/** Every name the flat namespace holds — service ids and subsystem names together. */\nexport function treeNames(tree: FleetTree): string[] {\n  return [...tree.services.map((s) => s.id), ...tree.subsystems.map((s) => s.name)];\n}\n\n/**\n * The near-miss tail a refusal appends to its \"no such name\" sentence, over\n * whichever pool the verb resolves against: the close names when there are\n * any, else `otherwise` — the verb's own pointer at what exists, or \"\" for\n * none. Eight refusals across `subsystem`, `adopt --subsystem` and\n * `list --subsystem` end this way, and each spelled the conditional itself;\n * the lead sentence and the fallback stay theirs, because those are what\n * differ.\n */\nexport function closeNamesHint(name: string, pool: string[], otherwise: string): string {\n  const close = closeIds(name, pool);\n  return close.length > 0 ? ` Close names: ${close.join(\", \")}.` : otherwise;\n}\n\n/**\n * Does the subsystem at `subPath` contain `path` — itself, or anywhere beneath\n * it? The move-into-own-subtree refusal. The parameter is the name chain, not\n * a `SubsystemEntry`, because a chain is all this comparison reads — the one\n * caller outside this module (`move`) has a chain it just composed and no\n * entry to hand, and a structural parameter it never reads would force a\n * placeholder there.\n */\nexport function withinSubsystem(subPath: string[], path: string[]): boolean {\n  return subPath.length <= path.length && subPath.every((name, i) => path[i] === name);\n}\n\n/** Services anywhere beneath a subsystem — the transitive membership the views and counts share. */\nexport function servicesUnder(tree: FleetTree, sub: SubsystemEntry): WalkedService[] {\n  return tree.services.filter((s) => sub.path.every((name, i) => s.subsystem[i] === name));\n}\n\n/** Child subsystems anywhere beneath one — `rm`'s other half of \"empty\". */\nexport function subsystemsUnder(tree: FleetTree, sub: SubsystemEntry): SubsystemEntry[] {\n  return tree.subsystems.filter((c) => c !== sub && withinSubsystem(sub.path, c.path));\n}\n"]}

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

@@ -6,7 +6,7 @@
  * package direction is `repo → repo/tree` (never back — `walk.ts` says why),
  * so the shared spelling lives on this side of the edge.
  */
-import { existsSync, statSync } from "node:fs";
+import { existsSync, realpathSync, statSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 /**
@@ -61,4 +61,30 @@ export async function markdownFiles(dir) {
 export async function countMarkdown(dir) {
     return (await markdownFiles(dir)).length;
 }
+/**
+ * Mark a directory as descended-into; false when it (or another name for it)
+ * already was. The symlink-cycle guard every walk that follows links through
+ * `entryIs` carries — the service tree (`./walk.ts`), the capability tree, the
+ * glossary, the generated-gherkin scan — and for one reason: a followed cycle
+ * without a visited set recurses until the stack ends. A path realpath cannot
+ * resolve is one whose children cannot be read either, so it is never entered.
+ */
+export function markDescended(dir, visited) {
+    let real;
+    try {
+        real = realpathSync(dir);
+    }
+    catch {
+        return false;
+    }
+    if (visited.has(real))
+        return false;
+    visited.add(real);
+    return true;
+}
+/** Sorted non-dot subdirectory names, links followed — a tree walk's deterministic child order. */
+export 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();
+}
 //# sourceMappingURL=fs.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../../../src/core/repo/tree/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAe,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,CAAS,EAAE,IAAoB;IAClE,IAAI,CAAC,CAAC,CAAC,cAAc,EAAE;QAAE,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC9E,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAW;IAC7C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,OAAO,OAAO;SACX,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;SAChE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;SAC7B,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,4FAA4F;AAC5F,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAW;IAC7C,OAAO,CAAC,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AAC3C,CAAC","sourcesContent":["/**\n * Directory-entry questions the enumerations share, symlinks followed.\n *\n * Moved here from `repo/repo.ts` when the tree walk arrived: the walk and the\n * feature enumeration must answer \"what IS this entry\" identically, and the\n * package direction is `repo → repo/tree` (never back — `walk.ts` says why),\n * so the shared spelling lives on this side of the edge.\n */\nimport { existsSync, statSync, type Dirent } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\n/**\n * What a directory entry IS, following a symlink to find out.\n *\n * `readdir(withFileTypes)` does not follow symlinks: for a symlink `Dirent`\n * every `isDirectory()`/`isFile()` is false, whatever it points at. That made a\n * symlinked `services/<id>/` or `features/<id>/` vanish from every enumeration\n * at once — `list`, `validate --all`, the fleet gate — with no diagnostic\n * anywhere, which is the one outcome a shared docs repo cannot survive: the\n * fleet gate reported a service that is not there as fine because it never saw\n * it. Composing a docs repo out of symlinks (a worktree, a submodule, one\n * service's directory shared between two checkouts) is legitimate, so they are\n * FOLLOWED rather than refused. A dangling link stats as nothing and is skipped\n * exactly as an absent directory is — it is not a service, and saying so would\n * mean inventing an entry to hang the complaint on.\n */\nexport function entryIs(dir: string, e: Dirent, want: \"dir\" | \"file\"): boolean {\n  if (!e.isSymbolicLink()) return want === \"dir\" ? e.isDirectory() : e.isFile();\n  try {\n    const s = statSync(join(dir, e.name));\n    return want === \"dir\" ? s.isDirectory() : s.isFile();\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Markdown files sitting directly in `dir`, sorted, as full paths — the ADR\n * corpus, and the only place that rule is spelled. Symlinks are resolved\n * through `entryIs`, which is the whole reason this is shared: `show` once kept\n * a second copy that tested `Dirent.isFile()` itself — always false for a\n * symlink, whatever it points at — so a docs repo composed of symlinks (the\n * layout `entryIs` above exists to support) had `loam list` and `loam show`\n * reporting different ADR counts for the same service. One rule, one answer.\n *\n * The list, not the count, is the primitive: the link check reads these same\n * files, and a corpus that disagreed with the count would grade documents the\n * fleet listing says are not there.\n */\nexport async function markdownFiles(dir: string): Promise<string[]> {\n  if (!existsSync(dir)) return [];\n  const entries = await readdir(dir, { withFileTypes: true });\n  return entries\n    .filter((e) => e.name.endsWith(\".md\") && entryIs(dir, e, \"file\"))\n    .map((e) => join(dir, e.name))\n    .sort();\n}\n\n/** How many markdown files sit directly in `dir` — the ADR count, over the corpus above. */\nexport async function countMarkdown(dir: string): Promise<number> {\n  return (await markdownFiles(dir)).length;\n}\n"]}
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../../../src/core/repo/tree/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAe,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,CAAS,EAAE,IAAoB;IAClE,IAAI,CAAC,CAAC,CAAC,cAAc,EAAE;QAAE,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC9E,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAW;IAC7C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,OAAO,OAAO;SACX,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;SAChE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;SAC7B,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,4FAA4F;AAC5F,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAW;IAC7C,OAAO,CAAC,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,OAAoB;IAC7D,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mGAAmG;AACnG,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;AAC5G,CAAC","sourcesContent":["/**\n * Directory-entry questions the enumerations share, symlinks followed.\n *\n * Moved here from `repo/repo.ts` when the tree walk arrived: the walk and the\n * feature enumeration must answer \"what IS this entry\" identically, and the\n * package direction is `repo → repo/tree` (never back — `walk.ts` says why),\n * so the shared spelling lives on this side of the edge.\n */\nimport { existsSync, realpathSync, statSync, type Dirent } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\n/**\n * What a directory entry IS, following a symlink to find out.\n *\n * `readdir(withFileTypes)` does not follow symlinks: for a symlink `Dirent`\n * every `isDirectory()`/`isFile()` is false, whatever it points at. That made a\n * symlinked `services/<id>/` or `features/<id>/` vanish from every enumeration\n * at once — `list`, `validate --all`, the fleet gate — with no diagnostic\n * anywhere, which is the one outcome a shared docs repo cannot survive: the\n * fleet gate reported a service that is not there as fine because it never saw\n * it. Composing a docs repo out of symlinks (a worktree, a submodule, one\n * service's directory shared between two checkouts) is legitimate, so they are\n * FOLLOWED rather than refused. A dangling link stats as nothing and is skipped\n * exactly as an absent directory is — it is not a service, and saying so would\n * mean inventing an entry to hang the complaint on.\n */\nexport function entryIs(dir: string, e: Dirent, want: \"dir\" | \"file\"): boolean {\n  if (!e.isSymbolicLink()) return want === \"dir\" ? e.isDirectory() : e.isFile();\n  try {\n    const s = statSync(join(dir, e.name));\n    return want === \"dir\" ? s.isDirectory() : s.isFile();\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Markdown files sitting directly in `dir`, sorted, as full paths — the ADR\n * corpus, and the only place that rule is spelled. Symlinks are resolved\n * through `entryIs`, which is the whole reason this is shared: `show` once kept\n * a second copy that tested `Dirent.isFile()` itself — always false for a\n * symlink, whatever it points at — so a docs repo composed of symlinks (the\n * layout `entryIs` above exists to support) had `loam list` and `loam show`\n * reporting different ADR counts for the same service. One rule, one answer.\n *\n * The list, not the count, is the primitive: the link check reads these same\n * files, and a corpus that disagreed with the count would grade documents the\n * fleet listing says are not there.\n */\nexport async function markdownFiles(dir: string): Promise<string[]> {\n  if (!existsSync(dir)) return [];\n  const entries = await readdir(dir, { withFileTypes: true });\n  return entries\n    .filter((e) => e.name.endsWith(\".md\") && entryIs(dir, e, \"file\"))\n    .map((e) => join(dir, e.name))\n    .sort();\n}\n\n/** How many markdown files sit directly in `dir` — the ADR count, over the corpus above. */\nexport async function countMarkdown(dir: string): Promise<number> {\n  return (await markdownFiles(dir)).length;\n}\n\n/**\n * Mark a directory as descended-into; false when it (or another name for it)\n * already was. The symlink-cycle guard every walk that follows links through\n * `entryIs` carries — the service tree (`./walk.ts`), the capability tree, the\n * glossary, the generated-gherkin scan — and for one reason: a followed cycle\n * without a visited set recurses until the stack ends. A path realpath cannot\n * resolve is one whose children cannot be read either, so it is never entered.\n */\nexport function markDescended(dir: string, visited: Set<string>): boolean {\n  let real: string;\n  try {\n    real = realpathSync(dir);\n  } catch {\n    return false;\n  }\n  if (visited.has(real)) return false;\n  visited.add(real);\n  return true;\n}\n\n/** Sorted non-dot subdirectory names, links followed — a tree walk's deterministic child order. */\nexport async 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"]}

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

@@ -0,0 +1,258 @@
+/**
+ * What one subsystem's generated view SHOWS: which boxes it draws around the
+ * services beneath a directory, and the one thing it may say about the map.
+ *
+ * Split from `../views.ts` when that file crossed the 400-line limit: the file
+ * render (header, view ids, staleness comparison) and the body render (the
+ * boxes) are two subjects, and the seam is exactly where the second one
+ * consults the LANDSCAPE. Everything here reads element ids and nothing else —
+ * no view is ever parsed (docs/DESIGN.md rule 26), and the generated file
+ * stays a pure function of the tree plus the committed map.
+ */
+import {} from "../../../c4/likec4.js";
+import { serviceResolver } from "../../../c4/resolve/service.js";
+import { servicesUnder, withinSubsystem } from "../find.js";
+import { subsystemLabel } from "./text.js";
+export function renderContext(tree, elements) {
+    const known = new Set(tree.services.map((s) => s.id));
+    const resolve = serviceResolver(elements, known);
+    return {
+        tree,
+        elementOf: elementByService(tree, elements, resolve),
+        elementIds: new Set(elements.map((e) => e.id)),
+        isServiceElement: (id) => known.has(resolve(id)),
+    };
+}
+/**
+ * Three shapes, and which one applies is a fact about the landscape rather
+ * than a setting:
+ *
+ *  1. **The model draws this group.** Some ancestor element holds exactly this
+ *     subsystem's members and nothing else, so the view includes it beside the
+ *     leaves and the renderer nests them inside the box the AUTHOR drew, with
+ *     the author's own title. Measured: including the ancestor alone renders
+ *     one empty box and the leaves alone render flat — both lines are needed.
+ *  2. **The model is flat.** No member element is nested at all, so there is
+ *     no authored box to agree with, and the view wraps the members in a
+ *     `group '<title>'` of its own — a real named box in the renderer, derived
+ *     from the DIRECTORY the services already sit in, mirroring the subtree so
+ *     a parent subsystem shows its children as boxes rather than as one pile.
+ *     Nothing is invented: the grouping is the tree, and the tree is what this
+ *     file has always mirrored.
+ *  3. **The model nests them, differently.** The members ARE nested but no
+ *     ancestor owns exactly them — the directory tree and the map disagree
+ *     about this group. loam draws no box (a synthetic one would silently
+ *     replace the author's boundary with the folder's, and the picture would
+ *     look the same whether or not the two agree) and writes ONE comment line
+ *     saying so, outside the view body. That comment is the whole of loam's
+ *     answer to the drift: it grades nothing, it fails nothing, and it appears
+ *     in the diff of the very commit that caused it — placement stays a fact
+ *     nothing branches on.
+ */
+export function viewBody(ctx, sub) {
+    const members = memberElements(ctx, sub);
+    if (members.length === 0)
+        return { lines: [], disclosure: null, of: null };
+    if (members.every((id) => !id.includes("."))) {
+        return { lines: [...groupedBody(ctx, sub, "    "), ...boundaryLines(members)], disclosure: null, of: null };
+    }
+    const includes = [...ownedAncestors(ctx, sub), ...members].map((id) => `    include ${id}`);
+    const lines = [...includes, ...boundaryLines(members)];
+    const owner = owningAncestor(ctx, sub);
+    if (owner !== null)
+        return { lines, disclosure: null, of: owner };
+    const shared = sharedAncestor(ctx, members);
+    return {
+        lines,
+        of: null,
+        disclosure: shared === null
+            ? "model: no boundary — these members do not share a containing element."
+            : `model: no boundary — ${shared} also holds services outside this subsystem.`,
+    };
+}
+/**
+ * What this group TOUCHES: for each member, every edge it has in either
+ * direction, so the view answers "what does payments talk to" and not only
+ * "who is in payments".
+ *
+ * **The measured trap, and it is why these lines are appended by the caller of
+ * `groupedBody` rather than inside it:** placed INSIDE the `group { }` block of
+ * the flat-map body shape, this exact predicate parses and validates with ZERO
+ * errors and draws a false picture. Measured at likec4 1.59.2 on a flat map of
+ * `alpha, beta` grouped and `outsider, store` outside it: at view level the two
+ * neighbours are drawn with no parent, correctly outside the box; moved inside
+ * the `group { }`, both are drawn as CHILDREN of that group — the diagram then
+ * claims `outsider` and `store` are part of the subsystem. A maintainer tidying
+ * the body by moving these lines next to the includes they refer to would ship
+ * that, and nothing anywhere would report it. They belong at view level, always.
+ *
+ * The WILDCARD is correct here, and that is not an inconsistency with the
+ * per-service views, which measure it as a defect (`./service/peers.ts`): at
+ * subsystem altitude a counterpart collapsing to its own group box is exactly
+ * the sentence "payments touches identity", and — once those group boxes are
+ * themselves views' subjects (`of <ancestor>`) — it is a click-through into
+ * that subsystem. At service altitude the same collapse is a lie about who
+ * calls whom.
+ *
+ * MEMBERS only, never `ownedAncestors`: `-> *` on an authored container pulls
+ * in every edge any descendant of it has, and in the `// model: no boundary`
+ * shape that container also holds services outside this subsystem — the view
+ * would draw traffic that is nobody-here's. Measured at 58 services in 11
+ * groups: 13-15 nodes and 31-39 edges per subsystem view, of which 11-12 nodes
+ * carry drill-down — the members into their own service views, the neighbouring
+ * group boxes into THEIR subsystem views.
+ */
+function boundaryLines(members) {
+    return ["", ...members.map((id) => `    include ${id} -> *, * -> ${id}`)];
+}
+/**
+ * The flat-model body: this subsystem as a box, its child subsystems as boxes
+ * inside it, its own services as leaves. Recursive, and the recursion is the
+ * point — a parent subsystem's view is otherwise one undifferentiated pile of
+ * every service beneath it.
+ *
+ * An empty child renders an empty named box, which is what the tree says: the
+ * group exists and holds nothing yet.
+ */
+function groupedBody(ctx, sub, indent) {
+    const inner = `${indent}  `;
+    const out = [`${indent}group '${subsystemLabel(sub)}' {`];
+    for (const child of childSubsystems(ctx, sub))
+        out.push(...groupedBody(ctx, child, inner));
+    for (const id of directMemberElements(ctx, sub))
+        out.push(`${inner}include ${id}`);
+    out.push(`${indent}}`);
+    return out;
+}
+/** The child subsystems one level down, ordered by name. */
+function childSubsystems(ctx, sub) {
+    return ctx.tree.subsystems
+        .filter((c) => c.path.length === sub.path.length + 1 && withinSubsystem(sub.path, c.path))
+        .sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+/** The drawn elements of the services filed in THIS directory, not in a child. */
+function directMemberElements(ctx, sub) {
+    return drawnElements(ctx, membersOf(ctx.tree, sub).filter((s) => s.subsystem.length === sub.path.length));
+}
+/** The drawn elements of every service beneath this subsystem, ordered by service id. */
+function memberElements(ctx, sub) {
+    return drawnElements(ctx, membersOf(ctx.tree, sub));
+}
+/**
+ * The element ids these services resolve to. A service the map does not draw
+ * is omitted rather than invented: the omission is already an error
+ * (`landscape.service-unmodelled`), and rendering only what the committed
+ * documents resolve keeps the output a function of committed bytes alone.
+ */
+function drawnElements(ctx, services) {
+    return services.map((s) => ctx.elementOf.get(s.id)).filter((id) => id !== undefined);
+}
+/**
+ * The boxes a nested-model view draws: this subsystem's own owning ancestor
+ * when it has one, plus the owning ancestor of every subsystem beneath it — so
+ * a parent view keeps its children's boundaries instead of flattening them
+ * into one box. Sorted and de-duplicated, because two subsystems resolve to
+ * one element only in a tree that already reports a collision.
+ */
+function ownedAncestors(ctx, sub) {
+    const found = new Set();
+    for (const candidate of ctx.tree.subsystems) {
+        if (!withinSubsystem(sub.path, candidate.path))
+            continue;
+        const owner = owningAncestor(ctx, candidate);
+        if (owner !== null)
+            found.add(owner);
+    }
+    return [...found].sort();
+}
+/**
+ * The deepest ancestor element that holds exactly this subsystem's members —
+ * or null when no element does.
+ *
+ * "Exactly" is the whole guard, and dropping it was measured on loam's own
+ * `examples/docs`: the members' longest common ancestor there is a group of
+ * five services while the subsystem holds two, so an unguarded include would
+ * generate a box labelled for the group with two of its five children drawn
+ * inside it — a diagram asserting something false, in a file the reader is
+ * told not to edit. Tightness is judged over ELEMENTS rather than over
+ * documented services: mid-adoption a group commonly holds systems no
+ * `services/<id>/` exists for yet, and counting only the documented ones would
+ * draw that same false box for the whole of an adoption.
+ *
+ * An ancestor that is itself a service's element is refused separately: one
+ * service's box containing another's is a picture of nothing.
+ */
+function owningAncestor(ctx, sub) {
+    const members = memberElements(ctx, sub);
+    if (members.length === 0)
+        return null;
+    const owned = new Set(members);
+    for (const candidate of ancestorChain(members)) {
+        if (!ctx.elementIds.has(candidate) || ctx.isServiceElement(candidate))
+            continue;
+        if (ownsExactly(ctx, candidate, owned))
+            return candidate;
+    }
+    return null;
+}
+/** The deepest common ancestor the map declares at all — the disclosure's subject. */
+function sharedAncestor(ctx, members) {
+    return ancestorChain(members).find((id) => ctx.elementIds.has(id)) ?? null;
+}
+/** The common proper ancestors of every member id, deepest first. */
+function ancestorChain(members) {
+    const segments = members.map((id) => id.split("."));
+    let common = Math.min(...segments.map((s) => s.length - 1));
+    for (let i = 0; i < common; i++) {
+        if (!segments.every((s) => s[i] === segments[0][i])) {
+            common = i;
+            break;
+        }
+    }
+    const out = [];
+    for (let depth = common; depth > 0; depth--)
+        out.push(segments[0].slice(0, depth).join("."));
+    return out;
+}
+/**
+ * Does every element beneath `ancestor` belong to this subsystem — as a
+ * member, as one of a member's own containers, or as a container of one?
+ */
+function ownsExactly(ctx, ancestor, members) {
+    const prefix = `${ancestor}.`;
+    for (const id of ctx.elementIds) {
+        if (!id.startsWith(prefix))
+            continue;
+        const claimed = [...members].some((m) => id === m || id.startsWith(`${m}.`) || m.startsWith(`${id}.`));
+        if (!claimed)
+            return false;
+    }
+    return true;
+}
+/**
+ * The landscape element standing for each service id: for every element,
+ * resolve it through the shared join, and let the SHALLOWEST element win
+ * (document order breaking ties). Shallowest, because `serviceResolver`
+ * resolves a service's own containers to the service too, and a view should
+ * include the service-level box, not whichever nested container happened to be
+ * declared first.
+ */
+function elementByService(tree, elements, resolve) {
+    const known = new Set(tree.services.map((s) => s.id));
+    const depth = (id) => id.split(".").length;
+    const out = new Map();
+    for (const e of elements) {
+        const service = resolve(e.id);
+        if (!known.has(service))
+            continue;
+        const held = out.get(service);
+        if (held === undefined || depth(e.id) < depth(held))
+            out.set(service, e.id);
+    }
+    return out;
+}
+/** Services beneath this subsystem at any depth, ordered by id — the transitive membership. */
+function membersOf(tree, sub) {
+    return [...servicesUnder(tree, sub)].sort((a, b) => (a.id < b.id ? -1 : 1));
+}
+//# sourceMappingURL=body.js.map