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

package/dist/core/c4/prefetch/fleet.js

@@ -0,0 +1,142 @@
+/**
+ * Every service model ONE command invocation has read, memoised — the fleet
+ * map, each model's shape, each per-service project, and each assembled
+ * `ServiceModel`.
+ *
+ * A package of its own rather than four more maps on `core/fleet-context.ts`,
+ * and the seam is the one that module's banner already states for its leaves:
+ * the rules being memoised here are `../service-model/`'s (which shape a file
+ * has, which documents its project holds, how a failed batch degrades), and a
+ * memo whose rules live an import away is a memo somebody fills under the wrong
+ * key. The read index keeps what it owns — the document parses, the
+ * enumerations — and hands them in. It also keeps that file under its line
+ * limit, which is the honest second reason: this axis is four memos and a batch
+ * plan, and it arrived at a module that was already 336 lines of other axes.
+ *
+ * The direction is one-way and load-bearing: `fleet-context.ts` imports this,
+ * never the reverse. Everything this class needs from the read index arrives as
+ * a function on the request (`ModelRead`), so nothing here knows that a
+ * FleetContext exists — which is what keeps `core/` → `core/c4/` acyclic.
+ *
+ * REQUEST-SCOPED exactly as `FleetContext` is: one instance per invocation,
+ * dropped when the command finishes. No module-level state, so a later run
+ * cannot observe an earlier one's answer, and a `chdir` between two tests
+ * cannot leak one docs repo into the next.
+ */
+import { resolve } from "node:path";
+import { loadArchitecture } from "../project/architecture.js";
+import { asLoadedDoc, loadProject } from "../project/load.js";
+import { modelProjectDocuments } from "../service-model/documents.js";
+import { batchServiceProjects, serviceModelAt, } from "../service-model/load.js";
+import { readModelShape, readModelShapes } from "../service-model/shape.js";
+/** One in-flight promise per key, created on first ask — the memo idiom, once. */
+function memo(store, k, make) {
+    let pending = store.get(k);
+    if (pending === undefined) {
+        pending = make();
+        store.set(k, pending);
+    }
+    return pending;
+}
+export class ServiceModels {
+    deps;
+    architectures = new Map();
+    shapeOf = new Map();
+    projects = new Map();
+    models = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * The fleet map as the PROJECT it is (`../project/architecture.ts`). Read
+     * twice over for every service now rather than once for the run — it is the
+     * gate on whether an extending model can be read at all, and the other half
+     * of the diff that decides what such a model actually declares — so the memo
+     * is what keeps a fleet run to one parse of it.
+     *
+     * Filled ONLY when somebody asks. `model` below hands `loadServiceModel` a
+     * thunk rather than an awaited value, so a fleet whose models all stand alone
+     * never parses this project at all — a standalone model is read as one file,
+     * and paying for the map (and inheriting its failures) for `loam show` or the
+     * adopt brief was cost and risk for an answer nobody used.
+     */
+    architecture(docsDir) {
+        return memo(this.architectures, resolve(docsDir), () => loadArchitecture(docsDir));
+    }
+    /**
+     * Which shape each model has, keyed by resolved path — ONE read of each
+     * file's bytes per invocation, however many questions are asked of it.
+     *
+     * The bulk form is the primary one because every caller asks in bulk: the
+     * fleet target needs the shapes of the WHOLE enumeration before it can grade
+     * a single renderer-file finding, and the prefetch needs them before it can
+     * decide which workspace each model belongs in.
+     */
+    async shapes(paths) {
+        const keys = [...new Set(paths.map((path) => resolve(path)))];
+        const missing = keys.filter((k) => !this.shapeOf.has(k));
+        for (const [k, shape] of await readModelShapes(missing)) {
+            // A concurrent read's promise stays authoritative — it is the one another
+            // caller is already holding — so a second scan of the same bytes can
+            // never replace it with a duplicate.
+            if (!this.shapeOf.has(k))
+                this.shapeOf.set(k, Promise.resolve(shape));
+        }
+        const answered = await Promise.all(keys.map(async (k) => [k, await this.shape(k)]));
+        return new Map(answered);
+    }
+    /** One model's shape, out of the same memo the bulk form fills. */
+    shape(modelPath) {
+        return memo(this.shapeOf, resolve(modelPath), () => readModelShape(modelPath));
+    }
+    /** A service's model, read the way its own shape demands. Memoised per model PATH, which is what identifies the file. */
+    model(docsDir, paths) {
+        return memo(this.models, resolve(paths.model), async () => serviceModelAt({
+            docsDir,
+            paths,
+            shape: await this.shape(paths.model),
+            known: await this.deps.known(docsDir),
+            // A thunk, so a standalone model never spins the map's workspace: the
+            // memo makes the extending case one parse for the run either way.
+            architecture: () => this.architecture(docsDir),
+            standalone: () => this.deps.standalone(paths.model),
+            project: () => this.project(docsDir, paths.model),
+        }));
+    }
+    /**
+     * Prepare every EXTENDING model's project in one workspace, and answer with
+     * the STANDALONE models' paths for the caller to prefetch through its own
+     * document batch — the two shapes need different workspaces, and only the
+     * caller has the memo the second one seeds.
+     *
+     * Purely an accelerator: a batch that could not be created seeds nothing and
+     * every reader falls back to its own load, so findings can never change
+     * because of a tmpdir — only the speed can.
+     */
+    async prefetch(docsDir, paths) {
+        const shapes = await this.shapes(paths.map((p) => p.model));
+        const models = (shape) => [...shapes].filter(([, found]) => found === shape).map(([model]) => model);
+        const extending = models("extending").filter((model) => !this.projects.has(model));
+        for (const [k, doc] of await batchServiceProjects(docsDir, extending)) {
+            // A concurrent load's promise stays authoritative: it is the one every
+            // reader is already holding, and replacing it would count the parse twice.
+            if (this.projects.has(k))
+                continue;
+            this.deps.onProjectLoad();
+            this.projects.set(k, Promise.resolve(doc));
+        }
+        return models("standalone");
+    }
+    /**
+     * One service's project — the architecture documents and its model, parsed
+     * together. Keyed on the model, which is what `prefetch` seeds above, so a
+     * batched fleet run and a single-service run answer out of the same memo.
+     */
+    project(docsDir, modelPath) {
+        return memo(this.projects, resolve(modelPath), async () => {
+            this.deps.onProjectLoad();
+            return asLoadedDoc(await loadProject(docsDir, await modelProjectDocuments(docsDir, modelPath)));
+        });
+    }
+}
+//# sourceMappingURL=fleet.js.map

