@ybotok/loam 0.1.0-beta.2 → 0.2.0-alpha.1

package/dist/core/repo/service-target.js

@@ -0,0 +1,153 @@
+/**
+ * Turning a name a caller typed into a name loam may join into a path.
+ *
+ * `unfiledServicePaths(docsDir, name)` spells `<docsDir>/services/<name>/`,
+ * and its parameter is `PathableService`: an unchecked name at that call site
+ * no longer compiles, and this module is where a name a caller typed EARNS the
+ * type. The history is why it exists. Six commands guard their argument with
+ * `assertServiceId` at the boundary; `validate` never did, and both of its
+ * entry points — `--service <id>` and the positional `<target>` — reached
+ * the path builder with whatever argv held. `--service ../../outside/services/x`
+ * resolved ABOVE the docs repo, and where a `spec.md` happened to sit there
+ * loam opened it, graded it, and reported its frontmatter through `--json`.
+ *
+ * The grammar alone is not the answer, and this is the whole reason this module
+ * exists rather than a call to `assertServiceId`. `services/Payment Service/`
+ * is a directory `loam list` shows, `validate --all` grades, and
+ * `service.id-invalid` calls an error nobody can fix without a rename — so it
+ * is exactly the directory somebody points `validate --service` at. Refusing on
+ * the grammar would make the one service loam complains about the one service
+ * loam cannot look at.
+ *
+ * So the enumeration answers first and the grammar answers second:
+ *
+ *   in `services/`      → the enumeration's OWN id, which is a name loam
+ *                         already reads off disk every time it lists the fleet.
+ *                         Legal or not, it exists, and joining it lands where
+ *                         the directory is.
+ *   not there, legal    → the caller's name. Nothing exists yet; the run
+ *                         continues and grades it `service.unknown`, with the
+ *                         near-miss hints that make a typo diagnosable.
+ *   not there, illegal  → refused, before any path is built.
+ *
+ * `show` and `status` already resolve against the enumeration this way. What
+ * they do not do is fall through to the grammar, which is why they answer
+ * "no such service" to a name that could never BE a service — a worse sentence
+ * for the same input.
+ */
+import { listServices } from "./repo.js";
+import { parseServiceId } from "../kernel/ids/service.js";
+import { serviceTreePath } from "../kernel/ids/dirs.js";
+import { servicePathsAt, unfiledServicePaths } from "./paths.js";
+/**
+ * The enumerated services, or the empty list when `services/` cannot be
+ * enumerated at all. The swallow is deliberate and spelled ONCE: every
+ * repository-aware resolver wants "which services exist" as context, and an
+ * unenumerable `services/` is that repository's own diagnosis
+ * (`services-missing`), never the asking check's. Six call sites each carried
+ * this try/catch in their own spelling before it lived here — which is exactly
+ * the shape docs/CODE-STYLE.md warns about: an errno fix lands in one copy and
+ * the other five keep the old behaviour. The existence probes that used to ask
+ * `existsSync(services/<id>/)` ask membership HERE for the same tolerance:
+ * `validate --feature` must run in a docs repo with no `services/` at all,
+ * where enumerating is a refusal but "does this service exist" still has the
+ * honest answer no.
+ */
+export async function enumeratedServices(docsDir, fleet) {
+    try {
+        return await listServices(docsDir, fleet);
+    }
+    catch {
+        return [];
+    }
+}
+/** The id projection of `enumeratedServices` — most membership asks want only the names. */
+export async function enumeratedServiceIds(docsDir, fleet) {
+    return (await enumeratedServices(docsDir, fleet)).map((s) => s.id);
+}
+/**
+ * The artifact paths of a service wherever it lives: the enumeration's own
+ * directory when the id exists anywhere in the tree, the unfiled root
+ * spelling otherwise — so an absent service still probes, grades
+ * (`service.unknown`) and CREATES exactly as it did when the tree was flat.
+ * This is the one bridge the ~40 former `servicePaths` call sites resolve
+ * through — and it is NOT free: without a `fleet` context every call is a
+ * fresh fleet enumeration (one readdir per directory walked plus a
+ * frontmatter read and several existence probes per service), which measured
+ * ~13 ms per call on a 120-service fleet. A call site inside a loop must
+ * thread the command's `FleetContext`; a caller that already holds a
+ * `ServiceEntry` should spell `servicePathsAt(entry.dir)` directly and pay
+ * nothing.
+ */
+/**
+ * Where a service sits under `services/`, repo-relative and WITHOUT a trailing
+ * slash — for a message that names an existing directory to a reader.
+ *
+ * The join it replaces is `services/${id}`, which is right for an unfiled
+ * service and wrong for every filed one; `paths.ts` states the same rule for
+ * artifact paths and this is its display sibling. A name the enumeration does
+ * not answer to falls back to the unfiled spelling, which is the only honest
+ * answer: there is no directory to point at, and that is usually what the
+ * message is about.
+ */
+export async function serviceTreePathOf(docsDir, service, fleet) {
+    const entry = (await enumeratedServices(docsDir, fleet)).find((s) => s.id === service);
+    return entry === undefined ? `services/${service}` : serviceTreePath(entry);
+}
+export async function locateServicePaths(docsDir, service, fleet) {
+    const entry = (await enumeratedServices(docsDir, fleet)).find((s) => s.id === service);
+    return entry === undefined ? unfiledServicePaths(docsDir, service) : servicePathsAt(entry.dir);
+}
+export async function resolveServiceTarget(docsDir, name, label, fleet) {
+    // The enumeration is asked first, and its answer is the value that travels
+    // on: `entry.id` rather than `name`. They are equal as strings, and only one
+    // of them carries the fact that a `readdir` produced it. The resolved `dir`
+    // travels too, so a caller that goes on to read artifacts can spell
+    // `servicePathsAt(dir)` without a second enumeration; it is absent exactly
+    // when the name resolved by grammar alone — nothing exists to point at.
+    const entry = (await listServices(docsDir, fleet)).find((s) => s.id === name);
+    if (entry !== undefined)
+        return { ok: true, id: entry.id, dir: entry.dir };
+    return parseServiceId(name, label);
+}
+/**
+ * The same resolution for a name a DOCUMENT declared — an edge target's
+ * `metadata { service '…' }` binding, or its title standing in for one — where
+ * the caller needs an answer instead of a refusal: which enumerated directory,
+ * if any, does this text name?
+ *
+ * The enumeration is the fleet's `services/` plus whatever directory names the
+ * caller has already read for itself — a feature's own `specs/<svc>/`, the only
+ * place a service the feature INTRODUCES has a directory at all. There is
+ * deliberately no grammar arm here, in either direction: `services/Payment
+ * Service/` keeps resolving for the banner's reason, and a legal-looking name
+ * that matches no directory has no living file anywhere, so the caller's
+ * business is to grade it absent — never to build a path from it.
+ *
+ * The index is built on the first ask, not at construction: coherence asks per
+ * op-edge and features routinely carry none, so the enumeration only runs once
+ * an answer matters. A repo whose `services/` cannot be enumerated resolves
+ * only the caller's own names — every living probe would have found nothing
+ * there anyway, and `services-missing` is that repository's diagnosis, not
+ * this document's.
+ */
+export function enumeratedServiceIndex(docsDir, known, fleet) {
+    let index;
+    return async (name) => {
+        if (index === undefined) {
+            index = new Map();
+            for (const id of known)
+                index.set(id, id);
+            try {
+                for (const s of await listServices(docsDir, fleet))
+                    index.set(s.id, s.id);
+            }
+            catch {
+                // The docblock's last paragraph: no enumerable services/ means the
+                // fleet half of the index is empty, not that the question is an error.
+            }
+        }
+        return index.get(name);
+    };
+}
+//# sourceMappingURL=service-target.js.map

