jschoubben
5e83ac2c22
Jochen: a normal application has 3-5 ADRs, maybe 10 for a large one, and we are at 65. Fair, and the cause is mine -- I recorded every FINDING as a decision rather than every fork in the road. Two merges, both cases where one decision had been split across many records because it was taken over several days rather than at once. 0019 absorbs ten records about how this repository works: what it is and that it is public, the folder flow, the two design layers, the issue front door, status in frontmatter, playbooks, the naming rule, the product name. Those were never ten decisions -- they were one, seen from ten angles as the repository took shape. 0016 absorbs the five about the lab: a node is a virtual machine, a router is scenery, a scenario declares the underlay, a scenario is a closed address space, and the two scenario classes. Same pattern -- one design, split by the order it was worked out in. The consolidated 0019 also raises the bar for what earns a record, since that is what produced 65: a record is warranted when there is a genuine fork -- a direction reversed, an alternative that will be proposed again, something contested. A finding is not a decision, and a bug is certainly not. Everything else belongs in the design document where the reasoning is actually read. The checker earned its place here. Deleting nine records left 13 dangling links across the repository and it named every one, including in AGENTS.md. Nothing was found by reading. Remaining clusters worth the same treatment: the host (8 records), delivery (5), modules (6), connectivity (4), substrate and control plane (4). That would be 52 down to roughly 30.
5.1 KiB
status, date, deciders, reconstructed, extends
| status | date | deciders | reconstructed | extends |
|---|---|---|---|---|
| accepted | 2026-08-24 | jochen | false | 0034-a-test-defends-a-decision.md |
35. A picture of a system is read from the system, never from what asked for it
Context
A scenario declaration is a file. A raised scenario is a set of machines, links and rulesets. The two are supposed to correspond, and the entire value of the lab rests on noticing when they do not — ADR 0034 says a claim nothing checks is a claim that will quietly stop being true.
Drawing a scenario makes that concrete, and forces a choice that looks cosmetic and is not. A diagram of a running system can be produced two ways: parse the declaration and lay it out, or interrogate the system and lay that out. The first is far easier — the declaration is already parsed, already validated, already in memory.
It is also worthless for the only question worth asking of such a picture: is what is running what I asked for? A drawing built from the request and captioned as raised answers that question with the request, which always agrees with itself.
This is the same fault as 04-ISSUES/003 — a firewall key declared in five manifests and read by no code, so a manifest appears to restrict a port and restricts nothing. The declaration was never wrong. Nothing ever asked the system.
Considered options
- Draw the declaration, and label it honestly. Cheap, and useful for review before anything is raised. Insufficient alone: it can never disagree with itself.
- Draw the system, inferring the rest from the declaration where the system is silent. The tempting middle. Rejected — a picture where some facts are observed and some are assumed has no honest caption, and the assumed ones are exactly the interesting ones.
- Two pictures, one layout, neither borrowing from the other. Chosen.
Decision
A picture captioned as raised reads only the running system. It never opens the declaration, not even for a fact the system happens not to record.
Where the hypervisor does not natively hold a fact the picture needs — whether a segment is public, what a gateway translates, whether a machine refuses inbound — the raise records it on the resource as metadata, and the picture reads it back from there.
That recording carries its own rule, which is the substance of this decision rather than an implementation note:
A behavioural tag is written after the behaviour works, never when the resource is created.
Written at creation, a tag restates the request in a new location and inherits none of the authority of having happened. A failed raise deliberately leaves its wreckage standing, so a tag written up front would let a picture of that wreckage badge translation the gateway was never configured to do — reproducing, inside the tool built to catch the fault, exactly the fault.
So: the gateway is tagged after its ruleset applies; the machine after the read-back proves its firewall loaded.
Both pictures render through one layout, so they can be put side by side and the difference read off directly.
Consequences
-
It earned itself on the first comparison. Drawn side by side, every virtual machine in the live picture held no addresses at all. A container's interface carries the name of the device it was configured as; a virtual machine names its own — so joining addresses to devices by name attached every address to a container and none to a VM. Nothing failed; a whole class of machine silently lost its addresses. The two pictures disagreed, so it was visible in seconds. It is now joined on MAC.
-
Raise does more work, and writes metadata it does not itself consume. Accepted: the cost is a few config keys, and it is what makes a raised instance self-describing.
-
A resource raised before a tag existed is missing it. The reader says so rather than filling the gap from the declaration — an untagged link draws as unknown, not as what the file said it should be.
-
The rule generalises past diagrams. Anything reporting on the mesh — a status view, an inventory, a health check — is subject to it. A report assembled from the intended state is not a report.
-
The declared picture stays, and stays useful: it is review before raising, and it is one half of the comparison. It carries no runtime status, because it cannot know any.
-
The constitution sync is now owed. Accepted 2026-08-25, so §5 carries the rule unqualified and playbook 05 is due. Until it runs, the mesh does not enforce this — an unsynced rule is a rule the mesh does not enforce, whatever this document says.
References
- ADR 0034 — a claim nothing checks stops being true.
- ADR 0016 — why the lab must not supply what the mesh is responsible for; the same instinct, applied to facts rather than to configuration.
- 04-ISSUES/003 — the fault in production form.