package/dist/core/c4/prefetch/fleet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet.js","sourceRoot":"","sources":["../../../../src/core/c4/prefetch/fleet.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Every service model ONE command invocation has read, memoised — the fleet\n * map, each model's shape, each per-service project, and each assembled\n * `ServiceModel`.\n *\n * A package of its own rather than four more maps on `core/fleet-context.ts`,\n * and the seam is the one that module's banner already states for its leaves:\n * the rules being memoised here are `../service-model/`'s (which shape a file\n * has, which documents its project holds, how a failed batch degrades), and a\n * memo whose rules live an import away is a memo somebody fills under the wrong\n * key. The read index keeps what it owns — the document parses, the\n * enumerations — and hands them in. It also keeps that file under its line\n * limit, which is the honest second reason: this axis is four memos and a batch\n * plan, and it arrived at a module that was already 336 lines of other axes.\n *\n * The direction is one-way and load-bearing: `fleet-context.ts` imports this,\n * never the reverse. Everything this class needs from the read index arrives as\n * a function on the request (`ModelRead`), so nothing here knows that a\n * FleetContext exists — which is what keeps `core/` → `core/c4/` acyclic.\n *\n * REQUEST-SCOPED exactly as `FleetContext` is: one instance per invocation,\n * dropped when the command finishes. No module-level state, so a later run\n * cannot observe an earlier one's answer, and a `chdir` between two tests\n * cannot leak one docs repo into the next.\n */\nimport { resolve } from \"node:path\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport type { ServicePaths } from \"../../repo/paths.js\";\nimport type { LoadedDoc } from \"../likec4.js\";\nimport { loadArchitecture } from \"../project/architecture.js\";\nimport { asLoadedDoc, loadProject } from \"../project/load.js\";\nimport { modelProjectDocuments } from \"../service-model/documents.js\";\nimport {\n  batchServiceProjects,\n  serviceModelAt,\n  type ServiceModel,\n} from \"../service-model/load.js\";\nimport { readModelShape, readModelShapes, type ModelShape } from \"../service-model/shape.js\";\n\n/**\n * The three things this memo cannot know for itself, supplied once by whoever\n * owns it. Functions rather than values because each is itself memoised on the\n * caller's side: asking again is what makes an answer shared rather than\n * copied.\n */\nexport interface ModelDeps {\n  /** Fires once per per-service project actually parsed, batched or not — the caller owns its counters. */\n  onProjectLoad: () => void;\n  /** The service directories that exist — the caller has enumerated them; this package must not enumerate them again. */\n  known: (docsDir: DocsDir) => Promise<ReadonlySet<string>>;\n  /** Parse one `.likec4` document ALONE, through the caller's own document memo, so a prefetched parse is a hit. */\n  standalone: (path: string) => Promise<LoadedDoc>;\n}\n\n/** One in-flight promise per key, created on first ask — the memo idiom, once. */\nfunction memo<T>(store: Map<string, Promise<T>>, k: string, make: () => Promise<T>): Promise<T> {\n  let pending = store.get(k);\n  if (pending === undefined) {\n    pending = make();\n    store.set(k, pending);\n  }\n  return pending;\n}\n\nexport class ServiceModels {\n  private readonly architectures = new Map<string, Promise<LoadedDoc>>();\n  private readonly shapeOf = new Map<string, Promise<ModelShape>>();\n  private readonly projects = new Map<string, Promise<LoadedDoc>>();\n  private readonly models = new Map<string, Promise<ServiceModel>>();\n\n  constructor(private readonly deps: ModelDeps) {}\n\n  /**\n   * The fleet map as the PROJECT it is (`../project/architecture.ts`). Read\n   * twice over for every service now rather than once for the run — it is the\n   * gate on whether an extending model can be read at all, and the other half\n   * of the diff that decides what such a model actually declares — so the memo\n   * is what keeps a fleet run to one parse of it.\n   *\n   * Filled ONLY when somebody asks. `model` below hands `loadServiceModel` a\n   * thunk rather than an awaited value, so a fleet whose models all stand alone\n   * never parses this project at all — a standalone model is read as one file,\n   * and paying for the map (and inheriting its failures) for `loam show` or the\n   * adopt brief was cost and risk for an answer nobody used.\n   */\n  architecture(docsDir: DocsDir): Promise<LoadedDoc> {\n    return memo(this.architectures, resolve(docsDir), () => loadArchitecture(docsDir));\n  }\n\n  /**\n   * Which shape each model has, keyed by resolved path — ONE read of each\n   * file's bytes per invocation, however many questions are asked of it.\n   *\n   * The bulk form is the primary one because every caller asks in bulk: the\n   * fleet target needs the shapes of the WHOLE enumeration before it can grade\n   * a single renderer-file finding, and the prefetch needs them before it can\n   * decide which workspace each model belongs in.\n   */\n  async shapes(paths: readonly string[]): Promise<Map<string, ModelShape>> {\n    const keys = [...new Set(paths.map((path) => resolve(path)))];\n    const missing = keys.filter((k) => !this.shapeOf.has(k));\n    for (const [k, shape] of await readModelShapes(missing)) {\n      // A concurrent read's promise stays authoritative — it is the one another\n      // caller is already holding — so a second scan of the same bytes can\n      // never replace it with a duplicate.\n      if (!this.shapeOf.has(k)) this.shapeOf.set(k, Promise.resolve(shape));\n    }\n    const answered = await Promise.all(keys.map(async (k) => [k, await this.shape(k)] as const));\n    return new Map(answered);\n  }\n\n  /** One model's shape, out of the same memo the bulk form fills. */\n  shape(modelPath: string): Promise<ModelShape> {\n    return memo(this.shapeOf, resolve(modelPath), () => readModelShape(modelPath));\n  }\n\n  /** A service's model, read the way its own shape demands. Memoised per model PATH, which is what identifies the file. */\n  model(docsDir: DocsDir, paths: ServicePaths): Promise<ServiceModel> {\n    return memo(this.models, resolve(paths.model), async () =>\n      serviceModelAt({\n        docsDir,\n        paths,\n        shape: await this.shape(paths.model),\n        known: await this.deps.known(docsDir),\n        // A thunk, so a standalone model never spins the map's workspace: the\n        // memo makes the extending case one parse for the run either way.\n        architecture: () => this.architecture(docsDir),\n        standalone: () => this.deps.standalone(paths.model),\n        project: () => this.project(docsDir, paths.model),\n      }),\n    );\n  }\n\n  /**\n   * Prepare every EXTENDING model's project in one workspace, and answer with\n   * the STANDALONE models' paths for the caller to prefetch through its own\n   * document batch — the two shapes need different workspaces, and only the\n   * caller has the memo the second one seeds.\n   *\n   * Purely an accelerator: a batch that could not be created seeds nothing and\n   * every reader falls back to its own load, so findings can never change\n   * because of a tmpdir — only the speed can.\n   */\n  async prefetch(docsDir: DocsDir, paths: readonly ServicePaths[]): Promise<string[]> {\n    const shapes = await this.shapes(paths.map((p) => p.model));\n    const models = (shape: ModelShape): string[] =>\n      [...shapes].filter(([, found]) => found === shape).map(([model]) => model);\n    const extending = models(\"extending\").filter((model) => !this.projects.has(model));\n    for (const [k, doc] of await batchServiceProjects(docsDir, extending)) {\n      // A concurrent load's promise stays authoritative: it is the one every\n      // reader is already holding, and replacing it would count the parse twice.\n      if (this.projects.has(k)) continue;\n      this.deps.onProjectLoad();\n      this.projects.set(k, Promise.resolve(doc));\n    }\n    return models(\"standalone\");\n  }\n\n  /**\n   * One service's project — the architecture documents and its model, parsed\n   * together. Keyed on the model, which is what `prefetch` seeds above, so a\n   * batched fleet run and a single-service run answer out of the same memo.\n   */\n  private project(docsDir: DocsDir, modelPath: string): Promise<LoadedDoc> {\n    return memo(this.projects, resolve(modelPath), async () => {\n      this.deps.onProjectLoad();\n      return asLoadedDoc(await loadProject(docsDir, await modelProjectDocuments(docsDir, modelPath)));\n    });\n  }\n}\n"]}

