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

package/dist/core/c4/parsed/deployment.js

@@ -0,0 +1,158 @@
+/**
+ * The DEPLOYMENT model a document declares — which physical nodes exist, which
+ * containers are instanced where, and what talks to what across them.
+ *
+ * A `deployment { }` block has been legal in a docs repo since LikeC4 could
+ * parse one, and until this reader existed loam saw none of it. The parser
+ * resolved every `instanceOf` — so a container renamed out from under a
+ * deployment node already failed the gate — and after that no requirement could
+ * name a node, no `#obl-` tag on a datacenter was graded, and the context pack
+ * an agent implements from did not mention topology at all. Integrity held at
+ * the level of syntax and was absent at the level of requirements. ROADMAP's
+ * deployment axis and `meta/docs/features/FEAT-1-the-deployment-axis/` are the
+ * item and the specification; this module is its first half.
+ *
+ * ## Why this is a `parsed/` reader and not a package of its own
+ *
+ * It is the same job the three modules beside it do: take one corner of
+ * LikeC4's parse output and hand back a loam-neutral record, defensively, with
+ * its shape assumptions owned outright. `readSpecification`, `readDynamicViews`
+ * and `readViewIds` are all called on the line above `flattenModel(model)` in
+ * each of loam's three loaders, and so is this. FEAT-1's delta said
+ * `src/core/c4/deploy/`; a package holding this alone would be a directory
+ * pretending to be a subject (docs/DESIGN.md), and the delta was corrected
+ * rather than the code bent to it — which is what an unarchived feature is for.
+ *
+ * **`parsed/` is now AT its five-file limit.** The next reader here needs a
+ * split first, and the seam to split on is the one this file does not share:
+ * `dynamic-views.ts` and `view-ids.ts` read `$data`, this one and
+ * `specification.ts` read the model surface.
+ *
+ * ## What is read, and what is deliberately left
+ *
+ * Nodes, instances and relationships, with the ids, titles and tags each
+ * carries. MEASURED at the 1.59.2 pin, and every line of it needed measuring
+ * rather than assuming:
+ *
+ *  - `nodes()` returns deployment NODES only — an `instanceOf` is not among
+ *    them, which is why instances are a second list rather than a filter.
+ *  - an instance carries the LOGICAL element it deploys as `element.id`, and
+ *    that is the whole join back to the C4 model: `eu.a.dbA -> orders.db`.
+ *  - both nodes and instances carry `tags`, so `#obl-geo` on a datacenter is
+ *    readable — the fail-open case that made this an item.
+ *  - a relationship carries `tags` and `metadata` DIRECTLY (`r.metadata`, no
+ *    `$relationship` indirection), and both model stages return byte-identical
+ *    results, which is what lets `test/likec4-model-parity.test.ts` cover this
+ *    read with the substitution it already pins.
+ *  - a document with NO `deployment { }` block still returns a deployment
+ *    object whose three iterators are empty. Absent and empty are therefore the
+ *    same answer here, deliberately: no reader may distinguish "declares none"
+ *    from "could not be read", because the second is what the defensive returns
+ *    below produce and a fleet that draws no topology owes loam nothing.
+ *
+ * `metadata` is NOT carried on the records below, and neither is an instance's
+ * `kind`. Both are readable; no check reads them yet, and a field carried
+ * before a caller needs it is a field nobody notices going wrong. Add one with
+ * the check that consumes it.
+ */
+/** No topology — what an absent block and an unreadable one both come back as. */
+export const NO_DEPLOYMENT = { nodes: [], instances: [], relationships: [] };
+/** Is there anything here? The opt-in every deployment check is gated on. */
+export function hasDeployment(d) {
+    return d.nodes.length > 0 || d.instances.length > 0 || d.relationships.length > 0;
+}
+/** A record, or nothing — the parse surface hands back `unknown`. */
+function record(v) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+}
+/** An iterable produced by `name()`, or an empty one when the surface is not what we measured. */
+function iterate(source, name) {
+    const fn = source[name];
+    if (typeof fn !== "function")
+        return [];
+    try {
+        const out = fn.call(source);
+        // A generator satisfies this; so does an array. Anything else is a shape
+        // change upstream, and the honest answer to one is "no topology read".
+        return out !== null && typeof out === "object" && Symbol.iterator in out
+            ? [...out]
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** A string field, or the empty string — never `undefined` leaking into a record. */
+function str(o, key) {
+    const v = o[key];
+    return typeof v === "string" ? v : "";
+}
+/** Tags as loam models them: a plain array of strings, always present. */
+function tags(o) {
+    const v = o["tags"];
+    return Array.isArray(v) ? v.filter((t) => typeof t === "string") : [];
+}
+/**
+ * Read the deployment model off an awaited `parsedModel()`.
+ *
+ * Defensive throughout, in the shape `readViewIds` established: an entry
+ * missing the one field that identifies it is DROPPED rather than reported with
+ * a hole, and a surface that is not what was measured yields an empty model
+ * instead of throwing. A check that cannot see the topology must say
+ * could-not-look through its own silence, never fail the fleet's parse.
+ */
+export function readDeployment(model) {
+    const root = record(model);
+    if (root === undefined)
+        return NO_DEPLOYMENT;
+    const deployment = record(root["deployment"]);
+    if (deployment === undefined)
+        return NO_DEPLOYMENT;
+    const nodes = [];
+    for (const raw of iterate(deployment, "nodes")) {
+        const n = record(raw);
+        if (n === undefined)
+            continue;
+        const id = str(n, "id");
+        if (id === "")
+            continue;
+        nodes.push({ id, kind: str(n, "kind"), title: str(n, "title"), tags: tags(n) });
+    }
+    const instances = [];
+    for (const raw of iterate(deployment, "instances")) {
+        const i = record(raw);
+        if (i === undefined)
+            continue;
+        const id = str(i, "id");
+        // The logical element is the whole point of the record. An instance whose
+        // element cannot be read joins to nothing, so reporting it would put a
+        // deployed thing on the map that no requirement could ever cover.
+        const element = record(i["element"]);
+        if (id === "" || element === undefined)
+            continue;
+        const elementId = str(element, "id");
+        if (elementId === "")
+            continue;
+        instances.push({ id, element: elementId, title: str(i, "title"), tags: tags(i) });
+    }
+    const relationships = [];
+    for (const raw of iterate(deployment, "relationships")) {
+        const r = record(raw);
+        if (r === undefined)
+            continue;
+        const source = record(r["source"]);
+        const target = record(r["target"]);
+        if (source === undefined || target === undefined)
+            continue;
+        const from = str(source, "id");
+        const to = str(target, "id");
+        if (from === "" || to === "")
+            continue;
+        // LikeC4 reports an untitled edge as `title: null` — normalized to the
+        // declared optional exactly as `flattenModel` does for the logical model.
+        const title = typeof r["title"] === "string" ? r["title"] : undefined;
+        relationships.push({ source: from, target: to, ...(title === undefined ? {} : { title }), tags: tags(r) });
+    }
+    return { nodes, instances, relationships };
+}
+//# sourceMappingURL=deployment.js.map

package/dist/core/c4/parsed/deployment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment.js","sourceRoot":"","sources":["../../../../src/core/c4/parsed/deployment.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The DEPLOYMENT model a document declares — which physical nodes exist, which\n * containers are instanced where, and what talks to what across them.\n *\n * A `deployment { }` block has been legal in a docs repo since LikeC4 could\n * parse one, and until this reader existed loam saw none of it. The parser\n * resolved every `instanceOf` — so a container renamed out from under a\n * deployment node already failed the gate — and after that no requirement could\n * name a node, no `#obl-` tag on a datacenter was graded, and the context pack\n * an agent implements from did not mention topology at all. Integrity held at\n * the level of syntax and was absent at the level of requirements. ROADMAP's\n * deployment axis and `meta/docs/features/FEAT-1-the-deployment-axis/` are the\n * item and the specification; this module is its first half.\n *\n * ## Why this is a `parsed/` reader and not a package of its own\n *\n * It is the same job the three modules beside it do: take one corner of\n * LikeC4's parse output and hand back a loam-neutral record, defensively, with\n * its shape assumptions owned outright. `readSpecification`, `readDynamicViews`\n * and `readViewIds` are all called on the line above `flattenModel(model)` in\n * each of loam's three loaders, and so is this. FEAT-1's delta said\n * `src/core/c4/deploy/`; a package holding this alone would be a directory\n * pretending to be a subject (docs/DESIGN.md), and the delta was corrected\n * rather than the code bent to it — which is what an unarchived feature is for.\n *\n * **`parsed/` is now AT its five-file limit.** The next reader here needs a\n * split first, and the seam to split on is the one this file does not share:\n * `dynamic-views.ts` and `view-ids.ts` read `$data`, this one and\n * `specification.ts` read the model surface.\n *\n * ## What is read, and what is deliberately left\n *\n * Nodes, instances and relationships, with the ids, titles and tags each\n * carries. MEASURED at the 1.59.2 pin, and every line of it needed measuring\n * rather than assuming:\n *\n *  - `nodes()` returns deployment NODES only — an `instanceOf` is not among\n *    them, which is why instances are a second list rather than a filter.\n *  - an instance carries the LOGICAL element it deploys as `element.id`, and\n *    that is the whole join back to the C4 model: `eu.a.dbA -> orders.db`.\n *  - both nodes and instances carry `tags`, so `#obl-geo` on a datacenter is\n *    readable — the fail-open case that made this an item.\n *  - a relationship carries `tags` and `metadata` DIRECTLY (`r.metadata`, no\n *    `$relationship` indirection), and both model stages return byte-identical\n *    results, which is what lets `test/likec4-model-parity.test.ts` cover this\n *    read with the substitution it already pins.\n *  - a document with NO `deployment { }` block still returns a deployment\n *    object whose three iterators are empty. Absent and empty are therefore the\n *    same answer here, deliberately: no reader may distinguish \"declares none\"\n *    from \"could not be read\", because the second is what the defensive returns\n *    below produce and a fleet that draws no topology owes loam nothing.\n *\n * `metadata` is NOT carried on the records below, and neither is an instance's\n * `kind`. Both are readable; no check reads them yet, and a field carried\n * before a caller needs it is a field nobody notices going wrong. Add one with\n * the check that consumes it.\n */\n\n/** One deployment node — a region, a datacenter, a cluster; the kinds are the fleet's own. */\nexport interface DeployNode {\n  /** The dotted path LikeC4 gives it: `eu.dcA.k8sA`. */\n  id: string;\n  /** The `deploymentNode` kind the specification declares. */\n  kind: string;\n  title: string;\n  tags: string[];\n}\n\n/** One deployed instance of a logical element. */\nexport interface DeployInstance {\n  id: string;\n  /**\n   * The id of the C4 element this instance deploys — the join back to the\n   * logical model, and the only reason an instance is worth reading at all.\n   */\n  element: string;\n  title: string;\n  tags: string[];\n}\n\n/** One edge between deployment objects — replication, failover, a network hop. */\nexport interface DeployRel {\n  source: string;\n  target: string;\n  title?: string;\n  tags: string[];\n}\n\n/** A document's whole deployment model, flattened. */\nexport interface DeploymentModel {\n  nodes: DeployNode[];\n  instances: DeployInstance[];\n  relationships: DeployRel[];\n}\n\n/** No topology — what an absent block and an unreadable one both come back as. */\nexport const NO_DEPLOYMENT: DeploymentModel = { nodes: [], instances: [], relationships: [] };\n\n/** Is there anything here? The opt-in every deployment check is gated on. */\nexport function hasDeployment(d: DeploymentModel): boolean {\n  return d.nodes.length > 0 || d.instances.length > 0 || d.relationships.length > 0;\n}\n\n/** A record, or nothing — the parse surface hands back `unknown`. */\nfunction record(v: unknown): Record<string, unknown> | undefined {\n  return v && typeof v === \"object\" && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;\n}\n\n/** An iterable produced by `name()`, or an empty one when the surface is not what we measured. */\nfunction iterate(source: Record<string, unknown>, name: string): unknown[] {\n  const fn = source[name];\n  if (typeof fn !== \"function\") return [];\n  try {\n    const out: unknown = (fn as () => unknown).call(source);\n    // A generator satisfies this; so does an array. Anything else is a shape\n    // change upstream, and the honest answer to one is \"no topology read\".\n    return out !== null && typeof out === \"object\" && Symbol.iterator in (out as object)\n      ? [...(out as Iterable<unknown>)]\n      : [];\n  } catch {\n    return [];\n  }\n}\n\n/** A string field, or the empty string — never `undefined` leaking into a record. */\nfunction str(o: Record<string, unknown>, key: string): string {\n  const v = o[key];\n  return typeof v === \"string\" ? v : \"\";\n}\n\n/** Tags as loam models them: a plain array of strings, always present. */\nfunction tags(o: Record<string, unknown>): string[] {\n  const v = o[\"tags\"];\n  return Array.isArray(v) ? v.filter((t): t is string => typeof t === \"string\") : [];\n}\n\n/**\n * Read the deployment model off an awaited `parsedModel()`.\n *\n * Defensive throughout, in the shape `readViewIds` established: an entry\n * missing the one field that identifies it is DROPPED rather than reported with\n * a hole, and a surface that is not what was measured yields an empty model\n * instead of throwing. A check that cannot see the topology must say\n * could-not-look through its own silence, never fail the fleet's parse.\n */\nexport function readDeployment(model: unknown): DeploymentModel {\n  const root = record(model);\n  if (root === undefined) return NO_DEPLOYMENT;\n  const deployment = record(root[\"deployment\"]);\n  if (deployment === undefined) return NO_DEPLOYMENT;\n\n  const nodes: DeployNode[] = [];\n  for (const raw of iterate(deployment, \"nodes\")) {\n    const n = record(raw);\n    if (n === undefined) continue;\n    const id = str(n, \"id\");\n    if (id === \"\") continue;\n    nodes.push({ id, kind: str(n, \"kind\"), title: str(n, \"title\"), tags: tags(n) });\n  }\n\n  const instances: DeployInstance[] = [];\n  for (const raw of iterate(deployment, \"instances\")) {\n    const i = record(raw);\n    if (i === undefined) continue;\n    const id = str(i, \"id\");\n    // The logical element is the whole point of the record. An instance whose\n    // element cannot be read joins to nothing, so reporting it would put a\n    // deployed thing on the map that no requirement could ever cover.\n    const element = record(i[\"element\"]);\n    if (id === \"\" || element === undefined) continue;\n    const elementId = str(element, \"id\");\n    if (elementId === \"\") continue;\n    instances.push({ id, element: elementId, title: str(i, \"title\"), tags: tags(i) });\n  }\n\n  const relationships: DeployRel[] = [];\n  for (const raw of iterate(deployment, \"relationships\")) {\n    const r = record(raw);\n    if (r === undefined) continue;\n    const source = record(r[\"source\"]);\n    const target = record(r[\"target\"]);\n    if (source === undefined || target === undefined) continue;\n    const from = str(source, \"id\");\n    const to = str(target, \"id\");\n    if (from === \"\" || to === \"\") continue;\n    // LikeC4 reports an untitled edge as `title: null` — normalized to the\n    // declared optional exactly as `flattenModel` does for the logical model.\n    const title = typeof r[\"title\"] === \"string\" ? r[\"title\"] : undefined;\n    relationships.push({ source: from, target: to, ...(title === undefined ? {} : { title }), tags: tags(r) });\n  }\n\n  return { nodes, instances, relationships };\n}\n"]}

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

@@ -20,6 +20,7 @@ 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`.
@@ -92,6 +93,7 @@ export async function loadProject(base, paths) {
         relationships: [],
         views: [],
         viewIds: [],
+        deployment: NO_DEPLOYMENT,
     });
     const targets = [...new Set(paths.map((path) => resolve(path)))];
     if (targets.length === 0)
@@ -113,6 +115,7 @@ export async function loadProject(base, paths) {
                 specification: readSpecification(model.specification),
                 views: readDynamicViews(model),
                 viewIds: readViewIds(model),
+                deployment: readDeployment(model),
                 ...flattenModel(model),
             };
         }
@@ -176,6 +179,7 @@ export function asLoadedDoc(doc) {
         ...(doc.specification === undefined ? {} : { specification: doc.specification }),
         views: doc.views,
         viewIds: doc.viewIds,
+        deployment: doc.deployment,
         elements: doc.elements,
         relationships: doc.relationships,
     };

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

@@ -1 +1 @@
-{"version":3,"file":"load.js","sourceRoot":"","sources":["../../../../src/core/c4/project/load.ts"],"names":[],"mappings":"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","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\";\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}\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  });\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        ...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    elements: doc.elements,\n    relationships: doc.relationships,\n  };\n}\n"]}
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../../../src/core/c4/project/load.ts"],"names":[],"mappings":"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","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

@@ -110,4 +110,50 @@ export function serviceResolver(elements, known) {
 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