hq/02-DECISIONS/README.md

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 reasoning is never rewritten. The reasoning that was rejected is the expensive half to rediscover.

Progressive insight

A record is a decision, not a snapshot of everything that was true the day it was written, and those two fail differently. A fact a record asserted can turn out to be wrong while the decision it supports stays right — a count taken before anyone measured, a file named that does not exist, a proof attributed to a step that cannot run it. Superseding a record for that buries a correct decision under a second one, and teaches every reader to first work out which of two records is live. Done a few times, the reading order stops being one.

So: a correction of fact that leaves the decision standing is made in the record, in place, marked and dated.

Progressive insight — YYYY-MM-DD. What was found, what the record said before, and what it says instead.

Three conditions, all of which hold:

• It corrects a fact, not a judgement. That a suite does not exist is a fact. That building it is the wrong order is a judgement, and judgements supersede.
• It adds; it never quietly replaces. Where body text changes, the note says what stood there before, so a reader who followed a citation to the old wording can find out what happened to it. A correction nobody can see is indistinguishable from a record that was always right, which is the failure the immutability rule exists to prevent.
• The decision, the options weighed and the consequences stand untouched. If the correction changes what was decided, which alternatives were rejected, or a consequence another record relies on, it is not an insight — write the superseding record.

What still supersedes, without exception: reversing a decision, changing its scope, rejecting an option it accepted, or making a consequence false that a later record cites. The test is not how large the edit looks in a diff; it is whether a reader who acted on the old text would now be wrong about what was decided rather than about a detail the decision did not rest on.

How this is checked. 00-META/checks/records.py requires every insight to be marked in the form above and dated no earlier than the record's own date: — an unmarked edit is a rule violation the reviewer looks for in the diff, and a marked one is legible in the record itself. The git history is the backstop, not the record of intent; the note is the record of intent.

A pointer back from what a record changes

A new record naming an old one is not enough. Where a record changes a mechanism an older record states — without reversing the decision, so no supersession — the older record gets a dated note saying where its mechanism now lives. A reader arrives at the old record by following a citation, and finds text that is still the decision and no longer the method; nothing in it says a later record moved the method, and the new record is not in their hands.

The mechanism changed — YYYY-MM-DD, by ADR NNNN. What still stands, what moved, and why.

Three examples of the shape, all found by being missed: ADR 0066 still described a routed name being written into every container after 0148 replaced that with resolution; ADR 0047 still said a module's code runs in a container after 0150 made it a supervised process; and ADR 0016 still read as though the lab were the test bed after 0149 said the live mesh is. Each was a citation leading to the wrong answer, in a record that was not wrong about anything it decided.

