@ybotok/loam 0.2.0-alpha.5 → 0.2.0-alpha.7

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

@@ -0,0 +1,132 @@
+/**
+ * The ROOT `likec4.config.json`'s `exclude` list, as `loam subsystem sync`
+ * derives it from the shapes on disk.
+ *
+ * It sits beside `./views.ts` for that module's reason and by the same seam:
+ * both answer "what should this renderer-only file say, given the tree?", both
+ * are pure derivations one command writes, and keeping them together is what
+ * stops the writer and the grader spelling one rule twice. The difference is
+ * ownership, and it is stated in `core/c4/service-model/renderer.ts`: every byte
+ * of the generated views file is loam's, while this file is the team's and loam
+ * maintains exactly the `services/` entries in it. What an entry COVERS is
+ * `core/c4/root-project/exclude.ts`'s question, asked of the directory the entry
+ * names rather than of its spelling.
+ *
+ * It is a module rather than three functions in `../sync.ts` because that file
+ * reached its line limit carrying them, and this is the phase boundary inside
+ * it: `sync.ts` is the lock, the transaction and the report; this is one of the
+ * three things it decides to write.
+ */
+import { readFile } from "node:fs/promises";
+import { excludingEntry, parseRootProject, readRootExclude } from "../../../core/c4/root-project/exclude.js";
+import { standaloneExclude } from "../../../core/c4/service-model/renderer.js";
+import { serviceTreePath } from "../../../core/kernel/ids/dirs.js";
+import { rootProjectPath } from "../../../core/repo/paths.js";
+import { planWrite } from "../../../core/staging/writes.js";
+/** The answer for a run that has no root file to read, and the shape every other arm fills. */
+export const NO_EXCLUDE = {
+    updated: false,
+    entries: [],
+    added: [],
+    removed: [],
+    write: null,
+    unreadable: false,
+};
+/**
+ * The root project's `exclude` list, recomputed from the shapes on disk.
+ *
+ * WHAT MAKES THIS SAFE TO RUN ON EVERY SYNC is the split `standaloneExclude`
+ * enforces: the `services/` half of the list is loam's and every other entry is
+ * the team's, kept in order. The scaffold's node_modules glob, `features/**`, a
+ * team's own `drafts/**` all survive; only the entries that decide whether a
+ * model is renderable are derived. A standalone model MUST be excluded (inside
+ * the root project every kind it declares is a duplicate blamed on the map as
+ * well) and an extending model must NOT be (the root project is the only place
+ * it parses), so a service that migrates from one shape to the other has its
+ * entry added or dropped on the next sync instead of quietly blanking a project.
+ *
+ * THE GATE keeps an old repository untouched. A fleet whose models all stand
+ * alone and whose root already says `services/**` is already correct, and
+ * rewriting it into one entry per service would be a diff with no fact behind
+ * it — so the rewrite happens only when at least one model extends the map (the
+ * blanket exclusion is then wrong) or some standalone model is not covered at
+ * all (the renderer is merging it into the map right now). Comparing the parsed
+ * ARRAYS rather than the bytes is the second half of the same rule: a file whose
+ * `exclude` already says what this run would write is left exactly as the team
+ * formatted it.
+ *
+ * A root config loam cannot read an `exclude` list out of is REPORTED and never
+ * rewritten. Guessing at the JSON a team hand-wrote is how a writer destroys a
+ * file it did not understand.
+ */
+export async function planExclude(docsDir, services, models) {
+    const current = await readRootExclude(docsDir);
+    if (current === null)
+        return { ...NO_EXCLUDE, unreadable: true };
+    const standalone = models.filter((m) => m.standalone).map((m) => serviceTreePath(m.service));
+    // Both halves of the shape scan travel, not just the standalone one: an entry
+    // is loam's to take back either because loam wrote it (a tree the enumeration
+    // returns) or because it HIDES a model that only parses in the root project,
+    // and only the extending list can answer the second question. Without it a
+    // subsystem-wide `services/platform/**` survived every sync while
+    // `service.model-excluded` named that same sync as the repair.
+    const extending = models.filter((m) => !m.standalone).map((m) => serviceTreePath(m.service));
+    const wanted = standaloneExclude(current, {
+        standalone,
+        extending,
+        enumerated: services.map((svc) => serviceTreePath(svc)),
+    });
+    const uncovered = standalone.some((tree) => excludingEntry(current, tree) === null);
+    if (extending.length === 0 && !uncovered)
+        return { ...NO_EXCLUDE, entries: [...current] };
+    if (current.length === wanted.length && current.every((entry, i) => entry === wanted[i])) {
+        return { ...NO_EXCLUDE, entries: wanted };
+    }
+    const bytes = await rewrittenRootProject(docsDir, wanted);
+    if (bytes === null)
+        return { ...NO_EXCLUDE, entries: [...current], unreadable: true };
+    return {
+        updated: true,
+        entries: wanted,
+        added: wanted.filter((entry) => !current.includes(entry)),
+        removed: current.filter((entry) => !wanted.includes(entry)),
+        // `planWrite` decides create-vs-overwrite from the filesystem, so the root
+        // file — which by definition already exists here — is staged as an
+        // OVERWRITE, and `swapStaged` compares it against its pre-image immediately
+        // before the rename: a team member editing the same file during the sync
+        // stops the commit instead of having their bytes buried.
+        write: planWrite(rootProjectPath(docsDir), bytes),
+        unreadable: false,
+    };
+}
+/**
+ * The root project file with its `exclude` replaced and NOTHING else touched —
+ * every other key kept, in the order the team wrote them, re-serialised as
+ * 2-space JSON with a trailing newline (`core/docs.ts`'s own form, so a
+ * scaffolded file round-trips byte for byte).
+ *
+ * Null when the file stopped being a JSON object between `readRootExclude` and
+ * here, which is a concurrent edit rather than a state loam may write over.
+ */
+async function rewrittenRootProject(docsDir, exclude) {
+    let text;
+    try {
+        text = await readFile(rootProjectPath(docsDir), "utf8");
+    }
+    catch {
+        // Unreadable is not "excludes nothing": the caller reports it and writes
+        // nothing at all.
+        return null;
+    }
+    // The SAME parse the grader read the list with — `parseRootProject`, which
+    // tolerates the byte-order mark PowerShell's `Out-File` writes. Two parses
+    // would mean a run that read an `exclude` here and then declared the file
+    // unreadable at the write, which is exactly what a BOM produced before
+    // (re-verification 2026-09-04, area C item 3). Re-read rather than carried:
+    // the point of this read is that it happens immediately before the swap.
+    const parsed = parseRootProject(text);
+    if (parsed === null)
+        return null;
+    return `${JSON.stringify({ ...parsed, exclude: [...exclude] }, null, 2)}\n`;
+}
+//# sourceMappingURL=exclude.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exclude.js","sourceRoot":"","sources":["../../../../src/commands/subsystem/txn/exclude.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The ROOT `likec4.config.json`'s `exclude` list, as `loam subsystem sync`\n * derives it from the shapes on disk.\n *\n * It sits beside `./views.ts` for that module's reason and by the same seam:\n * both answer \"what should this renderer-only file say, given the tree?\", both\n * are pure derivations one command writes, and keeping them together is what\n * stops the writer and the grader spelling one rule twice. The difference is\n * ownership, and it is stated in `core/c4/service-model/renderer.ts`: every byte\n * of the generated views file is loam's, while this file is the team's and loam\n * maintains exactly the `services/` entries in it. What an entry COVERS is\n * `core/c4/root-project/exclude.ts`'s question, asked of the directory the entry\n * names rather than of its spelling.\n *\n * It is a module rather than three functions in `../sync.ts` because that file\n * reached its line limit carrying them, and this is the phase boundary inside\n * it: `sync.ts` is the lock, the transaction and the report; this is one of the\n * three things it decides to write.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { excludingEntry, parseRootProject, readRootExclude } from \"../../../core/c4/root-project/exclude.js\";\nimport { standaloneExclude } from \"../../../core/c4/service-model/renderer.js\";\nimport { serviceTreePath, type DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { rootProjectPath } from \"../../../core/repo/paths.js\";\nimport type { SurveyedModel } from \"../../../core/repo/tree/render/projects.js\";\nimport type { WalkedService } from \"../../../core/repo/tree/walk.js\";\nimport { planWrite, type PlannedWrite } from \"../../../core/staging/writes.js\";\n\n/** What one sync did to the ROOT project's `exclude` list. */\nexport interface ExcludePlan {\n  /** Whether this run rewrites the list. */\n  updated: boolean;\n  /** The list as it stands after this run — the current one when nothing changed. */\n  entries: string[];\n  added: string[];\n  removed: string[];\n  /** The rewrite, staged with everything else. Null when nothing is owed. */\n  write: PlannedWrite | null;\n  /** The root file exists and loam could not read an `exclude` list out of it — reported, never rewritten. */\n  unreadable: boolean;\n}\n\n/** The answer for a run that has no root file to read, and the shape every other arm fills. */\nexport const NO_EXCLUDE: ExcludePlan = {\n  updated: false,\n  entries: [],\n  added: [],\n  removed: [],\n  write: null,\n  unreadable: false,\n};\n\n/**\n * The root project's `exclude` list, recomputed from the shapes on disk.\n *\n * WHAT MAKES THIS SAFE TO RUN ON EVERY SYNC is the split `standaloneExclude`\n * enforces: the `services/` half of the list is loam's and every other entry is\n * the team's, kept in order. The scaffold's node_modules glob, `features/**`, a\n * team's own `drafts/**` all survive; only the entries that decide whether a\n * model is renderable are derived. A standalone model MUST be excluded (inside\n * the root project every kind it declares is a duplicate blamed on the map as\n * well) and an extending model must NOT be (the root project is the only place\n * it parses), so a service that migrates from one shape to the other has its\n * entry added or dropped on the next sync instead of quietly blanking a project.\n *\n * THE GATE keeps an old repository untouched. A fleet whose models all stand\n * alone and whose root already says `services/**` is already correct, and\n * rewriting it into one entry per service would be a diff with no fact behind\n * it — so the rewrite happens only when at least one model extends the map (the\n * blanket exclusion is then wrong) or some standalone model is not covered at\n * all (the renderer is merging it into the map right now). Comparing the parsed\n * ARRAYS rather than the bytes is the second half of the same rule: a file whose\n * `exclude` already says what this run would write is left exactly as the team\n * formatted it.\n *\n * A root config loam cannot read an `exclude` list out of is REPORTED and never\n * rewritten. Guessing at the JSON a team hand-wrote is how a writer destroys a\n * file it did not understand.\n */\nexport async function planExclude(\n  docsDir: DocsDir,\n  services: readonly WalkedService[],\n  models: readonly SurveyedModel<WalkedService>[],\n): Promise<ExcludePlan> {\n  const current = await readRootExclude(docsDir);\n  if (current === null) return { ...NO_EXCLUDE, unreadable: true };\n  const standalone = models.filter((m) => m.standalone).map((m) => serviceTreePath(m.service));\n  // Both halves of the shape scan travel, not just the standalone one: an entry\n  // is loam's to take back either because loam wrote it (a tree the enumeration\n  // returns) or because it HIDES a model that only parses in the root project,\n  // and only the extending list can answer the second question. Without it a\n  // subsystem-wide `services/platform/**` survived every sync while\n  // `service.model-excluded` named that same sync as the repair.\n  const extending = models.filter((m) => !m.standalone).map((m) => serviceTreePath(m.service));\n  const wanted = standaloneExclude(current, {\n    standalone,\n    extending,\n    enumerated: services.map((svc) => serviceTreePath(svc)),\n  });\n  const uncovered = standalone.some((tree) => excludingEntry(current, tree) === null);\n  if (extending.length === 0 && !uncovered) return { ...NO_EXCLUDE, entries: [...current] };\n  if (current.length === wanted.length && current.every((entry, i) => entry === wanted[i])) {\n    return { ...NO_EXCLUDE, entries: wanted };\n  }\n  const bytes = await rewrittenRootProject(docsDir, wanted);\n  if (bytes === null) return { ...NO_EXCLUDE, entries: [...current], unreadable: true };\n  return {\n    updated: true,\n    entries: wanted,\n    added: wanted.filter((entry) => !current.includes(entry)),\n    removed: current.filter((entry) => !wanted.includes(entry)),\n    // `planWrite` decides create-vs-overwrite from the filesystem, so the root\n    // file — which by definition already exists here — is staged as an\n    // OVERWRITE, and `swapStaged` compares it against its pre-image immediately\n    // before the rename: a team member editing the same file during the sync\n    // stops the commit instead of having their bytes buried.\n    write: planWrite(rootProjectPath(docsDir), bytes),\n    unreadable: false,\n  };\n}\n\n/**\n * The root project file with its `exclude` replaced and NOTHING else touched —\n * every other key kept, in the order the team wrote them, re-serialised as\n * 2-space JSON with a trailing newline (`core/docs.ts`'s own form, so a\n * scaffolded file round-trips byte for byte).\n *\n * Null when the file stopped being a JSON object between `readRootExclude` and\n * here, which is a concurrent edit rather than a state loam may write over.\n */\nasync function rewrittenRootProject(docsDir: DocsDir, exclude: readonly string[]): Promise<string | null> {\n  let text: string;\n  try {\n    text = await readFile(rootProjectPath(docsDir), \"utf8\");\n  } catch {\n    // Unreadable is not \"excludes nothing\": the caller reports it and writes\n    // nothing at all.\n    return null;\n  }\n  // The SAME parse the grader read the list with — `parseRootProject`, which\n  // tolerates the byte-order mark PowerShell's `Out-File` writes. Two parses\n  // would mean a run that read an `exclude` here and then declared the file\n  // unreadable at the write, which is exactly what a BOM produced before\n  // (re-verification 2026-09-04, area C item 3). Re-read rather than carried:\n  // the point of this read is that it happens immediately before the swap.\n  const parsed = parseRootProject(text);\n  if (parsed === null) return null;\n  return `${JSON.stringify({ ...parsed, exclude: [...exclude] }, null, 2)}\\n`;\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":"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","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

