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

package/CHANGELOG.md

@@ -10,6 +10,52 @@ case for a change — the alternative that was rejected, the defect it came from
 generalises — lives where it is maintained: [SCHEMA.md](SCHEMA.md) for the rule,
 [ROADMAP.md](ROADMAP.md) for the priority and its exit criteria, and the commit that landed it._
 
+## [0.2.0-alpha.5] - 2026-09-03
+
+An adopted service's model renders from the docs root. Still a prerelease on the `alpha` line:
+`npm i @ybotok/loam@alpha` installs it. Nothing below is breaking. What a repo with adopted services
+NOTICES: one `service.likec4-config-missing` warning per service on its first `validate --all`
+until one `loam subsystem sync`, and from that sync on `--project` for `likec4 validate` at the
+docs root.
+
+### Added — an adopted service's model renders from the docs root
+
+The root `likec4.config.json` excludes `services/**`, and has to; what that cost was never stated:
+an adopted service's `model.likec4` — the artifact `loam adopt` spends the most effort on — was a
+box on the fleet map with nothing renderable inside it in the renderer opened at the docs root, and
+the only documented way to see its containers was one `npx likec4 start services/<id>` per service.
+One problem report; one file per service closes it.
+
+- `loam subsystem sync` now writes `services/<…>/<svc>/likec4.config.json` beside every service
+  `model.likec4` that has none, whenever the root `likec4.config.json` exists — **create-only**: a
+  file that exists is yours and is never compared, rewritten or removed. Measured at the pinned
+  likec4, a project file inside a service directory registers the model as a project of its own
+  regardless of the root's exclusion, so `npx likec4 start` at the docs root shows `fleet` plus one
+  project per service. Without the root file nothing is written and the text says `loam doctor`
+  prints it. `subsystem sync --json` carries an additive `projects` key, `{ root, created, current }`
+  — whether the root file exists, the repo-relative paths written this run (sorted by id), and how
+  many model-bearing services already had one. `action` still describes
+  `architecture/subsystems.likec4` alone.
+- `loam validate --all` gains one warning per service, `service.likec4-config-missing`, on the
+  `landscape` target with the service's tree path as its `scope`: `model.likec4` exists and the
+  project file does not. Never an error, never gating, never in `--service`, `status` or `doctor`;
+  the fix is `loam subsystem sync`, never a hand-written file. `doctor.likec4-config-missing`'s fix
+  text now hands over to `sync` once the root file is written.
+- The project name: the id with every `.` folded to `-` (LikeC4's name grammar refuses the byte),
+  prefixed `service-` when that would equal the root project's `fleet` or LikeC4's reserved
+  `default`; `title` is the id verbatim, and the title is what the renderer's picker shows. Not
+  injective — an id spelled billing.core beside one spelled billing-core, or `service-fleet` beside
+  `fleet` — and LikeC4 suffixes the later one `-1`; disclosed, never graded.
+
+What a repo NOTICES on upgrade: one warning per adopted service on the first `validate --all` until
+one `loam subsystem sync` — under `--strict`, CI is red until then; after that `sync`, N untracked
+files (`sync` does not `git add` them) and `move-uncommitted` on the next `loam subsystem move` of
+such a service until they are committed; from the first `sync` on, `likec4 validate` at the docs
+root needs `--project <name>` (measured: with more than one project it refuses bare, while
+`likec4 build` and `likec4 export` take every project and need no flag); and the renderer's project
+list grows by one per adopted service, beside `fleet`. No command, flag, exit code or envelope key
+changes; `projects` is additive.
+
 ## [0.2.0-alpha.4] - 2026-09-03
 
 The view title becomes the subsystem's path. `0.2.0-alpha.3` was tagged and **never published** — it

package/MIGRATING-from-OpenSpec.md

@@ -312,7 +312,10 @@ services, loam frontmatter, Operations/Covers links and feature identity still r
   specs intentionally remain `status: draft`.
 - `Operations:` links to provider OpenAPI `operationId`s, and `Covers:` links where architecture
   requirements are created.
-- `architecture/landscape.likec4`, service `model.likec4`, and explicit fleet relationships.
+- `architecture/landscape.likec4`, service `model.likec4`, and explicit fleet relationships — then
+  `loam subsystem sync`, which writes each model's `likec4.config.json` (the staged repo already
+  carries the root one) so the models render beside the map; `validate --all` warns
+  `service.likec4-config-missing` for any model still without one.
 - Service OpenAPI contracts and provider-before-consumer sequencing where inbound edges already name
   operations.
 - LikeC4 and OpenAPI deltas for the already mapped active feature ids (`FEAT-12`, `BUG-42`, and so

package/README.md

@@ -5,13 +5,14 @@
 ![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
 ![node: >=22.22.3](https://img.shields.io/badge/node-%3E%3D22.22.3-brightgreen.svg)
 [![CI](https://github.com/ybotok/loam/actions/workflows/ci.yml/badge.svg)](https://github.com/ybotok/loam/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/@ybotok/loam.svg)](https://www.npmjs.com/package/@ybotok/loam)
+[![npm](https://img.shields.io/npm/v/@ybotok/loam/alpha.svg?label=npm%20alpha)](https://www.npmjs.com/package/@ybotok/loam)
 
-> **Pre-release: `0.2.0-alpha.4`**, the third published release of the 0.2 line and the newest published
+> **Pre-release: `0.2.0-alpha.5`**, the fourth published release of the 0.2 line and the newest published
 > version of [`@ybotok/loam`](https://www.npmjs.com/package/@ybotok/loam). It publishes under the
-> `alpha` npm dist-tag: `npm i @ybotok/loam@alpha`, or the exact version, always installs this
-> line. `latest` is moved onto a release by hand once it has published, so a plain
-> `npm i @ybotok/loam` may still resolve to `0.1.0-beta.3` until it is. See [Status](#status).
+> `alpha` npm dist-tag — which is what the badge above reads: `npm i @ybotok/loam@alpha`, or the
+> exact version, always installs this line. `latest` is moved onto a release by hand once it has
+> published, so a plain `npm i @ybotok/loam` resolves to an earlier release until it is moved. See
+> [Status](#status).
 
 `loam` keeps an authored C4 model, requirements, API and event contracts, permissions, domain
 vocabulary and verification evidence in explicit agreement as a system changes. The same lifecycle
@@ -486,7 +487,7 @@ always preserved byte for byte, with the entry printed for manual merge.
   maps, what is lost, what must be added.
 - [ROADMAP.md](ROADMAP.md) — the evidence-backed improvement plan, priorities, non-goals and exit
   criteria.
-- [CHANGELOG.md](CHANGELOG.md) — released beta.1–alpha.4 plus the changes on `main` under
+- [CHANGELOG.md](CHANGELOG.md) — released beta.1–alpha.5 plus the changes on `main` under
   `[Unreleased]`.
 - [docs/BENCHMARKS.md](https://github.com/ybotok/loam/blob/main/docs/BENCHMARKS.md) — what a
   fleet-sized run costs, with the method, the machine and the committed runs behind every number.
@@ -520,14 +521,14 @@ component baselines, the `architecture/permissions.yaml` authorization vocabular
 authored-capability axes with the `Realizes:` join, use cases graded as `dynamic view`s, the
 `glossary/<term>.md` domain vocabulary checked through the links that cite it, and the
 `architecture/obligations.yaml` architectural obligations checked through `#obl-` tags and
-`Covers:`. Known limits, each with its owner in [ROADMAP.md](ROADMAP.md): the complete gate still
-needs repeatable CI and installed-package evidence observed from an actual push. Speculative
-`render`, health composition and UI generation come later. Behind that status stand **157 test files** (counted 2026-09-02): the count is graded
+`Covers:`. Known limits, each with its owner in [ROADMAP.md](ROADMAP.md): the scheduled CI
+`stability` job has still to be observed green. Speculative `render`, health composition and UI
+generation come later. Behind that status stand **159 test files** (counted 2026-09-02): the count is graded
 against a live readdir by `test/docs-facts.test.ts`, so this sentence fails the suite the moment it
 trails the tree.
 
 The package is published as [`@ybotok/loam`](https://www.npmjs.com/package/@ybotok/loam), currently
-`0.2.0-alpha.4`: the unscoped `loam` name is taken by an unrelated GDAL wrapper, so the package ships
+`0.2.0-alpha.5`: the unscoped `loam` name is taken by an unrelated GDAL wrapper, so the package ships
 under the maintainer's own npm user scope. Releases are tag-driven and maintainer-only
 ([CONTRIBUTING.md](CONTRIBUTING.md)); the version this line names is pinned to `package.json` by a
 drift test, so it cannot silently trail a release.

package/ROADMAP.md

@@ -18,27 +18,30 @@ acceptance tests, and implementation evidence remain ordinary files in repositor
 state inside a service. The CLI is small enough to audit, and every writer — not only archive — now
 commits through a locked, journaled transaction that a crash cannot leave half-applied.
 
-The tree contains **427 TypeScript modules in 130 source packages**, with an acyclic package graph
+The tree contains **429 TypeScript modules in 130 source packages**, with an acyclic package graph
 checked by
 [scripts/package-graph.mjs](https://github.com/ybotok/loam/blob/main/scripts/package-graph.mjs). The
 CLI exposes **29 commands** from [src/cli.ts](https://github.com/ybotok/loam/blob/main/src/cli.ts),
-and the suite stands at **157 test files**. Those four counts are deliberately stated OUTSIDE the
+and the suite stands at **159 test files**. Those four counts are deliberately stated OUTSIDE the
 dated snapshot below: each derives from the tree in one readdir, so
 [test/docs-facts.test.ts](https://github.com/ybotok/loam/blob/main/test/docs-facts.test.ts) grades
 them live and this paragraph cannot quietly trail the code the way its predecessor did.
 
-_Measured 2026-09-03 at `0.2.0-alpha.4`, and dated because neither number has a cheap derivation:_
+_Measured 2026-09-03 at `0.2.0-alpha.5`, and dated because neither number has a cheap derivation:_
 lint, typecheck, `npm run arch:check` and `npm run meta:check` green; `npm test` passing
-**3,410/3,410 tests**, with two `skipIf(asRoot)` cases the root gate container cannot run; the
-coverage gate passing with **92.26% statements, 84.06% branches, 96.62% functions, and 94.20%
+**3,434/3,434 tests**, with two `skipIf(asRoot)` cases the root gate container cannot run; the
+coverage gate passing with **92.30% statements, 84.11% branches, 96.64% functions, and 94.24%
 lines** against its thresholds of 91 / 82 / 95 / 93; and `npm run release:check` plus
 `npm run test:package` green against the real tarball.
 
-One qualification remains, and it is observation rather than code: nothing has been pushed since the
-CI `stability` job and the tarball-reading package smoke landed, so repeatable CI executions — the
-stability job seen green, and the installed-package smoke run from a pushed commit — are still
-release evidence to collect, even though the gate-stress proof passed locally on its landing tree
-and the smoke passes locally against the real tarball. The runner class recorded on 2026-08-18 is
+Most of that qualification is now closed by observation rather than by code. Measured 2026-09-03 on
+pushed commits: `ci` at `1de7c97` green — `test` on Node 22.22.3 and 24, and the installed-package
+`package` job on ubuntu (both Node lines) and windows — and the `release` workflow on tag
+`v0.2.0-alpha.4` green end to end, `release-gate` (lint, typecheck, coverage, the packed candidate,
+the smoke of that exact candidate, `release:check`) followed by `publish`, which put the tarball on
+npm under the `alpha` dist-tag. What is left is one job: `stability` is SKIPPED on a push — it runs
+on the weekly schedule and on dispatch — so it is still release evidence to collect, even though the
+gate-stress proof passes locally. The runner class recorded on 2026-08-18 is
 still the reading to apply to a red of that shape: a restricted filesystem sandbox that denies `tsx`
 its local IPC socket fails only the
 [test/cli-entry.test.ts](https://github.com/ybotok/loam/blob/main/test/cli-entry.test.ts) cases with
@@ -103,12 +106,15 @@ has landed (see [Recently landed](#recently-landed)) — the authored business a
 axis, and as of 2026-09-02 the deployment axis, which is the first item this file ever wrote
 directly into this section rather than promoting from [Later](#later--promote-only-from-evidence).
 
-### Release evidence, unchanged
+### Release evidence — one job left
 
-What is left is the one thing this file cannot close by writing code, and it stays
-where it is rather than being promoted for the shape of it: the CI `stability` job and the
-installed-package smoke have still to be OBSERVED green from a pushed commit. That is release
-evidence to collect, not an improvement to make.
+What is left is the one thing this file cannot close by writing code, and it stays where it is
+rather than being promoted for the shape of it. The installed-package half closed on 2026-09-03:
+the `package` job ran green on a pushed commit across three runner/Node combinations, and the whole
+publication path ran green on tag `v0.2.0-alpha.4`. The CI `stability` job has still to be OBSERVED
+green — it is skipped on a push and runs on the weekly schedule — so it is still release evidence to
+collect, not an improvement to make. `workflow_dispatch` is the way to collect it deliberately
+rather than waiting for Monday.
 
 An item returns to this section from [Later](#later--promote-only-from-evidence) when fleet evidence
 names its operator, repeated task, failure mode, frequency, current workaround and measurable
@@ -125,6 +131,52 @@ changes, exit criteria, and what each review surfaced — are in this file's his
 working tree and not committed, and the range goes in with the commit rather than being guessed at
 here.
 
+#### The service model, renderable from the fleet root
+
+**Landed 2026-09-03**, from one problem report. The root `likec4.config.json` that
+`loam init --create` writes excludes `services/**` on purpose — every `model.likec4` declares its
+own `specification` block, and a renderer merging the tree calls each one a duplicate — and the
+cost of that exclusion had gone unstated for a release: the model `loam adopt` spends the most
+effort on was a box with nothing inside it in the renderer opened at the docs root, and the only
+documented path to its containers was one renderer invocation per service directory. The report's
+hand-written workaround, one project file per service, is what this entry makes loam's.
+
+**Measured** at the pinned likec4 before a line was written. A `services/<svc>/likec4.config.json`
+is registered as a project of its own even though the root excludes the directory: the workspace
+loads `fleet` plus one project per service with zero errors, the root project sees exactly the
+files it saw before, and each service project carries an auto `index` view of the containers beside
+the authored view. A nested project named `fleet` is silently registered as `fleet-1`. With more
+than one project, `likec4 validate` at the root refuses with `Specify exact project` until given
+`--project`. A nested project holding no `.likec4` file is silently absent from the project list. A
+service model that does not parse breaks only its own project; siblings and `fleet` still compute.
+And the project picker shows `title ?? id`, so the title is what a human reads.
+
+**What landed.** `loam subsystem sync` writes the file — create-only, two keys, bytes a function of
+the id alone — beside every service model that has none, once the root project file exists, and
+reports them under an additive `projects` key. `loam validate --all` grades presence with one
+warning per service, `service.likec4-config-missing`, whose fix is `sync`. No new command: the
+[Later](#later--promote-only-from-evidence) Rendering row's evidence bar was met for the SCOPING
+half of its trigger and answered by wiring — one file that tells the renderer where a project is —
+not by a drawing verb; drawing stays LikeC4's, and the row says so now.
+
+**Rejected.** A new command, because the report's problem was a missing file, not a missing verb,
+and a verb would have put loam between a team and its renderer for good. The agent writing the file
+from the adopt brief, because a file written by hand per service is the state the report found —
+one of four adopted services had one — and loam already writes the root file and knows every
+service directory. A generated-and-compared file with a `-stale` grade, because the bytes cannot go
+stale and a compare would fight the `title` and styles LikeC4 lets a team add. Grading in `doctor`
+alone, because the gap is per service and `doctor` reports on the repository, not on its services;
+the docs repo's CI runs `validate --all`.
+
+**Costs**, each where a user meets it. A repo with adopted services reports one warning per service
+on its first `validate --all` after upgrading, until one `sync`; that `sync` leaves N untracked
+files it does not `git add`; from the first service project on, `likec4 validate` at the docs root
+needs `--project <name>` (`build` and `export` take every project without one — measured); the
+renderer's project list grows by one per adopted service, and a fleet-map box is not a link into
+that project (LikeC4 projects are separate models); and the project name is not injective (an id spelled billing.core beside one spelled
+billing-core, `service-fleet` beside `fleet`), disclosed in SCHEMA rather than escaped away,
+because the picker shows the id.
+
 #### The generated subsystem views — a label, a boundary, and one reader of the map
 
 **Landed 2026-09-03.** Three problem reports from a fleet running loam, one axis. The generated
@@ -365,7 +417,9 @@ item gets promoted — it went from here to `## Now` and from there to
   invocation, scoping, or artifact reproducibility is the recurring problem, and it must stay
   outside validation so view computation cannot slow or change the gate. This item is about
   **drawing**, and LikeC4 keeps that job. Reading a `dynamic view`'s declared steps is not rendering
-  and is not this item — see docs/DESIGN.md rule 26.
+  and is not this item — see docs/DESIGN.md rule 26. The scoping half of that bar was met and
+  answered on 2026-09-03 by the per-service project file `loam subsystem sync` writes (see
+  [Recently landed](#recently-landed)) — wiring rather than a verb; drawing stays LikeC4's.
 - **UI generation:** begin with a disposable projection over the stable JSON contract only after CLI
   consumers demonstrate a repeated navigation problem. It must not introduce a second mutable state,
   hidden workflow state, or a required service.

package/SCHEMA.md

@@ -72,6 +72,7 @@ docs/
   glossary/<term>.md                 the system's domain vocabulary, one file per term; nesting allowed [authored, opt-in]
   services/<svc>/                    at the root (unfiled), or inside subsystem directories at any depth
     model.likec4                        boundary C4 (containers/components) [adopt]
+    likec4.config.json                  one LikeC4 project per service model, create-only  [GENERATED: loam subsystem sync]
     spec.md                          living requirements (Requirement/Scenario)  [adopt]
     arch.spec.md                     living ARCHITECTURE requirements (outbox, retries, alerts; Covers:)  [authored]
     openapi.yaml                     API contract                        [adopt / authored]
@@ -204,6 +205,44 @@ does not parse standalone (its `include` lines reference elements the landscape
 holds **static** views, whose contents loam never reads in any document. Only the LikeC4 renderer,
 which merges the whole `architecture/` project, resolves its includes.
 
+The tree's **second renderer file** is per service — `services/<…>/<svc>/likec4.config.json`,
+which `loam subsystem sync` also writes, beside every `model.likec4` that has none. The root
+project is scoped to `architecture/` and excludes `services/**`, and must be, since each model
+declares its own `specification` block; what that exclusion cost went unstated for a release: an
+adopted service was a box on the fleet map with nothing renderable inside it. Measured at the
+pinned likec4, a project file INSIDE a service directory is registered as a project of its own
+regardless of that exclusion, so one `npx likec4 start` at the docs root loads `fleet` plus one
+project per service, each carrying LikeC4's own `index` view of the containers beside the authored
+one, and a model that does not parse breaks only its own project. The file is **create-only** —
+never compared, never rewritten, never removed — under the root config's ownership rule, not the
+views file's: there is no `-stale` grade because nothing can make it stale. Its bytes are a
+function of the id alone (two keys, `name` and `title`), so placement never changes them and a
+`subsystem move` carries the file with no write of its own — it rides inside the rename the move's
+transaction already journals (in a git-backed repo, commit the files `sync` wrote first: `move`
+refuses over untracked paths, `move-uncommitted`); a compare would only fight the keys LikeC4 lets a
+team add (`title`, styles). `name` is the id with every
+`.` folded to `-` (LikeC4's name grammar refuses the byte; loam's id grammar admits it), prefixed
+`service-` when the result would equal the root project's `fleet` (a nested project of that name
+is silently registered as `fleet-1`) or LikeC4's reserved `default`; `title` is the id verbatim,
+and the title is what the renderer's project picker shows. The name is **not injective**, and
+that is disclosed rather than escaped away: an id spelled billing.core beside a service literally
+named billing-core, or `service-fleet` beside `fleet`, share a name and LikeC4 suffixes the later
+one `-1`; no loam
+finding grades it, because the picker still reads the id. Order is a gate — the root file first
+(`loam init --create` writes it, `loam doctor` prints it), then `sync`: without the root file
+nothing is written and the text output says so. No model, no file: a spec-only service is owed
+nothing and gets its file on the first `sync` after its model lands. No legal id, no file either: a
+directory whose name breaks the service-id grammar (`service.id-invalid`) would get a `name` the
+renderer silently drops, and a create-only file the renderer ignores would silence the grade for
+good, so `sync` skips it and the rename that clears `service.id-invalid` earns the file. A file left behind by a
+deleted model is the team's and harmless (measured: a nested project holding no `.likec4` file is
+absent from the project list). `validate --all` grades presence only — one warning per service,
+`service.likec4-config-missing`, on the fleet `landscape` target, never an error, never in
+`--service`, `status` or `doctor`; the fix is `loam subsystem sync`, never a hand-written file. A
+feature's `delta.likec4` is deliberately out of scope: the directory is transient and
+`loam archive` moves it where a project file would still be registered, so every shipped feature
+would keep a dead project in the list forever.
+
 A move is **one journaled transaction over N directory renames plus the regenerated views file**
 (`loam subsystem move <name>... --into <sub|.>`; `rename` is a one-rename move; whole subtrees move
 as one rename). It refuses only when git reports uncommitted changes under a directory being moved
@@ -2295,9 +2334,17 @@ through the forge, not through loam features:
   **parsed** model and never computes a view — it reads what a view **declares** (a `dynamic view`'s
   tags and ordered steps, already materialized by the parse loam pays for) and never what a view
   **shows**. It renders nothing, and view *computation* is what is superlinear in edges. (If you
-  want diagrams, add a `views` block and render it with LikeC4's own tooling — `npx likec4 start` in
-  the docs repo for the fleet map, `npx likec4 start services/<id>` for one service model — and
-  scope the views, because an `include *` over a fleet-sized landscape takes minutes. `loam init`
+  want diagrams, add a `views` block and render it with LikeC4's own tooling — `npx likec4 start`
+  at the docs root, which renders the fleet map AND every adopted service's model, each as the
+  project its own `services/<svc>/likec4.config.json` declares (written by `loam subsystem sync`;
+  the Layout section has the rule), and `npx likec4 start features/<FEAT>` for a delta, which is
+  transient and gets no project — and scope the views, because an `include *` over a fleet-sized
+  landscape takes minutes. Two costs arrive with the first service project. Measured at the
+  pinned likec4: with more than one project, `likec4 validate` at the docs root refuses without
+  `--project <name>`, so a CI step that ran it bare changes (`likec4 build` and `likec4 export` take
+  every project and need no flag). And the renderer's project list grows by one per adopted service
+  beside `fleet` — LikeC4 projects are separate models, so a box on the fleet map is not a link into
+  that service's project. `loam init`
   scaffolds the landscape with no `views` block for that reason: loam should not plant a diagram it
   never draws **— and never asks for one: a fleet that draws nothing owes no views block.** It also
   scaffolds a `likec4.config.json` that scopes the root LikeC4 project to `architecture/`: loam
@@ -2556,9 +2603,9 @@ component-surface pins), `verify`,
 transactional `archive` / `unarchive`, `vouch`, and the OpenSpec audit/migration on-ramp are
 implemented, each with a `--json` contract.
 
-Known and unclosed, so nobody has to discover them: the complete gate still needs repeatable CI and
-installed-package evidence observed from an actual push, even though behavior, coverage and the
-local stress runner pass. Both contract axes now merge a components-only delta: a feature
+Known and unclosed, so nobody has to discover them: the scheduled CI `stability` job has still to be
+observed green, even though behavior, coverage, the installed-package smoke and the local stress
+runner all pass. Both contract axes now merge a components-only delta: a feature
 asyncapi.yaml declaring no channel/operation/message slot (`components.schemas`-only, say) merges
 the component surfaces it declares, pinned by the root `x-loam-baselines` record, and they enter the
 ref sweep like anything else the merge wrote — so a `$ref` whose target the delta itself defines

package/dist/commands/subsystem/sync.js

@@ -1,29 +1,58 @@
 /**
- * `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. The ONE repair for `subsystem.views-stale`.
+ *  - `services/<…>/<id>/likec4.config.json`, one LikeC4 project file beside
+ *    every `model.likec4`. CREATE-ONLY: never compared, never rewritten, never
+ *    removed.
  *
- * The expected bytes come from `./txn/views.ts` — the same module every
+ * The two rules differ because the two files answer to different owners. The
+ * views file is a pure function of the tree and the committed landscape, so
+ * every byte of it is loam's and a hand edit is by definition stale. The
+ * 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.
+ *
+ * The project files are written only when 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.
  */
 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 { emitJson, fail, repoPath } from "../../core/envelope/json.js";
+import { LIKEC4_ROOT_PROJECT, rootProjectPath, serviceRenderPaths, subsystemViewsPath, } 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 { commitStaged } from "../../core/staging/txn/transaction.js";
+import { planWrite } from "../../core/staging/writes.js";
 import { viewsAgree } from "../../core/repo/tree/render/views.js";
 import { expectedViews } from "./txn/views.js";
 export async function runSync(docsDir, json) {
@@ -61,23 +90,71 @@ export async function runSync(docsDir, json) {
         // 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 agree = viewsAgree(actual, expected);
+        const plan = planProjects(docsDir, tree.services);
+        const projects = (created) => ({
+            root: plan.root,
+            created,
+            current: plan.current,
+            modelled: plan.modelled,
+        });
+        if (agree && plan.gaps.length === 0) {
+            report(json, { action: "current", subsystems: tree.subsystems.length, recovered, projects: projects([]) });
             return;
         }
-        const action = actual === null ? "created" : expectedBytes === null ? "removed" : "updated";
-        const staged = await stageWrites([{ path, content: expectedBytes }]);
+        // `action` still describes the views file alone: a run that only created
+        // project files answers `current` for it, exactly as before the projects
+        // existed, so nothing reading the key sees a new meaning.
+        const action = agree
+            ? "current"
+            : actual === null
+                ? "created"
+                : expectedBytes === null
+                    ? "removed"
+                    : "updated";
+        const writes = agree ? [] : [{ path, content: expectedBytes }];
+        // `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)));
+        }
+        // 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 });
+        const created = plan.gaps.map((gap) => repoPath(docsDir, gap.path));
+        report(json, { action, subsystems: tree.subsystems.length, recovered, projects: projects(created) });
     }
     finally {
         await releaseLock();
     }
 }
+/**
+ * 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 size of the domain it counted against, 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) {
+    const root = existsSync(rootProjectPath(docsDir));
+    const survey = surveyProjects(services, serviceRenderPaths);
+    if (!root)
+        return { root, gaps: [], current: 0, modelled: survey.modelled };
+    return { root, gaps: survey.gaps, current: survey.modelled - survey.gaps.length, modelled: survey.modelled };
+}
 function report(json, out) {
     if (json) {
         emitJson({
@@ -86,18 +163,32 @@ function report(json, out) {
             action: out.action,
             subsystems: out.subsystems,
             ...(out.recovered === null ? {} : { recovered: out.recovered }),
+            projects: { root: out.projects.root, created: out.projects.created, current: out.projects.current },
         });
         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 wrote = out.projects.created.length;
+    // "nothing to write" is a claim about the whole run, and it is false the
+    // moment a project file landed beside a current views file.
     const sentence = {
-        current: `architecture/subsystems.likec4 is current (${out.subsystems} subsystem(s)) — nothing to write.`,
+        current: `architecture/subsystems.likec4 is current (${out.subsystems} subsystem(s))${wrote === 0 ? " — 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.`,
     };
     console.log(sentence[out.action]);
+    if (wrote > 0) {
+        console.log(`wrote ${wrote} services/<…>/likec4.config.json — one LikeC4 project per service model, create-only ` +
+            "(a file that already exists is yours and is never touched; commit the new ones before a " +
+            "`loam subsystem move`, which refuses over untracked paths). With more than one project, " +
+            "likec4 validate at the docs root needs --project <name>; build and export take every project.");
+    }
+    if (!out.projects.root && out.projects.modelled > 0) {
+        console.log("note: no likec4.config.json at the docs root, so no service project files were written — " +
+            "`loam doctor` prints the root file.");
+    }
 }
 //# 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/render/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. The ONE repair for `subsystem.views-stale`.\n *  - `services/<…>/<id>/likec4.config.json`, one LikeC4 project file beside\n *    every `model.likec4`. CREATE-ONLY: never compared, never rewritten, never\n *    removed.\n *\n * The two rules differ because the two files answer to different owners. The\n * views file is a pure function of the tree and the committed landscape, so\n * every byte of it is loam's and a hand edit is by definition stale. The\n * project file's bytes are a function of the service id ALONE — the identity\n * no verb ever changes — so nothing can make it stale, and the keys LikeC4\n * lets a team add to it (`title`, styles, a contact) are the team's; a compare\n * would fight them, and a rewrite would take them. `core/repo/tree/render/projects.ts`\n * records the measurement behind the file and the naming rule; here, presence\n * is the one question asked of it, through the SAME predicate `validate --all`\n * grades with (`missingProjects`), so the grader can never name a gap this\n * writer would not fill.\n *\n * The project files are written only when the ROOT `likec4.config.json` exists.\n * Without it the tree is not a loadable workspace at all — every model would\n * merge into one project and report every declaration as a duplicate — and a\n * nested project beside a missing root is a promise about a renderer that\n * cannot be opened. `loam doctor` prints the root file; sync says so and\n * 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.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { emitJson, fail, repoPath } from \"../../core/envelope/json.js\";\nimport {\n  LIKEC4_ROOT_PROJECT,\n  rootProjectPath,\n  serviceRenderPaths,\n  subsystemViewsPath,\n} from \"../../core/repo/paths.js\";\nimport { listFleetTree } from \"../../core/repo/repo.js\";\nimport { type ProjectGap, renderServiceProject, surveyProjects } from \"../../core/repo/tree/render/projects.js\";\nimport type { WalkedService } from \"../../core/repo/tree/walk.js\";\nimport { stageWrites } from \"../../core/staging/commit.js\";\nimport { type CommitRecovery, InterruptedCommitError } from \"../../core/staging/interrupted.js\";\nimport { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { recoverInterruptedCommit } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { planWrite, type PlannedWrite } from \"../../core/staging/writes.js\";\nimport { viewsAgree } from \"../../core/repo/tree/render/views.js\";\nimport { expectedViews } from \"./txn/views.js\";\n\n/** What one sync did to the views file — and ONLY that file; the projects report separately. */\ntype SyncAction = \"current\" | \"created\" | \"updated\" | \"removed\";\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  /** Model-bearing services that ALREADY had a file; 0 whenever `root` is false. */\n  current: number;\n  /** Model-bearing services, root or no root — what the root-missing note is owed to. */\n  modelled: number;\n}\n\n/** The additive `projects` payload key, and what the text lines are composed from. */\ninterface ProjectsReport {\n  root: boolean;\n  /** Repo-relative POSIX paths written this run, sorted by id. */\n  created: string[];\n  current: number;\n  modelled: number;\n}\n\nexport async function runSync(docsDir: DocsDir, json: boolean): Promise<void> {\n  let releaseLock: () => Promise<void>;\n  try {\n    releaseLock = await acquireDocsLockWaiting(docsDir, LOCK_WAIT_MS);\n  } catch (err) {\n    if (!(err instanceof DocsBusyError)) throw err;\n    fail(json, \"docs-busy\", err.message);\n    return;\n  }\n  try {\n    // A predecessor's journal is recovered (or refused) before the tree is\n    // read: the views file itself may be the half-written one.\n    let recovered: CommitRecovery | null;\n    try {\n      recovered = await recoverInterruptedCommit(docsDir);\n    } catch (err) {\n      if (!(err instanceof InterruptedCommitError)) throw err;\n      fail(json, \"commit-interrupted\", err.message);\n      return;\n    }\n\n    const tree = await listFleetTree(docsDir);\n    const expected = await expectedViews(docsDir, tree);\n    const path = subsystemViewsPath(docsDir);\n    const expectedBytes = expected === 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    const agree = viewsAgree(actual, expected);\n    const plan = planProjects(docsDir, tree.services);\n    const projects = (created: string[]): ProjectsReport => ({\n      root: plan.root,\n      created,\n      current: plan.current,\n      modelled: plan.modelled,\n    });\n    if (agree && plan.gaps.length === 0) {\n      report(json, { action: \"current\", subsystems: tree.subsystems.length, recovered, projects: projects([]) });\n      return;\n    }\n    // `action` still describes the views file alone: a run that only created\n    // project files answers `current` for it, exactly as before the projects\n    // existed, so nothing reading the key sees a new meaning.\n    const action: SyncAction = agree\n      ? \"current\"\n      : actual === null\n        ? \"created\"\n        : expectedBytes === null\n          ? \"removed\"\n          : \"updated\";\n    const writes: PlannedWrite[] = agree ? [] : [{ path, content: expectedBytes }];\n    // `planWrite` marks a non-existent target exclusive — a no-clobber create\n    // that fails EEXIST rather than replacing a file another writer landed in\n    // the same instant. That IS the create-only rule, enforced by the write\n    // path rather than by the `existsSync` the predicate already ran: a file\n    // that appears between the check and the swap is somebody's, and stays.\n    for (const gap of plan.gaps) {\n      writes.push(planWrite(gap.path, renderServiceProject(gap.service.id, LIKEC4_ROOT_PROJECT)));\n    }\n    // 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    const created = plan.gaps.map((gap) => repoPath(docsDir, gap.path));\n    report(json, { action, subsystems: tree.subsystems.length, recovered, projects: projects(created) });\n  } finally {\n    await releaseLock();\n  }\n}\n\n/**\n * What the project half of this run owes, from ONE predicate. `surveyProjects`\n * is the shared spelling of \"has a model, a legal id, and no file\", and it\n * hands back the size of the domain it counted against, so `current` is a\n * subtraction rather than a second reading of the same two paths — a loop\n * here 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(docsDir: DocsDir, services: readonly WalkedService[]): ProjectPlan {\n  const root = existsSync(rootProjectPath(docsDir));\n  const survey = surveyProjects(services, serviceRenderPaths);\n  if (!root) return { root, gaps: [], current: 0, modelled: survey.modelled };\n  return { root, gaps: survey.gaps, current: survey.modelled - survey.gaps.length, modelled: survey.modelled };\n}\n\nfunction report(\n  json: boolean,\n  out: { action: SyncAction; subsystems: number; recovered: CommitRecovery | null; projects: ProjectsReport },\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      projects: { root: out.projects.root, created: out.projects.created, current: out.projects.current },\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 wrote = out.projects.created.length;\n  // \"nothing to write\" is a claim about the whole run, and it is false the\n  // moment a project file landed beside a current views file.\n  const sentence: Record<SyncAction, string> = {\n    current: `architecture/subsystems.likec4 is current (${out.subsystems} subsystem(s))${wrote === 0 ? \" — 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  if (wrote > 0) {\n    console.log(\n      `wrote ${wrote} services/<…>/likec4.config.json — one LikeC4 project per service model, create-only ` +\n        \"(a file that already exists is yours and is never touched; commit the new ones before a \" +\n        \"`loam subsystem move`, which refuses over untracked paths). With more than one project, \" +\n        \"likec4 validate at the docs root needs --project <name>; build and export take every project.\",\n    );\n  }\n  if (!out.projects.root && out.projects.modelled > 0) {\n    console.log(\n      \"note: no likec4.config.json at the docs root, so no service project files were written — \" +\n        \"`loam doctor` prints the root file.\",\n    );\n  }\n}\n"]}

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

@@ -7,6 +7,25 @@
  * the same commit as whatever changed the tree — a marker without its view,
  * or renames without theirs, is exactly the `subsystem.views-stale` state
  * the generated file's contract refuses to leave between two commits.
+ *
+ * This window does NOT write the per-service project files
+ * (`services/<…>/<id>/likec4.config.json`); only `../sync.ts` does, and the
+ * asymmetry is deliberate rather than an omission. The views file must ride
+ * in the verb's commit because its bytes depend on the PLACEMENT the verb is
+ * changing. A project file's bytes depend on the service id alone, which no
+ * verb here changes — and the file lives INSIDE the service directory, so a
+ * `move` carries it to the new location as part of the rename it already
+ * journals (in a git-backed repo that move REFUSES first, `move-uncommitted`,
+ * until the files `sync` created are committed — the refusal names them, and
+ * `sync`'s own output says to commit them), and `rm` never reaches one,
+ * because it refuses any subsystem that still holds a member
+ * (`subsystem-not-empty`, `../edit.ts`). No verb can
+ * therefore leave a project file stale or orphaned, and a verb that filled
+ * gaps in passing would silently write files a `--json` reader of `new` or
+ * `rename` was never told to expect. The one state a verb can leave is a
+ * model with no file beside it, and that is the state `validate --all` names
+ * as `service.likec4-config-missing`, with `loam subsystem sync` as the
+ * repair — one writer, so the create-only rule has one place to hold.
  */
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";