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

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

@@ -0,0 +1,187 @@
+/**
+ * One directory of `.likec4` documents, loaded as ONE LikeC4 project — the way
+ * the renderer already reads `architecture/`.
+ *
+ * A package of its own rather than more of `../workspace.ts`, and the seam is
+ * the isolation rule, not the line count. That module stages every document as
+ * its own single-file project ON PURPOSE, so an author-written `import` can
+ * never resolve against a sibling; this one does the opposite deliberately, for
+ * the set of documents that are meant to see each other. Two loaders with
+ * opposite contracts should not share a file: the next reader has to be able to
+ * tell at a glance which one they are looking at.
+ */
+import { randomBytes } from "node:crypto";
+import { copyFile, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { LikeC4 } from "likec4";
+import { inOrder } from "../../kernel/concurrency.js";
+import { flattenModel } from "../likec4.js";
+import { readDynamicViews } from "../parsed/dynamic-views.js";
+import { readSpecification } from "../parsed/specification.js";
+import { readViewIds } from "../parsed/view-ids.js";
+import { readDeployment, NO_DEPLOYMENT } from "../parsed/deployment.js";
+/**
+ * Stage a set of documents as ONE project, mirroring their paths relative to
+ * `base`.
+ *
+ * The relative structure is preserved rather than flattened to basenames, and
+ * that is load-bearing twice over: two use cases named `checkout.likec4` in
+ * different subdirectories would overwrite each other on copy, and LikeC4
+ * reports a view's `sourcePath` relative to the project root — so flattening
+ * would make every finding name a file the author cannot find.
+ */
+async function stageProject(root, base, targets) {
+    const project = `arch_${randomBytes(8).toString("hex")}`;
+    const folder = join(root, project);
+    await mkdir(folder, { recursive: true });
+    await writeFile(join(folder, "likec4.config.json"), JSON.stringify({ name: project }), "utf8");
+    // rel -> real path, so an error carrying the staged path can be handed back
+    // spelled the way the author wrote it.
+    const byRel = new Map();
+    await inOrder(targets, async (path) => {
+        const rel = relative(base, path).split(/[\\/]/).join("/");
+        const dest = join(folder, ...rel.split("/"));
+        try {
+            await mkdir(dirname(dest), { recursive: true });
+            await copyFile(path, dest);
+            byRel.set(rel, path);
+        }
+        catch {
+            // Dropped, exactly as `stage` drops one: the caller's ordinary per-path
+            // load owns the error, and a project missing one document still answers
+            // about the rest.
+        }
+        return null;
+    });
+    return byRel;
+}
+/**
+ * Load a directory of `.likec4` documents as ONE LikeC4 project — the way the
+ * renderer already reads `architecture/`, and the only way a document that
+ * declares views over ANOTHER file's elements can be read at all.
+ *
+ * Measured at the 1.59.2 pin: a views-only `usecases/checkout.likec4` parsed
+ * alone is five errors (unresolved tag, unresolved elements); the same file
+ * beside its landscape in one project is zero, and each view comes back with
+ * its own `sourcePath`. That is the whole reason this function exists — a use
+ * case lives in a file of its own, and `loadBatch`'s one-project-per-document
+ * isolation makes such a file unreadable by construction.
+ *
+ * Two rules the caller must know, because both invert what holds elsewhere:
+ *
+ *  - **Exactly one document in the set declares the `specification` block.**
+ *    Every `.likec4` file loam parses alone must declare its own; inside one
+ *    project a second declaration is a duplicate error blamed on BOTH files
+ *    (measured).
+ *  - **Errors are per document, but the MODEL is all-or-nothing.** A typo in
+ *    one file is attributed to that file — so the finding names it, which is
+ *    better than today, where a use case in the landscape would blame the
+ *    landscape — but loam's standing rule is that errors mean no model, and
+ *    here the model is the project's. `clean` says which case the caller is in.
+ *
+ * The generated `architecture/subsystems.likec4` must NOT be in `targets`:
+ * docs/DESIGN.md rule 26 keeps it a byte compare, and a stale one whose
+ * `include` names a removed element would otherwise be a parse error that
+ * blanks the whole fleet map.
+ */
+export async function loadProject(base, paths) {
+    const empty = (errors, clean) => ({
+        errors,
+        clean,
+        elements: [],
+        relationships: [],
+        views: [],
+        viewIds: [],
+        deployment: NO_DEPLOYMENT,
+    });
+    const targets = [...new Set(paths.map((path) => resolve(path)))];
+    if (targets.length === 0)
+        return empty(new Map(), true);
+    const root = await mkdtemp(join(tmpdir(), "loam-c4-"));
+    try {
+        const byRel = await stageProject(root, resolve(base), targets);
+        if (byRel.size === 0)
+            return empty(new Map(), true);
+        const likec4 = await LikeC4.fromWorkspace(root, { logger: false });
+        try {
+            const errors = groupProjectErrors(likec4, byRel);
+            if (errors.size > 0)
+                return empty(errors, false);
+            const model = (await likec4.parsedModel());
+            return {
+                errors,
+                clean: true,
+                specification: readSpecification(model.specification),
+                views: readDynamicViews(model),
+                viewIds: readViewIds(model),
+                deployment: readDeployment(model),
+                ...flattenModel(model),
+            };
+        }
+        finally {
+            await likec4.dispose();
+        }
+    }
+    finally {
+        await rm(root, { recursive: true, force: true });
+    }
+}
+/**
+ * `getErrors()` split per DOCUMENT inside one project, each error's
+ * `sourceFsPath` rewritten to the document's real absolute path.
+ *
+ * `groupErrors` above keys on the project folder segment, which cannot work
+ * here — every document shares one project. This keys on the staged relative
+ * path instead, longest first so `usecases/checkout.likec4` is matched before a
+ * hypothetical `checkout.likec4` at the root. An error nobody can attribute
+ * throws for the same reason it does there: a dropped error grades its document
+ * clean, which is failing open in the fleet gate.
+ */
+function groupProjectErrors(likec4, byRel) {
+    const rels = [...byRel.keys()].sort((a, b) => b.length - a.length);
+    const grouped = new Map();
+    for (const err of likec4.getErrors()) {
+        const spelled = err.sourceFsPath.split(/[\\/]/).join("/");
+        const rel = rels.find((candidate) => spelled.endsWith(`/${candidate}`) || spelled === candidate);
+        if (rel === undefined) {
+            throw new Error(`unattributable LikeC4 error in project workspace: ${err.message}`);
+        }
+        const real = byRel.get(rel);
+        const list = grouped.get(real) ?? [];
+        list.push({ ...err, sourceFsPath: real });
+        grouped.set(real, list);
+    }
+    return grouped;
+}
+/**
+ * A `ProjectDoc` in the shape every existing landscape reader already takes.
+ *
+ * The per-file error map flattens into one list, which loses nothing: each
+ * error still carries the real path of the document that raised it, so a
+ * finding can name the file even though the list is flat. Sorted by that path
+ * so a project with two broken documents reports them in a stable order —
+ * `getErrors()` returns whatever order the workspace scan produced.
+ *
+ * The model travels only when the project is clean, which is loam's standing
+ * rule (`errors mean no model`) applied at project altitude: a use-case file
+ * with an unresolved element leaves the landscape unusable, and pretending
+ * otherwise would grade a fleet against half a map.
+ */
+export function asLoadedDoc(doc) {
+    const errors = [...doc.errors]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .flatMap(([, list]) => list);
+    if (!doc.clean)
+        return { errors, elements: [], relationships: [] };
+    return {
+        errors,
+        ...(doc.specification === undefined ? {} : { specification: doc.specification }),
+        views: doc.views,
+        viewIds: doc.viewIds,
+        deployment: doc.deployment,
+        elements: doc.elements,
+        relationships: doc.relationships,
+    };
+}
+//# sourceMappingURL=load.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../../../src/core/c4/project/load.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AACtD,OAAO,EAAE,YAAY,EAA6E,MAAM,cAAc,CAAC;AACvH,OAAO,EAAE,gBAAgB,EAAmB,MAAM,4BAA4B,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAyB,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,WAAW,EAAoB,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAwB,MAAM,yBAAyB,CAAC;AAmB9F;;;;;;;;;GASG;AACH,KAAK,UAAU,YAAY,CAAC,IAAY,EAAE,IAAY,EAAE,OAAiB;IACvE,MAAM,OAAO,GAAG,QAAQ,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACnC,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,oBAAoB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;IAC/F,4EAA4E;IAC5E,uCAAuC;IACvC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,MAAM,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACpC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1D,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7C,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAChD,MAAM,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC3B,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;YACxE,wEAAwE;YACxE,kBAAkB;QACpB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,KAAe;IAC7D,MAAM,KAAK,GAAG,CAAC,MAAkC,EAAE,KAAc,EAAc,EAAE,CAAC,CAAC;QACjF,MAAM;QACN,KAAK;QACL,QAAQ,EAAE,EAAE;QACZ,aAAa,EAAE,EAAE;QACjB,KAAK,EAAE,EAAE;QACT,OAAO,EAAE,EAAE;QACX,UAAU,EAAE,aAAa;KAC1B,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,IAAI,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QAC/D,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,IAAI,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YACjD,IAAI,MAAM,CAAC,IAAI,GAAG,CAAC;gBAAE,OAAO,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YACjD,MAAM,KAAK,GAAG,CAAC,MAAM,MAAM,CAAC,WAAW,EAAE,CAAkB,CAAC;YAC5D,OAAO;gBACL,MAAM;gBACN,KAAK,EAAE,IAAI;gBACX,aAAa,EAAE,iBAAiB,CAAC,KAAK,CAAC,aAAa,CAAC;gBACrD,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC;gBAC9B,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC;gBAC3B,UAAU,EAAE,cAAc,CAAC,KAAK,CAAC;gBACjC,GAAG,YAAY,CAAC,KAAK,CAAC;aACvB,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACzB,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,kBAAkB,CAAC,MAAc,EAAE,KAA0B;IACpE,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IACnE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IACjD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,SAAS,EAAE,CAAC,IAAI,OAAO,KAAK,SAAS,CAAC,CAAC;QACjG,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,qDAAqD,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACtF,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,GAAe;IACzC,MAAM,MAAM,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC;SAC3B,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAChD,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC,GAAG,CAAC,KAAK;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;IACnE,OAAO;QACL,MAAM;QACN,GAAG,CAAC,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC;QAChF,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,aAAa,EAAE,GAAG,CAAC,aAAa;KACjC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * One directory of `.likec4` documents, loaded as ONE LikeC4 project — the way\n * the renderer already reads `architecture/`.\n *\n * A package of its own rather than more of `../workspace.ts`, and the seam is\n * the isolation rule, not the line count. That module stages every document as\n * its own single-file project ON PURPOSE, so an author-written `import` can\n * never resolve against a sibling; this one does the opposite deliberately, for\n * the set of documents that are meant to see each other. Two loaders with\n * opposite contracts should not share a file: the next reader has to be able to\n * tell at a glance which one they are looking at.\n */\nimport { randomBytes } from \"node:crypto\";\nimport { copyFile, mkdir, mkdtemp, rm, writeFile } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { dirname, join, relative, resolve } from \"node:path\";\nimport { LikeC4 } from \"likec4\";\nimport { inOrder } from \"../../kernel/concurrency.js\";\nimport { flattenModel, type Elem, type LikeC4Error, type LoadedDoc, type ReadableModel, type Rel } from \"../likec4.js\";\nimport { readDynamicViews, type ParsedView } from \"../parsed/dynamic-views.js\";\nimport { readSpecification, type DocSpecification } from \"../parsed/specification.js\";\nimport { readViewIds, type ViewIdClaim } from \"../parsed/view-ids.js\";\nimport { readDeployment, NO_DEPLOYMENT, type DeploymentModel } from \"../parsed/deployment.js\";\n\n/** A directory of `.likec4` documents loaded as one LikeC4 project. */\nexport interface ProjectDoc {\n  /** Errors by the REAL absolute path of the document that raised them. */\n  errors: Map<string, LikeC4Error[]>;\n  /** True when no document in the project raised one — loam's \"errors mean no model\" gate. */\n  clean: boolean;\n  elements: Elem[];\n  relationships: Rel[];\n  specification?: DocSpecification;\n  /** Every dynamic view the project declares, each carrying the file it is written in. */\n  views: ParsedView[];\n  /** Every authored view id the project claims, each with its file. */\n  viewIds: ViewIdClaim[];\n  /** The project's deployment model — empty when it declares none, and when it did not parse. */\n  deployment: DeploymentModel;\n}\n\n/**\n * Stage a set of documents as ONE project, mirroring their paths relative to\n * `base`.\n *\n * The relative structure is preserved rather than flattened to basenames, and\n * that is load-bearing twice over: two use cases named `checkout.likec4` in\n * different subdirectories would overwrite each other on copy, and LikeC4\n * reports a view's `sourcePath` relative to the project root — so flattening\n * would make every finding name a file the author cannot find.\n */\nasync function stageProject(root: string, base: string, targets: string[]): Promise<Map<string, string>> {\n  const project = `arch_${randomBytes(8).toString(\"hex\")}`;\n  const folder = join(root, project);\n  await mkdir(folder, { recursive: true });\n  await writeFile(join(folder, \"likec4.config.json\"), JSON.stringify({ name: project }), \"utf8\");\n  // rel -> real path, so an error carrying the staged path can be handed back\n  // spelled the way the author wrote it.\n  const byRel = new Map<string, string>();\n  await inOrder(targets, async (path) => {\n    const rel = relative(base, path).split(/[\\\\/]/).join(\"/\");\n    const dest = join(folder, ...rel.split(\"/\"));\n    try {\n      await mkdir(dirname(dest), { recursive: true });\n      await copyFile(path, dest);\n      byRel.set(rel, path);\n    } catch {\n      // Dropped, exactly as `stage` drops one: the caller's ordinary per-path\n      // load owns the error, and a project missing one document still answers\n      // about the rest.\n    }\n    return null;\n  });\n  return byRel;\n}\n\n/**\n * Load a directory of `.likec4` documents as ONE LikeC4 project — the way the\n * renderer already reads `architecture/`, and the only way a document that\n * declares views over ANOTHER file's elements can be read at all.\n *\n * Measured at the 1.59.2 pin: a views-only `usecases/checkout.likec4` parsed\n * alone is five errors (unresolved tag, unresolved elements); the same file\n * beside its landscape in one project is zero, and each view comes back with\n * its own `sourcePath`. That is the whole reason this function exists — a use\n * case lives in a file of its own, and `loadBatch`'s one-project-per-document\n * isolation makes such a file unreadable by construction.\n *\n * Two rules the caller must know, because both invert what holds elsewhere:\n *\n *  - **Exactly one document in the set declares the `specification` block.**\n *    Every `.likec4` file loam parses alone must declare its own; inside one\n *    project a second declaration is a duplicate error blamed on BOTH files\n *    (measured).\n *  - **Errors are per document, but the MODEL is all-or-nothing.** A typo in\n *    one file is attributed to that file — so the finding names it, which is\n *    better than today, where a use case in the landscape would blame the\n *    landscape — but loam's standing rule is that errors mean no model, and\n *    here the model is the project's. `clean` says which case the caller is in.\n *\n * The generated `architecture/subsystems.likec4` must NOT be in `targets`:\n * docs/DESIGN.md rule 26 keeps it a byte compare, and a stale one whose\n * `include` names a removed element would otherwise be a parse error that\n * blanks the whole fleet map.\n */\nexport async function loadProject(base: string, paths: string[]): Promise<ProjectDoc> {\n  const empty = (errors: Map<string, LikeC4Error[]>, clean: boolean): ProjectDoc => ({\n    errors,\n    clean,\n    elements: [],\n    relationships: [],\n    views: [],\n    viewIds: [],\n    deployment: NO_DEPLOYMENT,\n  });\n  const targets = [...new Set(paths.map((path) => resolve(path)))];\n  if (targets.length === 0) return empty(new Map(), true);\n  const root = await mkdtemp(join(tmpdir(), \"loam-c4-\"));\n  try {\n    const byRel = await stageProject(root, resolve(base), targets);\n    if (byRel.size === 0) return empty(new Map(), true);\n    const likec4 = await LikeC4.fromWorkspace(root, { logger: false });\n    try {\n      const errors = groupProjectErrors(likec4, byRel);\n      if (errors.size > 0) return empty(errors, false);\n      const model = (await likec4.parsedModel()) as ReadableModel;\n      return {\n        errors,\n        clean: true,\n        specification: readSpecification(model.specification),\n        views: readDynamicViews(model),\n        viewIds: readViewIds(model),\n        deployment: readDeployment(model),\n        ...flattenModel(model),\n      };\n    } finally {\n      await likec4.dispose();\n    }\n  } finally {\n    await rm(root, { recursive: true, force: true });\n  }\n}\n\n/**\n * `getErrors()` split per DOCUMENT inside one project, each error's\n * `sourceFsPath` rewritten to the document's real absolute path.\n *\n * `groupErrors` above keys on the project folder segment, which cannot work\n * here — every document shares one project. This keys on the staged relative\n * path instead, longest first so `usecases/checkout.likec4` is matched before a\n * hypothetical `checkout.likec4` at the root. An error nobody can attribute\n * throws for the same reason it does there: a dropped error grades its document\n * clean, which is failing open in the fleet gate.\n */\nfunction groupProjectErrors(likec4: LikeC4, byRel: Map<string, string>): Map<string, LikeC4Error[]> {\n  const rels = [...byRel.keys()].sort((a, b) => b.length - a.length);\n  const grouped = new Map<string, LikeC4Error[]>();\n  for (const err of likec4.getErrors()) {\n    const spelled = err.sourceFsPath.split(/[\\\\/]/).join(\"/\");\n    const rel = rels.find((candidate) => spelled.endsWith(`/${candidate}`) || spelled === candidate);\n    if (rel === undefined) {\n      throw new Error(`unattributable LikeC4 error in project workspace: ${err.message}`);\n    }\n    const real = byRel.get(rel)!;\n    const list = grouped.get(real) ?? [];\n    list.push({ ...err, sourceFsPath: real });\n    grouped.set(real, list);\n  }\n  return grouped;\n}\n\n/**\n * A `ProjectDoc` in the shape every existing landscape reader already takes.\n *\n * The per-file error map flattens into one list, which loses nothing: each\n * error still carries the real path of the document that raised it, so a\n * finding can name the file even though the list is flat. Sorted by that path\n * so a project with two broken documents reports them in a stable order —\n * `getErrors()` returns whatever order the workspace scan produced.\n *\n * The model travels only when the project is clean, which is loam's standing\n * rule (`errors mean no model`) applied at project altitude: a use-case file\n * with an unresolved element leaves the landscape unusable, and pretending\n * otherwise would grade a fleet against half a map.\n */\nexport function asLoadedDoc(doc: ProjectDoc): LoadedDoc {\n  const errors = [...doc.errors]\n    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))\n    .flatMap(([, list]) => list);\n  if (!doc.clean) return { errors, elements: [], relationships: [] };\n  return {\n    errors,\n    ...(doc.specification === undefined ? {} : { specification: doc.specification }),\n    views: doc.views,\n    viewIds: doc.viewIds,\n    deployment: doc.deployment,\n    elements: doc.elements,\n    relationships: doc.relationships,\n  };\n}\n"]}

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

@@ -0,0 +1,220 @@
+/**
+ * The `architecture/` project AS THIS FEATURE'S MERGE WOULD LEAVE IT, staged
+ * and parsed, with a feature's own documents standing beside it.
+ *
+ * WHY THE POST-MERGE MAP AND NOT THE LIVING ONE. A document a feature brings
+ * names elements, and a feature that adds a service adds the element its own
+ * document names. Graded against the LIVING landscape that name is unresolved —
+ * LikeC4 refuses the document, the project blanks, and loam reports a hole
+ * against a file whose only fault is arriving with the change that makes it
+ * true. Graded against the merge it resolves exactly when the merge lands the
+ * element it names, which is `ARCH-LOAM-FEATURE-CORPUS`: inside a feature
+ * window, the corpus is feature ∪ living.
+ *
+ * IT IS ALSO THE CHECK. The merge preview is the only reading under which "a
+ * document naming an element the merge does not land" is answerable at all, and
+ * that refusal is why it runs before `loam archive` writes rather than after:
+ * without it the document is copied into `architecture/` and the NEXT reader's
+ * `loam validate --all` carries the failure, against a file they did not write.
+ *
+ * ## Why it lives here rather than in one axis
+ *
+ * It was `core/usecases/delta/overlay.ts`'s private machinery while the
+ * use-case slot was the only feature-local `.likec4` document. The deployment
+ * slot is the second, and a second copy of this staging is the copy that
+ * drifts — the two would disagree first about the merge preview, which is the
+ * one thing both refusals rest on. So the staging moved down to the package
+ * that owns the project loader and the merge, and each axis keeps only its own
+ * INTERPRETATION of the parse: which views are the feature's, or which
+ * documents failed.
+ *
+ * ## Why it stages its own tree
+ *
+ * `loadProject` copies documents from disk, keyed on their path relative to a
+ * base — so it can be handed neither a landscape that exists only in memory nor
+ * a document living outside `architecture/`, and both are exactly what this
+ * needs. Teaching it to take content would put a second, rarely-exercised
+ * staging rule inside a loader whose docstring already carries two rules that
+ * invert what holds elsewhere. Staging here costs one copy of a handful of
+ * small files and keeps that loader's contract at one.
+ *
+ * THE PRICE OF THAT CHOICE IS PATHS, and it is paid here rather than left to
+ * the caller: every path LikeC4 reports — a parse error's `sourceFsPath`, a
+ * view's `sourcePath` — names a temp tree, and a finding naming a temp
+ * directory is a finding nobody can act on. `real()` maps them back to the file
+ * the author wrote, and the temp tree is gone before this returns.
+ *
+ * FAIL CLOSED, and not silently. Every failure is the `unreadable` arm carrying
+ * LikeC4's own messages: a document this cannot read is never one that grades
+ * clean.
+ */
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { loadFile } from "../likec4.js";
+import { planLandscapeMerge } from "../splice/landscape-merge.js";
+import { inOrder } from "../../kernel/concurrency.js";
+import { decodeDocument } from "../../kernel/document-bytes.js";
+import { featurePaths, landscapePath, subsystemViewsPath } from "../../repo/paths.js";
+import { architectureDir } from "./architecture.js";
+import { architectureDocuments } from "./documents.js";
+import { asLoadedDoc, loadProject } from "./load.js";
+/**
+ * Stage the living `architecture/` with the merge preview in place of the
+ * landscape, add the feature's own documents, and parse the result.
+ *
+ * A feature bringing no documents is not this function's business: both callers
+ * return their own empty answer before reaching it, at the cost of one walk
+ * over a directory that is not there. That walk is the axis's per-feature
+ * opt-in and the whole price a fleet that has not adopted it pays.
+ */
+export async function stageMergedProject(req) {
+    const merged = await mergedLandscape(req);
+    if (merged.kind === "failed")
+        return { kind: "unreadable", errors: [merged.reason] };
+    const arch = architectureDir(req.docsDir);
+    const living = await architectureDocuments(arch, [subsystemViewsPath(req.docsDir)]);
+    const root = await mkdtemp(join(tmpdir(), "loam-staged-"));
+    try {
+        // Staged rel -> the path the AUTHOR wrote, so every message that leaves
+        // here names a file they can open. Built as the tree is staged, because
+        // that is the one moment both spellings are in hand.
+        const authored = new Map();
+        const landscape = resolve(landscapePath(req.docsDir));
+        await inOrder(living, async (path) => {
+            // The living landscape is staged from the merge preview when there is
+            // one; copying it as well would declare every element twice.
+            if (merged.kind === "merged" && resolve(path) === landscape)
+                return null;
+            await stage(root, spell(relative(arch, path)), path, authored);
+            return null;
+        });
+        if (merged.kind === "merged") {
+            const rel = spell(relative(arch, landscape));
+            await write(root, rel, merged.content);
+            authored.set(rel, landscape);
+        }
+        // The feature's own documents LAST, so one whose living twin exists wins
+        // the staging rather than colliding with it. That case is already an error
+        // the gate refuses before any merge — `usecase.flow-exists`,
+        // `deployment.doc-exists` — and grading the feature's version is the more
+        // useful of the two answers to give an author who is about to be told to
+        // delete the file.
+        const mine = new Set();
+        for (const document of req.documents) {
+            await stage(root, document.rel, document.path, authored);
+            mine.add(document.rel);
+        }
+        const doc = asLoadedDoc(await loadProject(root, await architectureDocuments(root)));
+        // TWO SPELLINGS REACH HERE and both must map, which is the one thing this
+        // helper cannot be allowed to get half right. A parse error's
+        // `sourceFsPath` is an ABSOLUTE path into the temp tree; a view's
+        // `sourcePath` is already the project-RELATIVE rel LikeC4 reports. The
+        // rel-first lookup answers the second, and the relative() computation the
+        // first. Handling only one leaves the other silently returning the temp
+        // spelling, which is a finding naming a directory that no longer exists.
+        const real = (path) => authored.get(spell(path)) ?? authored.get(spell(relative(root, path))) ?? path;
+        if (doc.errors.length > 0) {
+            // An error naming no document is LikeC4 declining to attribute one. It
+            // still travels: a hole loam cannot place is still a hole, and dropping
+            // it here would grade the feature clean on the strength of a missing
+            // field.
+            return {
+                kind: "unreadable",
+                errors: doc.errors.map((e) => (e.sourceFsPath === undefined ? e.message : `${real(e.sourceFsPath)}: ${e.message}`)),
+            };
+        }
+        return { kind: "read", doc, real, mine };
+    }
+    catch (err) {
+        // The `unreadable` arm is a PROMISE, not a description of the happy path.
+        // Two things under here throw rather than return: `loadProject` refuses an
+        // error it cannot attribute to a document, and every `mkdir`/`copyFile` in
+        // the staging above can fail on a full disk or a denied temp directory.
+        // Callers run inside `loam validate --feature` and the archive gate — and
+        // the one behaviour a check added to those may never have is failing the
+        // run it was added to. So a throw becomes the same could-not-look answer a
+        // parse error already produces, which each caller turns into its own
+        // refusal that writes nothing.
+        return { kind: "unreadable", errors: [err instanceof Error ? err.message : String(err)] };
+    }
+    finally {
+        await rm(root, { recursive: true, force: true });
+    }
+}
+/**
+ * The merge preview, computed with the SAME function `loam archive` commits
+ * with.
+ *
+ * Reusing `planLandscapeMerge` rather than approximating it is what makes this
+ * an answer about the archive rather than a second opinion beside it: an
+ * element placed differently, a tag stripped differently, or a splice refused
+ * there and allowed here would be a document graded against a map the merge
+ * never writes.
+ *
+ * THE PARITY IS THE MERGE, NOT THE WHOLE GATE, and the difference is worth
+ * naming rather than leaving for a reader to discover. `planLandscape` runs one
+ * check BEFORE it computes the merge and this does not: a delta declaring the
+ * feature tag on a specification KIND is refused there, because every element
+ * of that kind inherits the tag and the merge would splice the whole document.
+ * Such a delta reaches `newEls` here unfiltered, so the preview this grades
+ * against is one the archive would never write. It changes no verdict — that
+ * archive refuses either way, before anything is written — and it is recorded
+ * because the next reader to widen either side needs to know the two are not
+ * the same gate.
+ *
+ * A throw is `failed` rather than propagated. Every `LandscapeSpliceError` this
+ * can raise is one `planLandscape` raises again — with its own message, its own
+ * refusal code, and before anything is written — so throwing here would only
+ * decide which of two identical refusals an author reads first.
+ */
+async function mergedLandscape(req) {
+    const deltaPath = featurePaths(req.featureDir).delta;
+    const landscape = landscapePath(req.docsDir);
+    if (!existsSync(deltaPath) || !existsSync(landscape))
+        return { kind: "living" };
+    const delta = await (req.load ?? loadFile)(deltaPath);
+    if (delta.errors.length > 0) {
+        return {
+            kind: "failed",
+            reason: `delta.likec4 has ${delta.errors.length} parse error(s) — a feature's own documents cannot be graded against a map that does not parse`,
+        };
+    }
+    try {
+        const plan = await planLandscapeMerge({
+            landscapeText: await text(landscape),
+            deltaText: await text(deltaPath),
+            deltaElements: delta.elements,
+            newEls: delta.elements.filter((e) => e.tags.includes(req.featureId)),
+            newRels: delta.relationships.filter((r) => r.tags.includes(req.featureId)),
+            featureId: req.featureId,
+        });
+        return plan.content === null ? { kind: "living" } : { kind: "merged", content: plan.content };
+    }
+    catch (err) {
+        return { kind: "failed", reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Read a document loam is about to hand LikeC4, refusing the encodings that decode as empty. */
+async function text(path) {
+    return decodeDocument(await readFile(path), path);
+}
+/** A path spelled the way a staged rel is spelled — `/`-separated, on every platform. */
+function spell(path) {
+    return path.split(/[\\/]/).join("/");
+}
+/** Copy one authored document into the staged tree, remembering where it came from. */
+async function stage(root, rel, path, authored) {
+    const dest = join(root, ...rel.split("/"));
+    await mkdir(dirname(dest), { recursive: true });
+    await copyFile(path, dest);
+    authored.set(rel, resolve(path));
+}
+/** Write one document into the staged tree from bytes loam holds rather than a file. */
+async function write(root, rel, content) {
+    const dest = join(root, ...rel.split("/"));
+    await mkdir(dirname(dest), { recursive: true });
+    await writeFile(dest, content, "utf8");
+}
+//# sourceMappingURL=staged.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"staged.js","sourceRoot":"","sources":["../../../../src/core/c4/project/staged.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The `architecture/` project AS THIS FEATURE'S MERGE WOULD LEAVE IT, staged\n * and parsed, with a feature's own documents standing beside it.\n *\n * WHY THE POST-MERGE MAP AND NOT THE LIVING ONE. A document a feature brings\n * names elements, and a feature that adds a service adds the element its own\n * document names. Graded against the LIVING landscape that name is unresolved —\n * LikeC4 refuses the document, the project blanks, and loam reports a hole\n * against a file whose only fault is arriving with the change that makes it\n * true. Graded against the merge it resolves exactly when the merge lands the\n * element it names, which is `ARCH-LOAM-FEATURE-CORPUS`: inside a feature\n * window, the corpus is feature ∪ living.\n *\n * IT IS ALSO THE CHECK. The merge preview is the only reading under which \"a\n * document naming an element the merge does not land\" is answerable at all, and\n * that refusal is why it runs before `loam archive` writes rather than after:\n * without it the document is copied into `architecture/` and the NEXT reader's\n * `loam validate --all` carries the failure, against a file they did not write.\n *\n * ## Why it lives here rather than in one axis\n *\n * It was `core/usecases/delta/overlay.ts`'s private machinery while the\n * use-case slot was the only feature-local `.likec4` document. The deployment\n * slot is the second, and a second copy of this staging is the copy that\n * drifts — the two would disagree first about the merge preview, which is the\n * one thing both refusals rest on. So the staging moved down to the package\n * that owns the project loader and the merge, and each axis keeps only its own\n * INTERPRETATION of the parse: which views are the feature's, or which\n * documents failed.\n *\n * ## Why it stages its own tree\n *\n * `loadProject` copies documents from disk, keyed on their path relative to a\n * base — so it can be handed neither a landscape that exists only in memory nor\n * a document living outside `architecture/`, and both are exactly what this\n * needs. Teaching it to take content would put a second, rarely-exercised\n * staging rule inside a loader whose docstring already carries two rules that\n * invert what holds elsewhere. Staging here costs one copy of a handful of\n * small files and keeps that loader's contract at one.\n *\n * THE PRICE OF THAT CHOICE IS PATHS, and it is paid here rather than left to\n * the caller: every path LikeC4 reports — a parse error's `sourceFsPath`, a\n * view's `sourcePath` — names a temp tree, and a finding naming a temp\n * directory is a finding nobody can act on. `real()` maps them back to the file\n * the author wrote, and the temp tree is gone before this returns.\n *\n * FAIL CLOSED, and not silently. Every failure is the `unreadable` arm carrying\n * LikeC4's own messages: a document this cannot read is never one that grades\n * clean.\n */\nimport { existsSync } from \"node:fs\";\nimport { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { dirname, join, relative, resolve } from \"node:path\";\nimport { loadFile, type LoadedDoc } from \"../likec4.js\";\nimport { planLandscapeMerge } from \"../splice/landscape-merge.js\";\nimport { inOrder } from \"../../kernel/concurrency.js\";\nimport { decodeDocument } from \"../../kernel/document-bytes.js\";\nimport type { DocsDir, FeatureDir } from \"../../kernel/ids/dirs.js\";\nimport { featurePaths, landscapePath, subsystemViewsPath } from \"../../repo/paths.js\";\nimport { architectureDir } from \"./architecture.js\";\nimport { architectureDocuments } from \"./documents.js\";\nimport { asLoadedDoc, loadProject } from \"./load.js\";\n\n/** One document a feature brings, and where it would live under `architecture/`. */\nexport interface StagedDocument {\n  /** Its path relative to `architecture/`, `/`-separated — where the merge would write it. */\n  rel: string;\n  /** The absolute path of the authored file. */\n  path: string;\n}\n\nexport interface StagedProjectRequest {\n  docsDir: DocsDir;\n  featureDir: FeatureDir;\n  /** The feature's id — the tag that selects the delta's own additions. */\n  featureId: string;\n  /** The feature's own documents, staged LAST so they win over a living twin. */\n  documents: readonly StagedDocument[];\n  /**\n   * The caller's memoised LikeC4 read, when it has one. Only `delta.likec4`\n   * goes through it, and only to compute the merge preview — but a caller\n   * inside `featureCoherence` has already loaded that exact document, and\n   * loading one spins a fresh Langium workspace, which\n   * `core/coherence/coherence.ts` calls the dominant per-feature cost.\n   */\n  load?: (path: string) => Promise<LoadedDoc>;\n}\n\n/** The staged parse, or the honest refusal to say. */\nexport type StagedProject =\n  | {\n      kind: \"read\";\n      /** The whole staged project, parsed. */\n      doc: LoadedDoc;\n      /** A path LikeC4 reported, spelled as the author wrote it. */\n      real: (path: string) => string;\n      /** The staged rels that are THIS feature's documents — everything else is living. */\n      mine: ReadonlySet<string>;\n    }\n  | { kind: \"unreadable\"; errors: string[] };\n\n/**\n * Stage the living `architecture/` with the merge preview in place of the\n * landscape, add the feature's own documents, and parse the result.\n *\n * A feature bringing no documents is not this function's business: both callers\n * return their own empty answer before reaching it, at the cost of one walk\n * over a directory that is not there. That walk is the axis's per-feature\n * opt-in and the whole price a fleet that has not adopted it pays.\n */\nexport async function stageMergedProject(req: StagedProjectRequest): Promise<StagedProject> {\n  const merged = await mergedLandscape(req);\n  if (merged.kind === \"failed\") return { kind: \"unreadable\", errors: [merged.reason] };\n\n  const arch = architectureDir(req.docsDir);\n  const living = await architectureDocuments(arch, [subsystemViewsPath(req.docsDir)]);\n  const root = await mkdtemp(join(tmpdir(), \"loam-staged-\"));\n  try {\n    // Staged rel -> the path the AUTHOR wrote, so every message that leaves\n    // here names a file they can open. Built as the tree is staged, because\n    // that is the one moment both spellings are in hand.\n    const authored = new Map<string, string>();\n    const landscape = resolve(landscapePath(req.docsDir));\n    await inOrder(living, async (path) => {\n      // The living landscape is staged from the merge preview when there is\n      // one; copying it as well would declare every element twice.\n      if (merged.kind === \"merged\" && resolve(path) === landscape) return null;\n      await stage(root, spell(relative(arch, path)), path, authored);\n      return null;\n    });\n    if (merged.kind === \"merged\") {\n      const rel = spell(relative(arch, landscape));\n      await write(root, rel, merged.content);\n      authored.set(rel, landscape);\n    }\n    // The feature's own documents LAST, so one whose living twin exists wins\n    // the staging rather than colliding with it. That case is already an error\n    // the gate refuses before any merge — `usecase.flow-exists`,\n    // `deployment.doc-exists` — and grading the feature's version is the more\n    // useful of the two answers to give an author who is about to be told to\n    // delete the file.\n    const mine = new Set<string>();\n    for (const document of req.documents) {\n      await stage(root, document.rel, document.path, authored);\n      mine.add(document.rel);\n    }\n    const doc = asLoadedDoc(await loadProject(root, await architectureDocuments(root)));\n    // TWO SPELLINGS REACH HERE and both must map, which is the one thing this\n    // helper cannot be allowed to get half right. A parse error's\n    // `sourceFsPath` is an ABSOLUTE path into the temp tree; a view's\n    // `sourcePath` is already the project-RELATIVE rel LikeC4 reports. The\n    // rel-first lookup answers the second, and the relative() computation the\n    // first. Handling only one leaves the other silently returning the temp\n    // spelling, which is a finding naming a directory that no longer exists.\n    const real = (path: string): string =>\n      authored.get(spell(path)) ?? authored.get(spell(relative(root, path))) ?? path;\n    if (doc.errors.length > 0) {\n      // An error naming no document is LikeC4 declining to attribute one. It\n      // still travels: a hole loam cannot place is still a hole, and dropping\n      // it here would grade the feature clean on the strength of a missing\n      // field.\n      return {\n        kind: \"unreadable\",\n        errors: doc.errors.map((e) => (e.sourceFsPath === undefined ? e.message : `${real(e.sourceFsPath)}: ${e.message}`)),\n      };\n    }\n    return { kind: \"read\", doc, real, mine };\n  } catch (err) {\n    // The `unreadable` arm is a PROMISE, not a description of the happy path.\n    // Two things under here throw rather than return: `loadProject` refuses an\n    // error it cannot attribute to a document, and every `mkdir`/`copyFile` in\n    // the staging above can fail on a full disk or a denied temp directory.\n    // Callers run inside `loam validate --feature` and the archive gate — and\n    // the one behaviour a check added to those may never have is failing the\n    // run it was added to. So a throw becomes the same could-not-look answer a\n    // parse error already produces, which each caller turns into its own\n    // refusal that writes nothing.\n    return { kind: \"unreadable\", errors: [err instanceof Error ? err.message : String(err)] };\n  } finally {\n    await rm(root, { recursive: true, force: true });\n  }\n}\n\n/** What the landscape looks like after this feature's C4 delta is spliced in. */\ntype MergedLandscape =\n  /** The delta adds nothing, or there is none — the living landscape stands. */\n  | { kind: \"living\" }\n  /** The merge preview, as authored bytes. */\n  | { kind: \"merged\"; content: string }\n  /** The merge could not be computed; `planLandscape` owns the refusal and says why. */\n  | { kind: \"failed\"; reason: string };\n\n/**\n * The merge preview, computed with the SAME function `loam archive` commits\n * with.\n *\n * Reusing `planLandscapeMerge` rather than approximating it is what makes this\n * an answer about the archive rather than a second opinion beside it: an\n * element placed differently, a tag stripped differently, or a splice refused\n * there and allowed here would be a document graded against a map the merge\n * never writes.\n *\n * THE PARITY IS THE MERGE, NOT THE WHOLE GATE, and the difference is worth\n * naming rather than leaving for a reader to discover. `planLandscape` runs one\n * check BEFORE it computes the merge and this does not: a delta declaring the\n * feature tag on a specification KIND is refused there, because every element\n * of that kind inherits the tag and the merge would splice the whole document.\n * Such a delta reaches `newEls` here unfiltered, so the preview this grades\n * against is one the archive would never write. It changes no verdict — that\n * archive refuses either way, before anything is written — and it is recorded\n * because the next reader to widen either side needs to know the two are not\n * the same gate.\n *\n * A throw is `failed` rather than propagated. Every `LandscapeSpliceError` this\n * can raise is one `planLandscape` raises again — with its own message, its own\n * refusal code, and before anything is written — so throwing here would only\n * decide which of two identical refusals an author reads first.\n */\nasync function mergedLandscape(req: StagedProjectRequest): Promise<MergedLandscape> {\n  const deltaPath = featurePaths(req.featureDir).delta;\n  const landscape = landscapePath(req.docsDir);\n  if (!existsSync(deltaPath) || !existsSync(landscape)) return { kind: \"living\" };\n  const delta = await (req.load ?? loadFile)(deltaPath);\n  if (delta.errors.length > 0) {\n    return {\n      kind: \"failed\",\n      reason: `delta.likec4 has ${delta.errors.length} parse error(s) — a feature's own documents cannot be graded against a map that does not parse`,\n    };\n  }\n  try {\n    const plan = await planLandscapeMerge({\n      landscapeText: await text(landscape),\n      deltaText: await text(deltaPath),\n      deltaElements: delta.elements,\n      newEls: delta.elements.filter((e) => e.tags.includes(req.featureId)),\n      newRels: delta.relationships.filter((r) => r.tags.includes(req.featureId)),\n      featureId: req.featureId,\n    });\n    return plan.content === null ? { kind: \"living\" } : { kind: \"merged\", content: plan.content };\n  } catch (err) {\n    return { kind: \"failed\", reason: err instanceof Error ? err.message : String(err) };\n  }\n}\n\n/** Read a document loam is about to hand LikeC4, refusing the encodings that decode as empty. */\nasync function text(path: string): Promise<string> {\n  return decodeDocument(await readFile(path), path);\n}\n\n/** A path spelled the way a staged rel is spelled — `/`-separated, on every platform. */\nfunction spell(path: string): string {\n  return path.split(/[\\\\/]/).join(\"/\");\n}\n\n/** Copy one authored document into the staged tree, remembering where it came from. */\nasync function stage(root: string, rel: string, path: string, authored: Map<string, string>): Promise<void> {\n  const dest = join(root, ...rel.split(\"/\"));\n  await mkdir(dirname(dest), { recursive: true });\n  await copyFile(path, dest);\n  authored.set(rel, resolve(path));\n}\n\n/** Write one document into the staged tree from bytes loam holds rather than a file. */\nasync function write(root: string, rel: string, content: string): Promise<void> {\n  const dest = join(root, ...rel.split(\"/\"));\n  await mkdir(dirname(dest), { recursive: true });\n  await writeFile(dest, content, \"utf8\");\n}\n"]}

package/dist/core/c4/resolve/service.js

@@ -0,0 +1,159 @@
+/**
+ * Which `services/<id>/` directory a modelled element belongs to.
+ *
+ * A distinct subject from loading a document, and a distinct phase: the
+ * loader beside this package (`../likec4.ts`) turns LikeC4's parse output into
+ * loam's neutral `Elem`/`Rel` records, and everything here runs AFTER that, over
+ * those records, answering one question the model itself never states outright.
+ * It is the join every fleet-wide check rests on — the landscape↔services
+ * reconciliation, the spine's edge grouping, `Covers:` resolution, health.yaml's
+ * dependency matching — which is why `docs/DESIGN.md`'s Open-decisions table
+ * audits its call sites as a subject of their own rather than as a detail of the
+ * loader.
+ *
+ * The resolution order below is the whole of it, and its last rung is the one
+ * that lies: read that comment before adding a caller.
+ */
+import { declaredService } from "../../kernel/ids/service.js";
+import {} from "../likec4.js";
+/**
+ * The service directory an element stands for: an explicit
+ * `metadata { service '<id>' }` binding wins, the title is the fallback.
+ *
+ * The fallback is what every docs repo written before the binding existed relies
+ * on, and it is also the trap the binding exists to close: matching on the title
+ * means renaming a box in a diagram silently unlinks it from its service, and
+ * every check that joined the two just stops finding anything.
+ */
+export function elementService(e) {
+    return e.service ?? declaredService(e.title);
+}
+/**
+ * Every id an endpoint may be filed under, nearest first: `a.b.c`, `a.b`, `a`.
+ *
+ * A landscape does not have to draw a service as one opaque box. The moment
+ * somebody models its containers — `paymentService.api`, `paymentService.worker`
+ * — an edge drawn INTO a container is still an edge into the service, and every
+ * join that groups by service has to know that. Resolving only the exact id is
+ * what made those edges invisible: the spine check silently skipped them, and
+ * the no-openapi grace treated a service with a dozen inbound container calls as
+ * one nobody calls at all.
+ */
+function ancestorIds(id) {
+    const out = [id];
+    for (let dot = id.lastIndexOf("."); dot !== -1; dot = id.lastIndexOf(".", dot - 1)) {
+        out.push(id.slice(0, dot));
+    }
+    return out;
+}
+/**
+ * A memoized `id -> service` resolver over one document.
+ *
+ * Resolution order, and why it is this order:
+ *
+ *  1. the nearest ancestor (the id itself first) carrying an explicit
+ *     `metadata { service '<id>' }` — a binding is a claim somebody wrote down,
+ *     so it outranks every guess;
+ *  2. the nearest ancestor whose title names a REAL `services/<id>/` directory —
+ *     positive evidence from the filesystem, available only to callers that
+ *     hand in `known`;
+ *  3. the element's own title, and finally the raw id — today's fallback, kept
+ *     LAST because it is the one that lies: it happily resolves
+ *     `paymentService.api` to "api", a service that has never existed.
+ *
+ * Built once per document and shared, because it is called inside loops over
+ * every relationship and the walk up the ancestor chain is not free.
+ */
+export function serviceResolver(elements, known) {
+    const byId = new Map(elements.map((e) => [e.id, e]));
+    const memo = new Map();
+    return (id) => {
+        const hit = memo.get(id);
+        if (hit !== undefined)
+            return hit;
+        let answer;
+        for (const candidate of ancestorIds(id)) {
+            const e = byId.get(candidate);
+            if (e?.service !== undefined) {
+                answer = e.service;
+                break;
+            }
+        }
+        if (answer === undefined && known !== undefined) {
+            for (const candidate of ancestorIds(id)) {
+                const e = byId.get(candidate);
+                if (e !== undefined && known.has(e.title)) {
+                    answer = declaredService(e.title);
+                    break;
+                }
+            }
+        }
+        if (answer === undefined) {
+            const self = byId.get(id);
+            answer = self ? elementService(self) : declaredService(id);
+        }
+        memo.set(id, answer);
+        return answer;
+    };
+}
+/**
+ * The service a relationship endpoint belongs to. An id that names no element
+ * resolves to itself, so a partial document degrades to the id rather than
+ * throwing.
+ *
+ * `known` is the set of service directories that actually exist; pass it
+ * wherever the caller has enumerated `services/`, so an edge into a modelled
+ * container resolves to the service that owns it instead of to the container's
+ * own title. Callers with a single document and no repository in hand omit it
+ * and keep the pre-existing behaviour.
+ */
+export function serviceOf(elements, id, known) {
+    return serviceResolver(elements, known)(id);
+}
+/**
+ * One `id -> service` resolver per document, not one per lookup.
+ *
+ * `serviceOf` builds a fresh id map on every call, and this axis calls it twice
+ * for every relationship in scope — inside loops that already run over every
+ * relationship a service can see. `serviceResolver`'s own doc says it is "built
+ * once per document and shared"; this is where both axes that need it keep
+ * that promise — `../arch.ts`'s `coversEdge` and `./steps.ts`'s `resolvedTier`,
+ * each exported and each handed only the element array.
+ *
+ * A module-level cache is normally the wrong shape here, because a command runs
+ * against whatever directory it was invoked in. This one is safe: the key is the
+ * per-invocation `Elem[]` a parse produced, its value is a pure function of that
+ * key alone, and nothing in it is derived from the working directory — so two
+ * runs can never see each other's answer, and the entry dies with the document.
+ * Nothing mutates an `Elem[]` after parse.
+ *
+ * Two tiers because the fleet set is part of the answer: the same document
+ * resolves differently with and without `known`, so a cache keyed on the
+ * elements alone handed a with-fleet caller the without-fleet resolver.
+ * Callers build ONE set per run and pass the same instance through, which is
+ * what lets the inner WeakMap key on the set's identity.
+ */
+const RESOLVERS = new WeakMap();
+const FLEET_RESOLVERS = new WeakMap();
+export function resolverFor(elements, known) {
+    if (known === undefined) {
+        const cached = RESOLVERS.get(elements);
+        if (cached !== undefined)
+            return cached;
+        const resolver = serviceResolver(elements);
+        RESOLVERS.set(elements, resolver);
+        return resolver;
+    }
+    let perSet = FLEET_RESOLVERS.get(elements);
+    if (perSet === undefined) {
+        perSet = new WeakMap();
+        FLEET_RESOLVERS.set(elements, perSet);
+    }
+    const cached = perSet.get(known);
+    if (cached !== undefined)
+        return cached;
+    const resolver = serviceResolver(elements, known);
+    perSet.set(known, resolver);
+    return resolver;
+}
+//# sourceMappingURL=service.js.map