@@ -1,12 +1,15 @@
 /**
  * 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 the views file from the
- * PLANNED post-state, commit through the journaled transaction (directory
- * renames included), report. One window, because the views file 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 file's contract refuses to leave between two commits.
+ * 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
@@ -26,11 +29,19 @@
  * 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 } from "../../../core/envelope/json.js";
-import { subsystemViewsPath } from "../../../core/repo/paths.js";
+import { fail, repoPath } from "../../../core/envelope/json.js";
 import { listFleetTree } from "../../../core/repo/repo.js";
 import { stageWrites } from "../../../core/staging/commit.js";
 import { InterruptedCommitError } from "../../../core/staging/interrupted.js";
@@ -38,11 +49,21 @@ import { acquireDocsLock, DocsBusyError } from "../../../core/staging/lock.js";
 import { recoverInterruptedCommit } 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 { viewsAgree } from "../../../core/repo/tree/render/views.js";
-import { expectedViews } from "./views.js";
-/** The text tail a verb's success line carries about the generated file. */
+import { expectedViews, LANDSCAPE_UNREADABLE_NOTE } 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 views === "current" ? "" : ` — architecture/subsystems.likec4 ${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.
@@ -74,19 +95,69 @@ export async function commitWindow(docsDir, json, plan) {
         const txn = await plan(await listFleetTree(docsDir));
         if (txn === null)
             return;
-        const path = subsystemViewsPath(docsDir);
         const expected = await expectedViews(docsDir, txn.tree);
-        const bytes = expected === null ? null : Buffer.from(expected, "utf8");
-        // Content, not bytes — `viewsAgree` carries the reason. Without it every
-        // subsystem move on a Windows clone folded a rewrite of this file into its
-        // transaction that changed not one fact, and journalled it.
-        const current = existsSync(path) ? await readFile(path, "utf8") : null;
-        let views = "current";
-        const writes = [...txn.writes];
-        if (!viewsAgree(current, expected)) {
-            views = current === null ? "created" : bytes === null ? "removed" : "updated";
-            writes.push({ path, content: bytes });
+        // 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,
@@ -105,9 +176,42 @@ export async function commitWindow(docsDir, json, plan) {
             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 releaseLock();
     }
 }
+/**
+ * Compare ONE generated file against what it must say, append the write when
+ * they differ, and name what happened.
+ *
+ * The compare is over CONTENT, not bytes — `viewsAgree` carries the reason,
+ * beside the generator that mints them: an ordinary Windows clone hands a
+ * generated file back with CRLF and not one fact in it changed, and without
+ * this every subsystem move on such a clone folded a rewrite that changed
+ * nothing into its transaction and journalled it. What gets WRITTEN is still
+ * the LF render as a Buffer, so the decode here is a comparison only.
+ *
+ * `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;
+    if (viewsAgree(current, file.content))
+        return "current";
+    if (protect && file.content === null)
+        return "current";
+    const bytes = file.content === null ? null : Buffer.from(file.content, "utf8");
+    writes.push({ path: file.path, content: bytes });
+    return current === null ? "created" : bytes === null ? "removed" : "updated";
+}
 //# sourceMappingURL=txn.js.map