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

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

@@ -0,0 +1,128 @@
+/**
+ * The link half of `subsystem move` and `rename`: every relative markdown link
+ * the renames would break, re-expressed so it reaches the same file.
+ *
+ * THE DEFECT THIS CLOSES. A move is a directory rename, and a relative link is
+ * a route from one directory to another. `services/orders/spec.md` citing
+ * `../../glossary/order.md` is two directories below the docs root; moved into
+ * `services/commerce/orders/` it is three, and the same text names
+ * `services/glossary/order.md`, which is nothing. The move reported success,
+ * staged the renames in git, and the next `validate --all` failed
+ * `link.unresolved` on every moved document that cited anything outside its
+ * own directory — the "failing between two commits" state the commit window
+ * exists to refuse. The same rename breaks the other direction too: a
+ * capability document or a glossary term citing `services/orders/spec.md`
+ * now points where nothing is.
+ *
+ * SO BOTH DIRECTIONS ARE REWRITTEN, with the one rule archive's merge uses
+ * (`core/links/parse.ts`'s `rebaseLinks`): the target is unchanged, only the
+ * route to it, and a link whose text still reaches its target from the new
+ * place keeps its exact spelling.
+ *
+ * - Every markdown file under a moved directory, whatever its name — a runbook,
+ *   an ADR, a subsystem's own notes: the rename moves them all, so it owes them
+ *   all the same correction. Written at the OLD path, because the transaction
+ *   swaps files before it renames directories (`core/staging/txn/`), so the
+ *   rewritten bytes travel with the rename.
+ * - Every other document in the link corpus (`core/links/corpus.ts`: the fleet's
+ *   own documents, every service's, every in-flight feature's) whose links
+ *   reach INTO a moved directory. Archived features are not in it, for the
+ *   corpus's own reason: their links describe the tree as it was, and nothing
+ *   grades them.
+ *
+ * A document that cannot be decoded is left as it is: rewriting means writing
+ * the whole file back, and `link.unreadable` already names it.
+ */
+import { dirname, resolve } from "node:path";
+import { allAuthoredDocuments, movedMarkdown } from "../../../core/links/corpus.js";
+import { rebaseLinks } from "../../../core/links/parse.js";
+import { FleetContext } from "../../../core/fleet-context.js";
+import { movedUnderVouch, parseFrontmatter } from "../../../core/document/frontmatter.js";
+import { parseRequirements } from "../../../core/document/parse.js";
+import { requirementDigest } from "../../../core/document/spec.js";
+import { repoPath } from "../../../core/envelope/json.js";
+import { featuresDir } from "../../../core/repo/paths.js";
+import { inOrder } from "../../../core/kernel/concurrency.js";
+import { acrossRename, isPathInside } from "../../../core/kernel/path-safety.js";
+import { planWrite, readUtf8 } from "../../../core/staging/writes.js";
+export async function movedLinks(docsDir, moves) {
+    const retarget = (target) => {
+        for (const move of moves) {
+            if (isPathInside(move.from, target))
+                return acrossRename(target, move.from, move.to);
+        }
+        return target;
+    };
+    const out = { writes: [], relinked: [], notices: [] };
+    // The moved documents first, then every other document the corpus names —
+    // one list, deduplicated in order, because the order is what `relinked`
+    // reports and a person reads it top to bottom.
+    const candidates = [];
+    for (const move of moves)
+        candidates.push(...(await movedMarkdown(move.from)));
+    try {
+        const corpus = await allAuthoredDocuments(docsDir, new FleetContext());
+        candidates.push(...corpus.filter((path) => !moves.some((move) => isPathInside(move.from, path))));
+    }
+    catch (err) {
+        // The corpus walk enumerates every service and feature; a tree it cannot
+        // walk is one `validate` will diagnose, and the moved documents are still
+        // corrected. A move is not refused over a question it only asks to be
+        // helpful — but it does not pretend the question was answered either.
+        out.notices.push(`links INTO the moved directories were not checked — the fleet's documents could not be walked (${err instanceof Error ? err.message : String(err)}); ` +
+            "`loam validate --all` names any that broke.");
+    }
+    const seen = new Set();
+    const unique = [];
+    for (const path of candidates) {
+        if (seen.has(resolve(path)))
+            continue;
+        seen.add(resolve(path));
+        unique.push(path);
+    }
+    // Read and rewrite with bounded concurrency — the whole corpus is read
+    // before the commit window can land — and apply in input order (`inOrder`).
+    const rewritten = await inOrder(unique, async (path) => {
+        let text;
+        try {
+            text = await readUtf8(path);
+        }
+        catch {
+            // Absent (the corpus names every slot a service MAY fill — most have no
+            // runbook) or undecodable: either way there are no links to rewrite
+            // that loam could write back, and `link.unreadable` names the second.
+            return null;
+        }
+        const after = retarget(path);
+        const next = rebaseLinks(text, { from: dirname(path), to: dirname(after), retarget });
+        return next === text ? null : { path, after, text, next };
+    });
+    for (const one of rewritten) {
+        if (one === null)
+            continue;
+        const { path, after, text, next } = one;
+        out.writes.push(planWrite(path, next));
+        out.relinked.push(after);
+        const where = repoPath(docsDir, after);
+        if (movedUnderVouch(parseFrontmatter(next), next) && !movedUnderVouch(parseFrontmatter(text), text)) {
+            out.notices.push(`${where} is vouched, and this move rewrote links in it — content.stale follows until its owner re-vouches.`);
+        }
+        // Living documents only: a `Based-On:` pin holds the digest of a LIVING
+        // requirement, so a feature's own delta text moving pins nothing.
+        const pinned = (md) => parseRequirements(md).map(requirementDigest).join(",");
+        if (!isPathInside(featuresDir(docsDir), path) && pinned(next) !== pinned(text)) {
+            out.notices.push(`${where}: links this move rewrote sit inside requirements, so a feature in flight that pins one with Based-On: ` +
+                "reports delta.baseline-stale until `loam rebase` re-pins it.");
+        }
+    }
+    return out;
+}
+/**
+ * The rewritten documents that do NOT ride a rename — the ones a move touches
+ * outside the directories it names, which its uncommitted-work refusal and its
+ * git staging have to be told about by path.
+ */
+export function outside(links, moves) {
+    return links.writes.map((w) => w.path).filter((path) => !moves.some((move) => isPathInside(move.from, path)));
+}
+//# sourceMappingURL=links.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../../../src/commands/subsystem/txn/links.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The link half of `subsystem move` and `rename`: every relative markdown link\n * the renames would break, re-expressed so it reaches the same file.\n *\n * THE DEFECT THIS CLOSES. A move is a directory rename, and a relative link is\n * a route from one directory to another. `services/orders/spec.md` citing\n * `../../glossary/order.md` is two directories below the docs root; moved into\n * `services/commerce/orders/` it is three, and the same text names\n * `services/glossary/order.md`, which is nothing. The move reported success,\n * staged the renames in git, and the next `validate --all` failed\n * `link.unresolved` on every moved document that cited anything outside its\n * own directory — the \"failing between two commits\" state the commit window\n * exists to refuse. The same rename breaks the other direction too: a\n * capability document or a glossary term citing `services/orders/spec.md`\n * now points where nothing is.\n *\n * SO BOTH DIRECTIONS ARE REWRITTEN, with the one rule archive's merge uses\n * (`core/links/parse.ts`'s `rebaseLinks`): the target is unchanged, only the\n * route to it, and a link whose text still reaches its target from the new\n * place keeps its exact spelling.\n *\n * - Every markdown file under a moved directory, whatever its name — a runbook,\n *   an ADR, a subsystem's own notes: the rename moves them all, so it owes them\n *   all the same correction. Written at the OLD path, because the transaction\n *   swaps files before it renames directories (`core/staging/txn/`), so the\n *   rewritten bytes travel with the rename.\n * - Every other document in the link corpus (`core/links/corpus.ts`: the fleet's\n *   own documents, every service's, every in-flight feature's) whose links\n *   reach INTO a moved directory. Archived features are not in it, for the\n *   corpus's own reason: their links describe the tree as it was, and nothing\n *   grades them.\n *\n * A document that cannot be decoded is left as it is: rewriting means writing\n * the whole file back, and `link.unreadable` already names it.\n */\nimport { dirname, resolve } from \"node:path\";\nimport { allAuthoredDocuments, movedMarkdown } from \"../../../core/links/corpus.js\";\nimport { rebaseLinks } from \"../../../core/links/parse.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { movedUnderVouch, parseFrontmatter } from \"../../../core/document/frontmatter.js\";\nimport { parseRequirements } from \"../../../core/document/parse.js\";\nimport { requirementDigest } from \"../../../core/document/spec.js\";\nimport { repoPath } from \"../../../core/envelope/json.js\";\nimport { featuresDir } from \"../../../core/repo/paths.js\";\nimport { inOrder } from \"../../../core/kernel/concurrency.js\";\nimport { acrossRename, isPathInside } from \"../../../core/kernel/path-safety.js\";\nimport { planWrite, readUtf8, type PlannedWrite } from \"../../../core/staging/writes.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\n\n/** One directory rename, absolute paths. */\nexport interface DirectoryMove {\n  from: string;\n  to: string;\n}\n\n/** The link rewrites a set of renames owes, and where each rewritten document will be read from. */\nexport interface MovedLinks {\n  /** Planned at each document's CURRENT path — the swap lands before the rename carries it. */\n  writes: PlannedWrite[];\n  /** Each rewritten document's path once the move has landed, absolute, in the order written. */\n  relinked: string[];\n  /**\n   * The notes a person owes a reading of. A rewritten route is still a\n   * changed byte: under a `content_digest` it is `content.stale` until the\n   * owner re-vouches, and inside a requirement it moves the digest a\n   * `Based-On:` pin holds, so a feature in flight that pins it is\n   * `delta.baseline-stale` until it is rebased. Neither is softened — the\n   * archive merge reports the first the same way (`revouchOwed`) — but both\n   * are said here, by path, rather than discovered by the next gate.\n   */\n  notices: string[];\n}\n\nexport async function movedLinks(docsDir: DocsDir, moves: readonly DirectoryMove[]): Promise<MovedLinks> {\n  const retarget = (target: string): string => {\n    for (const move of moves) {\n      if (isPathInside(move.from, target)) return acrossRename(target, move.from, move.to);\n    }\n    return target;\n  };\n  const out: MovedLinks = { writes: [], relinked: [], notices: [] };\n  // The moved documents first, then every other document the corpus names —\n  // one list, deduplicated in order, because the order is what `relinked`\n  // reports and a person reads it top to bottom.\n  const candidates: string[] = [];\n  for (const move of moves) candidates.push(...(await movedMarkdown(move.from)));\n  try {\n    const corpus = await allAuthoredDocuments(docsDir, new FleetContext());\n    candidates.push(...corpus.filter((path) => !moves.some((move) => isPathInside(move.from, path))));\n  } catch (err) {\n    // The corpus walk enumerates every service and feature; a tree it cannot\n    // walk is one `validate` will diagnose, and the moved documents are still\n    // corrected. A move is not refused over a question it only asks to be\n    // helpful — but it does not pretend the question was answered either.\n    out.notices.push(\n      `links INTO the moved directories were not checked — the fleet's documents could not be walked (${err instanceof Error ? err.message : String(err)}); ` +\n        \"`loam validate --all` names any that broke.\",\n    );\n  }\n  const seen = new Set<string>();\n  const unique: string[] = [];\n  for (const path of candidates) {\n    if (seen.has(resolve(path))) continue;\n    seen.add(resolve(path));\n    unique.push(path);\n  }\n  // Read and rewrite with bounded concurrency — the whole corpus is read\n  // before the commit window can land — and apply in input order (`inOrder`).\n  const rewritten = await inOrder(unique, async (path) => {\n    let text: string;\n    try {\n      text = await readUtf8(path);\n    } catch {\n      // Absent (the corpus names every slot a service MAY fill — most have no\n      // runbook) or undecodable: either way there are no links to rewrite\n      // that loam could write back, and `link.unreadable` names the second.\n      return null;\n    }\n    const after = retarget(path);\n    const next = rebaseLinks(text, { from: dirname(path), to: dirname(after), retarget });\n    return next === text ? null : { path, after, text, next };\n  });\n  for (const one of rewritten) {\n    if (one === null) continue;\n    const { path, after, text, next } = one;\n    out.writes.push(planWrite(path, next));\n    out.relinked.push(after);\n    const where = repoPath(docsDir, after);\n    if (movedUnderVouch(parseFrontmatter(next), next) && !movedUnderVouch(parseFrontmatter(text), text)) {\n      out.notices.push(`${where} is vouched, and this move rewrote links in it — content.stale follows until its owner re-vouches.`);\n    }\n    // Living documents only: a `Based-On:` pin holds the digest of a LIVING\n    // requirement, so a feature's own delta text moving pins nothing.\n    const pinned = (md: string): string => parseRequirements(md).map(requirementDigest).join(\",\");\n    if (!isPathInside(featuresDir(docsDir), path) && pinned(next) !== pinned(text)) {\n      out.notices.push(\n        `${where}: links this move rewrote sit inside requirements, so a feature in flight that pins one with Based-On: ` +\n          \"reports delta.baseline-stale until `loam rebase` re-pins it.\",\n      );\n    }\n  }\n  return out;\n}\n\n/**\n * The rewritten documents that do NOT ride a rename — the ones a move touches\n * outside the directories it names, which its uncommitted-work refusal and its\n * git staging have to be told about by path.\n */\nexport function outside(links: MovedLinks, moves: readonly DirectoryMove[]): string[] {\n  return links.writes.map((w) => w.path).filter((path) => !moves.some((move) => isPathInside(move.from, path)));\n}\n"]}

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

