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

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,23 +29,39 @@
  * 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";
-import { acquireDocsLock, DocsBusyError } from "../../../core/staging/lock.js";
-import { recoverInterruptedCommit } from "../../../core/staging/recovery/recover.js";
+import {} from "../../../core/staging/interrupted.js";
+import { openCommitWindow } from "../../../core/staging/recovery/recover.js";
 import { commitStaged } from "../../../core/staging/txn/transaction.js";
 import {} from "../../../core/staging/writes.js";
-import { viewsAgree } from "../../../core/repo/tree/render/views.js";
-import { expectedViews, LANDSCAPE_UNREADABLE_NOTE } from "./views.js";
-/** The text tail a verb's success line carries about the generated file. */
+import { authoredGeneratedPaths, authoredRefusal } from "../../../core/repo/tree/render/service/header.js";
+import { expectedViews, LANDSCAPE_UNREADABLE_NOTE, planGenerated } from "./views.js";
+/** The text tail a verb's success line carries about the generated files — one clause per file that moved. */
 export function reportViews(views) {
-    return 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.
@@ -50,43 +69,81 @@ export function reportViews(views) {
  * staged and nothing is written.
  */
 export async function commitWindow(docsDir, json, plan) {
-    let releaseLock;
-    try {
-        releaseLock = await acquireDocsLock(docsDir);
-    }
-    catch (err) {
-        if (!(err instanceof DocsBusyError))
-            throw err;
-        fail(json, "docs-busy", err.message);
+    // Refuse-fast (0), as archive takes the lock: two concurrent verbs answer
+    // `docs-busy` rather than queue behind each other.
+    const opened = await openCommitWindow(docsDir, 0);
+    if (!opened.ok) {
+        fail(json, opened.code, opened.message);
         return;
     }
+    const { recovered } = opened;
     try {
-        let recovered;
-        try {
-            recovered = await recoverInterruptedCommit(docsDir);
-        }
-        catch (err) {
-            if (!(err instanceof InterruptedCommitError))
-                throw err;
-            fail(json, "commit-interrupted", err.message);
-            return;
-        }
         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.content === null ? null : Buffer.from(expected.content, "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.content)) {
-            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,
@@ -114,7 +171,26 @@ export async function commitWindow(docsDir, json, plan) {
             console.log(LANDSCAPE_UNREADABLE_NOTE);
     }
     finally {
-        await releaseLock();
+        await opened.release();
     }
 }
+/**
+ * Compare ONE generated file against what it must say, append the write when
+ * they differ, and name what happened. The compare is `planGenerated`'s, the
+ * one `../sync.ts` makes too — `./views.ts` says why it is over CONTENT, not
+ * bytes, and why there is one spelling of it.
+ *
+ * `protect` is the caller's statement that a NULL render is not evidence: the
+ * file is left exactly as it is rather than deleted. It is never a licence to
+ * skip a real rewrite — a file loam can render is rendered, which is the
+ * difference between this window and `../sync.ts`'s `blocked`.
+ */
+async function stageGenerated(file, writes, protect) {
+    const current = existsSync(file.path) ? await readFile(file.path, "utf8") : null;
+    const planned = planGenerated(file, current);
+    if (planned.write === null || (protect && file.content === null))
+        return "current";
+    writes.push(planned.write);
+    return planned.action;
+}
 //# sourceMappingURL=txn.js.map

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

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

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

@@ -1,20 +1,32 @@
 /**
- * What the generated views file MUST say — the shared answer every subsystem
- * writer and `subsystem sync` render from. A module beneath the verbs (in the
- * txn/ subpackage) because the commit window and sync both consume it, and a
- * second spelling of "what should the views say" would be a second chance to
- * disagree with `validate`'s staleness check.
+ * What the generated views files MUST say — the shared answer every subsystem
+ * writer and `subsystem sync` render from, and the one compare both make against
+ * it (`planGenerated`). A module beneath the verbs (in the txn/ subpackage)
+ * because the commit window and sync both consume it, and a second spelling of
+ * "what should the views say" would be a second chance to disagree with
+ * `validate`'s staleness check.
+ *
+ * BOTH generated files come out of ONE read of the map, and that is the reason
+ * this module answers about the pair rather than about one file: they are
+ * rendered from the same parsed `architecture/` project, they are repaired by
+ * the same command, and they must land in the same commit — a verb that changed
+ * a service's placement changed a subsystem view's members AND that service's
+ * overview TITLE (`<subsystem path> / <service id>`), so shipping one without
+ * the other is the "stale between two commits" state the generated files'
+ * contract exists to refuse. Reading the project twice would also parse the
+ * whole fleet map twice per run for one answer.
  */
 import { existsSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 import { loadFile } from "../../../core/c4/likec4.js";
 import { architectureProjectDocuments, loadArchitecture } from "../../../core/c4/project/architecture.js";
 import { serviceDirOf } from "../../../core/kernel/ids/dirs.js";
-import { landscapePath } from "../../../core/repo/paths.js";
-import { renderSubsystemViews } from "../../../core/repo/tree/render/views.js";
+import { landscapePath, serviceViewsPath, subsystemViewsPath } from "../../../core/repo/paths.js";
+import { renderServiceOverviews, renderSubsystemViews, viewsAgree, } from "../../../core/repo/tree/render/views.js";
 /**
- * The elements and declared global style ids of the whole `architecture/`
- * PROJECT — the member join, and the one line a view may borrow a palette
+ * The elements, the relationships and the declared global style ids of the whole
+ * `architecture/` PROJECT — the member join, the edges every per-service view
+ * computes its peer set from, and the one line a view may borrow a palette
  * with — with the provenance of that answer beside it.
  *
  * The PROJECT, not the landscape file alone, and that is a correctness rule
@@ -54,8 +66,11 @@ import { renderSubsystemViews } from "../../../core/repo/tree/render/views.js";
  */
 export async function landscapeFacts(docsDir) {
     const path = landscapePath(docsDir);
+    // No map at all: no elements and NO EDGES, said outright. `relationships` is
+    // required of every `MapFacts` precisely so an empty answer has to be written
+    // down rather than dropped — see the type.
     if (!existsSync(path))
-        return { facts: { elements: [] }, known: true };
+        return { facts: { elements: [], relationships: [] }, known: true };
     try {
         const doc = await loadArchitecture(docsDir);
         // The whole document on success, so the render reads the same record
@@ -81,7 +96,23 @@ export async function landscapeFacts(docsDir) {
         // cannot merge them (that is what failed one line up), but a document that
         // parses alone certainly declares the style groups it declares.
         if (file.errors.length === 0) {
-            return { facts: { elements: file.elements, globalStyles: await declaredStyles(docsDir, file) }, known: false };
+            // THE LANDSCAPE'S OWN RELATIONSHIPS TRAVEL WITH ITS ELEMENTS. This arm
+            // composes a record rather than handing the document across, because the
+            // style census below is widened past what this one document declares — and
+            // the first version of it listed the fields it happened to be thinking
+            // about and dropped the edges the document was carrying all along. That is
+            // silent: every per-service view then renders with no peers, the service
+            // and its own interior and nothing it touches, and no check anywhere says
+            // so. `MapFacts` now REQUIRES the field for exactly this reason; the copy
+            // stays explicit so the widening above it stays visible.
+            return {
+                facts: {
+                    elements: file.elements,
+                    relationships: file.relationships,
+                    globalStyles: await declaredStyles(docsDir, file),
+                },
+                known: false,
+            };
         }
     }
     catch {
@@ -127,9 +158,48 @@ async function declaredStyles(docsDir, landscape) {
     }
     return [...ids].sort();
 }
+/**
+ * Compare ONE generated file against what it must say: the write when they
+ * differ, and what that write is. Both writers of these files — `../sync.ts`'s
+ * `planFile` and the verbs' `stageGenerated` (`./txn.ts`) — put their own veto
+ * in front of this and nothing else, because the rule is one rule, and a second
+ * spelling of it would be a second chance for the two writers to answer
+ * differently about the same file.
+ *
+ * The compare is over CONTENT, not bytes: `viewsAgree` records why, beside the
+ * generator. A Windows clone hands a generated file back CRLF with not one fact
+ * changed, and a byte compare made `sync` answer `updated` and rewrite it LF —
+ * after which git shows the file permanently modified and the next checkout puts
+ * the CRLF back — and folded the same rewrite into every subsystem move's
+ * transaction and journal. `validate` stopped demanding that rewrite; the
+ * writers must stop offering it, or they disagree about the same file. What gets
+ * WRITTEN is still the LF render as a Buffer, so the decode is a comparison only.
+ */
+export function planGenerated(file, current) {
+    if (viewsAgree(current, file.content))
+        return { action: "current", write: null };
+    const bytes = file.content === null ? null : Buffer.from(file.content, "utf8");
+    return {
+        action: current === null ? "created" : bytes === null ? "removed" : "updated",
+        write: { path: file.path, content: bytes },
+    };
+}
 export async function expectedViews(docsDir, tree) {
     const read = await landscapeFacts(docsDir);
-    return { known: read.known, content: renderSubsystemViews(tree, read.facts ?? { elements: [] }) };
+    // The parsed DOCUMENT goes across, never a literal composed here: `MapFacts`
+    // carries the relationships the per-service peer sets are computed from, and a
+    // caller that dropped them would render every service view peerless — the
+    // service and its interior, and nothing it touches — with no error anywhere.
+    // The type now REQUIRES the field so that mistake cannot be made silently
+    // (`render/views.ts` records what it cost); this last-resort literal is the one
+    // place an empty answer is the TRUE one — loam could not read the map at
+    // all — and it says so rather than leaving the field off.
+    const map = read.facts ?? { elements: [], relationships: [] };
+    return {
+        known: read.known,
+        subsystems: { path: subsystemViewsPath(docsDir), content: renderSubsystemViews(tree, map) },
+        services: { path: serviceViewsPath(docsDir), content: renderServiceOverviews(tree, map) },
+    };
 }
 /**
  * The one line a person is owed when the map cannot be read — the same sentence

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

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

package/dist/commands/tasks/render.js

@@ -0,0 +1,116 @@
+/** How many units one service shows before the rest are elided behind its own lens. */
+const PER_SERVICE_LIMIT = 12;
+/** `path:line`, or just the path — a source with no line is still worth opening. */
+function at(unit) {
+    const source = unit.source;
+    if (source === undefined)
+        return "";
+    return source.line === undefined ? ` (${source.path})` : ` (${source.path}:${source.line})`;
+}
+function line(unit) {
+    return `    [${unit.at}] ${unit.kind}  ${unit.claim}${at(unit)}`;
+}
+export function renderPacket(packet) {
+    console.log(`${packet.feature} — ${packet.counts.open} open · ${packet.counts.done} done · ${packet.counts.attested} attested`);
+    console.log(`  record: ${packet.record} · stamps: ${packet.stamps}${packet.service === null ? "" : ` · lens: ${packet.service}`}`);
+    // The blind spots FIRST, and before any list: an empty packet over a document
+    // nobody could read is the one output an implementer must never take at face
+    // value, and a warning under fifty lines of units is a warning nobody reads.
+    for (const warning of blindSpots(packet))
+        console.log(`  ⚠ ${warning}`);
+    console.log("");
+    const subjects = [...new Set(packet.units.map((unit) => unit.subject))];
+    if (packet.units.length === 0) {
+        console.log(packet.counts.attested > 0 || packet.counts.done > 0
+            ? "  Nothing open. Every unit is recorded confirmed, or attested and waiting on a run."
+            : "  Nothing open — this feature's delta, specs and contracts promise nothing yet.");
+    }
+    for (const subject of subjects) {
+        const units = packet.units.filter((unit) => unit.subject === subject);
+        console.log(`  ${subject}`);
+        for (const unit of units.slice(0, PER_SERVICE_LIMIT))
+            console.log(line(unit));
+        if (units.length > PER_SERVICE_LIMIT) {
+            console.log(`    +${units.length - PER_SERVICE_LIMIT} more — loam tasks ${packet.feature} --service ${subject} --json`);
+        }
+        console.log("");
+    }
+    if (packet.frontier.length > 0) {
+        console.log(`  frontier: ${packet.frontier.join(", ")}${packet.frontierElided > 0 ? ` (+${packet.frontierElided})` : ""}`);
+    }
+    for (const waiting of packet.waitingOn ?? []) {
+        console.log(`  waiting on ${waiting.subject}: ${waiting.id}  ${waiting.claim}`);
+    }
+    console.log("\n  Review:");
+    for (const note of packet.review)
+        console.log(`    - ${note}`);
+}
+/**
+ * The leaf, in full. The follow-up command is literal rather than a shape to
+ * fill in, because the reader is usually a model cheap enough that "the
+ * appropriate verify invocation" is a guess it will get wrong.
+ */
+export function renderNext(packet) {
+    const unit = packet.units[0];
+    if (unit === undefined) {
+        console.log(`${packet.feature} — nothing open (${packet.counts.done} done · ${packet.counts.attested} attested)`);
+        console.log(`  record: ${packet.record} · stamps: ${packet.stamps}`);
+        for (const warning of blindSpots(packet))
+            console.log(`  ⚠ ${warning}`);
+        return;
+    }
+    console.log(`${packet.feature} — next: ${unit.id}`);
+    for (const warning of blindSpots(packet))
+        console.log(`  ⚠ ${warning}`);
+    console.log("");
+    console.log(`  [${unit.at}] ${unit.kind}  [${unit.subject}]`);
+    console.log(`  ${unit.claim}`);
+    const source = unit.source;
+    if (source !== undefined) {
+        console.log(`  ${source.path}${source.line === undefined ? "" : `:${source.line}`}`);
+        // Verbatim, never reflowed: these are the bytes the scenario digest was
+        // taken over, and a test written from reworded criteria answers a claim
+        // nobody made.
+        if ("lines" in source)
+            for (const body of source.lines)
+                console.log(`    ${body}`);
+    }
+    if (unit.dependsOn.length > 0)
+        console.log(`  depends on: ${unit.dependsOn.join(", ")}`);
+    console.log(`\n  done: ${unit.done.check}`);
+    console.log(`\n  ${followUp(packet.feature, unit)}`);
+}
+/**
+ * The command that closes this unit.
+ *
+ * A `describe` unit is the one arm that is NOT a `loam verify --record`: there
+ * is no claim to answer, because a requirement with no scenario asks no
+ * question — the work is writing the Given/When/Then into the file named above,
+ * and `loam validate --feature` is what grades that it landed. Pointing it at
+ * `--record` would invite an answer to a question the checklist does not carry.
+ */
+function followUp(feature, unit) {
+    if (unit.at === "describe")
+        return `loam validate --feature ${feature}`;
+    if (unit.at === "generate")
+        return `loam gherkin ${feature}`;
+    if (unit.kind === "scenario.tested") {
+        return `loam verify ${feature} --service ${unit.subject} --results report.json`;
+    }
+    return `loam verify ${feature} --record answers.json --service ${unit.subject}`;
+}
+/** What the packet could not look at — one sentence per document class. */
+function blindSpots(packet) {
+    const out = [];
+    if (packet.unreadable.architecture !== undefined) {
+        out.push(`delta.likec4 does not parse (${packet.unreadable.architecture}) — no c4.calls unit could be derived, ` +
+            "so this list is short because loam could not look, not because the work is done");
+    }
+    const contracts = packet.unreadable.contracts;
+    if (contracts !== undefined) {
+        out.push(`contract delta unreadable for ${contracts.join(", ")} — operations and messages are missing from this packet, ` +
+            "not absent from the feature");
+    }
+    return out;
+}
+//# sourceMappingURL=render.js.map