@ybotok/loam 0.2.0-alpha.6 → 0.2.0-alpha.9

package/dist/commands/subsystem/sync.js

@@ -4,9 +4,17 @@
  *
  *  - `architecture/subsystems.likec4`, the GENERATED views file. Recomputed from
  *    the tree on every run, compared, written when it differs, removed when the
- *    tree has no subsystems. The ONE repair for `subsystem.views-stale`. Left
- *    exactly as it is when the `architecture/` project does not parse and the
- *    file already exists — `action: "blocked"`, below.
+ *    tree has no subsystems. One of the two repairs for `subsystem.views-stale`.
+ *    Left exactly as it is when the `architecture/` project does not parse and
+ *    the file already exists — `action: "blocked"`, below.
+ *  - `architecture/services.likec4`, the OTHER generated views file: one
+ *    overview view per service the map draws, so a reader can open a service and
+ *    see what it touches. Same rules, same commit, same code when it drifts —
+ *    which is what makes ONE `subsystem.views-stale` honest about two files, and
+ *    why this command is named as the repair for both. Removed when NO service
+ *    resolves to a map element, exactly as the subsystem file is removed when
+ *    the tree has no subsystems. `serviceViews` is its `action`; `action` still
+ *    means the subsystem file alone.
  *  - `services/<…>/<id>/likec4.config.json`, one LikeC4 project file beside
  *    every model that STANDS ALONE. Never compared, never rewritten. Created
  *    where a standalone model has none, and DELETED where an extending model has
@@ -27,9 +35,38 @@
  *    extending model — a subsystem-wide `services/platform/**` survived every
  *    sync while `service.model-excluded` named this command as the repair.
  *
