jschoubben
b4607dfc03
Decided after measuring what renumbering actually costs: 96 references in code comments across two repositories, none of which would have failed to compile. They would have pointed at the wrong reasoning, which is worse than a broken link because nothing reports it. So a number identifies a record and never changes. It cannot also be a position -- a position moves when the set changes, and an identity that moves is not one. The reading order moves into an index generated from each record's `topic:`. Six topics, in the order somebody learns the system. The index is WRITTEN rather than only generated on demand, which reverses what this repository previously said. The reason it said otherwise is that a hand-written index drifts -- but a reader looking at the folder on a forge sees the folder, not a command, and the drift objection is answered by checking rather than by refusing to write one. That is §5's own rule: a rule states how it is checked. Two checks, both confirmed to bite. index.py fails when the written order no longer matches the records. records.py fails when a record has no topic or one nobody defined -- the quiet failure being a record that vanishes from the order rather than appearing in the wrong place.
100 lines
5.1 KiB
Markdown
100 lines
5.1 KiB
Markdown
---
|
|
topic: checking it
|
|
status: accepted
|
|
date: 2026-08-24
|
|
deciders: jochen
|
|
reconstructed: false
|
|
extends: 0017-a-test-defends-a-decision.md
|
|
---
|
|
|
|
# 18. 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 0017](0017-a-test-defends-a-decision.md) 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](../04-ISSUES/003-firewall-scope-is-read-by-no-code/00-report.md) — 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
|
|
|
|
1. **Draw the declaration, and label it honestly.** Cheap, and useful for review before
|
|
anything is raised. Insufficient alone: it can never disagree with itself.
|
|
2. **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.
|
|
3. **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](../00-META/process/05-constitution-sync.md) 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 0017](0017-a-test-defends-a-decision.md) — a claim nothing checks stops being true.
|
|
- [ADR 0016](0016-the-lab.md) — 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](../04-ISSUES/003-firewall-scope-is-read-by-no-code/00-report.md) — the fault in production
|
|
form.
|