jschoubben
c8f430290e
The mesh's own seats said who does a job and nothing about what may be said to them or by them, and that gap showed up three times in one day looking like three different problems: a build machine with three audiences for one outcome and no way to derive a grant for any of them; an event genuinely about a role with nowhere to live but the namespace of whichever module holds that role today; and a catalogue catching up on builds, where every option needed a grant the design refuses. One cause — the mesh has roles it cannot describe. So the `mesh-*` seats take the same three fields a module's seat has, and the machinery that already derives authority, queues and consumers from a declared seat does it for these too. Builds become work submitted to a role, and `mesh.build.request`, `mesh.control.built` and the BUILDS stream retire. A work queue shared by several build machines is exactly what a seat's `accepts` is, so a second mechanism for it was two places a permission could be wrong. The outcome is the seat's own event, which means one publish still reaches whoever asked, the controller that records it and the catalogue that places it — the fan-out a shared exchange gave for free, written as a subject the mesh derived rather than a topology somebody configured. That also avoids the grant that ruled out the alternatives: no holder needs permission to publish into an asker's inbox. The blocking gap is now named rather than incidental: the shared library has no way for a module to publish on a seat. The build machine is Go and reaches the bus directly, so it is unaffected; the artifact-store event waits.
03-DESIGN
The authoritative specification. Implementation is built against what is written here.
Two layers
| Folder | What it is |
|---|---|
00-as-is/ |
The mesh that exists today. Shipped behaviour, described as it is — including behaviour nobody would choose again. |
01-to-be/ |
The mesh being built toward. Every statement traceable to a record in 02-DECISIONS/. |
They are never mixed. A statement about the future does not belong in an as-is document, and an as-is document is never edited to describe an intention.
When a to-be design ships, it does not move. Its as-is counterpart is written or updated,
the to-be document's status becomes implemented, and both stand — one describing what runs,
the other recording what was intended. Deleting the intention loses the reasoning, which is
the expensive half.
Frontmatter
Every design document (not the READMEs) carries:
---
layer: as-is | to-be
status: designed | in-progress | implemented | abandoned
code: [] # owning code repo(s), from 00-META/repos.md
updated: YYYY-MM-DD # date of the last status change, not of text edits
decisions: [] # 02-DECISIONS/ records this document rests on
---
For an as-is document, status: implemented is the normal state — it describes something that
runs — and code: names where that implementation lives.
Status changes when implementation state changes, never because design text was edited. An
implemented claim must be defensible from the owning repository's main branch, not from
intent. If it cannot be checked, it is in-progress.
Cross-cutting views are generated from this frontmatter by the hq-status skill and never
written to disk.
What belongs here
Functional analysis, architectural description, and specification — prose and diagrams
only, no code. A manifest field may be named; a manifest may not be pasted. A document
enters the to-be layer only after the decision behind it is recorded in 02-DECISIONS/
and the research that produced it is closed.
Subfolders are encouraged where a layer grows enough to need them.