package/dist/core/c4/project/architecture.js

@@ -18,14 +18,63 @@
  * command-layer business: it is about which validate target a failed read is
  * filed against.
  */
-import { join } from "node:path";
+import { join, relative, resolve } from "node:path";
+import { excludingPath, readRootExclude } from "../root-project/exclude.js";
 import { architectureDocuments } from "./documents.js";
 import { asLoadedDoc, loadProject } from "./load.js";
-import { subsystemViewsPath } from "../../repo/paths.js";
+import { landscapePath, subsystemViewsPath } from "../../repo/paths.js";
 /** `<docsDir>/architecture` — the LikeC4 project root, spelled once. */
 export function architectureDir(docsDir) {
     return join(docsDir, "architecture");
 }
+/**
+ * Exactly the documents `loadArchitecture` puts in the fleet map's project, as
+ * one named answer.
+ *
+ * It exists because a SECOND project now has to contain the same set: a service
+ * model that extends the map is parsed beside it (`c4/service-model/`), and the
+ * set it must be staged with is this one plus the model. Two spellings of "the
+ * architecture project's documents" would be two chances to forget the
+ * generated `subsystems.likec4` exclusion — a correctness rule, not an
+ * optimisation (`./documents.ts` says what it prevents) — and the reader that
+ * forgot it would blank a service's whole model over a stale generated file it
+ * has nothing to do with.
+ *
+ * THE ROOT `exclude` IS HONOURED HERE, and that is the second correctness rule
+ * this one list carries. A `.likec4` under `architecture/` that the root project
+ * excludes is a document the RENDERER never loads, so a global style group
+ * declared in one is a name the fleet project cannot resolve — and until this
+ * filter existed the generated subsystem views referenced it anyway: `likec4
+ * validate` Invalid on every run, `loam validate --all` at 0 errors, `doctor`
+ * healthy and `sync` "current" (verification 2026-09-04, W5). A root config loam
+ * cannot read an `exclude` list out of filters nothing: asserting an exclusion on
+ * evidence loam does not have is worse than loading one document too many.
+ *
+ * THE MAP ITSELF IS THE FLOOR, and it is not a special case for tidiness. The
+ * filter had none, so an entry covering `architecture/landscape.likec4` — an
+ * `architecture/*.likec4` a team wrote for a palette, say — left this list
+ * EMPTY, and an empty project parses with zero errors. Every reader then took
+ * that for "the map declares nothing": `validate --all` reported
+ * `landscape.service-unmodelled` naming the very file that models the service
+ * and `c4.invalid` on every extending model, `subsystem sync` rewrote a good
+ * generated file down to a title, and nothing in either run mentioned the
+ * `exclude` entry that caused it (verification 2026-09-04, review C). Keeping
+ * the landscape is the tolerant direction this same banner already chooses for
+ * an unreadable config: loam grades one document the renderer may skip, rather
+ * than asserting a fleet's whole architecture says nothing. The entry is NAMED
+ * to its author one target over — `landscape.excluded`, in
+ * `commands/validate/fleet/views/projects.ts`, which reads this same list
+ * through this same matcher so the two can never disagree about which file the
+ * renderer drops.
+ */
+export async function architectureProjectDocuments(docsDir) {
+    const paths = await architectureDocuments(architectureDir(docsDir), [subsystemViewsPath(docsDir)]);
+    const exclude = await readRootExclude(docsDir);
+    if (exclude === null || exclude.length === 0)
+        return paths;
+    const map = resolve(landscapePath(docsDir));
+    return paths.filter((path) => resolve(path) === map || excludingPath(exclude, relative(docsDir, path)) === null);
+}
 /**
  * The fleet map, read as the PROJECT it actually is.
  *
@@ -39,7 +88,6 @@ export function architectureDir(docsDir) {
  * always did, which is what keeps this a widening rather than a change.
  */
 export async function loadArchitecture(docsDir) {
-    const dir = architectureDir(docsDir);
-    return asLoadedDoc(await loadProject(dir, await architectureDocuments(dir, [subsystemViewsPath(docsDir)])));
+    return asLoadedDoc(await loadProject(architectureDir(docsDir), await architectureProjectDocuments(docsDir)));
 }
 //# sourceMappingURL=architecture.js.map

