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

package/CHANGELOG.md

@@ -10,6 +10,168 @@ 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.7] - 2026-09-07
+
+Infrastructure belongs on the fleet map, and the render is navigable at fleet scale. Still a
+prerelease on the `alpha` line: `npm i @ybotok/loam@alpha` installs it. One code is REMOVED —
+`landscape.datastore-private`, the first code this project has ever retired — and no flag, path or
+payload key is. What a repo NOTICES on its first `validate --all` after upgrading: a
+`subsystem.views-stale` error against the new `architecture/services.likec4`, in every fleet whose
+map draws a service, cleared by one `loam subsystem sync`; a second one against
+`architecture/subsystems.likec4` wherever subsystems exist, because those views gained boundary
+edges and an `of` subject; and silence where a datastore drawn beside the services used to be told
+to move.
+
+**Upgrading: one `loam subsystem sync` per docs repo, once.** `loam validate --all` reports
+`subsystem.views-stale` (error) against the new `architecture/services.likec4` in EVERY existing
+docs repo whose fleet map draws a service — flat fleets with no subsystems included, because the
+file is new everywhere and an absent generated file is a state of its own. This is not a
+subsystems-only upgrade: a fleet that has never run `loam subsystem new` gets the finding too. A
+repo that DOES have subsystems gets a second finding on the same run, against
+`architecture/subsystems.likec4`, because the subsystem views gained boundary edges and an `of`
+subject and every existing copy therefore re-renders differently. One `loam subsystem sync` writes
+both files and clears both findings. `loam archive` names the same repair rather than claiming
+"complete + current". Nothing else in a repository has to change, and no document a team wrote is
+touched — and a document a team wrote that is already standing at one of the two generated paths is
+refused by name rather than overwritten (below).
+
+### Removed — `landscape.datastore-private`, because where a store is drawn is the team's choice
+
+- **`landscape.datastore-private` (warn) is retired.** It fired on a `database` element drawn at
+  fleet level with exactly ONE consumer, and its whole message prescribed deleting the peer and
+  writing the store inside its owner. The identical store nested was silent, so the check graded the
+  DRAWING and not the architecture — a restriction rather than a fact about the fleet. A store one
+  service owns may now be nested under that service's element or drawn beside the services, and loam
+  grades neither. The code is not in the frozen `ErrorCode` or `IssueCode` unions, so removing it
+  breaks no contract; `loam explain landscape.datastore-private` no longer answers, and the row is
+  gone from the agent-facing check table.
+- **`landscape.datastore-shared` (warn) is unchanged**, both arms. Two or more services on one store
+  is a fact about coupling, not a restriction, and it fires at two consumers for both placements
+  alike. What survives from the retired code's message is the one clause that was a fact about
+  LikeC4 rather than a preference, and SCHEMA's "Private stores" now leads with it: a second
+  consumer's edge resolves only against a declaration the MAP holds, because a per-service project
+  is `architecture/` plus one model.
+- **Infrastructure is not a service.** A new `INFRA_KINDS` set in `core/vocabulary/maturity.ts` —
+  `database`, `queue`, `topic`, `cache`, `bucket`, compared case-insensitively — takes such an
+  element out of four surfaces at once: the drawn-service census behind
+  `landscape.service-undocumented`, the `loam gate` partner set (an infra endpoint is dropped from
+  the `partners` payload, exactly as an actor already was), the `loam verify` checklist (a
+  fleet-level store no longer mints a `service.exists` claim no repository can answer), and the
+  scorecard's element denominator, whose `c4` row now counts services rather than services plus
+  their stores. The hook is the kind NAME, with the same limitation `ACTOR_KINDS` lives with: a
+  fleet spelling its kind `postgres` is not covered, and a tag can be added later as a second
+  spelling. A store BOUND to a directory with `metadata { service }`, or titled like one, stays an
+  adopted service on every one of the four surfaces — the census predicate wins over the kind.
+  `landscape.service-undocumented`'s message gained a THIRD remedy beside "bind it" and "tag it
+  `#external`", spelled from the same set: neither of the old two was true of a store the fleet
+  owns, and that message is the only place an author learns which kind spellings loam reads.
+- `c4.uncovered` was left alone, and the measurement is the reason: a delta drawing
+  `splitLedger = database 'split-ledger'` earns it, and adding `Covers: splitLedger` to the
+  feature's `arch.spec.md` delta silences it exactly, with no `covers.unknown`. The remedy the
+  message names is true, so this is not a residual restriction — and the code fires only on elements
+  a feature DELTA adds, never from `validate --all` over a living tree.
+- The acceptance criterion, run for real: a `database` drawn at fleet level, owned by the fleet, with
+  one consumer, no `#external` tag and no binding, now earns ZERO findings from `loam validate --all`
+  and from `loam gate`.
+
+### Added — `architecture/services.likec4`: one generated overview view per service
+
+- **New generated path `architecture/services.likec4`**, written by `loam subsystem sync` beside
+  `architecture/subsystems.likec4`, removed by it when the fleet map draws no service, and owned
+  outright by loam: views only, byte-reproducible, one view per service the map resolves, sorted by
+  service directory id. Each view is declared `of` its service's element, which is what makes the
+  fleet map, every subsystem view and every other service view click-through into it with no
+  authored link — measured at likec4 1.59.2. Peers are NAMED one by one rather than wildcarded,
+  because on a map that groups its services the wildcard form collapses every peer to its group box
+  and yields no drill-down at all (measured on a 120-service fleet: 0 of 10 nodes navigable). Median
+  at 58 services in 11 groups: 10 nodes, 8 edges per view, about 7 ms of layout each.
+- **Titles are folders.** A per-service view is titled `<subsystem path> / <service directory id>`,
+  built from the same path helper the subsystem views use, so both generated files fold into one
+  browser folder tree mirroring `services/`. LikeC4 has no view-folder syntax — `views { group … }`
+  is a parse error at the pin — and splitting the title on `/` is the whole mechanism.
+- **An authored view of the same element keeps precedence.** Two views `of` one element are legal;
+  the first document alphabetically wins the default navigation target and both stay reachable,
+  because the subject's own node cycles to the other. `architecture/landscape.likec4` sorts before
+  `architecture/services.likec4`. loam does not detect the authored view and never will:
+  docs/DESIGN.md rule 26 forbids reading what a view SHOWS.
+- **Subsystem views gained two things** in the same generator: `include <member> -> *, * -> <member>`
+  per member, so a subsystem view answers "what does this group touch" and not only "who is in it",
+  and `view subsystem_<name> of <ancestor>` when the map holds an element owning exactly that
+  subsystem's members. Measured at 58/11: ~14 nodes, ~38 edges, 12 of 14 nodes navigable. Every
+  existing `architecture/subsystems.likec4` therefore re-renders differently and is stale once.
+- **`subsystem.views-stale` now grades two files**, one finding per file, each naming its own path in
+  `subject`, `locations[0]` and the message. No new code was minted: both files are written by one
+  command in one commit and repaired by one run, which is what makes one code honest.
+- **`subsystem.view-id-collision` reserves `service_` as well as `subsystem_`.** A `service_` id is
+  reserved only for a service the fleet map actually DRAWS, so an unmodelled `services/<id>/`
+  reserves nothing; the message names which generated file and which prefix.
+- `deployment.doc-reserved` refuses a feature deployment document named `services.likec4` for the
+  same reason it already refused `subsystems.likec4`: both names are generated, overwritten
+  wholesale, and parsed by nothing.
+- **No writer overwrites a generated views file it did not write, and refusing is now an exit 1.**
+  Both generated paths are filenames loam RESERVES inside `architecture/`, a directory the team
+  owns, and every writer of them rewrites the file whole — so a repository that already kept a
+  hand-authored diagram at one of those paths would have lost it, silently, on the first run after
+  the release that reserved the name. Reproduced before the guard existed: with a hand-authored
+  `architecture/services.likec4` in the tree, `loam subsystem new platform` printed
+  `architecture/services.likec4 updated` and destroyed it, first line and all.
+- **What makes a file loam's is its FIRST LINE**, `// generated by loam`, with a leading byte-order
+  mark stripped before the test — a Windows editor adds one without changing a fact, and without the
+  strip loam would call its own output authored and refuse to regenerate it for good. A hand EDIT of
+  a generated file keeps that line, so it is still loam's to repair and one `loam subsystem sync`
+  puts it back: that has always been what `subsystem.views-stale` says. Only a file that never
+  carried the mark is somebody else's. **A 0-byte file at either path counts as somebody else's** —
+  it carries no mark — so an empty `architecture/subsystems.likec4` or
+  `architecture/services.likec4` is no longer filled in; delete it and re-run.
+- **`loam subsystem sync` declines the one file and finishes the rest.** `--json` reports the new
+  `action` value **`refused`** — on `action` for `architecture/subsystems.likec4`, on
+  `serviceViews.action` for `architecture/services.likec4`, one predicate behind both — while the
+  other generated file, the per-service project files and the root `exclude` are still done and
+  still reported, and the **exit code is 1**. That is `loam validate`'s shape rather than a refusal
+  envelope, and the non-zero exit is the point: `loam validate --all` goes on reporting
+  `subsystem.views-stale` for that path with `loam subsystem sync` named as the repair, so a run in
+  a hook or a CI step must not report success over a file it can never fix.
+- **`loam subsystem new` / `rm` / `move` / `rename` and `loam seed` refuse WHOLE**, before a byte is
+  staged: `error.code` `already-exists`, exit 1, nothing written and — for `move` and `rename` —
+  nothing renamed. No new code was minted, because that is what `already-exists` has always meant on
+  these verbs; `loam seed` can answer it for the first time. They refuse whole rather than per-file
+  because their entire contract is that the generated files land in the SAME commit as the change,
+  so completing the structural half would manufacture the very `subsystem.views-stale` state that
+  commit window exists never to leave behind — irreversibly, for a `move` that also stages renames.
+- **The refusal sentence is one sentence, verbatim from all five writers.** It names the mark loam
+  looked for, says that not one byte changed, and gives the way out: rename the file to a name loam
+  does not reserve — every other `.likec4` under `architecture/` renders in the same project, so the
+  diagram is not lost — or delete it, then re-run.
+- **Payload keys, all additive.** `loam subsystem sync --json` keeps `path` and `action` meaning the
+  subsystem file and adds `serviceViews: { path, action }`; `loam subsystem new` / `move` / `rm` /
+  `rename --json` keep `views` and add `serviceViews`; `loam archive --json` keeps
+  `subsystemViewsStale` and adds `staleViews: string[]`, the generated files it left behind. Nothing
+  existing changed meaning.
+- The generated-file SET is now one table (`GENERATED_ARCHITECTURE_FILES`), read by the path
+  builders, the name reservation, both project loads that must EXCLUDE these files (the fleet map's
+  and `c4.fleet-project-invalid`'s), archive's staging and `loam seed`'s. Four readers that must
+  never disagree about which files are generated, and a name in one but not another failed silently
+  both ways while there was only one.
+
+### Added — the intra-service use-case slot, published rather than graded
+
+- **`loam adopt` briefs `services/<…>/<id>/usecases/<name>.likec4` as an OPTIONAL target**, with the
+  tag grammar and a worked example: a `dynamic view` tagged `#req-<Requirement-ID>` as the first
+  thing in the view body, the tag declared once (in the landscape's `specification` for an extending
+  model, in the model's own for a standalone one), every hop backed by a relationship the model
+  declares, and the view id namespaced by the service because an extending model's views share the
+  root project's flat id namespace. Optional-and-absent prints lowercase `missing` and is not a
+  finding — the existing mechanism for an optional artifact, not a new one.
+- **The generated AGENTS.md names the slot and its title convention**,
+  `'<subsystem path> / <service id> / <use case>'`, so an authored use-case view lands in the same
+  browser folder as its service's generated overview.
+- **No new finding code, and no check on absence.** docs/DESIGN.md rule 26 — presence is never owed,
+  and no check may grade a view's absence — is enforced by `scripts/arch-check.mjs`, so there is no
+  service.usecases-missing and there never will be. The grader (`c4.valid`'s
+  ` · K tagged flow(s) graded`) has existed since 2026-09-03; all that was missing was anyone being
+  told. A usecase.flow-untagged check, which would grade a view that EXISTS, is recorded on
+  [ROADMAP.md](ROADMAP.md) with its promotion bar rather than built.
+
 ## [0.2.0-alpha.6] - 2026-09-04
 
 A service model may extend the fleet map, and the nine problem reports one fleet filed against the

package/README.md

@@ -7,7 +7,7 @@
 [![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/alpha.svg?label=npm%20alpha)](https://www.npmjs.com/package/@ybotok/loam)
 
-> **Pre-release: `0.2.0-alpha.6`**, the fifth published release of the 0.2 line and the newest published
+> **Pre-release: `0.2.0-alpha.7`**, the sixth 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 — 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
@@ -493,7 +493,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.6 plus the changes on `main` under
+- [CHANGELOG.md](CHANGELOG.md) — released beta.1–alpha.7 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.
@@ -529,12 +529,12 @@ authored-capability axes with the `Realizes:` join, use cases graded as `dynamic
 `architecture/obligations.yaml` architectural obligations checked through `#obl-` tags and
 `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 **173 test files** (counted 2026-09-04): the count is graded
+generation come later. Behind that status stand **174 test files** (counted 2026-09-07): 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.6`: the unscoped `loam` name is taken by an unrelated GDAL wrapper, so the package ships
+`0.2.0-alpha.7`: 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,19 +18,19 @@ 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 **464 TypeScript modules in 143 source packages**, with an acyclic package graph
+The tree contains **468 TypeScript modules in 144 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 **173 test files**. Those four counts are deliberately stated OUTSIDE the
+and the suite stands at **174 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-04 at `0.2.0-alpha.6`, and dated because neither number has a cheap derivation:_
+_Measured 2026-09-07 at `0.2.0-alpha.7`, 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,772/3,772 tests**, with two `skipIf(asRoot)` cases the root gate container cannot run; the
-coverage gate passing with **92.78% statements, 84.65% branches, 97.08% functions, and 94.63%
+**3,802/3,802 tests**, with two `skipIf(asRoot)` cases the root gate container cannot run; the
+coverage gate passing with **92.88% statements, 84.83% branches, 97.14% functions, and 94.70%
 lines** against its thresholds of 91 / 82 / 95 / 93; and `npm run release:check` plus
 `npm run test:package` green against the real tarball.
 
@@ -193,7 +193,9 @@ merged map before writing either. Second, the consumer census read `architecture
 this shape a private store's consuming edges — which live in the models now — counted for nothing:
 `landscape.datastore-private` went silent or named the wrong service, and a nested store two
 services reach was graded nowhere. It reads every extending model's attested calls now, and
-`landscape.datastore-shared` fires for a nested store. Third, the wiring guard this entry landed
+`landscape.datastore-shared` fires for a nested store. (That census still stands; the code named
+here does not — `landscape.datastore-private` was retired on 2026-09-07, because where a store is
+drawn is the team's choice. See the CHANGELOG entry.) Third, the wiring guard this entry landed
 failed open on every root `exclude` spelling except `services/<tree>/**`, `loam subsystem sync`
 never removed the stray per-service project file it told repositories to delete (and that file
 CLAIMS the model, rather than holding nothing as the design note said), and
@@ -675,6 +677,25 @@ item gets promoted — it went from here to `## Now` and from there to
   change as the `arch.spec.md` requirement it answers. Until then a service-local flow is written
   directly into the service directory in the same pull request, where git produces the conflict;
   building the feature route ahead of that evidence is the invented need the non-goals forbid.
+- **A subsystem-scoped use-case slot.** A flow whose hops all sit inside one subsystem's subtree
+  looks like it wants a home between the two that exist — `architecture/usecases/` is the fleet's
+  slot, `services/<…>/<svc>/usecases/` is one service's. Deliberately NOT built (2026-09-07), and
+  the reason is that the capability is already there: a subsystem-scoped flow IS a fleet use case
+  whose hops happen to share a subtree, `architecture/usecases/<name>.likec4` already grades it, and
+  its view already folds into the same title-path folders as the generated subsystem view above it.
+  A second slot would duplicate the grader, the tag vocabulary and the archive route for no
+  capability that does not exist today. Promote only on evidence that a fleet's subsystem flows are
+  being lost among its fleet flows in the renderer's view list — which is a naming problem before it
+  is a slot problem, and one the title convention answers first.
+- **A flow-untagged check** (it would be spelled usecase.flow-untagged): a `.likec4` beside a
+  service's model that mentions a `req-` prefix while no view in that project carries the tag — an
+  author who reached for the intra-service use-case axis and missed, whose flow renders and is
+  graded by nothing. It grades a view that EXISTS rather than an absence, so docs/DESIGN.md rule 26
+  permits it, unlike the service.usecases-missing nobody may ever build. Not built (2026-09-07) for
+  a mechanical reason worth stating: `core/brief/checks.ts` sits at 399 of 400 lines inside a
+  five-file-capped package, so a new non-ok code forces a split-module commit before any behaviour
+  can land, and that split should be chosen for a seam rather than for a code. Promote when a second
+  fleet reports a flow that rendered and was graded by nothing.
 - **Landscape scaling:** retain one landscape while conflicts are exceptional, and half of what
   this row once asked for arrived on 2026-09-04. Per-service internals now live in
   `services/<svc>/model.likec4` by default: `loam archive` routes a delta's fqn-spelled interior

package/SCHEMA.md

@@ -62,6 +62,7 @@ docs/
   architecture/
     landscape.likec4                    global C4 (system landscape)
     subsystems.likec4                   one view per subsystem, views only    [GENERATED: loam subsystem sync]
+    services.likec4                     one overview view per service, views only [GENERATED: loam subsystem sync]
     permissions.yaml                    system-wide authorization vocabulary  [authored, opt-in]
     capabilities.yaml                   system-wide capability vocabulary     [authored, opt-in]
     obligations.yaml                    system-wide architectural obligations [authored, opt-in]
@@ -135,7 +136,7 @@ model.likec4 stays THE model:
 `c4.valid`, `Covers:` and every other model check read it alone, and a sibling that does not parse
 is one `usecase.flow-invalid` while the model keeps grading. Files loam does not read: a `.likec4`
 in a subsystem directory, in a feature directory outside `delta.likec4`/`usecases/`/`deployment/`,
-the generated `subsystems.likec4`, a sibling the service's own `likec4.config.json` `exclude`
+the generated `subsystems.likec4` and `services.likec4`, a sibling the service's own `likec4.config.json` `exclude`
 covers (it is in no project the renderer loads either), and every UNTAGGED `dynamic view`
 anywhere — a diagram, never a use case.
 
@@ -153,8 +154,8 @@ a map the next reader's `loam validate --all` fails on.
 top-level `specification { }` block containing an `element` declaration:
 
 - an **extending model** declares no element kind. It is parsed INSIDE the fleet's `architecture/`
-  project — the landscape plus every other `architecture/**/*.likec4` except the generated
-  `subsystems.likec4` — and says what is inside the service with `extend <fqn> { … }` on the element
+  project — the landscape plus every other `architecture/**/*.likec4` except the generated views
+  files (`subsystems.likec4`, `services.likec4`) — and says what is inside the service with `extend <fqn> { … }` on the element
   the map already binds to the directory. `<fqn>` is the FULLY-QUALIFIED id: `extend orderService`
   resolves to nothing when the element is `marketplace.orderService`. No `specification` is needed,
   no partner is re-declared, and `model {}` or no model at all are both fine. `extend` accepts
@@ -181,7 +182,7 @@ exactly why its copies of the map's elements can drift.
 |---|---|---|
 | `c4.declaration-diverged` (warn, service) | standalone | an element this model and the fleet map (`architecture/`) both declare, whose `kind`, `title`, tag SET or `metadata { service }` binding differ. The two are joined by id, then by the `metadata { service }` binding both wrote, then by the map element whose id ends with the model's as a dotted tail (`paymentService` ↔ `marketplace.paymentService`) — a tail two map elements answer to joins nothing, and a tail that is a BARE last segment (`db`, `api`) is a key only for a FLEET-LEVEL map element: one no ancestor of which stands for a service, so a top-level element or a box the map draws inside a plain grouping element, never an element drawn inside a service's own. `description` is deliberately not compared — it is prose, nothing grades it, and the other four each change what a view shows or what loam resolves. When the tag sets are all that differ and copying the map's declaration would not clear them — because the difference comes off `specification { element <kind> { … } }` on one side or the other — the message says so and names the document whose specification declares them, rather than asking for a copy. One finding per divergent element; silent while the map does not parse |
 | `c4.element-unowned` (warn, service) | extending | the model declares an element OUTSIDE the element that resolves to this service. Three remedies, first first: a store or component this service owns goes INSIDE the `extend <fqn> { }` block, where its id becomes `<fqn>.<name>`; a system the service reaches belongs in the map, declared once; another service's internals belong in that service's model |
-| `c4.fleet-project-invalid` (warn, landscape) | extending | `--all` only, and not while `landscape.excluded` holds — this load reads what the renderer reads and so has no floor under the map, and one `exclude` entry covering the map turns every extending model's `extend` into an unresolved reference (measured on `examples/docs`: 161 warnings from one line). loam loads the fleet project the way the renderer does — a walk of the docs root, minus everything the root `exclude` covers, minus the generated `subsystems.likec4`, minus every STANDALONE service directory (`service.model-unexcluded` owns that state), minus `features/` (a delta carries its own `specification` and the directory is transient) — and reports each error NOT already present in the map alone or in any per-service project the same run made. A `.likec4` in a SUBSYSTEM directory, above every service, is in that set. This is the class no per-service grade can see: two services declaring the same tag locally, two models adding the same child id, a broken untagged sibling nobody opted in. All of them are renderer-fatal. `locations[0]` is the file the error is in and the message tail names the failure it actually is |
+| `c4.fleet-project-invalid` (warn, landscape) | extending | `--all` only, and not while `landscape.excluded` holds — this load reads what the renderer reads and so has no floor under the map, and one `exclude` entry covering the map turns every extending model's `extend` into an unresolved reference (measured on `examples/docs`: 161 warnings from one line). loam loads the fleet project the way the renderer does — a walk of the docs root, minus everything the root `exclude` covers, minus the generated views files (`subsystems.likec4`, `services.likec4`), minus every STANDALONE service directory (`service.model-unexcluded` owns that state), minus `features/` (a delta carries its own `specification` and the directory is transient) — and reports each error NOT already present in the map alone or in any per-service project the same run made. A `.likec4` in a SUBSYSTEM directory, above every service, is in that set. This is the class no per-service grade can see: two services declaring the same tag locally, two models adding the same child id, a broken untagged sibling nobody opted in. All of them are renderer-fatal. `locations[0]` is the file the error is in and the message tail names the failure it actually is |
 | `service.likec4-config-stray` (warn, landscape) | extending | a `likec4.config.json` beside an extending model. The renderer registers it as a project of its own rooted at that directory, so the docs root stops being a one-project workspace (`likec4 validate .` then refuses without `--project`), and wherever that nested project claims the model it parses alone, out of the root project where the map's kinds are: the model does not resolve and `export json --project fleet` loses the service's containers (measured, likec4 1.59.2 — which of the two happens depends on the workspace; on `examples/docs` the fleet export was byte-identical with and without the file, on a seeded fleet the containers went). Run `loam subsystem sync`: it deletes the file. Deleting it by hand works too. loam never writes one beside an extending model |
 | `service.model-excluded` (warn, landscape) | extending | the root `likec4.config.json`'s `exclude` covers this model's directory, so the renderer never loads it and the service is a box with nothing inside it. An entry is read the way the renderer reads it (measured, likec4 1.59.2): a bare entry is a raw path PREFIX starting on a `/` boundary, so `services`, `services/`, `services/*`, `services/**`, `services/**/*`, a wildcard segment in the middle and the bare `services/pay` all cover `services/payment-service` — while the glob form `services/pay/**` wants the literal separator and covers nothing there. An entry shaped like a FILE rather than a directory (`services/**/model.likec4`, `**/model.likec4`) is reported too, with a different repair: `loam subsystem sync` maintains only the `services/` directory entries, so that shape has to be narrowed or deleted by hand. The finding quotes the entry verbatim, because the repair is to edit that line; `loam subsystem sync` is the repair for the directory shape |
 | `service.model-unexcluded` (warn, landscape) | standalone | the mirror, and the one that costs most: the root `exclude` does NOT cover a standalone model's directory, so the renderer merges it into the root project and reports every kind and element it declares as a duplicate — blanking the whole project, not just this service. An entry already covering the directory in any of the spellings above satisfies it, and `sync` appends no second glob for one. Same repair |
@@ -218,24 +219,34 @@ So a hop naming `<service-fqn>.<container>` resolves in neither the preview nor
 leaves, and `usecase.flow-invalid` refuses — where the un-routed preview resolved it, passed the
 gate `--approve` cannot override, and landed a flow the next `loam validate --all` failed on.
 
-**Private stores.** A store one service owns is nested UNDER that service's element — written in
-the service's `extend <fqn> { store = database … }` block, or inside the service's element on the
-map when the map draws that service's containers. The `extend` placement needs an EXTENDING model:
-a model that declares its own `specification` is parsed alone, so `extend <fqn>` resolves nothing
-there, and for such a service the map is the only placement (or migrate the model — see "Two
-shapes of a service model" above). `landscape.datastore-private` names whichever of the two the
-consumer's model shape allows. Drawn beside the services instead it reads as a
-system in its own right (`landscape.datastore-private`). Nesting closes no door: loam counts a
+**Private stores.** **Where a store is drawn is the team's choice.** A store one service owns may be
+nested UNDER that service's element — written in the service's `extend <fqn> { store = database … }`
+block, or inside the service's element on the map when the map draws that service's containers — or
+drawn beside the services as an element of its own. Both are first-class and loam grades neither as
+wrong. Until 2026-09-07 the second earned `landscape.datastore-private` at one consumer, a warning
+whose whole message prescribed deleting the peer while the identical store nested was silent: it
+graded the drawing rather than the architecture, and it is retired. Infrastructure is not a service
+either — an element whose kind is `database`, `queue`, `topic`, `cache` or `bucket` is out of the
+service census, so an owned store drawn at fleet level is not `landscape.service-undocumented`, is
+not a `loam gate` partner, and mints no `service.exists` verification claim. The `extend` placement
+needs an EXTENDING model: a model that declares its own `specification` is parsed alone, so
+`extend <fqn>` resolves nothing there, and for such a service the map is the only nesting site (or
+migrate the model — see "Two shapes of a service model" above).
+
+What the choice DOES decide is one thing, and it is a fact about LikeC4 rather than a preference: **a
+second consumer's edge resolves only against a declaration the MAP holds**, because a per-service
+project is `architecture/` plus one model. Draw a container-level edge to `<owner-fqn>.<store>` in
+another service's model while the store lives in the owner's `extend` block and that model is
+`c4.invalid` ("Could not resolve reference to Referenceable named '<store>'"). So a store a second
+consumer will name has to be on the map — nested inside the owner's element there, or beside the
+services. That was always the load-bearing half; the prescription around it was not.
+
+Nesting closes no door in the other direction: loam counts a
 consumer a service's EXTENDING model attests exactly as it counts one the map draws, so a nested
 store two services reach is `landscape.datastore-shared` — the store's owner plus every service
 whose model draws an outbound call at it or below it. The second consumer draws that call as a
 container-level edge to `<owner-fqn>.<store>` in its OWN model, and the service-level twin on the
-map as usual. Which of the two placements to choose is decided by that edge: a per-service project
-is `architecture/` plus one model, so the edge resolves only when the MAP declares the store —
-written in the owner's `extend` block, the same edge is `c4.invalid` on the consumer ("Could not
-resolve reference to Referenceable named '<store>'"). Nest it on the map when a second consumer is
-foreseeable, and in the model when it is not. The choice is cheap in ONE direction, and the
-direction is the whole of the rule. The two placements give the store the same id,
+map as usual. The two placements give the store the same id,
 `<owner-fqn>.<store>`, so moving the declaration OUT of the owner's `extend` block into the owner's
 element on the map rewrites no edge and no `Covers:` line — measured on `examples/docs`, where
 moving `db` out of order-service's `extend` block into `orderService` on the map left the model at
@@ -246,7 +257,10 @@ order-service's `extend` block is `c4.invalid` on checkout-web's model ("Could n
 reference to Referenceable named 'db'"), or `landscape.invalid` plus one `spine.landscape-invalid`
 per service when that second edge is drawn on the map. `landscape.datastore-shared` needs a second
 consumer to fire, so it always prints in the state where map→extend breaks, and its message says
-so. The consumer census is fleet-scope: it reads
+so. It is the one datastore grade left, it fires at two consumers for both placements alike, and it
+states a coupling rather than prescribing a move: shared means the same DATA, and if two services
+only share a host or a cluster the honest model is one private store each. The consumer census is
+fleet-scope: it reads
 EXTENDING models only, because their ids are the map's fully-qualified ids and the join is exact,
 while a standalone model's ids are its own file's and are never matched to a landscape element.
 
@@ -433,11 +447,12 @@ the file behind.
 `loam subsystem sync` is the one regenerator (it also *removes* the file when the tree has no
 subsystems), every `loam subsystem` write verb regenerates it inside the same transaction, and
 `validate --all` grades staleness by **content comparison** (line endings normalized; a CRLF
-checkout changes no fact) — exactly one error,
-`subsystem.views-stale`, on exactly that file; nothing in loam ever parses it: a views-only document
-does not parse standalone (its `include` lines reference elements the landscape defines), and it
-holds **static** views, whose contents loam never reads in any document. Only the LikeC4 renderer,
-which merges the whole `architecture/` project, resolves its includes.
+checkout changes no fact) — one error,
+`subsystem.views-stale`, per stale generated file, each naming its own path (there are two of them;
+`architecture/services.likec4` is below); nothing in loam ever parses either: a views-only document
+does not parse standalone (its `include` lines reference elements the landscape defines), and both
+hold **static** views, whose contents loam never reads in any document. Only the LikeC4 renderer,
+which merges the whole `architecture/` project, resolves their includes.
 
 `sync` refuses to rewrite this file while the `architecture/` project cannot be read. The render
 needs the map's elements and its global-style census, and a tolerant "no elements" answer wrote a
@@ -452,7 +467,111 @@ surface. With no file yet, and inside a tree-changing verb's commit window (`new
 `rename`, whose contract is that the file lands with the change), the tolerant shape is written as
 before and the same note is printed.
 
-The tree's **second renderer file** is per service — `services/<…>/<svc>/likec4.config.json`,
+### `architecture/services.likec4` — one overview view per service
+
+The **second generated views file**, written by the same `loam subsystem sync`, in the same commit,
+removed by it when the map draws no service, and graded by the same `subsystem.views-stale` on its
+own path. Views only, one per service the fleet map draws, sorted by service directory id:
+
+```
+view service_payment_2dservice of marketplace.paymentService {
+  title 'Payments / payment-service'
+  global style services
+  include *
+  include kafka.orderEvents
+  include marketplace.checkoutWeb
+  include stripe
+  exclude * -> *
+  include -> marketplace.paymentService
+  include marketplace.paymentService ->
+  include marketplace.paymentService.* -> marketplace.paymentService.*
+}
+```
+
+**Why the peers are named one by one, measured at the 1.59.2 pin on a 120-service and a 58-service
+fleet.** The obvious recipe — `include <fqn> -> *` and `include * -> <fqn>` — is wrong at fleet
+scale and looks perfect on a small flat fixture, which is how it would have shipped. LikeC4 draws a
+counterpart at the highest ancestor that is not also an ancestor of the subject, so on a map that
+GROUPS its services (which is exactly what a 100-service fleet needs at fleet level) every peer
+collapses to its group box: the naive view of one service in the 120-service fleet drew six group
+boxes and **0 of its 10 nodes had drill-down**. loam already reads elements and relationships, so it
+names each peer itself — the far endpoint of every edge touching the service or anything inside it,
+spelled as the map declares it, so an edge at a topic names the topic and not the broker, which is
+the truer picture and the one the map already draws. `exclude * -> *` then drops the peer-to-peer
+cross traffic (23 edges down to 7 on the same fixture), and the three lines after it put back
+exactly the subject's own: the UNARY `include -> <fqn>` / `include <fqn> ->`, never the binary
+wildcard, which re-introduces the parent group boxes as extra nodes (16 instead of 10). `include
+<fqn>.* -> <fqn>.*` is the interior wiring, and it is legal on a childless element — it simply
+matches nothing — which is what makes one line work for both model shapes: an extending model's
+containers are in the root project and appear, a standalone model's are not and the line is silent.
+
+Measured at 58 services in 11 groups: a median of **10 nodes and 8 edges** per generated view, every
+peer that is a service carrying drill-down into its own generated view, and `npx likec4 export json`
+— which layouts every view — costing about **7 ms per generated view** (1.3 s with 120 of them
+against 451 ms without). `likec4 start` layouts on demand, so a reader pays for the one view they
+open, and the generated views are all small BY CONSTRUCTION; the expensive view is the hand-authored
+fleet one, and it is unaffected.
+
+**Drill-down is the `of`, and it costs one keyword.** `view <id> of <element-fqn>` names the view's
+subject, and LikeC4 then computes `navigateTo` on that element's node in **every other view that
+draws it** — no authored links anywhere. So one generated view per service makes the fleet map,
+every subsystem view and every other service view click-through into the service. The subsystem
+views take the same keyword when the map holds an element owning exactly that subsystem's members,
+which closes the mesh — `fleet → payments → payments/service-22 → identity/service-45 → identity`,
+every hop generated, none authored.
+
+**Two views of one element are legal, and the FIRST DOCUMENT ALPHABETICALLY wins** the default
+navigation target — measured by renaming the files, LikeC4's load order being alphabetical by path.
+Both stay reachable: inside a view of the subject, the subject's own node navigates to the OTHER
+view of the same element, so the renderer cycles between siblings and nothing is orphaned.
+`architecture/landscape.likec4` sorts before `architecture/services.likec4`, so a team's authored
+`view of <element>` written in the map keeps precedence over the generated one, and neither is lost.
+loam does not detect this and never will: **docs/DESIGN.md rule 26 forbids loam reading what a view
+SHOWS**, in any document, so it may not look at an authored `view of` to decide whether to emit. It
+emits for every service the map draws, and the alphabet settles the rest.
+
+**The first line is the deed, and every writer checks it.** Both generated views files open with a
+`// generated by loam` mark, and that mark is what makes the path loam's rather than the team's.
+These are the only two filenames loam RESERVES inside `architecture/`, a directory that is otherwise
+entirely authored, so a repository that already had a file at one of those paths must not lose it to
+an upgrade — the archive's promise that authored bytes stay authored holds here too. Every writer of
+these paths reads the first line first: `loam subsystem sync` reports that one file `refused`,
+writes nothing for it, still does the rest of its work, and exits 1; `loam subsystem new`, `rm`,
+`move` and `rename` and `loam seed` refuse the WHOLE operation with `already-exists`, writing,
+renaming and staging nothing, because their commit window exists precisely to land the generated
+file in the same commit as the change to the tree — completing half of that would manufacture the
+`subsystem.views-stale` state the window exists never to leave behind. The consequence to know: a
+file with no mark is never regenerated, and an EMPTY file carries no mark either, so a truncated one
+must be deleted by hand before sync will write it again. loam's own staging is atomic and cannot
+produce one.
+
+**Titles are folders, because there is nothing else.** LikeC4 has **no view-folder syntax** —
+`views { group 'X' { … } }` is a parse error at the pinned version and the AST carries no view-group
+type at all. What it has is the title: a view title is split on `/` into browser folders and only
+the last segment is shown. So a per-service view is titled `<subsystem path> / <service directory
+id>`, built from the same path helper the subsystem views use, and the two generated files fold into
+ONE folder tree mirroring `services/`. An unfiled service is its own id at the root. The service
+**directory id** is used rather than the map element's title: it is the name every loam command
+addresses the service by, it cannot drift from the map, and a directory id cannot contain `/`. A
+`dynamic view` you author under `services/<…>/<id>/usecases/` lands in the same folder when you
+title it `'<subsystem path> / <service id> / <use case>'` — a convention loam states and never
+grades.
+
+**Which services appear.** Exactly those the element→service join resolves, the same join the
+subsystem views use. A service the map does not draw is omitted — its absence is already
+`landscape.service-unmodelled`, and rendering only what the committed map resolves is what keeps the
+output a function of committed bytes. **View ids** are `service_` plus the same hex escaping the
+subsystem view ids use, so the two generated files cannot collide with each other, and an authored
+view claiming one is `subsystem.view-id-collision` — which names the file and the reserved prefix. A
+`service_` id is reserved only for a service the map actually draws. **Style**: `global style
+services`, presence-detected off the parsed map's declared style ids exactly as `subsystems` is, and
+written only when a group of that name is declared — a reference to an undeclared group is a parse
+error that blanks the whole project.
+
+### The per-service LikeC4 project file
+
+A different artifact from the two generated views files above, and the tree's other renderer
+concern: `services/<…>/<svc>/likec4.config.json`,
 which `loam subsystem sync` also writes, beside every **standalone** `model.likec4` that has none.
 An extending model needs no such file and never gets one: it belongs to the root project, which is
 where it parses, and a project file beside it is `service.likec4-config-stray` — which `sync`
@@ -975,7 +1094,7 @@ There is no manifest of services: the directories under `services/` **are** the
   touched/untouched, never a set difference over the attested calls, because loam cannot tell a
   call the map forgot from one the fleet deliberately does not draw at its own altitude. "Edge in
   the map" means an edge in the `architecture/` PROJECT — the landscape plus every other `.likec4`
-  under it, minus the generated `subsystems.likec4` — and `loam adopt` reads the same set. An
+  under it, minus the generated views files (`subsystems.likec4`, `services.likec4`) — and `loam adopt` reads the same set. An
   `#external` element is never the subject, whatever directory it is bound to.
 
 **`architecture/landscape.likec4` is required, not optional.** Its absence is a finding, never a
@@ -1440,9 +1559,9 @@ the CI escalation.
   match, with a did-you-mean hint. Deliberately the service model and never the landscape read on
   its own: the
   landscape carries only what crosses the service boundary, the model carries everything the service
-  touches (a private store nested inside the service's own element — `landscape.datastore-private`
-  is the check pushing it there, and `landscape.datastore-shared` is what a second consumer of that
-  nested store now earns), and that is the set the on-call file must agree with. For an extending model
+  touches (a private store nested inside the service's own element — one of the two placements
+  "Private stores" above leaves to the team, and `landscape.datastore-shared` is what a second
+  consumer of that nested store earns), and that is the set the on-call file must agree with. For an extending model
   the set is its own SLICE: the elements it adds, plus the partners its own edges point at and their
   ancestors — so a dependency named `kafka` resolves through an edge that names `kafka.orderEvents`,
   and a peer service resolves through the `metadata { service }` binding on the map's element the
@@ -2947,9 +3066,10 @@ arrived. Per-service internals now live in `services/<svc>/model.likec4` **by de
 where a second team adopting a service writes, so it adds nothing to this file. It is a default and
 not a prohibition: the map MAY hold a service's interior, and sometimes must. A store a second
 service will reach has to be declared where that consumer's project can see it — a per-service
-project is `architecture/` plus one model — so it is nested inside the owner's element ON THE MAP,
-which is exactly what "Private stores" above prescribes and what `landscape.datastore-private` and
-`landscape.datastore-shared` offer as a placement. A delta spelling a parent in the legacy
+project is `architecture/` plus one model — so it is drawn ON THE MAP, nested inside the owner's
+element or beside the services, whichever the team prefers. Which of the two is nobody's business
+but the team's: "Private stores" above leaves the placement open and loam grades neither, so nothing
+here says a store must move. A delta spelling a parent in the legacy
 title-join lands its container on the map too. What an extending model owns is what it DECLARES,
 not everything below the service's element. `loam archive` routes rather than forbids — a delta's
 additions nested under a service whose model extends the map, with the whole parent chain spelled