vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

docs: describe the recorded meta fan-out pin

Browse source
This commit is contained in:
atlas 2026-10-25 02:05:24 +02:00 • committed by mara
commit 8b255b43a0
2 changed files with 20 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

20
docs/swarm/builder.md
View file

@ -150,10 +150,22 @@ pins the agent's current config (see
[Config changes](../agent-lifecycle/config-changes.md#the-swarms-meta-flake)). A render
equal to the committed `flake.nix` sends no lock.
When a commit moves the pin from one rev to another, the controller sends a
deploy to every agent a hive places, so they rebuild on the new hyperhive. A
restart that moves nothing deploys nothing, and the first commit deploys
nothing.
The controller sends a deploy to every agent a hive places whenever the pin in
`internal/meta` differs from the pin it last sent, so they rebuild on the new
hyperhive. It keeps that pin as the key `pin` in the `meta-fanout` KV bucket,
which only the controller reads or writes, and a `RecordFanout` job writes the
key after every deploy of the fan-out succeeds. The check runs after each update
and once when the controller starts.
- The first commit sends a deploy, because the key holds no pin yet.
- A controller that starts with no key, as after the upgrade that added it,
sends one round. A deploy is idempotent per pin, so the round is harmless.
- A controller that dies after the commit, or a deploy that fails, leaves the
key behind. The next update or start sends the deploys again.
- A restart that finds the key equal to the pin sends nothing.
- When the bucket won't open, or its key won't read, the controller logs a
warning and sends deploys only when its own update moved the pin. That case
writes no key.
## Credentials