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

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

@@ -0,0 +1 @@
+{"version":3,"file":"subsystem.js","sourceRoot":"","sources":["../../../src/commands/subsystem/subsystem.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAU,CAAC;AAGlF,4FAA4F;AAC5F,MAAM,KAAK,GAA8D;IACvE,GAAG,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,+FAA+F,EAAE;IAC/H,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,yCAAyC,EAAE;IACjF,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,8BAA8B,EAAE;IACjE,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,qBAAqB,EAAE;IACpD,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE;IACjD,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,0BAA0B,EAAE;IAC9D,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE;CAClD,CAAC;AAEF,4FAA4F;AAC5F,SAAS,UAAU,CAAC,IAAU,EAAE,IAAsB;IACpD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,6BAA6B,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;IACzG,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,+BAA+B,KAAK,CAAC,IAAI,CAAC,KAAK,iBAAiB,CAAC;IACxH,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI;QAC1B,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC;QACvB,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC;QACvB,CAAC,eAAe,EAAE,IAAI,CAAC,WAAW,CAAC;QACnC,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC;KACf,EAAE,CAAC;QACX,IAAI,KAAK,KAAK,SAAS,IAAI,IAAI,KAAK,KAAK;YAAE,OAAO,GAAG,IAAI,sBAAsB,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IACrG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,OAAO;SACJ,OAAO,CAAC,WAAW,CAAC;SACpB,WAAW,CAAC,iFAAiF,CAAC;SAC9F,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;SACrC,QAAQ,CAAC,YAAY,EAAE,oDAAoD,CAAC;SAC5E,MAAM,CAAC,eAAe,EAAE,0EAA0E,CAAC;SACnG,MAAM,CAAC,gBAAgB,EAAE,yDAAyD,CAAC;SACnF,MAAM,CAAC,gBAAgB,EAAE,0DAA0D,CAAC;SACpF,MAAM,CAAC,sBAAsB,EAAE,gDAAgD,CAAC;SAChF,MAAM,CAAC,gBAAgB,EAAE,wDAAwD,CAAC;SAClF,MAAM,CAAC,QAAQ,EAAE,qDAAqD,CAAC;SACvE,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,KAAe,EAAE,IAAsB,EAAE,EAAE;QACtE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;QAChC,IAAI,CAAE,KAA2B,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACjD,yEAAyE;YACzE,IAAI,CAAC,IAAI,EAAE,gBAAgB,EAAE,iBAAiB,IAAI,gBAAgB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACxF,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAY,CAAC,CAAC;QAClC,IAAI,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;YACzD,IAAI,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,IAAI,WAAW,KAAK,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,GAAG,aAAa,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;YACjI,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,UAAU,CAAC,IAAY,EAAE,IAAI,CAAC,CAAC;QAC9C,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC;YACrC,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO;QAC5B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAC3B,uEAAuE;QACvE,sEAAsE;QACtE,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC;YAAE,OAAO;QACtD,IAAI,CAAC;YACH,QAAQ,IAAY,EAAE,CAAC;gBACrB,KAAK,KAAK;oBACR,OAAO,MAAM,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;gBACtD,KAAK,MAAM;oBACT,OAAO,MAAM,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,IAAK,EAAE,IAAI,CAAC,CAAC;gBACzD,KAAK,QAAQ;oBACX,OAAO,MAAM,SAAS,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,KAAK,CAAC,CAAC,CAAE,CAAC,EAAE,IAAI,CAAC,CAAC;gBAChE,KAAK,IAAI;oBACP,OAAO,MAAM,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,IAAI,CAAC,CAAC;gBAC/C,KAAK,MAAM;oBACT,OAAO,MAAM,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;gBACtC,KAAK,SAAS;oBACZ,OAAO,MAAM,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,IAAI,CAAC,CAAC;gBACpD,KAAK,MAAM;oBACT,OAAO,MAAM,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,CAAC,GAAG,YAAY,wBAAwB,CAAC;gBAAE,MAAM,GAAG,CAAC;YAC1D,mBAAmB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC","sourcesContent":["/**\n * `loam subsystem <verb>` — the command surface over the tree under\n * `services/`.\n *\n * ONE registration with the verbs dispatched inside the action, deliberately\n * NOT Commander subcommands: test/agents.test.ts counts the literal\n * command-registration calls across src/commands/ and asserts the count\n * equals `buildProgram()`'s command list, so nested subcommands would\n * register as one command while counting as many literals — the guard would\n * fail in a way that reads as unrelated. (That same scan is why this comment\n * never spells the registration call with its parenthesis.) The option\n * superset is declared here once; the arity table below refuses a flag on a\n * verb that does not read it, because a silently ignored `--into` is a move\n * that did not happen.\n */\nimport type { Command } from \"commander\";\nimport { configOrRefuse, fail } from \"../../core/envelope/json.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { docsRepoReady, reportDocsRepoError } from \"../policy/gate.js\";\nimport { runNew, runRm } from \"./edit.js\";\nimport { runMove, runRename } from \"./move.js\";\nimport { runHistory, runList } from \"./query.js\";\nimport { runSync } from \"./sync.js\";\n\nexport interface SubsystemOptions {\n  into?: string;\n  under?: string;\n  title?: string;\n  description?: string;\n  owner?: string;\n  json?: boolean;\n}\n\nconst VERBS = [\"new\", \"move\", \"rename\", \"rm\", \"list\", \"history\", \"sync\"] as const;\ntype Verb = (typeof VERBS)[number];\n\n/** How many names each verb takes, spelled once so the refusals agree with the dispatch. */\nconst NAMES: Record<Verb, { min: number; max: number; usage: string }> = {\n  new: { min: 1, max: 1, usage: \"subsystem new <name> [--under <sub>] [--title <text>] [--description <text>] [--owner <name>]\" },\n  move: { min: 1, max: Infinity, usage: \"subsystem move <name>... --into <sub|.>\" },\n  rename: { min: 2, max: 2, usage: \"subsystem rename <old> <new>\" },\n  rm: { min: 1, max: 1, usage: \"subsystem rm <name>\" },\n  list: { min: 0, max: 0, usage: \"subsystem list\" },\n  history: { min: 1, max: 1, usage: \"subsystem history <name>\" },\n  sync: { min: 0, max: 0, usage: \"subsystem sync\" },\n};\n\n/** The flag/verb contradictions worth refusing: an ignored flag is a lie about what ran. */\nfunction flagMisuse(verb: Verb, opts: SubsystemOptions): string | null {\n  if (opts.into !== undefined && verb !== \"move\") return `--into belongs to 'move' (${NAMES.move.usage}).`;\n  if (opts.into === undefined && verb === \"move\") return `'move' needs a destination: ${NAMES.move.usage} ('.' unfiles).`;\n  for (const [flag, value] of [\n    [\"--under\", opts.under],\n    [\"--title\", opts.title],\n    [\"--description\", opts.description],\n    [\"--owner\", opts.owner],\n  ] as const) {\n    if (value !== undefined && verb !== \"new\") return `${flag} belongs to 'new' (${NAMES.new.usage}).`;\n  }\n  return null;\n}\n\nexport function registerSubsystem(program: Command): void {\n  program\n    .command(\"subsystem\")\n    .description(\"Manage the subsystem tree under services/ — the grouping no identity depends on\")\n    .argument(\"<verb>\", VERBS.join(\" | \"))\n    .argument(\"[names...]\", \"the subsystem or service names the verb applies to\")\n    .option(\"--into <name>\", \"move: the destination subsystem, or '.' for the services/ root (unfiled)\")\n    .option(\"--under <name>\", \"new: the parent subsystem (default: the services/ root)\")\n    .option(\"--title <text>\", \"new: the subsystem's human title, kept in subsystem.yaml\")\n    .option(\"--description <text>\", \"new: what the group is, kept in subsystem.yaml\")\n    .option(\"--owner <name>\", \"new: who answers for the group, kept in subsystem.yaml\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (verb: string, names: string[], opts: SubsystemOptions) => {\n      const json = opts.json === true;\n      if (!(VERBS as readonly string[]).includes(verb)) {\n        // The same code `list` gives a bad section: one mistake class, one code.\n        fail(json, \"invalid-option\", `Unknown verb '${verb}'. Expected: ${VERBS.join(\" | \")}.`);\n        return;\n      }\n      const arity = NAMES[verb as Verb];\n      if (names.length < arity.min || names.length > arity.max) {\n        fail(json, \"invalid-option\", `'${verb}' takes ${arity.min === arity.max ? arity.min : `${arity.min}+`} name(s): ${arity.usage}`);\n        return;\n      }\n      const misuse = flagMisuse(verb as Verb, opts);\n      if (misuse !== null) {\n        fail(json, \"invalid-option\", misuse);\n        return;\n      }\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n      const { docsDir } = config;\n      // \"services\": every verb reads or rewrites the tree that IS the fleet,\n      // so a docsDir with no services/ is a refusal, never an empty answer.\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n      try {\n        switch (verb as Verb) {\n          case \"new\":\n            return await runNew(docsDir, names[0]!, opts, json);\n          case \"move\":\n            return await runMove(docsDir, names, opts.into!, json);\n          case \"rename\":\n            return await runRename(docsDir, [names[0]!, names[1]!], json);\n          case \"rm\":\n            return await runRm(docsDir, names[0]!, json);\n          case \"list\":\n            return await runList(docsDir, json);\n          case \"history\":\n            return await runHistory(docsDir, names[0]!, json);\n          case \"sync\":\n            return await runSync(docsDir, json);\n        }\n      } catch (err) {\n        if (!(err instanceof DocsRepoUnavailableError)) throw err;\n        reportDocsRepoError(json, err);\n      }\n    });\n}\n"]}

package/dist/commands/subsystem/sync.js

@@ -0,0 +1,318 @@
+/**
+ * `loam subsystem sync` — the writer of everything under the tree that exists
+ * only to be RENDERED, which is the renderer's reading of the tree twice over:
+ *
+ *  - `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. 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
+ *    one: measured at the 1.59.2 pin, that nested project claims the model out of
+ *    the root project and the fleet loses the service's interior
+ *    (`core/repo/tree/render/projects.ts` carries the measurement). This is the
+ *    repair `service.likec4-config-stray` has always named and, until now, did
+ *    not perform.
+ *  - the ROOT `likec4.config.json`'s `exclude` list, and ONLY that key. Derived
+ *    from the shapes on disk on every run and rewritten when it differs, because
+ *    the two shapes need opposite answers from it: a standalone model must be
+ *    excluded (inside the root project every kind it declares is a duplicate)
+ *    and an extending model must not be (the root project is the only place it
+ *    parses). `planExclude` below states the gate that keeps an old repository
+ *    untouched, and `core/c4/service-model/renderer.ts` states which half of the
+ *    list is loam's and which is the team's. One entry loam did NOT write is
+ *    taken anyway, and only this one: an entry naming a directory that HIDES an
+ *    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 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
+ * would fight them, and a rewrite would take them. `core/repo/tree/render/projects.ts`
+ * records the measurement behind the file and the naming rule; here, presence
+ * is the one question asked of it, through the SAME predicate `validate --all`
+ * grades with (`missingProjects`), so the grader can never name a gap this
+ * writer would not fill.
+ *
+ * Nothing under `services/` is written, and no `exclude` is recomputed, unless
+ * the ROOT `likec4.config.json` exists. Without it the tree is not a loadable
+ * workspace at all — every model would merge into one project and report every
+ * declaration as a duplicate — and a nested project beside a missing root is a
+ * promise about a renderer that cannot be opened. `loam doctor` prints the root
+ * file; sync says so and writes nothing for the services until it is there.
+ *
+ * Every write goes through the same lock + journaled transaction every docs
+ * writer uses (`commitStaged`), and both kinds land in ONE commit: a
+ * predecessor's interrupted commit is recovered first and a sync killed
+ * mid-swap is rolled forward by the next writer. Idempotent by construction:
+ * the expected views bytes are a pure function of the tree, and a project
+ * file, once present, is never a gap again — so a second run reports
+ * `current` and writes nothing.
+ *
+ * The expected views bytes come from `./txn/views.ts` — the same module every
+ * writer verb renders from, so sync and the transactions cannot disagree
+ * about what the file should say. The subsystem verbs' own commit window
+ * (`./txn/txn.ts`) does NOT write project files, and records why. What this run
+ * SAYS it did is `./txn/report.ts`: the third answer about the same three files,
+ * and the phase that is not part of the commit.
+ */
+import { existsSync } from "node:fs";
+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 } 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 { 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 { 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, planGenerated } from "./txn/views.js";
+export async function runSync(docsDir, json) {
+    // 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 {
+        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 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
+        // the two shapes (`core/repo/tree/render/projects.ts`).
+        const shapes = await readModelShapes(tree.services.map((svc) => serviceRenderPaths(svc.dir).model));
+        const plan = planProjects(docsDir, tree.services, shapes);
+        const exclude = plan.root ? await planExclude(docsDir, tree.services, plan.models) : NO_EXCLUDE;
+        // The plan IS the report: every gap is created and every stray removed in
+        // the one commit below, and the early return is the branch where both lists
+        // are empty.
+        const projects = () => ({
+            root: plan.root,
+            // SORTED BY PATH, which is what the contract says these keys hold and what
+            // the survey's own order is not: `surveyProjects` sorts by service id, so
+            // `services/svc-a/…` came out before `services/platform/svc-d/…` and a
+            // consumer told the list was "sorted" got an order no path sort produces
+            // (re-verification 2026-09-04, area C item 6). The text view prints the
+            // same array, so the two orders cannot drift apart.
+            created: plan.gaps.map((gap) => repoPath(docsDir, gap.path)).sort(),
+            removed: plan.strays.map((stray) => repoPath(docsDir, stray.path)).sort(),
+            current: plan.current,
+            modelled: plan.modelled,
+            exclude,
+        });
+        // `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 = [...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
+        // path rather than by the `existsSync` the predicate already ran: a file
+        // that appears between the check and the swap is somebody's, and stays.
+        for (const gap of plan.gaps) {
+            writes.push(planWrite(gap.path, renderServiceProject(gap.service.id, LIKEC4_ROOT_PROJECT)));
+        }
+        // The one file this verb DELETES, and it rides the same journal as the rest,
+        // so a run killed mid-swap is rolled forward rather than half-done.
+        // `content: null` is the delete the views file already uses.
+        for (const stray of plan.strays)
+            writes.push({ path: stray.path, content: null });
+        // The root project's `exclude`, in the SAME transaction as the files it
+        // decides the fate of: a run that wrote the per-service projects and died
+        // before the exclude would leave a tree where the renderer loads a
+        // standalone model twice — once in the root project, where every kind it
+        // declares is a duplicate — which is worse than either end state.
+        if (exclude.write !== null)
+            writes.push(exclude.write);
+        // One lock, one journal, one commit for both kinds of file — a sync killed
+        // between the views swap and the project creates would otherwise leave a
+        // half-state no later run could tell from a team's deliberate deletion.
+        const staged = await stageWrites(writes);
+        const committed = await commitStaged({ root: docsDir, command: "subsystem", rerun: "loam subsystem sync", target: "subsystems" }, staged, "synced");
+        if (!committed.ok) {
+            fail(json, committed.code, committed.message);
+            return;
+        }
+        say();
+    }
+    finally {
+        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
+ * hands back the sizes of the two domains it counted against — every model it
+ * walked, and the standalone models a file is owed for — so `current` is a
+ * subtraction rather than a second reading of the same two paths. A loop here
+ * re-spelling "has a model" was the drift the shared predicate exists to
+ * prevent, and it would have kept counting a directory the survey had
+ * skipped. Without the root file the gaps are real but stay unfilled —
+ * writing them would promise a renderer nobody can open — and `current` is 0
+ * because "already had a file" is only a fact about a workspace that exists.
+ */
+function planProjects(docsDir, services, shapes) {
+    const root = existsSync(rootProjectPath(docsDir));
+    // A model that EXTENDS the map is owed no file, and the survey is where that
+    // is decided — one predicate for the writer and the grader, so `validate --all`
+    // can never name a gap this run would not fill. An unreadable model classifies
+    // as standalone (`readModelShapes`), which is the conservative arm: it gets a
+    // project file, which is what every model got before shapes existed.
+    const survey = surveyProjects(services, serviceRenderPaths, (model) => shapes.get(resolve(model)) !== "extending");
+    if (!root)
+        return { root, gaps: [], strays: [], current: 0, modelled: survey.modelled, models: survey.models };
+    return {
+        root,
+        gaps: survey.gaps,
+        // The removal is gated on the root file for the same reason the create is:
+        // without it the docs root is not a LikeC4 workspace, so nothing there is
+        // claiming anything out of a root project that does not exist, and deleting
+        // a team's file over a renderer nobody can open is a writer acting on a
+        // hazard it cannot see.
+        strays: survey.strays,
+        // Over the STANDALONE domain, which is the one `gaps` was drawn from: a
+        // model that extends the map is owed no file, so it can neither be a gap nor
+        // "already have one", and subtracting from `modelled` counted every
+        // extending model as the latter.
+        current: survey.standalone - survey.gaps.length,
+        modelled: survey.modelled,
+        models: survey.models,
+    };
+}
+//# sourceMappingURL=sync.js.map

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

@@ -0,0 +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. 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/exclude.js

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

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

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