jschoubben
e1febe8e0f
The consolidation left a sparse sequence -- 1, 4, 6, 7, 9, 10, 12, 15, 16, 18, 19, 25, 34, 35, 36, 37, 40, 42, 44, 45, 48, 49, 58 -- where the gaps were only the archaeology of what used to be there. Renumbered contiguously. Renames run in ascending order, so every target number is already free and no two files ever collide. The reference rewrite is one simultaneous pass rather than a sequence of replacements. Numbers moved into slots other numbers were vacating -- the node host went 37 to 16 while the lab went 16 to 9 -- so replacing one at a time would have cascaded and silently pointed things at the wrong record. Seven plain-text references survived the merges as prose rather than links, naming records that no longer existed: the enrolment token, the link boundary, what a declaration is, reachability, the repository structure. Each mapped to the consolidated record that now holds it. Verified rather than assumed: every [ADR NNNN](path) link now has matching text and target, checked across the whole repository, and the checker passes. Frontmatter `consolidates:` lists dropped -- they named records that are gone, and each consolidated record already says in prose what it absorbed.
99 lines
5.1 KiB
Markdown
99 lines
5.1 KiB
Markdown
---
|
|
status: accepted
|
|
date: 2026-08-24
|
|
deciders: jochen
|
|
reconstructed: false
|
|
extends: 0013-a-test-defends-a-decision.md
|
|
---
|
|
|
|
# 14. 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 0013](0013-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 0013](0013-a-test-defends-a-decision.md) — a claim nothing checks stops being true.
|
|
- [ADR 0009](0009-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.
|