@@ -0,0 +1,174 @@
+/**
+ * What one `loam subsystem sync` SAYS it did — the `--json` envelope and the
+ * human lines, in one place.
+ *
+ * It sits beside `./views.ts` and `./exclude.ts` because it is the third answer
+ * about the same three files, and it moved out of `../sync.ts` for that file's
+ * standing reason: `sync.ts` is the lock, the transaction and the plan, and it
+ * reached the 400-line limit carrying the output too. Composing a report is not
+ * a phase of the commit, so nothing here reads the disk or decides anything — a
+ * caller hands over what happened and this spells it.
+ */
+import { emitJson } from "../../../core/envelope/json.js";
+import { authoredRefusal } from "../../../core/repo/tree/render/service/header.js";
+import { LANDSCAPE_UNREADABLE_NOTE } from "./views.js";
+/** The second generated file's name, spelled once here so the key and the sentence cannot drift. */
+const SERVICE_VIEWS = "architecture/services.likec4";
+export function reportSync(json, out) {
+    // One reason today, and it is exactly the `action` it explains — spelled as a
+    // record so a second cause is an added value rather than a re-read of the
+    // sentence a person sees.
+    const blocked = out.action === "blocked" ? { reason: "landscape-invalid" } : null;
+    if (json) {
+        emitJson({
+            command: "subsystem",
+            path: "architecture/subsystems.likec4",
+            action: out.action,
+            subsystems: out.subsystems,
+            // ADDITIVE, and emitted on every run including the untouched one: a
+            // consumer must be able to read what happened to the second generated file
+            // without branching on whether this run happened to change it. `path` and
+            // `action` keep their frozen meaning — the subsystem file — so nothing
+            // reading them sees a new one.
+            serviceViews: { path: SERVICE_VIEWS, action: out.serviceViews },
+            ...(blocked === null ? {} : { blocked }),
+            ...(out.recovered === null ? {} : { recovered: out.recovered }),
+            projects: {
+                root: out.projects.root,
+                created: out.projects.created,
+                removed: out.projects.removed,
+                current: out.projects.current,
+                // Additive, and emitted in every mode including the untouched one: a
+                // consumer must be able to read what the root project now excludes
+                // without branching on whether this run happened to change it.
+                //
+                // `unreadable` travels with it because `entries: []` alone collapses the
+                // two answers `readRootExclude` insists must stay apart — "the file
+                // excludes nothing" and "loam could not read the file" are opposite
+                // facts about what the renderer will load, and the text view had the
+                // distinction while `--json` did not (verification 2026-09-04, review C).
+                exclude: {
+                    updated: out.projects.exclude.updated,
+                    entries: out.projects.exclude.entries,
+                    added: out.projects.exclude.added,
+                    removed: out.projects.exclude.removed,
+                    unreadable: out.projects.exclude.unreadable,
+                },
+            },
+        });
+        return;
+    }
+    if (out.recovered !== null && out.recovered.outcome !== "consistent") {
+        console.log(`note: recovered an interrupted \`loam ${out.recovered.command}\` commit first (${out.recovered.outcome}).`);
+    }
+    console.log(views(out));
+    serviceViews(out.serviceViews);
+    // Owed on BOTH arms: the run that declined to rewrite an existing file, and
+    // the run that wrote the tolerant shape because there was none to protect.
+    if (out.mapUnreadable)
+        console.log(LANDSCAPE_UNREADABLE_NOTE);
+    projects(out.projects);
+    exclude(out.projects);
+}
+/** The one line about the generated views file. */
+function views(out) {
+    // "nothing to write" is a claim about the WHOLE run, and it is false the moment
+    // any of this verb's FOUR writers landed something beside a current subsystem
+    // views file: the per-service views file, a project file created, one removed,
+    // or the root `exclude` rewritten. The exclude arm was missed when it was
+    // added, so the tail contradicted the very next line of output (verification
+    // 2026-09-04, review C) — and the per-service file is the same trap one file
+    // over, which is why it is in the same expression rather than a second one.
+    const quiet = out.serviceViews === "current" &&
+        out.projects.created.length === 0 &&
+        out.projects.removed.length === 0 &&
+        !out.projects.exclude.updated;
+    const sentence = {
+        current: `architecture/subsystems.likec4 is current (${out.subsystems} subsystem(s))${quiet ? " — nothing to write." : "."}`,
+        created: `wrote architecture/subsystems.likec4 — ${out.subsystems} subsystem view(s).`,
+        updated: `updated architecture/subsystems.likec4 — ${out.subsystems} subsystem view(s).`,
+        removed: `removed architecture/subsystems.likec4 — the tree has no subsystems, so the generated file must be absent.`,
+        blocked: "architecture/subsystems.likec4 left as it is — architecture/ does not parse as one project, so the " +
+            "render's element join is the landscape file's alone (a use-case document that binds an element of its " +
+            "own is not in it), and rewriting the file would take its `include` lines with it.",
+        refused: authoredRefusal("architecture/subsystems.likec4"),
+    };
+    return sentence[out.action];
+}
+/**
+ * The one line about `architecture/services.likec4`, printed on every answer but
+ * `current` — so on the two that left the file alone (`blocked`, `refused`) as
+ * well as the three that changed it. "Nothing happened to it, and here is why"
+ * is exactly the sentence a person needs; only "nothing happened to it because
+ * nothing needed to" is silence worth keeping.
+ *
+ * SILENT WHEN CURRENT, and that is the difference from the subsystem file's line
+ * above: that one is the sentence this command has always ended on and a person
+ * reads it as "the run happened", while a second unconditional line about a file
+ * nothing touched is noise on every run in a fleet that is already in order. The
+ * `--json` key is unconditional for the opposite reason — a consumer branches on
+ * a value, not on a line's presence.
+ *
+ * No view COUNT here, deliberately. The subsystem line counts subsystems because
+ * the tree answers that without reading anything; the per-service file draws
+ * only the services the MAP resolves, and the honest count is the render's, not
+ * the tree's. loam never reads a generated file's content (docs/DESIGN.md rule
+ * 26), so counting the views in it is the one place the count could come from
+ * and the one place it may not.
+ */
+function serviceViews(action) {
+    if (action === "current")
+        return;
+    const sentence = {
+        created: `wrote ${SERVICE_VIEWS} — one overview view per service the fleet map draws.`,
+        updated: `updated ${SERVICE_VIEWS} — one overview view per service the fleet map draws.`,
+        removed: `removed ${SERVICE_VIEWS} — the fleet map draws none of the services under services/, so the generated file must be absent.`,
+        blocked: `${SERVICE_VIEWS} left as it is — architecture/ does not parse as one project, so no service resolves to a ` +
+            "map element and the render would have emptied the file rather than improved it.",
+        refused: authoredRefusal(SERVICE_VIEWS),
+    };
+    console.log(sentence[action]);
+}
+/** The per-service project files this run created and removed. */
+function projects(out) {
+    if (out.created.length > 0) {
+        console.log(`wrote ${out.created.length} services/<…>/likec4.config.json — one LikeC4 project per service model whose ` +
+            "model stands alone (an existing file is yours and is never rewritten; commit the new ones before a " +
+            "`loam subsystem move`, which refuses over untracked paths). With more than one project, " +
+            "likec4 validate at the docs root needs --project <name>; build and export take every project.");
+    }
+    // Named one per line: this is a DELETE of a file a team may have written, and
+    // a count would leave a reader nothing to check against their own diff.
+    for (const path of out.removed)
+        console.log(`removed ${path}`);
+    if (out.removed.length > 0) {
+        console.log("— that model extends the fleet map, and a project file beside it registers a second renderer project " +
+            "rooted at the service directory: `likec4 validate .` then refuses without `--project`, and wherever " +
+            "that project claims the model it loads it alone, where the map's kinds are not, and the fleet project " +
+            "loses the service's interior. This is what `service.likec4-config-stray` names.");
+    }
+    if (!out.root && out.modelled > 0) {
+        console.log("note: no likec4.config.json at the docs root, so no service project files were written — " +
+            "`loam doctor` prints the root file.");
+    }
+}
+/** The root project's `exclude`, and the one state loam refuses to touch. */
+function exclude(out) {
+    const plan = out.exclude;
+    if (plan.updated) {
+        // Named entries rather than a count: this line is the whole record of a
+        // rewrite to a file the team owns, and "updated the exclude list" gives a
+        // reader nothing to check against their own diff.
+        const parts = [
+            ...(plan.added.length > 0 ? [`+${plan.added.join(" +")}`] : []),
+            ...(plan.removed.length > 0 ? [`-${plan.removed.join(" -")}`] : []),
+        ];
+        console.log(`rewrote likec4.config.json's \`exclude\` (${parts.join(" ")}) — the root project excludes exactly the ` +
+            "models that stand alone; a model that extends the fleet map renders from the docs root and must not be excluded.");
+    }
+    if (plan.unreadable) {
+        console.log("note: likec4.config.json at the docs root is not a JSON object with a string `exclude` list, so it was " +
+            "left exactly as it is — loam does not rewrite a project file it cannot read.");
+    }
+}
+//# sourceMappingURL=report.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../../src/commands/subsystem/txn/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,kDAAkD,CAAC;AAGnF,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAoBvD,oGAAoG;AACpG,MAAM,aAAa,GAAG,8BAA8B,CAAC;AAiDrD,MAAM,UAAU,UAAU,CAAC,IAAa,EAAE,GAAe;IACvD,8EAA8E;IAC9E,0EAA0E;IAC1E,0BAA0B;IAC1B,MAAM,OAAO,GAAuB,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACtG,IAAI,IAAI,EAAE,CAAC;QACT,QAAQ,CAAC;YACP,OAAO,EAAE,WAAW;YACpB,IAAI,EAAE,gCAAgC;YACtC,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,oEAAoE;YACpE,2EAA2E;YAC3E,0EAA0E;YAC1E,uEAAuE;YACvE,+BAA+B;YAC/B,YAAY,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,CAAC,YAAY,EAAE;YAC/D,GAAG,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;YACxC,GAAG,CAAC,GAAG,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;YAC/D,QAAQ,EAAE;gBACR,IAAI,EAAE,GAAG,CAAC,QAAQ,CAAC,IAAI;gBACvB,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO;gBAC7B,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO;gBAC7B,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO;gBAC7B,qEAAqE;gBACrE,mEAAmE;gBACnE,+DAA+D;gBAC/D,EAAE;gBACF,yEAAyE;gBACzE,oEAAoE;gBACpE,oEAAoE;gBACpE,qEAAqE;gBACrE,0EAA0E;gBAC1E,OAAO,EAAE;oBACP,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO;oBACrC,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO;oBACrC,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK;oBACjC,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO;oBACrC,UAAU,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU;iBAC5C;aACF;SACF,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IACD,IAAI,GAAG,CAAC,SAAS,KAAK,IAAI,IAAI,GAAG,CAAC,SAAS,CAAC,OAAO,KAAK,YAAY,EAAE,CAAC;QACrE,OAAO,CAAC,GAAG,CACT,yCAAyC,GAAG,CAAC,SAAS,CAAC,OAAO,oBAAoB,GAAG,CAAC,SAAS,CAAC,OAAO,IAAI,CAC5G,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,YAAY,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC/B,4EAA4E;IAC5E,2EAA2E;IAC3E,IAAI,GAAG,CAAC,aAAa;QAAE,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IAC9D,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvB,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AACxB,CAAC;AAED,mDAAmD;AACnD,SAAS,KAAK,CAAC,GAAe;IAC5B,gFAAgF;IAChF,8EAA8E;IAC9E,+EAA+E;IAC/E,0EAA0E;IAC1E,6EAA6E;IAC7E,6EAA6E;IAC7E,4EAA4E;IAC5E,MAAM,KAAK,GACT,GAAG,CAAC,YAAY,KAAK,SAAS;QAC9B,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QACjC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QACjC,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC;IAChC,MAAM,QAAQ,GAA+B;QAC3C,OAAO,EAAE,8CAA8C,GAAG,CAAC,UAAU,iBAAiB,KAAK,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,GAAG,EAAE;QAC5H,OAAO,EAAE,0CAA0C,GAAG,CAAC,UAAU,qBAAqB;QACtF,OAAO,EAAE,4CAA4C,GAAG,CAAC,UAAU,qBAAqB;QACxF,OAAO,EAAE,4GAA4G;QACrH,OAAO,EACL,qGAAqG;YACrG,wGAAwG;YACxG,mFAAmF;QACrF,OAAO,EAAE,eAAe,CAAC,gCAAgC,CAAC;KAC3D,CAAC;IACF,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,YAAY,CAAC,MAAkB;IACtC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO;IACjC,MAAM,QAAQ,GAAmD;QAC/D,OAAO,EAAE,SAAS,aAAa,uDAAuD;QACtF,OAAO,EAAE,WAAW,aAAa,uDAAuD;QACxF,OAAO,EAAE,WAAW,aAAa,oGAAoG;QACrI,OAAO,EACL,GAAG,aAAa,4FAA4F;YAC5G,iFAAiF;QACnF,OAAO,EAAE,eAAe,CAAC,aAAa,CAAC;KACxC,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,kEAAkE;AAClE,SAAS,QAAQ,CAAC,GAAmB;IACnC,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,GAAG,CACT,SAAS,GAAG,CAAC,OAAO,CAAC,MAAM,gFAAgF;YACzG,qGAAqG;YACrG,0FAA0F;YAC1F,+FAA+F,CAClG,CAAC;IACJ,CAAC;IACD,8EAA8E;IAC9E,wEAAwE;IACxE,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,OAAO;QAAE,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IAC/D,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,GAAG,CACT,uGAAuG;YACrG,sGAAsG;YACtG,wGAAwG;YACxG,iFAAiF,CACpF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QAClC,OAAO,CAAC,GAAG,CACT,2FAA2F;YACzF,qCAAqC,CACxC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,SAAS,OAAO,CAAC,GAAmB;IAClC,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC;IACzB,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,wEAAwE;QACxE,0EAA0E;QAC1E,kDAAkD;QAClD,MAAM,KAAK,GAAG;YACZ,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/D,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACpE,CAAC;QACF,OAAO,CAAC,GAAG,CACT,6CAA6C,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,4CAA4C;YACtG,kHAAkH,CACrH,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,OAAO,CAAC,GAAG,CACT,yGAAyG;YACvG,8EAA8E,CACjF,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["/**\n * What one `loam subsystem sync` SAYS it did — the `--json` envelope and the\n * human lines, in one place.\n *\n * It sits beside `./views.ts` and `./exclude.ts` because it is the third answer\n * about the same three files, and it moved out of `../sync.ts` for that file's\n * standing reason: `sync.ts` is the lock, the transaction and the plan, and it\n * reached the 400-line limit carrying the output too. Composing a report is not\n * a phase of the commit, so nothing here reads the disk or decides anything — a\n * caller hands over what happened and this spells it.\n */\nimport { emitJson } from \"../../../core/envelope/json.js\";\nimport { authoredRefusal } from \"../../../core/repo/tree/render/service/header.js\";\nimport type { CommitRecovery } from \"../../../core/staging/interrupted.js\";\nimport type { ExcludePlan } from \"./exclude.js\";\nimport { LANDSCAPE_UNREADABLE_NOTE } from \"./views.js\";\n\n/**\n * What one sync did to the views file — and ONLY that file; the projects report\n * separately.\n *\n * `blocked` is the fifth answer: the map cannot be read, a generated file\n * already exists, and this run left it exactly as it is. The tolerant render\n * used to run anyway and rewrote a good file down to title and description\n * (verification 2026-09-04, W5). The project half is unaffected and still runs —\n * neither the per-service files nor the root `exclude` depend on the map.\n *\n * `refused` is the sixth, and it is about OWNERSHIP rather than about the map:\n * the file standing at a path loam generates does not open with loam's mark, so\n * it is somebody's authored document and this command will not take it. It is\n * the only action that also sets a non-zero exit code (`../sync.ts` says why),\n * because unlike `blocked` it is not a state any later run clears on its own.\n */\nexport type SyncAction = \"current\" | \"created\" | \"updated\" | \"removed\" | \"blocked\" | \"refused\";\n\n/** The second generated file's name, spelled once here so the key and the sentence cannot drift. */\nconst SERVICE_VIEWS = \"architecture/services.likec4\";\n\n/** Why a run answered `blocked`. One reason today; a key rather than a bare string so a second one is additive. */\ninterface SyncBlocked {\n  reason: \"landscape-invalid\";\n}\n\n/** The additive `projects` payload key, and what the text lines are composed from. */\nexport interface ProjectsReport {\n  root: boolean;\n  /** POSIX paths relative to the DOCS ROOT, written this run, sorted by path. */\n  created: string[];\n  /**\n   * POSIX paths relative to the DOCS ROOT, DELETED this run, sorted by path — a\n   * `likec4.config.json` beside a model that extends the map. `[]` rather than\n   * absent on a run that removed none, so a consumer reads the key.\n   *\n   * SORTED BY PATH rather than by service id, which is the order the survey\n   * hands them over in: `../sync.ts` sorts both arrays where it spells them, so\n   * the `--json` list and the `removed <path>` lines below can never disagree.\n   */\n  removed: string[];\n  current: number;\n  modelled: number;\n  exclude: ExcludePlan;\n}\n\n/** Everything one run has to say, as the caller knows it. */\nexport interface SyncReport {\n  /** `architecture/subsystems.likec4` — and nothing else; the `--json` `action` key is exactly this. */\n  action: SyncAction;\n  /**\n   * `architecture/services.likec4` — the per-service overviews.\n   *\n   * A field of its own rather than a folded `action`, for the reason the shared\n   * finding code carries the path: the two files drift for different reasons and\n   * a reader told only that \"the generated views changed\" would have to diff the\n   * repo to find out which one. `blocked` reaches it exactly as it reaches the\n   * other, and for a sharper reason — with no readable map no service resolves,\n   * so the tolerant render is the empty file rather than a poorer one.\n   */\n  serviceViews: SyncAction;\n  subsystems: number;\n  recovered: CommitRecovery | null;\n  projects: ProjectsReport;\n  /** The map could not be read at all — the note is owed whether or not a file was protected. */\n  mapUnreadable: boolean;\n}\n\nexport function reportSync(json: boolean, out: SyncReport): void {\n  // One reason today, and it is exactly the `action` it explains — spelled as a\n  // record so a second cause is an added value rather than a re-read of the\n  // sentence a person sees.\n  const blocked: SyncBlocked | null = out.action === \"blocked\" ? { reason: \"landscape-invalid\" } : null;\n  if (json) {\n    emitJson({\n      command: \"subsystem\",\n      path: \"architecture/subsystems.likec4\",\n      action: out.action,\n      subsystems: out.subsystems,\n      // ADDITIVE, and emitted on every run including the untouched one: a\n      // consumer must be able to read what happened to the second generated file\n      // without branching on whether this run happened to change it. `path` and\n      // `action` keep their frozen meaning — the subsystem file — so nothing\n      // reading them sees a new one.\n      serviceViews: { path: SERVICE_VIEWS, action: out.serviceViews },\n      ...(blocked === null ? {} : { blocked }),\n      ...(out.recovered === null ? {} : { recovered: out.recovered }),\n      projects: {\n        root: out.projects.root,\n        created: out.projects.created,\n        removed: out.projects.removed,\n        current: out.projects.current,\n        // Additive, and emitted in every mode including the untouched one: a\n        // consumer must be able to read what the root project now excludes\n        // without branching on whether this run happened to change it.\n        //\n        // `unreadable` travels with it because `entries: []` alone collapses the\n        // two answers `readRootExclude` insists must stay apart — \"the file\n        // excludes nothing\" and \"loam could not read the file\" are opposite\n        // facts about what the renderer will load, and the text view had the\n        // distinction while `--json` did not (verification 2026-09-04, review C).\n        exclude: {\n          updated: out.projects.exclude.updated,\n          entries: out.projects.exclude.entries,\n          added: out.projects.exclude.added,\n          removed: out.projects.exclude.removed,\n          unreadable: out.projects.exclude.unreadable,\n        },\n      },\n    });\n    return;\n  }\n  if (out.recovered !== null && out.recovered.outcome !== \"consistent\") {\n    console.log(\n      `note: recovered an interrupted \\`loam ${out.recovered.command}\\` commit first (${out.recovered.outcome}).`,\n    );\n  }\n  console.log(views(out));\n  serviceViews(out.serviceViews);\n  // Owed on BOTH arms: the run that declined to rewrite an existing file, and\n  // the run that wrote the tolerant shape because there was none to protect.\n  if (out.mapUnreadable) console.log(LANDSCAPE_UNREADABLE_NOTE);\n  projects(out.projects);\n  exclude(out.projects);\n}\n\n/** The one line about the generated views file. */\nfunction views(out: SyncReport): string {\n  // \"nothing to write\" is a claim about the WHOLE run, and it is false the moment\n  // any of this verb's FOUR writers landed something beside a current subsystem\n  // views file: the per-service views file, a project file created, one removed,\n  // or the root `exclude` rewritten. The exclude arm was missed when it was\n  // added, so the tail contradicted the very next line of output (verification\n  // 2026-09-04, review C) — and the per-service file is the same trap one file\n  // over, which is why it is in the same expression rather than a second one.\n  const quiet =\n    out.serviceViews === \"current\" &&\n    out.projects.created.length === 0 &&\n    out.projects.removed.length === 0 &&\n    !out.projects.exclude.updated;\n  const sentence: Record<SyncAction, string> = {\n    current: `architecture/subsystems.likec4 is current (${out.subsystems} subsystem(s))${quiet ? \" — nothing to write.\" : \".\"}`,\n    created: `wrote architecture/subsystems.likec4 — ${out.subsystems} subsystem view(s).`,\n    updated: `updated architecture/subsystems.likec4 — ${out.subsystems} subsystem view(s).`,\n    removed: `removed architecture/subsystems.likec4 — the tree has no subsystems, so the generated file must be absent.`,\n    blocked:\n      \"architecture/subsystems.likec4 left as it is — architecture/ does not parse as one project, so the \" +\n      \"render's element join is the landscape file's alone (a use-case document that binds an element of its \" +\n      \"own is not in it), and rewriting the file would take its `include` lines with it.\",\n    refused: authoredRefusal(\"architecture/subsystems.likec4\"),\n  };\n  return sentence[out.action];\n}\n\n/**\n * The one line about `architecture/services.likec4`, printed on every answer but\n * `current` — so on the two that left the file alone (`blocked`, `refused`) as\n * well as the three that changed it. \"Nothing happened to it, and here is why\"\n * is exactly the sentence a person needs; only \"nothing happened to it because\n * nothing needed to\" is silence worth keeping.\n *\n * SILENT WHEN CURRENT, and that is the difference from the subsystem file's line\n * above: that one is the sentence this command has always ended on and a person\n * reads it as \"the run happened\", while a second unconditional line about a file\n * nothing touched is noise on every run in a fleet that is already in order. The\n * `--json` key is unconditional for the opposite reason — a consumer branches on\n * a value, not on a line's presence.\n *\n * No view COUNT here, deliberately. The subsystem line counts subsystems because\n * the tree answers that without reading anything; the per-service file draws\n * only the services the MAP resolves, and the honest count is the render's, not\n * the tree's. loam never reads a generated file's content (docs/DESIGN.md rule\n * 26), so counting the views in it is the one place the count could come from\n * and the one place it may not.\n */\nfunction serviceViews(action: SyncAction): void {\n  if (action === \"current\") return;\n  const sentence: Record<Exclude<SyncAction, \"current\">, string> = {\n    created: `wrote ${SERVICE_VIEWS} — one overview view per service the fleet map draws.`,\n    updated: `updated ${SERVICE_VIEWS} — one overview view per service the fleet map draws.`,\n    removed: `removed ${SERVICE_VIEWS} — the fleet map draws none of the services under services/, so the generated file must be absent.`,\n    blocked:\n      `${SERVICE_VIEWS} left as it is — architecture/ does not parse as one project, so no service resolves to a ` +\n      \"map element and the render would have emptied the file rather than improved it.\",\n    refused: authoredRefusal(SERVICE_VIEWS),\n  };\n  console.log(sentence[action]);\n}\n\n/** The per-service project files this run created and removed. */\nfunction projects(out: ProjectsReport): void {\n  if (out.created.length > 0) {\n    console.log(\n      `wrote ${out.created.length} services/<…>/likec4.config.json — one LikeC4 project per service model whose ` +\n        \"model stands alone (an existing file is yours and is never rewritten; commit the new ones before a \" +\n        \"`loam subsystem move`, which refuses over untracked paths). With more than one project, \" +\n        \"likec4 validate at the docs root needs --project <name>; build and export take every project.\",\n    );\n  }\n  // Named one per line: this is a DELETE of a file a team may have written, and\n  // a count would leave a reader nothing to check against their own diff.\n  for (const path of out.removed) console.log(`removed ${path}`);\n  if (out.removed.length > 0) {\n    console.log(\n      \"— that model extends the fleet map, and a project file beside it registers a second renderer project \" +\n        \"rooted at the service directory: `likec4 validate .` then refuses without `--project`, and wherever \" +\n        \"that project claims the model it loads it alone, where the map's kinds are not, and the fleet project \" +\n        \"loses the service's interior. This is what `service.likec4-config-stray` names.\",\n    );\n  }\n  if (!out.root && out.modelled > 0) {\n    console.log(\n      \"note: no likec4.config.json at the docs root, so no service project files were written — \" +\n        \"`loam doctor` prints the root file.\",\n    );\n  }\n}\n\n/** The root project's `exclude`, and the one state loam refuses to touch. */\nfunction exclude(out: ProjectsReport): void {\n  const plan = out.exclude;\n  if (plan.updated) {\n    // Named entries rather than a count: this line is the whole record of a\n    // rewrite to a file the team owns, and \"updated the exclude list\" gives a\n    // reader nothing to check against their own diff.\n    const parts = [\n      ...(plan.added.length > 0 ? [`+${plan.added.join(\" +\")}`] : []),\n      ...(plan.removed.length > 0 ? [`-${plan.removed.join(\" -\")}`] : []),\n    ];\n    console.log(\n      `rewrote likec4.config.json's \\`exclude\\` (${parts.join(\" \")}) — the root project excludes exactly the ` +\n        \"models that stand alone; a model that extends the fleet map renders from the docs root and must not be excluded.\",\n    );\n  }\n  if (plan.unreadable) {\n    console.log(\n      \"note: likec4.config.json at the docs root is not a JSON object with a string `exclude` list, so it was \" +\n        \"left exactly as it is — loam does not rewrite a project file it cannot read.\",\n    );\n  }\n}\n"]}

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