package/dist/core/c4/project/architecture.js.map

@@ -1 +1 @@
-{"version":3,"file":"architecture.js","sourceRoot":"","sources":["../../../../src/core/c4/project/architecture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,wEAAwE;AACxE,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAgB;IACrD,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO,WAAW,CAAC,MAAM,WAAW,CAAC,GAAG,EAAE,MAAM,qBAAqB,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9G,CAAC","sourcesContent":["/**\n * `architecture/` as ONE LikeC4 project — the docsDir-aware wrapper over the two\n * modules beside it.\n *\n * It lived in `commands/validate/fleet/load.ts` until the use-case axis grew a\n * second reader. That was the right home while `validate --all` was the only\n * caller: the command layer is where a `DocsDir` becomes paths. It stopped being\n * the right home the moment `core/usecases/fleet.ts` needed the same load —\n * `core/` may not import from `commands/` (AGENTS.md), so the choice was a second\n * copy of the two-line composition or one copy one level down. A second copy is\n * the copy that drifts, and the thing that would drift is which documents are in\n * the project: the generated `architecture/subsystems.likec4` exclusion is a\n * correctness rule (see `./documents.ts`), not a preference, and a reader that\n * forgot it would blank a fleet's whole map over a stale generated file.\n *\n * So the wrapper moved here and `validate`'s own module kept the landscape\n * CONTAINMENT — `readLandscape` / `unreadableLandscape` — which is genuinely\n * command-layer business: it is about which validate target a failed read is\n * filed against.\n */\nimport { join } from \"node:path\";\nimport type { LoadedDoc } from \"../likec4.js\";\nimport { architectureDocuments } from \"./documents.js\";\nimport { asLoadedDoc, loadProject } from \"./load.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport { subsystemViewsPath } from \"../../repo/paths.js\";\n\n/** `<docsDir>/architecture` — the LikeC4 project root, spelled once. */\nexport function architectureDir(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\");\n}\n\n/**\n * The fleet map, read as the PROJECT it actually is.\n *\n * `architecture/landscape.likec4` plus every `architecture/usecases/*.likec4`,\n * merged the way the renderer merges them — because a use case declares views\n * over the landscape's elements and does not parse standalone (measured: five\n * errors). `architectureDocuments` owns which files are in and why the\n * generated one is not.\n *\n * A fleet with no use cases loads exactly the landscape and behaves as it\n * always did, which is what keeps this a widening rather than a change.\n */\nexport async function loadArchitecture(docsDir: DocsDir): Promise<LoadedDoc> {\n  const dir = architectureDir(docsDir);\n  return asLoadedDoc(await loadProject(dir, await architectureDocuments(dir, [subsystemViewsPath(docsDir)])));\n}\n"]}
+{"version":3,"file":"architecture.js","sourceRoot":"","sources":["../../../../src/core/c4/project/architecture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAExE,wEAAwE;AACxE,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,OAAgB;IACjE,MAAM,KAAK,GAAG,MAAM,qBAAqB,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACnG,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5C,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;AACnH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAgB;IACrD,OAAO,WAAW,CAAC,MAAM,WAAW,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,4BAA4B,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC/G,CAAC","sourcesContent":["/**\n * `architecture/` as ONE LikeC4 project — the docsDir-aware wrapper over the two\n * modules beside it.\n *\n * It lived in `commands/validate/fleet/load.ts` until the use-case axis grew a\n * second reader. That was the right home while `validate --all` was the only\n * caller: the command layer is where a `DocsDir` becomes paths. It stopped being\n * the right home the moment `core/usecases/fleet.ts` needed the same load —\n * `core/` may not import from `commands/` (AGENTS.md), so the choice was a second\n * copy of the two-line composition or one copy one level down. A second copy is\n * the copy that drifts, and the thing that would drift is which documents are in\n * the project: the generated `architecture/subsystems.likec4` exclusion is a\n * correctness rule (see `./documents.ts`), not a preference, and a reader that\n * forgot it would blank a fleet's whole map over a stale generated file.\n *\n * So the wrapper moved here and `validate`'s own module kept the landscape\n * CONTAINMENT — `readLandscape` / `unreadableLandscape` — which is genuinely\n * command-layer business: it is about which validate target a failed read is\n * filed against.\n */\nimport { join, relative, resolve } from \"node:path\";\nimport type { LoadedDoc } from \"../likec4.js\";\nimport { excludingPath, readRootExclude } from \"../root-project/exclude.js\";\nimport { architectureDocuments } from \"./documents.js\";\nimport { asLoadedDoc, loadProject } from \"./load.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport { landscapePath, subsystemViewsPath } from \"../../repo/paths.js\";\n\n/** `<docsDir>/architecture` — the LikeC4 project root, spelled once. */\nexport function architectureDir(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\");\n}\n\n/**\n * Exactly the documents `loadArchitecture` puts in the fleet map's project, as\n * one named answer.\n *\n * It exists because a SECOND project now has to contain the same set: a service\n * model that extends the map is parsed beside it (`c4/service-model/`), and the\n * set it must be staged with is this one plus the model. Two spellings of \"the\n * architecture project's documents\" would be two chances to forget the\n * generated `subsystems.likec4` exclusion — a correctness rule, not an\n * optimisation (`./documents.ts` says what it prevents) — and the reader that\n * forgot it would blank a service's whole model over a stale generated file it\n * has nothing to do with.\n *\n * THE ROOT `exclude` IS HONOURED HERE, and that is the second correctness rule\n * this one list carries. A `.likec4` under `architecture/` that the root project\n * excludes is a document the RENDERER never loads, so a global style group\n * declared in one is a name the fleet project cannot resolve — and until this\n * filter existed the generated subsystem views referenced it anyway: `likec4\n * validate` Invalid on every run, `loam validate --all` at 0 errors, `doctor`\n * healthy and `sync` \"current\" (verification 2026-09-04, W5). A root config loam\n * cannot read an `exclude` list out of filters nothing: asserting an exclusion on\n * evidence loam does not have is worse than loading one document too many.\n *\n * THE MAP ITSELF IS THE FLOOR, and it is not a special case for tidiness. The\n * filter had none, so an entry covering `architecture/landscape.likec4` — an\n * `architecture/*.likec4` a team wrote for a palette, say — left this list\n * EMPTY, and an empty project parses with zero errors. Every reader then took\n * that for \"the map declares nothing\": `validate --all` reported\n * `landscape.service-unmodelled` naming the very file that models the service\n * and `c4.invalid` on every extending model, `subsystem sync` rewrote a good\n * generated file down to a title, and nothing in either run mentioned the\n * `exclude` entry that caused it (verification 2026-09-04, review C). Keeping\n * the landscape is the tolerant direction this same banner already chooses for\n * an unreadable config: loam grades one document the renderer may skip, rather\n * than asserting a fleet's whole architecture says nothing. The entry is NAMED\n * to its author one target over — `landscape.excluded`, in\n * `commands/validate/fleet/views/projects.ts`, which reads this same list\n * through this same matcher so the two can never disagree about which file the\n * renderer drops.\n */\nexport async function architectureProjectDocuments(docsDir: DocsDir): Promise<string[]> {\n  const paths = await architectureDocuments(architectureDir(docsDir), [subsystemViewsPath(docsDir)]);\n  const exclude = await readRootExclude(docsDir);\n  if (exclude === null || exclude.length === 0) return paths;\n  const map = resolve(landscapePath(docsDir));\n  return paths.filter((path) => resolve(path) === map || excludingPath(exclude, relative(docsDir, path)) === null);\n}\n\n/**\n * The fleet map, read as the PROJECT it actually is.\n *\n * `architecture/landscape.likec4` plus every `architecture/usecases/*.likec4`,\n * merged the way the renderer merges them — because a use case declares views\n * over the landscape's elements and does not parse standalone (measured: five\n * errors). `architectureDocuments` owns which files are in and why the\n * generated one is not.\n *\n * A fleet with no use cases loads exactly the landscape and behaves as it\n * always did, which is what keeps this a widening rather than a change.\n */\nexport async function loadArchitecture(docsDir: DocsDir): Promise<LoadedDoc> {\n  return asLoadedDoc(await loadProject(architectureDir(docsDir), await architectureProjectDocuments(docsDir)));\n}\n"]}

package/dist/core/c4/project/batch.js

@@ -0,0 +1,140 @@
+/**
+ * Many PROJECTS — each a directory-shaped set of documents that must see each
+ * other — through ONE LikeC4 workspace.
+ *
+ * The third loader, and the seam is the same one that already separates the
+ * two beside it: `../workspace.ts` batches N documents as N isolated
+ * single-file projects, `./load.ts` loads ONE project of N documents, and this
+ * loads N projects of N documents each. The shape exists because a service
+ * model that EXTENDS the fleet map is only readable beside the map (measured:
+ * an `extend <fqn> { … }` model parsed alone is every id unresolved), so a
+ * fleet run that used to parse 56 models as 56 isolated documents now needs 56
+ * projects — the architecture documents plus one model each. Measured at the
+ * 1.59.2 pin on an example landscape with 56 generated models: 56 such projects
+ * in ONE workspace take ~700 ms, while 20 SEPARATE workspaces take 2.2 s. The
+ * workspace, not the parse, is what a fleet run pays for.
+ *
+ * Isolation is `../workspace.ts`'s rule verbatim, and for its reason: every
+ * project folder is named `p<i>_<token>` with one crypto-random token per
+ * invocation, so an author-written `import … from '<name>'` cannot resolve
+ * against a sibling project it guessed the name of. Here the sibling projects
+ * are other services' — a model importing another service's project would
+ * silently grade against documents its own repo never named.
+ *
+ * The failure story is the caller's, exactly as it is for the other two loaders:
+ * a project whose documents could not be staged at all is ABSENT from the
+ * result (the caller's ordinary per-project load reproduces the error), and a
+ * batch-INFRASTRUCTURE failure — tmpdir denied, the sandboxed-runner class
+ * ROADMAP documents — rejects the whole call so `FleetContext` can degrade to
+ * per-project loads. Findings can never change because a workspace could not be
+ * created; only the speed can.
+ */
+import { randomBytes } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { LikeC4 } from "likec4";
+import { inOrder } from "../../kernel/concurrency.js";
+import { cleanProjectDoc, emptyProject, groupErrorsByRel, stageProject, } from "./load.js";
+/**
+ * Load many projects in one workspace. Returns `key` → `ProjectDoc`; a project
+ * that could not be staged at all is absent from the result.
+ *
+ * Each project's verdict is `loadProject`'s, applied per project rather than
+ * per workspace: errors mean no model, and the model here is that ONE
+ * project's — a broken service model leaves the other 55 projects with their
+ * models intact, which is the whole reason the fleet is staged as many projects
+ * rather than as one.
+ */
+export async function loadProjectBatch(projects) {
+    const out = new Map();
+    if (projects.length === 0)
+        return out;
+    const root = await mkdtemp(join(tmpdir(), "loam-c4-"));
+    try {
+        const staged = await stageAll(root, projects);
+        if (staged.length === 0)
+            return out;
+        // One workspace for every project — the entire point. The logger is
+        // disabled exactly as in the two loaders beside this one: diagnostics are
+        // returned per document, not written out-of-band to stderr (core never
+        // prints).
+        const likec4 = await LikeC4.fromWorkspace(root, { logger: false });
+        try {
+            const byProject = groupByProject(likec4.getErrors(), new Set(staged.map((s) => s.project)));
+            for (const { key, project, byRel } of staged) {
+                const errors = groupErrorsByRel(byProject.get(project) ?? [], byRel);
+                if (errors.size > 0) {
+                    out.set(key, emptyProject(errors, false));
+                }
+                else {
+                    out.set(key, cleanProjectDoc((await likec4.parsedModel(project))));
+                }
+            }
+        }
+        finally {
+            await likec4.dispose();
+        }
+        return out;
+    }
+    finally {
+        // The workspace is this invocation's alone; nothing else may observe it.
+        // A kill between mkdtemp and here can strand a loam-c4-* dir in OS tmp —
+        // never in the docs repo — which docs/DESIGN.md records as accepted.
+        await rm(root, { recursive: true, force: true });
+    }
+}
+/**
+ * Every project staged into its own folder under `root`, in input order.
+ *
+ * ONE token for the whole invocation, and the index makes each name unique
+ * inside it — `../workspace.ts`'s scheme exactly, so the two batch loaders
+ * cannot drift into two answers about whether a sibling project is nameable.
+ * A project none of whose documents could be copied is dropped rather than
+ * staged empty: an empty project in the workspace would parse clean and grade a
+ * service against nothing at all, where absence sends the caller back to its
+ * own per-project load and today's error.
+ */
+async function stageAll(root, projects) {
+    const token = randomBytes(8).toString("hex");
+    // Concurrent, capped, in input order (kernel/concurrency's contract): the
+    // per-project folders share nothing, and on a network-mounted docs repo the
+    // sequential form pays a round-trip per document. Nulls mark the drops so the
+    // p<i> names stay tied to the caller's own ordering.
+    const results = await inOrder([...projects.entries()], async ([i, req]) => {
+        const project = `p${i}_${token}`;
+        const targets = [...new Set(req.paths.map((path) => resolve(path)))];
+        const byRel = await stageProject(root, project, resolve(req.base), targets);
+        return byRel.size === 0 ? null : { key: req.key, project, byRel };
+    });
+    return results.filter((r) => r !== null);
+}
+/**
+ * One workspace's diagnostics split per PROJECT, keyed on the unique
+ * `p<i>_<token>` path SEGMENT.
+ *
+ * Never a tmp-root prefix compare, for `../workspace.ts`'s measured reason:
+ * darwin hands back realpathed workspace paths (`/var/…` becomes
+ * `/private/var/…`) in some environments and the literal mkdtemp path in
+ * others, and a prefix compare silently attributes every error to nobody in
+ * exactly one of those two worlds. The segment survives both.
+ *
+ * An error this walk cannot attribute throws, and the whole batch with it: a
+ * dropped error grades its project clean, which is failing open in the fleet
+ * gate. The caller degrades to per-project loads, where the error reappears
+ * against the document that raised it.
+ */
+function groupByProject(errors, projects) {
+    const grouped = new Map();
+    for (const err of errors) {
+        const project = err.sourceFsPath.split(/[\\/]/).find((segment) => projects.has(segment));
+        if (project === undefined) {
+            throw new Error(`unattributable LikeC4 error in batch workspace: ${err.message}`);
+        }
+        const list = grouped.get(project) ?? [];
+        list.push(err);
+        grouped.set(project, list);
+    }
+    return grouped;
+}
+//# sourceMappingURL=batch.js.map

package/dist/core/c4/project/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../../../../src/core/c4/project/batch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Many PROJECTS — each a directory-shaped set of documents that must see each\n * other — through ONE LikeC4 workspace.\n *\n * The third loader, and the seam is the same one that already separates the\n * two beside it: `../workspace.ts` batches N documents as N isolated\n * single-file projects, `./load.ts` loads ONE project of N documents, and this\n * loads N projects of N documents each. The shape exists because a service\n * model that EXTENDS the fleet map is only readable beside the map (measured:\n * an `extend <fqn> { … }` model parsed alone is every id unresolved), so a\n * fleet run that used to parse 56 models as 56 isolated documents now needs 56\n * projects — the architecture documents plus one model each. Measured at the\n * 1.59.2 pin on an example landscape with 56 generated models: 56 such projects\n * in ONE workspace take ~700 ms, while 20 SEPARATE workspaces take 2.2 s. The\n * workspace, not the parse, is what a fleet run pays for.\n *\n * Isolation is `../workspace.ts`'s rule verbatim, and for its reason: every\n * project folder is named `p<i>_<token>` with one crypto-random token per\n * invocation, so an author-written `import … from '<name>'` cannot resolve\n * against a sibling project it guessed the name of. Here the sibling projects\n * are other services' — a model importing another service's project would\n * silently grade against documents its own repo never named.\n *\n * The failure story is the caller's, exactly as it is for the other two loaders:\n * a project whose documents could not be staged at all is ABSENT from the\n * result (the caller's ordinary per-project load reproduces the error), and a\n * batch-INFRASTRUCTURE failure — tmpdir denied, the sandboxed-runner class\n * ROADMAP documents — rejects the whole call so `FleetContext` can degrade to\n * per-project loads. Findings can never change because a workspace could not be\n * created; only the speed can.\n */\nimport { randomBytes } from \"node:crypto\";\nimport { mkdtemp, rm } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { join, resolve } from \"node:path\";\nimport { LikeC4 } from \"likec4\";\nimport { inOrder } from \"../../kernel/concurrency.js\";\nimport type { LikeC4Error, ReadableModel } from \"../likec4.js\";\nimport {\n  cleanProjectDoc,\n  emptyProject,\n  groupErrorsByRel,\n  stageProject,\n  type ProjectDoc,\n} from \"./load.js\";\n\n/** One project to load: the caller's key for it, the root its documents are mirrored relative to, and the documents. */\nexport interface ProjectRequest {\n  /**\n   * How the caller will look the answer up. Never derived here from a path,\n   * because the caller's identity for a project is not this module's business:\n   * `FleetContext` keys on the resolved `model.likec4` path, and a second\n   * spelling of that key is a memo the caller can never hit.\n   */\n  key: string;\n  /**\n   * The directory the documents' relative structure is preserved against —\n   * the docs root for a per-service project, which is what makes a view's\n   * `sourcePath` come back spelled `services/<tree>/model.likec4`, the way the\n   * renderer spells it from the same root.\n   */\n  base: string;\n  paths: string[];\n}\n\n/** A project that reached the workspace: the caller's key, its folder name, and rel → real path. */\ninterface StagedProject {\n  key: string;\n  /** The workspace folder name — `parsedModel`'s argument AND the error-attribution segment. */\n  project: string;\n  byRel: Map<string, string>;\n}\n\n/**\n * Load many projects in one workspace. Returns `key` → `ProjectDoc`; a project\n * that could not be staged at all is absent from the result.\n *\n * Each project's verdict is `loadProject`'s, applied per project rather than\n * per workspace: errors mean no model, and the model here is that ONE\n * project's — a broken service model leaves the other 55 projects with their\n * models intact, which is the whole reason the fleet is staged as many projects\n * rather than as one.\n */\nexport async function loadProjectBatch(\n  projects: readonly ProjectRequest[],\n): Promise<Map<string, ProjectDoc>> {\n  const out = new Map<string, ProjectDoc>();\n  if (projects.length === 0) return out;\n  const root = await mkdtemp(join(tmpdir(), \"loam-c4-\"));\n  try {\n    const staged = await stageAll(root, projects);\n    if (staged.length === 0) return out;\n    // One workspace for every project — the entire point. The logger is\n    // disabled exactly as in the two loaders beside this one: diagnostics are\n    // returned per document, not written out-of-band to stderr (core never\n    // prints).\n    const likec4 = await LikeC4.fromWorkspace(root, { logger: false });\n    try {\n      const byProject = groupByProject(likec4.getErrors(), new Set(staged.map((s) => s.project)));\n      for (const { key, project, byRel } of staged) {\n        const errors = groupErrorsByRel(byProject.get(project) ?? [], byRel);\n        if (errors.size > 0) {\n          out.set(key, emptyProject(errors, false));\n        } else {\n          out.set(key, cleanProjectDoc((await likec4.parsedModel(project)) as ReadableModel));\n        }\n      }\n    } finally {\n      await likec4.dispose();\n    }\n    return out;\n  } finally {\n    // The workspace is this invocation's alone; nothing else may observe it.\n    // A kill between mkdtemp and here can strand a loam-c4-* dir in OS tmp —\n    // never in the docs repo — which docs/DESIGN.md records as accepted.\n    await rm(root, { recursive: true, force: true });\n  }\n}\n\n/**\n * Every project staged into its own folder under `root`, in input order.\n *\n * ONE token for the whole invocation, and the index makes each name unique\n * inside it — `../workspace.ts`'s scheme exactly, so the two batch loaders\n * cannot drift into two answers about whether a sibling project is nameable.\n * A project none of whose documents could be copied is dropped rather than\n * staged empty: an empty project in the workspace would parse clean and grade a\n * service against nothing at all, where absence sends the caller back to its\n * own per-project load and today's error.\n */\nasync function stageAll(root: string, projects: readonly ProjectRequest[]): Promise<StagedProject[]> {\n  const token = randomBytes(8).toString(\"hex\");\n  // Concurrent, capped, in input order (kernel/concurrency's contract): the\n  // per-project folders share nothing, and on a network-mounted docs repo the\n  // sequential form pays a round-trip per document. Nulls mark the drops so the\n  // p<i> names stay tied to the caller's own ordering.\n  const results = await inOrder([...projects.entries()], async ([i, req]) => {\n    const project = `p${i}_${token}`;\n    const targets = [...new Set(req.paths.map((path) => resolve(path)))];\n    const byRel = await stageProject(root, project, resolve(req.base), targets);\n    return byRel.size === 0 ? null : { key: req.key, project, byRel };\n  });\n  return results.filter((r): r is StagedProject => r !== null);\n}\n\n/**\n * One workspace's diagnostics split per PROJECT, keyed on the unique\n * `p<i>_<token>` path SEGMENT.\n *\n * Never a tmp-root prefix compare, for `../workspace.ts`'s measured reason:\n * darwin hands back realpathed workspace paths (`/var/…` becomes\n * `/private/var/…`) in some environments and the literal mkdtemp path in\n * others, and a prefix compare silently attributes every error to nobody in\n * exactly one of those two worlds. The segment survives both.\n *\n * An error this walk cannot attribute throws, and the whole batch with it: a\n * dropped error grades its project clean, which is failing open in the fleet\n * gate. The caller degrades to per-project loads, where the error reappears\n * against the document that raised it.\n */\nfunction groupByProject(\n  errors: readonly (LikeC4Error & { sourceFsPath: string })[],\n  projects: ReadonlySet<string>,\n): Map<string, (LikeC4Error & { sourceFsPath: string })[]> {\n  const grouped = new Map<string, (LikeC4Error & { sourceFsPath: string })[]>();\n  for (const err of errors) {\n    const project = err.sourceFsPath.split(/[\\\\/]/).find((segment) => projects.has(segment));\n    if (project === undefined) {\n      throw new Error(`unattributable LikeC4 error in batch workspace: ${err.message}`);\n    }\n    const list = grouped.get(project) ?? [];\n    list.push(err);\n    grouped.set(project, list);\n  }\n  return grouped;\n}\n"]}

package/dist/core/c4/project/documents.js

@@ -2,10 +2,15 @@
  * Which `.likec4` documents in a docs repo's `architecture/` loam loads as one
  * project.
  *
- * The renderer's answer is "all of them" — `likec4.config.json` scopes the root
- * LikeC4 project to everything but `services/**` and `features/**`. loam's
- * answer is all of them EXCEPT the generated `architecture/subsystems.likec4`,
- * and that exception is not an optimisation:
+ * The renderer's answer is "all of them". The root `likec4.config.json` no
+ * longer excludes `services/**`: the root project holds the map AND every
+ * service model that EXTENDS it, because such a model is only readable beside
+ * the map, and `loam subsystem sync` excludes only the directory of each model
+ * that STANDS ALONE — one `services/<tree>/**` entry per standalone model,
+ * never the whole subtree (`c4/service-model/renderer.ts` owns that list, and
+ * is the one place loam reads that file). loam's own answer here is all of them
+ * EXCEPT the generated `architecture/subsystems.likec4`, and that exception is
+ * not an optimisation:
  *
  *  - docs/DESIGN.md rule 26 excludes the generated file from every read loam
  *    performs. Its staleness is a byte compare (`subsystem.views-stale`) and

package/dist/core/c4/project/documents.js.map

@@ -1 +1 @@
-{"version":3,"file":"documents.js","sourceRoot":"","sources":["../../../../src/core/c4/project/documents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,GAAW,EAAE,IAAI,GAAa,EAAE;IAC1E,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,KAAK,EAAE,EAAU,EAAiB,EAAE;QAC/C,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,KAAK,CAAC,WAAW,EAAE;gBAAE,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;iBACrC,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC,CAAC;IACF,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC","sourcesContent":["/**\n * Which `.likec4` documents in a docs repo's `architecture/` loam loads as one\n * project.\n *\n * The renderer's answer is \"all of them\" — `likec4.config.json` scopes the root\n * LikeC4 project to everything but `services/**` and `features/**`. loam's\n * answer is all of them EXCEPT the generated `architecture/subsystems.likec4`,\n * and that exception is not an optimisation:\n *\n *  - docs/DESIGN.md rule 26 excludes the generated file from every read loam\n *    performs. Its staleness is a byte compare (`subsystem.views-stale`) and\n *    nothing anywhere reads its contents.\n *  - Including it would invent a failure mode. Its `include` lines name\n *    landscape element ids, so a file that has drifted — a service removed\n *    since the last `loam subsystem sync` — would be a parse error, and a parse\n *    error in one project document blanks the model for all of them. A fleet\n *    whose only problem is a stale generated file would lose its whole map\n *    instead of getting the one finding that names the repair.\n *\n * The skip is passed in by the caller rather than spelled here, so the filename\n * stays written in `repo/paths.ts` alone.\n */\nimport { readdir } from \"node:fs/promises\";\nimport { join, resolve } from \"node:path\";\n\n/**\n * Every `.likec4` file under `dir`, recursively, minus `skip`, in a stable\n * order.\n *\n * Sorted because it decides the staging order and therefore nothing at all —\n * LikeC4 merges a project regardless — but a stable list makes a failure\n * reproducible and a diff of one readable. A directory that does not exist is\n * an empty list, never a throw: a fleet with no `architecture/` is a fleet with\n * nothing to load, which is already `landscape.missing`'s question, not this\n * function's.\n */\nexport async function architectureDocuments(dir: string, skip: string[] = []): Promise<string[]> {\n  const excluded = new Set(skip.map((path) => resolve(path)));\n  const found: string[] = [];\n  const walk = async (at: string): Promise<void> => {\n    let entries;\n    try {\n      entries = await readdir(at, { withFileTypes: true });\n    } catch {\n      return;\n    }\n    for (const entry of entries) {\n      const path = join(at, entry.name);\n      if (entry.isDirectory()) await walk(path);\n      else if (entry.name.endsWith(\".likec4\") && !excluded.has(resolve(path))) found.push(path);\n    }\n  };\n  await walk(resolve(dir));\n  return found.sort();\n}\n"]}
+{"version":3,"file":"documents.js","sourceRoot":"","sources":["../../../../src/core/c4/project/documents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,GAAW,EAAE,IAAI,GAAa,EAAE;IAC1E,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,KAAK,EAAE,EAAU,EAAiB,EAAE;QAC/C,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,KAAK,CAAC,WAAW,EAAE;gBAAE,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;iBACrC,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC,CAAC;IACF,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC","sourcesContent":["/**\n * Which `.likec4` documents in a docs repo's `architecture/` loam loads as one\n * project.\n *\n * The renderer's answer is \"all of them\". The root `likec4.config.json` no\n * longer excludes `services/**`: the root project holds the map AND every\n * service model that EXTENDS it, because such a model is only readable beside\n * the map, and `loam subsystem sync` excludes only the directory of each model\n * that STANDS ALONE — one `services/<tree>/**` entry per standalone model,\n * never the whole subtree (`c4/service-model/renderer.ts` owns that list, and\n * is the one place loam reads that file). loam's own answer here is all of them\n * EXCEPT the generated `architecture/subsystems.likec4`, and that exception is\n * not an optimisation:\n *\n *  - docs/DESIGN.md rule 26 excludes the generated file from every read loam\n *    performs. Its staleness is a byte compare (`subsystem.views-stale`) and\n *    nothing anywhere reads its contents.\n *  - Including it would invent a failure mode. Its `include` lines name\n *    landscape element ids, so a file that has drifted — a service removed\n *    since the last `loam subsystem sync` — would be a parse error, and a parse\n *    error in one project document blanks the model for all of them. A fleet\n *    whose only problem is a stale generated file would lose its whole map\n *    instead of getting the one finding that names the repair.\n *\n * The skip is passed in by the caller rather than spelled here, so the filename\n * stays written in `repo/paths.ts` alone.\n */\nimport { readdir } from \"node:fs/promises\";\nimport { join, resolve } from \"node:path\";\n\n/**\n * Every `.likec4` file under `dir`, recursively, minus `skip`, in a stable\n * order.\n *\n * Sorted because it decides the staging order and therefore nothing at all —\n * LikeC4 merges a project regardless — but a stable list makes a failure\n * reproducible and a diff of one readable. A directory that does not exist is\n * an empty list, never a throw: a fleet with no `architecture/` is a fleet with\n * nothing to load, which is already `landscape.missing`'s question, not this\n * function's.\n */\nexport async function architectureDocuments(dir: string, skip: string[] = []): Promise<string[]> {\n  const excluded = new Set(skip.map((path) => resolve(path)));\n  const found: string[] = [];\n  const walk = async (at: string): Promise<void> => {\n    let entries;\n    try {\n      entries = await readdir(at, { withFileTypes: true });\n    } catch {\n      return;\n    }\n    for (const entry of entries) {\n      const path = join(at, entry.name);\n      if (entry.isDirectory()) await walk(path);\n      else if (entry.name.endsWith(\".likec4\") && !excluded.has(resolve(path))) found.push(path);\n    }\n  };\n  await walk(resolve(dir));\n  return found.sort();\n}\n"]}