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

package/dist/core/c4/service-model/fleet/extending.js

@@ -0,0 +1,82 @@
+/**
+ * Every service whose `model.likec4` EXTENDS the fleet map, with its living
+ * source in hand — the list the landscape merge routes a nested addition
+ * through.
+ *
+ * ## Why it is here and not beside the archive
+ *
+ * It was `commands/archive/plan/model/extending.ts`'s, beside the proof that
+ * the merged model parses, and for one merge that was the right seam: reading
+ * the fleet and deciding to write belong to the command, `core/c4/splice/` is a
+ * pure text-to-text computation, and nothing else needed the list.
+ *
+ * Then the archive stopped being the only reader. `../../project/staged.ts`
+ * previews the map a feature's own merge would leave, and every feature-side
+ * gate rests on that preview — `usecase.flow-invalid` and
+ * `deployment.doc-invalid` both refuse on it, and `--approve` reaches neither.
+ * A preview computed without this list previews the WRONG map: it holds
+ * interior the archive routes into `services/<…>/model.likec4`, so a
+ * feature-local flow hopping to `<service-fqn>.<container>` resolved against it,
+ * passed the gate, and was copied verbatim into `architecture/usecases/`, where
+ * it resolves against nothing (verification 2026-09-04, review finding F8;
+ * measured: `loam archive --approve` at exit 0, then `loam validate --all` with
+ * one `landscape.invalid` and one `spine.landscape-invalid` per service).
+ *
+ * A reader in `commands/` cannot close that: `core/` may never import
+ * `commands/`. Nor could it live in `../../project/` beside the staging that
+ * needs it — the shape scan is `../shape.ts`, and `../` imports
+ * `../../project/`, so the edge would be a package cycle
+ * (`node scripts/package-graph.mjs` refuses it). So it sits one level BELOW the
+ * shape scan it calls, in a package that nothing in `core/c4/` imports back:
+ * `core/delta/`, `core/coherence/` and the archive all reach it, and the graph
+ * stays acyclic.
+ *
+ * ## The shape decision is not this file's
+ *
+ * `../shape.ts` owns it: a model declaring an element kind is STANDALONE, is
+ * parsed alone, and owns no share of the merge — the map draws its containers
+ * exactly as it did before the extending shape existed. A model that cannot be
+ * read is not in the list either, which is the same conservative arm the shape
+ * reader takes.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { inOrder } from "../../../kernel/concurrency.js";
+import { repoPath } from "../../../envelope/json.js";
+import { servicePathsAt } from "../../../repo/paths.js";
+import { enumeratedServices } from "../../../repo/service-target.js";
+import { readModelShapes } from "../shape.js";
+/**
+ * The fleet's extending models, ordered by the enumeration.
+ *
+ * `fleet` is OPTIONAL for the reason `enumeratedServices` makes it optional:
+ * the callers are three, and only two of them run inside an invocation index.
+ * With one, the enumeration and the shape scan are memo hits and this costs one
+ * small read per extending model; without one, the same bulk scan runs directly
+ * (`readModelShapes`) and the answer is identical. What must never differ
+ * between the two is the LIST — a gate that routed differently depending on
+ * whether its caller happened to hold a read index would be a gate nobody could
+ * reproduce.
+ */
+export async function extendingModels(docsDir, fleet) {
+    const services = await enumeratedServices(docsDir, fleet);
+    if (services.length === 0)
+        return [];
+    const paths = services.map((entry) => servicePathsAt(entry.dir).model);
+    const shapes = fleet === undefined ? await readModelShapes(paths) : await fleet.modelShapes(paths);
+    const found = await inOrder(services, async (entry) => {
+        const path = servicePathsAt(entry.dir).model;
+        if (shapes.get(resolve(path)) !== "extending")
+            return null;
+        try {
+            return { service: entry.id, path: repoPath(docsDir, path), text: await readFile(path, "utf8") };
+        }
+        catch {
+            // Unreadable is not extending: the merge would be splicing into bytes it
+            // never saw, and the map's arm is the honest fallback.
+            return null;
+        }
+    });
+    return found.filter((model) => model !== null);
+}
+//# sourceMappingURL=extending.js.map

