jschoubben
702efca6bb
HQ held only the to-be. Every reader had to already know the system the decisions were about, and an as-is claim had nowhere to live except inside an intention. Adds 02-DESIGN/00-as-is — eleven documents written from the implementation and the operational record, not from intent, including the parts nobody would choose again. The two existing designs move under 01-to-be. Layers are declared in frontmatter and never mix: a design that ships does not move, its as-is counterpart is written, and both stand. Back-fills adr/0001-0014 for decisions taken in implementation and never recorded — the broker, the module abstraction, the mesh database, managed files, provisioning, migrations, the workspace removal, failing loudly, the constitution, application placement, linking, the employee model, the artifact, the three silos. Each marked reconstructed, dated from the history, and citing the evidence it was recovered from. The two existing records renumber to 0015 and 0016 so the ledger runs oldest first; 0017 extends 0015 to modules outside the core, principle only — the domain list is deliberately not invented here. how-we-build.md becomes the source of the mesh constitution, with a sync playbook, so the enforced copy stops being the only one that is true. Process becomes explicit: five playbooks, eight thin skills that defer to them, a repository map, and AGENTS.md with CLAUDE.md as its include. The five Observations become 04-ISSUES 001-005 where they can be owned and closed. 006 is new and uncomfortable: HQ is not indexed into the knowledge base. That claim is what decision 27 rests on, it was never checked, and the README now says so instead of repeating it. Also corrects the ADR index into something generated, the "02-DESIGN is empty" claim, the VISION.md pointer that did not survive the repo split, and a note asserting the symlink rule was contradicted — it was a misreading; the rule forbids hand-made links, the installer links by design.
3.4 KiB
layer, status, code, updated, decisions
| layer | status | code | updated | decisions | |||
|---|---|---|---|---|---|---|---|
| as-is | implemented |
|
2026-08-23 |
|
Interfaces and observability
How the mesh is reached, and how anyone can tell what it is doing.
Capabilities are the primary interface
The mesh's primary interface is not a web console. It is a set of capabilities, exposed to a session and callable in language.
A capability is contributed by a module and is available on any node, wherever it actually runs: local ones directly, remote ones through a stand-in created at startup that forwards over the broker. The caller does not know the difference, and the credentials never move.
This is the mesh's stated vision made concrete — an agent states an intent and the mesh works out which node holds the thing. It is also why a capability's schema is load-bearing in a way that is easy to underestimate: a parameter name that collides with the transport's own reserved names breaks the call, and a validation-library version mismatch has silently dropped every argument while the call still appeared to succeed.
The board
A web interface presents the mesh — nodes, modules, pipelines, agents, work. It is a view. Its own guidance is that shared logic belongs in the mesh's library rather than inline in the board, precisely so the board does not quietly become a second implementation of the mesh's rules.
Public exposure
Nodes carrying a public name run a reverse proxy as the sole entry point. A module declares the names its interfaces answer on, portably, and the proxy's configuration is generated from those declarations rather than written — generated files are marked as such and anything hand-written beside them is left alone.
Nodes without a public role use a local equivalent with locally-trusted certificates. The generation step degrades quietly on a node with no proxy, which is intended and is one more place where "nothing happened" is the correct outcome and looks identical to a failure.
Certificate issuance currently always targets the public authority's production endpoint,
which consumes real quota for every experiment
(04-ISSUES/004).
Health
Nodes run checks and report. The mesh's health surface answers whether things are up.
What it does not answer is whether they are correct, and that gap is the recurring theme of this whole system: the deploy path reports transport rather than effect, so absence reads as success. A check that confirms a service is running does not confirm the service is running the code that was just deployed, and a node has been left on old code with a version marker that had already advanced.
Thoughts
Every node's daemon runs a periodic loop that surfaces observations from that node's own context. They are stored in the mesh and can inform a session or trigger action.
It is the one part of the mesh that is not request-driven — the mesh noticing things rather than being asked.
The honest summary
Observability tells you the mesh is up. Establishing that it is right currently means reading the operational record and checking by hand.
That is the gap the lab is designed to close
(01-to-be/01-end-to-end-testing.md): a place where a
change can be run end to end and a verdict produced, cheaply enough that producing one is
routine.