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

package/dist/commands/subsystem/txn/views.js

@@ -0,0 +1,249 @@
+/**
+ * What the generated views files MUST say — the shared answer every subsystem
+ * writer and `subsystem sync` render from, and the one compare both make against
+ * it (`planGenerated`). A module beneath the verbs (in the txn/ subpackage)
+ * because the commit window and sync both consume it, and a second spelling of
+ * "what should the views say" would be a second chance to disagree with
+ * `validate`'s staleness check.
+ *
+ * BOTH generated files come out of ONE read of the map, and that is the reason
+ * this module answers about the pair rather than about one file: they are
+ * rendered from the same parsed `architecture/` project, they are repaired by
+ * the same command, and they must land in the same commit — a verb that changed
+ * a service's placement changed a subsystem view's members AND that service's
+ * overview TITLE (`<subsystem path> / <service id>`), so shipping one without
+ * the other is the "stale between two commits" state the generated files'
+ * contract exists to refuse. Reading the project twice would also parse the
+ * whole fleet map twice per run for one answer.
+ */
+import { existsSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { loadFile } from "../../../core/c4/likec4.js";
+import { architectureProjectDocuments, loadArchitecture } from "../../../core/c4/project/architecture.js";
+import { serviceDirOf } from "../../../core/kernel/ids/dirs.js";
+import { landscapePath, serviceViewsPath, subsystemViewsPath } from "../../../core/repo/paths.js";
+import { renderServiceOverviews, renderSubsystemViews, viewsAgree, } from "../../../core/repo/tree/render/views.js";
+/**
+ * The elements, the relationships and the declared global style ids of the whole
+ * `architecture/` PROJECT — the member join, the edges every per-service view
+ * computes its peer set from, and the one line a view may borrow a palette
+ * with — with the provenance of that answer beside it.
+ *
+ * The PROJECT, not the landscape file alone, and that is a correctness rule
+ * rather than a preference: `validate` grades this file against
+ * `loadArchitecture` — the landscape merged with every
+ * `architecture/usecases/*.likec4`, which may `extend` the model and bind
+ * elements of its own. While this side read the landscape alone, a use-case
+ * document declaring one element bound to a filed service was enough to make
+ * `sync` answer `current` while `validate --all` reported
+ * `subsystem.views-stale` and named `sync` as the repair — a loop no command
+ * could clear, reproduced on `examples/docs` before this call changed. Two
+ * readers of "what should the views say" must read the same documents, or the
+ * shared render in `core/repo/tree/render/views.ts` is shared in name only.
+ *
+ * WHY THE FALLBACK AND THE FLAG ARE TWO ANSWERS RATHER THAN ONE. The fallback
+ * exists because one broken use-case document must not cost the render its
+ * member join: the landscape's own elements are still the truth about who
+ * belongs in which subsystem, and re-rendering the file without them takes every
+ * `include` line off it (verification 2026-09-04, W5). But the STYLE CENSUS is
+ * not the landscape file's alone — SCHEMA blesses a palette in any `.likec4`
+ * under `architecture/` — so the fallback takes it over EVERY document that
+ * parses on its own (`declaredStyles`). Reading it off the landscape alone was
+ * enough to drop `global style subsystems` from a good generated file whenever
+ * the palette sat in a sibling and an unrelated sibling was broken
+ * (re-verification 2026-09-04, area C item 8).
+ *
+ * `known` still means the PROJECT parsed, and nothing weaker, because the MEMBER
+ * JOIN is what it licences: a use-case document that binds an element of its own
+ * contributes to the join and cannot be read document by document. It is
+ * `../sync.ts`'s licence to leave an existing file alone.
+ *
+ * An ABSENT map is not a failure: there is nothing to read, the empty facts are
+ * the truth, and the tolerant render is what a fleet being scaffolded needs. An
+ * EMPTY project is no longer reachable here — `architectureProjectDocuments`
+ * keeps the landscape whatever the root `exclude` says, and its banner records
+ * what an empty one cost.
+ */
+export async function landscapeFacts(docsDir) {
+    const path = landscapePath(docsDir);
+    // No map at all: no elements and NO EDGES, said outright. `relationships` is
+    // required of every `MapFacts` precisely so an empty answer has to be written
+    // down rather than dropped — see the type.
+    if (!existsSync(path))
+        return { facts: { elements: [], relationships: [] }, known: true };
+    try {
+        const doc = await loadArchitecture(docsDir);
+        // The whole document on success, so the render reads the same record
+        // `validate --all` grades against; `globalStyles` rides along without
+        // being named here, and a field the loaders add later does too.
+        if (doc.errors.length === 0)
+            return { facts: doc, known: true };
+    }
+    catch {
+        // A throw and a parse error are the same evidence: fall through to the file.
+    }
+    try {
+        const file = await loadFile(path);
+        // THE STYLE CENSUS IS TAKEN OVER EVERY DOCUMENT, not over the landscape, and
+        // that is what makes the fallback safe for a verb that has to write. A
+        // palette declared in a SIBLING under `architecture/` is invisible to a read
+        // of the landscape alone, so a `subsystem new` run standing beside one
+        // unrelated broken sibling silently dropped `global style subsystems` from a
+        // good generated file — the landscape parsed, the element join survived, and
+        // nothing graded the loss because `sync` answers `blocked` for as long as the
+        // broken file stands (re-verification 2026-09-04, area C item 8). Reading
+        // each document ON ITS OWN is the widening the fallback is entitled to: it
+        // cannot merge them (that is what failed one line up), but a document that
+        // parses alone certainly declares the style groups it declares.
+        if (file.errors.length === 0) {
+            // THE LANDSCAPE'S OWN RELATIONSHIPS TRAVEL WITH ITS ELEMENTS. This arm
+            // composes a record rather than handing the document across, because the
+            // style census below is widened past what this one document declares — and
+            // the first version of it listed the fields it happened to be thinking
+            // about and dropped the edges the document was carrying all along. That is
+            // silent: every per-service view then renders with no peers, the service
+            // and its own interior and nothing it touches, and no check anywhere says
+            // so. `MapFacts` now REQUIRES the field for exactly this reason; the copy
+            // stays explicit so the widening above it stays visible.
+            return {
+                facts: {
+                    elements: file.elements,
+                    relationships: file.relationships,
+                    globalStyles: await declaredStyles(docsDir, file),
+                },
+                known: false,
+            };
+        }
+    }
+    catch {
+        // Unreadable bytes; the caller is told loam could not say.
+    }
+    return { facts: null, known: false };
+}
+/**
+ * Every global style id declared by an `architecture/` document that parses ON
+ * ITS OWN, the landscape's included — the union, sorted, so the render is a
+ * function of the set rather than of readdir order.
+ *
+ * The document set is `architectureProjectDocuments`: the same list the PROJECT
+ * read uses, so the fallback can never consider a file the merged read would
+ * have excluded — the generated views file itself, or one the root `exclude`
+ * hides from the renderer. A document that does not parse alone contributes
+ * nothing and is not an error here: it is named by `loam validate --all`, and
+ * the note this module carries already tells the reader the census came from
+ * outside a project read.
+ */
+async function declaredStyles(docsDir, landscape) {
+    const ids = new Set(landscape.globalStyles ?? []);
+    let paths;
+    try {
+        paths = await architectureProjectDocuments(docsDir);
+    }
+    catch {
+        return [...ids].sort();
+    }
+    const map = resolve(landscapePath(docsDir));
+    for (const path of paths) {
+        if (resolve(path) === map)
+            continue;
+        try {
+            const doc = await loadFile(path);
+            if (doc.errors.length === 0)
+                for (const id of doc.globalStyles ?? [])
+                    ids.add(id);
+        }
+        catch {
+            // One unreadable sibling costs its own styles and nothing else.
+        }
+    }
+    return [...ids].sort();
+}
+/**
+ * Compare ONE generated file against what it must say: the write when they
+ * differ, and what that write is. Both writers of these files — `../sync.ts`'s
+ * `planFile` and the verbs' `stageGenerated` (`./txn.ts`) — put their own veto
+ * in front of this and nothing else, because the rule is one rule, and a second
+ * spelling of it would be a second chance for the two writers to answer
+ * differently about the same file.
+ *
+ * The compare is over CONTENT, not bytes: `viewsAgree` records why, beside the
+ * generator. A Windows clone hands a generated file back CRLF with not one fact
+ * changed, and a byte compare made `sync` answer `updated` and rewrite it LF —
+ * after which git shows the file permanently modified and the next checkout puts
+ * the CRLF back — and folded the same rewrite into every subsystem move's
+ * transaction and journal. `validate` stopped demanding that rewrite; the
+ * writers must stop offering it, or they disagree about the same file. What gets
+ * WRITTEN is still the LF render as a Buffer, so the decode is a comparison only.
+ */
+export function planGenerated(file, current) {
+    if (viewsAgree(current, file.content))
+        return { action: "current", write: null };
+    const bytes = file.content === null ? null : Buffer.from(file.content, "utf8");
+    return {
+        action: current === null ? "created" : bytes === null ? "removed" : "updated",
+        write: { path: file.path, content: bytes },
+    };
+}
+export async function expectedViews(docsDir, tree) {
+    const read = await landscapeFacts(docsDir);
+    // The parsed DOCUMENT goes across, never a literal composed here: `MapFacts`
+    // carries the relationships the per-service peer sets are computed from, and a
+    // caller that dropped them would render every service view peerless — the
+    // service and its interior, and nothing it touches — with no error anywhere.
+    // The type now REQUIRES the field so that mistake cannot be made silently
+    // (`render/views.ts` records what it cost); this last-resort literal is the one
+    // place an empty answer is the TRUE one — loam could not read the map at
+    // all — and it says so rather than leaving the field off.
+    const map = read.facts ?? { elements: [], relationships: [] };
+    return {
+        known: read.known,
+        subsystems: { path: subsystemViewsPath(docsDir), content: renderSubsystemViews(tree, map) },
+        services: { path: serviceViewsPath(docsDir), content: renderServiceOverviews(tree, map) },
+    };
+}
+/**
+ * The one line a person is owed when the map cannot be read — the same sentence
+ * from `../sync.ts` (which then leaves an existing file alone) and from a
+ * tree-changing verb (which renders the tolerant shape anyway, because its own
+ * contract is that the file lands in the verb's commit). It names the gating
+ * surface rather than repeating its findings: `loam validate --all` is where the
+ * broken document is named. It lives here, beside the facts it is about, because
+ * both callers are on this side of the `txn/` boundary and a constant in
+ * `../sync.ts` would point the package edge back up.
+ */
+export const LANDSCAPE_UNREADABLE_NOTE = "note: architecture/ does not parse as one project, so the element join is whatever " +
+    "architecture/landscape.likec4 alone says and the style census is the union of the documents that parse on " +
+    "their own — fix the map (`loam validate --all` names the file), then re-run `loam subsystem sync`.";
+/**
+ * The tree AS THE RENAMES LEAVE IT, computed in memory: every dir under a
+ * moved root is remapped by prefix, and each entry's placement chain is
+ * re-derived from its remapped dir. The views file is rendered from this, so
+ * the commit lands file and renames agreeing — never from a re-walk that
+ * would have to happen between two states. Beside `expectedViews` because the
+ * two are one promise: what the commit renames and what the file says must
+ * come from the same in-memory answer.
+ */
+export function movedTree(tree, renames, servicesRoot) {
+    const remap = (dir) => {
+        for (const r of renames) {
+            if (dir === r.from || dir.startsWith(r.from + sep))
+                return r.to + dir.slice(r.from.length);
+        }
+        return dir;
+    };
+    const chainOf = (dir) => relative(servicesRoot, dir).split(sep);
+    return {
+        findings: tree.findings,
+        services: tree.services.map((s) => {
+            const dir = remap(s.dir);
+            // The constructor call records provenance: a readdir-established
+            // directory carried through a rename this same commit performs.
+            return { ...s, dir: serviceDirOf(dir), subsystem: chainOf(dir).slice(0, -1) };
+        }),
+        subsystems: tree.subsystems.map((s) => {
+            const dir = remap(s.dir);
+            return { ...s, dir, path: chainOf(dir) };
+        }),
+    };
+}
+//# sourceMappingURL=views.js.map

package/dist/commands/subsystem/txn/views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.js","sourceRoot":"","sources":["../../../../src/commands/subsystem/txn/views.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,EAAE,4BAA4B,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC1G,OAAO,EAAE,YAAY,EAAgB,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAClG,OAAO,EAEL,sBAAsB,EACtB,oBAAoB,EACpB,UAAU,GACX,MAAM,yCAAyC,CAAC;AAiBjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAgB;IACnD,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACpC,6EAA6E;IAC7E,8EAA8E;IAC9E,2CAA2C;IAC3C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC1F,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAC5C,qEAAqE;QACrE,sEAAsE;QACtE,gEAAgE;QAChE,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,6EAA6E;IAC/E,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QAClC,6EAA6E;QAC7E,uEAAuE;QACvE,6EAA6E;QAC7E,uEAAuE;QACvE,6EAA6E;QAC7E,6EAA6E;QAC7E,8EAA8E;QAC9E,0EAA0E;QAC1E,2EAA2E;QAC3E,2EAA2E;QAC3E,gEAAgE;QAChE,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,uEAAuE;YACvE,yEAAyE;YACzE,2EAA2E;YAC3E,uEAAuE;YACvE,2EAA2E;YAC3E,yEAAyE;YACzE,0EAA0E;YAC1E,0EAA0E;YAC1E,yDAAyD;YACzD,OAAO;gBACL,KAAK,EAAE;oBACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;oBACvB,aAAa,EAAE,IAAI,CAAC,aAAa;oBACjC,YAAY,EAAE,MAAM,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC;iBAClD;gBACD,KAAK,EAAE,KAAK;aACb,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,2DAA2D;IAC7D,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,KAAK,UAAU,cAAc,CAAC,OAAgB,EAAE,SAAmB;IACjE,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC;IAClD,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,4BAA4B,CAAC,OAAO,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG;YAAE,SAAS;QACpC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;YACjC,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;gBAAE,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,YAAY,IAAI,EAAE;oBAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpF,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;QAClE,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAeD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,aAAa,CAAC,IAAkB,EAAE,OAAsB;IACtE,IAAI,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACjF,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/E,OAAO;QACL,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;QAC7E,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE;KAC3C,CAAC;AACJ,CAAC;AA0CD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAgB,EAAE,IAAe;IACnE,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC;IAC3C,6EAA6E;IAC7E,+EAA+E;IAC/E,0EAA0E;IAC1E,6EAA6E;IAC7E,0EAA0E;IAC1E,gFAAgF;IAChF,yEAAyE;IACzE,0DAA0D;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;IAC9D,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,UAAU,EAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE;QAC3F,QAAQ,EAAE,EAAE,IAAI,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,sBAAsB,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE;KAC1F,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,yBAAyB,GACpC,qFAAqF;IACrF,4GAA4G;IAC5G,oGAAoG,CAAC;AAEvG;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,IAAe,EAAE,OAAuC,EAAE,YAAoB;IACtG,MAAM,KAAK,GAAG,CAAC,GAAW,EAAU,EAAE;QACpC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC;gBAAE,OAAO,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7F,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,GAAW,EAAY,EAAE,CAAC,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClF,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YAChC,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACzB,iEAAiE;YACjE,gEAAgE;YAChE,OAAO,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,CAAC,CAAC;QACF,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACpC,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACzB,OAAO,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3C,CAAC,CAAC;KACH,CAAC;AACJ,CAAC","sourcesContent":["/**\n * What the generated views files MUST say — the shared answer every subsystem\n * writer and `subsystem sync` render from, and the one compare both make against\n * it (`planGenerated`). A module beneath the verbs (in the txn/ subpackage)\n * because the commit window and sync both consume it, and a second spelling of\n * \"what should the views say\" would be a second chance to disagree with\n * `validate`'s staleness check.\n *\n * BOTH generated files come out of ONE read of the map, and that is the reason\n * this module answers about the pair rather than about one file: they are\n * rendered from the same parsed `architecture/` project, they are repaired by\n * the same command, and they must land in the same commit — a verb that changed\n * a service's placement changed a subsystem view's members AND that service's\n * overview TITLE (`<subsystem path> / <service id>`), so shipping one without\n * the other is the \"stale between two commits\" state the generated files'\n * contract exists to refuse. Reading the project twice would also parse the\n * whole fleet map twice per run for one answer.\n */\nimport { existsSync } from \"node:fs\";\nimport { relative, resolve, sep } from \"node:path\";\nimport { loadFile } from \"../../../core/c4/likec4.js\";\nimport { architectureProjectDocuments, loadArchitecture } from \"../../../core/c4/project/architecture.js\";\nimport { serviceDirOf, type DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { landscapePath, serviceViewsPath, subsystemViewsPath } from \"../../../core/repo/paths.js\";\nimport {\n  type MapFacts,\n  renderServiceOverviews,\n  renderSubsystemViews,\n  viewsAgree,\n} from \"../../../core/repo/tree/render/views.js\";\nimport type { FleetTree } from \"../../../core/repo/tree/walk.js\";\nimport type { PlannedWrite } from \"../../../core/staging/writes.js\";\n\n/** What one read of the map yielded, and whether it came from the whole project. */\nexport interface LandscapeRead {\n  /** The element join and the style census, or null when neither reading was available. */\n  facts: MapFacts | null;\n  /**\n   * The `architecture/` PROJECT parsed. FALSE means the facts below, if there\n   * are any, were assembled document by document — the member join from the\n   * landscape file alone (so an element a use-case document binds is missing\n   * from it), the style census from every document that parses on its own.\n   */\n  known: boolean;\n}\n\n/**\n * The elements, the relationships and the declared global style ids of the whole\n * `architecture/` PROJECT — the member join, the edges every per-service view\n * computes its peer set from, and the one line a view may borrow a palette\n * with — with the provenance of that answer beside it.\n *\n * The PROJECT, not the landscape file alone, and that is a correctness rule\n * rather than a preference: `validate` grades this file against\n * `loadArchitecture` — the landscape merged with every\n * `architecture/usecases/*.likec4`, which may `extend` the model and bind\n * elements of its own. While this side read the landscape alone, a use-case\n * document declaring one element bound to a filed service was enough to make\n * `sync` answer `current` while `validate --all` reported\n * `subsystem.views-stale` and named `sync` as the repair — a loop no command\n * could clear, reproduced on `examples/docs` before this call changed. Two\n * readers of \"what should the views say\" must read the same documents, or the\n * shared render in `core/repo/tree/render/views.ts` is shared in name only.\n *\n * WHY THE FALLBACK AND THE FLAG ARE TWO ANSWERS RATHER THAN ONE. The fallback\n * exists because one broken use-case document must not cost the render its\n * member join: the landscape's own elements are still the truth about who\n * belongs in which subsystem, and re-rendering the file without them takes every\n * `include` line off it (verification 2026-09-04, W5). But the STYLE CENSUS is\n * not the landscape file's alone — SCHEMA blesses a palette in any `.likec4`\n * under `architecture/` — so the fallback takes it over EVERY document that\n * parses on its own (`declaredStyles`). Reading it off the landscape alone was\n * enough to drop `global style subsystems` from a good generated file whenever\n * the palette sat in a sibling and an unrelated sibling was broken\n * (re-verification 2026-09-04, area C item 8).\n *\n * `known` still means the PROJECT parsed, and nothing weaker, because the MEMBER\n * JOIN is what it licences: a use-case document that binds an element of its own\n * contributes to the join and cannot be read document by document. It is\n * `../sync.ts`'s licence to leave an existing file alone.\n *\n * An ABSENT map is not a failure: there is nothing to read, the empty facts are\n * the truth, and the tolerant render is what a fleet being scaffolded needs. An\n * EMPTY project is no longer reachable here — `architectureProjectDocuments`\n * keeps the landscape whatever the root `exclude` says, and its banner records\n * what an empty one cost.\n */\nexport async function landscapeFacts(docsDir: DocsDir): Promise<LandscapeRead> {\n  const path = landscapePath(docsDir);\n  // No map at all: no elements and NO EDGES, said outright. `relationships` is\n  // required of every `MapFacts` precisely so an empty answer has to be written\n  // down rather than dropped — see the type.\n  if (!existsSync(path)) return { facts: { elements: [], relationships: [] }, known: true };\n  try {\n    const doc = await loadArchitecture(docsDir);\n    // The whole document on success, so the render reads the same record\n    // `validate --all` grades against; `globalStyles` rides along without\n    // being named here, and a field the loaders add later does too.\n    if (doc.errors.length === 0) return { facts: doc, known: true };\n  } catch {\n    // A throw and a parse error are the same evidence: fall through to the file.\n  }\n  try {\n    const file = await loadFile(path);\n    // THE STYLE CENSUS IS TAKEN OVER EVERY DOCUMENT, not over the landscape, and\n    // that is what makes the fallback safe for a verb that has to write. A\n    // palette declared in a SIBLING under `architecture/` is invisible to a read\n    // of the landscape alone, so a `subsystem new` run standing beside one\n    // unrelated broken sibling silently dropped `global style subsystems` from a\n    // good generated file — the landscape parsed, the element join survived, and\n    // nothing graded the loss because `sync` answers `blocked` for as long as the\n    // broken file stands (re-verification 2026-09-04, area C item 8). Reading\n    // each document ON ITS OWN is the widening the fallback is entitled to: it\n    // cannot merge them (that is what failed one line up), but a document that\n    // parses alone certainly declares the style groups it declares.\n    if (file.errors.length === 0) {\n      // THE LANDSCAPE'S OWN RELATIONSHIPS TRAVEL WITH ITS ELEMENTS. This arm\n      // composes a record rather than handing the document across, because the\n      // style census below is widened past what this one document declares — and\n      // the first version of it listed the fields it happened to be thinking\n      // about and dropped the edges the document was carrying all along. That is\n      // silent: every per-service view then renders with no peers, the service\n      // and its own interior and nothing it touches, and no check anywhere says\n      // so. `MapFacts` now REQUIRES the field for exactly this reason; the copy\n      // stays explicit so the widening above it stays visible.\n      return {\n        facts: {\n          elements: file.elements,\n          relationships: file.relationships,\n          globalStyles: await declaredStyles(docsDir, file),\n        },\n        known: false,\n      };\n    }\n  } catch {\n    // Unreadable bytes; the caller is told loam could not say.\n  }\n  return { facts: null, known: false };\n}\n\n/**\n * Every global style id declared by an `architecture/` document that parses ON\n * ITS OWN, the landscape's included — the union, sorted, so the render is a\n * function of the set rather than of readdir order.\n *\n * The document set is `architectureProjectDocuments`: the same list the PROJECT\n * read uses, so the fallback can never consider a file the merged read would\n * have excluded — the generated views file itself, or one the root `exclude`\n * hides from the renderer. A document that does not parse alone contributes\n * nothing and is not an error here: it is named by `loam validate --all`, and\n * the note this module carries already tells the reader the census came from\n * outside a project read.\n */\nasync function declaredStyles(docsDir: DocsDir, landscape: MapFacts): Promise<string[]> {\n  const ids = new Set(landscape.globalStyles ?? []);\n  let paths: string[];\n  try {\n    paths = await architectureProjectDocuments(docsDir);\n  } catch {\n    return [...ids].sort();\n  }\n  const map = resolve(landscapePath(docsDir));\n  for (const path of paths) {\n    if (resolve(path) === map) continue;\n    try {\n      const doc = await loadFile(path);\n      if (doc.errors.length === 0) for (const id of doc.globalStyles ?? []) ids.add(id);\n    } catch {\n      // One unreadable sibling costs its own styles and nothing else.\n    }\n  }\n  return [...ids].sort();\n}\n\n/**\n * ONE generated file: where it lives, and the bytes it must hold — `null` for\n * \"this file must not exist\", which is a state of its own and not a blank file\n * (`render/stale.ts` keeps the same three apart on the reading side).\n */\nexport interface ExpectedFile {\n  path: string;\n  content: string | null;\n}\n\n/** What a commit does to one generated file once every writer's own veto has passed. */\nexport type ViewsAction = \"created\" | \"updated\" | \"removed\" | \"current\";\n\n/**\n * Compare ONE generated file against what it must say: the write when they\n * differ, and what that write is. Both writers of these files — `../sync.ts`'s\n * `planFile` and the verbs' `stageGenerated` (`./txn.ts`) — put their own veto\n * in front of this and nothing else, because the rule is one rule, and a second\n * spelling of it would be a second chance for the two writers to answer\n * differently about the same file.\n *\n * The compare is over CONTENT, not bytes: `viewsAgree` records why, beside the\n * generator. A Windows clone hands a generated file back CRLF with not one fact\n * changed, and a byte compare made `sync` answer `updated` and rewrite it LF —\n * after which git shows the file permanently modified and the next checkout puts\n * the CRLF back — and folded the same rewrite into every subsystem move's\n * transaction and journal. `validate` stopped demanding that rewrite; the\n * writers must stop offering it, or they disagree about the same file. What gets\n * WRITTEN is still the LF render as a Buffer, so the decode is a comparison only.\n */\nexport function planGenerated(file: ExpectedFile, current: string | null): { action: ViewsAction; write: PlannedWrite | null } {\n  if (viewsAgree(current, file.content)) return { action: \"current\", write: null };\n  const bytes = file.content === null ? null : Buffer.from(file.content, \"utf8\");\n  return {\n    action: current === null ? \"created\" : bytes === null ? \"removed\" : \"updated\",\n    write: { path: file.path, content: bytes },\n  };\n}\n\n/**\n * The bytes BOTH generated files must hold for this tree, and whether the map\n * they were computed from was read as a PROJECT.\n *\n * The content is always renderable — from the landscape file alone, or from\n * nothing — because a fleet with no generated file yet must still get one, and\n * the tree-changing verbs must still land theirs in the commit that changes the\n * tree. `known: false` is the caller's licence to leave an EXISTING file alone\n * instead (`../sync.ts`, `action: \"blocked\"`).\n *\n * NAMED FIELDS, never an array, and never one folded answer: the two files go\n * stale for different reasons and each is named in its own finding and its own\n * report line, so a caller that could not tell them apart would have nothing to\n * say. `subsystem.views-stale` carries the path precisely so one code covers\n * both honestly.\n *\n * THE SERVICE FILE IS THE ONE THE MAP CAN EMPTY. `renderSubsystemViews` answers\n * null only when the TREE has no subsystems — a fact no map can change — while\n * `renderServiceOverviews` answers null whenever no service resolves to an\n * element, which is exactly what an unreadable map looks like from here (`facts`\n * falls back to an empty element list and an empty edge list alike). So for that\n * file \"must be absent\" and \"loam could not read the map\" are the same bytes,\n * and only `known` tells them apart:\n * a writer must not treat a null service render under `known: false` as evidence\n * that the file should go. Both callers hold that line, and say so.\n */\nexport interface ExpectedViews {\n  /**\n   * The `architecture/` PROJECT was read. False means the content was rendered\n   * from the landscape file alone — or from nothing at all — so its style census\n   * is not one an existing file may be rewritten from, and its element join is\n   * not one the per-service file may be deleted on.\n   */\n  known: boolean;\n  /** `architecture/subsystems.likec4` — one view per subsystem, from the tree. */\n  subsystems: ExpectedFile;\n  /** `architecture/services.likec4` — one overview view per service the map draws. */\n  services: ExpectedFile;\n}\n\nexport async function expectedViews(docsDir: DocsDir, tree: FleetTree): Promise<ExpectedViews> {\n  const read = await landscapeFacts(docsDir);\n  // The parsed DOCUMENT goes across, never a literal composed here: `MapFacts`\n  // carries the relationships the per-service peer sets are computed from, and a\n  // caller that dropped them would render every service view peerless — the\n  // service and its interior, and nothing it touches — with no error anywhere.\n  // The type now REQUIRES the field so that mistake cannot be made silently\n  // (`render/views.ts` records what it cost); this last-resort literal is the one\n  // place an empty answer is the TRUE one — loam could not read the map at\n  // all — and it says so rather than leaving the field off.\n  const map = read.facts ?? { elements: [], relationships: [] };\n  return {\n    known: read.known,\n    subsystems: { path: subsystemViewsPath(docsDir), content: renderSubsystemViews(tree, map) },\n    services: { path: serviceViewsPath(docsDir), content: renderServiceOverviews(tree, map) },\n  };\n}\n\n/**\n * The one line a person is owed when the map cannot be read — the same sentence\n * from `../sync.ts` (which then leaves an existing file alone) and from a\n * tree-changing verb (which renders the tolerant shape anyway, because its own\n * contract is that the file lands in the verb's commit). It names the gating\n * surface rather than repeating its findings: `loam validate --all` is where the\n * broken document is named. It lives here, beside the facts it is about, because\n * both callers are on this side of the `txn/` boundary and a constant in\n * `../sync.ts` would point the package edge back up.\n */\nexport const LANDSCAPE_UNREADABLE_NOTE =\n  \"note: architecture/ does not parse as one project, so the element join is whatever \" +\n  \"architecture/landscape.likec4 alone says and the style census is the union of the documents that parse on \" +\n  \"their own — fix the map (`loam validate --all` names the file), then re-run `loam subsystem sync`.\";\n\n/**\n * The tree AS THE RENAMES LEAVE IT, computed in memory: every dir under a\n * moved root is remapped by prefix, and each entry's placement chain is\n * re-derived from its remapped dir. The views file is rendered from this, so\n * the commit lands file and renames agreeing — never from a re-walk that\n * would have to happen between two states. Beside `expectedViews` because the\n * two are one promise: what the commit renames and what the file says must\n * come from the same in-memory answer.\n */\nexport function movedTree(tree: FleetTree, renames: { from: string; to: string }[], servicesRoot: string): FleetTree {\n  const remap = (dir: string): string => {\n    for (const r of renames) {\n      if (dir === r.from || dir.startsWith(r.from + sep)) return r.to + dir.slice(r.from.length);\n    }\n    return dir;\n  };\n  const chainOf = (dir: string): string[] => relative(servicesRoot, dir).split(sep);\n  return {\n    findings: tree.findings,\n    services: tree.services.map((s) => {\n      const dir = remap(s.dir);\n      // The constructor call records provenance: a readdir-established\n      // directory carried through a rename this same commit performs.\n      return { ...s, dir: serviceDirOf(dir), subsystem: chainOf(dir).slice(0, -1) };\n    }),\n    subsystems: tree.subsystems.map((s) => {\n      const dir = remap(s.dir);\n      return { ...s, dir, path: chainOf(dir) };\n    }),\n  };\n}\n"]}

