2026-09-05 10:27:11 +00:00
1 changed files with 75 additions and 0 deletions
@@ -0,0 +1,75 @@
 ---
 status: open
 opened: 2026-08-29
 located-in: [mesh-host, mesh-control]
 fixed-by:
 amended-design:
 ---
 # 010 — The first declaration a node receives destroys the substrate it raised
 ## Symptom
 A first node was raised from its carried bundle: container runtime, store, two context databases,
 their schemas, broker, control plane. Eleven resources, all running. It then enrolled against the
 control plane on its own machine, held its link open, and was sent a declaration naming two
 resources — a directory and a file.
 Both were applied correctly. And **every container on the machine was removed**: the store, the
 broker, and the control plane that had sent the declaration. The link died mid-sentence with
 `the link closed: Exception (501) Reason: "EOF"`, because the broker carrying it had just been
 torn down by the message it carried.
 Afterwards `mesh-host owned` listed two resources. The mesh had deleted itself.
 ## What is actually wrong
 Nothing in the code is behaving incorrectly. `apply` removes what the store holds and the incoming
 declaration does not name, which is what reconciliation means — the declaration is the desired
 state, not a patch, and anything else would make it impossible to remove a resource by omission.
 **The fault is that the carried bundle and mesh declarations share one store.** The host cannot
 tell "this machine raised this for itself before there was a mesh" from "the mesh told this
 machine to have this", so the second overwrites the first completely.
 That is invisible until the two meet, which happens exactly once per mesh: on the first node,
 after enrolment, at the moment the control plane first speaks.
 ## Why it matters more than a footgun
 **The first node is the only node where the substrate is not the mesh's doing.** Every other node
 receives everything it runs from the control plane, so a complete declaration is complete by
 construction. The first node raised its own substrate from a file it carried, and the control
 plane has never been told about it — so the control plane cannot include it in a declaration even
 if it wanted to.
 So the first node is left in a state no other node is in, and the ordinary path destroys it.
 ## What is not the answer
 - **Making the control plane send the substrate back.** It does not know what the bundle contained
  and should not: the bundle exists precisely because there was no control plane yet.
 - **Making apply stop removing orphans.** Removal by omission is how a declaration says *stop
  running this*, and losing it costs the property that a node converges on what it was told rather
  than accumulating.
 - **Special-casing the first node.** [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)
  is explicit that its specialness lasts two commands, and this would extend it for ever.
 ## The shape of an answer, not yet chosen
 The store needs to record **where a resource came from** — carried, or declared — and reconcile
 each against its own source. A declaration would then remove only what the mesh previously
 declared, and the bundle would remain the bundle's business until the mesh is told about it.
 That leaves a real question behind it: **what happens when the mesh eventually does declare the
 substrate**, which it must, or the substrate can never be upgraded. Two sources claiming the same
 container is the ambiguity this issue is made of, moved rather than removed.
 ## How it was found
 In the lab, on a sealed machine, by doing the ordinary thing: raise a first node, enrol it, and
 tell it something. It was not a test of this — it was the first end-to-end run of the link, and
 this fell out of it.
 The declaration was two lines and destroyed a working mesh in under a second, which is worth
 holding on to: this is not an edge case reached by trying, it is the first thing that happens.