package/dist/core/repo/service-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-target.js","sourceRoot":"","sources":["../../../src/core/repo/service-target.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Turning a name a caller typed into a name loam may join into a path.\n *\n * `unfiledServicePaths(docsDir, name)` spells `<docsDir>/services/<name>/`,\n * and its parameter is `PathableService`: an unchecked name at that call site\n * no longer compiles, and this module is where a name a caller typed EARNS the\n * type. The history is why it exists. Six commands guard their argument with\n * `assertServiceId` at the boundary; `validate` never did, and both of its\n * entry points — `--service <id>` and the positional `<target>` — reached\n * the path builder with whatever argv held. `--service ../../outside/services/x`\n * resolved ABOVE the docs repo, and where a `spec.md` happened to sit there\n * loam opened it, graded it, and reported its frontmatter through `--json`.\n *\n * The grammar alone is not the answer, and this is the whole reason this module\n * exists rather than a call to `assertServiceId`. `services/Payment Service/`\n * is a directory `loam list` shows, `validate --all` grades, and\n * `service.id-invalid` calls an error nobody can fix without a rename — so it\n * is exactly the directory somebody points `validate --service` at. Refusing on\n * the grammar would make the one service loam complains about the one service\n * loam cannot look at.\n *\n * So the enumeration answers first and the grammar answers second:\n *\n *   in `services/`      → the enumeration's OWN id, which is a name loam\n *                         already reads off disk every time it lists the fleet.\n *                         Legal or not, it exists, and joining it lands where\n *                         the directory is.\n *   not there, legal    → the caller's name. Nothing exists yet; the run\n *                         continues and grades it `service.unknown`, with the\n *                         near-miss hints that make a typo diagnosable.\n *   not there, illegal  → refused, before any path is built.\n *\n * `show` and `status` already resolve against the enumeration this way. What\n * they do not do is fall through to the grammar, which is why they answer\n * \"no such service\" to a name that could never BE a service — a worse sentence\n * for the same input.\n */\nimport { listServices } from \"./repo.js\";\nimport { parseServiceId, type PathableService, type RawServiceId } from \"../kernel/ids/service.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { serviceTreePath, type DocsDir, type ServiceDir } from \"../kernel/ids/dirs.js\";\nimport { servicePathsAt, unfiledServicePaths, type ServicePaths } from \"./paths.js\";\nimport type { ServiceEntry } from \"./entries.js\";\n\nexport type ServiceTarget =\n  | { readonly ok: true; readonly id: RawServiceId; readonly dir?: ServiceDir }\n  | { readonly ok: false; readonly problem: string };\n\n/**\n * The enumerated services, or the empty list when `services/` cannot be\n * enumerated at all. The swallow is deliberate and spelled ONCE: every\n * repository-aware resolver wants \"which services exist\" as context, and an\n * unenumerable `services/` is that repository's own diagnosis\n * (`services-missing`), never the asking check's. Six call sites each carried\n * this try/catch in their own spelling before it lived here — which is exactly\n * the shape docs/CODE-STYLE.md warns about: an errno fix lands in one copy and\n * the other five keep the old behaviour. The existence probes that used to ask\n * `existsSync(services/<id>/)` ask membership HERE for the same tolerance:\n * `validate --feature` must run in a docs repo with no `services/` at all,\n * where enumerating is a refusal but \"does this service exist\" still has the\n * honest answer no.\n */\nexport async function enumeratedServices(\n  docsDir: DocsDir,\n  fleet?: FleetContext,\n): Promise<ServiceEntry[]> {\n  try {\n    return await listServices(docsDir, fleet);\n  } catch {\n    return [];\n  }\n}\n\n/** The id projection of `enumeratedServices` — most membership asks want only the names. */\nexport async function enumeratedServiceIds(\n  docsDir: DocsDir,\n  fleet?: FleetContext,\n): Promise<RawServiceId[]> {\n  return (await enumeratedServices(docsDir, fleet)).map((s) => s.id);\n}\n\n/**\n * The artifact paths of a service wherever it lives: the enumeration's own\n * directory when the id exists anywhere in the tree, the unfiled root\n * spelling otherwise — so an absent service still probes, grades\n * (`service.unknown`) and CREATES exactly as it did when the tree was flat.\n * This is the one bridge the ~40 former `servicePaths` call sites resolve\n * through — and it is NOT free: without a `fleet` context every call is a\n * fresh fleet enumeration (one readdir per directory walked plus a\n * frontmatter read and several existence probes per service), which measured\n * ~13 ms per call on a 120-service fleet. A call site inside a loop must\n * thread the command's `FleetContext`; a caller that already holds a\n * `ServiceEntry` should spell `servicePathsAt(entry.dir)` directly and pay\n * nothing.\n */\n/**\n * Where a service sits under `services/`, repo-relative and WITHOUT a trailing\n * slash — for a message that names an existing directory to a reader.\n *\n * The join it replaces is `services/${id}`, which is right for an unfiled\n * service and wrong for every filed one; `paths.ts` states the same rule for\n * artifact paths and this is its display sibling. A name the enumeration does\n * not answer to falls back to the unfiled spelling, which is the only honest\n * answer: there is no directory to point at, and that is usually what the\n * message is about.\n */\nexport async function serviceTreePathOf(\n  docsDir: DocsDir,\n  service: string,\n  fleet?: FleetContext,\n): Promise<string> {\n  const entry = (await enumeratedServices(docsDir, fleet)).find((s) => s.id === service);\n  return entry === undefined ? `services/${service}` : serviceTreePath(entry);\n}\n\nexport async function locateServicePaths(\n  docsDir: DocsDir,\n  service: PathableService,\n  fleet?: FleetContext,\n): Promise<ServicePaths> {\n  const entry = (await enumeratedServices(docsDir, fleet)).find((s) => s.id === service);\n  return entry === undefined ? unfiledServicePaths(docsDir, service) : servicePathsAt(entry.dir);\n}\n\nexport async function resolveServiceTarget(\n  docsDir: DocsDir,\n  name: string,\n  label: string,\n  fleet?: FleetContext,\n): Promise<ServiceTarget> {\n  // The enumeration is asked first, and its answer is the value that travels\n  // on: `entry.id` rather than `name`. They are equal as strings, and only one\n  // of them carries the fact that a `readdir` produced it. The resolved `dir`\n  // travels too, so a caller that goes on to read artifacts can spell\n  // `servicePathsAt(dir)` without a second enumeration; it is absent exactly\n  // when the name resolved by grammar alone — nothing exists to point at.\n  const entry = (await listServices(docsDir, fleet)).find((s) => s.id === name);\n  if (entry !== undefined) return { ok: true, id: entry.id, dir: entry.dir };\n  return parseServiceId(name, label);\n}\n\n/**\n * The same resolution for a name a DOCUMENT declared — an edge target's\n * `metadata { service '…' }` binding, or its title standing in for one — where\n * the caller needs an answer instead of a refusal: which enumerated directory,\n * if any, does this text name?\n *\n * The enumeration is the fleet's `services/` plus whatever directory names the\n * caller has already read for itself — a feature's own `specs/<svc>/`, the only\n * place a service the feature INTRODUCES has a directory at all. There is\n * deliberately no grammar arm here, in either direction: `services/Payment\n * Service/` keeps resolving for the banner's reason, and a legal-looking name\n * that matches no directory has no living file anywhere, so the caller's\n * business is to grade it absent — never to build a path from it.\n *\n * The index is built on the first ask, not at construction: coherence asks per\n * op-edge and features routinely carry none, so the enumeration only runs once\n * an answer matters. A repo whose `services/` cannot be enumerated resolves\n * only the caller's own names — every living probe would have found nothing\n * there anyway, and `services-missing` is that repository's diagnosis, not\n * this document's.\n */\nexport function enumeratedServiceIndex(\n  docsDir: DocsDir,\n  known: readonly RawServiceId[],\n  fleet?: FleetContext,\n): (name: string) => Promise<RawServiceId | undefined> {\n  let index: Map<string, RawServiceId> | undefined;\n  return async (name: string): Promise<RawServiceId | undefined> => {\n    if (index === undefined) {\n      index = new Map<string, RawServiceId>();\n      for (const id of known) index.set(id, id);\n      try {\n        for (const s of await listServices(docsDir, fleet)) index.set(s.id, s.id);\n      } catch {\n        // The docblock's last paragraph: no enumerable services/ means the\n        // fleet half of the index is empty, not that the question is an error.\n      }\n    }\n    return index.get(name);\n  };\n}\n"]}

