jschoubben
89302aa3e0
Two corrections, both from the operator and both better than what was written. An SDK is an implementation of the mesh's module protocol in one language, and nothing more. The first draft defined it by the test it passes, which describes how you check one rather than what one is — and leaves it sounding like a library that helpers could accumulate in. And the protocol is split per capability, which was missing entirely. A module that only consumes events uses the event capability; one that serves tools uses the tool capability; a provider uses provisioning. Nothing about consuming an event requires knowing how a grant is answered, so an SDK need not implement all of it to be real. That has a precedent here: a host declares which resource kinds it can apply, and a partial host is a real thing rather than a broken one (ADR 0005). An SDK implementing the floor and events is exactly as legitimate, and a module written against it is a module that does events. Which changes what adding a language costs. A Rust SDK doing connection and events is useful the day it exists, with tools and provisioning following when something needs them — rather than a language being unsupported until it is entirely supported, which is what makes adding one a project instead of a contribution. Conformance is therefore per capability too: a monolithic pass or fail would make a partial implementation indistinguishable from a broken one, which is the distinction the whole thing rests on. Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
02-DECISIONS
Architecture decision records — the "why" trail behind the rules in
00-META and the specifications in 03-DESIGN.
Numbered 02 because a decision precedes the design it authorises. Research concludes,
the decision is recorded here, and only then is the design written. Following the folder
numbers walks the process in the order it happens.
One file per decision, numbered, never deleted. A superseded record has its status: changed
and gains a pointer to what replaced it — its text is never edited. The reasoning that was
rejected is the expensive half to rediscover.
The records run in the order the decisions were taken, oldest first.
Every decision is a record. There is no ledger and no index file — if a decision is worth
recording it is worth a record, and if it is not worth a record it is not recorded
(ADR 0019). A "decision" small enough to be one line is
almost always a rule, and a rule belongs in
00-META/how-we-build.md, where it is enforced and keeps the
incident that earned it.
Frontmatter
---
status: proposed | accepted | superseded
date: YYYY-MM-DD # when the decision was taken, not when it was written down
deciders: name
reconstructed: true|false # true when the record was written after the fact from evidence
superseded-by: # 02-DECISIONS/NNNN-....md, when status is superseded
extends: # 02-DECISIONS/NNNN-....md, when this record widens an earlier one
---
Body
# N. Title in plain language
## Context what was true, with evidence
## Considered Options numbered, each with why it was rejected
## Decision what was decided
## Consequences what follows, including what got harder
## References commits, pull requests, knowledge-base entries, prior art
State evidence, not assertion. "Zero of 124 modules declare brain as a dependency"
outranks "the dependency rule is not followed".
Reconstructed records
Records 0001–0014 were written on 2026-08-23, after the decisions they describe. Records 0015 onward were taken as records. Those
decisions were taken in implementation rather than in a document; the records state what was
decided and the evidence it was decided from, and each carries reconstructed: true and says
so in its first lines.
A reconstructed record is not a transcript. Where the deliberation is not recoverable, the options section states what the alternatives were and why the chosen one won on the evidence available — not a discussion that did not happen. Where a date is not establishable it says so rather than guessing.
Index
A number identifies a record and never changes. Records are referenced from outside this repository — code comments, commit messages — so a number that moves invalidates them silently. Renumbering once cost 96 references across two code repositories, and that is why the numbers are now fixed.
So the folder is in creation order, and the reading order lives here. It is generated from
each record's topic: and written, because a reader looking at the folder on a forge sees the
folder rather than a command. The objection to a written index is that it drifts — which is
answered by checking it rather than by refusing to write one:
python3 00-META/checks/index.py --write regenerate
python3 00-META/checks/index.py fail if stale
What the mesh is
- 0001 — The mesh brokers capabilities; nodes host; agents think
- 0002 — Nodes communicate over a message broker, not over HTTP
- 0003 — An agent is a persistent employee, not an instance of a pool
Its tiers, from the bottom up
- 0004 — A node, and how it joins
- 0005 — The node host
- 0006 — The substrate and the control plane
- 0007 — Connectivity
- 0008 — A context owns its store, exclusively
- 0028 — The substrate supplies the control plane and nothing else
- 0029 — A network is a shape, because an action cannot be undone
- 0030 — Data outlives the mesh that declared it
- 0031 — The control plane authenticates nobody, so identity is a module
- 0033 — The substrate is a store and a broker
- 0036 — Bootstrap ends at a usable mesh, and the first credential comes from a person
- 0066 — Public routing is name-agnostic, its names are resolved inside the mesh, and an internal authority can certify them
- 0067 — Genesis is a pivot: a temporary control plane installs the registry that makes it permanent
- 0068 — The lab takes requests, one at a time, and runs each from its own copy (proposed)
- 0069 — A module is a repository and a path within it
- 0070 — The catalogue owns the module graph, and genesis builds rather than carries
- 0071 — Genesis clones from a mesh, and checks what it got
- 0072 — Two graphs, and a build chain that orders itself
- 0073 — The installer carries a builder, and the registry stays where it is
- 0074 — The mesh defines a module protocol; an SDK is an implementation of it (proposed)
What runs on them, and how it gets there
- 0009 — Modules and the graph
- 0010 — Delivery
- 0024 — Model access is a provision, and a licence is a thing with a name
- 0026 — The mesh has a session of its own, and it is the node session's mechanism
- 0027 — A provision names what the consumer is coupled to, not the role it plays
- 0035 — One implementation, several surfaces, and what that costs
- 0038 — The mesh assigns the port, and a module does not care (proposed)
- 0040 — What a module is
- 0041 — Events are a relationship, the lighter sibling of provisioning
- 0042 — The shape of an event on the wire
- 0043 — A module's broker account is scoped by what it emits and consumes
- 0044 — A public name is provisioned, not registered by hand
- 0045 — A machine's firewall is the sum of what its modules listen on
- 0046 — A module's configuration is its assignment's, not its manifest's
- 0047 — A module runs its code as its own process, with its own account
- 0048 — A provider creates the credential the mesh minted, and seals nothing
- 0049 — A consumer's identity is bounded by the tightest backend that must accept it
- 0050 — Model access is vendor-agnostic, and a vendor is an adapter
- 0051 — Shared data is the operator's, and a module is granted access to it
- 0052 — An init step is a container run once to completion, gating what follows
- 0053 — A scheduled step is a container run on a recurring schedule
- 0054 — Model usage is a vendor-neutral record, produced by the adapter, at two grains
- 0055 — Model access is answered by a licence, or by a node that hosts the model
How it is built
- 0011 — Managed files are generated onto nodes and never edited there
- 0012 — The mesh creates no symlinks — a derived file is a copy
- 0013 — Schema and state changes are numbered migrations, in the same language as the code
- 0014 — No workspace — each module is a standalone package consuming published dependencies
- 0015 — Applications live in their own repository; the monorepo is for the mesh
- 0016 — The lab
- 0037 — Where a module lives (proposed)
- 0039 — What the SDK holds, and what it refuses
How it is checked
- 0017 — A test defends a decision
- 0018 — A picture of a system is read from the system, never from what asked for it
How we work
- 0019 — How this repository works
- 0020 — The mesh is governed by a constitution, injected where work is decided
- 0021 — HQ is the source of the mesh constitution
- 0022 — The constitution absorbs what is already enforced
- 0023 — The approval is the checkpoint, not the second pair of hands
- 0025 — The design record is read where it is written, never copied to be found
- 0032 — The local account owns the mesh; a surface delegates to a module (superseded)
- 0034 — The local account owns the mesh, and a web application's login is not that