+ * NEITHER views file is written over a document loam did not write. Both are
+ * filenames loam RESERVES inside `architecture/`, a directory the team owns, and
+ * both are rewritten whole — so a repository that already kept a hand-authored
+ * diagram at one of those paths would have lost it, silently, on the first sync
+ * after the release that reserved the name. One predicate answers it for both
+ * (`readGeneratedFile`, off the file's own first line), the run reports
+ * `refused` for that file, writes nothing for it, and exits non-zero. A hand
+ * EDIT of a generated file is a different thing and is still repaired: it keeps
+ * the mark, so it is loam's file with wrong bytes in it, which is exactly what
+ * `subsystem.views-stale` says.
+ *
+ * THIS COMMAND IS NOT THE ONLY WRITER, and for a while it was the only one
+ * holding that line — reproduced, with a hand-authored
+ * `architecture/services.likec4` in the tree: `loam subsystem new platform`
+ * printed "architecture/services.likec4 updated" and destroyed it. The predicate
+ * and the refusal sentence therefore live below every writer
+ * (`core/repo/tree/render/service/header.ts`), and `./txn/txn.ts` and
+ * `../seed/plan.ts` ask the same question of the same two paths.
+ *
+ * WHAT DIFFERS IS THE POLICY, not the question, and the difference is the shape
+ * of the operation rather than a second opinion about ownership. Sync REPORTS
+ * `refused` for the one file and does the rest: nothing it writes depends on
+ * that file, every part of it is idempotent, and a run that also created a
+ * project file really did create it. A tree-changing verb and `seed` REFUSE
+ * WHOLE, because their generated file has to land in the same commit as the
+ * change to the tree — completing half of that is the very state the commit
+ * window exists never to leave between two commits, and `subsystem move` would
+ * additionally leave git-staged renames behind it.
+ *
  * The rules differ because the files answer to different owners. The
- * views file is a pure function of the tree and the committed landscape, so
- * every byte of it is loam's and a hand edit is by definition stale. The
+ * views files are a pure function of the tree and the committed landscape, so
+ * every byte of them is loam's and a hand edit is by definition stale. The
  * project file's bytes are a function of the service id ALONE — the identity
  * no verb ever changes — so nothing can make it stale, and the keys LikeC4
  * lets a team add to it (`title`, styles, a contact) are the team's; a compare
@@ -62,65 +99,38 @@
  * and the phase that is not part of the commit.
  */
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { readModelShapes } from "../../core/c4/service-model/shape.js";
 import { fail, repoPath } from "../../core/envelope/json.js";
-import { LIKEC4_ROOT_PROJECT, rootProjectPath, serviceRenderPaths, subsystemViewsPath, } from "../../core/repo/paths.js";
+import { LIKEC4_ROOT_PROJECT, rootProjectPath, serviceRenderPaths } from "../../core/repo/paths.js";
 import { listFleetTree } from "../../core/repo/repo.js";
 import { renderServiceProject, surveyProjects, } from "../../core/repo/tree/render/projects.js";
 import { stageWrites } from "../../core/staging/commit.js";
-import { InterruptedCommitError } from "../../core/staging/interrupted.js";
-import { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from "../../core/staging/lock.js";
-import { recoverInterruptedCommit } from "../../core/staging/recovery/recover.js";
+import { LOCK_WAIT_MS } from "../../core/staging/lock.js";
+import { openCommitWindow } from "../../core/staging/recovery/recover.js";
 import { commitStaged } from "../../core/staging/txn/transaction.js";
 import { planWrite } from "../../core/staging/writes.js";
-import { viewsAgree } from "../../core/repo/tree/render/views.js";
+import { readGeneratedFile } from "../../core/repo/tree/render/service/header.js";
 import { NO_EXCLUDE, planExclude } from "./txn/exclude.js";
 import { reportSync } from "./txn/report.js";
-import { expectedViews } from "./txn/views.js";
+import { expectedViews, planGenerated } from "./txn/views.js";
 export async function runSync(docsDir, json) {
-    let releaseLock;
-    try {
-        releaseLock = await acquireDocsLockWaiting(docsDir, LOCK_WAIT_MS);
-    }
-    catch (err) {
-        if (!(err instanceof DocsBusyError))
-            throw err;
-        fail(json, "docs-busy", err.message);
+    // A predecessor's journal is recovered (or refused) before the tree is
+    // read: the views file itself may be the half-written one.
+    const opened = await openCommitWindow(docsDir, LOCK_WAIT_MS);
+    if (!opened.ok) {
+        fail(json, opened.code, opened.message);
         return;
     }
+    const { recovered } = opened;
     try {
-        // A predecessor's journal is recovered (or refused) before the tree is
-        // read: the views file itself may be the half-written one.
-        let recovered;
-        try {
-            recovered = await recoverInterruptedCommit(docsDir);
-        }
-        catch (err) {
-            if (!(err instanceof InterruptedCommitError))
-                throw err;
-            fail(json, "commit-interrupted", err.message);
-            return;
-        }
         const tree = await listFleetTree(docsDir);
+        // BOTH generated files, from ONE read of the map — `./txn/views.ts` says why
+        // the pair is one answer and why the parsed document, never a literal, is
+        // what the per-service peer sets are computed from.
         const expected = await expectedViews(docsDir, tree);
-        const path = subsystemViewsPath(docsDir);
-        const expectedBytes = expected.content === null ? null : Buffer.from(expected.content, "utf8");
-        // Content, not bytes: `viewsAgree` records why, beside the generator. A
-        // Windows clone hands this file back CRLF with not one fact changed, and a
-        // byte compare made `sync` answer `updated` and rewrite it LF — after which
-        // git shows the file permanently modified and the next checkout puts the
-        // CRLF back. `validate` stopped demanding that rewrite; `sync` must stop
-        // offering it, or the two disagree about the same file.
-        const actual = existsSync(path) ? await readFile(path, "utf8") : null;
-        // The render cannot be trusted against a file that already exists when the
-        // map is unreadable: without the element join and the style census it is a
-        // title and a description, and writing it would take the `include` lines,
-        // the boundary comment and the palette reference off a file whose only fault
-        // is a sibling document that does not parse.
-        const blocked = !expected.known && actual !== null;
-        const agree = blocked || viewsAgree(actual, expected.content);
+        const views = await planFile(expected.subsystems, expected.known);
+        const services = await planFile(expected.services, expected.known);
         // ONE read of every model's bytes for the whole run, and the same scan the
         // grader uses: it decides which directories are owed a project file AND
         // which the root project must exclude, and those are opposite answers for
@@ -145,31 +155,40 @@ export async function runSync(docsDir, json) {
             modelled: plan.modelled,
             exclude,
         });
-        // `action` still describes the views file alone: a run that only created
-        // project files answers `current` for it, exactly as before the projects
-        // existed, so nothing reading the key sees a new meaning. `blocked` is the
-        // one exception and it is about that same file: it was left as it is.
-        const action = blocked
-            ? "blocked"
-            : agree
-                ? "current"
-                : actual === null
-                    ? "created"
-                    : expectedBytes === null
-                        ? "removed"
-                        : "updated";
-        const say = () => reportSync(json, {
-            action,
-            subsystems: tree.subsystems.length,
-            recovered,
-            projects: projects(),
-            mapUnreadable: !expected.known,
-        });
-        if (agree && plan.gaps.length === 0 && plan.strays.length === 0 && exclude.write === null) {
+        // `action` still describes `architecture/subsystems.likec4` ALONE — a run
+        // that only created project files, or only rewrote the per-service
+        // overviews, answers `current` for it, exactly as before either existed, so
+        // nothing reading the key sees a new meaning. The second generated file
+        // arrives as a key of its own (`serviceViews`), because a payload key's
+        // meaning is frozen and folding two files into one answer would lose which
+        // one moved — the only thing either sentence has to say.
+        const say = () => {
+            reportSync(json, {
+                action: views.action,
+                serviceViews: services.action,
+                subsystems: tree.subsystems.length,
+                recovered,
+                projects: projects(),
+                mapUnreadable: !expected.known,
+            });
+            // A REFUSAL MUST NOT READ AS A CLEAN RUN. The rest of the sync really did
+            // happen — the other generated file, the project files, the root
+            // `exclude` — so this is `loam doctor`'s and `loam validate`'s shape and
+            // not `fail()`'s: the whole report is emitted, and the exit code says the
+            // tree was not left in the state the command was asked to leave it in. A
+            // caller that runs `loam subsystem sync` in a hook or a CI step would
+            // otherwise be told nothing, forever, about a file it can never repair —
+            // and `loam validate --all` would go on reporting `subsystem.views-stale`
+            // for that path with this very command named as the fix.
+            if (views.action === "refused" || services.action === "refused")
+                process.exitCode = 1;
+        };
+        const generated = [views.write, services.write].filter((write) => write !== null);
+        if (generated.length === 0 && plan.gaps.length === 0 && plan.strays.length === 0 && exclude.write === null) {
             say();
             return;
         }
-        const writes = agree ? [] : [{ path, content: expectedBytes }];
+        const writes = [...generated];
         // `planWrite` marks a non-existent target exclusive — a no-clobber create
         // that fails EEXIST rather than replacing a file another writer landed in
         // the same instant. That IS the create-only rule, enforced by the write
@@ -202,9 +221,60 @@ export async function runSync(docsDir, json) {
         say();
     }
     finally {
-        await releaseLock();
+        await opened.release();
     }
 }
+/**
+ * What this run will do to ONE generated file: the action to report, and the
+ * write to stage (or null for "leave it alone").
+ *
+ * ONE function for both generated files, because the rule is one rule and a
+ * second spelling of it would be a second chance for `subsystems.likec4` and
+ * `services.likec4` to answer differently about the same map. Past the two
+ * vetoes below, the compare is `planGenerated` (`./txn/views.ts`), the one the
+ * tree-changing verbs make too, which says why it is over CONTENT, not bytes.
+ *
+ * `blocked` is the map's veto and it is the whole reason `known` is threaded
+ * this far. The render cannot be trusted against a file that already exists when
+ * `architecture/` does not parse as one project: without the element join and
+ * the style census, `subsystems.likec4` is a title and a description — writing
+ * it would take the `include` lines, the boundary comment and the palette
+ * reference off a file whose only fault is a sibling document that does not
+ * parse — and `services.likec4` is NOTHING AT ALL, because every one of its
+ * views is gated on a service resolving to a map element, so the tolerant render
+ * would delete the whole file. An absent file is not protected: there is nothing
+ * to lose and a fleet being scaffolded must still get its first one.
+ *
+ * `refused` is the OTHER veto and it comes from the file rather than from the
+ * map: a file at one of these reserved paths that does not open with loam's mark
+ * was written by somebody, and this command writes both files whole. It is
+ * checked first, applies to both files through one predicate, and is the one
+ * answer here that makes the run exit non-zero — see `runSync`.
+ */
+async function planFile(file, known) {
+    // ONE read for both questions — what the file says, and whose it is. The
+    // predicate and the reader live beside the mark itself
+    // (`core/repo/tree/render/service/header.ts`), below every writer of these two
+    // paths, because sync is one of FIVE and was for a while the only one holding
+    // the line.
+    const { text: actual, authored } = await readGeneratedFile(file.path);
+    // OWNERSHIP FIRST, before the map's veto and before the compare, because it is
+    // the one question whose wrong answer destroys work. Both of these are
+    // filenames loam RESERVES inside a directory the team owns, and every arm
+    // below writes the whole file or deletes it: a docs repo that already kept a
+    // hand-authored diagram at one of them would have lost it on the first sync
+    // after the upgrade that reserved the name, silently, breaking the promise the
+    // rest of the tree keeps (archive's verbatim splice: authored bytes stay
+    // authored). So the file is asked who wrote it. An EDIT of a generated file
+    // still carries the mark and is still loam's to repair — that is the whole
+    // point of `subsystem.views-stale` — and only a file that never carried it is
+    // somebody else's. Absent is not refused: there is nothing to lose.
+    if (authored)
+        return { action: "refused", write: null };
+    if (!known && actual !== null)
+        return { action: "blocked", write: null };
+    return planGenerated(file, actual);
+}
 /**
  * What the project half of this run owes, from ONE predicate. `surveyProjects`
  * is the shared spelling of "has a model, a legal id, and no file", and it

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

@@ -1 +1 @@
-{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../src/commands/subsystem/sync.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam subsystem sync` — the writer of everything under the tree that exists\n * only to be RENDERED, which is the renderer's reading of the tree twice over:\n *\n *  - `architecture/subsystems.likec4`, the GENERATED views file. Recomputed from\n *    the tree on every run, compared, written when it differs, removed when the\n *    tree has no subsystems. The ONE repair for `subsystem.views-stale`. Left\n *    exactly as it is when the `architecture/` project does not parse and the\n *    file already exists — `action: \"blocked\"`, below.\n *  - `services/<…>/<id>/likec4.config.json`, one LikeC4 project file beside\n *    every model that STANDS ALONE. Never compared, never rewritten. Created\n *    where a standalone model has none, and DELETED where an extending model has\n *    one: measured at the 1.59.2 pin, that nested project claims the model out of\n *    the root project and the fleet loses the service's interior\n *    (`core/repo/tree/render/projects.ts` carries the measurement). This is the\n *    repair `service.likec4-config-stray` has always named and, until now, did\n *    not perform.\n *  - the ROOT `likec4.config.json`'s `exclude` list, and ONLY that key. Derived\n *    from the shapes on disk on every run and rewritten when it differs, because\n *    the two shapes need opposite answers from it: a standalone model must be\n *    excluded (inside the root project every kind it declares is a duplicate)\n *    and an extending model must not be (the root project is the only place it\n *    parses). `planExclude` below states the gate that keeps an old repository\n *    untouched, and `core/c4/service-model/renderer.ts` states which half of the\n *    list is loam's and which is the team's. One entry loam did NOT write is\n *    taken anyway, and only this one: an entry naming a directory that HIDES an\n *    extending model — a subsystem-wide `services/platform/**` survived every\n *    sync while `service.model-excluded` named this command as the repair.\n *\n * The rules differ because the files answer to different owners. The\n * views file is a pure function of the tree and the committed landscape, so\n * every byte of it is loam's and a hand edit is by definition stale. The\n * project file's bytes are a function of the service id ALONE — the identity\n * no verb ever changes — so nothing can make it stale, and the keys LikeC4\n * lets a team add to it (`title`, styles, a contact) are the team's; a compare\n * would fight them, and a rewrite would take them. `core/repo/tree/render/projects.ts`\n * records the measurement behind the file and the naming rule; here, presence\n * is the one question asked of it, through the SAME predicate `validate --all`\n * grades with (`missingProjects`), so the grader can never name a gap this\n * writer would not fill.\n *\n * Nothing under `services/` is written, and no `exclude` is recomputed, unless\n * the ROOT `likec4.config.json` exists. Without it the tree is not a loadable\n * workspace at all — every model would merge into one project and report every\n * declaration as a duplicate — and a nested project beside a missing root is a\n * promise about a renderer that cannot be opened. `loam doctor` prints the root\n * file; sync says so and writes nothing for the services until it is there.\n *\n * Every write goes through the same lock + journaled transaction every docs\n * writer uses (`commitStaged`), and both kinds land in ONE commit: a\n * predecessor's interrupted commit is recovered first and a sync killed\n * mid-swap is rolled forward by the next writer. Idempotent by construction:\n * the expected views bytes are a pure function of the tree, and a project\n * file, once present, is never a gap again — so a second run reports\n * `current` and writes nothing.\n *\n * The expected views bytes come from `./txn/views.ts` — the same module every\n * writer verb renders from, so sync and the transactions cannot disagree\n * about what the file should say. The subsystem verbs' own commit window\n * (`./txn/txn.ts`) does NOT write project files, and records why. What this run\n * SAYS it did is `./txn/report.ts`: the third answer about the same three files,\n * and the phase that is not part of the commit.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { resolve } from \"node:path\";\nimport { readModelShapes, type ModelShape } from \"../../core/c4/service-model/shape.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { fail, repoPath } from \"../../core/envelope/json.js\";\nimport {\n  LIKEC4_ROOT_PROJECT,\n  rootProjectPath,\n  serviceRenderPaths,\n  subsystemViewsPath,\n} from \"../../core/repo/paths.js\";\nimport { listFleetTree } from \"../../core/repo/repo.js\";\nimport {\n  type ProjectGap,\n  renderServiceProject,\n  surveyProjects,\n  type SurveyedModel,\n} from \"../../core/repo/tree/render/projects.js\";\nimport type { WalkedService } from \"../../core/repo/tree/walk.js\";\nimport { stageWrites } from \"../../core/staging/commit.js\";\nimport { type CommitRecovery, InterruptedCommitError } from \"../../core/staging/interrupted.js\";\nimport { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { recoverInterruptedCommit } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { planWrite, type PlannedWrite } from \"../../core/staging/writes.js\";\nimport { viewsAgree } from \"../../core/repo/tree/render/views.js\";\nimport { NO_EXCLUDE, planExclude } from \"./txn/exclude.js\";\nimport { type ProjectsReport, reportSync, type SyncAction } from \"./txn/report.js\";\nimport { expectedViews } from \"./txn/views.js\";\n\n/**\n * The per-service project half of one sync, before the write: what the\n * predicate found, and the two counts the report needs beside it.\n */\ninterface ProjectPlan {\n  /** Whether the root project file exists — the gate on every service write. */\n  root: boolean;\n  /** The files this run will create. Empty whenever `root` is false. */\n  gaps: ProjectGap<WalkedService>[];\n  /** The files this run will DELETE — a project file beside an extending model. Empty whenever `root` is false. */\n  strays: ProjectGap<WalkedService>[];\n  /**\n   * Services owed a project file that ALREADY had one — so STANDALONE models\n   * only; 0 whenever `root` is false. An extending model is owed none, and\n   * counting it here said a file was in place beside a model that must not have\n   * one (`service.likec4-config-stray` grades exactly that state).\n   */\n  current: number;\n  /** Model-bearing services, root or no root — what the root-missing note is owed to. */\n  modelled: number;\n  /** Every model this run considered, with its shape — the exclude list is derived from the same walk. */\n  models: SurveyedModel<WalkedService>[];\n}\n\nexport async function runSync(docsDir: DocsDir, json: boolean): Promise<void> {\n  let releaseLock: () => Promise<void>;\n  try {\n    releaseLock = await acquireDocsLockWaiting(docsDir, LOCK_WAIT_MS);\n  } catch (err) {\n    if (!(err instanceof DocsBusyError)) throw err;\n    fail(json, \"docs-busy\", err.message);\n    return;\n  }\n  try {\n    // A predecessor's journal is recovered (or refused) before the tree is\n    // read: the views file itself may be the half-written one.\n    let recovered: CommitRecovery | null;\n    try {\n      recovered = await recoverInterruptedCommit(docsDir);\n    } catch (err) {\n      if (!(err instanceof InterruptedCommitError)) throw err;\n      fail(json, \"commit-interrupted\", err.message);\n      return;\n    }\n\n    const tree = await listFleetTree(docsDir);\n    const expected = await expectedViews(docsDir, tree);\n    const path = subsystemViewsPath(docsDir);\n    const expectedBytes = expected.content === null ? null : Buffer.from(expected.content, \"utf8\");\n    // Content, not bytes: `viewsAgree` records why, beside the generator. A\n    // Windows clone hands this file back CRLF with not one fact changed, and a\n    // byte compare made `sync` answer `updated` and rewrite it LF — after which\n    // git shows the file permanently modified and the next checkout puts the\n    // CRLF back. `validate` stopped demanding that rewrite; `sync` must stop\n    // offering it, or the two disagree about the same file.\n    const actual = existsSync(path) ? await readFile(path, \"utf8\") : null;\n    // The render cannot be trusted against a file that already exists when the\n    // map is unreadable: without the element join and the style census it is a\n    // title and a description, and writing it would take the `include` lines,\n    // the boundary comment and the palette reference off a file whose only fault\n    // is a sibling document that does not parse.\n    const blocked = !expected.known && actual !== null;\n    const agree = blocked || viewsAgree(actual, expected.content);\n    // ONE read of every model's bytes for the whole run, and the same scan the\n    // grader uses: it decides which directories are owed a project file AND\n    // which the root project must exclude, and those are opposite answers for\n    // the two shapes (`core/repo/tree/render/projects.ts`).\n    const shapes = await readModelShapes(tree.services.map((svc) => serviceRenderPaths(svc.dir).model));\n    const plan = planProjects(docsDir, tree.services, shapes);\n    const exclude = plan.root ? await planExclude(docsDir, tree.services, plan.models) : NO_EXCLUDE;\n    // The plan IS the report: every gap is created and every stray removed in\n    // the one commit below, and the early return is the branch where both lists\n    // are empty.\n    const projects = (): ProjectsReport => ({\n      root: plan.root,\n      // SORTED BY PATH, which is what the contract says these keys hold and what\n      // the survey's own order is not: `surveyProjects` sorts by service id, so\n      // `services/svc-a/…` came out before `services/platform/svc-d/…` and a\n      // consumer told the list was \"sorted\" got an order no path sort produces\n      // (re-verification 2026-09-04, area C item 6). The text view prints the\n      // same array, so the two orders cannot drift apart.\n      created: plan.gaps.map((gap) => repoPath(docsDir, gap.path)).sort(),\n      removed: plan.strays.map((stray) => repoPath(docsDir, stray.path)).sort(),\n      current: plan.current,\n      modelled: plan.modelled,\n      exclude,\n    });\n    // `action` still describes the views file alone: a run that only created\n    // project files answers `current` for it, exactly as before the projects\n    // existed, so nothing reading the key sees a new meaning. `blocked` is the\n    // one exception and it is about that same file: it was left as it is.\n    const action: SyncAction = blocked\n      ? \"blocked\"\n      : agree\n        ? \"current\"\n        : actual === null\n          ? \"created\"\n          : expectedBytes === null\n            ? \"removed\"\n            : \"updated\";\n    const say = (): void =>\n      reportSync(json, {\n        action,\n        subsystems: tree.subsystems.length,\n        recovered,\n        projects: projects(),\n        mapUnreadable: !expected.known,\n      });\n    if (agree && plan.gaps.length === 0 && plan.strays.length === 0 && exclude.write === null) {\n      say();\n      return;\n    }\n    const writes: PlannedWrite[] = agree ? [] : [{ path, content: expectedBytes }];\n    // `planWrite` marks a non-existent target exclusive — a no-clobber create\n    // that fails EEXIST rather than replacing a file another writer landed in\n    // the same instant. That IS the create-only rule, enforced by the write\n    // path rather than by the `existsSync` the predicate already ran: a file\n    // that appears between the check and the swap is somebody's, and stays.\n    for (const gap of plan.gaps) {\n      writes.push(planWrite(gap.path, renderServiceProject(gap.service.id, LIKEC4_ROOT_PROJECT)));\n    }\n    // The one file this verb DELETES, and it rides the same journal as the rest,\n    // so a run killed mid-swap is rolled forward rather than half-done.\n    // `content: null` is the delete the views file already uses.\n    for (const stray of plan.strays) writes.push({ path: stray.path, content: null });\n    // The root project's `exclude`, in the SAME transaction as the files it\n    // decides the fate of: a run that wrote the per-service projects and died\n    // before the exclude would leave a tree where the renderer loads a\n    // standalone model twice — once in the root project, where every kind it\n    // declares is a duplicate — which is worse than either end state.\n    if (exclude.write !== null) writes.push(exclude.write);\n    // One lock, one journal, one commit for both kinds of file — a sync killed\n    // between the views swap and the project creates would otherwise leave a\n    // half-state no later run could tell from a team's deliberate deletion.\n    const staged = await stageWrites(writes);\n    const committed = await commitStaged(\n      { root: docsDir, command: \"subsystem\", rerun: \"loam subsystem sync\", target: \"subsystems\" },\n      staged,\n      \"synced\",\n    );\n    if (!committed.ok) {\n      fail(json, committed.code, committed.message);\n      return;\n    }\n    say();\n  } finally {\n    await releaseLock();\n  }\n}\n\n/**\n * What the project half of this run owes, from ONE predicate. `surveyProjects`\n * is the shared spelling of \"has a model, a legal id, and no file\", and it\n * hands back the sizes of the two domains it counted against — every model it\n * walked, and the standalone models a file is owed for — so `current` is a\n * subtraction rather than a second reading of the same two paths. A loop here\n * re-spelling \"has a model\" was the drift the shared predicate exists to\n * prevent, and it would have kept counting a directory the survey had\n * skipped. Without the root file the gaps are real but stay unfilled —\n * writing them would promise a renderer nobody can open — and `current` is 0\n * because \"already had a file\" is only a fact about a workspace that exists.\n */\nfunction planProjects(\n  docsDir: DocsDir,\n  services: readonly WalkedService[],\n  shapes: ReadonlyMap<string, ModelShape>,\n): ProjectPlan {\n  const root = existsSync(rootProjectPath(docsDir));\n  // A model that EXTENDS the map is owed no file, and the survey is where that\n  // is decided — one predicate for the writer and the grader, so `validate --all`\n  // can never name a gap this run would not fill. An unreadable model classifies\n  // as standalone (`readModelShapes`), which is the conservative arm: it gets a\n  // project file, which is what every model got before shapes existed.\n  const survey = surveyProjects(services, serviceRenderPaths, (model) => shapes.get(resolve(model)) !== \"extending\");\n  if (!root) return { root, gaps: [], strays: [], current: 0, modelled: survey.modelled, models: survey.models };\n  return {\n    root,\n    gaps: survey.gaps,\n    // The removal is gated on the root file for the same reason the create is:\n    // without it the docs root is not a LikeC4 workspace, so nothing there is\n    // claiming anything out of a root project that does not exist, and deleting\n    // a team's file over a renderer nobody can open is a writer acting on a\n    // hazard it cannot see.\n    strays: survey.strays,\n    // Over the STANDALONE domain, which is the one `gaps` was drawn from: a\n    // model that extends the map is owed no file, so it can neither be a gap nor\n    // \"already have one\", and subtracting from `modelled` counted every\n    // extending model as the latter.\n    current: survey.standalone - survey.gaps.length,\n    modelled: survey.modelled,\n    models: survey.models,\n  };\n}\n"]}
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../../src/commands/subsystem/sync.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam subsystem sync` — the writer of everything under the tree that exists\n * only to be RENDERED, which is the renderer's reading of the tree twice over:\n *\n *  - `architecture/subsystems.likec4`, the GENERATED views file. Recomputed from\n *    the tree on every run, compared, written when it differs, removed when the\n *    tree has no subsystems. One of the two repairs for `subsystem.views-stale`.\n *    Left exactly as it is when the `architecture/` project does not parse and\n *    the file already exists — `action: \"blocked\"`, below.\n *  - `architecture/services.likec4`, the OTHER generated views file: one\n *    overview view per service the map draws, so a reader can open a service and\n *    see what it touches. Same rules, same commit, same code when it drifts —\n *    which is what makes ONE `subsystem.views-stale` honest about two files, and\n *    why this command is named as the repair for both. Removed when NO service\n *    resolves to a map element, exactly as the subsystem file is removed when\n *    the tree has no subsystems. `serviceViews` is its `action`; `action` still\n *    means the subsystem file alone.\n *  - `services/<…>/<id>/likec4.config.json`, one LikeC4 project file beside\n *    every model that STANDS ALONE. Never compared, never rewritten. Created\n *    where a standalone model has none, and DELETED where an extending model has\n *    one: measured at the 1.59.2 pin, that nested project claims the model out of\n *    the root project and the fleet loses the service's interior\n *    (`core/repo/tree/render/projects.ts` carries the measurement). This is the\n *    repair `service.likec4-config-stray` has always named and, until now, did\n *    not perform.\n *  - the ROOT `likec4.config.json`'s `exclude` list, and ONLY that key. Derived\n *    from the shapes on disk on every run and rewritten when it differs, because\n *    the two shapes need opposite answers from it: a standalone model must be\n *    excluded (inside the root project every kind it declares is a duplicate)\n *    and an extending model must not be (the root project is the only place it\n *    parses). `planExclude` below states the gate that keeps an old repository\n *    untouched, and `core/c4/service-model/renderer.ts` states which half of the\n *    list is loam's and which is the team's. One entry loam did NOT write is\n *    taken anyway, and only this one: an entry naming a directory that HIDES an\n *    extending model — a subsystem-wide `services/platform/**` survived every\n *    sync while `service.model-excluded` named this command as the repair.\n *\n * NEITHER views file is written over a document loam did not write. Both are\n * filenames loam RESERVES inside `architecture/`, a directory the team owns, and\n * both are rewritten whole — so a repository that already kept a hand-authored\n * diagram at one of those paths would have lost it, silently, on the first sync\n * after the release that reserved the name. One predicate answers it for both\n * (`readGeneratedFile`, off the file's own first line), the run reports\n * `refused` for that file, writes nothing for it, and exits non-zero. A hand\n * EDIT of a generated file is a different thing and is still repaired: it keeps\n * the mark, so it is loam's file with wrong bytes in it, which is exactly what\n * `subsystem.views-stale` says.\n *\n * THIS COMMAND IS NOT THE ONLY WRITER, and for a while it was the only one\n * holding that line — reproduced, with a hand-authored\n * `architecture/services.likec4` in the tree: `loam subsystem new platform`\n * printed \"architecture/services.likec4 updated\" and destroyed it. The predicate\n * and the refusal sentence therefore live below every writer\n * (`core/repo/tree/render/service/header.ts`), and `./txn/txn.ts` and\n * `../seed/plan.ts` ask the same question of the same two paths.\n *\n * WHAT DIFFERS IS THE POLICY, not the question, and the difference is the shape\n * of the operation rather than a second opinion about ownership. Sync REPORTS\n * `refused` for the one file and does the rest: nothing it writes depends on\n * that file, every part of it is idempotent, and a run that also created a\n * project file really did create it. A tree-changing verb and `seed` REFUSE\n * WHOLE, because their generated file has to land in the same commit as the\n * change to the tree — completing half of that is the very state the commit\n * window exists never to leave between two commits, and `subsystem move` would\n * additionally leave git-staged renames behind it.\n *\n * The rules differ because the files answer to different owners. The\n * views files are a pure function of the tree and the committed landscape, so\n * every byte of them is loam's and a hand edit is by definition stale. The\n * project file's bytes are a function of the service id ALONE — the identity\n * no verb ever changes — so nothing can make it stale, and the keys LikeC4\n * lets a team add to it (`title`, styles, a contact) are the team's; a compare\n * would fight them, and a rewrite would take them. `core/repo/tree/render/projects.ts`\n * records the measurement behind the file and the naming rule; here, presence\n * is the one question asked of it, through the SAME predicate `validate --all`\n * grades with (`missingProjects`), so the grader can never name a gap this\n * writer would not fill.\n *\n * Nothing under `services/` is written, and no `exclude` is recomputed, unless\n * the ROOT `likec4.config.json` exists. Without it the tree is not a loadable\n * workspace at all — every model would merge into one project and report every\n * declaration as a duplicate — and a nested project beside a missing root is a\n * promise about a renderer that cannot be opened. `loam doctor` prints the root\n * file; sync says so and writes nothing for the services until it is there.\n *\n * Every write goes through the same lock + journaled transaction every docs\n * writer uses (`commitStaged`), and both kinds land in ONE commit: a\n * predecessor's interrupted commit is recovered first and a sync killed\n * mid-swap is rolled forward by the next writer. Idempotent by construction:\n * the expected views bytes are a pure function of the tree, and a project\n * file, once present, is never a gap again — so a second run reports\n * `current` and writes nothing.\n *\n * The expected views bytes come from `./txn/views.ts` — the same module every\n * writer verb renders from, so sync and the transactions cannot disagree\n * about what the file should say. The subsystem verbs' own commit window\n * (`./txn/txn.ts`) does NOT write project files, and records why. What this run\n * SAYS it did is `./txn/report.ts`: the third answer about the same three files,\n * and the phase that is not part of the commit.\n */\nimport { existsSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport { readModelShapes, type ModelShape } from \"../../core/c4/service-model/shape.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { fail, repoPath } from \"../../core/envelope/json.js\";\nimport { LIKEC4_ROOT_PROJECT, rootProjectPath, serviceRenderPaths } from \"../../core/repo/paths.js\";\nimport { listFleetTree } from \"../../core/repo/repo.js\";\nimport {\n  type ProjectGap,\n  renderServiceProject,\n  surveyProjects,\n  type SurveyedModel,\n} from \"../../core/repo/tree/render/projects.js\";\nimport type { WalkedService } from \"../../core/repo/tree/walk.js\";\nimport { stageWrites } from \"../../core/staging/commit.js\";\nimport { LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { openCommitWindow } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { planWrite, type PlannedWrite } from \"../../core/staging/writes.js\";\nimport { readGeneratedFile } from \"../../core/repo/tree/render/service/header.js\";\nimport { NO_EXCLUDE, planExclude } from \"./txn/exclude.js\";\nimport { type ProjectsReport, reportSync, type SyncAction } from \"./txn/report.js\";\nimport { type ExpectedFile, expectedViews, planGenerated } from \"./txn/views.js\";\n\n/**\n * The per-service project half of one sync, before the write: what the\n * predicate found, and the two counts the report needs beside it.\n */\ninterface ProjectPlan {\n  /** Whether the root project file exists — the gate on every service write. */\n  root: boolean;\n  /** The files this run will create. Empty whenever `root` is false. */\n  gaps: ProjectGap<WalkedService>[];\n  /** The files this run will DELETE — a project file beside an extending model. Empty whenever `root` is false. */\n  strays: ProjectGap<WalkedService>[];\n  /**\n   * Services owed a project file that ALREADY had one — so STANDALONE models\n   * only; 0 whenever `root` is false. An extending model is owed none, and\n   * counting it here said a file was in place beside a model that must not have\n   * one (`service.likec4-config-stray` grades exactly that state).\n   */\n  current: number;\n  /** Model-bearing services, root or no root — what the root-missing note is owed to. */\n  modelled: number;\n  /** Every model this run considered, with its shape — the exclude list is derived from the same walk. */\n  models: SurveyedModel<WalkedService>[];\n}\n\nexport async function runSync(docsDir: DocsDir, json: boolean): Promise<void> {\n  // A predecessor's journal is recovered (or refused) before the tree is\n  // read: the views file itself may be the half-written one.\n  const opened = await openCommitWindow(docsDir, LOCK_WAIT_MS);\n  if (!opened.ok) {\n    fail(json, opened.code, opened.message);\n    return;\n  }\n  const { recovered } = opened;\n  try {\n    const tree = await listFleetTree(docsDir);\n    // BOTH generated files, from ONE read of the map — `./txn/views.ts` says why\n    // the pair is one answer and why the parsed document, never a literal, is\n    // what the per-service peer sets are computed from.\n    const expected = await expectedViews(docsDir, tree);\n    const views = await planFile(expected.subsystems, expected.known);\n    const services = await planFile(expected.services, expected.known);\n    // ONE read of every model's bytes for the whole run, and the same scan the\n    // grader uses: it decides which directories are owed a project file AND\n    // which the root project must exclude, and those are opposite answers for\n    // the two shapes (`core/repo/tree/render/projects.ts`).\n    const shapes = await readModelShapes(tree.services.map((svc) => serviceRenderPaths(svc.dir).model));\n    const plan = planProjects(docsDir, tree.services, shapes);\n    const exclude = plan.root ? await planExclude(docsDir, tree.services, plan.models) : NO_EXCLUDE;\n    // The plan IS the report: every gap is created and every stray removed in\n    // the one commit below, and the early return is the branch where both lists\n    // are empty.\n    const projects = (): ProjectsReport => ({\n      root: plan.root,\n      // SORTED BY PATH, which is what the contract says these keys hold and what\n      // the survey's own order is not: `surveyProjects` sorts by service id, so\n      // `services/svc-a/…` came out before `services/platform/svc-d/…` and a\n      // consumer told the list was \"sorted\" got an order no path sort produces\n      // (re-verification 2026-09-04, area C item 6). The text view prints the\n      // same array, so the two orders cannot drift apart.\n      created: plan.gaps.map((gap) => repoPath(docsDir, gap.path)).sort(),\n      removed: plan.strays.map((stray) => repoPath(docsDir, stray.path)).sort(),\n      current: plan.current,\n      modelled: plan.modelled,\n      exclude,\n    });\n    // `action` still describes `architecture/subsystems.likec4` ALONE — a run\n    // that only created project files, or only rewrote the per-service\n    // overviews, answers `current` for it, exactly as before either existed, so\n    // nothing reading the key sees a new meaning. The second generated file\n    // arrives as a key of its own (`serviceViews`), because a payload key's\n    // meaning is frozen and folding two files into one answer would lose which\n    // one moved — the only thing either sentence has to say.\n    const say = (): void => {\n      reportSync(json, {\n        action: views.action,\n        serviceViews: services.action,\n        subsystems: tree.subsystems.length,\n        recovered,\n        projects: projects(),\n        mapUnreadable: !expected.known,\n      });\n      // A REFUSAL MUST NOT READ AS A CLEAN RUN. The rest of the sync really did\n      // happen — the other generated file, the project files, the root\n      // `exclude` — so this is `loam doctor`'s and `loam validate`'s shape and\n      // not `fail()`'s: the whole report is emitted, and the exit code says the\n      // tree was not left in the state the command was asked to leave it in. A\n      // caller that runs `loam subsystem sync` in a hook or a CI step would\n      // otherwise be told nothing, forever, about a file it can never repair —\n      // and `loam validate --all` would go on reporting `subsystem.views-stale`\n      // for that path with this very command named as the fix.\n      if (views.action === \"refused\" || services.action === \"refused\") process.exitCode = 1;\n    };\n    const generated = [views.write, services.write].filter((write) => write !== null);\n    if (generated.length === 0 && plan.gaps.length === 0 && plan.strays.length === 0 && exclude.write === null) {\n      say();\n      return;\n    }\n    const writes: PlannedWrite[] = [...generated];\n    // `planWrite` marks a non-existent target exclusive — a no-clobber create\n    // that fails EEXIST rather than replacing a file another writer landed in\n    // the same instant. That IS the create-only rule, enforced by the write\n    // path rather than by the `existsSync` the predicate already ran: a file\n    // that appears between the check and the swap is somebody's, and stays.\n    for (const gap of plan.gaps) {\n      writes.push(planWrite(gap.path, renderServiceProject(gap.service.id, LIKEC4_ROOT_PROJECT)));\n    }\n    // The one file this verb DELETES, and it rides the same journal as the rest,\n    // so a run killed mid-swap is rolled forward rather than half-done.\n    // `content: null` is the delete the views file already uses.\n    for (const stray of plan.strays) writes.push({ path: stray.path, content: null });\n    // The root project's `exclude`, in the SAME transaction as the files it\n    // decides the fate of: a run that wrote the per-service projects and died\n    // before the exclude would leave a tree where the renderer loads a\n    // standalone model twice — once in the root project, where every kind it\n    // declares is a duplicate — which is worse than either end state.\n    if (exclude.write !== null) writes.push(exclude.write);\n    // One lock, one journal, one commit for both kinds of file — a sync killed\n    // between the views swap and the project creates would otherwise leave a\n    // half-state no later run could tell from a team's deliberate deletion.\n    const staged = await stageWrites(writes);\n    const committed = await commitStaged(\n      { root: docsDir, command: \"subsystem\", rerun: \"loam subsystem sync\", target: \"subsystems\" },\n      staged,\n      \"synced\",\n    );\n    if (!committed.ok) {\n      fail(json, committed.code, committed.message);\n      return;\n    }\n    say();\n  } finally {\n    await opened.release();\n  }\n}\n\n/**\n * What this run will do to ONE generated file: the action to report, and the\n * write to stage (or null for \"leave it alone\").\n *\n * ONE function for both generated files, because the rule is one rule and a\n * second spelling of it would be a second chance for `subsystems.likec4` and\n * `services.likec4` to answer differently about the same map. Past the two\n * vetoes below, the compare is `planGenerated` (`./txn/views.ts`), the one the\n * tree-changing verbs make too, which says why it is over CONTENT, not bytes.\n *\n * `blocked` is the map's veto and it is the whole reason `known` is threaded\n * this far. The render cannot be trusted against a file that already exists when\n * `architecture/` does not parse as one project: without the element join and\n * the style census, `subsystems.likec4` is a title and a description — writing\n * it would take the `include` lines, the boundary comment and the palette\n * reference off a file whose only fault is a sibling document that does not\n * parse — and `services.likec4` is NOTHING AT ALL, because every one of its\n * views is gated on a service resolving to a map element, so the tolerant render\n * would delete the whole file. An absent file is not protected: there is nothing\n * to lose and a fleet being scaffolded must still get its first one.\n *\n * `refused` is the OTHER veto and it comes from the file rather than from the\n * map: a file at one of these reserved paths that does not open with loam's mark\n * was written by somebody, and this command writes both files whole. It is\n * checked first, applies to both files through one predicate, and is the one\n * answer here that makes the run exit non-zero — see `runSync`.\n */\nasync function planFile(file: ExpectedFile, known: boolean): Promise<{ action: SyncAction; write: PlannedWrite | null }> {\n  // ONE read for both questions — what the file says, and whose it is. The\n  // predicate and the reader live beside the mark itself\n  // (`core/repo/tree/render/service/header.ts`), below every writer of these two\n  // paths, because sync is one of FIVE and was for a while the only one holding\n  // the line.\n  const { text: actual, authored } = await readGeneratedFile(file.path);\n  // OWNERSHIP FIRST, before the map's veto and before the compare, because it is\n  // the one question whose wrong answer destroys work. Both of these are\n  // filenames loam RESERVES inside a directory the team owns, and every arm\n  // below writes the whole file or deletes it: a docs repo that already kept a\n  // hand-authored diagram at one of them would have lost it on the first sync\n  // after the upgrade that reserved the name, silently, breaking the promise the\n  // rest of the tree keeps (archive's verbatim splice: authored bytes stay\n  // authored). So the file is asked who wrote it. An EDIT of a generated file\n  // still carries the mark and is still loam's to repair — that is the whole\n  // point of `subsystem.views-stale` — and only a file that never carried it is\n  // somebody else's. Absent is not refused: there is nothing to lose.\n  if (authored) return { action: \"refused\", write: null };\n  if (!known && actual !== null) return { action: \"blocked\", write: null };\n  return planGenerated(file, actual);\n}\n\n/**\n * What the project half of this run owes, from ONE predicate. `surveyProjects`\n * is the shared spelling of \"has a model, a legal id, and no file\", and it\n * hands back the sizes of the two domains it counted against — every model it\n * walked, and the standalone models a file is owed for — so `current` is a\n * subtraction rather than a second reading of the same two paths. A loop here\n * re-spelling \"has a model\" was the drift the shared predicate exists to\n * prevent, and it would have kept counting a directory the survey had\n * skipped. Without the root file the gaps are real but stay unfilled —\n * writing them would promise a renderer nobody can open — and `current` is 0\n * because \"already had a file\" is only a fact about a workspace that exists.\n */\nfunction planProjects(\n  docsDir: DocsDir,\n  services: readonly WalkedService[],\n  shapes: ReadonlyMap<string, ModelShape>,\n): ProjectPlan {\n  const root = existsSync(rootProjectPath(docsDir));\n  // A model that EXTENDS the map is owed no file, and the survey is where that\n  // is decided — one predicate for the writer and the grader, so `validate --all`\n  // can never name a gap this run would not fill. An unreadable model classifies\n  // as standalone (`readModelShapes`), which is the conservative arm: it gets a\n  // project file, which is what every model got before shapes existed.\n  const survey = surveyProjects(services, serviceRenderPaths, (model) => shapes.get(resolve(model)) !== \"extending\");\n  if (!root) return { root, gaps: [], strays: [], current: 0, modelled: survey.modelled, models: survey.models };\n  return {\n    root,\n    gaps: survey.gaps,\n    // The removal is gated on the root file for the same reason the create is:\n    // without it the docs root is not a LikeC4 workspace, so nothing there is\n    // claiming anything out of a root project that does not exist, and deleting\n    // a team's file over a renderer nobody can open is a writer acting on a\n    // hazard it cannot see.\n    strays: survey.strays,\n    // Over the STANDALONE domain, which is the one `gaps` was drawn from: a\n    // model that extends the map is owed no file, so it can neither be a gap nor\n    // \"already have one\", and subtracting from `modelled` counted every\n    // extending model as the latter.\n    current: survey.standalone - survey.gaps.length,\n    modelled: survey.modelled,\n    models: survey.models,\n  };\n}\n"]}

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

@@ -10,7 +10,10 @@
  * 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
@@ -22,6 +25,12 @@ export function reportSync(json, out) {
             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: {
@@ -53,6 +62,7 @@ export function reportSync(json, out) {
         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)
@@ -63,11 +73,16 @@ export function reportSync(json, out) {
 /** 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 three writers landed something beside a current views
-    // file: a project file created, one removed, or the root `exclude` rewritten.
-    // The third was missed when it was added, so the tail contradicted the very
-    // next line of output (verification 2026-09-04, review C).
-    const quiet = out.projects.created.length === 0 && out.projects.removed.length === 0 && !out.projects.exclude.updated;
+    // 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).`,
@@ -76,9 +91,44 @@ function views(out) {
         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) {

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

@@ -1 +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;AAG1D,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAiDvD,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,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,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,2EAA2E;IAC3E,8EAA8E;IAC9E,4EAA4E;IAC5E,2DAA2D;IAC3D,MAAM,KAAK,GACT,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC;IAC1G,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;KACtF,CAAC;IACF,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC9B,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 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 */\nexport type SyncAction = \"current\" | \"created\" | \"updated\" | \"removed\" | \"blocked\";\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  action: 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      ...(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  // 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 three writers landed something beside a current views\n  // file: a project file created, one removed, or the root `exclude` rewritten.\n  // The third was missed when it was added, so the tail contradicted the very\n  // next line of output (verification 2026-09-04, review C).\n  const quiet =\n    out.projects.created.length === 0 && out.projects.removed.length === 0 && !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  };\n  return sentence[out.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"]}
+{"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"]}