package/dist/core/repo/state.js

@@ -0,0 +1,58 @@
+/**
+ * Is there a docs repo there at all?
+ *
+ * Three answers, not two: missing, present-but-empty, and ok. The middle one
+ * exists because a freshly cloned docs repo whose `services/` git never tracked
+ * looks identical to a directory nobody wired — and the fix differs.
+ */
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+export function docsRepoState(docsDir) {
+    const path = docsDir;
+    let isDir = false;
+    try {
+        isDir = statSync(path).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (!isDir)
+        return { kind: "missing", path };
+    return { kind: existsSync(join(path, "services")) ? "ok" : "no-services", path };
+}
+/**
+ * The docs repo is not there. Thrown rather than returned because every caller
+ * of the enumeration wants the same thing — to stop — and a `[]` return is the
+ * bug this closes. `message` is written for a human at a terminal: the CLI's
+ * top-level handler prints it verbatim, and commands that catch it report
+ * `repository-unavailable`.
+ */
+export class DocsRepoUnavailableError extends Error {
+    state;
+    constructor(state, message) {
+        super(message);
+        this.state = state;
+        this.name = "DocsRepoUnavailableError";
+    }
+}
+/**
+ * Refuse to enumerate a docs repo that is not one. `allow` names the states the
+ * caller can honestly survive: features/ may be absent from a real docs repo
+ * (nothing is in flight yet), so feature enumeration only insists the docs repo
+ * EXISTS, while service enumeration insists it is shaped like a docs repo — a
+ * `services/` directory is what makes it one.
+ */
+export function requireDocsRepo(docsDir, allow) {
+    const state = docsRepoState(docsDir);
+    if (allow.includes(state.kind))
+        return;
+    if (state.kind === "missing") {
+        throw new DocsRepoUnavailableError(state, `The configured docs repo does not exist: ${state.path}. ` +
+            "Fix `docsDir` in loam.json, clone the docs repo there, " +
+            "or run `loam init --docs <dir> --create` to make a new one.");
+    }
+    throw new DocsRepoUnavailableError(state, `${state.path} is not a docs repo — it has no services/ directory. ` +
+        "Point `docsDir` in loam.json at the shared docs repo, " +
+        "or run `loam init --docs <dir> --create` to make one.");
+}
+//# sourceMappingURL=state.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/core/repo/state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA8BjC,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,IAAI,GAAG,OAAO,CAAC;IACrB,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,CAAC;QACH,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,GAAG,KAAK,CAAC;IAChB,CAAC;IACD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC7C,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,EAAE,IAAI,EAAE,CAAC;AACnF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAEtC,KAAK;IADhB,YACW,KAAoB,EAC7B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;qBAHN,KAAK;QAId,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,KAAqB;IACpE,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO;IACvC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,wBAAwB,CAChC,KAAK,EACL,4CAA4C,KAAK,CAAC,IAAI,IAAI;YACxD,yDAAyD;YACzD,6DAA6D,CAChE,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,wBAAwB,CAChC,KAAK,EACL,GAAG,KAAK,CAAC,IAAI,uDAAuD;QAClE,wDAAwD;QACxD,uDAAuD,CAC1D,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Is there a docs repo there at all?\n *\n * Three answers, not two: missing, present-but-empty, and ok. The middle one\n * exists because a freshly cloned docs repo whose `services/` git never tracked\n * looks identical to a directory nobody wired — and the fix differs.\n */\nimport { existsSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\n/* ------------------------------------------------------------------ */\n/* Is there a docs repo there at all?                                  */\n/* ------------------------------------------------------------------ */\n\n/**\n * What is actually at `docsDir`. Three answers, because they point at three\n * different fixes and the enumeration below used to give all of them the same\n * one — an empty list:\n *\n *  - `missing`     — nothing there (or not a directory): `docsDir` in loam.json\n *                    is wrong, or the docs repo was never cloned;\n *  - `no-services` — a directory, but with no `services/`: it is some other\n *                    directory, most often the service repo itself after a typo;\n *  - `ok`          — a docs repo. `services/` may still be EMPTY, and that is a\n *                    legitimate state: a docs repo before the first `loam adopt`.\n *\n * \"Empty fleet\" and \"wrong path\" are the same output only if nobody asks this\n * question, and a green `loam list` over a docsDir that does not exist is worse\n * than a red one: it says the fleet is fine.\n */\nexport type DocsRepoKind = \"missing\" | \"no-services\" | \"ok\";\n\nexport interface DocsRepoState {\n  kind: DocsRepoKind;\n  /** The path examined, so a caller can quote it without re-deriving it. */\n  path: string;\n}\n\nexport function docsRepoState(docsDir: string): DocsRepoState {\n  const path = docsDir;\n  let isDir = false;\n  try {\n    isDir = statSync(path).isDirectory();\n  } catch {\n    isDir = false;\n  }\n  if (!isDir) return { kind: \"missing\", path };\n  return { kind: existsSync(join(path, \"services\")) ? \"ok\" : \"no-services\", path };\n}\n\n/**\n * The docs repo is not there. Thrown rather than returned because every caller\n * of the enumeration wants the same thing — to stop — and a `[]` return is the\n * bug this closes. `message` is written for a human at a terminal: the CLI's\n * top-level handler prints it verbatim, and commands that catch it report\n * `repository-unavailable`.\n */\nexport class DocsRepoUnavailableError extends Error {\n  constructor(\n    readonly state: DocsRepoState,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"DocsRepoUnavailableError\";\n  }\n}\n\n/**\n * Refuse to enumerate a docs repo that is not one. `allow` names the states the\n * caller can honestly survive: features/ may be absent from a real docs repo\n * (nothing is in flight yet), so feature enumeration only insists the docs repo\n * EXISTS, while service enumeration insists it is shaped like a docs repo — a\n * `services/` directory is what makes it one.\n */\nexport function requireDocsRepo(docsDir: string, allow: DocsRepoKind[]): void {\n  const state = docsRepoState(docsDir);\n  if (allow.includes(state.kind)) return;\n  if (state.kind === \"missing\") {\n    throw new DocsRepoUnavailableError(\n      state,\n      `The configured docs repo does not exist: ${state.path}. ` +\n        \"Fix `docsDir` in loam.json, clone the docs repo there, \" +\n        \"or run `loam init --docs <dir> --create` to make a new one.\",\n    );\n  }\n  throw new DocsRepoUnavailableError(\n    state,\n    `${state.path} is not a docs repo — it has no services/ directory. ` +\n      \"Point `docsDir` in loam.json at the shared docs repo, \" +\n      \"or run `loam init --docs <dir> --create` to make one.\",\n  );\n}\n"]}

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

@@ -0,0 +1,52 @@
+/**
+ * Name resolution over a walked tree — the questions every `loam subsystem`
+ * verb asks before it acts: what does this name denote, what sits beneath a
+ * subsystem, and which names come close to a miss. One module so `move`,
+ * `rm`, `new` and `history` cannot grow four private spellings of "the flat
+ * namespace" — the walk already enforces one namespace, and resolution must
+ * read it the same way.
+ */
+import { closeIds } from "../../c4/arch.js";
+/**
+ * Resolve one name against the flat namespace. Services win a tie on
+ * purpose: a tie IS `subsystem.name-collision`, already an error finding,
+ * and while it stands the service reading keeps every id-addressed command
+ * coherent.
+ */
+export function findInTree(tree, name) {
+    const service = tree.services.find((s) => s.id === name);
+    if (service !== undefined)
+        return { kind: "service", service };
+    const subsystem = tree.subsystems.find((s) => s.name === name);
+    if (subsystem !== undefined)
+        return { kind: "subsystem", subsystem };
+    return null;
+}
+/** Every name the flat namespace holds — service ids and subsystem names together. */
+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);
+}
+/**
+ * Does the subsystem at `subPath` contain `path` — itself, or anywhere beneath
+ * it? The move-into-own-subtree refusal. The parameter is the name chain, not
+ * a `SubsystemEntry`, because a chain is all this comparison reads — the one
+ * caller outside this module (`move`) has a chain it just composed and no
+ * entry to hand, and a structural parameter it never reads would force a
+ * placeholder there.
+ */
+export function withinSubsystem(subPath, path) {
+    return subPath.length <= path.length && subPath.every((name, i) => path[i] === name);
+}
+/** Services anywhere beneath a subsystem — the transitive membership the views and counts share. */
+export function servicesUnder(tree, sub) {
+    return tree.services.filter((s) => sub.path.every((name, i) => s.subsystem[i] === name));
+}
+/** Child subsystems anywhere beneath one — `rm`'s other half of "empty". */
+export function subsystemsUnder(tree, sub) {
+    return tree.subsystems.filter((c) => c !== sub && withinSubsystem(sub.path, c.path));
+}
+//# sourceMappingURL=find.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,64 @@
+/**
+ * Directory-entry questions the enumerations share, symlinks followed.
+ *
+ * Moved here from `repo/repo.ts` when the tree walk arrived: the walk and the
+ * feature enumeration must answer "what IS this entry" identically, and the
+ * 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 { readdir } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * What a directory entry IS, following a symlink to find out.
+ *
+ * `readdir(withFileTypes)` does not follow symlinks: for a symlink `Dirent`
+ * every `isDirectory()`/`isFile()` is false, whatever it points at. That made a
+ * symlinked `services/<id>/` or `features/<id>/` vanish from every enumeration
+ * at once — `list`, `validate --all`, the fleet gate — with no diagnostic
+ * anywhere, which is the one outcome a shared docs repo cannot survive: the
+ * fleet gate reported a service that is not there as fine because it never saw
+ * it. Composing a docs repo out of symlinks (a worktree, a submodule, one
+ * service's directory shared between two checkouts) is legitimate, so they are
+ * FOLLOWED rather than refused. A dangling link stats as nothing and is skipped
+ * exactly as an absent directory is — it is not a service, and saying so would
+ * mean inventing an entry to hang the complaint on.
+ */
+export function entryIs(dir, e, want) {
+    if (!e.isSymbolicLink())
+        return want === "dir" ? e.isDirectory() : e.isFile();
+    try {
+        const s = statSync(join(dir, e.name));
+        return want === "dir" ? s.isDirectory() : s.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Markdown files sitting directly in `dir`, sorted, as full paths — the ADR
+ * corpus, and the only place that rule is spelled. Symlinks are resolved
+ * through `entryIs`, which is the whole reason this is shared: `show` once kept
+ * a second copy that tested `Dirent.isFile()` itself — always false for a
+ * symlink, whatever it points at — so a docs repo composed of symlinks (the
+ * layout `entryIs` above exists to support) had `loam list` and `loam show`
+ * reporting different ADR counts for the same service. One rule, one answer.
+ *
+ * The list, not the count, is the primitive: the link check reads these same
+ * files, and a corpus that disagreed with the count would grade documents the
+ * fleet listing says are not there.
+ */
+export async function markdownFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+        .filter((e) => e.name.endsWith(".md") && entryIs(dir, e, "file"))
+        .map((e) => join(dir, e.name))
+        .sort();
+}
+/** How many markdown files sit directly in `dir` — the ADR count, over the corpus above. */
+export async function countMarkdown(dir) {
+    return (await markdownFiles(dir)).length;
+}
+//# sourceMappingURL=fs.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,61 @@
+/**
+ * The subsystem marker: `subsystem.yaml`, the one file that makes a directory
+ * under `services/` a GROUP rather than a service.
+ *
+ * Presence classifies; content is metadata. The walk decides what a directory
+ * IS from the marker's existence alone, so a marker that cannot be read still
+ * classifies its directory as a subsystem — anything else would let a corrupt
+ * byte reinterpret a whole subtree as a service and swallow the fleet beneath
+ * it, the exact silent-shrink the three-way classification exists to refuse.
+ * An unreadable marker is reported as exactly one `subsystem.invalid` finding
+ * instead (`walk.ts` emits it from the `invalid` field here).
+ *
+ * The defensive-read shape is `core/permissions/permissions.ts`'s: every wrong
+ * shape is an `invalid` sentence naming what is wrong, never a throw — this is
+ * a read model, and a marker somebody hand-edited badly must not take down the
+ * enumeration that would report it.
+ */
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+import { isRecord } from "../../kernel/records.js";
+/** The marker's filename — spelled here and nowhere else. */
+export const SUBSYSTEM_MARKER = "subsystem.yaml";
+/**
+ * Read one marker. An EMPTY file is a valid marker with no metadata — the
+ * marker's job is done by existing, and `title`/`description`/`owner` are all
+ * optional. A `members` key is invalid on purpose: placement is recorded
+ * exactly once, in the directory itself, and a membership list would be a
+ * second copy that merges, drifts and lies (SCHEMA.md's marker-not-manifest
+ * rule).
+ */
+export async function readSubsystemMarker(path) {
+    let doc;
+    try {
+        doc = parseYaml(await readFile(path, "utf8"));
+    }
+    catch (e) {
+        return { invalid: e instanceof Error ? e.message : String(e) };
+    }
+    if (doc === null || doc === undefined)
+        return {};
+    if (!isRecord(doc))
+        return { invalid: "the document is not a mapping" };
+    if (doc["members"] !== undefined) {
+        return {
+            invalid: "it declares `members` — a subsystem's members are the service directories inside it, " +
+                "recorded exactly once, in the directory itself; a list here would be a second copy that drifts",
+        };
+    }
+    for (const field of ["title", "description", "owner"]) {
+        const value = doc[field];
+        if (value !== undefined && typeof value !== "string") {
+            return { invalid: `\`${field}\` is not a string` };
+        }
+    }
+    return {
+        ...(typeof doc["title"] === "string" ? { title: doc["title"] } : {}),
+        ...(typeof doc["description"] === "string" ? { description: doc["description"] } : {}),
+        ...(typeof doc["owner"] === "string" ? { owner: doc["owner"] } : {}),
+    };
+}
+//# sourceMappingURL=marker.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"marker.js","sourceRoot":"","sources":["../../../../src/core/repo/tree/marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,gBAAgB,GAAG,gBAAgB,CAAC;AAUjD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAAY;IACpD,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,SAAS,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,OAAO,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACjD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAAC;IACxE,IAAI,GAAG,CAAC,SAAS,CAAC,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO;YACL,OAAO,EACL,uFAAuF;gBACvF,gGAAgG;SACnG,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAU,EAAE,CAAC;QAC/D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACrD,OAAO,EAAE,OAAO,EAAE,KAAK,KAAK,oBAAoB,EAAE,CAAC;QACrD,CAAC;IACH,CAAC;IACD,OAAO;QACL,GAAG,CAAC,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,GAAG,CAAC,OAAO,GAAG,CAAC,aAAa,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtF,GAAG,CAAC,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACrE,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The subsystem marker: `subsystem.yaml`, the one file that makes a directory\n * under `services/` a GROUP rather than a service.\n *\n * Presence classifies; content is metadata. The walk decides what a directory\n * IS from the marker's existence alone, so a marker that cannot be read still\n * classifies its directory as a subsystem — anything else would let a corrupt\n * byte reinterpret a whole subtree as a service and swallow the fleet beneath\n * it, the exact silent-shrink the three-way classification exists to refuse.\n * An unreadable marker is reported as exactly one `subsystem.invalid` finding\n * instead (`walk.ts` emits it from the `invalid` field here).\n *\n * The defensive-read shape is `core/permissions/permissions.ts`'s: every wrong\n * shape is an `invalid` sentence naming what is wrong, never a throw — this is\n * a read model, and a marker somebody hand-edited badly must not take down the\n * enumeration that would report it.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { parse as parseYaml } from \"yaml\";\nimport { isRecord } from \"../../kernel/records.js\";\n\n/** The marker's filename — spelled here and nowhere else. */\nexport const SUBSYSTEM_MARKER = \"subsystem.yaml\";\n\nexport interface SubsystemMeta {\n  title?: string;\n  description?: string;\n  owner?: string;\n  /** Why the file could not be read as subsystem metadata, when it could not. */\n  invalid?: string;\n}\n\n/**\n * Read one marker. An EMPTY file is a valid marker with no metadata — the\n * marker's job is done by existing, and `title`/`description`/`owner` are all\n * optional. A `members` key is invalid on purpose: placement is recorded\n * exactly once, in the directory itself, and a membership list would be a\n * second copy that merges, drifts and lies (SCHEMA.md's marker-not-manifest\n * rule).\n */\nexport async function readSubsystemMarker(path: string): Promise<SubsystemMeta> {\n  let doc: unknown;\n  try {\n    doc = parseYaml(await readFile(path, \"utf8\"));\n  } catch (e) {\n    return { invalid: e instanceof Error ? e.message : String(e) };\n  }\n  if (doc === null || doc === undefined) return {};\n  if (!isRecord(doc)) return { invalid: \"the document is not a mapping\" };\n  if (doc[\"members\"] !== undefined) {\n    return {\n      invalid:\n        \"it declares `members` — a subsystem's members are the service directories inside it, \" +\n        \"recorded exactly once, in the directory itself; a list here would be a second copy that drifts\",\n    };\n  }\n  for (const field of [\"title\", \"description\", \"owner\"] as const) {\n    const value = doc[field];\n    if (value !== undefined && typeof value !== \"string\") {\n      return { invalid: `\\`${field}\\` is not a string` };\n    }\n  }\n  return {\n    ...(typeof doc[\"title\"] === \"string\" ? { title: doc[\"title\"] } : {}),\n    ...(typeof doc[\"description\"] === \"string\" ? { description: doc[\"description\"] } : {}),\n    ...(typeof doc[\"owner\"] === \"string\" ? { owner: doc[\"owner\"] } : {}),\n  };\n}\n"]}

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

@@ -0,0 +1,172 @@
+/**
+ * The generated views file: `architecture/subsystems.likec4`, one LikeC4 view
+ * per subsystem enumerating the services beneath it. GENERATED, never
+ * authored — authored bytes stay authored (archive's verbatim-splice promise),
+ * so the tree is mirrored into a file of its own that `loam subsystem sync`
+ * owns outright, and staleness against the tree is a byte compare
+ * (`subsystem.views-stale` in `validate --all`), never a parse: a spike
+ * confirmed a views-only document does NOT parse standalone (its `include`
+ * lines reference elements the landscape defines), so nothing in loam ever
+ * loads this file (and rule 26 does not change that: this file is GENERATED and
+ * holds STATIC views, whose contents loam may not read in any document) — only
+ * the LikeC4 renderer, which merges the whole `architecture/` project per
+ * likec4.config.json, resolves it.
+ *
+ * The output is deterministic and line-oriented, and both halves are the
+ * contract: subsystems sorted by path, members sorted by id, ONE `include`
+ * per line — so two concurrent moves into different groups touch different
+ * lines and git merges the file without intervention, exactly as the
+ * service-grouped landscape splice already achieves. Byte-reproducible on any
+ * machine: no timestamps, no absolute paths, no readdir-order dependence (the
+ * walk sorts, and every list is re-sorted here). Plain lexicographic sorts on
+ * purpose — the ids' own grammar is ASCII, an INVALID name is still ordered
+ * deterministically, and `compareIds`' numeric tokenizing lives in `repo/`,
+ * which this package must not import (`walk.ts` says why the edge only points
+ * the other way).
+ *
+ * Membership is TRANSITIVE: a subsystem's view includes every service beneath
+ * it at any depth, so a parent's view is the whole group's map rather than an
+ * empty frame around its children. An empty view body is legal LikeC4 (same
+ * spike), so an empty subsystem renders as one — `subsystem new` must be
+ * usable before anything moves in.
+ *
+ * Include lines name the landscape ELEMENT id, resolved through the same
+ * element→service join `validate` uses (`serviceResolver`: explicit
+ * `metadata { service }` binding first, then a title naming a real service) —
+ * because element ids in real landscapes are not service ids, and a view of
+ * raw service ids would silently render empty for every such fleet. A member
+ * with no landscape element is omitted from the includes: the omission is
+ * already an error (`landscape.service-unmodelled`), and rendering only what
+ * the committed landscape resolves keeps the output a function of committed
+ * bytes alone.
+ */
+import {} from "../../c4/likec4.js";
+import { serviceResolver } from "../../c4/resolve/service.js";
+import { servicesUnder } from "./find.js";
+/**
+ * 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.
+ */
+const HEADER = "// generated by loam — 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";
+/**
+ * Render the views file for a walked tree, or null when the tree has no
+ * subsystems — the file must then be ABSENT, so a flat fleet never carries a
+ * generated artifact that says nothing.
+ */
+export function renderSubsystemViews(tree, elements) {
+    if (tree.subsystems.length === 0)
+        return null;
+    const elementOf = elementByService(tree, elements);
+    const lines = [HEADER, "views {"];
+    const subsystems = [...tree.subsystems].sort((a, b) => (pathKey(a) < pathKey(b) ? -1 : 1));
+    for (const [i, sub] of subsystems.entries()) {
+        if (i > 0)
+            lines.push("");
+        lines.push(`  // services/${pathKey(sub)}`);
+        lines.push(`  view ${subsystemViewId(sub)} {`);
+        for (const member of membersOf(tree, sub)) {
+            const element = elementOf.get(member.id);
+            if (element !== undefined)
+                lines.push(`    include ${element}`);
+        }
+        lines.push("  }");
+    }
+    lines.push("}");
+    return lines.join("\n") + "\n";
+}
+/**
+ * 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) {
+    const known = new Set(tree.services.map((s) => s.id));
+    const resolve = serviceResolver(elements, known);
+    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));
+}
+/** The sort key and the comment spelling: the subsystem's path from services/, joined. */
+function pathKey(sub) {
+    return sub.path.join("/");
+}
+/**
+ * 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.
+ */
+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("__")}`;
+}
+/**
+ * Does the file on disk already SAY what `renderSubsystemViews` renders?
+ *
+ * The generator above only ever emits LF. `core.autocrlf=true` is Git for
+ * Windows' installer default and a docs repo ships no `.gitattributes`, so an
+ * ordinary Windows clone hands the file back with CRLF and not one fact
+ * changed. Four call sites asked this question with a byte equality and all
+ * four answered "stale" on such a clone: `loam validate` reported an error,
+ * `loam subsystem sync` reported `updated` and rewrote with LF, git then showed
+ * the file permanently modified, and the next checkout restored the CRLF. That
+ * is a loop rather than a diagnosis, which is why the comparison lives here
+ * now — the module that mints the bytes is the one that owes an answer about
+ * them, and three near-copies of this rule would go stale one at a time.
+ *
+ * Still never a parse: a views-only document does not parse standalone, and no
+ * check anywhere reads this file's content. The narrowing is from BYTES to
+ * CONTENT, which is what `subsystem.views-stale`'s own message ("does not match
+ * the tree") already claims. The symmetric cost is accepted and is the one
+ * `core/verify/pins/pin.ts` documents for `pinnedDigest`: a pure line-ending
+ * change is invisible, correctly, because it is not a change to what the file
+ * says.
+ *
+ * `null` is carried through as itself rather than collapsing into `""`: absent,
+ * must-be-absent and present-but-different are three distinct states with three
+ * distinct messages, and a fleet whose views file does not exist is not a fleet
+ * whose views file is blank.
+ */
+export function viewsAgree(actual, expected) {
+    const lf = (text) => (text === null ? null : text.replace(/\r\n|\r/g, "\n"));
+    return lf(actual) === lf(expected);
+}
+//# sourceMappingURL=views.js.map