This is not machine-checked, and it cannot be from extends: alone. 102 records extend another and 87 name a parent that does not mention them, which is correct: extending usually means building on a context, and a one-directional pointer is the right shape for that. What needs a note is the narrower case where the parent's own text has gone stale, and which case that is, is a judgement — so it is a rule for the author and the reviewer, and the diff is where it is caught. Making it mechanical would mean a record declaring the relationship in its frontmatter, which is a change to the record schema and has not been decided.

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
• 0077 — The parts are named controller, foundation, node — not control plane, substrate, master
• 0083 — One push leaves the mesh consistent
• 0088 — The foundation filters before anything listens
• 0090 — A failure that repeats is said to be stuck
• 0100 — A node in use is adopted before it is converged
• 0101 — A machine's own resolver does not make it in use
• 0102 — The mesh writes into a shared file, never over it
• 0103 — What an adopted node holds, and what its guard refuses
• 0104 — A provision may be answered by an adapter to the predecessor
• 0105 — The mesh adopts the predecessor's tunnel in place
• 0106 — The bus is NATS
• 0116 — The bus is built in five steps, and the protocol moves with it
• 0119 — A taken tunnel's predecessor is retired once the take is proven
• 0125 — The bus is the only broker (superseded)
• 0127 — AMQP is a provision, not the bus (superseded)
• 0128 — The mesh bus is required, not ambient
• 0129 — A seat carries the protocol of its role
• 0130 — The predecessor is ending, and its broker goes with it
• 0131 — Everything on the mesh speaks to the broker seat, and AMQP is not a provision
• 0132 — A seat carries the tools its holder must serve
• 0134 — The mesh says what it applied
• 0142 — The mesh delivers its own components as binaries, not as container images

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
• 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
• 0075 — An artifact store is a provision; a package registry is a different one
• 0078 — The store and the broker are ordinary modules
• 0079 — The foundation seats are named after their servers
• 0092 — An operator delivers a pair credential, and the mesh never replaces it
• 0094 — A module may hold several secrets from one provider, each a pair of its own
• 0095 — The control plane is the way to ask a module
• 0098 — A fact a provider makes at first start is fetched from it, not carried in its manifest
• 0108 — A route carries the policy applied to a request, and names a secret rather than holding one
• 0109 — A package registry seat is one per ecosystem, not one for all of them
• 0126 — A module declares its own seats; the mesh reserves its own
• 0148 — The mesh's names are resolved, not copied into every container

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
• 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
• 0084 — Which provider serves a consumer, when the mesh runs more than one
• 0085 — A secret is a provision, and the vault is the module that provides it
• 0087 — A seeded file is created once, and what grows in it is not the mesh's
• 0091 — A mount is declared, and there are three things it can be
• 0099 — A step that runs once names what it reads, and runs again when it changed
• 0110 — A seat is held by one assignment, from a closed set, and it may deliver a provision
• 0112 — A module definition names no node, no mesh and no path: everything it needs is a requirement the mesh resolves
• 0113 — The vault makes every shared secret, a provider makes resources and data, and the mesh carries both
• 0114 — A credential two parties hold rotates over two credentials; one a single party holds rotates in place, staged; and retiring a credential never removes what it reached
• 0115 — One assignment of a module per node: the module's name is the assignment's identity
• 0117 — A machine's uplink is a seat: the mesh configures the manager, never the link
• 0118 — Undeclaring removes what the mesh made, and gives a unit back the state it was found in
• 0120 — A roster fact carries its format as a template: the mesh owns the data, the module owns the format
• 0121 — A system seat is named for its scope, and a module may define its own
• 0122 — A seat is data the controller owns, and a rename is a database update
• 0133 — A module owns its migrations, and the mesh owns when they run (superseded)
• 0135 — A module version prepares its state before it runs
• 0136 — A step gates its module, not the machine
• 0137 — A machine says which networks it routes (superseded)
• 0138 — An assignment binds an endpoint and says how far it reaches
• 0139 — A network is forwarded because a module declared it (superseded)
• 0140 — The filter constrains what arrives from outside, and says nothing about a machine's own guests
• 0141 — The host delivers its own successor, and versions live side by side
• 0143 — A consumer verifies the grant it is given (superseded)
• 0144 — Anything on a machine may call anything on it, and that is the whole of "local"
• 0145 — A module checks what the mesh claims is reachable, and it checks itself (superseded)
• 0146 — Connectivity is checked by name, per hosting form, with a valid certificate
• 0147 — A module anchors the mesh's authority on a machine, and takes it away again
• 0150 — A module's own code runs as supervised processes under the module's one account

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
• 0039 — What the SDK holds, and what it refuses
• 0068 — The lab takes requests, one at a time, and runs each from its own copy (superseded)
• 0069 — A module is a repository and a path within it
• 0076 — The SDK is a published package, and the toolchain resolves it by version
• 0082 — The registry is reached by name, and the overlay is its security
• 0086 — A secret reaches a process as a file, and an exception is declared
• 0096 — An upstream image is copied between registries, never through a machine's image store
• 0097 — A vendor image is a declared build input, and a recipe fetches nothing undeclared
• 0107 — Persistent data is a directory bind, never a named volume
• 0111 — A build source is on the mesh's git seat, or it is an external repository
• 0149 — The live mesh is the test bed

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
• 0089 — A bed reads the catalogue it proves
• 0093 — A fixture that runs a module's runtime carries the module's name

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
• 0080 — The development cycle is checked, not trusted
• 0081 — A decision nothing cites is not yet in the chain