ADR 0099: a step that runs once names what it reads; issues 077 and 078 resolved; designs 08 and 20 amended

2026-09-21 23:33:47 +02:00
parent c2a81cbb20
commit 0e0f0298c6
8 changed files with 146 additions and 7 deletions
@@ -0,0 +1,92 @@
+---
+topic: what runs on it
+status: accepted
+date: 2026-09-21
+deciders: jochen
+reconstructed: false
+extends: 0052-a-step-that-runs-once-before-a-container.md
+---
+
+# 99. A step that runs once names what it reads, and runs again when it changed
+
+## Context
+
+[ADR 0098](0098-a-fact-a-provider-makes-at-first-start-is-fetched-from-it.md) has a consumer
+fetch a fact its provider made at first start through a run-once step: the route proxy fetches
+the certificate authority's root before it starts. A run-once step runs once per declaration
+([ADR 0052](0052-a-step-that-runs-once-before-a-container.md)): its marker is the digest of its
+own declaration, and a re-apply that finds the marker does nothing.
+
+The provider can move. When the authority is assigned to another node it makes a new root there,
+and the mesh rewrites the consumer's binding file with the new address — but the step's own
+declaration has not changed, so the step does not run again, the proxy keeps the old root, and it
+refuses every certificate the new authority issues
+([issue 077](../04-ISSUES/077-a-fact-fetched-at-first-start-is-fetched-once/00-report.md)). A
+restart trigger was the natural remedy and was refused on a run-once step, on the ground that a
+step does not stay running to be restarted.
+
+Two things the host already does point at the answer. What a container reads is part of what it
+is: a container's digest includes the digest of every resource it names under `restart-on`, so a
+rewritten file it reads is a changed container
+([issue 045](../04-ISSUES/045-a-container-keeps-the-values-it-started-with/00-report.md)).
+And a run-once step's marker *is* its digest. Nothing new is needed for the step to run again when
+what it reads changed; only the refusal stands in the way.
+
+## Decision
+
+**A run-once step may name what it reads under `restart-on`. For a step the word means *run
+again*: when a named resource changed in this apply, the step's digest has moved, its marker no
+longer matches, and it runs again — gating what follows, as it did the first time.** Nothing
+about the marker changes; the refusal of the pair is lifted, in the control plane and on the host.
+
+**The container that consumes what a step made names the step.** A step that ran counts as a
+change, so a service that names it under `restart-on` is recreated after it, holding what the step
+fetched. Without this the step fetches a new root and the service keeps serving with the old one.
+
+The route proxy's gate names the binding file it reads; the proxy's server names the gate and the
+binding. When the authority moves, the binding is rewritten, the gate fetches the new root, and the
+server is recreated with it — in one apply.
+
+## Considered Options
+
+1. **A provider epoch in the binding — the mesh raises a number when a provider is re-issued or
+   moved, and the consumer's file carries it.** Rejected: the binding already changes when the
+   provider moves (its address does), and a re-issue does not change what the authority serves —
+   its state persists. An epoch would be a second signal for a change the file already shows.
+2. **The step runs before every start of the service, with no marker.** Rejected: every reconcile
+   would run it, and a step that runs on every apply reads as a change on every apply, so the
+   service naming it would be recreated every few minutes.
+3. **The proxy fetches the root itself, at start.** Rejected as the general answer: it fixes the
+   proxy and leaves the next consumer of a fact made at first start to fix itself. The step is the
+   general shape ([ADR 0098](0098-a-fact-a-provider-makes-at-first-start-is-fetched-from-it.md)).
+4. **Lift the refusal and read `restart-on` as *again* on a step.** Adopted: it is what the
+   digest already does, and it needs no new word.
+
+## Consequences
+
+A fact fetched at first start follows its provider when the provider moves. What is not covered:
+a provider whose state is wiped behind the mesh's back, on the same node, makes a new fact that
+nothing the mesh knows reflects. That is not a change the mesh can see, and it is not claimed.
+
+The one contradiction the refusal named is real and is now a documented reading: on a running
+container `restart-on` means recreate, on a step it means run again. Both are "this must reflect
+what it reads".
+
+## How it is checked
+
+- mesh-host: a unit test declares a run-once step naming a file, records its marker against the
+  file's old content, applies with the new content and asserts the step ran; applies again with
+  nothing changed and asserts it did not. A second test declares a container naming a run-once
+  step and asserts the container is recreated after the step ran, with the step as the stated
+  reason.
+- mesh-controller: the manifest parser accepts a run-once step with `restart-on`; the
+  catalogue-wide manifest test parses the route proxy's manifest, whose gate and server name what
+  they read.
+- The route-forwarding bed still passes with the host that accepts the pair. No bed moves the
+  authority: the mechanism is proven by the unit tests, the declaration by the manifest test.
+
+## References
+
+- [issue 077](../04-ISSUES/077-a-fact-fetched-at-first-start-is-fetched-once/00-report.md)
+- [ADR 0052](0052-a-step-that-runs-once-before-a-container.md), [ADR 0053](0053-a-step-that-runs-on-a-schedule.md), [ADR 0098](0098-a-fact-a-provider-makes-at-first-start-is-fetched-from-it.md)
+- [`03-DESIGN/01-to-be/08-connectivity.md`](../03-DESIGN/01-to-be/08-connectivity.md), [`03-DESIGN/01-to-be/20-writing-a-module.md`](../03-DESIGN/01-to-be/20-writing-a-module.md)
@@ -146,6 +146,7 @@ python3 00-META/checks/index.py            fail if stale
 - **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)
 - **0091** — [A mount is declared, and there are three things it can be](0091-a-mount-is-declared-three-ways.md)
+- **0099** — [A step that runs once names what it reads, and runs again when it changed](0099-a-step-that-runs-once-names-what-it-reads.md)

 ### How it is built