package/dist/core/c4/service-model/fleet/extending.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extending.js","sourceRoot":"","sources":["../../../../../src/core/c4/service-model/fleet/extending.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAIzD,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAgB,EAAE,KAAoB;IAC1E,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC1D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACvE,MAAM,MAAM,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACnG,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAkC,EAAE;QACpF,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;QAC7C,IAAI,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,WAAW;YAAE,OAAO,IAAI,CAAC;QAC3D,IAAI,CAAC;YACH,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;QAClG,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;YACzE,uDAAuD;YACvD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAA2B,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;AAC1E,CAAC","sourcesContent":["/**\n * Every service whose `model.likec4` EXTENDS the fleet map, with its living\n * source in hand — the list the landscape merge routes a nested addition\n * through.\n *\n * ## Why it is here and not beside the archive\n *\n * It was `commands/archive/plan/model/extending.ts`'s, beside the proof that\n * the merged model parses, and for one merge that was the right seam: reading\n * the fleet and deciding to write belong to the command, `core/c4/splice/` is a\n * pure text-to-text computation, and nothing else needed the list.\n *\n * Then the archive stopped being the only reader. `../../project/staged.ts`\n * previews the map a feature's own merge would leave, and every feature-side\n * gate rests on that preview — `usecase.flow-invalid` and\n * `deployment.doc-invalid` both refuse on it, and `--approve` reaches neither.\n * A preview computed without this list previews the WRONG map: it holds\n * interior the archive routes into `services/<…>/model.likec4`, so a\n * feature-local flow hopping to `<service-fqn>.<container>` resolved against it,\n * passed the gate, and was copied verbatim into `architecture/usecases/`, where\n * it resolves against nothing (verification 2026-09-04, review finding F8;\n * measured: `loam archive --approve` at exit 0, then `loam validate --all` with\n * one `landscape.invalid` and one `spine.landscape-invalid` per service).\n *\n * A reader in `commands/` cannot close that: `core/` may never import\n * `commands/`. Nor could it live in `../../project/` beside the staging that\n * needs it — the shape scan is `../shape.ts`, and `../` imports\n * `../../project/`, so the edge would be a package cycle\n * (`node scripts/package-graph.mjs` refuses it). So it sits one level BELOW the\n * shape scan it calls, in a package that nothing in `core/c4/` imports back:\n * `core/delta/`, `core/coherence/` and the archive all reach it, and the graph\n * stays acyclic.\n *\n * ## The shape decision is not this file's\n *\n * `../shape.ts` owns it: a model declaring an element kind is STANDALONE, is\n * parsed alone, and owns no share of the merge — the map draws its containers\n * exactly as it did before the extending shape existed. A model that cannot be\n * read is not in the list either, which is the same conservative arm the shape\n * reader takes.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport { inOrder } from \"../../../kernel/concurrency.js\";\nimport type { ExtendingModel } from \"../../splice/contract.js\";\nimport type { DocsDir } from \"../../../kernel/ids/dirs.js\";\nimport type { FleetContext } from \"../../../fleet-context.js\";\nimport { repoPath } from \"../../../envelope/json.js\";\nimport { servicePathsAt } from \"../../../repo/paths.js\";\nimport { enumeratedServices } from \"../../../repo/service-target.js\";\nimport { readModelShapes } from \"../shape.js\";\n\n/**\n * The fleet's extending models, ordered by the enumeration.\n *\n * `fleet` is OPTIONAL for the reason `enumeratedServices` makes it optional:\n * the callers are three, and only two of them run inside an invocation index.\n * With one, the enumeration and the shape scan are memo hits and this costs one\n * small read per extending model; without one, the same bulk scan runs directly\n * (`readModelShapes`) and the answer is identical. What must never differ\n * between the two is the LIST — a gate that routed differently depending on\n * whether its caller happened to hold a read index would be a gate nobody could\n * reproduce.\n */\nexport async function extendingModels(docsDir: DocsDir, fleet?: FleetContext): Promise<ExtendingModel[]> {\n  const services = await enumeratedServices(docsDir, fleet);\n  if (services.length === 0) return [];\n  const paths = services.map((entry) => servicePathsAt(entry.dir).model);\n  const shapes = fleet === undefined ? await readModelShapes(paths) : await fleet.modelShapes(paths);\n  const found = await inOrder(services, async (entry): Promise<ExtendingModel | null> => {\n    const path = servicePathsAt(entry.dir).model;\n    if (shapes.get(resolve(path)) !== \"extending\") return null;\n    try {\n      return { service: entry.id, path: repoPath(docsDir, path), text: await readFile(path, \"utf8\") };\n    } catch {\n      // Unreadable is not extending: the merge would be splicing into bytes it\n      // never saw, and the map's arm is the honest fallback.\n      return null;\n    }\n  });\n  return found.filter((model): model is ExtendingModel => model !== null);\n}\n"]}

package/dist/core/c4/service-model/load.js

@@ -0,0 +1,165 @@
+/**
+ * How a `model.likec4` is read — the entry point every reader of a service
+ * model goes through, whichever shape the file has.
+ *
+ * One function rather than a branch at each call site, because the branch is
+ * not local: a standalone model is a file, an extending model is a project, and
+ * the six readers that open `model.likec4` (the service target, the isolation
+ * scan, arch coverage, `loam show`, the adopt brief, the service's use cases)
+ * all want the same thing out of either — the errors, the service's own
+ * elements and relationships, and the views the file itself declares. Making
+ * each of them ask "which shape is this?" is how five of them would come to
+ * answer it differently.
+ *
+ * The FOUR arms below are the whole of the contract, and each exists because
+ * one of them is a state a fleet is actually in:
+ *
+ *  - standalone: today's behaviour, byte for byte. The file is parsed alone.
+ *  - the map does not parse: the model extends something unreadable, so it
+ *    cannot be read at all. NOT an error against the model — the fleet already
+ *    has `spine.landscape-invalid` for this, and a second finding here would
+ *    blame every service for one broken document.
+ *  - the project has errors: every one of them is this model's, including an
+ *    error LikeC4 blames on the landscape. That is sound because the map was
+ *    parsed alone first and came back clean — measured: a duplicate declaration
+ *    is reported against BOTH files, so the map's copy of the error exists only
+ *    because this model was added to the set.
+ *  - clean: the model's own slice (`./slice.ts`), its own views, and the
+ *    project's specification, in the shape a standalone model's `LoadedDoc`
+ *    already had.
+ *
+ * Nothing here is memoised. `../prefetch/fleet.ts` is the request-scoped memo
+ * over all of it — one instance per command invocation, owned by
+ * `core/fleet-context.ts` — because a loader that caches is a loader a test
+ * cannot ask twice.
+ */
+import { basename, relative, resolve } from "node:path";
+import { asLoadedDoc } from "../project/load.js";
+import { loadProjectBatch } from "../project/batch.js";
+import { modelProjectSets } from "./documents.js";
+import { sliceForService } from "./slice.js";
+/**
+ * `loadServiceModel` addressed by a service's paths — the two derivations that
+ * decide whether the slice and the views filter find anything at all, spelled
+ * here rather than at the caller.
+ *
+ * The SERVICE is the leaf directory name, which `ServiceEntry` defines as the
+ * canonical id at whatever depth the tree walk found the service; it is what an
+ * element's `metadata { service '…' }` binding names and what the element→
+ * service resolver answers, so a slice keyed on anything else is empty.
+ *
+ * The MODEL PATH is made docs-relative and `/`-separated, because that is how
+ * LikeC4 spells a view's `sourcePath` inside a project staged from the docs
+ * root — on Windows the native separator would miss every view, silently
+ * turning "this model declares no diagrams" into a fact about the operating
+ * system.
+ */
+export function serviceModelAt(sources) {
+    return loadServiceModel({
+        shape: sources.shape,
+        service: basename(sources.paths.dir),
+        modelPath: relative(sources.docsDir, sources.paths.model).split(/[\\/]/).join("/"),
+        known: sources.known,
+        architecture: sources.architecture,
+        standalone: sources.standalone,
+        project: sources.project,
+    });
+}
+/**
+ * A `LoadedDoc` carrying nothing — the shape a model that could not be read
+ * answers with. A FUNCTION rather than a shared constant: the arrays reach
+ * every caller, and one that pushed a finding into a module-level literal would
+ * corrupt the answer for every other service in the run.
+ */
+function noModel() {
+    return { errors: [], elements: [], relationships: [] };
+}
+export async function loadServiceModel(req) {
+    if (req.shape === "standalone") {
+        // Before the map is asked for, deliberately: a standalone model is a file
+        // parsed alone, so a reader of one must not pay for the `architecture/`
+        // project — nor inherit its failures.
+        return { shape: req.shape, doc: await req.standalone(), project: null, unowned: [], mapUnreadable: false };
+    }
+    const architecture = await req.architecture();
+    if (architecture.errors.length > 0) {
+        return { shape: req.shape, doc: noModel(), project: null, unowned: [], mapUnreadable: true };
+    }
+    const project = await req.project();
+    if (project.errors.length > 0) {
+        // Every error, not the ones whose path is the model's. The map parsed alone
+        // and came back clean, so an error now blamed on the landscape exists only
+        // because this model joined the set — and dropping it would grade the model
+        // valid while the renderer, reading the same two documents together,
+        // refuses to draw anything.
+        return {
+            shape: req.shape,
+            doc: { errors: project.errors, elements: [], relationships: [] },
+            project: null,
+            unowned: [],
+            mapUnreadable: false,
+        };
+    }
+    const slice = sliceForService({
+        project,
+        architecture,
+        service: req.service,
+        known: req.known,
+    });
+    return {
+        shape: req.shape,
+        doc: {
+            errors: [],
+            elements: slice.elements,
+            relationships: slice.relationships,
+            // The model file's OWN views, by the file each was written in. A service
+            // renders its own diagrams and the fleet's use cases are drawn over the
+            // same elements, so without the filter every service in the fleet would
+            // report every fleet-level view as one of its own.
+            views: (project.views ?? []).filter((view) => view.sourcePath === req.modelPath),
+            // The PROJECT's specification, deliberately: an extending model takes the
+            // map's kinds and tags, so "what this model can use" is the project's
+            // table, and a tags-only block of its own has already been merged into it.
+            ...(project.specification === undefined ? {} : { specification: project.specification }),
+        },
+        project,
+        unowned: slice.unowned,
+        mapUnreadable: false,
+    };
+}
+/**
+ * Every extending model's per-service project, parsed in ONE workspace — the
+ * engine under `../prefetch/fleet.ts`'s `prefetch`.
+ *
+ * Keyed by the RESOLVED model path, which is the key that memo files
+ * per-service projects under; a second spelling would be a memo the prefetch
+ * fills and no reader ever hits.
+ *
+ * A batch-infrastructure failure answers with an EMPTY map rather than
+ * rejecting: the prefetch is an accelerator and nothing more, so a workspace
+ * that could not be created must cost the run its speed and never one finding
+ * (`FleetContext.prefetchLikeC4` has behaved this way since the batch loader
+ * landed, and the two must not differ — a run that degrades one way and not the
+ * other is a run whose report depends on the tmpdir).
+ */
+export async function batchServiceProjects(docsDir, models) {
+    const out = new Map();
+    if (models.length === 0)
+        return out;
+    const requests = (await modelProjectSets(docsDir, models)).map((set) => ({
+        key: resolve(set.model),
+        base: docsDir,
+        paths: set.paths,
+    }));
+    try {
+        for (const [key, doc] of await loadProjectBatch(requests))
+            out.set(key, asLoadedDoc(doc));
+    }
+    catch {
+        // Unreadable is not invalid: the caller seeds nothing and every reader
+        // falls back to its own per-project load.
+        return new Map();
+    }
+    return out;
+}
+//# sourceMappingURL=load.js.map

package/dist/core/c4/service-model/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../../../src/core/c4/service-model/load.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How a `model.likec4` is read — the entry point every reader of a service\n * model goes through, whichever shape the file has.\n *\n * One function rather than a branch at each call site, because the branch is\n * not local: a standalone model is a file, an extending model is a project, and\n * the six readers that open `model.likec4` (the service target, the isolation\n * scan, arch coverage, `loam show`, the adopt brief, the service's use cases)\n * all want the same thing out of either — the errors, the service's own\n * elements and relationships, and the views the file itself declares. Making\n * each of them ask \"which shape is this?\" is how five of them would come to\n * answer it differently.\n *\n * The FOUR arms below are the whole of the contract, and each exists because\n * one of them is a state a fleet is actually in:\n *\n *  - standalone: today's behaviour, byte for byte. The file is parsed alone.\n *  - the map does not parse: the model extends something unreadable, so it\n *    cannot be read at all. NOT an error against the model — the fleet already\n *    has `spine.landscape-invalid` for this, and a second finding here would\n *    blame every service for one broken document.\n *  - the project has errors: every one of them is this model's, including an\n *    error LikeC4 blames on the landscape. That is sound because the map was\n *    parsed alone first and came back clean — measured: a duplicate declaration\n *    is reported against BOTH files, so the map's copy of the error exists only\n *    because this model was added to the set.\n *  - clean: the model's own slice (`./slice.ts`), its own views, and the\n *    project's specification, in the shape a standalone model's `LoadedDoc`\n *    already had.\n *\n * Nothing here is memoised. `../prefetch/fleet.ts` is the request-scoped memo\n * over all of it — one instance per command invocation, owned by\n * `core/fleet-context.ts` — because a loader that caches is a loader a test\n * cannot ask twice.\n */\nimport { basename, relative, resolve } from \"node:path\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport type { ServicePaths } from \"../../repo/paths.js\";\nimport type { Elem, LoadedDoc } from \"../likec4.js\";\nimport { asLoadedDoc } from \"../project/load.js\";\nimport { loadProjectBatch } from \"../project/batch.js\";\nimport { modelProjectSets } from \"./documents.js\";\nimport type { ModelShape } from \"./shape.js\";\nimport { sliceForService } from \"./slice.js\";\n\nexport interface ServiceModel {\n  shape: ModelShape;\n  /**\n   * Errors, the OWN elements and relationships, and the model file's own views\n   * — what every model-dependent check reads, in the shape it read when a model\n   * was always one self-contained file. For a standalone model it is exactly\n   * what parsing that file returns.\n   */\n  doc: LoadedDoc;\n  /**\n   * Extending only: the whole per-service project, map and model together —\n   * the scope a `Covers:` line and a use-case step resolve against, because\n   * both may legitimately name an element the map declares. Null for a\n   * standalone model, for a model that did not parse, and when the map itself\n   * is unreadable.\n   */\n  project: LoadedDoc | null;\n  /**\n   * Extending only: the elements the model adds OUTSIDE the element that\n   * resolves to it — `c4.element-unowned`, one finding each. Empty otherwise,\n   * including for a standalone model, whose partner copies are a different\n   * grade (`c4.declaration-diverged`) asking a different question.\n   */\n  unowned: Elem[];\n  /**\n   * The architecture project itself does not parse, so an extending model could\n   * not be read at all. `doc` then carries no errors and no model, and the\n   * finding is the fleet's `spine.landscape-invalid` rather than anything about\n   * this service's file.\n   */\n  mapUnreadable: boolean;\n}\n\nexport interface ServiceModelRequest {\n  shape: ModelShape;\n  /** The `services/<…>/<id>` directory name — what the model's elements must resolve to. */\n  service: string;\n  /**\n   * The model's path RELATIVE TO THE DOCS ROOT, `/`-separated: the spelling\n   * LikeC4 gives a view's `sourcePath` inside a project staged from that root,\n   * and therefore the only spelling the views filter below can join on.\n   */\n  modelPath: string;\n  /** Every service directory that exists, for the element→service resolver. */\n  known: ReadonlySet<string>;\n  /**\n   * Parse the architecture documents WITHOUT this model — both the gate on\n   * whether an extending model can be read and the diff's other half.\n   *\n   * A THUNK, like the two below, and awaited only in the extending branch. It\n   * arrived as a value and every caller therefore paid for the whole\n   * `architecture/` project before the shape was even consulted: `loam show` and\n   * the adopt brief over a fleet whose models all stand alone spun a LikeC4\n   * workspace they never read a byte of, and a `loadProject` failure in it\n   * propagated out of commands whose model read is one `readFile`. A standalone\n   * model is parsed alone, so the map is not part of its answer at all.\n   */\n  architecture: () => Promise<LoadedDoc>;\n  /** Parse the model file alone. Called for a standalone model and never otherwise. */\n  standalone: () => Promise<LoadedDoc>;\n  /** Parse the per-service project (map + model). Memoised and batched by the caller. */\n  project: () => Promise<LoadedDoc>;\n}\n\n/**\n * The DOCS-REPO facts a request is derived from, for the caller that holds\n * paths rather than the derived spellings.\n */\nexport interface ServiceModelSources {\n  docsDir: DocsDir;\n  paths: ServicePaths;\n  shape: ModelShape;\n  known: ReadonlySet<string>;\n  architecture: () => Promise<LoadedDoc>;\n  standalone: () => Promise<LoadedDoc>;\n  project: () => Promise<LoadedDoc>;\n}\n\n/**\n * `loadServiceModel` addressed by a service's paths — the two derivations that\n * decide whether the slice and the views filter find anything at all, spelled\n * here rather than at the caller.\n *\n * The SERVICE is the leaf directory name, which `ServiceEntry` defines as the\n * canonical id at whatever depth the tree walk found the service; it is what an\n * element's `metadata { service '…' }` binding names and what the element→\n * service resolver answers, so a slice keyed on anything else is empty.\n *\n * The MODEL PATH is made docs-relative and `/`-separated, because that is how\n * LikeC4 spells a view's `sourcePath` inside a project staged from the docs\n * root — on Windows the native separator would miss every view, silently\n * turning \"this model declares no diagrams\" into a fact about the operating\n * system.\n */\nexport function serviceModelAt(sources: ServiceModelSources): Promise<ServiceModel> {\n  return loadServiceModel({\n    shape: sources.shape,\n    service: basename(sources.paths.dir),\n    modelPath: relative(sources.docsDir, sources.paths.model).split(/[\\\\/]/).join(\"/\"),\n    known: sources.known,\n    architecture: sources.architecture,\n    standalone: sources.standalone,\n    project: sources.project,\n  });\n}\n\n/**\n * A `LoadedDoc` carrying nothing — the shape a model that could not be read\n * answers with. A FUNCTION rather than a shared constant: the arrays reach\n * every caller, and one that pushed a finding into a module-level literal would\n * corrupt the answer for every other service in the run.\n */\nfunction noModel(): LoadedDoc {\n  return { errors: [], elements: [], relationships: [] };\n}\n\nexport async function loadServiceModel(req: ServiceModelRequest): Promise<ServiceModel> {\n  if (req.shape === \"standalone\") {\n    // Before the map is asked for, deliberately: a standalone model is a file\n    // parsed alone, so a reader of one must not pay for the `architecture/`\n    // project — nor inherit its failures.\n    return { shape: req.shape, doc: await req.standalone(), project: null, unowned: [], mapUnreadable: false };\n  }\n  const architecture = await req.architecture();\n  if (architecture.errors.length > 0) {\n    return { shape: req.shape, doc: noModel(), project: null, unowned: [], mapUnreadable: true };\n  }\n  const project = await req.project();\n  if (project.errors.length > 0) {\n    // Every error, not the ones whose path is the model's. The map parsed alone\n    // and came back clean, so an error now blamed on the landscape exists only\n    // because this model joined the set — and dropping it would grade the model\n    // valid while the renderer, reading the same two documents together,\n    // refuses to draw anything.\n    return {\n      shape: req.shape,\n      doc: { errors: project.errors, elements: [], relationships: [] },\n      project: null,\n      unowned: [],\n      mapUnreadable: false,\n    };\n  }\n  const slice = sliceForService({\n    project,\n    architecture,\n    service: req.service,\n    known: req.known,\n  });\n  return {\n    shape: req.shape,\n    doc: {\n      errors: [],\n      elements: slice.elements,\n      relationships: slice.relationships,\n      // The model file's OWN views, by the file each was written in. A service\n      // renders its own diagrams and the fleet's use cases are drawn over the\n      // same elements, so without the filter every service in the fleet would\n      // report every fleet-level view as one of its own.\n      views: (project.views ?? []).filter((view) => view.sourcePath === req.modelPath),\n      // The PROJECT's specification, deliberately: an extending model takes the\n      // map's kinds and tags, so \"what this model can use\" is the project's\n      // table, and a tags-only block of its own has already been merged into it.\n      ...(project.specification === undefined ? {} : { specification: project.specification }),\n    },\n    project,\n    unowned: slice.unowned,\n    mapUnreadable: false,\n  };\n}\n\n/**\n * Every extending model's per-service project, parsed in ONE workspace — the\n * engine under `../prefetch/fleet.ts`'s `prefetch`.\n *\n * Keyed by the RESOLVED model path, which is the key that memo files\n * per-service projects under; a second spelling would be a memo the prefetch\n * fills and no reader ever hits.\n *\n * A batch-infrastructure failure answers with an EMPTY map rather than\n * rejecting: the prefetch is an accelerator and nothing more, so a workspace\n * that could not be created must cost the run its speed and never one finding\n * (`FleetContext.prefetchLikeC4` has behaved this way since the batch loader\n * landed, and the two must not differ — a run that degrades one way and not the\n * other is a run whose report depends on the tmpdir).\n */\nexport async function batchServiceProjects(\n  docsDir: DocsDir,\n  models: readonly string[],\n): Promise<Map<string, LoadedDoc>> {\n  const out = new Map<string, LoadedDoc>();\n  if (models.length === 0) return out;\n  const requests = (await modelProjectSets(docsDir, models)).map((set) => ({\n    key: resolve(set.model),\n    base: docsDir,\n    paths: set.paths,\n  }));\n  try {\n    for (const [key, doc] of await loadProjectBatch(requests)) out.set(key, asLoadedDoc(doc));\n  } catch {\n    // Unreadable is not invalid: the caller seeds nothing and every reader\n    // falls back to its own per-project load.\n    return new Map();\n  }\n  return out;\n}\n"]}

package/dist/core/c4/service-model/renderer.js

@@ -0,0 +1,128 @@
+/**
+ * The `exclude` list `loam subsystem sync` WRITES back into the root
+ * `likec4.config.json` — the write half of the one file loam otherwise only
+ * reads. The read half, and the matcher that decides whether an entry hides a
+ * directory, are `../root-project/exclude.ts`: they moved down there when the
+ * project loader became a reader of the same list, and this module is the only
+ * thing left that computes new bytes for it.
+ *
+ * The ownership rule is stated once and holds for both halves: `exclude` is a
+ * glob list in a tool's own config, the team owns the file, and loam maintains
+ * exactly the `services/` entries that decide whether a model is renderable. An
+ * entry loam does not recognise is left exactly where the team put it.
+ */
+import { excludedDirectory, excludingEntry } from "../root-project/exclude.js";
+/** The `services/` prefix every tree path is spelled under, in the config and on disk alike. */
+const SERVICES = "services";
+/**
+ * The `exclude` list `loam subsystem sync` writes: loam's own entries
+ * recomputed from the shapes on disk, everybody else's kept exactly as written
+ * and in that order.
+ *
+ * WHICH ENTRIES ARE LOAM'S is the careful half, and it is decided by two
+ * different questions rather than one.
+ *
+ * The first is AUTHORSHIP: the whole `services/` tree is loam's (it wrote that
+ * entry into every scaffold before this axis), and so is any entry naming a
+ * `services/<tree>` the enumeration actually found — those are the entries this
+ * function produced on an earlier sync, and one of them must disappear the
+ * moment that service's model becomes extending. This is why the enumeration is
+ * a parameter rather than something inferred from the entries themselves: an
+ * entry cannot say who wrote it, but the tree can say whether it names a service.
+ *
+ * The second is EFFECT, and it is the half that was missing. An entry only has
+ * to cover an ANCESTOR of a tree to hide it — `excludingEntry` says so, because
+ * that is how the renderer reads the list — so a root config saying
+ * `services/platform/**` hides `services/platform/identity-service` just as
+ * completely as `services/**` does, while naming a directory the enumeration
+ * never returns as a service. Left alone it warned `service.model-excluded`
+ * forever and `sync` answered `updated: false`: a repair loop that never closed,
+ * with the message naming the command that would not perform it. So an entry
+ * that covers a tree whose model EXTENDS the map is dropped as well — the
+ * standalone trees such an entry also covered get their own entries back through
+ * the append below.
+ *
+ * THE TWO QUESTIONS ARE ASKED THROUGH DIFFERENT FUNCTIONS, and that is the
+ * correction this round made (verification 2026-09-04, review C). AUTHORSHIP is
+ * about the directory an entry NAMES, so it goes through `excludedDirectory`,
+ * which answers null for an entry naming no plain directory at all (a starred
+ * middle segment, the `node_modules` glob). EFFECT is about what an entry HIDES,
+ * so it goes through `excludingEntry` — the same matcher the read side uses,
+ * whatever the entry's spelling. Asking effect through `excludedDirectory` too
+ * meant an entry with a star where the subsystem name goes was `kept`
+ * unconditionally: it hid an extending model forever while
+ * `service.model-excluded` named this command as the repair, which is the very
+ * loop the effect rule was added to close.
+ *
+ * Everything else survives untouched, INCLUDING a `services/legacy/**` for a
+ * directory that is not a service at all, and including a covering entry that
+ * hides only standalone trees: those are the team's own globs about their own
+ * tree, they hide nothing that needs to be visible, and a sync that ate one
+ * would be loam deleting a line it never wrote. Only the entries that make a
+ * renderable model unrenderable are taken.
+ *
+ * A standalone model MUST be excluded: it declares its own kinds, so inside the
+ * root project every one of them is a duplicate blamed on the fleet map as
+ * well, which blanks the whole project. An extending model must NOT be: the
+ * root project is the only place it parses at all.
+ *
+ * NOTHING IS APPENDED FOR A TREE THE SURVIVING LIST ALREADY COVERS. A second
+ * entry would be a line a person did not write appearing in a file they own,
+ * for a directory the renderer already skips — and SCHEMA.md promises exactly
+ * that ("a directory the list already covers in any of those spellings earns no
+ * second entry"). The risk it leaves is real and it is the recoverable one: if
+ * the team narrows their covering glob tomorrow, the standalone model becomes
+ * visible in the root project, `validate --all` says so as
+ * `service.model-unexcluded`, and the next sync writes the entry. A duplicate
+ * cannot be un-written by any command at all.
+ *
+ * The appended entries are sorted rather than kept in tree order because the
+ * file is a diff a person reads: a service adopted into the middle of a
+ * subsystem would otherwise move every line after it.
+ */
+export function standaloneExclude(exclude, trees) {
+    const enumerated = new Set(trees.enumerated.map(treeUnderServices));
+    const kept = exclude.filter((entry) => {
+        // EFFECT first, and through the matcher rather than through the directory
+        // the entry names: an entry that hides a model which only parses inside the
+        // root project has to go whatever its spelling, and the authorship half
+        // below cannot see half of those spellings.
+        if (trees.extending.some((tree) => excludingEntry([entry], tree) !== null))
+            return false;
+        const dir = servicesTreeOf(entry);
+        if (dir === null)
+            return true;
+        // The whole `services/` tree, however spelled: loam wrote that entry into
+        // every scaffold before the extending shape existed, and it is the one this
+        // rewrite exists to take back.
+        if (dir === "")
+            return false;
+        return !enumerated.has(dir);
+    });
+    const owed = [...new Set(trees.standalone.map(treeUnderServices))].sort();
+    return [...kept, ...owed.filter((tree) => excludingEntry(kept, tree) === null).map((tree) => `${SERVICES}/${tree}/**`)];
+}
+/**
+ * The service tree an entry names — the part under `services/` — or null when
+ * the entry is about something else entirely. `""` is the `services/` root
+ * itself.
+ *
+ * An entry that names no plain directory — a wildcard segment between two
+ * literal ones, or the leading doubled star of the `node_modules` glob —
+ * answers null: loam cannot say which trees such a line is about, so it is
+ * never loam's to rewrite, whatever it happens to cover.
+ */
+function servicesTreeOf(entry) {
+    const dir = excludedDirectory(entry);
+    if (dir === null)
+        return null;
+    if (dir === SERVICES)
+        return "";
+    return dir.startsWith(`${SERVICES}/`) ? dir.slice(SERVICES.length + 1) : null;
+}
+/** A tree path with the `services/` prefix stripped if the caller spelled it — `excludingEntry`'s normalisation, one level down. */
+function treeUnderServices(tree) {
+    const spelled = tree.split(/[\\/]/).filter((s) => s.length > 0).join("/");
+    return spelled.startsWith(`${SERVICES}/`) ? spelled.slice(SERVICES.length + 1) : spelled;
+}
+//# sourceMappingURL=renderer.js.map

package/dist/core/c4/service-model/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","sourceRoot":"","sources":["../../../../src/core/c4/service-model/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE/E,gGAAgG;AAChG,MAAM,QAAQ,GAAG,UAAU,CAAC;AAe5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA0B,EAAE,KAAmB;IAC/E,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QACpC,0EAA0E;QAC1E,4EAA4E;QAC5E,wEAAwE;QACxE,4CAA4C;QAC5C,IAAI,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACzF,MAAM,GAAG,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC9B,0EAA0E;QAC1E,4EAA4E;QAC5E,+BAA+B;QAC/B,IAAI,GAAG,KAAK,EAAE;YAAE,OAAO,KAAK,CAAC;QAC7B,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1E,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,QAAQ,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC;AAC1H,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,cAAc,CAAC,KAAa;IACnC,MAAM,GAAG,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IAChC,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAChF,CAAC;AAED,oIAAoI;AACpI,SAAS,iBAAiB,CAAC,IAAY;IACrC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1E,OAAO,OAAO,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AAC3F,CAAC","sourcesContent":["/**\n * The `exclude` list `loam subsystem sync` WRITES back into the root\n * `likec4.config.json` — the write half of the one file loam otherwise only\n * reads. The read half, and the matcher that decides whether an entry hides a\n * directory, are `../root-project/exclude.ts`: they moved down there when the\n * project loader became a reader of the same list, and this module is the only\n * thing left that computes new bytes for it.\n *\n * The ownership rule is stated once and holds for both halves: `exclude` is a\n * glob list in a tool's own config, the team owns the file, and loam maintains\n * exactly the `services/` entries that decide whether a model is renderable. An\n * entry loam does not recognise is left exactly where the team put it.\n */\nimport { excludedDirectory, excludingEntry } from \"../root-project/exclude.js\";\n\n/** The `services/` prefix every tree path is spelled under, in the config and on disk alike. */\nconst SERVICES = \"services\";\n\n/** The service trees a rewrite is computed against: which stand alone, and which exist at all. */\nexport interface ExcludeTrees {\n  /** Every service whose model declares its own kinds, and so must be excluded. */\n  standalone: readonly string[];\n  /**\n   * Every service whose model EXTENDS the map, and so must NOT be excluded by\n   * anything — the trees a covering entry is measured against below.\n   */\n  extending: readonly string[];\n  /** Every service the enumeration found — the domain loam's own entries are drawn from. */\n  enumerated: readonly string[];\n}\n\n/**\n * The `exclude` list `loam subsystem sync` writes: loam's own entries\n * recomputed from the shapes on disk, everybody else's kept exactly as written\n * and in that order.\n *\n * WHICH ENTRIES ARE LOAM'S is the careful half, and it is decided by two\n * different questions rather than one.\n *\n * The first is AUTHORSHIP: the whole `services/` tree is loam's (it wrote that\n * entry into every scaffold before this axis), and so is any entry naming a\n * `services/<tree>` the enumeration actually found — those are the entries this\n * function produced on an earlier sync, and one of them must disappear the\n * moment that service's model becomes extending. This is why the enumeration is\n * a parameter rather than something inferred from the entries themselves: an\n * entry cannot say who wrote it, but the tree can say whether it names a service.\n *\n * The second is EFFECT, and it is the half that was missing. An entry only has\n * to cover an ANCESTOR of a tree to hide it — `excludingEntry` says so, because\n * that is how the renderer reads the list — so a root config saying\n * `services/platform/**` hides `services/platform/identity-service` just as\n * completely as `services/**` does, while naming a directory the enumeration\n * never returns as a service. Left alone it warned `service.model-excluded`\n * forever and `sync` answered `updated: false`: a repair loop that never closed,\n * with the message naming the command that would not perform it. So an entry\n * that covers a tree whose model EXTENDS the map is dropped as well — the\n * standalone trees such an entry also covered get their own entries back through\n * the append below.\n *\n * THE TWO QUESTIONS ARE ASKED THROUGH DIFFERENT FUNCTIONS, and that is the\n * correction this round made (verification 2026-09-04, review C). AUTHORSHIP is\n * about the directory an entry NAMES, so it goes through `excludedDirectory`,\n * which answers null for an entry naming no plain directory at all (a starred\n * middle segment, the `node_modules` glob). EFFECT is about what an entry HIDES,\n * so it goes through `excludingEntry` — the same matcher the read side uses,\n * whatever the entry's spelling. Asking effect through `excludedDirectory` too\n * meant an entry with a star where the subsystem name goes was `kept`\n * unconditionally: it hid an extending model forever while\n * `service.model-excluded` named this command as the repair, which is the very\n * loop the effect rule was added to close.\n *\n * Everything else survives untouched, INCLUDING a `services/legacy/**` for a\n * directory that is not a service at all, and including a covering entry that\n * hides only standalone trees: those are the team's own globs about their own\n * tree, they hide nothing that needs to be visible, and a sync that ate one\n * would be loam deleting a line it never wrote. Only the entries that make a\n * renderable model unrenderable are taken.\n *\n * A standalone model MUST be excluded: it declares its own kinds, so inside the\n * root project every one of them is a duplicate blamed on the fleet map as\n * well, which blanks the whole project. An extending model must NOT be: the\n * root project is the only place it parses at all.\n *\n * NOTHING IS APPENDED FOR A TREE THE SURVIVING LIST ALREADY COVERS. A second\n * entry would be a line a person did not write appearing in a file they own,\n * for a directory the renderer already skips — and SCHEMA.md promises exactly\n * that (\"a directory the list already covers in any of those spellings earns no\n * second entry\"). The risk it leaves is real and it is the recoverable one: if\n * the team narrows their covering glob tomorrow, the standalone model becomes\n * visible in the root project, `validate --all` says so as\n * `service.model-unexcluded`, and the next sync writes the entry. A duplicate\n * cannot be un-written by any command at all.\n *\n * The appended entries are sorted rather than kept in tree order because the\n * file is a diff a person reads: a service adopted into the middle of a\n * subsystem would otherwise move every line after it.\n */\nexport function standaloneExclude(exclude: readonly string[], trees: ExcludeTrees): string[] {\n  const enumerated = new Set(trees.enumerated.map(treeUnderServices));\n  const kept = exclude.filter((entry) => {\n    // EFFECT first, and through the matcher rather than through the directory\n    // the entry names: an entry that hides a model which only parses inside the\n    // root project has to go whatever its spelling, and the authorship half\n    // below cannot see half of those spellings.\n    if (trees.extending.some((tree) => excludingEntry([entry], tree) !== null)) return false;\n    const dir = servicesTreeOf(entry);\n    if (dir === null) return true;\n    // The whole `services/` tree, however spelled: loam wrote that entry into\n    // every scaffold before the extending shape existed, and it is the one this\n    // rewrite exists to take back.\n    if (dir === \"\") return false;\n    return !enumerated.has(dir);\n  });\n  const owed = [...new Set(trees.standalone.map(treeUnderServices))].sort();\n  return [...kept, ...owed.filter((tree) => excludingEntry(kept, tree) === null).map((tree) => `${SERVICES}/${tree}/**`)];\n}\n\n/**\n * The service tree an entry names — the part under `services/` — or null when\n * the entry is about something else entirely. `\"\"` is the `services/` root\n * itself.\n *\n * An entry that names no plain directory — a wildcard segment between two\n * literal ones, or the leading doubled star of the `node_modules` glob —\n * answers null: loam cannot say which trees such a line is about, so it is\n * never loam's to rewrite, whatever it happens to cover.\n */\nfunction servicesTreeOf(entry: string): string | null {\n  const dir = excludedDirectory(entry);\n  if (dir === null) return null;\n  if (dir === SERVICES) return \"\";\n  return dir.startsWith(`${SERVICES}/`) ? dir.slice(SERVICES.length + 1) : null;\n}\n\n/** A tree path with the `services/` prefix stripped if the caller spelled it — `excludingEntry`'s normalisation, one level down. */\nfunction treeUnderServices(tree: string): string {\n  const spelled = tree.split(/[\\\\/]/).filter((s) => s.length > 0).join(\"/\");\n  return spelled.startsWith(`${SERVICES}/`) ? spelled.slice(SERVICES.length + 1) : spelled;\n}\n"]}

