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

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

@@ -0,0 +1,277 @@
+/**
+ * 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 { errorText, loadFile } from "../likec4.js";
+import { createdServiceModels } from "../service-model/created/models.js";
+import { planLandscapeMerge } from "../splice/landscape-merge.js";
+import { inOrder } from "../../kernel/concurrency.js";
+import { decodeDocument } from "../../kernel/document-bytes.js";
+import { featurePaths, landscapePath } from "../../repo/paths.js";
+import { architectureDir, generatedArchitectureDocuments } 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);
+    // BOTH generated documents come out, through the one list every project read
+    // shares: a views-only file does not parse standalone, so staging one that
+    // `sync` has not caught up with would blank the merge preview this whole
+    // module exists to parse (`./architecture.ts` states the rule).
+    const living = await architectureDocuments(arch, generatedArchitectureDocuments(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.
+            //
+            // DOCS-RELATIVE, `/`-separated, and carrying the line — the spelling the
+            // SERVICE arm of `usecase.flow-invalid` uses on purpose. These strings are
+            // the feature arm's whole payload (text, `--json` and the `loam archive`
+            // block message), and `real()` alone answered with an absolute Windows path
+            // and no line at all: `C:\Users\…\docs\features\FEAT-1\usecases\x.likec4:
+            // <message>` in a finding a person is asked to act on (verification
+            // 2026-09-04, W7). A path outside the docs root — which nothing here
+            // produces, but `relative` would spell `..\..` — keeps its absolute form.
+            return {
+                kind: "unreadable",
+                errors: doc.errors.map((e) => e.sourceFsPath === undefined ? errorText(e) : `${spellReal(req.docsDir, real(e.sourceFsPath))}: ${errorText(e)}`),
+            };
+        }
+        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 two places the sides
+ * differ are worth naming rather than leaving for a reader to discover.
+ *
+ * The first changes no verdict. `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 — but that archive refuses either way, before
+ * anything is written.
+ *
+ * The second changed every verdict about a fleet with extending models, and is
+ * why `models` is on the request at all. `planLandscape` names the fleet's
+ * extending models, so a nested addition is ROUTED into the model that owns
+ * that service's interior and never reaches the map; a request that omits them
+ * previews a map holding interior the archive will put somewhere else. A
+ * feature-local `usecases/<x>.likec4` whose hop names `<service-fqn>.<container>`
+ * then resolved in the preview, passed `usecase.flow-invalid` — the gate whose
+ * own message is "the archive would land an architecture/ nothing has checked",
+ * and which `--approve` cannot override — and was copied verbatim into
+ * `architecture/`, where it resolves against nothing and takes the whole fleet
+ * map down (verification 2026-09-04, review C; SCHEMA names that outcome as the
+ * thing that must not happen). A caller that leaves `models` out is asking for
+ * the pre-routing preview, and gets exactly the answers it got before.
+ *
+ * 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`,
+        };
+    }
+    // The models the archive will CREATE route exactly as the living ones do —
+    // a new service's interior lands in its new model, never on the map — so a
+    // preview asking for the routing gets them too (`createdServiceModels` says why).
+    const models = req.models === undefined
+        ? undefined
+        : [
+            ...req.models,
+            ...(await createdServiceModels({
+                docsDir: req.docsDir,
+                featureDir: req.featureDir,
+                featureId: req.featureId,
+                drawn: [...(await (req.load ?? loadFile)(landscape)).elements, ...delta.elements.filter((e) => e.tags.includes(req.featureId))],
+            })),
+        ];
+    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,
+            // As `planLandscape` passes it: without the table every edge of a tagged
+            // kind is a statement the splice cannot locate, and the preview fails a
+            // feature's flows over a merge the archive itself computes.
+            deltaKindTags: delta.specification?.relationshipKindTags ?? {},
+            ...(models === undefined ? {} : { models }),
+        });
+        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("/");
+}
+/**
+ * An authored path as a FINDING spells it: relative to the docs root,
+ * `/`-separated. A path that does not sit under the docs root keeps its absolute
+ * form — `relative` would answer with `..` segments, and a finding naming a
+ * document outside the repository is more honest as the absolute path it is.
+ */
+function spellReal(docsDir, path) {
+    const rel = relative(docsDir, path);
+    return rel.length > 0 && !rel.startsWith("..") ? spell(rel) : spell(path);
+}
+/** 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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAkB,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAE1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAEhE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,8BAA8B,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AA2DrD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAyB;IAChE,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;IAErF,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1C,6EAA6E;IAC7E,2EAA2E;IAC3E,yEAAyE;IACzE,gEAAgE;IAChE,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,IAAI,EAAE,8BAA8B,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9F,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,cAAc,CAAC,CAAC,CAAC;IAC3D,IAAI,CAAC;QACH,wEAAwE;QACxE,wEAAwE;QACxE,qDAAqD;QACrD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC3C,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QACtD,MAAM,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACnC,sEAAsE;YACtE,6DAA6D;YAC7D,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC;YACzE,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YAC/D,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;YAC7C,MAAM,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;YACvC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC/B,CAAC;QACD,yEAAyE;QACzE,2EAA2E;QAC3E,6DAA6D;QAC7D,0EAA0E;QAC1E,yEAAyE;QACzE,mBAAmB;QACnB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,QAAQ,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YACrC,MAAM,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACzD,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;QACD,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,WAAW,CAAC,IAAI,EAAE,MAAM,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpF,0EAA0E;QAC1E,8DAA8D;QAC9D,kEAAkE;QAClE,uEAAuE;QACvE,0EAA0E;QAC1E,wEAAwE;QACxE,yEAAyE;QACzE,MAAM,IAAI,GAAG,CAAC,IAAY,EAAU,EAAE,CACpC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QACjF,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,uEAAuE;YACvE,wEAAwE;YACxE,qEAAqE;YACrE,SAAS;YACT,EAAE;YACF,yEAAyE;YACzE,2EAA2E;YAC3E,yEAAyE;YACzE,4EAA4E;YAC5E,0EAA0E;YAC1E,oEAAoE;YACpE,qEAAqE;YACrE,0EAA0E;YAC1E,OAAO;gBACL,IAAI,EAAE,YAAY;gBAClB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC3B,CAAC,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CACjH;aACF,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC3C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,0EAA0E;QAC1E,2EAA2E;QAC3E,2EAA2E;QAC3E,wEAAwE;QACxE,0EAA0E;QAC1E,yEAAyE;QACzE,2EAA2E;QAC3E,qEAAqE;QACrE,+BAA+B;QAC/B,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IAC5F,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,KAAK,UAAU,eAAe,CAAC,GAAyB;IACtD,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC;IACrD,MAAM,SAAS,GAAG,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAChF,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC;IACtD,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,oBAAoB,KAAK,CAAC,MAAM,CAAC,MAAM,gGAAgG;SAChJ,CAAC;IACJ,CAAC;IACD,2EAA2E;IAC3E,2EAA2E;IAC3E,kFAAkF;IAClF,MAAM,MAAM,GACV,GAAG,CAAC,MAAM,KAAK,SAAS;QACtB,CAAC,CAAC,SAAS;QACX,CAAC,CAAC;YACE,GAAG,GAAG,CAAC,MAAM;YACb,GAAG,CAAC,MAAM,oBAAoB,CAAC;gBAC7B,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,UAAU,EAAE,GAAG,CAAC,UAAU;gBAC1B,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,KAAK,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;aAChI,CAAC,CAAC;SACJ,CAAC;IACR,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,kBAAkB,CAAC;YACpC,aAAa,EAAE,MAAM,IAAI,CAAC,SAAS,CAAC;YACpC,SAAS,EAAE,MAAM,IAAI,CAAC,SAAS,CAAC;YAChC,aAAa,EAAE,KAAK,CAAC,QAAQ;YAC7B,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACpE,OAAO,EAAE,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC1E,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,yEAAyE;YACzE,wEAAwE;YACxE,4DAA4D;YAC5D,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE,oBAAoB,IAAI,EAAE;YAC9D,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;SAC5C,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAChG,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACtF,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,KAAK,UAAU,IAAI,CAAC,IAAY;IAC9B,OAAO,cAAc,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;AACpD,CAAC;AAED,yFAAyF;AACzF,SAAS,KAAK,CAAC,IAAY;IACzB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACvC,CAAC;AAED;;;;;GAKG;AACH,SAAS,SAAS,CAAC,OAAgB,EAAE,IAAY;IAC/C,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACpC,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC5E,CAAC;AAED,uFAAuF;AACvF,KAAK,UAAU,KAAK,CAAC,IAAY,EAAE,GAAW,EAAE,IAAY,EAAE,QAA6B;IACzF,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3B,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AACnC,CAAC;AAED,wFAAwF;AACxF,KAAK,UAAU,KAAK,CAAC,IAAY,EAAE,GAAW,EAAE,OAAe;IAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC","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 { errorText, loadFile, type LoadedDoc } from \"../likec4.js\";\nimport { createdServiceModels } from \"../service-model/created/models.js\";\nimport type { ExtendingModel } from \"../splice/contract.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 } from \"../../repo/paths.js\";\nimport { architectureDir, generatedArchitectureDocuments } 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   * The fleet's extending models — the SAME list `loam archive` merges with.\n   * The merge routes a nested addition into the model that owns that service's\n   * interior, so a preview computed without this list holds interior the\n   * archive will put somewhere else, and every gate resting on the preview\n   * grades a map that will never exist (verification 2026-09-04, review C).\n   *\n   * Optional because it must be INJECTED rather than read here: the shape scan\n   * that decides which models extend the map lives in\n   * `../service-model/shape.ts`, and that package imports this one — reading it\n   * from here would be a package cycle. The reader is\n   * `../service-model/fleet/extending.ts`, one level below that scan, and both\n   * shipped callers fill this in from it: `core/delta/delta.ts` for the\n   * use-case overlay, `core/coherence/coherence.ts` for the deployment one.\n   * Omitted, the preview is the pre-routing one — the behaviour every caller\n   * had before this field existed, and what a fleet whose models all stand\n   * alone gets either way.\n   */\n  models?: readonly ExtendingModel[];\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  // BOTH generated documents come out, through the one list every project read\n  // shares: a views-only file does not parse standalone, so staging one that\n  // `sync` has not caught up with would blank the merge preview this whole\n  // module exists to parse (`./architecture.ts` states the rule).\n  const living = await architectureDocuments(arch, generatedArchitectureDocuments(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      //\n      // DOCS-RELATIVE, `/`-separated, and carrying the line — the spelling the\n      // SERVICE arm of `usecase.flow-invalid` uses on purpose. These strings are\n      // the feature arm's whole payload (text, `--json` and the `loam archive`\n      // block message), and `real()` alone answered with an absolute Windows path\n      // and no line at all: `C:\\Users\\…\\docs\\features\\FEAT-1\\usecases\\x.likec4:\n      // <message>` in a finding a person is asked to act on (verification\n      // 2026-09-04, W7). A path outside the docs root — which nothing here\n      // produces, but `relative` would spell `..\\..` — keeps its absolute form.\n      return {\n        kind: \"unreadable\",\n        errors: doc.errors.map((e) =>\n          e.sourceFsPath === undefined ? errorText(e) : `${spellReal(req.docsDir, real(e.sourceFsPath))}: ${errorText(e)}`,\n        ),\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 two places the sides\n * differ are worth naming rather than leaving for a reader to discover.\n *\n * The first changes no verdict. `planLandscape` runs one check BEFORE it\n * computes the merge and this does not: a delta declaring the feature tag on a\n * specification KIND is refused there, because every element of that kind\n * inherits the tag and the merge would splice the whole document. Such a delta\n * reaches `newEls` here unfiltered, so the preview this grades against is one\n * the archive would never write — but that archive refuses either way, before\n * anything is written.\n *\n * The second changed every verdict about a fleet with extending models, and is\n * why `models` is on the request at all. `planLandscape` names the fleet's\n * extending models, so a nested addition is ROUTED into the model that owns\n * that service's interior and never reaches the map; a request that omits them\n * previews a map holding interior the archive will put somewhere else. A\n * feature-local `usecases/<x>.likec4` whose hop names `<service-fqn>.<container>`\n * then resolved in the preview, passed `usecase.flow-invalid` — the gate whose\n * own message is \"the archive would land an architecture/ nothing has checked\",\n * and which `--approve` cannot override — and was copied verbatim into\n * `architecture/`, where it resolves against nothing and takes the whole fleet\n * map down (verification 2026-09-04, review C; SCHEMA names that outcome as the\n * thing that must not happen). A caller that leaves `models` out is asking for\n * the pre-routing preview, and gets exactly the answers it got before.\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  // The models the archive will CREATE route exactly as the living ones do —\n  // a new service's interior lands in its new model, never on the map — so a\n  // preview asking for the routing gets them too (`createdServiceModels` says why).\n  const models =\n    req.models === undefined\n      ? undefined\n      : [\n          ...req.models,\n          ...(await createdServiceModels({\n            docsDir: req.docsDir,\n            featureDir: req.featureDir,\n            featureId: req.featureId,\n            drawn: [...(await (req.load ?? loadFile)(landscape)).elements, ...delta.elements.filter((e) => e.tags.includes(req.featureId))],\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      // As `planLandscape` passes it: without the table every edge of a tagged\n      // kind is a statement the splice cannot locate, and the preview fails a\n      // feature's flows over a merge the archive itself computes.\n      deltaKindTags: delta.specification?.relationshipKindTags ?? {},\n      ...(models === undefined ? {} : { models }),\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/**\n * An authored path as a FINDING spells it: relative to the docs root,\n * `/`-separated. A path that does not sit under the docs root keeps its absolute\n * form — `relative` would answer with `..` segments, and a finding naming a\n * document outside the repository is more honest as the absolute path it is.\n */\nfunction spellReal(docsDir: DocsDir, path: string): string {\n  const rel = relative(docsDir, path);\n  return rel.length > 0 && !rel.startsWith(\"..\") ? spell(rel) : spell(path);\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/attested.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attested.js","sourceRoot":"","sources":["../../../../src/core/c4/resolve/attested.ts"],"names":[],"mappings":"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","sourcesContent":["/**\r\n * The calls a service's OWN `model.likec4` attests across its boundary.\r\n *\r\n * Two readers derive this list and must derive the same one: the adopt brief\r\n * (core/brief/landscape.ts reads it; core/brief/map/owed.ts names these calls\r\n * as the edges the fleet map still owes a drawn-but-edgeless service), and the fleet check\r\n * `landscape.service-isolated` (commands/validate/fleet/map/isolation.ts),\r\n * whose whole evidence gate is \"this list is non-empty\". A second spelling of\r\n * \"which relationships cross the boundary\" is how the brief would name an edge\r\n * the check then never asks for, or the reverse.\r\n *\r\n * It sits in this package because it is a question about the RESOLVED model —\r\n * which endpoints belong to the service — and `serviceResolver` beside it is\r\n * the one answer every join in loam gives to that. A relationship whose two\r\n * endpoints both resolve to the service (`api -> db`) is the service's own\r\n * internals; one where neither does (two context elements) is somebody else's\r\n * call. Only a relationship with EXACTLY one endpoint inside the boundary is\r\n * attested here, collapsed to the service side.\r\n *\r\n * What is deliberately NOT done: matching the counterpart to a landscape\r\n * element. One word names two different things in two documents often enough\r\n * — the reporting fleet's `orchestrator` was a container in the service model\r\n * and a campaign orchestrator on the map — that the join is the agent's to\r\n * make by hand. The counterpart is handed over exactly as the model spells\r\n * it, plus its title where the model declares the element.\r\n */\r\nimport { type Elem, type Rel } from \"../likec4.js\";\r\nimport { serviceResolver } from \"./service.js\";\r\n\r\nexport interface AttestedCall {\r\n  /** `out` when the service is the source; `in` when it is the target. */\r\n  direction: \"out\" | \"in\";\r\n  /** The foreign endpoint's id as model.likec4 spells it — never matched to a landscape element. */\r\n  counterpartId: string;\r\n  /** The foreign element's title when the model declares it; the id otherwise. */\r\n  counterpart: string;\r\n  title?: string;\r\n  op?: string;\r\n  publishes?: string;\r\n  consumes?: string;\r\n}\r\n\r\n/** The slice of a loaded document this derivation reads. */\r\nexport interface AttestingModel {\r\n  elements: Elem[];\r\n  relationships: Rel[];\r\n}\r\n\r\n/**\r\n * Every call the model declares with exactly one endpoint resolving to\r\n * `service`, de-duplicated and sorted.\r\n *\r\n * `known` is the enumerated fleet, for the reason every resolver call carries\r\n * it: a container of this service resolves to the service, and a stand-in\r\n * element titled like another REAL service resolves to that service rather\r\n * than to itself. The dedupe key is (direction, counterpart, op, publishes,\r\n * consumes) so two containers calling one system's one operation are one\r\n * attested call — the map draws edges between services, and that is one edge.\r\n */\r\nexport function attestedCalls(model: AttestingModel, service: string, known: ReadonlySet<string>): AttestedCall[] {\r\n  const resolve = serviceResolver(model.elements, known);\r\n  const byId = new Map(model.elements.map((e) => [e.id, e]));\r\n  const out = new Map<string, AttestedCall>();\r\n  for (const r of model.relationships) {\r\n    const from = resolve(r.source) === service;\r\n    const to = resolve(r.target) === service;\r\n    if (from === to) continue;\r\n    const foreign = from ? r.target : r.source;\r\n    const call: AttestedCall = {\r\n      direction: from ? \"out\" : \"in\",\r\n      counterpartId: foreign,\r\n      counterpart: byId.get(foreign)?.title ?? foreign,\r\n      ...(r.title === undefined ? {} : { title: r.title }),\r\n      ...(r.op === undefined ? {} : { op: r.op }),\r\n      ...(r.publishes === undefined ? {} : { publishes: r.publishes }),\r\n      ...(r.consumes === undefined ? {} : { consumes: r.consumes }),\r\n    };\r\n    const key = [call.direction, foreign, r.op ?? \"\", r.publishes ?? \"\", r.consumes ?? \"\"].join(\"\u0000\");\r\n    if (!out.has(key)) out.set(key, call);\r\n  }\r\n  // Keyed sort, so the order is a function of the calls and never of the\r\n  // order the author wrote them in — the brief's text and the finding's\r\n  // message are compared byte for byte by tests and by readers.\r\n  return [...out.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, call]) => call);\r\n}\r\n\r\n/**\r\n * One call as prose: `-> stripe (op 'authorize')`, `<- kafka (consumes\r\n * 'order.placed')`, `-> ledger` when the edge carries no join. Shared by the\r\n * brief's instruction and the fleet finding's message so the two surfaces\r\n * spell the same call the same way — a reader who meets it in `adopt` and\r\n * again in `validate --all` must recognise it as one thing.\r\n */\r\nexport function spellCall(call: AttestedCall): string {\r\n  const arrow = call.direction === \"out\" ? \"->\" : \"<-\";\r\n  const join =\r\n    call.op !== undefined\r\n      ? ` (op '${call.op}')`\r\n      : call.publishes !== undefined\r\n        ? ` (publishes '${call.publishes}')`\r\n        : call.consumes !== undefined\r\n          ? ` (consumes '${call.consumes}')`\r\n          : \"\";\r\n  return `${arrow} ${call.counterpart}${join}`;\r\n}\r\n\r\n/**\r\n * The edge form(s) the map owes for these calls, on the element that already\r\n * resolves to the service: `<id> -> <callee> …` when the service is the\r\n * caller, `<caller> -> <id> …` when it is the callee, both when the calls run\r\n * both ways. Direction is the part a template gets wrong silently: the repair\r\n * sentence used to spell the outbound form alone, so an agent following it\r\n * for an inbound call drew the dependency backwards — and because `op` must\r\n * be an operationId the TARGET's openapi.yaml defines, the reversed edge then\r\n * earned `spine.op-undefined` against the wrong service. Shared by the\r\n * brief's instruction and the fleet finding's message for the reason\r\n * `spellCall` is. With no call at all the outbound form stands in, so a\r\n * caller never receives an empty list.\r\n */\r\nexport function edgeTemplates(id: string, calls: readonly AttestedCall[]): string[] {\r\n  const outbound = calls.some((c) => c.direction === \"out\");\r\n  const inbound = calls.some((c) => c.direction === \"in\");\r\n  const forms: string[] = [];\r\n  if (outbound || !inbound) forms.push(`${id} -> <callee> 'Calls <op>' { metadata { op '<op>' } }`);\r\n  if (inbound) forms.push(`<caller> -> ${id} 'Calls <op>' { metadata { op '<op>' } }`);\r\n  return forms;\r\n}\r\n"]}

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

