push green meta builds to the attic cache and record cached

docs/swarm/builder.md

@@ -103,9 +103,10 @@ status has no link.
   hive's. A green check can therefore still fail on a hive, and the reverse.
 - The agent base is the builder's host's, not the hive's. Hives on another
   hyperhive or nixpkgs pin build something else.
-- The builder pushes nothing. The closure stays in the builder
+- The check pushes nothing. The closure stays in the builder
   host's store until it's collected, so on a host that also runs the hive, the
-  hive's own build can reuse whatever matches.
+  hive's own build can reuse whatever matches. A [meta build](#deploy-gate)
+  can push to [a binary cache](#binary-cache).
 - The PR check gates nothing. A merge deploys whatever the status says. The
   [deploy gate](#deploy-gate) is a separate build, from `internal/meta`.
 - A lost webhook delivery isn't retried: the head isn't built until the next
@@ -247,13 +248,48 @@ On a built reply the controller writes the agent's key in the `agent-closures`
 KV bucket: the `internal/meta` commit, the closure's store path, the builder's
 platform and the time. Only the controller writes the bucket, and the builder
 holds no grant on it. A failed build writes nothing and leaves the previous key.
-Nothing reads the bucket yet. The closure stays unrooted in the builder host's
-store.
+The record's `cached` field says whether the builder pushed the closure to
+[the binary cache](#binary-cache). Nothing reads the bucket yet. The closure stays
+unrooted in the builder host's store.
 
 The controller gives the `builder` forge account read on `internal/meta` when it
 updates the flake, and again before each build, since the repo is private. A
 grant the forge refuses fails the build with no verdict.
 
+## Binary cache
+
+With `services.hyperhive.swarm.attic.domain` and `cache` set, the builder pushes
+each green meta build's closure to that cache, an attic server outside the swarm,
+before it replies. It runs `attic push swarm:<cache> <out path>` once per build,
+not `attic watch`, and the builder pushes again when the controller runs a build again. The
+push has ten minutes, or less when the reply is due sooner, because it must end
+inside the 61 minutes the controller waits. `attic` checks the server's certificate
+against the system roots and pins nothing, so a Let's Encrypt certificate
+works.
+
+The push token is the operator's to write. The builder reads it on every push
+from `secret/swarm/services/attic/push-token` (field `value`), writes an `attic`
+config file holding it in the unit's private runtime directory (`/run/swarm-builder`,
+mode `0700`, the file `0600`), points `attic` at it with `XDG_CONFIG_HOME` and
+removes it after the push. The token is in no argument or variable, so no
+process listing shows it.
+
+The reply's `cached` says whether the push finished. A push that fails, times out
+or can't read the token leaves the build green with `cached` false and logs a
+warning with the reason; the deploy goes ahead and the next build of the agent
+tries again. With no cache set, the builder pushes nothing and `cached` is always
+false.
+
+Mixed versions:
+
+| controller | builder | what happens                                                  |
+| ---------- | ------- | ------------------------------------------------------------- |
+| new        | new     | `cached` in the reply and in the `agent-closures` record      |
+| new        | old     | the reply has no `cached`, which reads as `false`             |
+| old        | new     | the controller ignores `cached`; its record has no such field |
+
+A record written before the field existed also reads as `false`.
+
 ## Credentials
 
 | What                    | Where                                             | Who reads it                                       |
@@ -261,6 +297,7 @@ grant the forge refuses fails the build with no verdict.
 | store leaf              | `deploy.bao.builderClient{Cert,Key}File`          | nspawn, into the service as a credential           |
 | queue client secret     | `secret/swarm/services/swarm-builder/oidc/client` | the builder, at start and when authelia refuses it |
 | forge token (read-only) | `secret/swarm/services/builder/forge/token`       | the builder, on every build                        |
+| cache push token        | `secret/swarm/services/attic/push-token`          | the builder, on every push                         |
 
 The token belongs to the `builder` forge account, which swarm-controller
 creates, puts in the `hives` team of `agent-configs` (read on every config
@@ -270,7 +307,7 @@ gets the token through a credential helper reading the child's environment:
 it's in no argument, URL or lock, so no line `nix` prints can carry it into a
 status. The same `git` fetches a config's own inputs, so the builder registers
 the helper for the forge's URL only, and the helper answers only an `https`
-request for the forge's host: any other host gets nothing. The builder holds no write credential; swarm-controller writes the
+request for the forge's host: any other host gets nothing. The builder holds no forge write credential; swarm-controller writes the
 status with its own forge token. Details per path:
 [`credentials-reference.md`](credentials-reference.md).