package/dist/core/c4/service-model/shape.js

@@ -0,0 +1,126 @@
+/**
+ * Which of the two shapes a `model.likec4` has, decided by a byte scan of the
+ * file itself.
+ *
+ * A STANDALONE model declares at least one `element <kind>` inside a top-level
+ * `specification { }` block. It is parsed ALONE, exactly as every model was
+ * before this axis: it may re-declare the partners it talks to, and it renders
+ * only as a project of its own. An EXTENDING model declares no element kind —
+ * it takes the map's — and says what is inside the service with
+ * `extend <fqn> { … }`; it is parsed INSIDE the fleet's `architecture/`
+ * project, beside the map that declares those kinds.
+ *
+ * THE FILE'S OWN GRAMMAR DECIDES, never a config key, and that is the whole
+ * design of this module. A flag in `loam.json` would be a second authority on a
+ * fact the document already states, free to disagree with it — and the
+ * disagreement is not a warning but a parse: a model read the wrong way is
+ * either eleven `c4.invalid` errors (an extending model parsed alone: measured,
+ * deleting a model's `specification` under the old loader) or a pile of
+ * duplicate-declaration errors blamed on BOTH files (a standalone model staged
+ * beside the landscape). Nothing about a model has to be migrated for loam to
+ * read it correctly; the bytes say which it is.
+ *
+ * Every other answer is `extending`, and each of those is legal on purpose: a
+ * tags-only `specification { tag req-X }` (measured legal inside one project,
+ * and it lands the tag in the project's specification), a bare `model {}`, an
+ * empty file, a file that is only `views { }`. The conservative direction is
+ * therefore towards `extending` — which is why an unreadable file is NOT
+ * classified here at all (see `FleetContext.serviceModel`): absence is a
+ * question for the reader that establishes the file exists, not for a scanner
+ * looking at bytes it does not have.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { inOrder } from "../../kernel/concurrency.js";
+import { maskSource, matchBrace } from "../source-mask.js";
+/**
+ * A kind declaration inside a specification block — `element service`,
+ * `element softwareSystem`. Deliberately only `element`: `tag`,
+ * `relationship`, `deploymentNode` and `color` declare no ELEMENT kind, and a
+ * model whose specification holds only those still takes every element kind it
+ * uses from the map, which is exactly what makes it extending.
+ */
+const ELEMENT_KIND = /\belement\s+[A-Za-z_][\w-]*/;
+/**
+ * The shape of a model, from its source text.
+ *
+ * The scan runs over MASKED source (`../source-mask.ts`), so a comment or a
+ * string containing `specification { element x }` counts for nothing — and that
+ * is not a hypothetical: the brief loam writes for an adopted service explains
+ * the other shape in a comment, so an authored model can easily carry those
+ * exact words in prose. Reading them as a declaration would flip a whole
+ * service to the wrong loader.
+ *
+ * Only TOP-LEVEL blocks are considered — depth zero in the masked source — for
+ * the same reason: `specification` nested inside another block is not a
+ * declaration LikeC4 would honour, so loam must not honour it either.
+ *
+ * An unbalanced block (no closing brace) is read to end of file and still
+ * answers `standalone` when it declares a kind. That file does not parse at
+ * all, and both loaders will say so; answering `standalone` sends the reader to
+ * the one whose errors name only this file, which is the honest half of a
+ * broken document.
+ */
+export function modelShape(text) {
+    const { code } = maskSource(text);
+    // Built per call rather than hoisted to module scope: a `/g` regex carries
+    // `lastIndex`, which is mutable state a second caller would inherit — the
+    // module-level-state hazard AGENTS.md names, arriving through a constant that
+    // looks immutable.
+    const specification = /\bspecification\s*\{/g;
+    for (let match = specification.exec(code); match !== null; match = specification.exec(code)) {
+        const open = match.index + match[0].length - 1;
+        if (depthBefore(code, match.index) !== 0)
+            continue;
+        const close = matchBrace(code, open);
+        const body = close === -1 ? code.slice(open + 1) : code.slice(open + 1, close);
+        if (ELEMENT_KIND.test(body))
+            return "standalone";
+    }
+    return "extending";
+}
+/**
+ * One model's shape, from its bytes — the shape of a file that cannot be read
+ * is `standalone`.
+ *
+ * That is the conservative arm rather than a guess. The standalone path hands
+ * the model to the per-file loader, so a caller asking about a file that is not
+ * there (or is not readable) gets today's exact error — `c4.invalid`, naming
+ * that file — instead of a slice of the fleet map, which is what the extending
+ * path would answer about a document nobody could open.
+ */
+export async function readModelShape(path) {
+    return readFile(path, "utf8").then(modelShape, () => "standalone");
+}
+/**
+ * Many models' shapes at once, keyed by RESOLVED path.
+ *
+ * The fleet needs this list before it can do anything else: which models are
+ * batched as projects and which as documents, which directories are owed a
+ * per-service `likec4.config.json` and which must not have one. Every one of
+ * those questions is asked over the FULL service enumeration rather than over
+ * whatever subset a run is grading, so the read is a bulk one through the
+ * shared pool — a fleet of 56 models is 56 small reads, and the pool is what
+ * keeps them from being 56 sequential round-trips on a network-mounted docs
+ * repo.
+ */
+export async function readModelShapes(paths) {
+    const entries = await inOrder(paths, async (path) => [resolve(path), await readModelShape(path)]);
+    return new Map(entries);
+}
+/**
+ * How many blocks are open at `index` in masked code. A plain count, because
+ * the mask has already blanked every brace inside a string or a comment — the
+ * one thing that would make counting lie.
+ */
+function depthBefore(code, index) {
+    let depth = 0;
+    for (let i = 0; i < index; i += 1) {
+        if (code[i] === "{")
+            depth += 1;
+        else if (code[i] === "}")
+            depth -= 1;
+    }
+    return depth;
+}
+//# sourceMappingURL=shape.js.map

package/dist/core/c4/service-model/shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape.js","sourceRoot":"","sources":["../../../../src/core/c4/service-model/shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI3D;;;;;;GAMG;AACH,MAAM,YAAY,GAAG,6BAA6B,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,EAAE,IAAI,EAAE,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAClC,2EAA2E;IAC3E,0EAA0E;IAC1E,8EAA8E;IAC9E,mBAAmB;IACnB,MAAM,aAAa,GAAG,uBAAuB,CAAC;IAC9C,KAAK,IAAI,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,KAAK,IAAI,EAAE,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5F,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAC/C,IAAI,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;YAAE,SAAS;QACnD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QAC/E,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,YAAY,CAAC;IACnD,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAY;IAC/C,OAAO,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,UAAU,EAAE,GAAe,EAAE,CAAC,YAAY,CAAC,CAAC;AACjF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAAwB;IAC5D,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,cAAc,CAAC,IAAI,CAAC,CAAU,CAAC,CAAC;IAC3G,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,IAAY,EAAE,KAAa;IAC9C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG;YAAE,KAAK,IAAI,CAAC,CAAC;aAC3B,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG;YAAE,KAAK,IAAI,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["/**\n * Which of the two shapes a `model.likec4` has, decided by a byte scan of the\n * file itself.\n *\n * A STANDALONE model declares at least one `element <kind>` inside a top-level\n * `specification { }` block. It is parsed ALONE, exactly as every model was\n * before this axis: it may re-declare the partners it talks to, and it renders\n * only as a project of its own. An EXTENDING model declares no element kind —\n * it takes the map's — and says what is inside the service with\n * `extend <fqn> { … }`; it is parsed INSIDE the fleet's `architecture/`\n * project, beside the map that declares those kinds.\n *\n * THE FILE'S OWN GRAMMAR DECIDES, never a config key, and that is the whole\n * design of this module. A flag in `loam.json` would be a second authority on a\n * fact the document already states, free to disagree with it — and the\n * disagreement is not a warning but a parse: a model read the wrong way is\n * either eleven `c4.invalid` errors (an extending model parsed alone: measured,\n * deleting a model's `specification` under the old loader) or a pile of\n * duplicate-declaration errors blamed on BOTH files (a standalone model staged\n * beside the landscape). Nothing about a model has to be migrated for loam to\n * read it correctly; the bytes say which it is.\n *\n * Every other answer is `extending`, and each of those is legal on purpose: a\n * tags-only `specification { tag req-X }` (measured legal inside one project,\n * and it lands the tag in the project's specification), a bare `model {}`, an\n * empty file, a file that is only `views { }`. The conservative direction is\n * therefore towards `extending` — which is why an unreadable file is NOT\n * classified here at all (see `FleetContext.serviceModel`): absence is a\n * question for the reader that establishes the file exists, not for a scanner\n * looking at bytes it does not have.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport { inOrder } from \"../../kernel/concurrency.js\";\nimport { maskSource, matchBrace } from \"../source-mask.js\";\n\nexport type ModelShape = \"standalone\" | \"extending\";\n\n/**\n * A kind declaration inside a specification block — `element service`,\n * `element softwareSystem`. Deliberately only `element`: `tag`,\n * `relationship`, `deploymentNode` and `color` declare no ELEMENT kind, and a\n * model whose specification holds only those still takes every element kind it\n * uses from the map, which is exactly what makes it extending.\n */\nconst ELEMENT_KIND = /\\belement\\s+[A-Za-z_][\\w-]*/;\n\n/**\n * The shape of a model, from its source text.\n *\n * The scan runs over MASKED source (`../source-mask.ts`), so a comment or a\n * string containing `specification { element x }` counts for nothing — and that\n * is not a hypothetical: the brief loam writes for an adopted service explains\n * the other shape in a comment, so an authored model can easily carry those\n * exact words in prose. Reading them as a declaration would flip a whole\n * service to the wrong loader.\n *\n * Only TOP-LEVEL blocks are considered — depth zero in the masked source — for\n * the same reason: `specification` nested inside another block is not a\n * declaration LikeC4 would honour, so loam must not honour it either.\n *\n * An unbalanced block (no closing brace) is read to end of file and still\n * answers `standalone` when it declares a kind. That file does not parse at\n * all, and both loaders will say so; answering `standalone` sends the reader to\n * the one whose errors name only this file, which is the honest half of a\n * broken document.\n */\nexport function modelShape(text: string): ModelShape {\n  const { code } = maskSource(text);\n  // Built per call rather than hoisted to module scope: a `/g` regex carries\n  // `lastIndex`, which is mutable state a second caller would inherit — the\n  // module-level-state hazard AGENTS.md names, arriving through a constant that\n  // looks immutable.\n  const specification = /\\bspecification\\s*\\{/g;\n  for (let match = specification.exec(code); match !== null; match = specification.exec(code)) {\n    const open = match.index + match[0].length - 1;\n    if (depthBefore(code, match.index) !== 0) continue;\n    const close = matchBrace(code, open);\n    const body = close === -1 ? code.slice(open + 1) : code.slice(open + 1, close);\n    if (ELEMENT_KIND.test(body)) return \"standalone\";\n  }\n  return \"extending\";\n}\n\n/**\n * One model's shape, from its bytes — the shape of a file that cannot be read\n * is `standalone`.\n *\n * That is the conservative arm rather than a guess. The standalone path hands\n * the model to the per-file loader, so a caller asking about a file that is not\n * there (or is not readable) gets today's exact error — `c4.invalid`, naming\n * that file — instead of a slice of the fleet map, which is what the extending\n * path would answer about a document nobody could open.\n */\nexport async function readModelShape(path: string): Promise<ModelShape> {\n  return readFile(path, \"utf8\").then(modelShape, (): ModelShape => \"standalone\");\n}\n\n/**\n * Many models' shapes at once, keyed by RESOLVED path.\n *\n * The fleet needs this list before it can do anything else: which models are\n * batched as projects and which as documents, which directories are owed a\n * per-service `likec4.config.json` and which must not have one. Every one of\n * those questions is asked over the FULL service enumeration rather than over\n * whatever subset a run is grading, so the read is a bulk one through the\n * shared pool — a fleet of 56 models is 56 small reads, and the pool is what\n * keeps them from being 56 sequential round-trips on a network-mounted docs\n * repo.\n */\nexport async function readModelShapes(paths: readonly string[]): Promise<Map<string, ModelShape>> {\n  const entries = await inOrder(paths, async (path) => [resolve(path), await readModelShape(path)] as const);\n  return new Map(entries);\n}\n\n/**\n * How many blocks are open at `index` in masked code. A plain count, because\n * the mask has already blanked every brace inside a string or a comment — the\n * one thing that would make counting lie.\n */\nfunction depthBefore(code: string, index: number): number {\n  let depth = 0;\n  for (let i = 0; i < index; i += 1) {\n    if (code[i] === \"{\") depth += 1;\n    else if (code[i] === \"}\") depth -= 1;\n  }\n  return depth;\n}\n"]}