@@ -0,0 +1,51 @@
+/**
+ * The producer OUTSIDE the fleet: the `#external` element the map says sends a
+ * message no `services/<id>/` directory stands for.
+ *
+ * It sits in this package for `./attested.ts`'s reason: it is a question about
+ * the RESOLVED model — which endpoint of a `publishes` edge belongs to no
+ * service — and `serviceResolver` beside it is the one answer every join gives
+ * to that. It moved here from `commands/validate/checks/fleet-shape.ts`, where it
+ * sat beside the other checks that read tags off the drawn map, when a second
+ * reader needed the same answer: the consumer index (`core/consumers/`), which a
+ * `commands/` module can never be imported by.
+ */
+import {} from "../likec4.js";
+import {} from "../../kernel/ids/service.js";
+import { EXTERNAL_TAG } from "../../vocabulary/maturity.js";
+/**
+ * The #external element that declares it PUBLISHES this message, or null —
+ * the landscape-side half of the event spine's fleet question, whose fleet
+ * half is `../../asyncapi/producers.ts` (`spine.message-unproduced`, in
+ * `commands/validate/service/events/message-producers.ts`).
+ *
+ * Positive evidence only: an edge carrying `metadata { publishes '<msg>' }`
+ * whose source element — itself or a declared ancestor, since the edge may
+ * point out of a topic nested inside the broker — is tagged #external and
+ * resolves to no known service directory. The resolution guard is what keeps
+ * a mis-tagged internal service reading as unproduced: a tag is cheap to
+ * write, and a services/<id>/ directory outranks it.
+ */
+export function externalProducerOf(message, land, landSvcOf, known) {
+    if (land === null || land.errors.length > 0 || landSvcOf === null)
+        return null;
+    const knownIds = known;
+    const byId = new Map(land.elements.map((e) => [e.id, e]));
+    for (const r of land.relationships) {
+        if (r.publishes !== message)
+            continue;
+        if (knownIds.has(landSvcOf(r.source)))
+            continue;
+        for (let id = r.source;;) {
+            const e = byId.get(id);
+            if (e !== undefined && e.tags.includes(EXTERNAL_TAG))
+                return e.title;
+            const dot = id.lastIndexOf(".");
+            if (dot === -1)
+                break;
+            id = id.slice(0, dot);
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=external.js.map

package/dist/core/c4/resolve/external.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.js","sourceRoot":"","sources":["../../../../src/core/c4/resolve/external.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAkB,MAAM,cAAc,CAAC;AAC9C,OAAO,EAA2C,MAAM,6BAA6B,CAAC;AACtF,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAe,EACf,IAAsB,EACtB,SAAmD,EACnD,KAAgC;IAEhC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/E,MAAM,QAAQ,GAAwB,KAAK,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,SAAS,KAAK,OAAO;YAAE,SAAS;QACtC,IAAI,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAAE,SAAS;QAChD,KAAK,IAAI,EAAE,GAAG,CAAC,CAAC,MAAM,IAAM,CAAC;YAC3B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACvB,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;gBAAE,OAAO,CAAC,CAAC,KAAK,CAAC;YACrE,MAAM,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YAChC,IAAI,GAAG,KAAK,CAAC,CAAC;gBAAE,MAAM;YACtB,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["/**\n * The producer OUTSIDE the fleet: the `#external` element the map says sends a\n * message no `services/<id>/` directory stands for.\n *\n * It sits in this package for `./attested.ts`'s reason: it is a question about\n * the RESOLVED model — which endpoint of a `publishes` edge belongs to no\n * service — and `serviceResolver` beside it is the one answer every join gives\n * to that. It moved here from `commands/validate/checks/fleet-shape.ts`, where it\n * sat beside the other checks that read tags off the drawn map, when a second\n * reader needed the same answer: the consumer index (`core/consumers/`), which a\n * `commands/` module can never be imported by.\n */\nimport { type LoadedDoc } from \"../likec4.js\";\nimport { type DeclaredService, type RawServiceId } from \"../../kernel/ids/service.js\";\nimport { EXTERNAL_TAG } from \"../../vocabulary/maturity.js\";\n\n/**\n * The #external element that declares it PUBLISHES this message, or null —\n * the landscape-side half of the event spine's fleet question, whose fleet\n * half is `../../asyncapi/producers.ts` (`spine.message-unproduced`, in\n * `commands/validate/service/events/message-producers.ts`).\n *\n * Positive evidence only: an edge carrying `metadata { publishes '<msg>' }`\n * whose source element — itself or a declared ancestor, since the edge may\n * point out of a topic nested inside the broker — is tagged #external and\n * resolves to no known service directory. The resolution guard is what keeps\n * a mis-tagged internal service reading as unproduced: a tag is cheap to\n * write, and a services/<id>/ directory outranks it.\n */\nexport function externalProducerOf(\n  message: string,\n  land: LoadedDoc | null,\n  landSvcOf: ((id: string) => DeclaredService) | null,\n  known: ReadonlySet<RawServiceId>,\n): string | null {\n  if (land === null || land.errors.length > 0 || landSvcOf === null) return null;\n  const knownIds: ReadonlySet<string> = known;\n  const byId = new Map(land.elements.map((e) => [e.id, e]));\n  for (const r of land.relationships) {\n    if (r.publishes !== message) continue;\n    if (knownIds.has(landSvcOf(r.source))) continue;\n    for (let id = r.source; ; ) {\n      const e = byId.get(id);\n      if (e !== undefined && e.tags.includes(EXTERNAL_TAG)) return e.title;\n      const dot = id.lastIndexOf(\".\");\n      if (dot === -1) break;\n      id = id.slice(0, dot);\n    }\n  }\n  return null;\n}\n"]}

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

@@ -14,6 +14,7 @@
  * 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 { ancestorIds, properAncestorIds } from "../../kernel/ids/fqn/ancestors.js";
 import { declaredService } from "../../kernel/ids/service.js";
 import {} from "../likec4.js";
 /**
@@ -28,24 +29,14 @@ import {} from "../likec4.js";
 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.
+/*
+ * `ancestorIds` — every id an endpoint may be filed under, nearest first:
+ * `a.b.c`, `a.b`, `a` — now lives in `core/kernel/ids/fqn/ancestors.ts`, with
+ * the reason it exists at all (a landscape may draw a service's containers, and
+ * an edge into one is still an edge into the service). It moved because five
+ * modules were each walking that chain privately; the kernel is where a leaf
+ * helper goes when the modules that want it are heavier than it is.
  */
-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.
  *
@@ -110,4 +101,74 @@ 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;
+}
+/**
+ * The element each service is DRAWN as: for every service the map resolves an
+ * element to, the first service-level one in document order — an element that
+ * resolves to the service while an ancestor does too is a container of it,
+ * never a second box. The same filter and the same "first one" the adopt brief
+ * names (`core/brief/landscape.ts`), so `loam new` and `loam adopt` can never
+ * hand an author two different ids for one box.
+ *
+ * Exists so a scaffold reuses the id the map already spells instead of
+ * guessing one: a feature delta whose context ids differ from the landscape's
+ * does not line up at archive, and a guessed camelCase id on a seeded map
+ * (`svc_<id>`) never matched once.
+ */
+export function drawnServiceElements(elements, known) {
+    const svcOf = serviceResolver(elements, known);
+    const drawn = new Map();
+    for (const e of elements) {
+        const service = svcOf(e.id);
+        if (drawn.has(service) || properAncestorIds(e.id).some((a) => svcOf(a) === service))
+            continue;
+        drawn.set(service, e.id);
+    }
+    return drawn;
+}
 //# sourceMappingURL=service.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../../src/core/c4/resolve/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,eAAe,EAAwB,MAAM,6BAA6B,CAAC;AACpF,OAAO,EAAa,MAAM,cAAc,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,CAAO;IACpC,OAAO,CAAC,CAAC,OAAO,IAAI,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,WAAW,CAAC,EAAU;IAC7B,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC;IACjB,KAAK,IAAI,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC;QACnF,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,KAA2B;IAE3B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,IAAI,GAAG,EAA2B,CAAC;IAChD,OAAO,CAAC,EAAU,EAAmB,EAAE;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,GAAG,CAAC;QAClC,IAAI,MAAmC,CAAC;QACxC,KAAK,MAAM,SAAS,IAAI,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC;YACxC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC9B,IAAI,CAAC,EAAE,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC;gBACnB,MAAM;YACR,CAAC;QACH,CAAC;QACD,IAAI,MAAM,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAChD,KAAK,MAAM,SAAS,IAAI,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC;gBACxC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBAC9B,IAAI,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC1C,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;oBAClC,MAAM;gBACR,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC1B,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QACrB,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,EAAU,EAAE,KAA2B;IACjF,OAAO,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;AAC9C,CAAC","sourcesContent":["/**\n * Which `services/<id>/` directory a modelled element belongs to.\n *\n * A distinct subject from loading a document, and a distinct phase: the\n * loader beside this package (`../likec4.ts`) turns LikeC4's parse output into\n * loam's neutral `Elem`/`Rel` records, and everything here runs AFTER that, over\n * those records, answering one question the model itself never states outright.\n * It is the join every fleet-wide check rests on — the landscape↔services\n * reconciliation, the spine's edge grouping, `Covers:` resolution, health.yaml's\n * dependency matching — which is why `docs/DESIGN.md`'s Open-decisions table\n * audits its call sites as a subject of their own rather than as a detail of the\n * loader.\n *\n * The resolution order below is the whole of it, and its last rung is the one\n * that lies: read that comment before adding a caller.\n */\nimport { declaredService, type DeclaredService } from \"../../kernel/ids/service.js\";\nimport { type Elem } from \"../likec4.js\";\n\n/**\n * The service directory an element stands for: an explicit\n * `metadata { service '<id>' }` binding wins, the title is the fallback.\n *\n * The fallback is what every docs repo written before the binding existed relies\n * on, and it is also the trap the binding exists to close: matching on the title\n * means renaming a box in a diagram silently unlinks it from its service, and\n * every check that joined the two just stops finding anything.\n */\nexport function elementService(e: Elem): DeclaredService {\n  return e.service ?? declaredService(e.title);\n}\n\n/**\n * Every id an endpoint may be filed under, nearest first: `a.b.c`, `a.b`, `a`.\n *\n * A landscape does not have to draw a service as one opaque box. The moment\n * somebody models its containers — `paymentService.api`, `paymentService.worker`\n * — an edge drawn INTO a container is still an edge into the service, and every\n * join that groups by service has to know that. Resolving only the exact id is\n * what made those edges invisible: the spine check silently skipped them, and\n * the no-openapi grace treated a service with a dozen inbound container calls as\n * one nobody calls at all.\n */\nfunction ancestorIds(id: string): string[] {\n  const out = [id];\n  for (let dot = id.lastIndexOf(\".\"); dot !== -1; dot = id.lastIndexOf(\".\", dot - 1)) {\n    out.push(id.slice(0, dot));\n  }\n  return out;\n}\n\n/**\n * A memoized `id -> service` resolver over one document.\n *\n * Resolution order, and why it is this order:\n *\n *  1. the nearest ancestor (the id itself first) carrying an explicit\n *     `metadata { service '<id>' }` — a binding is a claim somebody wrote down,\n *     so it outranks every guess;\n *  2. the nearest ancestor whose title names a REAL `services/<id>/` directory —\n *     positive evidence from the filesystem, available only to callers that\n *     hand in `known`;\n *  3. the element's own title, and finally the raw id — today's fallback, kept\n *     LAST because it is the one that lies: it happily resolves\n *     `paymentService.api` to \"api\", a service that has never existed.\n *\n * Built once per document and shared, because it is called inside loops over\n * every relationship and the walk up the ancestor chain is not free.\n */\nexport function serviceResolver(\n  elements: Elem[],\n  known?: ReadonlySet<string>,\n): (id: string) => DeclaredService {\n  const byId = new Map(elements.map((e) => [e.id, e]));\n  const memo = new Map<string, DeclaredService>();\n  return (id: string): DeclaredService => {\n    const hit = memo.get(id);\n    if (hit !== undefined) return hit;\n    let answer: DeclaredService | undefined;\n    for (const candidate of ancestorIds(id)) {\n      const e = byId.get(candidate);\n      if (e?.service !== undefined) {\n        answer = e.service;\n        break;\n      }\n    }\n    if (answer === undefined && known !== undefined) {\n      for (const candidate of ancestorIds(id)) {\n        const e = byId.get(candidate);\n        if (e !== undefined && known.has(e.title)) {\n          answer = declaredService(e.title);\n          break;\n        }\n      }\n    }\n    if (answer === undefined) {\n      const self = byId.get(id);\n      answer = self ? elementService(self) : declaredService(id);\n    }\n    memo.set(id, answer);\n    return answer;\n  };\n}\n\n/**\n * The service a relationship endpoint belongs to. An id that names no element\n * resolves to itself, so a partial document degrades to the id rather than\n * throwing.\n *\n * `known` is the set of service directories that actually exist; pass it\n * wherever the caller has enumerated `services/`, so an edge into a modelled\n * container resolves to the service that owns it instead of to the container's\n * own title. Callers with a single document and no repository in hand omit it\n * and keep the pre-existing behaviour.\n */\nexport function serviceOf(elements: Elem[], id: string, known?: ReadonlySet<string>): DeclaredService {\n  return serviceResolver(elements, known)(id);\n}\n\n"]}
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../../src/core/c4/resolve/service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which `services/<id>/` directory a modelled element belongs to.\n *\n * A distinct subject from loading a document, and a distinct phase: the\n * loader beside this package (`../likec4.ts`) turns LikeC4's parse output into\n * loam's neutral `Elem`/`Rel` records, and everything here runs AFTER that, over\n * those records, answering one question the model itself never states outright.\n * It is the join every fleet-wide check rests on — the landscape↔services\n * reconciliation, the spine's edge grouping, `Covers:` resolution, health.yaml's\n * dependency matching — which is why `docs/DESIGN.md`'s Open-decisions table\n * audits its call sites as a subject of their own rather than as a detail of the\n * loader.\n *\n * The resolution order below is the whole of it, and its last rung is the one\n * that lies: read that comment before adding a caller.\n */\nimport { ancestorIds, properAncestorIds } from \"../../kernel/ids/fqn/ancestors.js\";\nimport { declaredService, type DeclaredService } from \"../../kernel/ids/service.js\";\nimport { type Elem } from \"../likec4.js\";\n\n/**\n * The service directory an element stands for: an explicit\n * `metadata { service '<id>' }` binding wins, the title is the fallback.\n *\n * The fallback is what every docs repo written before the binding existed relies\n * on, and it is also the trap the binding exists to close: matching on the title\n * means renaming a box in a diagram silently unlinks it from its service, and\n * every check that joined the two just stops finding anything.\n */\nexport function elementService(e: Elem): DeclaredService {\n  return e.service ?? declaredService(e.title);\n}\n\n/*\n * `ancestorIds` — every id an endpoint may be filed under, nearest first:\n * `a.b.c`, `a.b`, `a` — now lives in `core/kernel/ids/fqn/ancestors.ts`, with\n * the reason it exists at all (a landscape may draw a service's containers, and\n * an edge into one is still an edge into the service). It moved because five\n * modules were each walking that chain privately; the kernel is where a leaf\n * helper goes when the modules that want it are heavier than it is.\n */\n\n/**\n * A memoized `id -> service` resolver over one document.\n *\n * Resolution order, and why it is this order:\n *\n *  1. the nearest ancestor (the id itself first) carrying an explicit\n *     `metadata { service '<id>' }` — a binding is a claim somebody wrote down,\n *     so it outranks every guess;\n *  2. the nearest ancestor whose title names a REAL `services/<id>/` directory —\n *     positive evidence from the filesystem, available only to callers that\n *     hand in `known`;\n *  3. the element's own title, and finally the raw id — today's fallback, kept\n *     LAST because it is the one that lies: it happily resolves\n *     `paymentService.api` to \"api\", a service that has never existed.\n *\n * Built once per document and shared, because it is called inside loops over\n * every relationship and the walk up the ancestor chain is not free.\n */\nexport function serviceResolver(\n  elements: Elem[],\n  known?: ReadonlySet<string>,\n): (id: string) => DeclaredService {\n  const byId = new Map(elements.map((e) => [e.id, e]));\n  const memo = new Map<string, DeclaredService>();\n  return (id: string): DeclaredService => {\n    const hit = memo.get(id);\n    if (hit !== undefined) return hit;\n    let answer: DeclaredService | undefined;\n    for (const candidate of ancestorIds(id)) {\n      const e = byId.get(candidate);\n      if (e?.service !== undefined) {\n        answer = e.service;\n        break;\n      }\n    }\n    if (answer === undefined && known !== undefined) {\n      for (const candidate of ancestorIds(id)) {\n        const e = byId.get(candidate);\n        if (e !== undefined && known.has(e.title)) {\n          answer = declaredService(e.title);\n          break;\n        }\n      }\n    }\n    if (answer === undefined) {\n      const self = byId.get(id);\n      answer = self ? elementService(self) : declaredService(id);\n    }\n    memo.set(id, answer);\n    return answer;\n  };\n}\n\n/**\n * The service a relationship endpoint belongs to. An id that names no element\n * resolves to itself, so a partial document degrades to the id rather than\n * throwing.\n *\n * `known` is the set of service directories that actually exist; pass it\n * wherever the caller has enumerated `services/`, so an edge into a modelled\n * container resolves to the service that owns it instead of to the container's\n * own title. Callers with a single document and no repository in hand omit it\n * and keep the pre-existing behaviour.\n */\nexport function serviceOf(elements: Elem[], id: string, known?: ReadonlySet<string>): DeclaredService {\n  return serviceResolver(elements, known)(id);\n}\n\n/**\n * One `id -> service` resolver per document, not one per lookup.\n *\n * `serviceOf` builds a fresh id map on every call, and this axis calls it twice\n * for every relationship in scope — inside loops that already run over every\n * relationship a service can see. `serviceResolver`'s own doc says it is \"built\n * once per document and shared\"; this is where both axes that need it keep\n * that promise — `../arch.ts`'s `coversEdge` and `./steps.ts`'s `resolvedTier`,\n * each exported and each handed only the element array.\n *\n * A module-level cache is normally the wrong shape here, because a command runs\n * against whatever directory it was invoked in. This one is safe: the key is the\n * per-invocation `Elem[]` a parse produced, its value is a pure function of that\n * key alone, and nothing in it is derived from the working directory — so two\n * runs can never see each other's answer, and the entry dies with the document.\n * Nothing mutates an `Elem[]` after parse.\n *\n * Two tiers because the fleet set is part of the answer: the same document\n * resolves differently with and without `known`, so a cache keyed on the\n * elements alone handed a with-fleet caller the without-fleet resolver.\n * Callers build ONE set per run and pass the same instance through, which is\n * what lets the inner WeakMap key on the set's identity.\n */\nconst RESOLVERS = new WeakMap<Elem[], (id: string) => string>();\nconst FLEET_RESOLVERS = new WeakMap<Elem[], WeakMap<ReadonlySet<string>, (id: string) => string>>();\n\nexport function resolverFor(elements: Elem[], known?: ReadonlySet<string>): (id: string) => string {\n  if (known === undefined) {\n    const cached = RESOLVERS.get(elements);\n    if (cached !== undefined) return cached;\n    const resolver = serviceResolver(elements);\n    RESOLVERS.set(elements, resolver);\n    return resolver;\n  }\n  let perSet = FLEET_RESOLVERS.get(elements);\n  if (perSet === undefined) {\n    perSet = new WeakMap();\n    FLEET_RESOLVERS.set(elements, perSet);\n  }\n  const cached = perSet.get(known);\n  if (cached !== undefined) return cached;\n  const resolver = serviceResolver(elements, known);\n  perSet.set(known, resolver);\n  return resolver;\n}\n\n/**\n * The element each service is DRAWN as: for every service the map resolves an\n * element to, the first service-level one in document order — an element that\n * resolves to the service while an ancestor does too is a container of it,\n * never a second box. The same filter and the same \"first one\" the adopt brief\n * names (`core/brief/landscape.ts`), so `loam new` and `loam adopt` can never\n * hand an author two different ids for one box.\n *\n * Exists so a scaffold reuses the id the map already spells instead of\n * guessing one: a feature delta whose context ids differ from the landscape's\n * does not line up at archive, and a guessed camelCase id on a seeded map\n * (`svc_<id>`) never matched once.\n */\nexport function drawnServiceElements(elements: Elem[], known?: ReadonlySet<string>): Map<string, string> {\n  const svcOf = serviceResolver(elements, known);\n  const drawn = new Map<string, string>();\n  for (const e of elements) {\n    const service = svcOf(e.id);\n    if (drawn.has(service) || properAncestorIds(e.id).some((a) => svcOf(a) === service)) continue;\n    drawn.set(service, e.id);\n  }\n  return drawn;\n}\n"]}