package/dist/commands/tasks/actions.js

@@ -0,0 +1,107 @@
+/** The scenario's own name, when the packet found the words the claim was minted from. */
+function scenarioOf(unit) {
+    const source = unit.source;
+    return source !== undefined && "scenario" in source ? source.scenario : undefined;
+}
+/**
+ * A scenario action, with the claim appended when the name is missing. A
+ * scenario unit has no source only when the digest belt in core/tasks/packet.ts
+ * refused somebody else's words — rare, and then "make it pass" alone would be
+ * an instruction about nothing in particular.
+ */
+function aboutScenario(unit, phrase) {
+    const name = scenarioOf(unit);
+    return name === undefined ? `${phrase("it")}: ${unit.claim}` : phrase(`scenario '${name}'`);
+}
+/** `sends` or `receives`, out of the claim's prose — display only, see the header. */
+const DIRECTION = / declares it (sends|receives) message /;
+/** The provider at the end of `<from> calls '<op>' on <to>` — display only, see the header. */
+const CALLEE = / on (\S+)$/;
+/** What a unit waiting at `implement` asks for, by kind. */
+function implementAction(unit) {
+    switch (unit.kind) {
+        case "scenario.tested":
+            return aboutScenario(unit, (what) => `make ${what} pass, then record the run`);
+        case "api.exposes":
+            // Named because its channel is the unusual one: its done check asks for
+            // a contract-test report (`--contract-results`), not a cucumber run.
+            return unit.operation === undefined
+                ? unit.claim
+                : `expose operation '${unit.operation}' (contract-test evidence closes it)`;
+        case "event.declares": {
+            const direction = DIRECTION.exec(unit.claim)?.[1];
+            if (unit.token === undefined || direction === undefined)
+                return unit.claim;
+            return `${direction === "sends" ? "send" : "receive"} message '${unit.token}'`;
+        }
+        case "c4.calls": {
+            const callee = CALLEE.exec(unit.claim)?.[1];
+            if (unit.token === undefined || callee === undefined)
+                return unit.claim;
+            return `call '${unit.token}' on ${callee}`;
+        }
+        case "service.exists":
+            return `create service '${unit.subject}'`;
+        default:
+            // A kind added to the vocabulary after this was written still prints
+            // something true rather than nothing.
+            return unit.claim;
+    }
+}
+/**
+ * The unit as an action. `feature` is spelled into the one arm that names a
+ * command, because a reader handed "run the generator" with no id has to go and
+ * find out which feature they are looking at.
+ */
+export function actionOf(unit, feature) {
+    switch (unit.at) {
+        case "describe":
+            return unit.source === undefined
+                ? unit.claim
+                : `write the scenarios for requirement '${unit.source.requirement}' — at least one Given/When/Then, in the docs repo`;
+        case "generate":
+            return aboutScenario(unit, (what) => `generate the test for ${what} (loam gherkin ${feature})`);
+        case "attested":
+            return aboutScenario(unit, (what) => `re-answer ${what} from a test run — it rests on an agent's word`);
+        case "implement":
+            return implementAction(unit);
+        default: {
+            const unreachable = unit.at;
+            return unreachable;
+        }
+    }
+}
+/** The kinds a contract delta promises — openapi.yaml and asyncapi.yaml. */
+const CONTRACT_KINDS = new Set(["api.exposes", "event.declares"]);
+/** The kinds delta.likec4 promises — a service drawn, an edge between two. */
+const ARCHITECTURE_KINDS = new Set(["service.exists", "c4.calls"]);
+/**
+ * The heading a unit is filed under inside its service.
+ *
+ * A requirement's units sit under the requirement, which is where a person
+ * opens the file — and the path is printed ONCE there rather than on every
+ * row, which is most of what made the old view unreadable. The key carries the
+ * path as well as the requirement: one name may legitimately appear on both
+ * axes (`spec.md` and `arch.spec.md`), and those are two requirements.
+ *
+ * A describe unit's line IS the requirement heading's, so it rides on the
+ * heading; a scenario's line is its own and is printed on its row.
+ */
+export function groupOf(unit) {
+    if (CONTRACT_KINDS.has(unit.kind))
+        return { key: "contract", heading: "contract — operations and messages" };
+    if (ARCHITECTURE_KINDS.has(unit.kind))
+        return { key: "architecture", heading: "architecture — delta.likec4" };
+    const source = unit.source;
+    if (source === undefined) {
+        return { key: "unplaced", heading: "scenarios loam could not match to their words — each row quotes its claim" };
+    }
+    const label = source.path.endsWith("arch.spec.md") ? "arch requirement" : "requirement";
+    const id = source.requirementId === undefined ? "" : ` [${source.requirementId}]`;
+    const line = unit.at === "describe" && source.line !== undefined ? `:${source.line}` : "";
+    return {
+        key: ["requirement", source.path, source.requirementId ?? "", source.requirement].join("\0"),
+        heading: `${label} '${source.requirement}'${id} — ${source.path}${line}`,
+    };
+}
+//# sourceMappingURL=actions.js.map

