@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/dist/commands/subsystem/sync.js

@@ -1,103 +1,318 @@
 /**
- * `loam subsystem sync` — the ONE repair for `subsystem.views-stale`:
- * recompute the generated views file from the tree, write it when it
- * differs, remove it when the tree has no subsystems, and say which.
+ * `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:
  *
- * The write goes through the same lock + journaled transaction every docs
- * writer uses (`commitStaged`), so 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 bytes are a pure function
- * of the tree and the committed landscape, so a second run reports `current`
- * and writes nothing.
+ *  - `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.
  *
- * The expected bytes come from `./txn/views.ts` — the same module every
+ * 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.
+ * 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 { readFile } from "node:fs/promises";
-import { emitJson, fail } from "../../core/envelope/json.js";
-import { subsystemViewsPath } from "../../core/repo/paths.js";
+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 { InterruptedCommitError } from "../../core/staging/interrupted.js";
-import { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from "../../core/staging/lock.js";
-import { recoverInterruptedCommit } from "../../core/staging/recovery/recover.js";
+import { LOCK_WAIT_MS } from "../../core/staging/lock.js";
+import { openCommitWindow } from "../../core/staging/recovery/recover.js";
 import { commitStaged } from "../../core/staging/txn/transaction.js";
-import { viewsAgree } from "../../core/repo/tree/views.js";
-import { expectedViews } from "./txn/views.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) {
-    let releaseLock;
-    try {
-        releaseLock = await acquireDocsLockWaiting(docsDir, LOCK_WAIT_MS);
-    }
-    catch (err) {
-        if (!(err instanceof DocsBusyError))
-            throw err;
-        fail(json, "docs-busy", err.message);
+    // A predecessor's journal is recovered (or refused) before the tree is
+    // read: the views file itself may be the half-written one.
+    const opened = await openCommitWindow(docsDir, LOCK_WAIT_MS);
+    if (!opened.ok) {
+        fail(json, opened.code, opened.message);
         return;
     }
+    const { recovered } = opened;
     try {
-        // A predecessor's journal is recovered (or refused) before the tree is
-        // read: the views file itself may be the half-written one.
-        let recovered;
-        try {
-            recovered = await recoverInterruptedCommit(docsDir);
-        }
-        catch (err) {
-            if (!(err instanceof InterruptedCommitError))
-                throw err;
-            fail(json, "commit-interrupted", err.message);
-            return;
-        }
         const tree = await listFleetTree(docsDir);
+        // BOTH generated files, from ONE read of the map — `./txn/views.ts` says why
+        // the pair is one answer and why the parsed document, never a literal, is
+        // what the per-service peer sets are computed from.
         const expected = await expectedViews(docsDir, tree);
-        const path = subsystemViewsPath(docsDir);
-        const expectedBytes = expected === null ? null : Buffer.from(expected, "utf8");
-        // Content, not bytes: `viewsAgree` records why, beside the generator. A
-        // Windows clone hands this file back CRLF with not one fact changed, and a
-        // byte compare made `sync` answer `updated` and rewrite it LF — after which
-        // git shows the file permanently modified and the next checkout puts the
-        // CRLF back. `validate` stopped demanding that rewrite; `sync` must stop
-        // offering it, or the two disagree about the same file.
-        const actual = existsSync(path) ? await readFile(path, "utf8") : null;
-        if (viewsAgree(actual, expected)) {
-            report(json, { action: "current", subsystems: tree.subsystems.length, recovered });
+        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 action = actual === null ? "created" : expectedBytes === null ? "removed" : "updated";
-        const staged = await stageWrites([{ path, content: expectedBytes }]);
+        const writes = [...generated];
+        // `planWrite` marks a non-existent target exclusive — a no-clobber create
+        // that fails EEXIST rather than replacing a file another writer landed in
+        // the same instant. That IS the create-only rule, enforced by the write
+        // 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;
         }
-        report(json, { action, subsystems: tree.subsystems.length, recovered });
+        say();
     }
     finally {
-        await releaseLock();
+        await opened.release();
     }
 }
-function report(json, out) {
-    if (json) {
-        emitJson({
-            command: "subsystem",
-            path: "architecture/subsystems.likec4",
-            action: out.action,
-            subsystems: out.subsystems,
-            ...(out.recovered === null ? {} : { recovered: out.recovered }),
-        });
-        return;
-    }
-    if (out.recovered !== null && out.recovered.outcome !== "consistent") {
-        console.log(`note: recovered an interrupted \`loam ${out.recovered.command}\` commit first (${out.recovered.outcome}).`);
-    }
-    const sentence = {
-        current: `architecture/subsystems.likec4 is current (${out.subsystems} subsystem(s)) — nothing to write.`,
-        created: `wrote architecture/subsystems.likec4 — ${out.subsystems} subsystem view(s).`,
-        updated: `updated architecture/subsystems.likec4 — ${out.subsystems} subsystem view(s).`,
-        removed: `removed architecture/subsystems.likec4 — the tree has no subsystems, so the generated file must be absent.`,
+/**
+ * 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,
     };
-    console.log(sentence[out.action]);
 }
 //# sourceMappingURL=sync.js.map

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

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

package/dist/commands/subsystem/txn/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