ADRs 0087 and 0088; issues 031, 035 and 054 resolved; designs 05, 07 and 18 amended

A seeded file is created once (0087); the foundation filters before anything listens (0088); a machine becomes the last thing it was told (design 05). Each says how it is checked.
2026-09-21 12:11:50 +02:00
parent a211aecdfa
commit ee67f69ef4
9 changed files with 166 additions and 12 deletions
@@ -0,0 +1,63 @@
+---
+topic: what runs on it
+status: accepted
+date: 2026-09-21
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0010-delivery.md
+---
+
+# 87. A seeded file is created once, and what grows in it is not the mesh's
+
+## Context
+
+A declaration is complete for what the host owns, and the host reconciles what is declared
+([ADR 0010](0010-delivery.md)): a file with this content, held to it. That is the only thing a
+manifest could say about a file, and it is the wrong thing for a file a module needs to **exist
+before first start** and something else then legitimately writes into — an access list a
+provisioner appends consumers to and the program persists back, a bootstrap configuration a
+program rewrites. Every reconcile restored the seed behind the running program, erased what had
+grown in it, and reported success
+([issue 035](../04-ISSUES/035-reconciling-a-seed-file-wipes-what-grew-in-it/00-report.md)).
+
+A run-once step ([ADR 0052](0052-a-step-that-runs-once-before-a-container.md)) can write a seed
+only if absent, and that closed the instance for a broker whose seed is a program's job. It left
+the general case: a plain file the mesh writes and never overwrites.
+
+## Considered Options
+
+1. **Two owners never share a file: the provisioner owns it, and first-start ordering is solved
+   another way.** Rejected as the only answer — some software refuses to start without the file,
+   and a module that must ship a program merely to write an empty file has been made to write a
+   program to say one word.
+2. **A create-once semantic on a file.** Adopted.
+
+## Decision
+
+A file resource may say `create-once`. The host writes it when it is absent and, when it is
+present, leaves it entirely alone — content, mode and owner — and reports it as **kept**, not
+corrected. What is in the file then is somebody else's work the mesh asked for. The mesh removes
+nothing it did not create ([ADR 0030](0030-data-outlives-the-mesh-that-declared-it.md)); it now
+also does not overwrite what it created once and handed over.
+
+On the security question ADR 0010 asks of every new resource behaviour: this **narrows** what a
+declaration can do to a machine. A create-once file gives a compromised control plane one fewer
+way to change a machine repeatedly — it can seed, once, and never again.
+
+## Consequences
+
+A module says which of its files are seeds, and the difference is visible in the manifest rather
+than in whether the file happened to be revisited. A later change to a seed's declared content
+does not reach a machine that already has the file; that is the meaning of a seed, and a module
+that needs the new content ships it as a run-once step that migrates the existing file.
+
+## How it is checked
+
+The host's apply tests: a seed is created, grown into by hand, reconciled, and the growth survives
+with the outcome `kept`. The vault bed declares one on a real node, grows it, pushes again, and
+reads it back.
+
+## References
+
+- [issue 035](../04-ISSUES/035-reconciling-a-seed-file-wipes-what-grew-in-it/00-report.md)
+- [ADR 0010](0010-delivery.md), [ADR 0030](0030-data-outlives-the-mesh-that-declared-it.md), [ADR 0052](0052-a-step-that-runs-once-before-a-container.md)
@@ -0,0 +1,60 @@
+---
+topic: the mesh
+status: accepted
+date: 2026-09-21
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0078-the-store-and-broker-are-modules.md
+---
+
+# 88. The foundation filters before anything listens
+
+## Context
+
+Adopting the store and broker as ordinary modules
+([ADR 0078](0078-the-store-and-broker-are-modules.md)) needs them reachable by consumers across
+the mesh, so genesis raises them bound to every interface. The packet filter that decides who may
+reach them is a module too, installed a dozen steps later. Between the two, a control-node facing
+the network has its store and its bus open to anyone who can reach the machine, for the length
+of the install ([issue 054](../04-ISSUES/054-the-adopted-store-and-broker-are-open-before-the-filter/00-report.md)).
+The design's rule — what a port is reachable from is decided by the filter — is enforced by
+nothing for that window.
+
+## Considered Options
+
+1. **Accept the window**: the machine is mid-bootstrap and the exposure matches what the
+   pre-adoption modules had in steady state. Rejected — the whole point of deriving the filter
+   was to stop accepting that.
+2. **Bind narrowly at genesis and widen once the filter exists.** Rejected — a bind change is a
+   recreate of the mesh's store during install, and adoption in place needs the same spec.
+3. **The foundation carries a filter of its own, applied before the store.** Adopted.
+
+## Decision
+
+The foundation bundle installs the packet filter and loads a base ruleset **before the store and
+broker are raised**: drop by default; keep loopback, replies, ping and ssh; keep the mesh's own
+ports a node must reach before it is on the private network — the bus it enrols over and the
+registry it pulls from; and let the container runtime's own networks through the forward chain so
+containers keep working. It is written into the **same table** the filter module later derives, so
+that module replaces it wholesale the moment it can compute one from what the mesh knows, and
+nothing of the base survives to contradict it.
+
+## Consequences
+
+From its first resource a machine being made into a mesh refuses what it will refuse when
+finished; the window closes. What got harder: the base ruleset is static and names two ports the
+mesh's derived one also names — a change to which ports the foundation needs is now made in two
+places, and the bundle's own test says which.
+
+## How it is checked
+
+The installer's bundle test asserts the filter and its load precede the store and broker and that
+the rules name ssh, the bus and the registry and not the store's or broker's client ports. The
+genesis bed probes the machine from outside throughout the install: the store's port is never
+reachable, while the bus becomes reachable.
+
+## References
+
+- [issue 054](../04-ISSUES/054-the-adopted-store-and-broker-are-open-before-the-filter/00-report.md), issue 047
+- [ADR 0078](0078-the-store-and-broker-are-modules.md)
+- [`03-DESIGN/01-to-be/07-the-foundation.md`](../03-DESIGN/01-to-be/07-the-foundation.md)
@@ -86,6 +86,7 @@ python3 00-META/checks/index.py            fail if stale
 - **0003** — [An agent is a persistent employee, not an instance of a pool](0003-agents-are-persistent-employees.md)
 - **0077** — [The parts are named controller, foundation, node — not control plane, substrate, master](0077-the-controller-and-the-foundation.md)
 - **0083** — [One push leaves the mesh consistent](0083-one-push-leaves-the-mesh-consistent.md)
+- **0088** — [The foundation filters before anything listens](0088-the-foundation-filters-before-anything-listens.md)

 ### Its tiers, from the bottom up

@@ -138,6 +139,7 @@ python3 00-META/checks/index.py            fail if stale
 - **0055** — [Model access is answered by a licence, or by a node that hosts the model](0055-model-access-is-answered-by-a-licence-or-a-node.md)
 - **0084** — [Which provider serves a consumer, when the mesh runs more than one](0084-which-provider-serves-a-consumer.md)
 - **0085** — [A secret is a provision, and the vault is the module that provides it](0085-a-secret-is-a-provision.md)
+- **0087** — [A seeded file is created once, and what grows in it is not the mesh's](0087-a-seeded-file-is-created-once.md)

 ### How it is built