@@ -0,0 +1,196 @@
+/**
+ * The shared commit window every subsystem WRITE verb goes through — `new`,
+ * `rm`, `move` and `rename` all land here: lock, recover a predecessor's
+ * journal, plan against the walked tree, regenerate BOTH generated views files
+ * from the PLANNED post-state, commit through the journaled transaction
+ * (directory renames included), report. One window, because those files must
+ * land in the same commit as whatever changed the tree — a marker without its
+ * view, or renames without theirs, is exactly the `subsystem.views-stale` state
+ * the generated files' contract refuses to leave between two commits. The
+ * per-service file is in that rule and not beside it: its titles are
+ * `<subsystem path> / <service id>`, so the placement a verb changes is written
+ * into it too.
+ *
+ * This window does NOT write the per-service project files
+ * (`services/<…>/<id>/likec4.config.json`); only `../sync.ts` does, and the
+ * asymmetry is deliberate rather than an omission. The views file must ride
+ * in the verb's commit because its bytes depend on the PLACEMENT the verb is
+ * changing. A project file's bytes depend on the service id alone, which no
+ * verb here changes — and the file lives INSIDE the service directory, so a
+ * `move` carries it to the new location as part of the rename it already
+ * journals (in a git-backed repo that move REFUSES first, `move-uncommitted`,
+ * until the files `sync` created are committed — the refusal names them, and
+ * `sync`'s own output says to commit them), and `rm` never reaches one,
+ * because it refuses any subsystem that still holds a member
+ * (`subsystem-not-empty`, `../edit.ts`). No verb can
+ * therefore leave a project file stale or orphaned, and a verb that filled
+ * gaps in passing would silently write files a `--json` reader of `new` or
+ * `rename` was never told to expect. The one state a verb can leave is a
+ * model with no file beside it, and that is the state `validate --all` names
+ * as `service.likec4-config-missing`, with `loam subsystem sync` as the
+ * repair — one writer, so the create-only rule has one place to hold.
+ *
+ * NEITHER generated file is written over a document loam did not write, and
+ * that guard is checked HERE as well as in `../sync.ts` — see the comment at
+ * the check. Both are filenames loam RESERVES inside a directory the team
+ * owns, both are rewritten whole, and until the check below existed all four
+ * verbs took an authored file at either path without a word. Unlike sync,
+ * which reports the one file `refused` and completes the rest, a verb refuses
+ * WHOLE: the file has to land in this commit, so half of this commit is not a
+ * lesser version of it.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { fail, repoPath } from "../../../core/envelope/json.js";
+import { listFleetTree } from "../../../core/repo/repo.js";
+import { stageWrites } from "../../../core/staging/commit.js";
+import {} from "../../../core/staging/interrupted.js";
+import { openCommitWindow } from "../../../core/staging/recovery/recover.js";
+import { commitStaged } from "../../../core/staging/txn/transaction.js";
+import {} from "../../../core/staging/writes.js";
+import { authoredGeneratedPaths, authoredRefusal } from "../../../core/repo/tree/render/service/header.js";
+import { expectedViews, LANDSCAPE_UNREADABLE_NOTE, planGenerated } from "./views.js";
+/** The text tail a verb's success line carries about the generated files — one clause per file that moved. */
+export function reportViews(views) {
+    return ([
+        ["architecture/subsystems.likec4", views.subsystems],
+        ["architecture/services.likec4", views.services],
+    ]
+        // `current` says nothing: the tail hangs off a success line, and a verb
+        // that renamed one directory must not print two clauses about files that
+        // did not move.
+        .filter(([, action]) => action !== "current")
+        .map(([file, action]) => ` — ${file} ${action}`)
+        .join(""));
+}
+/**
+ * Lock → recover → plan → stage (views included) → journaled commit → report.
+ * `plan` returning null means it already reported a refusal; nothing was
+ * staged and nothing is written.
+ */
+export async function commitWindow(docsDir, json, plan) {
+    // Refuse-fast (0), as archive takes the lock: two concurrent verbs answer
+    // `docs-busy` rather than queue behind each other.
+    const opened = await openCommitWindow(docsDir, 0);
+    if (!opened.ok) {
+        fail(json, opened.code, opened.message);
+        return;
+    }
+    const { recovered } = opened;
+    try {
+        const txn = await plan(await listFleetTree(docsDir));
+        if (txn === null)
+            return;
+        const expected = await expectedViews(docsDir, txn.tree);
+        // OWNERSHIP BEFORE ANYTHING IS STAGED, and the WHOLE verb is refused.
+        //
+        // The guard first shipped in `../sync.ts` alone, and this window is the
+        // other writer of exactly the same two reserved paths — for `subsystem
+        // new`, `rm`, `move` and `rename` at once. Reproduced before this call
+        // existed: with a hand-authored `architecture/services.likec4` in the tree,
+        // `loam subsystem new platform` printed "architecture/services.likec4
+        // updated" and destroyed it, first line and all. One predicate, one
+        // sentence, shared from beneath every writer
+        // (`core/repo/tree/render/service/header.ts`).
+        //
+        // WHY THE WHOLE OPERATION AND NOT JUST THE FILE. `sync` can decline one file
+        // and still do the rest, because nothing else it writes depends on that file
+        // and every part of it is idempotent. This window cannot: its entire reason
+        // for existing is that the generated files land in the SAME commit as the
+        // change to the tree, so completing the structural half and reporting the
+        // file as refused would MANUFACTURE the `subsystem.views-stale` state the
+        // banner above says this window refuses to leave between two commits — and
+        // it would do so irreversibly, since `move` and `rename` also stage their
+        // renames in git. A half-done move nobody asked for is worse than a refusal
+        // a person can act on, and a refusal is re-runnable the moment the authored
+        // file is out of the reserved path.
+        //
+        // It runs AFTER `plan`, which writes nothing and has already answered the
+        // verb-specific refusals (`unknown-target`, `subsystem-not-empty`,
+        // `move-uncommitted`): a caller whose name is wrong AND whose tree holds an
+        // authored views file is better told about the name.
+        const authored = await authoredGeneratedPaths([expected.subsystems.path, expected.services.path]);
+        if (authored.length > 0) {
+            fail(json, 
+            // The code is `already-exists` and not a new one because it is exactly
+            // what that code has always meant here — "refusing to create over
+            // something that already exists, because overwriting would destroy work
+            // nobody asked to lose" — and it is already this command's documented
+            // refusal for the flat namespace. A second code for the same sentence
+            // would be a second branch an agent has to learn for no new decision.
+            "already-exists", authored.map((path) => authoredRefusal(repoPath(docsDir, path))).join(" ") +
+                " NOTHING was written and nothing was renamed: this command lands the generated views file in the same " +
+                "commit as the change to the tree, so it refuses whole rather than leaving the tree changed — and, for " +
+                "`move` and `rename`, renames staged in git — with a views file it may not write.");
+            return;
+        }
+        const writes = [...txn.writes];
+        // BOTH generated files, in the ONE commit that changes the tree. The
+        // per-service file is not a bystander here: its view titles are
+        // `<subsystem path> / <service id>`, so every `move` and `rename` restales
+        // it exactly as it restales the subsystem views, and leaving it for a later
+        // `sync` is the failing-between-two-commits state this window exists to
+        // refuse.
+        const views = {
+            subsystems: await stageGenerated(expected.subsystems, writes, false),
+            // PROTECTED when the map did not parse as a project, and only this file
+            // is: `renderSubsystemViews` answers null off the TREE, which is readable
+            // either way, while `renderServiceOverviews` answers null whenever no
+            // service resolves to an element — which is what an unreadable map looks
+            // like from here. Under `known: false` a null render is therefore not
+            // evidence of absence, and writing it would delete the whole file over a
+            // sibling document that does not parse. A verb still rewrites a file it
+            // CAN render (the tolerant arm this window has always taken), and the
+            // person is told by the note at the foot of this function.
+            services: await stageGenerated(expected.services, writes, !expected.known),
+        };
+        const staged = await stageWrites(writes);
+        const committed = await commitStaged({
+            root: docsDir,
+            command: "subsystem",
+            rerun: "loam subsystem sync",
+            target: txn.target,
+            ...(txn.moves === undefined ? {} : { moves: txn.moves }),
+        }, staged, txn.what);
+        if (!committed.ok) {
+            const code = committed.code === "rollback-incomplete"
+                ? committed.code
+                : committed.raced
+                    ? (txn.racedCode ?? txn.failedCode ?? committed.code)
+                    : (txn.failedCode ?? committed.code);
+            fail(json, code, committed.message);
+            return;
+        }
+        await txn.report(views, recovered);
+        // A verb CANNOT leave this file behind the tree — its bytes depend on the
+        // placement the verb just changed, so the tolerant render lands even when the
+        // map is unreadable and the file loses its includes. `sync` may decline that
+        // rewrite (`action: "blocked"`); a verb may not, so the person is told
+        // instead, and the same note names the run that puts the includes back.
+        if (!json && !expected.known)
+            console.log(LANDSCAPE_UNREADABLE_NOTE);
+    }
+    finally {
+        await opened.release();
+    }
+}
+/**
+ * Compare ONE generated file against what it must say, append the write when
+ * they differ, and name what happened. The compare is `planGenerated`'s, the
+ * one `../sync.ts` makes too — `./views.ts` says why it is over CONTENT, not
+ * bytes, and why there is one spelling of it.
+ *
+ * `protect` is the caller's statement that a NULL render is not evidence: the
+ * file is left exactly as it is rather than deleted. It is never a licence to
+ * skip a real rewrite — a file loam can render is rendered, which is the
+ * difference between this window and `../sync.ts`'s `blocked`.
+ */
+async function stageGenerated(file, writes, protect) {
+    const current = existsSync(file.path) ? await readFile(file.path, "utf8") : null;
+    const planned = planGenerated(file, current);
+    if (planned.write === null || (protect && file.content === null))
+        return "current";
+    writes.push(planned.write);
+    return planned.action;
+}
+//# sourceMappingURL=txn.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"txn.js","sourceRoot":"","sources":["../../../../src/commands/subsystem/txn/txn.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The shared commit window every subsystem WRITE verb goes through — `new`,\n * `rm`, `move` and `rename` all land here: lock, recover a predecessor's\n * journal, plan against the walked tree, regenerate BOTH generated views files\n * from the PLANNED post-state, commit through the journaled transaction\n * (directory renames included), report. One window, because those files must\n * land in the same commit as whatever changed the tree — a marker without its\n * view, or renames without theirs, is exactly the `subsystem.views-stale` state\n * the generated files' contract refuses to leave between two commits. The\n * per-service file is in that rule and not beside it: its titles are\n * `<subsystem path> / <service id>`, so the placement a verb changes is written\n * into it too.\n *\n * This window does NOT write the per-service project files\n * (`services/<…>/<id>/likec4.config.json`); only `../sync.ts` does, and the\n * asymmetry is deliberate rather than an omission. The views file must ride\n * in the verb's commit because its bytes depend on the PLACEMENT the verb is\n * changing. A project file's bytes depend on the service id alone, which no\n * verb here changes — and the file lives INSIDE the service directory, so a\n * `move` carries it to the new location as part of the rename it already\n * journals (in a git-backed repo that move REFUSES first, `move-uncommitted`,\n * until the files `sync` created are committed — the refusal names them, and\n * `sync`'s own output says to commit them), and `rm` never reaches one,\n * because it refuses any subsystem that still holds a member\n * (`subsystem-not-empty`, `../edit.ts`). No verb can\n * therefore leave a project file stale or orphaned, and a verb that filled\n * gaps in passing would silently write files a `--json` reader of `new` or\n * `rename` was never told to expect. The one state a verb can leave is a\n * model with no file beside it, and that is the state `validate --all` names\n * as `service.likec4-config-missing`, with `loam subsystem sync` as the\n * repair — one writer, so the create-only rule has one place to hold.\n *\n * NEITHER generated file is written over a document loam did not write, and\n * that guard is checked HERE as well as in `../sync.ts` — see the comment at\n * the check. Both are filenames loam RESERVES inside a directory the team\n * owns, both are rewritten whole, and until the check below existed all four\n * verbs took an authored file at either path without a word. Unlike sync,\n * which reports the one file `refused` and completes the rest, a verb refuses\n * WHOLE: the file has to land in this commit, so half of this commit is not a\n * lesser version of it.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { fail, repoPath, type ErrorCode } from \"../../../core/envelope/json.js\";\nimport { listFleetTree } from \"../../../core/repo/repo.js\";\nimport type { FleetTree } from \"../../../core/repo/tree/walk.js\";\nimport { stageWrites } from \"../../../core/staging/commit.js\";\nimport { type CommitRecovery } from \"../../../core/staging/interrupted.js\";\nimport { openCommitWindow } from \"../../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../../core/staging/txn/transaction.js\";\nimport { type PlannedWrite } from \"../../../core/staging/writes.js\";\nimport { authoredGeneratedPaths, authoredRefusal } from \"../../../core/repo/tree/render/service/header.js\";\nimport { type ExpectedFile, expectedViews, LANDSCAPE_UNREADABLE_NOTE, planGenerated, type ViewsAction } from \"./views.js\";\n\n/**\n * What one commit did to EACH generated file, kept apart.\n *\n * One action per file rather than one folded answer, for the reason\n * `./views.ts` gives about the expected bytes: the two files change for\n * different reasons and are named separately everywhere a person or a `--json`\n * reader meets them. The `views` key a verb has always emitted still carries\n * `subsystems` and nothing else — a payload key's meaning is frozen, so the\n * second file arrives as a key of its own beside it.\n */\nexport interface ViewsActions {\n  /** `architecture/subsystems.likec4` — the verb's `--json` `views` key, unchanged. */\n  subsystems: ViewsAction;\n  /** `architecture/services.likec4` — the per-service overviews, one per service the map draws. */\n  services: ViewsAction;\n}\n\n/** The text tail a verb's success line carries about the generated files — one clause per file that moved. */\nexport function reportViews(views: ViewsActions): string {\n  return (\n    [\n      [\"architecture/subsystems.likec4\", views.subsystems] as const,\n      [\"architecture/services.likec4\", views.services] as const,\n    ]\n      // `current` says nothing: the tail hangs off a success line, and a verb\n      // that renamed one directory must not print two clauses about files that\n      // did not move.\n      .filter(([, action]) => action !== \"current\")\n      .map(([file, action]) => ` — ${file} ${action}`)\n      .join(\"\")\n  );\n}\n\n/** What one subsystem verb asks the shared commit window to land. */\nexport interface SubsystemTxn {\n  /** The journal's `target` — what this commit is FOR. */\n  target: string;\n  /**\n   * Marker writes (create/delete), or a move's link rewrites (`./links.ts`) —\n   * planned at the document's pre-move path, which the swap lands on before\n   * the renames carry it; the views write is derived and appended.\n   */\n  writes: PlannedWrite[];\n  /** The tree AS THE COMMIT LEAVES IT — the views file is rendered from this. */\n  tree: FleetTree;\n  /** Directory renames, performed after the swaps, in this order. */\n  moves?: { from: string; to: string }[];\n  /** Remap of a RACED commit failure (new: a lost marker create is `already-exists`). */\n  racedCode?: ErrorCode;\n  /** Remap of a rolled-back commit failure (move: `move-failed` — no merge was computed). */\n  failedCode?: ErrorCode;\n  /** The rollback sentence's verb for half-state files. */\n  what: string;\n  report: (views: ViewsActions, recovered: CommitRecovery | null) => void | Promise<void>;\n}\n\n/**\n * Lock → recover → plan → stage (views included) → journaled commit → report.\n * `plan` returning null means it already reported a refusal; nothing was\n * staged and nothing is written.\n */\nexport async function commitWindow(\n  docsDir: DocsDir,\n  json: boolean,\n  plan: (tree: FleetTree) => Promise<SubsystemTxn | null>,\n): Promise<void> {\n  // Refuse-fast (0), as archive takes the lock: two concurrent verbs answer\n  // `docs-busy` rather than queue behind each other.\n  const opened = await openCommitWindow(docsDir, 0);\n  if (!opened.ok) {\n    fail(json, opened.code, opened.message);\n    return;\n  }\n  const { recovered } = opened;\n  try {\n    const txn = await plan(await listFleetTree(docsDir));\n    if (txn === null) return;\n\n    const expected = await expectedViews(docsDir, txn.tree);\n    // OWNERSHIP BEFORE ANYTHING IS STAGED, and the WHOLE verb is refused.\n    //\n    // The guard first shipped in `../sync.ts` alone, and this window is the\n    // other writer of exactly the same two reserved paths — for `subsystem\n    // new`, `rm`, `move` and `rename` at once. Reproduced before this call\n    // existed: with a hand-authored `architecture/services.likec4` in the tree,\n    // `loam subsystem new platform` printed \"architecture/services.likec4\n    // updated\" and destroyed it, first line and all. One predicate, one\n    // sentence, shared from beneath every writer\n    // (`core/repo/tree/render/service/header.ts`).\n    //\n    // WHY THE WHOLE OPERATION AND NOT JUST THE FILE. `sync` can decline one file\n    // and still do the rest, because nothing else it writes depends on that file\n    // and every part of it is idempotent. This window cannot: its entire reason\n    // for existing is that the generated files land in the SAME commit as the\n    // change to the tree, so completing the structural half and reporting the\n    // file as refused would MANUFACTURE the `subsystem.views-stale` state the\n    // banner above says this window refuses to leave between two commits — and\n    // it would do so irreversibly, since `move` and `rename` also stage their\n    // renames in git. A half-done move nobody asked for is worse than a refusal\n    // a person can act on, and a refusal is re-runnable the moment the authored\n    // file is out of the reserved path.\n    //\n    // It runs AFTER `plan`, which writes nothing and has already answered the\n    // verb-specific refusals (`unknown-target`, `subsystem-not-empty`,\n    // `move-uncommitted`): a caller whose name is wrong AND whose tree holds an\n    // authored views file is better told about the name.\n    const authored = await authoredGeneratedPaths([expected.subsystems.path, expected.services.path]);\n    if (authored.length > 0) {\n      fail(\n        json,\n        // The code is `already-exists` and not a new one because it is exactly\n        // what that code has always meant here — \"refusing to create over\n        // something that already exists, because overwriting would destroy work\n        // nobody asked to lose\" — and it is already this command's documented\n        // refusal for the flat namespace. A second code for the same sentence\n        // would be a second branch an agent has to learn for no new decision.\n        \"already-exists\",\n        authored.map((path) => authoredRefusal(repoPath(docsDir, path))).join(\" \") +\n          \" NOTHING was written and nothing was renamed: this command lands the generated views file in the same \" +\n          \"commit as the change to the tree, so it refuses whole rather than leaving the tree changed — and, for \" +\n          \"`move` and `rename`, renames staged in git — with a views file it may not write.\",\n      );\n      return;\n    }\n    const writes = [...txn.writes];\n    // BOTH generated files, in the ONE commit that changes the tree. The\n    // per-service file is not a bystander here: its view titles are\n    // `<subsystem path> / <service id>`, so every `move` and `rename` restales\n    // it exactly as it restales the subsystem views, and leaving it for a later\n    // `sync` is the failing-between-two-commits state this window exists to\n    // refuse.\n    const views: ViewsActions = {\n      subsystems: await stageGenerated(expected.subsystems, writes, false),\n      // PROTECTED when the map did not parse as a project, and only this file\n      // is: `renderSubsystemViews` answers null off the TREE, which is readable\n      // either way, while `renderServiceOverviews` answers null whenever no\n      // service resolves to an element — which is what an unreadable map looks\n      // like from here. Under `known: false` a null render is therefore not\n      // evidence of absence, and writing it would delete the whole file over a\n      // sibling document that does not parse. A verb still rewrites a file it\n      // CAN render (the tolerant arm this window has always taken), and the\n      // person is told by the note at the foot of this function.\n      services: await stageGenerated(expected.services, writes, !expected.known),\n    };\n    const staged = await stageWrites(writes);\n    const committed = await commitStaged(\n      {\n        root: docsDir,\n        command: \"subsystem\",\n        rerun: \"loam subsystem sync\",\n        target: txn.target,\n        ...(txn.moves === undefined ? {} : { moves: txn.moves }),\n      },\n      staged,\n      txn.what,\n    );\n    if (!committed.ok) {\n      const code =\n        committed.code === \"rollback-incomplete\"\n          ? committed.code\n          : committed.raced\n            ? (txn.racedCode ?? txn.failedCode ?? committed.code)\n            : (txn.failedCode ?? committed.code);\n      fail(json, code, committed.message);\n      return;\n    }\n    await txn.report(views, recovered);\n    // A verb CANNOT leave this file behind the tree — its bytes depend on the\n    // placement the verb just changed, so the tolerant render lands even when the\n    // map is unreadable and the file loses its includes. `sync` may decline that\n    // rewrite (`action: \"blocked\"`); a verb may not, so the person is told\n    // instead, and the same note names the run that puts the includes back.\n    if (!json && !expected.known) console.log(LANDSCAPE_UNREADABLE_NOTE);\n  } finally {\n    await opened.release();\n  }\n}\n\n/**\n * Compare ONE generated file against what it must say, append the write when\n * they differ, and name what happened. The compare is `planGenerated`'s, the\n * one `../sync.ts` makes too — `./views.ts` says why it is over CONTENT, not\n * bytes, and why there is one spelling of it.\n *\n * `protect` is the caller's statement that a NULL render is not evidence: the\n * file is left exactly as it is rather than deleted. It is never a licence to\n * skip a real rewrite — a file loam can render is rendered, which is the\n * difference between this window and `../sync.ts`'s `blocked`.\n */\nasync function stageGenerated(file: ExpectedFile, writes: PlannedWrite[], protect: boolean): Promise<ViewsAction> {\n  const current = existsSync(file.path) ? await readFile(file.path, \"utf8\") : null;\n  const planned = planGenerated(file, current);\n  if (planned.write === null || (protect && file.content === null)) return \"current\";\n  writes.push(planned.write);\n  return planned.action;\n}\n"]}