--- status: proposed date: 2026-08-28 deciders: jochen reconstructed: false extends: 0058-delivery-ends-in-a-declaration.md --- # 63. Delivery is reconciliation, not a pipeline ## Context [ADR 0058](0058-delivery-ends-in-a-declaration.md) stopped *deploy* being a stage that pushes to nodes: the control plane says what should be true, the host reconciles, and the thing that reports is the thing that did the work. It fixed the third silo and left the first two as they were — **and it said plainly what it did not fix:** > **Detection stays the fragile input, and this does not fix it.** *A merge that created no > pipeline, and nothing said so* is upstream of everything here and is untouched. That is not a defect in the detector. It is what happens when a system's correctness depends on an **event arriving**. The as-is records the ways it has failed — a webhook truncating its commit list on a large merge, a forge address whose port broke module-path matching — and the shape is always the same: *nothing happened, and nothing said so.* **The same move that fixed deploy fixes this, applied one level up.** This record is not a better detector. It is the removal of detection as a load-bearing mechanism. **And this is not the current coordinator repaired.** The existing pipeline is a state machine over stages; what follows is not that with better inputs. The old system's value here is as a catalogue of the ways this can fail, and it has been used for exactly that. ## Decision > **The control plane holds what source exists and what has been built from it, and builds the > difference.** A change becomes a build because **source is ahead of artifacts** — a comparison, answerable at any moment — rather than because a message arrived. **An event makes it fast. Nothing makes it necessary.** A push notification is an optimisation that lowers latency; a missed one costs latency and cannot cost correctness. That is the same property the host's drift timer has, and it is the whole point of both. So the mesh is one idea at two layers: | | reconciles | against | |---|---|---| | **the control plane** | artifacts | source | | **the host** | machine state | declarations | **What disappears:** the pipeline as a state machine. There is no stage list something can be omitted from — which is how a verify stage was built and never scheduled — and no run to lose. ## What this answers [Research 008](../01-RESEARCH/008-delivery-coordinator/00-overview.md) asked six questions. Two were answered by [ADR 0058](0058-delivery-ends-in-a-declaration.md); this answers the rest. **What is a deployed state?** Not an event — **two comparisons**, both answerable on demand: does every node's reported state match what is declared, and is what is declared built from current source? A milestone can be claimed by something that did not check. A comparison cannot. **What produces a verdict, and what is it about?** **An artifact, and it gates eligibility.** The mesh must not converge onto something broken, so an artifact may be declared only once something has judged it fit. The lab is what judges. This is sharper than the question expected: a verdict is not a report about a run, it is a property an artifact does or does not have. **How does delivery work before self-hosting?** It mostly stops being a question. A reconciler needs to read source and write artifacts; where those live is a **binding**, external at first and internal later. A pipeline has stages that name their targets, which is why the transition looked hard. ## What survives from ADR 0014 [ADR 0014](0014-build-publish-and-deploy-are-three-silos.md) is a decision about **cardinality**, and the cardinality observation is right and unchanged: building is per module, publishing is per module, and what happens on nodes is per node. What changes is that those are no longer three **silos of a job**. They are steps of reconciling one artifact, and the third is not a step at all any more ([ADR 0058](0058-delivery-ends-in-a-declaration.md)). ## What this costs Named because each is a way this can go wrong, and a decision that lists none has not been examined. - **"Is this artifact current?" must be answerable without building it.** A commit recorded against each artifact does it, and that record becomes load-bearing: wrong, and the mesh either rebuilds forever or never rebuilds at all. - **Rebuild storms.** One change to a shared library makes everything out of date at once. The ordering that today's *levels* provide has to come from the module graph ([research 011](../01-RESEARCH/011-the-module-graph/00-overview.md)), which is designed and not built. - **The run identity people actually use is lost.** *Did my change go out?* is answerable today by opening a pipeline. With convergence there is no run to open, and **something has to replace that** — a query over the two comparisons above — or this will be worse to live with than what it replaces, whatever its properties. - **A loop that will not converge is harder to debug than a job that failed.** A failed job stops and names its step. A reconciler that cannot reach its target retries forever, and without something that notices *this has been trying for an hour*, the failure is silence — which is the fault this record is removing, reintroduced in a new place. **This is the real risk and it is not solved here.** ## Consequences - **Detection stops being correctness and becomes latency.** The specific faults the as-is records — a truncated commit list, a broken path match — become slow rather than silent. - **The coordinator is not ported.** What replaces it is a comparison and a build, and the existing implementation informs it only as a list of things that went wrong. - **Two things must be cheap that are not yet designed**: reading what source exists, and reading what has been built. Both are queries against providers the mesh will host, and both are on the path of everything above. - **Research 008 can close**, which it could not before this. ## References - [ADR 0058](0058-delivery-ends-in-a-declaration.md) — the same move, one level down. - [ADR 0014](0014-build-publish-and-deploy-are-three-silos.md) — the cardinality that survives. - [ADR 0035](0035-a-picture-is-read-from-what-runs.md) — why a comparison beats a claim. - [`00-as-is/04`](../03-DESIGN/00-as-is/04-delivery.md) — the pitfalls this is designed against.