The builder takes work over the broker, and what is still missing

A build is work, not state, and that is why it does not travel as a declaration: as one it would either rebuild on every reconcile or carry "and I already did this", which is state about an event rather than about a machine. So it has its own queue and the answer comes back correlated. Three properties recorded because they are decisions: acknowledge only once the answer is away, one build at a time, and a failure is a result rather than silence. And the board page is corrected. A build result today is answered to whoever asked and kept nowhere, so a builds view has nothing to read. A record of past builds is the missing piece, not the builder.
2026-08-30 04:06:42 +02:00
parent a625e6c709
commit 4151c28927
2 changed files with 22 additions and 4 deletions
@@ -21,7 +21,7 @@ the other four are about the mesh itself.
 | | what it shows | where it stands here |
 |---|---|---|
 | **the mesh** | every node, what each runs, what each takes from another, module versions | **everything behind it exists** — it is a reader, not a second source |
-| **builds** | a build, its stages, its log | needs the builder |
+| **builds** | a build, its stages, its log | the builder exists; **what is missing is a record of past builds**, since a result is answered to whoever asked and kept nowhere |
 | **sessions** | model sessions, their usage, and switching between accounts | [ADR 0024](../../02-DECISIONS/0024-model-access-is-a-provision.md) |
 | **channels** | nodes messaging each other | the agent layer |

@@ -76,9 +76,27 @@ is not in it. The alternative — the control plane holding a container socket
 one component that can do anything on any machine, which is the property the whole design is
 arranged to avoid.

-So the builder is a module a node runs, given work over the broker like anything else. Today it is
-a command a person runs on such a machine; the mesh records the result identically either way,
-which is what makes the change from one to the other uninteresting.
+So the builder is a program a machine runs, given work over the broker like anything else, holding
+its own credential and nothing more.
+
+**A build is work, not state**, and that is why it does not travel as a declaration. Everything
+else the control plane sends a node is *what you should be*, reconciled forever. A build happens
+once and is finished; as a declaration it would either rebuild on every reconcile or carry "and I
+already did this" — state about an event rather than about a machine.
+
+So it has its own queue, and the answer comes back correlated. **One queue**, so several build
+machines share the work and each request is done exactly once, which a routing key per machine
+would not give.
+
+Three properties of the builder that are decisions:
+
+- **a request is acknowledged only once the answer is away.** A builder that dies mid-build then
+  leaves the work for another machine rather than losing it with nobody ever hearing why
+- **one build at a time.** Five at once against one runtime finishes all five slower than it would
+  have finished the first, and the queue is what shares work between machines
+- **a failure is a result.** A build that fails silently is indistinguishable from a builder that
+  is not running, and those want completely different responses — the same rule the host follows
+  about a service that does not exist

 ## Three properties that are decisions