package/dist/commands/tasks/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../../src/commands/tasks/actions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A unit said as something a person does, and the heading it is filed under.\n *\n * The packet's `claim` is the QUESTION `loam verify` asks — \"scenario 'X' of\n * requirement 'Y' (svc) is covered by a test\" — and a list of questions reads as\n * a claim ledger rather than a to-do list: the step a unit waits at used to be a\n * bracketed tag in front of a sentence that never changed with it. Here the step\n * and the kind together pick the verb, so a unit at `generate` says \"generate\n * the test\" and the same scenario at `implement` says \"make it pass\". The claim\n * stays on the payload and in `--next`, verbatim; this is a rendering, and\n * nothing ever reads it back.\n *\n * Two facts the phrasing wants live only in the claim's prose — which way an\n * event.declares message goes, and which service a c4.calls edge lands on:\n * `featureChecklist` (core/verify/checklist.ts) spells both into the sentence\n * and carries neither as a field. They are read out of the prose for DISPLAY\n * only, and a reworded claim falls back to the claim itself, which is always\n * true: no join key, count or verdict comes from here, which is the line\n * `Claim.operation`'s docblock draws against parsing claim prose.\n */\nimport type { TaskUnit } from \"../../core/tasks/unit.js\";\n\n/** The scenario's own name, when the packet found the words the claim was minted from. */\nfunction scenarioOf(unit: TaskUnit): string | undefined {\n  const source = unit.source;\n  return source !== undefined && \"scenario\" in source ? source.scenario : undefined;\n}\n\n/**\n * A scenario action, with the claim appended when the name is missing. A\n * scenario unit has no source only when the digest belt in core/tasks/packet.ts\n * refused somebody else's words — rare, and then \"make it pass\" alone would be\n * an instruction about nothing in particular.\n */\nfunction aboutScenario(unit: TaskUnit, phrase: (what: string) => string): string {\n  const name = scenarioOf(unit);\n  return name === undefined ? `${phrase(\"it\")}: ${unit.claim}` : phrase(`scenario '${name}'`);\n}\n\n/** `sends` or `receives`, out of the claim's prose — display only, see the header. */\nconst DIRECTION = / declares it (sends|receives) message /;\n\n/** The provider at the end of `<from> calls '<op>' on <to>` — display only, see the header. */\nconst CALLEE = / on (\\S+)$/;\n\n/** What a unit waiting at `implement` asks for, by kind. */\nfunction implementAction(unit: TaskUnit): string {\n  switch (unit.kind) {\n    case \"scenario.tested\":\n      return aboutScenario(unit, (what) => `make ${what} pass, then record the run`);\n    case \"api.exposes\":\n      // Named because its channel is the unusual one: its done check asks for\n      // a contract-test report (`--contract-results`), not a cucumber run.\n      return unit.operation === undefined\n        ? unit.claim\n        : `expose operation '${unit.operation}' (contract-test evidence closes it)`;\n    case \"event.declares\": {\n      const direction = DIRECTION.exec(unit.claim)?.[1];\n      if (unit.token === undefined || direction === undefined) return unit.claim;\n      return `${direction === \"sends\" ? \"send\" : \"receive\"} message '${unit.token}'`;\n    }\n    case \"c4.calls\": {\n      const callee = CALLEE.exec(unit.claim)?.[1];\n      if (unit.token === undefined || callee === undefined) return unit.claim;\n      return `call '${unit.token}' on ${callee}`;\n    }\n    case \"service.exists\":\n      return `create service '${unit.subject}'`;\n    default:\n      // A kind added to the vocabulary after this was written still prints\n      // something true rather than nothing.\n      return unit.claim;\n  }\n}\n\n/**\n * The unit as an action. `feature` is spelled into the one arm that names a\n * command, because a reader handed \"run the generator\" with no id has to go and\n * find out which feature they are looking at.\n */\nexport function actionOf(unit: TaskUnit, feature: string): string {\n  switch (unit.at) {\n    case \"describe\":\n      return unit.source === undefined\n        ? unit.claim\n        : `write the scenarios for requirement '${unit.source.requirement}' — at least one Given/When/Then, in the docs repo`;\n    case \"generate\":\n      return aboutScenario(unit, (what) => `generate the test for ${what} (loam gherkin ${feature})`);\n    case \"attested\":\n      return aboutScenario(unit, (what) => `re-answer ${what} from a test run — it rests on an agent's word`);\n    case \"implement\":\n      return implementAction(unit);\n    default: {\n      const unreachable: never = unit.at;\n      return unreachable;\n    }\n  }\n}\n\n/** The kinds a contract delta promises — openapi.yaml and asyncapi.yaml. */\nconst CONTRACT_KINDS: ReadonlySet<string> = new Set([\"api.exposes\", \"event.declares\"]);\n\n/** The kinds delta.likec4 promises — a service drawn, an edge between two. */\nconst ARCHITECTURE_KINDS: ReadonlySet<string> = new Set([\"service.exists\", \"c4.calls\"]);\n\nexport interface UnitGroup {\n  /** What makes two units one group: the same document and the same requirement in it. */\n  key: string;\n  heading: string;\n}\n\n/**\n * The heading a unit is filed under inside its service.\n *\n * A requirement's units sit under the requirement, which is where a person\n * opens the file — and the path is printed ONCE there rather than on every\n * row, which is most of what made the old view unreadable. The key carries the\n * path as well as the requirement: one name may legitimately appear on both\n * axes (`spec.md` and `arch.spec.md`), and those are two requirements.\n *\n * A describe unit's line IS the requirement heading's, so it rides on the\n * heading; a scenario's line is its own and is printed on its row.\n */\nexport function groupOf(unit: TaskUnit): UnitGroup {\n  if (CONTRACT_KINDS.has(unit.kind)) return { key: \"contract\", heading: \"contract — operations and messages\" };\n  if (ARCHITECTURE_KINDS.has(unit.kind)) return { key: \"architecture\", heading: \"architecture — delta.likec4\" };\n  const source = unit.source;\n  if (source === undefined) {\n    return { key: \"unplaced\", heading: \"scenarios loam could not match to their words — each row quotes its claim\" };\n  }\n  const label = source.path.endsWith(\"arch.spec.md\") ? \"arch requirement\" : \"requirement\";\n  const id = source.requirementId === undefined ? \"\" : ` [${source.requirementId}]`;\n  const line = unit.at === \"describe\" && source.line !== undefined ? `:${source.line}` : \"\";\n  return {\n    key: [\"requirement\", source.path, source.requirementId ?? \"\", source.requirement].join(\"\\0\"),\n    heading: `${label} '${source.requirement}'${id} — ${source.path}${line}`,\n  };\n}\n"]}