ADR 0043 — what a declaration is

Stage 2 could not start without it. Three constraints already bound the shape
and between them they decide most of it.

JSON, because the standard library carries it and carries no YAML, and a YAML
declaration would put a third-party parser inside the one binary whose whole
argument is that it needs nothing — to gain authoring comfort in a document
generated by a machine and read by a machine.

An ordered list, because ordering is a DECISION. A host deriving order from
declared dependencies would be deciding the thing most likely to differ between
what the control plane intended and what the machine does. The control plane
knows what depends on what; it says so by saying when.

Unknown is refused, never skipped — an unknown version, type or field refuses
the whole declaration. A host that skipped what it did not understand would
apply most of a declaration and report success, which is 04-ISSUES/003 with the
declaration on the other side of the wire.

Complete for what the host OWNS, and only that. It removes what it previously
applied and is no longer declared, which it knows from the store rather than by
inference, and never removes what it did not create — a converger that treats
'not declared' as 'must not exist' deletes what the mesh never put there.

Two consequences arriving earlier than the build order suggested: the store is
load-bearing at stage 2, because nothing can be removed without knowing what was
applied. And a closed address space bounds the first vocabulary to what needs no
network, because a scenario has no route to a package repository.
This commit is contained in:
2026-08-26 02:04:41 +02:00
parent 23232e019a
commit bea052753e
2 changed files with 136 additions and 9 deletions
+23 -9
View File
@@ -11,6 +11,7 @@ decisions:
- 02-DECISIONS/0039-the-link-is-the-security-boundary.md
- 02-DECISIONS/0008-a-failed-step-fails-the-job.md
- 02-DECISIONS/0041-the-host-depends-on-nothing.md
- 02-DECISIONS/0043-a-declaration-is-an-ordered-list-of-owned-resources.md
---
# The node host
@@ -132,15 +133,23 @@ the mesh, and the full peer set arrives derived.
## What a declaration is
**Open, and the first thing to settle in build.** The shape is constrained but not chosen:
Settled by [ADR 0043](../../02-DECISIONS/0043-a-declaration-is-an-ordered-list-of-owned-resources.md).
- It is data, not instructions — the host's vocabulary is finite, versioned and auditable, and
anything outside it is refused rather than best-effort interpreted.
- It is per-node and complete: what this machine should be, not a delta against what it was.
A delta requires the sender to know what the receiver holds, which is the coupling the store
exists to remove.
- Every addition to the vocabulary widens what a compromised control plane can express, so it
is a security artefact and additions are reviewed as such.
**JSON**, because the host has no dependencies to spend and the standard library carries no
YAML. **An ordered list of typed resources**, each with a stable identity — the order is stated
rather than derived, because deriving it would be the host deciding the thing most likely to
differ from what the control plane intended.
**Unknown is refused, never skipped.** An unknown version, type or field refuses the whole
declaration. A host that skipped what it did not understand would apply most of it and report
success.
**Complete for what the host owns, and only that.** It removes what it previously applied and
is no longer declared — a fact it holds, from the store, rather than an inference — and never
removes anything it did not create.
**Addressed.** A host with an identity refuses a declaration addressed elsewhere; a host
without one, applying the bundle it carries, has nothing to check against.
## Build order
@@ -154,6 +163,12 @@ what it is. No control plane, no declarations, no network. Verifiable immediatel
the first node's path, and it is the claim the skeleton's Move 1 rests on and has never proved:
that one host can raise the substrate alone.
The first vocabulary is bounded by something the lab makes unavoidable: **a scenario is a
closed address space**, so a resource that must be fetched cannot be applied there at all. So
stage 2 begins with what needs no network — files, directories, service state — and the types
that need artifacts wait on where those come from, which is open in
[`02-scenario-declaration.md`](02-scenario-declaration.md).
**3 — link and store.** The node connects, receives declarations, and holds what it applied.
**4 — enrolment.** The one genuinely new mechanism in
@@ -182,7 +197,6 @@ Each decision above owes a test:
## Open
- **What a declaration is.** Above; the first thing to settle.
- **Whether one host can raise the substrate alone.** Move 1 assumes it. Stage 2 tests it, and
if it is false the tier boundary moves.
- **What the host carries versus what it finds.** It manages `wg`, `nft`, `pacman`, `docker`;