Merge pull request 'sdk1: the controller's repository is emptied (ADR 0593 §11)' (#491) from feat/sdk1 into main

Nothing runs the controller (unassigned, out of the catalog) and the group's check builds every member; the repository is archived after the delivery. Issue 1126.

Claude-Session: https://claude.ai/code/session_01NcbgfJ9Gum47zkFKWRaovL

.gitignore

@@ -2,9 +2,11 @@
 
 # A built binary. The lab writes one here when pointed at the repository root by mistake;
 # built artifacts belong in build/, which is already ignored.
-/mesh-builder
 /mesh-controller
 /postgres-provisioner
 /redis-provisioner
 # And where `go build` in cmd/mesh-controller leaves it (novox/hq issue 233).
 /cmd/mesh-controller/mesh-controller
+
+# No repository commits its dependencies (issue 1305).
+vendor/

Dockerfile

@@ -1,45 +0,0 @@
-# The Go it builds with, pinned here because genesis builds this file with no arguments (novox/hq
-# issue 223) — the Makefile passes the same digest. A tag older than go.mod asks for is how
-# `make image` broke once before (issue 146).
-ARG GO_BASE=golang@sha256:8ac98ca534ac3f51e1f420a1dd2c15e74c75cfa0f23f3ad27eb5d7236c349a0c
-# The control plane's image — for genesis and the lab only. The mesh runs the controller as a Go
-# bundle the host starts as a process (module.json; novox/hq issue 213), and builds no image of it.
-# Genesis builds this file and raises it as the container the process replaces on the first push
-# (mesh-host internal/bootstrap, novox/hq issue 223).
-#
-# novox/hq ADR 0006: this image is pinned by digest in the bundle the host carries, fetched on a
-# machine where no mesh exists yet, and run before there is anything to check it against. So it
-# holds the program and nothing else — no shell, no package manager, no libc, nothing with a CVE
-# feed of its own. What a person has to audit before trusting a first node is one binary.
-#
-# There are no CA certificates in here on purpose. Nothing it does today makes an outbound TLS
-# connection to a public name: it reaches PostgreSQL on the machine it was raised on, and the
-# broker is verified against a fingerprint pinned in a token rather than against a public root
-# (novox/hq ADR 0004). Adding them "just in case" would put a trust store in the one image whose
-# whole argument is that it contains nothing to reason about.
-
-FROM ${GO_BASE} AS build
-WORKDIR /src
-
-# **Nothing is fetched** (novox/hq to-be 45 Phase 1): every dependency is in vendor/, committed, so
-# the image builds from this repository alone — the host's validator among them, whose module no
-# public proxy is asked for. Dependencies first, so a change to the source does not re-copy them.
-COPY go.mod go.sum ./
-COPY vendor/ vendor/
-
-# `COPY . .` brings `.git` along, so Go is told not to stamp the commit: the version is said by -X, and a
-# rebuild of an unchanged program is the same bytes (novox/hq ADR 0267 rule 6, issue 363).
-COPY . .
-ARG VERSION=development
-RUN CGO_ENABLED=0 GOFLAGS=-mod=vendor GOPROXY=off go build -trimpath -buildvcs=false \
-        -ldflags "-s -w -X main.version=${VERSION}" \
-        -o /mesh-controller ./cmd/mesh-controller
-
-FROM scratch
-COPY --from=build /mesh-controller /mesh-controller
-
-# Numeric because there is no /etc/passwd to look a name up in. Nothing here needs to be root:
-# it opens outbound connections and writes nothing to its own filesystem.
-USER 65534:65534
-
-ENTRYPOINT ["/mesh-controller"]

Makefile

@@ -1,149 +0,0 @@
-# novox/hq ADR 0006 — the control plane, in Go.
-#
-# The image the bundle pins holds the program and nothing else, so the build is static and the
-# container is built FROM scratch. That is not a size optimisation: this image is fetched by
-# digest and run on a machine where no mesh exists to check anything, and everything in it is
-# something a person would have to audit.
-
-VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo development)
-LDFLAGS := -s -w -X main.version=$(VERSION)
-
-# Where `make check` raises PostgreSQL. A high port and a throwaway container: nothing here
-# touches a database anybody else is using. Override PG_PORT if this one is taken -- the first
-# port chosen was already serving something that had been up for six days.
-PG_PORT      ?= 55532
-PG_CONTAINER ?= mesh-controller-check
-PG_IMAGE     ?= postgres:17-alpine
-export MESH_TEST_POSTGRES ?= postgres://postgres:check@127.0.0.1:$(PG_PORT)/postgres?sslmode=disable
-
-.PHONY: build image check test vet fmt postgres postgres-stop clean
-
-build:
-	CGO_ENABLED=0 go build -trimpath -ldflags '$(LDFLAGS)' -o build/mesh-controller ./cmd/mesh-controller
-
-# Tagged 'development' as well as by version, because the lab places images by name and a
-# scenario naming a version would have to be edited on every build. The version tag is what a
-# real bundle pins.
-IMAGE ?= mesh-controller:$(VERSION)
-DEV_TAG ?= mesh-controller:development
-
-# The Go base the image is built on.
-#
-# **`make image` was broken and stayed broken**, because the Dockerfile's fallback base was a Go
-# older than go.mod asks for: every build died at `go mod download` with "go.mod requires go >=
-# 1.26.0", and the pipeline never saw it because the pipeline passes the declared base in. Anybody
-# building the image by hand hit it and had to find the digest themselves (novox/hq 04-ISSUES/146,
-# what it cost).
-#
-# **Pinned here since the manifest stopped building an image** (novox/hq issue 213): the mesh builds
-# the controller as a Go bundle with its own toolchain, and only `make image` — genesis and the lab —
-# still needs a Go base. The digest is the one the manifest declared until then.
-GO_BASE ?= golang@sha256:8ac98ca534ac3f51e1f420a1dd2c15e74c75cfa0f23f3ad27eb5d7236c349a0c
-
-image:
-	@test -n "$(GO_BASE)" || { echo "no GO_BASE; pass GO_BASE=<image>"; exit 1; }
-	docker build --build-arg GO_BASE=$(GO_BASE) --build-arg VERSION=$(VERSION) -t $(IMAGE) -t $(DEV_TAG) .
-	@echo
-	@docker image inspect $(IMAGE) --format 'built {{.RepoTags}}  {{.Size}} bytes'
-
-# The builder ships as an image too, because it is a module the mesh assigns rather than a program
-# somebody starts on a machine by hand.
-BUILDER_IMAGE ?= mesh-builder:$(VERSION)
-BUILDER_DEV_TAG ?= mesh-builder:development
-
-builder-image:
-	@test -n "$(GO_BASE)" || { echo "no GO_BASE; pass GO_BASE=<image>"; exit 1; }
-	docker build --build-arg GO_BASE=$(GO_BASE) -f cmd/mesh-builder/Dockerfile -t $(BUILDER_IMAGE) -t $(BUILDER_DEV_TAG) .
-	@echo
-	@docker image inspect $(BUILDER_IMAGE) --format 'built {{.RepoTags}}  {{.Size}} bytes'
-
-# The provisioner ships as an image too, because it is the thing that makes a sealed credential
-# true on a machine -- and the mesh cannot, having discarded the plaintext.
-PROVISIONER_IMAGE ?= mesh-provision-postgres:$(VERSION)
-PROVISIONER_DEV_TAG ?= mesh-provision-postgres:development
-
-provisioner-image:
-	docker build --build-arg GO_BASE=$(GO_BASE) -f examples/postgres-provisioner/Dockerfile \
-		-t $(PROVISIONER_IMAGE) -t $(PROVISIONER_DEV_TAG) .
-	@echo
-	@docker image inspect $(PROVISIONER_IMAGE) --format 'built {{.RepoTags}}  {{.Size}} bytes'
-
-# The object store's provisioner, for the same reason: a bucket and a policy are not files, and
-# the mesh cannot make them -- it discarded the credential it would have to use.
-OBJECTSTORE_IMAGE ?= mesh-provision-objectstore:$(VERSION)
-OBJECTSTORE_DEV_TAG ?= mesh-provision-objectstore:development
-
-objectstore-image:
-	docker build --build-arg GO_BASE=$(GO_BASE) -f examples/objectstore-provisioner/Dockerfile \
-		-t $(OBJECTSTORE_IMAGE) -t $(OBJECTSTORE_DEV_TAG) .
-	@echo
-	@docker image inspect $(OBJECTSTORE_IMAGE) --format 'built {{.RepoTags}}  {{.Size}} bytes'
-
-# The cache's provisioner, for the same reason as the database's: an ACL user is not a file,
-# and the mesh cannot make one -- it discarded the credential it would have to use.
-REDIS_PROVISIONER_IMAGE ?= mesh-provision-redis:$(VERSION)
-REDIS_PROVISIONER_DEV_TAG ?= mesh-provision-redis:development
-
-redis-provisioner-image:
-	docker build --build-arg GO_BASE=$(GO_BASE) -f examples/redis-provisioner/Dockerfile \
-		-t $(REDIS_PROVISIONER_IMAGE) -t $(REDIS_PROVISIONER_DEV_TAG) .
-	@echo
-	@docker image inspect $(REDIS_PROVISIONER_IMAGE) --format 'built {{.RepoTags}}  {{.Size}} bytes'
-
-# The proxy that turns a route grant into traffic reaching a workload.
-PROXY_IMAGE ?= mesh-route-proxy:$(VERSION)
-PROXY_DEV_TAG ?= mesh-route-proxy:development
-
-proxy-image:
-	docker build --build-arg GO_BASE=$(GO_BASE) -f examples/route-proxy/Dockerfile -t $(PROXY_IMAGE) -t $(PROXY_DEV_TAG) .
-	@echo
-	@docker image inspect $(PROXY_IMAGE) --format 'built {{.RepoTags}}  {{.Size}} bytes'
-
-# The whole check. Raises a database, runs the repository's own check against it -- merge-check.sh,
-# the very script `mesh/repo-check` runs -- and takes the database down again, including when the
-# check fails, which is why the teardown is not conditional and the script's exit status is the
-# target's.
-#
-# **It calls the script rather than restating it** (novox/hq issue 431): this target used to list its
-# own steps, its formatting step walked vendor/ where the script's does not, and it failed on
-# third-party code no change could fix -- so a developer's check and the gate disagreed, and the steps
-# after formatting never ran through it. The script is the one list of steps; this target only gives it
-# a database (MESH_TEST_POSTGRES, exported above).
-#
-# **Packages in parallel, under the race detector, each test on a bus of its own** (internal/testbus),
-# as the script runs them: a bus per test, of the release the mesh runs, makes the suite the same in any
-# order, and the timeout bounds a hang to a failure with a stack, never a stalled gate.
-check: postgres
-	@sh merge-check.sh ; status=$$? ; docker rm -f $(PG_CONTAINER) >/dev/null 2>&1 || true ; exit $$status
-
-# Without a database the store's tests skip rather than fail, so this is the honest subset and not
-# the gate.
-test:
-	go test -timeout 15m ./...
-
-vet:
-	go vet ./...
-
-# Quick steps for a developer, not part of `check`. The directories gofmt reads must be the ones
-# merge-check.sh lists, never `.`, which walks vendor/ (novox/hq issue 431).
-fmt:
-	@unformatted=$$(gofmt -l cmd internal examples) ; \
-	if [ -n "$$unformatted" ] ; then echo "not gofmt'd:" ; echo "$$unformatted" ; exit 1 ; fi
-
-postgres:
-	@docker rm -f $(PG_CONTAINER) >/dev/null 2>&1 || true
-	@docker run -d --name $(PG_CONTAINER) -e POSTGRES_PASSWORD=check \
-		-p 127.0.0.1:$(PG_PORT):5432 $(PG_IMAGE) >/dev/null
-	@printf 'waiting for postgres'
-	@for i in $$(seq 1 60) ; do \
-		if docker exec $(PG_CONTAINER) pg_isready -U postgres >/dev/null 2>&1 ; then \
-			echo ' — ready' ; exit 0 ; fi ; \
-		printf '.' ; sleep 1 ; \
-	done ; \
-	echo ' — never came up' ; docker logs $(PG_CONTAINER) | tail -20 ; exit 1
-
-postgres-stop:
-	@docker rm -f $(PG_CONTAINER) >/dev/null 2>&1 || true
-
-clean:
-	rm -rf build/

README.md

@@ -1,218 +1,7 @@
 # mesh-controller
 
-**Tier 2 of Novox Mesh — the control plane.** Everything that needs to know about more than one
-node.
+The controller ended under issue 1126. Its jobs moved to the parts that ADR 0590 and ADR 0593 name: the indexer, the
+assigner, the provisioner, the grants part and the node-engine. Its last module, route-proxy, moved to mesh-networking.
 
-That is the whole test, and it draws the line the host cannot: the host applies and does not
-decide, *because deciding needs knowledge one machine does not have*. Which nodes should run the
-store, which peers belong in an overlay, whether a node has been unreachable for a week — nobody
-on a single machine can answer any of them.
-
-The reasoning lives in [novox/hq](https://git.novox.be/novox/hq); this repository carries no
-argument that is not settled there.
-
-## What it is not
-
-- **Not the thing that changes machines.** It decides; the host applies. It never reaches into a
-  node except through the host, over the link, in a bounded vocabulary.
-- **Not a database.** There is no mesh database. Each context owns its own store and nothing
-  outside a context touches it — including nodes, which hold no credential to any of them.
-- **Not privileged.** It has no more access to a machine than a declaration can express.
-
-## What exists today
-
-**One context of seven, and one of the things it will do.**
-
-| | |
-|---|---|
-| `inventory` | node records and enrolment tokens — **built, as far as identity** |
-| `identity` | the control plane's signing key, and the keys nodes are known by — **built** |
-| `config`, `connectivity`, `provisioning`, `delivery`, `observability` | not built |
-| the interface every surface speaks to | not built; its shape is not decided |
-
-```
-mesh-controller migrate                    bring each context's schema up to date
-mesh-controller node add <name>            create a node record
-mesh-controller node list                  the nodes this mesh knows about
-mesh-controller token issue --node <name>  a one-time right to join, for an existing record
-mesh-controller token issue --new <name>   create the record and issue for it
-mesh-controller identity show              this control plane's signing key
-mesh-controller broker show                where the broker is, and what to expect there
-mesh-controller version                    what this binary is
-```
-
-`migrate` is **step 3 of the foundation bootstrap** — the step the first node cannot get past, run
-against a database raised moments earlier from the bundle the host carries.
-
-### Tokens, and what they are missing
-
-A token is **a one-time right to join, issued for a node record** — which is where re-enrolment is
-decided, since what an identity binds to is settled when the token is made rather than when it is
-presented.
-
-What is built: the secret is 256 bits from the system's random source, shown once, and **stored
-only as a hash**, so a copy of this database is not a set of working credentials. It is usable
-exactly once and only before it expires, and both are read from the row rather than from a status
-something would have had to write. Issuing again for the same node invalidates the outstanding
-one — two live tokens are two machines able to join as the same node.
-
-Redemption is a single statement that both finds a live token and spends it, so eight concurrent
-attempts on one secret produce exactly one winner. There is a test that runs them.
-
-**A token now carries three of its four parts**, and is one line of base64 a person can copy. The
-signing key is real: an Ed25519 key this control plane generates once and keeps, whose public half
-travels in every token. A node believes a declaration because it carries a signature that key made
-— and pinning only the broker would not do, because it would make the control plane's authority
-transitive, so a compromised broker could forge declarations, and since the host applies whatever
-the link delivers that is the whole machine.
-
-**All four parts are built.** Given `MESH_BROKER_ADDRESS` and `MESH_BROKER_CERTIFICATE`, a token
-carries everything ADR 0004 requires. Without them it carries two, and `token issue` prints it
-**and names what is missing** rather than producing something that looks complete and cannot be
-used.
-
-**The fingerprint is derived from the certificate, never configured.** A configured one can drift
-from the certificate it describes, and a drifted pin is worse than none: every node issued a token
-during the drift refuses to connect, and the failure looks like an attack. It is computed over the
-DER bytes — what a client actually sees on the wire — so the same certificate re-wrapped with
-different line endings still produces the same pin.
-
-### Two contexts, and the rule between them is real
-
-`identity` is the second context and it exists partly to test a claim this repository had made and
-never checked: that a context reaches only its own store. It holds `MESH_STORE_IDENTITY`;
-`inventory` holds `MESH_STORE_INVENTORY`; there is no setting that reaches both and no way to ask
-for one. Run `migrate` with only one and it stops, naming the grant it does not have.
-
-A token needs a node record from one and a signing key from the other. Neither reads the other's
-store — the process holding both grants asks each for its part.
-
-### How a node is known
-
-**The node generates a keypair; the mesh records the public half.** The same principle as SSH, and
-the same rule `08-connectivity` already applies to the overlay keys — which is where this was
-settled all along, though it took being asked directly to notice.
-
-Only the public half is ever stored, and that is the property worth having: **a copy of this
-database grants nothing.** It is a list of who to believe, not a set of credentials, which is what
-makes *compromise of a node is compromise of that node* literally true.
-
-Exactly one key is live per node. Re-enrolment revokes the one it replaced, in the same
-transaction — two live identities for one node record is the stolen-laptop case, with the replaced
-machine still believed. The database enforces it as well as the code, and there is a test running
-six concurrent enrolments that fails when the constraint is removed.
-
-**Not the machine's SSH host key**, though that was the obvious economy. Host keys are regenerated
-by reinstalls and image clones, which would silently un-enrol a node; their lifecycle belongs to
-sshd rather than the mesh; and a partial host has no SSH daemon at all.
-
-## Reaching a store
-
-**A context is granted only what it exclusively owns.** No shared writes, no read-only role on
-another context's store, and no connection string that reaches more than one.
-
-That is a rule about credentials, so it is built as one. There is no mesh-wide connection setting
-and no way to ask for one:
-
-```
-MESH_STORE_INVENTORY=postgres://…/inventory
-```
-
-A process granted `inventory` holds that variable and no other. Reaching another context's store
-is not a matter of restraint — it has no address for it and no credential to present. And it is
-how the rule is *checked*: what a context can reach is visible in the declaration that runs it,
-as the list of variables it was given.
-
-Each context's database is named after the context. There is deliberately no database named for
-the mesh as a whole.
-
-## Migrations
-
-Numbered, embedded in the binary, applied in order, each in a transaction with the row recording
-it. The applying is four lines; the rest is refusals, and the refusals are the point:
-
-| it stops when | because |
-|---|---|
-| a migration that ran has since been edited | the database holds the old version, the repository holds the new one, and nothing holds the difference |
-| a migration is numbered below one that already ran | usually two branches taking the same next number — applying it now runs the schema in an order nobody tested |
-| two migrations share a number | order is the entire guarantee, and two files with one number have none |
-| a file in the directory is not a valid migration name | a misnamed migration would otherwise never run and nothing would say so |
-| a migration is empty | it records that something happened and changes nothing, which cannot be told from a mistake |
-
-All of them stop rather than warn. At the moment any of them is true, nobody knows what the
-database contains, and there is no correct guess about a schema.
-
-Running it again does nothing. Two copies running at once take an advisory lock, so a restart
-during a slow migration does not become two runners racing.
-
-## Building
-
-```
-make build      the binary
-make image      the container image
-make check      gofmt, vet, and every test against a real PostgreSQL
-```
-
-`make check` raises a throwaway PostgreSQL in a container and takes it down afterwards, including
-when the tests fail. Without one the tests that need a database **skip and say so** rather than
-passing quietly — `make test` is the honest subset, not the gate.
-
-Tests run against a real database rather than a fake because what is being tested *is* the
-database's behaviour: that DDL is transactional, that an advisory lock serialises, that a
-checksum mismatch is caught against a record PostgreSQL actually kept. A fake would assert that
-the fake behaves as expected.
-
-Every test here has been confirmed to fail when the behaviour it defends is removed. Two did not,
-when first written, and both are now commented with what they were missing.
-
-## Checks that cross into the host's repository
-
-Two things are agreed between this repository and `novox/mesh-host`, and each is a separate struct
-on each side. A field renamed on one of them fails **silently** — the crossing succeeds and
-something is simply absent — so both are checked by handing one side's real output to the other's
-real parser. Neither runs by default; each skips with a reason, because a repository that fails
-without its neighbour checked out is a repository nobody can build.
-
-**What this mesh sends, read by the host that receives it:**
-
-```
-mesh-controller:  ./build/mesh-controller plan <node> --json > /tmp/d.json
-mesh-host:     MESH_EMITTED=/tmp/d.json go test ./internal/declaration/ -v
-```
-
-**What a node says when it joins, read by this mesh:**
-
-```
-mesh-host:     MESH_ENROL_OUT=/tmp/enrol.json go test ./internal/link/
-mesh-controller:  MESH_ENROL=/tmp/enrol.json make check
-```
-
-The second does more than compare shapes: it seals something to the key that arrived and opens it
-with the private half the host kept. A key that is present, correctly named and simply *wrong*
-passes every check that only looks at the message.
-
-## The image
-
-**The mesh no longer runs the controller from it** (novox/hq issue 213). The module declares a Go
-bundle, `controller`, which the host on the controller's machine unpacks and runs as the process
-`mesh-controller` under the account of the same name (ADR 0188 §1, §3). The image stays for what
-still runs a container of the controller: genesis, which raises the first controller from it and
-installs the module from its manifest (mesh-host `internal/bootstrap`), and the lab. Neither is the
-mesh's own build any more — `make image` builds it.
-
-`FROM scratch`, holding one statically linked binary and nothing else — no shell, no package
-manager, no libc, no CA certificates.
-
-Not a size optimisation. The bundle a host carries pins this image by digest, and it is fetched
-and run on a machine where no mesh exists to check anything and a person is expected to have read
-the bundle and believed it. Everything in the image is something that person would have to audit.
-
-## Where the reasoning lives
-
-| | |
-|---|---|
-| what the control plane is | novox/hq ADR 0006 |
-| what it takes to run one, and why Go | novox/hq ADR 0006 |
-| a context owns its store, exclusively | novox/hq ADR 0008 |
-| schema changes are numbered migrations | novox/hq ADR 0013 |
-| a test defends a decision | novox/hq ADR 0017 |
+This repository holds no code and is archived once the delivery of the group that emptied it (release sdk1) is done.
+Its history stays here for reading.

cmd/mesh-builder/Dockerfile

@@ -1,22 +0,0 @@
-ARG ALPINE_BASE=alpine:3
-ARG GO_BASE=golang:1.25-alpine
-# The builder, as a module ships one.
-#
-# Not FROM scratch, unlike the control plane: this one runs git and a container client, so it
-# needs a filesystem with them on it. That is the honest cost of a machine whose job is to build —
-# and it is why building is a MODULE on a machine that has a runtime rather than something the
-# control plane does (novox/hq ADR 0005).
-FROM ${GO_BASE} AS build
-WORKDIR /src
-COPY go.mod go.sum ./
-RUN go mod download
-COPY . .
-RUN CGO_ENABLED=0 go build -trimpath -buildvcs=false -ldflags '-s -w' -o /mesh-builder ./cmd/mesh-builder
-
-FROM ${ALPINE_BASE}
-# git to clone what it is asked to build, and the docker client to build and push it. The daemon
-# is the machine's, reached through its socket — a build machine shares the runtime it was given
-# rather than running one inside itself.
-RUN apk add --no-cache git docker-cli
-COPY --from=build /mesh-builder /usr/local/bin/mesh-builder
-ENTRYPOINT ["/usr/local/bin/mesh-builder"]

cmd/mesh-builder/holder.go

@@ -1,433 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/nats-io/nats.go/micro"
-
-	"github.com/novox/mesh-controller/internal/builder"
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// What a holder of the build seat answers for, on its own machine (novox/hq ADR 0219).
-//
-// **The queue is the controller's; the build running here is this machine's.** The controller can
-// see and change what waits in the seat's queue, but an ask a holder already took is a process tree
-// on this machine and containers in this machine's runtime, and only this machine can end them. So
-// the holder serves four verbs on the seat's subjects for this machine: what it is building, kill
-// it, pause, resume.
-//
-// **One build at a time** (ADR 0190), which is also what builder.Said assumes — a package global
-// set per build — so "the build running here" is one or none, and kill names it by id so a call
-// that arrives as one build ends and the next begins cannot end the wrong one.
-
-// holder is this machine's state as a holder of the build seat.
-type holder struct {
-	on, seat string
-	// workspace is where the paused flag is kept, so a holder restarted while paused stays paused
-	// rather than silently taking work again.
-	workspace string
-	// say publishes this machine's state: whether it takes work (link.HolderState).
-	say func(link.HolderState) error
-	// remove runs what a kill needs outside the build: the containers left behind.
-	remove builder.Runner
-	// scratch is where check builds are kept (novox/hq ADR 0350 §5): what the week's sweep lets go of. Nil where
-	// this machine publishes to no artifact store.
-	scratch builder.Scratch
-
-	mu      sync.Mutex
-	paused  bool
-	running *running
-}
-
-// running is the build this machine is doing.
-type running struct {
-	request link.BuildRequest
-	step    string
-	started time.Time
-	cancel  context.CancelFunc
-	killed  bool
-	// returned is the build's own work having ended, before a kill or not; outcome is what was then
-	// announced, and announced whether it went out.
-	returned  bool
-	outcome   string
-	announced bool
-	done      chan struct{}
-}
-
-// pausedFile is where the flag lives in the workspace.
-func pausedFile(workspace string) string { return filepath.Join(workspace, ".mesh-builder-paused") }
-
-// newHolder reads the paused flag the workspace keeps.
-func newHolder(on, seat, workspace string, say func(link.HolderState) error) *holder {
-	h := &holder{on: on, seat: seat, workspace: workspace, say: say, remove: plainRun}
-	if _, err := os.Stat(pausedFile(workspace)); err == nil {
-		h.paused = true
-	}
-	return h
-}
-
-// Paused is asked by the taking loop before every fetch.
-func (h *holder) Paused() bool {
-	h.mu.Lock()
-	defer h.mu.Unlock()
-	return h.paused
-}
-
-// setPaused records the flag in the workspace first and then in memory, so what this holder says
-// it is and what it would be after a restart never differ.
-func (h *holder) setPaused(paused bool) error {
-	path := pausedFile(h.workspace)
-	if paused {
-		if err := os.MkdirAll(h.workspace, 0o755); err != nil {
-			return err
-		}
-		if err := os.WriteFile(path, []byte(time.Now().UTC().Format(time.RFC3339)+"\n"), 0o644); err != nil {
-			return fmt.Errorf("cannot keep the paused flag in %s: %w", path, err)
-		}
-	} else if err := os.Remove(path); err != nil && !errors.Is(err, os.ErrNotExist) {
-		return fmt.Errorf("cannot remove the paused flag %s: %w", path, err)
-	}
-	h.mu.Lock()
-	h.paused = paused
-	h.mu.Unlock()
-	h.announce()
-	return nil
-}
-
-// announce says whether this machine takes work. Never fatal: the flag is kept either way, and the
-// controller reading an older state is a plan read as late rather than a build lost.
-func (h *holder) announce() {
-	if h.say == nil {
-		return
-	}
-	if err := h.say(link.HolderState{On: h.on, Paused: h.Paused(), At: time.Now().UTC().Format(time.RFC3339Nano)}); err != nil {
-		fmt.Fprintf(os.Stderr, "cannot say whether this machine takes builds: %v\n", err)
-	}
-}
-
-// stateWhilePaused says this machine's state at start, and again every while it stays paused, so
-// a pause outlives the events stream's retention.
-func (h *holder) stateWhilePaused(ctx context.Context, every time.Duration) {
-	h.announce()
-	tick := time.NewTicker(every)
-	defer tick.Stop()
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-tick.C:
-			if h.Paused() {
-				h.announce()
-			}
-		}
-	}
-}
-
-// expireChecks lets go of every check build older than a week (novox/hq ADR 0350 §5), at start and every while
-// after. Every holder sweeps the one store; what one let go of, another finds gone.
-func (h *holder) expireChecks(ctx context.Context, every time.Duration, now func() time.Time) {
-	sweep := func() {
-		if h.scratch == nil {
-			return
-		}
-		n, err := h.scratch.Expire(ctx, builder.CheckBuildsKept, now())
-		switch {
-		case err != nil:
-			fmt.Fprintf(os.Stderr, "check builds older than %s: %d let go of, and not all: %v\n", builder.CheckBuildsKept, n, err)
-		case n > 0:
-			fmt.Fprintf(os.Stderr, "check builds older than %s: %d check(s)' builds let go of\n", builder.CheckBuildsKept, n)
-		}
-	}
-	sweep()
-	tick := time.NewTicker(every)
-	defer tick.Stop()
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-tick.C:
-			sweep()
-		}
-	}
-}
-
-// begin records the build this machine took, with the cancel that ends it.
-func (h *holder) begin(request link.BuildRequest, cancel context.CancelFunc) *running {
-	r := &running{request: request, started: time.Now(), cancel: cancel, done: make(chan struct{})}
-	h.mu.Lock()
-	h.running = r
-	h.mu.Unlock()
-	return r
-}
-
-// end clears it, and lets a kill waiting on it know it is over.
-func (h *holder) end(r *running) {
-	h.mu.Lock()
-	if h.running == r {
-		h.running = nil
-	}
-	h.mu.Unlock()
-	close(r.done)
-}
-
-// stepped records the step a build is at, for `current`.
-func (h *holder) stepped(r *running, step string) {
-	h.mu.Lock()
-	r.step = step
-	h.mu.Unlock()
-}
-
-// currentBuild is what `current` answers.
-type currentBuild struct {
-	On      string `json:"on"`
-	Paused  bool   `json:"paused"`
-	Running *struct {
-		ID         string `json:"id"`
-		Repository string `json:"repository"`
-		Path       string `json:"path,omitempty"`
-		Ref        string `json:"ref,omitempty"`
-		Step       string `json:"step,omitempty"`
-		Started    string `json:"started"`
-		Elapsed    string `json:"elapsed"`
-	} `json:"running,omitempty"`
-	Said string `json:"said"`
-}
-
-func (h *holder) current() currentBuild {
-	h.mu.Lock()
-	defer h.mu.Unlock()
-	out := currentBuild{On: h.on, Paused: h.paused}
-	taking := "taking builds"
-	if h.paused {
-		taking = "paused, taking no new build"
-	}
-	if h.running == nil {
-		out.Said = fmt.Sprintf("%s is building nothing; %s", h.on, taking)
-		return out
-	}
-	r := h.running
-	elapsed := time.Since(r.started).Round(time.Second)
-	out.Running = &struct {
-		ID         string `json:"id"`
-		Repository string `json:"repository"`
-		Path       string `json:"path,omitempty"`
-		Ref        string `json:"ref,omitempty"`
-		Step       string `json:"step,omitempty"`
-		Started    string `json:"started"`
-		Elapsed    string `json:"elapsed"`
-	}{r.request.ID, r.request.Repository, r.request.Path, r.request.Ref, r.step,
-		r.started.UTC().Format(time.RFC3339), elapsed.String()}
-	out.Said = fmt.Sprintf("%s is building %s (%s) at %s for %s; %s",
-		h.on, r.request.Repository, r.request.ID, orNothing(r.step), elapsed, taking)
-	return out
-}
-
-// The bounds a kill keeps: each pass removing containers, and the wait for the build to end between
-// them. The worst case — 15s, 20s, 15s — is inside what the controller waits for the answer
-// (killAnswer in the controller's queue.go, 75s).
-var (
-	killRemoves = 15 * time.Second
-	killWaits   = 20 * time.Second
-)
-
-// kill ends the build with this id, if it is the one running here and still working: its context
-// cancelled — which kills each command's process group — and the containers it started removed by
-// their label, once at once and again after the build has ended, so one created while it was being
-// killed is not left. The build's own goroutine announces it failed, killed by hand, and settles the
-// ask so it is not redelivered; the answer says whether that happened.
-func (h *holder) kill(id string) (string, error) {
-	h.mu.Lock()
-	r := h.running
-	if r == nil || r.request.ID != id {
-		doing := "nothing"
-		if r != nil {
-			doing = r.request.ID
-		}
-		h.mu.Unlock()
-		return "", fmt.Errorf("%s is not building %s; it is building %s. `queue` says where an ask is", h.on, id, doing)
-	}
-	if r.returned {
-		h.mu.Unlock()
-		return "", fmt.Errorf("%s on %s has already ended on its own and is saying how; `builds` shows it", id, h.on)
-	}
-	r.killed = true
-	cancel, done := r.cancel, r.done
-	h.mu.Unlock()
-
-	cancel()
-	removed, removeErr := h.removeContainers(id)
-	ended := false
-	select {
-	case <-done:
-		ended = true
-	case <-time.After(killWaits):
-	}
-	again, againErr := h.removeContainers(id)
-	removed += again
-	if removeErr == nil {
-		removeErr = againErr
-	}
-	containers := fmt.Sprintf("%d container(s) it started removed", removed)
-	if removeErr != nil {
-		containers = "its containers could not all be listed or removed: " + removeErr.Error()
-	}
-	if !ended {
-		return fmt.Sprintf("killed %s on %s: %s; the build has not finished ending yet — `builds` says when "+
-			"its outcome is in", id, h.on, containers), nil
-	}
-	h.mu.Lock()
-	outcome, announced := r.outcome, r.announced
-	h.mu.Unlock()
-	if !announced {
-		return fmt.Sprintf("killed %s (%s) on %s: its commands ended and %s, and its outcome could not be "+
-			"announced — the ask is not settled and will be handed out again", id, r.request.Repository, h.on,
-			containers), nil
-	}
-	return fmt.Sprintf("killed %s (%s) on %s: its commands ended, %s, and its outcome announced as failed, %s — "+
-		"settled, so it is not handed to another machine", id, r.request.Repository, h.on, containers, outcome), nil
-}
-
-// removeContainers is one pass of removing what the build left, bounded.
-func (h *holder) removeContainers(id string) (int, error) {
-	cleanup, stop := context.WithTimeout(context.Background(), killRemoves)
-	defer stop()
-	return builder.RemoveContainersOf(cleanup, h.remove, id)
-}
-
-// removeLeftBehind removes, once, what earlier holders on this machine left — called before anything is
-// taken, so none of it is this holder's — and says what it did. A runtime that cannot be asked is said
-// and the holder takes work all the same: what is left is waste, not a reason to stop building.
-func (h *holder) removeLeftBehind() int {
-	cleanup, stop := context.WithTimeout(context.Background(), killRemoves)
-	defer stop()
-	n, err := builder.RemoveLeftBehind(cleanup, h.remove)
-	switch {
-	case err != nil:
-		fmt.Fprintf(os.Stderr, "could not look for containers earlier builds left on %s: %v\n", h.on, err)
-	case n > 0:
-		fmt.Fprintf(os.Stderr, "removed %d container(s) earlier builds left on %s\n", n, h.on)
-	}
-	return n
-}
-
-// returned records that the build's work ended, and says whether a kill came first — only then is
-// the build killed; an error it ended with on its own is its own outcome.
-func (h *holder) returned(r *running) bool {
-	h.mu.Lock()
-	defer h.mu.Unlock()
-	r.returned = true
-	return r.killed
-}
-
-// said records the outcome announced, and whether it went out, for a kill to answer with.
-func (h *holder) said(r *running, outcome string, announced bool) {
-	h.mu.Lock()
-	r.outcome, r.announced = outcome, announced
-	h.mu.Unlock()
-}
-
-// handlers are the seat's verbs, as this machine answers them.
-func (h *holder) handlers() map[string]link.ToolHandler {
-	return map[string]link.ToolHandler{
-		"current": func(context.Context, json.RawMessage) (any, error) { return h.current(), nil },
-		"kill": func(_ context.Context, raw json.RawMessage) (any, error) {
-			var args struct {
-				ID string `json:"id"`
-			}
-			if err := json.Unmarshal(raw, &args); err != nil || strings.TrimSpace(args.ID) == "" {
-				return nil, errors.New("kill needs the build's id")
-			}
-			said, err := h.kill(strings.TrimSpace(args.ID))
-			if err != nil {
-				return nil, err
-			}
-			return map[string]any{"said": said}, nil
-		},
-		"pause": func(context.Context, json.RawMessage) (any, error) {
-			if err := h.setPaused(true); err != nil {
-				return nil, err
-			}
-			said := h.on + " is paused: it takes no new build until resumed"
-			if c := h.current(); c.Running != nil {
-				said += "; " + c.Running.ID + " runs on and finishes"
-			}
-			return map[string]any{"said": said, "paused": true}, nil
-		},
-		"resume": func(context.Context, json.RawMessage) (any, error) {
-			if err := h.setPaused(false); err != nil {
-				return nil, err
-			}
-			return map[string]any{"said": h.on + " takes builds again", "paused": false}, nil
-		},
-	}
-}
-
-func orNothing(s string) string {
-	if s == "" {
-		return "its start"
-	}
-	return s
-}
-
-// plainRun runs a command outside any build: no line reaches a build's log, because the build whose
-// log it would be is the one being ended.
-func plainRun(ctx context.Context, dir, name string, args ...string) (string, error) {
-	cmd := exec.CommandContext(ctx, name, args...)
-	cmd.Dir = dir
-	out, err := cmd.CombinedOutput()
-	if err != nil {
-		return string(out), fmt.Errorf("%s %s: %w: %s", name, strings.Join(args, " "), err, strings.TrimSpace(string(out)))
-	}
-	return string(out), nil
-}
-
-// announcement is what this holder answers discovery with (novox/hq ADR 0195, ADR 0197): this
-// machine's verbs of the seat, in the shape every tool runtime announces a seat's verb — kind seat,
-// the module answering, the seat, scope node, the machine, its description and argument schema — so
-// the console finds `<node>/node-build-agent.kill` by searching, as it finds any seat's verb.
-//
-// One service per machine, named for the seat and identified by the machine, so the answer is this
-// machine's four verbs and nothing more. The verbs are the compiled seat row's: a build machine has no
-// store, and what it serves is what this binary was built to serve.
-func announcement(seat, module, node string) micro.Info {
-	s, _ := catalogue.SeatNamed(seat)
-	var endpoints []micro.EndpointInfo
-	for _, v := range s.Serves {
-		schema, _ := json.Marshal(v.Input)
-		endpoints = append(endpoints, micro.EndpointInfo{
-			Name:    seat + "__" + v.Name,
-			Subject: link.NodeSeatToolSubject(seat, v.Name, node),
-			// The queue group the verbs are served in, as every runtime announces its own.
-			QueueGroup: "seat." + seat,
-			Metadata: map[string]string{
-				"kind": "seat", "module": module, "tool": v.Name, "seat": seat, "scope": "node",
-				"node": node, "interchangeable": "false", "description": v.Description, "schema": string(schema),
-			},
-		})
-	}
-	return micro.Info{
-		ServiceIdentity: micro.ServiceIdentity{Name: seat, ID: node, Version: "0.1.0",
-			Metadata: map[string]string{"seat": seat, "scope": "node", "node": node, "module": module}},
-		Description: "what the build running on " + node + " is, and ending, pausing and resuming it (novox/hq ADR 0219)",
-		Endpoints:   endpoints,
-	}
-}
-
-// moduleOf is the module a credential was issued for: its user is `<node>.<module>`.
-func moduleOf(user string) string {
-	if _, module, ok := strings.Cut(user, "."); ok && module != "" {
-		return module
-	}
-	return "build-agent"
-}

cmd/mesh-builder/holder_test.go

@@ -1,172 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// A holder paused stays paused across its restart: the flag is kept in its workspace (novox/hq ADR
-// 0219), and what it says about itself follows.
-func TestAPausedHolderStaysPausedAcrossARestart(t *testing.T) {
-	workspace := t.TempDir()
-	var said []link.HolderState
-	h := newHolder("ace", link.TheBuildMachine, workspace, func(s link.HolderState) error {
-		said = append(said, s)
-		return nil
-	})
-	if h.Paused() {
-		t.Fatal("a new holder starts paused")
-	}
-	if _, err := h.handlers()["pause"](context.Background(), json.RawMessage(`{}`)); err != nil {
-		t.Fatal(err)
-	}
-	if !h.Paused() || len(said) != 1 || !said[0].Paused || said[0].On != "ace" {
-		t.Fatalf("paused: %v, said %+v", h.Paused(), said)
-	}
-	again := newHolder("ace", link.TheBuildMachine, workspace, nil)
-	if !again.Paused() {
-		t.Fatal("restarted, the holder forgot it was paused")
-	}
-	if _, err := again.handlers()["resume"](context.Background(), json.RawMessage(`{}`)); err != nil {
-		t.Fatal(err)
-	}
-	if newHolder("ace", link.TheBuildMachine, workspace, nil).Paused() {
-		t.Fatal("resumed, the holder came back paused")
-	}
-}
-
-// kill ends the build with that id — its context, which ends its commands — removes what it left by
-// label, and refuses an id it is not building.
-func TestKillEndsTheBuildRunningHereAndNoOther(t *testing.T) {
-	h := newHolder("ace", link.TheBuildMachine, t.TempDir(), nil)
-	var removed []string
-	h.remove = func(_ context.Context, _ string, name string, args ...string) (string, error) {
-		removed = append(removed, name+" "+strings.Join(args, " "))
-		if args[0] == "ps" {
-			return "c1\n", nil
-		}
-		return "", nil
-	}
-	kill := h.handlers()["kill"]
-	if _, err := kill(context.Background(), json.RawMessage(`{"id":"build-1"}`)); err == nil {
-		t.Fatal("killed a build while none ran")
-	}
-
-	building, cancel := context.WithCancel(context.Background())
-	r := h.begin(link.BuildRequest{ID: "build-1", Repository: "novox/a"}, cancel)
-	h.stepped(r, "image")
-	if c := h.current(); c.Running == nil || c.Running.ID != "build-1" || c.Running.Step != "image" {
-		t.Fatalf("current says %+v", c)
-	}
-	if _, err := kill(context.Background(), json.RawMessage(`{"id":"build-2"}`)); err == nil ||
-		!strings.Contains(err.Error(), "build-1") {
-		t.Fatalf("killed another id: %v", err)
-	}
-	// The build's own goroutine: it ends when its context does, as a build's commands do, and
-	// announces what came of it.
-	go func() {
-		<-building.Done()
-		if h.returned(r) {
-			h.said(r, link.KilledByHand, true)
-		}
-		h.end(r)
-	}()
-	answer, err := kill(context.Background(), json.RawMessage(`{"id":"build-1"}`))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if building.Err() == nil {
-		t.Fatal("the build's context was not cancelled")
-	}
-	if !r.killed {
-		t.Error("the build is not marked killed, so it would be announced as an ordinary failure")
-	}
-	said := answer.(map[string]any)["said"].(string)
-	if !strings.Contains(said, "2 container(s)") || !strings.Contains(said, "announced as failed") || !strings.Contains(said, link.KilledByHand) {
-		t.Errorf("kill said %q", said)
-	}
-	// Removed at the kill and again once the build had ended: a container made in between is caught.
-	if len(removed) != 4 || !strings.Contains(removed[0], "label=mesh.build=build-1") || !strings.Contains(removed[2], "label=mesh.build=build-1") {
-		t.Errorf("removed %v", removed)
-	}
-	if c := h.current(); c.Running != nil {
-		t.Errorf("after the kill current says %+v", c)
-	}
-}
-
-// A holder announces this machine's verbs of the seat as the console reads a seat's verb, and no more.
-func TestAHolderAnnouncesItsMachinesVerbsForTheConsole(t *testing.T) {
-	info := announcement(link.TheBuildMachine, moduleOf("ace.build-agent"), "ace")
-	if info.Name != "node-build-agent" || info.ID != "ace" || len(info.Endpoints) != 4 {
-		t.Fatalf("announced %s/%s with %d endpoints", info.Name, info.ID, len(info.Endpoints))
-	}
-	kill := info.Endpoints[1]
-	md := kill.Metadata
-	if kill.Subject != "mesh.seat.node-build-agent.tool.kill.ace" || kill.QueueGroup != "seat.node-build-agent" || md["kind"] != "seat" || md["seat"] != "node-build-agent" ||
-		md["scope"] != "node" || md["node"] != "ace" || md["tool"] != "kill" || md["module"] != "build-agent" ||
-		!strings.Contains(md["description"], "killed by hand") || !strings.Contains(md["schema"], `"id"`) {
-		t.Fatalf("kill is announced as %+v", kill)
-	}
-	body, err := json.Marshal(info)
-	if err != nil || len(body) > 8*1024 {
-		t.Fatalf("the answer is %d bytes (%v)", len(body), err)
-	}
-}
-
-// A build that ended on its own as the kill arrived says what it did: the kill is refused, and its
-// own error is its outcome. One whose outcome could not be announced is not said to be settled.
-func TestAKillArrivingAfterTheBuildEndedIsRefusedAndAnUnannouncedKillSaysSo(t *testing.T) {
-	h := newHolder("ace", link.TheBuildMachine, t.TempDir(), nil)
-	h.remove = func(context.Context, string, string, ...string) (string, error) { return "", nil }
-	_, cancel := context.WithCancel(context.Background())
-	r := h.begin(link.BuildRequest{ID: "build-1"}, cancel)
-	if killed := h.returned(r); killed {
-		t.Fatal("a build nobody killed reads as killed")
-	}
-	if _, err := h.kill("build-1"); err == nil || !strings.Contains(err.Error(), "ended on its own") {
-		t.Fatalf("killed a build that had ended: %v", err)
-	}
-	h.end(r)
-
-	building, cancel := context.WithCancel(context.Background())
-	r = h.begin(link.BuildRequest{ID: "build-2"}, cancel)
-	go func() {
-		<-building.Done()
-		if h.returned(r) {
-			h.said(r, link.KilledByHand, false)
-		}
-		h.end(r)
-	}()
-	said, err := h.kill("build-2")
-	if err != nil || strings.Contains(said, "announced as failed") || !strings.Contains(said, "could not be announced") {
-		t.Fatalf("kill said %q (%v)", said, err)
-	}
-}
-
-// **Issue 306**: a holder starting removes the containers earlier builds left on its machine, through
-// the runner a kill uses, and a runtime that cannot be asked does not stop it.
-func TestAHolderStartingRemovesWhatEarlierBuildsLeftHere(t *testing.T) {
-	h := newHolder("novox", link.TheBuildMachine, t.TempDir(), nil)
-	var removed []string
-	h.remove = func(_ context.Context, _ string, name string, args ...string) (string, error) {
-		removed = append(removed, name+" "+strings.Join(args, " "))
-		if args[0] == "ps" {
-			return "c1 build-1\nc2 build-1\nc3 check-here-2\n", nil
-		}
-		return "", nil
-	}
-	if n := h.removeLeftBehind(); n != 2 || len(removed) != 2 || removed[1] != "docker rm -f c1 c2" {
-		t.Fatalf("removed %d: %v", n, removed)
-	}
-	h.remove = func(context.Context, string, string, ...string) (string, error) {
-		return "", errors.New("no runtime")
-	}
-	if n := h.removeLeftBehind(); n != 0 {
-		t.Errorf("a runtime that cannot be asked removed %d", n)
-	}
-}

cmd/mesh-builder/main.go

@@ -1,808 +0,0 @@
-// mesh-builder — the thing a build machine runs.
-//
-// It takes work from the mesh, turns a repository into artifacts, publishes them, and says what
-// came out. It is **not** the control plane and it is **not** the host:
-//
-//   - the control plane decides and never touches a machine. Building runs commands on one, and
-//     what the control plane may send a machine is bounded by the declaration language
-//     (novox/hq ADR 0005). "Run this build" is not in it, and widening the language so it could
-//     be would make the control plane able to run anything anywhere.
-//   - the host applies declarations and holds no opinion about what they contain. A host that
-//     also built things would need a container runtime and git, on every machine, to do something
-//     almost none of them will ever do.
-//
-// So it is a module: a program a machine runs because the mesh told it to, holding its own broker
-// credential and nothing else. Compromise of a build machine is compromise of a build machine.
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"log"
-	"net/url"
-	"os"
-	"os/signal"
-	"sort"
-	"strings"
-	"syscall"
-	"time"
-
-	"github.com/nats-io/nats.go"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/builder"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// version is set at build time.
-var version = "development"
-
-func main() {
-	if err := run(); err != nil {
-		fmt.Fprintf(os.Stderr, "mesh-builder: %v\n", err)
-		os.Exit(1)
-	}
-}
-
-const usage = `mesh-builder — builds modules for the mesh
-
-It consumes build requests and answers with what it made. Nothing is listened on and nothing
-is dialled except the broker.
-
-  MESH_BROKER_FILE   a file the mesh sealed to this machine holding the same
-  MESH_REGISTRY      host:port to publish artifacts to, when the mesh has not said
-  MESH_BINDING       a file the mesh wrote saying where the artifact store is
-  MESH_PACKAGE_BINDING  a file the mesh wrote saying where the package registry is
-  MESH_NPM_TOKEN_FILE   a file the mesh sealed holding the token for it
-  MESH_GENESIS_PACKAGE_REGISTRY  the document the installer sealed at genesis, read while no
-                     binding is present (novox/hq ADR 0336)
-  MESH_NPM_REGISTRY  a package registry URL, when the mesh has not said (a person, the bootstrap)
-  MESH_NPM_TOKEN     the token for it, likewise
-  MESH_NPM_SCOPE     the scope it answers for (default: @novox)
-  MESH_WORKSPACE     where to clone and build (default: a temporary directory)
-
-It also builds one module and stops, which is how a mesh is raised — before there is a
-broker to take work from or a registry to publish into:
-
-  mesh-builder build <repository> [--path P] [--ref COMMIT] [--registry HOST:PORT]
-
-Without --registry the artifacts stay in this machine's container runtime, named by the
-digest of their own configuration. The result is printed as JSON.
-
-  mesh-builder ready
-
-exits 0 once the agent running in this container is bound to its build work and pulls it, and
-1 before: its container's health check.
-`
-
-func run() error {
-	if len(os.Args) > 1 {
-		switch os.Args[1] {
-		case "version":
-			fmt.Println(version)
-			return nil
-		case "build":
-			return buildOnce(context.Background(), os.Args[2:])
-		case "ready":
-			// The container's health check (novox/hq issue 544): exits non-zero until the agent takes work.
-			return ready()
-		default:
-			fmt.Print(usage)
-			return nil
-		}
-	}
-
-	if err := notReady(); err != nil {
-		return err
-	}
-	// **The builder's own version is part of every reuse key** (novox/hq ADR 0350 §1): a builder that builds
-	// differently never takes a build another one made.
-	builder.Version = builder.SelfVersion(version)
-	credential, err := brokerFrom()
-	if err != nil {
-		return err
-	}
-	registry, err := whereToPublish()
-	if err != nil {
-		return err
-	}
-	workspace := os.Getenv("MESH_WORKSPACE")
-	if workspace == "" {
-		workspace = os.TempDir() + "/mesh-builder"
-	}
-	// **The mesh's name for this machine, not the container's.** A build is reported to the rest
-	// of the mesh, and a report whose origin reads `104cb10e105b` names something no other module
-	// can look up. The mesh already knows the answer and has a way to say it — `${machine:name}`
-	// in the environment file this module is handed — so the hostname is only what is left when
-	// nobody said.
-	on := os.Getenv("MESH_NODE")
-	if on == "" {
-		hostname, err := os.Hostname()
-		if err != nil {
-			return fmt.Errorf("this build machine has no name: nothing said MESH_NODE and the host would not say either: %w", err)
-		}
-		on = hostname
-	}
-
-	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
-	defer stop()
-
-	js, seat, err := dialFor(credential)
-	if err != nil {
-		return err
-	}
-	defer js.Close()
-
-	// **This machine's holder: paused or not, and the build it is running** (novox/hq ADR 0219). The
-	// paused flag is read from the workspace before anything is taken, so a holder restarted while
-	// paused takes nothing.
-	h := newHolder(on, seat, workspace, func(state link.HolderState) error {
-		body, err := json.Marshal(state)
-		if err != nil {
-			return err
-		}
-		_, err = js.Context().Publish(link.BuildPausedOf(seat, on), body)
-		return err
-	})
-	if h.Paused() {
-		fmt.Fprintf(os.Stderr, "paused (kept in %s): taking no build until resumed\n", pausedFile(workspace))
-	}
-	// **What an earlier holder here left goes before anything is taken** (novox/hq issue 306): a holder
-	// recreated mid-check left the check's store and bus running, and the ask went to another machine.
-	h.removeLeftBehind()
-	machine := link.MachineOverNATSWith(js, on, seat, link.MachineOptions{Paused: h.Paused,
-		Taking: func() { taking(seat) }})
-	defer machine.Close()
-
-	// The seat's verbs, on this machine's subjects. Only the seat that declares them: the retired
-	// one serves none, and a subscription its holder has no grant for would be refused for ever.
-	if seat == link.TheBuildMachine {
-		stopServing, err := link.OverNATS{Conn: js.Conn()}.ServeNodeSeatTools(seat, on, h.handlers(),
-			log.New(os.Stderr, "", 0))
-		if err != nil {
-			return err
-		}
-		defer stopServing()
-		// And says so, for the console to find (novox/hq ADR 0197).
-		stopAnnouncing, err := link.OverNATS{Conn: js.Conn()}.Announce(
-			announcement(seat, moduleOf(credential.User), on), log.New(os.Stderr, "", 0))
-		if err != nil {
-			return err
-		}
-		defer stopAnnouncing()
-		go h.stateWhilePaused(ctx, time.Hour)
-	}
-
-	fmt.Fprintf(os.Stderr, "building for the mesh, publishing to %s\n", registry)
-	publisher := builder.Registry{Address: registry, Run: builder.Command}
-	// Check builds are let go of after a week (novox/hq ADR 0350 §5).
-	h.scratch = publisher
-	go h.expireChecks(ctx, time.Hour, time.Now)
-
-	return machine.Take(ctx, func(ctx context.Context, work link.Build) {
-		answer(ctx, publisher, on, workspace, work, h)
-	})
-}
-
-// dialFor opens this machine's link to whichever bus the mesh is on, and says which build seat it
-// holds.
-//
-// **One place chooses**, as everywhere else the bus change went (novox/hq ADR 0116 step 5): a build
-// machine told about both would take work from one and answer on the other, and every log line would
-// say it was fine.
-func dialFor(credential Credential) (*broker.JetStream, string, error) {
-	// **The credential names the bus, and there is one** (novox/hq ADR 0131, design 28 task 5.5).
-	// A credential for the mesh's bus carries user, password and fingerprint beside the address,
-	// and that is enough to dial it, pinned.
-	if !credential.onTheNewBus() {
-		return nil, "", fmt.Errorf("the credential at hand names %q, which is not the mesh's bus", credential.URL)
-	}
-	// Named for what it is, not the controller whose code dials it (novox/hq issue 327).
-	host, _ := os.Hostname()
-	js, err := broker.DialPinned(credential.natsURL(), credential.Fingerprint, nats.Name("build agent on "+host))
-	if err != nil {
-		return nil, "", err
-	}
-	// **The seat this machine serves is the one its credential claims** (novox/hq ADR 0190, the
-	// handover): the mesh issues a build machine's credential naming the seat its module claims,
-	// and one binary serves the old role as `builder` and the new as `build-agent` from that alone.
-	seat := link.BuildSeatClaimed(credential.seatsClaimed())
-	fmt.Fprintf(os.Stderr, "taking build work as a holder of %s\n", seat)
-	return js, seat, nil
-}
-
-// answer does one build and says what happened, whichever way it went.
-func answer(ctx context.Context, publisher builder.Publisher, on, workspace string, work link.Build, h *holder) {
-	request := work.Request()
-
-	// **Its own context, so it can be killed alone** (novox/hq ADR 0219): cancelled by `kill`, it ends
-	// this build's commands and nothing else; the machine's own context ending — a SIGTERM — still
-	// reaches it through the parent, and that keeps today's meaning below.
-	building, cancel := context.WithCancel(ctx)
-	defer cancel()
-	var mine *running
-	if h != nil {
-		mine = h.begin(request, cancel)
-		defer h.end(mine)
-	}
-
-	// **First thing, and to stdout.** A build request that arrives and produces no visible line until
-	// it either finishes or fails is indistinguishable from one that never arrived — which cost a long
-	// diagnosis against a running mesh, chasing "the handler never fired" when the truth was only that
-	// the handler said nothing until the end.
-	fmt.Fprintf(os.Stderr, "a build request arrived for %s (%s)\n", request.Repository, request.ID)
-
-	// **Everything a build says goes two ways**: to stderr, as always, and onto the bus as the
-	// role's own events under the build's id (novox/hq ADR 0157) — so whoever asked, and anybody
-	// watching, reads the same lines this container's log holds, live, and after the fact from the
-	// stream. Said first, before anything runs, so a build that hangs is one that visibly started.
-	say := func(step, message string) {
-		fmt.Fprintf(os.Stderr, "  [%s] %s\n", step, message)
-		work.Say(step, message)
-		if mine != nil && step != "run" && step != "output" {
-			h.stepped(mine, step)
-		}
-	}
-	builder.Said = say
-	defer func() { builder.Said = nil }()
-	if err := work.Began(ctx); err != nil {
-		fmt.Fprintf(os.Stderr, "cannot say a build started: %v\n", err)
-	}
-
-	result := link.BuildResult{
-		ID: request.ID, Repository: request.Repository, Path: request.Path,
-		Ref: request.Ref, On: on, Source: request.Source, DryRun: request.DryRun,
-	}
-	what := "building " + request.Repository
-	if request.Path != "" {
-		what += " at " + request.Path
-	}
-	if request.Ref != "" {
-		what += " on " + request.Ref
-	}
-	say("build", what)
-
-	npmrc, err := packagesFrom(on)
-	if err == nil {
-		say("packages", saysRegistry(npmrc))
-	}
-	registryHere, isRegistry := publisher.(builder.Registry)
-	var built builder.Result
-	if request.Check != nil {
-		// **A pull request's merge check, not a build** (novox/hq to-be 45 §9): nothing is built,
-		// published or registered; the verdict is the outcome.
-		result.Checked = request.Check
-		registry := ""
-		if r, ok := publisher.(builder.Registry); ok {
-			registry = r.Address
-		}
-		spec := checkSpecOf(request)
-		// What the merge would move, built by the check for the walk to take (novox/hq ADR 0350 §1): into the
-		// scratch namespace. **Never with the package registry's credential**: this is code nobody has approved
-		// yet, and a recipe could read the credential it is handed (issue 462). A module that resolves packages
-		// at build time has no reuse key anyway, so nothing is lost by refusing it here.
-		if isRegistry && len(spec.Builds) > 0 {
-			spec.BuildWith = &builder.CheckBuilding{Publish: publisher, Scratch: registryHere, Held: request.Held,
-				Seats: request.Seats}
-		}
-		var v builder.CheckVerdict
-		v, err = builder.Check(building, builder.Command, spec, workspace, registry, forgeFrom(), say)
-		if err == nil {
-			result.Check = &link.CheckOutcome{Verdict: v.Verdict, Summary: v.Summary, Report: v.Report,
-				Took: v.Took.Round(time.Second).String(), Gate: layerOf(v.Gate), RepoCheck: layerOf(v.Repo),
-				Head: v.Head, Trunk: v.Trunk, Beside: v.Beside, Built: checkBuiltOf(v.Built)}
-			// What each of a group's heads was judged as (novox/hq ADR 0323 §6).
-			for _, m := range v.Members {
-				result.Check.Members = append(result.Check.Members, link.CheckedMember{Owner: m.Owner, Repo: m.Repo,
-					Commit: m.Head, Trunk: m.Trunk})
-			}
-		}
-	} else if err == nil {
-		// The package-registry credential is a build input, so it is resolved before the clone: a
-		// build that could not have resolved its dependencies is refused in front of the reason, not
-		// after a clone that then fails at npm ci.
-		// Every container it starts is labelled with its id, so a kill finds what outlived the
-		// docker client (ADR 0219).
-		if request.Reuse != nil && isRegistry && !request.DryRun {
-			// **A walk's build takes the check's build of the same key** (novox/hq ADR 0350 §2).
-			reuse := builder.Reuse{Scratch: registryHere}
-			for _, p := range request.Reuse.Pulls {
-				reuse.Pulls = append(reuse.Pulls, builder.PullRef{Owner: p.Owner, Repo: p.Repo, Number: p.Number})
-			}
-			// Only what a verdict names is taken (ADR 0350 §2).
-			for _, b := range request.Reuse.Builds {
-				named := builder.NamedBuild{Pull: builder.PullRef{Owner: b.Pull.Owner, Repo: b.Pull.Repo,
-					Number: b.Pull.Number}, Check: b.Check, Module: b.Built.Module, Key: b.Built.Key,
-					Digests: map[string]string{}}
-				for _, m := range b.Built.Made {
-					named.Digests[m.Name] = builder.DigestOf(m.Reference)
-				}
-				reuse.Named = append(reuse.Named, named)
-			}
-			built, err = builder.BuildReusing(building, builder.Labelled(builder.Command, request.ID), publisher, reuse,
-				request.Repository, request.Path, request.Ref, workspace, request.Held, npmrc,
-				forgeFrom(), say, request.Seats)
-		} else {
-			built, err = builder.Build(building, builder.Labelled(builder.Command, request.ID), publisher,
-				request.Repository, request.Path, request.Ref, workspace, request.Held, npmrc,
-				forgeFrom(), say, request.Seats)
-		}
-	}
-	// What it copied into the store, whatever became of the build (novox/hq ADR 0257).
-	result.Mirrored = built.Mirrored
-	// Only a build the kill ended: the kill came before its work did. One that finished — built, or
-	// failed on its own — in the moment the kill arrived says what it did, and the kill is refused.
-	killed := false
-	if mine != nil {
-		killed = h.returned(mine) && err != nil
-	}
-	if killed {
-		// **Killed by hand is the outcome, whatever the build was doing** (novox/hq ADR 0219): the
-		// error it ended with is the kill's consequence, not a fault of the source.
-		result.Failed = link.KilledByHand
-		say("failed", link.KilledByHand)
-	} else if err != nil {
-		// A failure is a result. A build that fails and says nothing is indistinguishable from a
-		// builder that is not running, and those want completely different responses.
-		result.Failed = err.Error()
-		say("failed", err.Error())
-	} else if request.Check != nil {
-		say("checked", result.Check.Verdict+": "+result.Check.Summary)
-	} else {
-		manifest, marshalErr := json.Marshal(built.Manifest)
-		if marshalErr != nil {
-			result.Failed = marshalErr.Error()
-		} else {
-			result.Commit = built.Commit
-			result.Manifest = manifest
-			for _, made := range built.Built {
-				result.Made = append(result.Made, link.MadeArtifact{
-					Name: made.Name, Kind: made.Kind, Reference: made.Reference,
-				})
-			}
-			result.Against = built.Against
-			result.SourceFingerprint = built.Source
-			// What the walk did instead of building, or why it built (novox/hq ADR 0350 §3, §4).
-			result.ReuseKey = built.ReuseKey
-			if built.Reused != nil {
-				f := built.Reused.From
-				result.Reused = built.Reused.Words()
-				result.ReusedFrom = &link.ReusedFrom{Pull: link.PullRef{Owner: f.Pull.Owner, Repo: f.Pull.Repo,
-					Number: f.Pull.Number}, Head: f.Head, Trunk: f.Trunk, Check: f.Check, Key: f.Key}
-			} else if request.Reuse != nil {
-				result.BuiltWhy = built.Why
-				if result.BuiltWhy == "" {
-					result.BuiltWhy = "it has no artifact to build"
-				}
-			}
-			result.Trunk, result.OnTrunk, result.Branches = built.Trunk, built.OnTrunk, built.Branches
-			for _, r := range built.Read {
-				result.Read = append(result.Read, link.ReadRepository{Repository: r.Repository, Ref: r.Ref})
-			}
-			for _, s := range built.Sources {
-				result.Sources = append(result.Sources, link.BuildSource{Repository: s.Repository, Ref: s.Ref, Paths: s.Paths})
-			}
-			say("built", built.Manifest.Module+" from "+short(built.Commit))
-		}
-	}
-
-	// A killed build is announced on a context of its own: the build's was the one cancelled, and the
-	// outcome must go out and the ask be settled — acknowledged, never redelivered to another machine
-	// to be built again. A machine being stopped is the other case and keeps its meaning: the
-	// parent's context is gone, nothing is announced or settled, and the ask is redelivered.
-	announcing := ctx
-	if killed {
-		fresh, stop := context.WithTimeout(context.Background(), 30*time.Second)
-		defer stop()
-		announcing = fresh
-	}
-	announceErr := work.Announce(announcing, result)
-	if mine != nil {
-		h.said(mine, result.Failed, announceErr == nil)
-	}
-	if err := announceErr; err != nil {
-		// Said, not fatal: the build happened. A build reported as failed because announcing it
-		// failed is a lie about work that was done — and the request stays unsettled below only if
-		// nothing was said at all, so another machine can try.
-		fmt.Fprintf(os.Stderr, "cannot say what came of a build: %v\n", err)
-		return
-	}
-
-	// Settled only once the outcome is away, so a machine that dies before answering leaves the work
-	// for another rather than losing it.
-	if err := work.Done(); err != nil {
-		fmt.Fprintf(os.Stderr, "the outcome is away and the request could not be settled: %v\n", err)
-	}
-}
-
-// checkSpecOf is a check request as the builder runs it.
-func checkSpecOf(request link.BuildRequest) builder.CheckSpec {
-	c := request.Check
-	spec := builder.CheckSpec{ID: request.ID, Repository: request.Repository, Ref: request.Ref,
-		Owner: c.Owner, Repo: c.Repo, Number: c.Number, Paths: c.Paths, Beside: map[string]builder.Beside{},
-		Modules: c.Modules, New: c.New, Manifests: c.Manifests, Judge: c.Judge, Base: c.Base,
-		Toolchain: builder.ToolchainOf(request.Held), Toolchains: builder.ToolchainsOf(request.Held)}
-	for dir, b := range c.Beside {
-		spec.Beside[dir] = builder.Beside{Repository: b.Repository, Ref: b.Ref}
-	}
-	for _, b := range c.Builds {
-		spec.Builds = append(spec.Builds, builder.CheckBuildSpec{Module: b.Module, Repository: b.Repository, Path: b.Path,
-			Ref: b.Ref, Merged: b.Merged, Tier: b.Tier, Skip: b.Skip})
-	}
-	for _, m := range c.Members {
-		spec.Group = append(spec.Group, builder.GroupHead{Owner: m.Owner, Repo: m.Repo, Repository: m.Repository,
-			Ref: m.Ref, Paths: m.Paths, Base: m.Base})
-	}
-	return spec
-}
-
-// checkBuiltOf is a check's builds for its merge as the outcome carries them (novox/hq ADR 0350 §1).
-func checkBuiltOf(built []builder.CheckBuilt) []link.CheckBuilt {
-	var out []link.CheckBuilt
-	for _, b := range built {
-		c := link.CheckBuilt{Module: b.Module, Key: b.Key, NotBuilt: b.NotBuilt, Took: b.Took.Round(time.Second).String()}
-		for _, m := range b.Made {
-			c.Made = append(c.Made, link.MadeArtifact{Name: m.Name, Kind: m.Kind, Reference: m.Reference})
-		}
-		out = append(out, c)
-	}
-	return out
-}
-
-// layerOf is one layer of a check as the outcome carries it.
-func layerOf(l *builder.Layer) *link.CheckLayer {
-	if l == nil {
-		return nil
-	}
-	return &link.CheckLayer{Verdict: l.Verdict, Summary: l.Summary, Modules: l.Modules}
-}
-
-// packagesFrom is where a build resolves the mesh's own published packages — the SDK above all
-// (novox/hq ADR 0076, issue 053) — on this machine.
-//
-// **The binding wins, then the genesis document** (novox/hq ADR 0336 §3, §4). The build agent's
-// npm-package-registry requirement is optional: on genesis's node, before the gitea module is assigned,
-// nothing provides it, and the installer sealed the forge it raised to this agent as one document
-// instead. Once the requirement binds, the binding names the endpoint the way the artifact store's
-// does and a sealed token file the credential, and the genesis document is left unread. A binding
-// file named and absent is a requirement not bound here, never a fault: the environment names the
-// path whether or not the mesh wrote it.
-//
-// The environment variables remain for a builder run by a person. With none of the three the result
-// is disabled and says this machine, so a build that needs the registry is refused naming it (§6),
-// and a build that needs none builds anyway.
-func packagesFrom(machine string) (builder.Npmrc, error) {
-	scope := strings.TrimSpace(os.Getenv("MESH_NPM_SCOPE"))
-	if scope == "" {
-		scope = "@novox"
-	}
-	none := builder.Npmrc{Machine: machine}
-
-	if path := strings.TrimSpace(os.Getenv("MESH_PACKAGE_BINDING")); path != "" {
-		raw, err := os.ReadFile(path)
-		switch {
-		case errors.Is(err, os.ErrNotExist):
-			// Not bound on this machine: the genesis document, or nothing.
-		case err != nil:
-			return none, fmt.Errorf("cannot read what the mesh said about the package registry: %w", err)
-		default:
-			return fromBinding(path, raw, scope, machine)
-		}
-	}
-	if path := strings.TrimSpace(os.Getenv("MESH_GENESIS_PACKAGE_REGISTRY")); path != "" {
-		raw, err := os.ReadFile(path)
-		switch {
-		case errors.Is(err, os.ErrNotExist):
-			// Not this mesh's genesis node, or the installer has not sealed it yet.
-		case err != nil:
-			return none, fmt.Errorf("cannot read the genesis document for the package registry: %w", err)
-		default:
-			return fromGenesis(path, raw, scope, machine)
-		}
-	}
-
-	// A builder run by a person.
-	registry := strings.TrimSpace(os.Getenv("MESH_NPM_REGISTRY"))
-	secret := strings.TrimSpace(os.Getenv("MESH_NPM_TOKEN"))
-	username := strings.TrimSpace(os.Getenv("MESH_NPM_USER"))
-	if registry == "" && secret == "" {
-		return none, nil
-	}
-	n := builder.Npmrc{Scope: scope, Registry: registry, From: builder.FromEnvironment, Machine: machine}
-	if username != "" {
-		n.Username, n.Password = username, secret
-	} else {
-		n.Token = secret
-	}
-	return n, nil
-}
-
-// fromBinding composes the registry from the npm-package-registry binding the mesh wrote and the
-// credential it sealed beside it. The mesh authenticates the ordinary way — a generated password the
-// provider only applies (novox/hq ADR 0048) — so with a username the secret is a password (basic
-// auth); without one it is a bearer token a provider minted.
-func fromBinding(path string, raw []byte, scope, machine string) (builder.Npmrc, error) {
-	none := builder.Npmrc{Machine: machine}
-	var told struct {
-		From   string         `json:"from"`
-		At     string         `json:"at"`
-		As     string         `json:"as"`
-		Serves map[string]any `json:"serves"`
-	}
-	if err := json.Unmarshal(raw, &told); err != nil {
-		return none, fmt.Errorf("%s is not a binding: %w", path, err)
-	}
-	if told.At == "" {
-		return none, fmt.Errorf(
-			"%s says the package registry is on %q and gives no address for it", path, told.From)
-	}
-	// Composed from what the provider serves, so nothing here knows gitea's URL shape from
-	// another registry's: it states its port, the path its registry answers on, and the scheme.
-	scheme := "https"
-	if s, ok := told.Serves["scheme"]; ok {
-		scheme = fmt.Sprintf("%v", s)
-	}
-	port, ok := told.Serves["port"]
-	if !ok {
-		return none, fmt.Errorf("%s says nothing about which port the package registry answers on", path)
-	}
-	npmPath, ok := told.Serves["npm-path"]
-	if !ok {
-		return none, fmt.Errorf("%s says nothing about the path the package registry answers on", path)
-	}
-	secret := strings.TrimSpace(os.Getenv("MESH_NPM_TOKEN"))
-	if file := strings.TrimSpace(os.Getenv("MESH_NPM_TOKEN_FILE")); file != "" {
-		raw, err := os.ReadFile(file)
-		if err != nil {
-			return none, fmt.Errorf("cannot read this builder's package-registry credential: %w", err)
-		}
-		secret = strings.TrimSpace(string(raw))
-	}
-	n := builder.Npmrc{Scope: scope, Registry: fmt.Sprintf("%s://%s:%v%v", scheme, told.At, port, npmPath),
-		From: builder.FromBinding, Machine: machine}
-	if told.As != "" {
-		n.Username, n.Password = told.As, secret
-	} else {
-		n.Token = secret
-	}
-	return n, nil
-}
-
-// GenesisRegistry is the genesis document (novox/hq ADR 0336 §3): what the installer sealed to the
-// build agent on its node at genesis's packages step, as the `genesis-package-registry` own-secret —
-// the forge it raised, the port this node gave the package registry, its npm path, and the account it
-// made with that account's password. mesh-host writes it; the field names are the two repositories'
-// agreement.
-type GenesisRegistry struct {
-	Scheme   string `json:"scheme"`
-	At       string `json:"at"`
-	Port     int    `json:"port"`
-	NpmPath  string `json:"npm-path"`
-	As       string `json:"as"`
-	Password string `json:"password"`
-}
-
-// fromGenesis composes the registry from the genesis document.
-func fromGenesis(path string, raw []byte, scope, machine string) (builder.Npmrc, error) {
-	none := builder.Npmrc{Machine: machine}
-	var g GenesisRegistry
-	if err := json.Unmarshal(raw, &g); err != nil {
-		return none, fmt.Errorf("%s is not the genesis document for the package registry: %w", path, err)
-	}
-	var missing []string
-	for name, value := range map[string]string{"at": g.At, "npm-path": g.NpmPath, "as": g.As, "password": g.Password} {
-		if strings.TrimSpace(value) == "" {
-			missing = append(missing, name)
-		}
-	}
-	if g.Port <= 0 {
-		missing = append(missing, "port")
-	}
-	if len(missing) > 0 {
-		sort.Strings(missing)
-		return none, fmt.Errorf("%s, the genesis document for the package registry, says nothing of %s",
-			path, strings.Join(missing, ", "))
-	}
-	scheme := g.Scheme
-	if scheme == "" {
-		scheme = "http"
-	}
-	return builder.Npmrc{Scope: scope, Registry: fmt.Sprintf("%s://%s:%d%s", scheme, g.At, g.Port, g.NpmPath),
-		Username: g.As, Password: g.Password, From: builder.FromGenesis, Machine: machine}, nil
-}
-
-// saysRegistry is the line each build's log carries about the package registry (novox/hq ADR 0336
-// §4): which of the binding and the genesis document it resolved from, or that it has neither here.
-func saysRegistry(n builder.Npmrc) string {
-	if n.Enabled() {
-		return "the package registry is resolved from " + n.From
-	}
-	machine := n.Machine
-	if machine == "" {
-		machine = "this machine"
-	}
-	return fmt.Sprintf("no package registry: %s is unbound on %s and no genesis document is here; "+
-		"a build needing it is refused", builder.RegistryRequirement, machine)
-}
-
-// forgeFrom is the git credential this builder may offer a clone, composed from the same binding
-// and sealed secret its package-registry half already reads: the forge that answers npm is the
-// forge that hosts the repositories, and its provisioner applies one password to one user for
-// both. Anything missing means no credential, and every clone stays anonymous — which is all a
-// mesh of public repositories ever needs.
-//
-// The URL names the binding's own address — the machine the mesh says the forge is on — so a
-// private repository is registered and built by that address, and a clone of anything else is
-// never shown this credential (git's credential store matches the whole origin).
-func forgeFrom() builder.GitCredential {
-	path := strings.TrimSpace(os.Getenv("MESH_PACKAGE_BINDING"))
-	if path == "" {
-		return builder.GitCredential{}
-	}
-	raw, err := os.ReadFile(path)
-	if err != nil {
-		return builder.GitCredential{}
-	}
-	var told struct {
-		At     string         `json:"at"`
-		As     string         `json:"as"`
-		Serves map[string]any `json:"serves"`
-	}
-	if err := json.Unmarshal(raw, &told); err != nil || told.At == "" || told.As == "" {
-		return builder.GitCredential{}
-	}
-	secret := strings.TrimSpace(os.Getenv("MESH_NPM_TOKEN"))
-	if file := strings.TrimSpace(os.Getenv("MESH_NPM_TOKEN_FILE")); file != "" {
-		if raw, err := os.ReadFile(file); err == nil {
-			secret = strings.TrimSpace(string(raw))
-		}
-	}
-	if secret == "" {
-		return builder.GitCredential{}
-	}
-	scheme := "https"
-	if s, ok := told.Serves["scheme"]; ok {
-		scheme = fmt.Sprintf("%v", s)
-	}
-	host := told.At
-	if port, ok := told.Serves["port"]; ok {
-		host = fmt.Sprintf("%s:%v", told.At, port)
-	}
-	made := url.URL{Scheme: scheme, User: url.UserPassword(told.As, secret), Host: host}
-	return builder.GitCredential{URL: made.String()}
-}
-
-func short(commit string) string {
-	if len(commit) > 8 {
-		return commit[:8]
-	}
-	return commit
-}
-
-// whereToPublish is the artifact store this builder uses.
-//
-// **Preferably from the mesh.** A builder that is a module requires an artifact store, and the
-// mesh writes it a file saying which machine answers that and on what port — the same binding any
-// consumer of any provision gets. Reading it means the address is not a setting somebody keeps in
-// step by hand, and moving the store is an ordinary reassignment rather than an edit on every
-// build machine.
-//
-// The environment variable remains for a builder run by a person, which is how this started and
-// how it is still run while being developed.
-func whereToPublish() (string, error) {
-	binding := strings.TrimSpace(os.Getenv("MESH_BINDING"))
-	if binding == "" {
-		registry := strings.TrimSpace(os.Getenv("MESH_REGISTRY"))
-		if registry == "" {
-			return "", fmt.Errorf("neither MESH_BINDING nor MESH_REGISTRY: a built artifact " +
-				"nobody can fetch is not built")
-		}
-		return registry, nil
-	}
-
-	raw, err := os.ReadFile(binding)
-	if err != nil {
-		return "", fmt.Errorf("cannot read what the mesh said about the artifact store: %w", err)
-	}
-	var told struct {
-		From   string         `json:"from"`
-		At     string         `json:"at"`
-		Serves map[string]any `json:"serves"`
-	}
-	if err := json.Unmarshal(raw, &told); err != nil {
-		return "", fmt.Errorf("%s is not a binding: %w", binding, err)
-	}
-	if told.At == "" {
-		// The provider is not on the private network, so there is no name to reach it by. Said
-		// rather than falling back to the machine's own name, which would publish to a store on
-		// the wrong machine and be found out much later.
-		return "", fmt.Errorf(
-			"%s says the artifact store is on %q and gives no address for it", binding, told.From)
-	}
-	port, ok := told.Serves["port"]
-	if !ok {
-		return "", fmt.Errorf("%s says nothing about which port the artifact store answers on",
-			binding)
-	}
-	return fmt.Sprintf("%s:%v", told.At, port), nil
-}
-
-// brokerFrom is where this builder connects, and with what.
-//
-// **Preferably from a file the mesh sealed to this machine.** A builder that is a module is given
-// its credential the way every other module is given one: generated or accepted centrally, sealed
-// to the machine, written by the host. Putting it in an environment variable instead would mean
-// the one copy that matters passing through a terminal and a process listing.
-//
-// The variable remains for a builder run by a person.
-func brokerFrom() (Credential, error) {
-	if path := strings.TrimSpace(os.Getenv("MESH_BROKER_FILE")); path != "" {
-		raw, err := os.ReadFile(path)
-		if err != nil {
-			return Credential{}, fmt.Errorf("cannot read this builder's credential: %w", err)
-		}
-		said := strings.TrimSpace(string(raw))
-		if said == "" {
-			// An empty credential file is a machine that will connect as nobody and be refused,
-			// with the reason three layers away.
-			return Credential{}, fmt.Errorf("%s is empty, so this builder has no credential", path)
-		}
-		var held Credential
-		if err := json.Unmarshal([]byte(said), &held); err == nil && held.URL != "" {
-			return held, nil
-		}
-		// A file holding only a URL, which is what a person writing one by hand produces. The
-		// broker is then verified against whatever this machine already trusts.
-		return Credential{URL: said}, nil
-	}
-	return Credential{}, fmt.Errorf(
-		"no MESH_BROKER_FILE: a build machine with no credential for the bus has nothing to build")
-}
-
-// Credential is what a build machine is given so it can reach the broker.
-//
-// Two things, because reaching a broker over TLS needs both: who to connect as, and what to check
-// the certificate against. A mesh's broker presents a certificate of the mesh's own, which is in
-// no public trust store, so a URL alone can only connect to a broker somebody else vouches for.
-//
-// **The same shape a node gets, for the same reason** (novox/hq ADR 0004): the fingerprint travels
-// out of band — here, sealed with the credential — and the endpoint is verified once at connect.
-type Credential struct {
-	URL         string `json:"url"`
-	Fingerprint string `json:"fingerprint,omitempty"`
-	// User and Password ride beside the address on the bus being built (design 25): a credential
-	// embedded in a URL leaks into every log line that prints a connection, so the mesh seals them
-	// as two fields and this machine joins them once, here, to dial.
-	User     string `json:"user,omitempty"`
-	Password string `json:"password,omitempty"`
-	// Claims are the seats the module this credential was issued for claims, as the mesh writes
-	// them beside the credential (novox/hq ADR 0159). The first is the build role this machine
-	// serves; a credential naming none is from before claims travelled in it.
-	Claims []struct {
-		Seat string `json:"seat"`
-	} `json:"claims,omitempty"`
-}
-
-// seatsClaimed is the seats the credential names, in order.
-func (c Credential) seatsClaimed() []string {
-	out := make([]string, 0, len(c.Claims))
-	for _, claim := range c.Claims {
-		out = append(out, claim.Seat)
-	}
-	return out
-}
-
-// onTheNewBus is whether a credential is for the bus being built: its address says so, and the
-// mesh only ever seals such a credential with the user and password beside it.
-func (c Credential) onTheNewBus() bool { return strings.HasPrefix(strings.TrimSpace(c.URL), "nats://") }
-
-// natsURL is the address with this machine's credential in it, for the one dial that needs it.
-func (c Credential) natsURL() string {
-	rest := strings.TrimPrefix(strings.TrimSpace(c.URL), "nats://")
-	if c.User == "" {
-		return "nats://" + rest
-	}
-	return "nats://" + c.User + ":" + c.Password + "@" + rest
-}

cmd/mesh-builder/once.go

@@ -1,188 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"flag"
-	"fmt"
-	"os"
-	"strings"
-
-	"github.com/novox/mesh-controller/internal/builder"
-)
-
-// buildOnce is the builder doing one build and stopping, with no broker and no mesh.
-//
-// **This is how a mesh is raised** (novox/hq ADR 0073). The installer carries this program and runs
-// it once, before anything else exists, to produce the control plane from the same repository and
-// path that every later rebuild of it will use. What raises the mesh is therefore the same thing
-// that maintains it — not a second mechanism that has to be kept in step with the first and is
-// exercised once per new mesh, which is how often enough to rot.
-//
-// It takes no work from a queue and answers nobody: there is no broker yet, and the only thing
-// waiting for the answer is the installer that started it. So the result goes to standard output as
-// JSON, which is what the installer reads.
-//
-// With no --registry it publishes nowhere and the image stays in this machine's container runtime,
-// named by the digest of its own configuration (see builder.Local). That is the genesis case. With
-// one, it publishes as it always does — the same command is how an operator builds a module by hand
-// on a mesh that already exists.
-func buildOnce(ctx context.Context, args []string) error {
-	set := flag.NewFlagSet("build", flag.ContinueOnError)
-	path := set.String("path", "", "the module's directory inside the repository (default: its root)")
-	ref := set.String("ref", "", "the commit to build; a branch is a moving target somebody else controls")
-	registry := set.String("registry", "",
-		"host:port to publish to. Without it the artifacts stay in this machine's container runtime, which is the genesis case")
-	workspace := set.String("workspace", "", "where to clone and build (default: a temporary directory)")
-	on := multiple(set, "on",
-		"a base this build stands on, as <module>/<artifact>=<reference>. Repeatable")
-	positionals, err := parseAround(set, args)
-	if err != nil {
-		return err
-	}
-	if len(positionals) != 1 {
-		return errors.New("mesh-builder build <repository> [--path P] [--ref COMMIT] [--registry HOST:PORT]")
-	}
-	repository := positionals[0]
-
-	where := *workspace
-	if where == "" {
-		where = os.TempDir() + "/mesh-builder-once"
-	}
-
-	// What this build may stand on, said on the command line because there is no mesh to ask.
-	//
-	// **This is the genesis case and it is meant to be awkward.** On a running mesh the control
-	// plane answers this, because only it knows what this mesh holds. Here nothing has been built
-	// yet, so whoever runs this says what to use — and for the control plane, which is the one
-	// module raised before anything else exists, the answer is ordinarily nothing at all.
-	bases := map[string]string{}
-	for _, pair := range *on {
-		key, reference, found := strings.Cut(pair, "=")
-		if !found || key == "" || reference == "" {
-			return fmt.Errorf(
-				"--on takes <module>/<artifact>=<reference>, and %q is not that", pair)
-		}
-		bases[key] = reference
-	}
-
-	// Local unless told otherwise, because the moment this exists for has nowhere to publish. A
-	// default pointing at a registry would mean genesis failing at a push to something that is not
-	// there yet, one step away from the thing that could explain it.
-	var publisher builder.Publisher = builder.Local{Run: builder.Command}
-	if *registry != "" {
-		publisher = builder.Registry{Address: *registry, Run: builder.Command}
-	}
-
-	fmt.Fprintf(os.Stderr, "building %s", repository)
-	if *path != "" {
-		fmt.Fprintf(os.Stderr, " at %s", *path)
-	}
-	if *ref != "" {
-		fmt.Fprintf(os.Stderr, " at %s", *ref)
-	}
-	fmt.Fprintln(os.Stderr)
-
-	machine := os.Getenv("MESH_NODE")
-	if machine == "" {
-		machine, _ = os.Hostname()
-	}
-	npmrc, err := packagesFrom(machine)
-	if err != nil {
-		return err
-	}
-	fmt.Fprintf(os.Stderr, "  [packages] %s\n", saysRegistry(npmrc))
-	built, buildErr := builder.Build(ctx, builder.Command, publisher, repository, *path, *ref, where, bases, npmrc,
-		forgeFrom(),
-		func(step, message string) { fmt.Fprintf(os.Stderr, "  [%s] %s\n", step, message) })
-	if buildErr != nil {
-		return buildErr
-	}
-
-	// To standard output, and everything else to standard error, so the caller can read this
-	// without having to separate it from progress.
-	out := onceResult{
-		Module:     built.Manifest.Module,
-		Commit:     built.Commit,
-		Repository: repository,
-		Path:       *path,
-		Ref:        *ref,
-		Manifest:   built.Manifest,
-		Against:    built.Against,
-		Source:     built.Source,
-	}
-	for _, r := range built.Read {
-		out.Read = append(out.Read, readRepository{Repository: r.Repository, Ref: r.Ref})
-	}
-	for _, made := range built.Built {
-		out.Made = append(out.Made, madeArtifact{Name: made.Name, Kind: made.Kind, Reference: made.Reference})
-	}
-	body, err := json.MarshalIndent(out, "", "  ")
-	if err != nil {
-		return err
-	}
-	fmt.Println(string(body))
-	fmt.Fprintf(os.Stderr, "  built %s from %s\n", built.Manifest.Module, short(built.Commit))
-	return nil
-}
-
-// onceResult is what one build reports to whoever started it.
-//
-// The same fields the mesh records for a build, so a reader comparing a genesis build against an
-// ordinary one is comparing the same thing said the same way.
-type onceResult struct {
-	Module     string           `json:"module"`
-	Commit     string           `json:"commit"`
-	Repository string           `json:"repository"`
-	Path       string           `json:"path,omitempty"`
-	Ref        string           `json:"ref,omitempty"`
-	Manifest   any              `json:"manifest"`
-	Made       []madeArtifact   `json:"made"`
-	Against    []string         `json:"against,omitempty"`
-	Read       []readRepository `json:"read,omitempty"`
-	Source     string           `json:"source-fingerprint,omitempty"`
-}
-
-// readRepository is a repository this build read source from besides the module's own.
-type readRepository struct {
-	Repository string `json:"repository"`
-	Ref        string `json:"ref,omitempty"`
-}
-
-type madeArtifact struct {
-	Name      string `json:"name"`
-	Kind      string `json:"kind"`
-	Reference string `json:"reference"`
-}
-
-// parseAround lets flags appear on either side of the repository, because a person writing this by
-// hand will put them wherever reads best and the standard parser stops at the first thing that is
-// not a flag. The same helper the control plane's commands use, for the same reason.
-func parseAround(set *flag.FlagSet, args []string) ([]string, error) {
-	var positionals []string
-	rest := args
-	for {
-		if err := set.Parse(rest); err != nil {
-			return nil, err
-		}
-		rest = set.Args()
-		if len(rest) == 0 {
-			return positionals, nil
-		}
-		positionals = append(positionals, rest[0])
-		rest = rest[1:]
-	}
-}
-
-// multiple is a flag that may be given more than once.
-type repeated []string
-
-func (r *repeated) String() string     { return strings.Join(*r, ", ") }
-func (r *repeated) Set(v string) error { *r = append(*r, v); return nil }
-
-func multiple(set *flag.FlagSet, name, usage string) *[]string {
-	var values repeated
-	set.Var(&values, name, usage)
-	return (*[]string)(&values)
-}

cmd/mesh-builder/packages_test.go

@@ -1,102 +0,0 @@
-package main
-
-import (
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/builder"
-)
-
-// The build agent's package registry (novox/hq ADR 0336, issue 121): its npm-package-registry
-// requirement is optional, so the binding may be absent, and on genesis's node the installer seals
-// the forge it raised as one genesis document instead.
-
-// registryFiles names the three paths the build agent's environment always names, writing only those
-// given.
-func registryFiles(t *testing.T, binding, token, genesis string) {
-	t.Helper()
-	dir := t.TempDir()
-	for env, content := range map[string]string{
-		"MESH_PACKAGE_BINDING":          binding,
-		"MESH_NPM_TOKEN_FILE":           token,
-		"MESH_GENESIS_PACKAGE_REGISTRY": genesis,
-	} {
-		path := filepath.Join(dir, env)
-		t.Setenv(env, path)
-		if content != "" {
-			if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
-				t.Fatal(err)
-			}
-		}
-	}
-	for _, env := range []string{"MESH_NPM_REGISTRY", "MESH_NPM_TOKEN", "MESH_NPM_USER", "MESH_NPM_SCOPE"} {
-		t.Setenv(env, "")
-	}
-}
-
-const (
-	aBinding = `{"from":"gitea","at":"anchor.mesh","as":"anchor-agent",
-	  "serves":{"scheme":"http","port":3000,"npm-path":"/api/packages/novox/npm/"}}`
-	aGenesisDocument = `{"scheme":"http","at":"127.0.0.1","port":3100,"npm-path":"/api/packages/novox/npm/",
-	  "as":"mesh-builder","password":"genesis-secret"}`
-)
-
-func TestUntilTheRequirementBindsTheGenesisDocumentIsRead(t *testing.T) {
-	registryFiles(t, "", "", aGenesisDocument)
-	n, err := packagesFrom("anchor")
-	if err != nil {
-		t.Fatalf("an absent binding beside a genesis document was refused: %v", err)
-	}
-	if n.From != builder.FromGenesis || n.Registry != "http://127.0.0.1:3100/api/packages/novox/npm/" ||
-		n.Username != "mesh-builder" || n.Password != "genesis-secret" || n.Scope != "@novox" {
-		t.Fatalf("the genesis document was not what the registry came from: %+v", n)
-	}
-	file, err := n.File()
-	if err != nil || !strings.Contains(file, "//127.0.0.1:3100/api/packages/novox/npm/:username=mesh-builder") {
-		t.Fatalf("the .npmrc is not written from the genesis document: %v\n%s", err, file)
-	}
-	if got := saysRegistry(n); !strings.Contains(got, "genesis document") {
-		t.Errorf("the log does not say the genesis document: %s", got)
-	}
-}
-
-func TestARealBindingWinsOverTheGenesisDocument(t *testing.T) {
-	registryFiles(t, aBinding, "bound-secret\n", aGenesisDocument)
-	n, err := packagesFrom("anchor")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if n.From != builder.FromBinding || n.Registry != "http://anchor.mesh:3000/api/packages/novox/npm/" ||
-		n.Username != "anchor-agent" || n.Password != "bound-secret" {
-		t.Fatalf("the binding did not win over the genesis document: %+v", n)
-	}
-	if got := saysRegistry(n); !strings.Contains(got, "binding") {
-		t.Errorf("the log does not say the binding: %s", got)
-	}
-}
-
-func TestWithNeitherTheAgentHasNoRegistryAndSaysWhere(t *testing.T) {
-	registryFiles(t, "", "", "")
-	n, err := packagesFrom("workstation")
-	if err != nil {
-		t.Fatalf("an unbound optional requirement was a fault: %v", err)
-	}
-	if n.Enabled() || n.Machine != "workstation" {
-		t.Fatalf("a registry came from nowhere: %+v", n)
-	}
-	got := saysRegistry(n)
-	for _, want := range []string{"npm-package-registry", "unbound", "workstation"} {
-		if !strings.Contains(got, want) {
-			t.Errorf("the log does not say %q: %s", want, got)
-		}
-	}
-}
-
-func TestAGenesisDocumentMissingAFieldIsRefusedByName(t *testing.T) {
-	registryFiles(t, "", "", `{"at":"127.0.0.1","port":3000,"npm-path":"/api/packages/novox/npm/","as":"mesh-builder"}`)
-	if _, err := packagesFrom("anchor"); err == nil || !strings.Contains(err.Error(), "password") {
-		t.Fatalf("a genesis document with no password was taken: %v", err)
-	}
-}

cmd/mesh-builder/ready.go

@@ -1,44 +0,0 @@
-package main
-
-import (
-	"errors"
-	"fmt"
-	"os"
-	"path/filepath"
-)
-
-// **The build agent says it is ready** (novox/hq issue 544). It listens on nothing, so no http or tcp
-// check can see it work; it writes a mark once it is bound to its worker and pulls build work, and its
-// container's health check runs `mesh-builder ready`, which passes only while the mark is there. Without
-// it the node-engine could judge the agent only alive, and every walk that moved it waited out the whole
-// grace on each machine.
-//
-// The mark lives in the container's own temporary directory, never in the workspace the machine keeps:
-// a new container starts without it, and a restarted one removes it before it binds again.
-func readyMark() string { return filepath.Join(os.TempDir(), "mesh-builder.ready") }
-
-// notReady removes the mark: a holder starting is not taking work until it says so again.
-func notReady() error {
-	if err := os.Remove(readyMark()); err != nil && !errors.Is(err, os.ErrNotExist) {
-		return fmt.Errorf("cannot remove the mark that this agent takes build work (%s): %w", readyMark(), err)
-	}
-	return nil
-}
-
-// taking writes the mark. A mark that cannot be written is said, and the agent goes on building: its
-// check then says it is not ready, which is the truth the gate should hear.
-func taking(seat string) {
-	if err := os.WriteFile(readyMark(), []byte(seat+"\n"), 0o644); err != nil {
-		fmt.Fprintf(os.Stderr, "cannot mark that this agent takes build work (%s): %v\n", readyMark(), err)
-		return
-	}
-	fmt.Fprintf(os.Stderr, "taking build work from %s\n", seat)
-}
-
-// ready is the health check: nil when this container's agent is bound and pulling build work.
-func ready() error {
-	if _, err := os.Stat(readyMark()); err != nil {
-		return fmt.Errorf("not taking build work yet: %s is not there", readyMark())
-	}
-	return nil
-}

cmd/mesh-builder/ready_test.go

@@ -1,32 +0,0 @@
-package main
-
-import (
-	"os"
-	"testing"
-)
-
-// The health check passes only between the agent saying it takes work and its next start (novox/hq
-// issue 544).
-func TestTheAgentIsReadyOnlyOnceItTakesWork(t *testing.T) {
-	t.Setenv("TMPDIR", t.TempDir())
-	if err := ready(); err == nil {
-		t.Fatal("an agent that never took work is ready")
-	}
-	taking("mesh-build-machine")
-	if err := ready(); err != nil {
-		t.Fatalf("an agent taking work is not ready: %v", err)
-	}
-	// Started again, it is not ready until it binds again.
-	if err := notReady(); err != nil {
-		t.Fatal(err)
-	}
-	if err := ready(); err == nil {
-		t.Fatal("an agent starting again is ready before it takes work")
-	}
-	if err := notReady(); err != nil {
-		t.Fatalf("removing a mark that is not there failed: %v", err)
-	}
-	if _, err := os.Stat(readyMark()); err == nil {
-		t.Fatal("the mark is still there")
-	}
-}

cmd/mesh-builder/seat_test.go

@@ -1,27 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// The seat a build machine serves comes from its credential (novox/hq ADR 0190 handover).
-func TestTheCredentialSaysWhichBuildRoleThisMachineServes(t *testing.T) {
-	var held Credential
-	if err := json.Unmarshal([]byte(`{"url":"nats://bus:4222","user":"anchor.builder","password":"x",
-		"claims":[{"seat":"mesh-build-machine","scope":"mesh","serves":[]}]}`), &held); err != nil {
-		t.Fatal(err)
-	}
-	if got := link.BuildSeatClaimed(held.seatsClaimed()); got != "mesh-build-machine" {
-		t.Errorf("the old builder's credential serves %q", got)
-	}
-	var bare Credential
-	if err := json.Unmarshal([]byte(`{"url":"nats://bus:4222","user":"anchor.build-agent","password":"x"}`), &bare); err != nil {
-		t.Fatal(err)
-	}
-	if got := link.BuildSeatClaimed(bare.seatsClaimed()); got != link.TheBuildMachine {
-		t.Errorf("a credential without claims serves %q, want %s", got, link.TheBuildMachine)
-	}
-}

cmd/mesh-builder/stdout_test.go

@@ -1,44 +0,0 @@
-package main
-
-import (
-	"os"
-	"strings"
-	"testing"
-)
-
-// **The genesis path writes its result to stdout and nothing else there.** The installer captures
-// stdout alone and parses it as JSON; one stray log line makes that fail with "invalid character"
-// — exactly what a builder fmt.Printf caused, breaking a build that had worked. This keeps
-// diagnostics on stderr so a future print cannot repeat it silently.
-func TestBuilderDiagnosticsStayOffStdout(t *testing.T) {
-	allowed := map[string]bool{
-		"string(body)": true, // once.go: the result JSON, which IS stdout
-		"version)":     true, // --version
-		`"stopping")`:  true, // the loop.s shutdown line
-		"usage)":       true, // --help text, for a human
-	}
-	for _, file := range []string{"once.go", "main.go"} {
-		src, err := os.ReadFile(file)
-		if err != nil {
-			t.Fatal(err)
-		}
-		for i, raw := range strings.Split(string(src), "\n") {
-			line := strings.TrimSpace(raw)
-			if !strings.HasPrefix(line, "fmt.Printf(") &&
-				!strings.HasPrefix(line, "fmt.Println(") &&
-				!strings.HasPrefix(line, "fmt.Print(") {
-				continue
-			}
-			ok := false
-			for token := range allowed {
-				if strings.Contains(line, token) {
-					ok = true
-				}
-			}
-			if !ok {
-				t.Errorf("%s:%d writes a diagnostic to stdout, which the installer parses as JSON:\n  %s",
-					file, i+1, line)
-			}
-		}
-	}
-}

cmd/mesh-builder/where_test.go

@@ -1,225 +0,0 @@
-package main
-
-import (
-	"crypto/ed25519"
-	"crypto/rand"
-	"crypto/sha256"
-	"crypto/tls"
-	"crypto/x509"
-	"crypto/x509/pkix"
-	"encoding/hex"
-	"math/big"
-	"net"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/broker"
-)
-
-// Where a builder publishes.
-//
-// Preferably from the mesh: a builder that is a module requires an artifact store, and the mesh
-// writes it a binding saying which machine answers and on what port. Reading it means the address
-// is not a setting somebody keeps in step by hand.
-
-func binding(t *testing.T, body string) string {
-	t.Helper()
-	path := filepath.Join(t.TempDir(), "artifact-store.json")
-	if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	return path
-}
-
-func TestTheMeshSaysWhereToPublish(t *testing.T) {
-	t.Setenv("MESH_BINDING", binding(t, `{"binding":1,"provision":"artifact-store",
-		"from":"anchor","at":"anchor.internal","serves":{"port":5000,"scheme":"http"}}`))
-	where, err := whereToPublish()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if where != "anchor.internal:5000" {
-		t.Fatalf("got %q", where)
-	}
-}
-
-func TestABindingWithNoAddressIsRefused(t *testing.T) {
-	// The provider is not on the private network, so there is no name to reach it by. Falling
-	// back to anything would publish to a store on the wrong machine and be found out much later.
-	t.Setenv("MESH_BINDING", binding(t, `{"binding":1,"from":"anchor","serves":{"port":5000}}`))
-	_, err := whereToPublish()
-	if err == nil {
-		t.Fatal("a binding with nowhere to reach was accepted")
-	}
-	if !strings.Contains(err.Error(), "anchor") {
-		t.Fatalf("the failure does not name the machine: %v", err)
-	}
-}
-
-func TestABindingWithNoPortIsRefused(t *testing.T) {
-	t.Setenv("MESH_BINDING", binding(t, `{"binding":1,"from":"a","at":"a.internal","serves":{}}`))
-	if _, err := whereToPublish(); err == nil {
-		t.Fatal("a binding saying nothing about a port was accepted")
-	}
-}
-
-func TestTheVariableStillWorksForABuilderRunByAPerson(t *testing.T) {
-	// Which is how this started and how it is still run while being developed.
-	t.Setenv("MESH_BINDING", "")
-	t.Setenv("MESH_REGISTRY", "127.0.0.1:5000")
-	where, err := whereToPublish()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if where != "127.0.0.1:5000" {
-		t.Fatalf("got %q", where)
-	}
-}
-
-func TestNeitherIsRefusedRatherThanGuessed(t *testing.T) {
-	t.Setenv("MESH_BINDING", "")
-	t.Setenv("MESH_REGISTRY", "")
-	if _, err := whereToPublish(); err == nil {
-		t.Fatal("a builder with nowhere to publish reported somewhere")
-	}
-}
-
-func TestTheCredentialComesFromAFileTheMeshSealed(t *testing.T) {
-	// A builder that is a module is given its credential the way every module is: sealed to the
-	// machine and written by the host. An environment variable instead would put the one copy
-	// that matters through a terminal and a process listing.
-	path := filepath.Join(t.TempDir(), "broker")
-	if err := os.WriteFile(path, []byte("amqps://a-builder:secret@broker.internal:5671/\n"), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	t.Setenv("MESH_BROKER_FILE", path)
-	t.Setenv("MESH_BROKER_AMQP", "amqp://should-not-be-used@nowhere/")
-
-	got, err := brokerFrom()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if got.URL != "amqps://a-builder:secret@broker.internal:5671/" {
-		t.Fatalf("got %q", got.URL)
-	}
-}
-
-// The credential the mesh seals carries what to check the broker's certificate against, because a
-// mesh's broker presents a certificate of the mesh's own and no public trust store has it. A URL
-// alone can only reach a broker somebody else vouches for.
-func TestTheSealedCredentialCarriesWhatVerifiesTheBroker(t *testing.T) {
-	path := filepath.Join(t.TempDir(), "broker")
-	if err := os.WriteFile(path, []byte(
-		`{"url":"amqps://a-builder:secret@broker.internal:5671/","fingerprint":"abc123"}`),
-		0o600); err != nil {
-		t.Fatal(err)
-	}
-	t.Setenv("MESH_BROKER_FILE", path)
-	t.Setenv("MESH_BROKER_AMQP", "")
-
-	got, err := brokerFrom()
-	if err != nil {
-		t.Fatal(err)
-	}
-	if got.URL != "amqps://a-builder:secret@broker.internal:5671/" {
-		t.Fatalf("the url was lost: %q", got.URL)
-	}
-	if got.Fingerprint != "abc123" {
-		t.Fatal("the builder was given nothing to check the broker against, so it can only " +
-			"connect to a broker some public authority vouches for")
-	}
-}
-
-func TestAnEmptyCredentialFileIsRefused(t *testing.T) {
-	// Otherwise the builder connects as nobody and is refused, with the reason three layers away.
-	path := filepath.Join(t.TempDir(), "broker")
-	if err := os.WriteFile(path, []byte("\n"), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	t.Setenv("MESH_BROKER_FILE", path)
-	t.Setenv("MESH_BROKER_AMQP", "")
-	if _, err := brokerFrom(); err == nil {
-		t.Fatal("an empty credential was accepted")
-	}
-}
-
-func TestABuilderWithNoCredentialAtAllSaysSo(t *testing.T) {
-	t.Setenv("MESH_BROKER_FILE", "")
-	t.Setenv("MESH_BROKER_AMQP", "")
-	if _, err := brokerFrom(); err == nil {
-		t.Fatal("a builder with no broker reported one")
-	}
-}
-
-// The pin is compared in the spelling the mesh writes it.
-//
-// A bare digest against a written fingerprint never matches, and the failure is indistinguishable
-// from being pointed at the wrong broker — which is the one thing this check exists to report
-// truthfully. It cost a lab run.
-func TestThePinIsComparedInTheSpellingTheMeshWritesIt(t *testing.T) {
-	certificate, key := aServerCertificate(t)
-	der := certificate.Certificate[0]
-	sum := sha256.Sum256(der)
-	written := "sha256:" + hex.EncodeToString(sum[:])
-
-	listener, err := tls.Listen("tcp", "127.0.0.1:0", &tls.Config{
-		Certificates: []tls.Certificate{certificate}, MinVersion: tls.VersionTLS12,
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	defer listener.Close()
-	go func() {
-		for {
-			conn, err := listener.Accept()
-			if err != nil {
-				return
-			}
-			_ = conn.(*tls.Conn).Handshake()
-			conn.Close()
-		}
-	}()
-	_ = key
-
-	// The pin the mesh wrote must be accepted.
-	if err := handshakeWith(listener.Addr().String(), written); err != nil {
-		t.Fatalf("the broker this builder was told about was refused: %v", err)
-	}
-	// And a different one refused, or the check reports nothing.
-	other := "sha256:" + strings.Repeat("ab", 32)
-	if err := handshakeWith(listener.Addr().String(), other); err == nil {
-		t.Fatal("a broker this builder was not told about was accepted")
-	}
-}
-
-// handshakeWith runs the pin check the builder dials with against an address.
-func handshakeWith(address, pin string) error {
-	conn, err := tls.Dial("tcp", address, broker.PinnedToFingerprint(pin))
-	if err != nil {
-		return err
-	}
-	return conn.Close()
-}
-
-func aServerCertificate(t *testing.T) (tls.Certificate, ed25519.PrivateKey) {
-	t.Helper()
-	public, private, err := ed25519.GenerateKey(rand.Reader)
-	if err != nil {
-		t.Fatal(err)
-	}
-	template := &x509.Certificate{
-		SerialNumber: big.NewInt(1),
-		Subject:      pkix.Name{CommonName: "a broker"},
-		NotBefore:    time.Now().Add(-time.Hour),
-		NotAfter:     time.Now().Add(time.Hour),
-		IPAddresses:  []net.IP{net.ParseIP("127.0.0.1")},
-	}
-	der, err := x509.CreateCertificate(rand.Reader, template, template, public, private)
-	if err != nil {
-		t.Fatal(err)
-	}
-	return tls.Certificate{Certificate: [][]byte{der}, PrivateKey: private}, private
-}

cmd/mesh-controller/accept_outside.go

@@ -1,145 +0,0 @@
-package main
-
-import (
-	"context"
-	"fmt"
-	"sort"
-	"strings"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// A provision whose credential only a person outside the mesh can give (novox/hq ADR 0337, issue 164, issue 165):
-// given once for its provider, at the controller's terminal, and sealed in one act to every consumer that binds the
-// provision from that provider now. The value is never read back, printed or kept.
-
-// outsideOffer is the provider module's own name when `secret accept <node> <module> <name>` names a provision that
-// module offers with a credential issued outside the mesh, and "" when it names anything else (an own secret, or a
-// pair with --provider).
-func outsideOffer(ctx context.Context, module, name, provider string) (string, error) {
-	if provider != "" {
-		return "", nil
-	}
-	open, err := openStores(ctx)
-	if err != nil {
-		return "", err
-	}
-	defer open.Close()
-	shelf, err := open.inventory.Catalogue(ctx)
-	if err != nil {
-		return "", err
-	}
-	if m, known := shelf[module]; known && m.IssuedOutsideOf(name) {
-		return module, nil
-	}
-	return "", nil
-}
-
-// offeredOutsideBy is a module that offers the provision with a credential issued outside the mesh, or "".
-func offeredOutsideBy(ctx context.Context, provision string) (string, error) {
-	open, err := openStores(ctx)
-	if err != nil {
-		return "", err
-	}
-	defer open.Close()
-	shelf, err := open.inventory.Catalogue(ctx)
-	if err != nil {
-		return "", err
-	}
-	module, _ := catalogue.OffersIssuedOutside(shelf, provision)
-	return module, nil
-}
-
-// consumersFrom is every consumer that binds a provision from one provider now, found by resolving every machine as
-// its next send would, and the machines that could not be resolved, with why.
-func consumersFrom(ctx context.Context, open *stores, provider, providerModule, provision string) (
-	[]inventory.PairEnd, []string, error) {
-	nodes, err := open.inventory.Nodes(ctx)
-	if err != nil {
-		return nil, nil, err
-	}
-	var out []inventory.PairEnd
-	var unresolved []string
-	for _, n := range nodes {
-		plan, _, err := planFor(ctx, open, n.Name)
-		if err != nil {
-			unresolved = append(unresolved, fmt.Sprintf("%s: %s", n.Name, oneLine(err.Error())))
-			continue
-		}
-		out = append(out, bindsFrom(plan, n.Name, provider, providerModule, provision)...)
-	}
-	return out, unresolved, nil
-}
-
-// bindsFrom is every consumer on one machine whose resolution answers the provision from that provider. Pure.
-func bindsFrom(plan catalogue.Resolution, machine, provider, providerModule, provision string) []inventory.PairEnd {
-	var out []inventory.PairEnd
-	for _, need := range plan.Needs {
-		if need.ByRecord || need.Name != provision || need.From != provider {
-			continue
-		}
-		if need.Module != "" && need.Module != providerModule {
-			continue
-		}
-		out = append(out, inventory.PairEnd{Consumer: machine, ConsumerModule: need.For, Local: need.Local})
-	}
-	sort.Slice(out, func(i, j int) bool {
-		return out[i].ConsumerModule+"\x00"+out[i].Local < out[j].ConsumerModule+"\x00"+out[j].Local
-	})
-	return out
-}
-
-// acceptForProvision gives a provision's credential issued outside the mesh, once for its provider (ADR 0337 §3).
-func acceptForProvision(ctx context.Context, provider, providerModule, provision, value string) error {
-	open, err := openStores(ctx)
-	if err != nil {
-		return err
-	}
-	defer open.Close()
-	consumers, unresolved, err := consumersFrom(ctx, open, provider, providerModule, provision)
-	if err != nil {
-		return err
-	}
-	accepted, err := open.inventory.AcceptSecretForProvision(ctx, provision, provider, providerModule, value, consumers)
-	value = ""
-	if err != nil {
-		return err
-	}
-	fmt.Print(acceptedSaid(provider, providerModule, provision, accepted, unresolved))
-	if len(accepted.Sealed) == 0 {
-		return nil
-	}
-	if err := sendTo(ctx, open, accepted.Machines); err != nil {
-		return fmt.Errorf("%s is sealed and could not be sent: %w; `push %s` sends it", provision, err,
-			strings.Join(accepted.Machines, "`, `push "))
-	}
-	fmt.Printf("  sent %s; each consumer starts again on it\n", strings.Join(accepted.Machines, ", "))
-	return nil
-}
-
-// acceptedSaid is what one accept for a provider did, in words that never carry the value. Pure.
-func acceptedSaid(provider, providerModule, provision string, a inventory.ProvisionAccepted, unresolved []string) string {
-	var b strings.Builder
-	if len(a.Sealed) == 0 {
-		fmt.Fprintf(&b, "%s from %s on %s: no consumer binds it now, so nothing was sealed; a consumer that binds "+
-			"later waits for it, and this line given again seals it to every consumer then\n", provision,
-			providerModule, provider)
-	} else {
-		var names []string
-		for _, c := range a.Sealed {
-			names = append(names, fmt.Sprintf("%s on %s%s", c.ConsumerModule, c.Consumer, asLocal(c.Local)))
-		}
-		fmt.Fprintf(&b, "%s from %s on %s is given, sealed to %s and to %s\n", provision, providerModule, provider,
-			strings.Join(names, ", "), provider)
-		fmt.Fprintf(&b, "  the mesh cannot read it back, never makes one of its own for it, and will not rotate it\n")
-	}
-	for _, c := range a.Unsealable {
-		fmt.Fprintf(&b, "  not sealed to %s on %s: no sealing key on that machine; give it again once it has one\n",
-			c.ConsumerModule, c.Consumer)
-	}
-	for _, u := range unresolved {
-		fmt.Fprintf(&b, "  not known whether a consumer on %s binds it, which did not resolve; give it again once it does\n", u)
-	}
-	return b.String()
-}

cmd/mesh-controller/acting.go

@@ -1,375 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"os"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/nats-io/nats.go"
-	"github.com/nats-io/nats.go/jetstream"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/lease"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// Acting under the lease (novox/hq to-be 45 §6, ADR 0227 rule 1).
-//
-// **Only the instance holding the lease acts**: sends a declaration, writes a plan, a condition or a
-// call. Every one of those passes theLease.epoch, which answers the epoch the act carries or why it may
-// not happen. Three ways a process stands to the lease:
-//
-//   - **The serving controller** takes it before it does anything else — before it asserts the bus's
-//     objects, which are the controller's to write — waiting while another holds it, and renews it.
-//     A renewal refused or failed is the lease lost: the gate closes at once and the process exits, so
-//     its service manager restarts it as a candidate (serve, in push.go).
-//   - **A command run at a shell** — `push` in the installer, the lab, a person repairing a mesh whose
-//     controller is down (issue 201) — acts **under the holder's epoch** when a controller holds the
-//     lease: it is the same mesh's word, composed and sent under the store's hold of each machine like
-//     the serving controller's, and the epoch it carries is read at the moment it acts, so a handover
-//     between makes it stale and refused like any other. **When nobody holds the lease, the command
-//     takes it** for as long as it runs and gives it back; a controller starting meanwhile waits for
-//     it, as it would for another controller.
-//   - **A process with no bus** — a test, a command that only reads — acts with no epoch and is
-//     refused nothing: there is nothing to order against, and nothing it does reaches a machine.
-//
-// **Unleased, said and temporary.** A serving controller whose bus refuses it the lease's key — the bus's
-// user list is older than this build and does not grant the bucket yet — and that sees no other holder
-// serves without one, as every controller did before the lease: declarations carry no epoch, which no
-// node-engine refuses. Said once, kept as a condition (S12), and tried again every renewal interval; the
-// first push that sends the bus its new user list grants it, and the next try takes it. Refusing to act
-// instead would be a controller that can never send the user list that lets it act.
-
-// actor is this process's standing to the lease.
-type actor struct {
-	mu sync.Mutex
-	// held is the lease this process holds: the serving controller's, or a command's own.
-	held *lease.Lease
-	// unleased is why a serving controller acts without the lease; empty while it holds it or is not
-	// serving.
-	unleased string
-	// serving is a serving controller, which never borrows another's epoch.
-	serving bool
-	// kv is the lease bucket, for a command to read the holder's epoch from.
-	kv    jetstream.KeyValue
-	close func()
-	// noBus is a process with no bus configured.
-	noBus bool
-	// reset is when the lease bucket was found raised again from nothing and its revisions moved past
-	// the highest epoch issued, and what was said of it; zero when it was not (S12).
-	reset     time.Time
-	resetSaid string
-	// renewEvery and poll, when set, are how often the serving controller renews the lease it holds and
-	// looks again at one another holds, in place of the lease's own: a test's, so two controllers hand the
-	// lease over in a second rather than in a renewal of five (novox/hq issue 591). A renewal is given
-	// the lease's own RenewEvery to answer however often it is made, so a slow bus does not lose it.
-	renewEvery, poll time.Duration
-}
-
-// theLease is this process's standing to the lease.
-var theLease = &actor{}
-
-// instance names this process among controller instances: its machine, its process and when it
-// started. The lease's holder and every call this process keeps carry it.
-var instance = func() string {
-	host, _ := os.Hostname()
-	return fmt.Sprintf("controller@%s pid %d since %s", host, os.Getpid(), time.Now().UTC().Format(time.RFC3339))
-}()
-
-// epoch is the gate: the epoch an act carries — zero for none — or why it may not happen.
-func (a *actor) epoch(ctx context.Context) (uint64, error) {
-	a.mu.Lock()
-	held, serving, unleased, noBus := a.held, a.serving, a.unleased, a.noBus
-	a.mu.Unlock()
-	switch {
-	case held != nil:
-		return held.Epoch()
-	case serving && unleased != "":
-		return 0, nil
-	case serving:
-		return 0, lease.ErrNotHeld
-	case noBus:
-		return 0, nil
-	}
-	return a.forACommand(ctx)
-}
-
-// forACommand is a command's epoch: the holder's, or a lease of its own when nobody holds one.
-func (a *actor) forACommand(ctx context.Context) (uint64, error) {
-	a.mu.Lock()
-	defer a.mu.Unlock()
-	if a.held != nil {
-		return a.held.Epoch()
-	}
-	if a.kv == nil {
-		address, err := broker.BusAddress()
-		if err != nil {
-			// No bus: this process reaches no machine, and has nothing to order against.
-			a.noBus = true
-			return 0, nil
-		}
-		js, err := broker.Dial(address)
-		if err != nil {
-			return 0, fmt.Errorf("the bus cannot be reached, so whether a controller holds the lease cannot be "+
-				"read and nothing is done: %w", err)
-		}
-		api, err := jetstream.New(js.Conn())
-		if err != nil {
-			js.Close()
-			return 0, err
-		}
-		reading, cancel := context.WithTimeout(ctx, 10*time.Second)
-		defer cancel()
-		if err := broker.EnsureLeaseBucket(reading, api); err != nil {
-			js.Close()
-			return 0, err
-		}
-		kv, err := api.KeyValue(reading, broker.LeaseBucket)
-		if err != nil {
-			js.Close()
-			return 0, err
-		}
-		a.kv, a.close = kv, js.Close
-		if _, found, err := lease.Current(reading, kv); err == nil && !found {
-			// Nobody: this command takes it for as long as it runs.
-			l, err := lease.Open(reading, api, broker.LeaseBucket, lease.Options{Holder: holderOf(instance),
-				Say: func(format string, args ...any) { fmt.Printf(format+"\n", args...) }})
-			if err != nil {
-				return 0, err
-			}
-			epoch, err := l.TryTake(reading)
-			if err != nil {
-				return 0, fmt.Errorf("no controller holds the lease and this command could not take it: %w", err)
-			}
-			keeping, stop := context.WithCancel(context.Background())
-			go l.Keep(keeping)
-			a.held = l
-			closeBus := a.close
-			a.close = func() {
-				stop()
-				l.Release(context.Background())
-				closeBus()
-			}
-			return epoch, nil
-		}
-	}
-	reading, cancel := context.WithTimeout(ctx, 10*time.Second)
-	defer cancel()
-	holder, found, err := lease.Current(reading, a.kv)
-	if err != nil {
-		return 0, fmt.Errorf("who holds the controller lease cannot be read, so nothing is done: %w", err)
-	}
-	if !found {
-		return 0, errors.New("the controller that held the lease while this command ran let go of it; nothing " +
-			"more is done under an epoch nobody holds — run the command again")
-	}
-	return holder.Epoch, nil
-}
-
-// release gives back what this process holds, at its end.
-func (a *actor) release() {
-	a.mu.Lock()
-	closing := a.close
-	a.close = nil
-	a.mu.Unlock()
-	if closing != nil {
-		closing()
-	}
-}
-
-// holderOf is this process as the lease's holder.
-func holderOf(instance string) lease.Holder {
-	host, _ := os.Hostname()
-	build := runningBuild()
-	if build == "" {
-		build = version
-	}
-	return lease.Holder{Instance: instance, Host: host, Build: build}
-}
-
-// RunningBuildVar is where the declaration tells this process which build it is (module.json, the
-// controller process's env): the version its bundle is delivered as, `${version}` composed by the
-// catalogue from the bundle's digest. Empty for a process placed by hand.
-const RunningBuildVar = "MESH_CONTROLLER_VERSION"
-
-// runningBuild is the version of the build this process is, or empty when the declaration did not say.
-func runningBuild() string {
-	return strings.TrimSpace(os.Getenv(RunningBuildVar))
-}
-
-// serveUnderTheLease takes the lease for the serving controller, waiting while another holds it, and
-// keeps it until ctx ends. Lost is closed when it is lost; the caller exits on it.
-func (a *actor) serveUnderTheLease(ctx context.Context, inv *inventory.Inventory, address string) (lost <-chan struct{}, err error) {
-	a.mu.Lock()
-	a.serving = true
-	a.mu.Unlock()
-	// Its own connection, held as long as the lease, and named so (novox/hq issue 327).
-	js, err := broker.Dial(address, nats.Name(broker.ConnectionName+" lease"))
-	if err != nil {
-		return nil, fmt.Errorf("the mesh is on the bus at %s and this control plane cannot reach it to take the "+
-			"lease: %w", broker.BareAddress(address), err)
-	}
-	api, err := jetstream.New(js.Conn())
-	if err != nil {
-		js.Close()
-		return nil, err
-	}
-	asserting, cancel := context.WithTimeout(ctx, 10*time.Second)
-	err = broker.EnsureLeaseBucket(asserting, api)
-	cancel()
-	if err != nil {
-		js.Close()
-		return nil, err
-	}
-	say := func(format string, args ...any) { fmt.Printf(format+"\n", args...) }
-	l, err := lease.Open(ctx, api, broker.LeaseBucket, lease.Options{Holder: holderOf(instance),
-		RenewEvery: a.renewEvery, RenewWithin: lease.RenewEvery, Poll: a.poll, Floor: inv.HighestEpoch, Say: say, Health: controllerHealth, Moved: func(was, floor uint64) {
-			a.mu.Lock()
-			defer a.mu.Unlock()
-			a.reset = time.Now()
-			a.resetSaid = fmt.Sprintf("the lease bucket was at revision %d with epoch %d already issued: it was "+
-				"raised again from nothing (a bus whose data was replaced), and its revisions were moved past %d so "+
-				"no machine refuses the next epoch", was, floor, floor)
-		}})
-	if err != nil {
-		js.Close()
-		return nil, err
-	}
-	gone := make(chan struct{})
-	epoch, err := l.Take(ctx)
-	switch {
-	case ctx.Err() != nil:
-		js.Close()
-		return nil, ctx.Err()
-	case err != nil && !errors.Is(err, lease.ErrUnwritable):
-		// Whether another controller acts cannot be told: this one does not act, and exits to try again.
-		js.Close()
-		return nil, err
-	case err != nil:
-		// Nobody holds it and the bus will not let it be written: unleased, said, tried again (see above).
-		a.mu.Lock()
-		a.unleased = err.Error()
-		a.mu.Unlock()
-		say("this controller serves WITHOUT the lease: %v. Its declarations carry no epoch; it tries again "+
-			"every %s, and the first push that sends the bus its user list grants it", err, lease.RenewEvery)
-		go a.takeWhenGranted(ctx, l, inv, gone)
-	default:
-		a.took(ctx, l, inv, epoch, gone)
-	}
-	a.mu.Lock()
-	a.close = func() {
-		if held, err := l.Epoch(); err == nil {
-			ending, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-			if err := inv.EndEpoch(ending, held, inventory.EpochReleased); err != nil {
-				say("how epoch %d ended could not be recorded: %v", held, err)
-			}
-			cancel()
-		}
-		l.Release(context.Background())
-		js.Close()
-	}
-	a.mu.Unlock()
-	return gone, nil
-}
-
-// took is the lease taken: recorded, earlier epochs nobody gave back ended as expired, kept.
-func (a *actor) took(ctx context.Context, l *lease.Lease, inv *inventory.Inventory, epoch uint64, gone chan struct{}) {
-	a.mu.Lock()
-	a.held, a.unleased = l, ""
-	a.mu.Unlock()
-	h := holderOf(instance)
-	recording, cancel := context.WithTimeout(ctx, 10*time.Second)
-	expired, err := inv.TookEpoch(recording, inventory.Epoch{Epoch: epoch, Instance: h.Instance, Host: h.Host,
-		Build: h.Build, Taken: time.Now()})
-	cancel()
-	if err != nil {
-		fmt.Printf("epoch %d could not be recorded as taken, so a stale refusal from it will not name it: %v\n", epoch, err)
-	}
-	for _, e := range expired {
-		fmt.Printf("the controller of epoch %d (%s) stopped renewing the lease without giving it back: it is "+
-			"taken over at epoch %d\n", e.Epoch, e.Instance, epoch)
-	}
-	go l.Keep(ctx)
-	go func() {
-		<-l.Lost()
-		if ctx.Err() == nil {
-			why := l.LostWhy()
-			ending, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-			_ = inv.EndEpoch(ending, epoch, inventory.EpochLost)
-			cancel()
-			fmt.Printf("the controller lease was lost (epoch %d): %v — this controller stops and exits, to "+
-				"be started again as a candidate\n", epoch, why)
-		}
-		close(gone)
-	}()
-}
-
-// takeWhenGranted tries the lease again every renewal interval while serving unleased, and stops this
-// controller if another took it meanwhile: two serving at once is what the lease is for.
-func (a *actor) takeWhenGranted(ctx context.Context, l *lease.Lease, inv *inventory.Inventory, gone chan struct{}) {
-	tick := time.NewTicker(lease.RenewEvery)
-	defer tick.Stop()
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-tick.C:
-		}
-		epoch, err := l.TryTake(ctx)
-		if errors.Is(err, lease.ErrTaken) {
-			fmt.Printf("another controller took the lease while this one served without it: %v — this one "+
-				"stops and exits\n", err)
-			close(gone)
-			return
-		}
-		if err != nil {
-			// Still not written, or not readable this time: unleased, said by S12, tried again.
-			a.mu.Lock()
-			a.unleased = err.Error()
-			a.mu.Unlock()
-			continue
-		}
-		a.took(ctx, l, inv, epoch, gone)
-		return
-	}
-}
-
-// standing is what `status` and the self-check say of this process and the lease.
-type standing struct {
-	Epoch    uint64
-	Held     bool
-	Renewed  time.Time
-	Unleased string
-	// Reset is when the lease bucket was found raised again from nothing, and ResetSaid what of it.
-	Reset     time.Time
-	ResetSaid string
-}
-
-func (a *actor) standing() standing {
-	a.mu.Lock()
-	held, unleased, reset, resetSaid := a.held, a.unleased, a.reset, a.resetSaid
-	a.mu.Unlock()
-	st := standing{Unleased: unleased, Reset: reset, ResetSaid: resetSaid}
-	if held == nil {
-		return st
-	}
-	epoch, err := held.Epoch()
-	st.Epoch, st.Held, st.Renewed = epoch, err == nil, held.Renewed()
-	return st
-}
-
-// The gates, given to what acts: a declaration's send (link) and a plan's write (the inventory).
-func init() {
-	link.ActingGate = func(ctx context.Context) error {
-		_, err := theLease.epoch(ctx)
-		if err != nil {
-			return fmt.Errorf("this controller may not send: %w", err)
-		}
-		return nil
-	}
-}

cmd/mesh-controller/acts.go

@@ -1,435 +0,0 @@
-package main
-
-import (
-	"context"
-	"fmt"
-	"github.com/novox/mesh-controller/internal/broker"
-	"io"
-	"slices"
-	"sort"
-	"strings"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// The things the mesh can be asked to do, separated from how it was asked.
-//
-// **A surface is an adapter with no decisions in it** (novox/hq ADR 0035). The command line and
-// the command API call the same functions here, so an assignment refused at one is refused at the
-// other for the same reason and in the same words. The moment a surface can accept something
-// another would reject, the mesh has two answers to one question and people learn which to trust.
-//
-// Each returns what happened as text a person can read and a caller can pass on. Neither surface
-// composes its own explanation, because two explanations of one refusal drift.
-
-// assign puts a module on a node, and says at once what in the mesh no longer works out.
-//
-// The assignment is kept even when the node does not resolve: it is what a person meant, and
-// assignment is not an ordering. A consumer assigned before its provider does not resolve for as
-// long as it takes to assign the provider, and refusing the first half of a pair would make the
-// order somebody types two commands in part of the mesh's rules.
-//
-// **What is checked is the mesh, not the one machine** — because that is what the assignment
-// changes. novox/hq 04-ISSUES/017 names the shape: an action can succeed into a state its own
-// verify rejects, and it happens when the action's test is not the test the verify uses. Here the
-// action tested one node and the verify is resolution over all of them, so an assignment could be
-// reported as fine while it took a provision away from every other machine — a module offering a
-// mesh-scoped provision stops offering it the moment its own node stops resolving, and every
-// consumer elsewhere is then told *nothing in this mesh provides it*, with a remedy that names a
-// module already assigned. That was found on a four-node raise and read as a version bump breaking
-// provider recognition; it was neither the version nor the provider.
-//
-// It costs a resolution per machine. Assignment is a person typing a command, and being told which
-// machines this just blocked is worth more than the milliseconds.
-func assign(ctx context.Context, open *stores, node string, modules ...string) (string, error) {
-	return assignWith(ctx, open, node, assignOptions{}, modules...)
-}
-
-// assignWith is assign asked with its options: build, for a module known and not built (novox/hq issue 325).
-func assignWith(ctx context.Context, open *stores, node string, opts assignOptions, modules ...string) (string, error) {
-	if len(modules) == 0 {
-		return "", fmt.Errorf("assign %s names no module", node)
-	}
-	if err := refusedMovingTheController(modules); err != nil {
-		return "", err
-	}
-	// Every line of the answer comes from the one resolution after the write (novox/hq issue 237):
-	// what the reads before it would say about a machine left out is not the answer's.
-	ctx = leftOutSaidBy(ctx, io.Discard)
-	// Held while it is recorded, so it cannot land between a converge's preview and its flip and
-	// be taken without ever having been previewed (novox/hq ADR 0100).
-	ctx, release, err := holdNodes(ctx, open, []string{node})
-	if err != nil {
-		return "", err
-	}
-	defer release()
-	// **A module the catalogue does not hold is looked for further before it is refused** (novox/hq issue
-	// 325): a build in flight keeps the assignment pending, a module known and not built is said with how to
-	// build it, and only a name the mesh never heard of is refused as unknown. Several modules in one act
-	// are judged together (ADR 0207), so an act naming one not registered is not made in part.
-	if missing, err := notInCatalogue(ctx, open, modules); err != nil {
-		return "", err
-	} else if len(missing) > 0 {
-		if len(modules) == 1 {
-			return notRegistered(ctx, open, node, modules[0], opts)
-		}
-		var lines []string
-		for _, m := range missing {
-			where, err := whereIs(ctx, open.inventory, m, time.Now())
-			if err != nil {
-				return "", err
-			}
-			lines = append(lines, where.said)
-		}
-		return "", fmt.Errorf("%w: nothing was assigned, since modules assigned together are judged together "+
-			"(ADR 0207) and %s not registered:\n  %s\n  assign them together once each is registered, or each "+
-			"alone to keep it pending on its build", inventory.ErrNoSuchModule, strings.Join(missing, ", "),
-			strings.Join(lines, "\n  "))
-	}
-	// **The one assignment refused for what the node lacks** (novox/hq ADR 0207). Everything else
-	// an assignment leaves unresolved is kept, because assignment is not an ordering; a module whose
-	// resources are applied through a seat nothing on the node holds is refused, because that order
-	// — the service manager, the package manager and the runtime before anything that installs,
-	// runs or contains — is the mesh's to keep. Several modules in one act are judged together, so
-	// holders that depend on each other go on in one command.
-	shelf, before, err := seatDependenciesOnAssign(ctx, open, node, modules)
-	if err != nil {
-		return "", err
-	}
-	// **Before the new assignment can unsettle a seat somebody holds only by being alone**
-	// (novox/hq 04-ISSUES/170): what the mesh derived so far is written down, and then the
-	// assignment resolves against a record rather than against a coincidence.
-	settled, err := recordDerivedHolders(ctx, open)
-	if err != nil {
-		return "", err
-	}
-	var lines []string
-	var added []string
-	for _, module := range modules {
-		fresh, err := open.inventory.Assign(ctx, node, module)
-		if err != nil {
-			return strings.Join(lines, "\n"), err
-		}
-		if !fresh {
-			// Nothing changed, and saying "is assigned" would read as an action. One node runs one
-			// of each — the module's name is the assignment's identity (novox/hq ADR 0115).
-			lines = append(lines, fmt.Sprintf(
-				"%s already runs %s — one node runs one of each (ADR 0115); nothing changed", node, module))
-			continue
-		}
-		added = append(added, module)
-		lines = append(lines, fmt.Sprintf("%s is assigned %s", node, module))
-	}
-	if len(added) == 0 {
-		return strings.Join(lines, "\n"), nil
-	}
-	answer := strings.Join(lines, "\n")
-	for _, line := range settled {
-		answer += "\n  " + line
-	}
-	// Its bus credential, in the same act (novox/hq issue 203): an assignment pushed before its
-	// credential exists delivers a process that cannot authenticate and crash-loops until somebody
-	// runs a second verb and a second push. Issued here when the module speaks on the bus and has
-	// no credential yet; kept when it has one, so re-assigning rotates nothing.
-	var issued []string
-	for _, module := range added {
-		if line := issueOnAssign(ctx, open, node, module); line != "" {
-			issued = append(issued, line)
-		}
-	}
-	// **The one resolution the rest of the answer is said from** (novox/hq issue 237), taken after
-	// the write: what this act changed about this node's unmet seat dependencies, and nothing else
-	// (novox/hq ADR 0207) — a dependency of a module just assigned, or one this assignment met; the
-	// rest of the node's list, and every other node's, is `status`'s — and whether the node resolves.
-	after := resolvedAfter(ctx, open, shelf, node)
-	for _, line := range unheldChangeTo(shelf, node, before, after.modules, after.unheld) {
-		answer += "\n  " + line
-	}
-	for _, line := range issued {
-		answer += "\n  " + line
-	}
-	plan, err := after.plan, after.err
-	if err != nil {
-		// Kept, and still refused. Both halves are the answer, and the rest of the mesh is still
-		// worth reporting: this machine's refusal is rarely the only consequence.
-		return answer + blockedElsewhere(ctx, open, node), err
-	}
-	// Kept, and cannot be hosted here. Said at once rather than discovered at push: a module whose
-	// capability the machine lacks is on the wrong machine, and the assignment records what a person
-	// meant while this line says it will not run until it moves. The rest of the node still pushes.
-	isAdded := map[string]bool{}
-	for _, m := range added {
-		isAdded[m] = true
-	}
-	for _, u := range plan.Unhostable {
-		if !isAdded[u.Module] {
-			continue
-		}
-		for _, c := range u.Missing {
-			answer += "\n  but " + catalogue.WrongMachine(u.Module, c, node)
-		}
-	}
-	return answer + fmt.Sprintf("\n  run `push %s` to send it", node) +
-		blockedElsewhere(ctx, open, node), nil
-}
-
-// seatDependenciesOnAssign is the refusal ADR 0207 makes at assignment, or nothing, with the
-// catalogue and the node's assignments it was judged against. Modules already assigned are not new
-// and are not judged again.
-func seatDependenciesOnAssign(ctx context.Context, open *stores, node string, modules []string) (
-	map[string]catalogue.Manifest, []string, error) {
-	shelf, err := open.inventory.Catalogue(ctx)
-	if err != nil {
-		return nil, nil, err
-	}
-	assigned, err := open.inventory.Assigned(ctx, node)
-	if err != nil {
-		return nil, nil, err
-	}
-	already := map[string]bool{}
-	for _, a := range assigned {
-		already[a] = true
-	}
-	var adding []string
-	for _, m := range modules {
-		if !already[m] {
-			adding = append(adding, m)
-		}
-	}
-	// The lines AssignRefusal says beside an assignment it lets through are said by unheldChange
-	// with everything else this act changed, so they are not said twice.
-	if _, err := catalogue.AssignRefusal(shelf, node, assigned, adding); err != nil {
-		return nil, nil, err
-	}
-	// Two modules declaring one path or unit, or one package present and absent, is refused before anything
-	// is recorded (novox/hq ADR 0210, ADR 0303, 04-ISSUES/235): kept, the node would not resolve until one came
-	// off again. Two modules declaring one package present is not a collision (ADR 0303, issue 628).
-	if err := catalogue.CollisionRefusal(shelf, node, assigned, adding); err != nil {
-		return nil, nil, err
-	}
-	return shelf, assigned, nil
-}
-
-// unassign takes modules off a node. What they leave behind is the host's business: a directory
-// holding anything the mesh did not put there is kept (novox/hq ADR 0030).
-//
-// It reports the rest of the mesh for the same reason assign does, and more sharply: taking a
-// module off one machine is the ordinary way to stop providing something to another, and nothing
-// about the command's own output would ever have said so.
-//
-// **Refused when it takes away the last holder of a seat a module left on the node depends on**
-// (novox/hq ADR 0207) — the other side of refusing that module's assignment without one. Several
-// modules in one act are judged together, so a holder and its dependents come off in one command.
-func unassign(ctx context.Context, open *stores, node string, modules ...string) (string, error) {
-	if err := refusedMovingTheController(modules); err != nil {
-		return "", err
-	}
-	if len(modules) == 0 {
-		return "", fmt.Errorf("unassign %s names no module", node)
-	}
-	// One resolution after the write, as assign's answer (novox/hq issue 237).
-	ctx = leftOutSaidBy(ctx, io.Discard)
-	ctx, release, err := holdNodes(ctx, open, []string{node})
-	if err != nil {
-		return "", err
-	}
-	defer release()
-	shelf, err := open.inventory.Catalogue(ctx)
-	if err != nil {
-		return "", err
-	}
-	assigned, err := open.inventory.Assigned(ctx, node)
-	if err != nil {
-		return "", err
-	}
-	// Every one checked before any is taken off, so a refusal leaves the node as it was.
-	runs := map[string]bool{}
-	for _, a := range assigned {
-		runs[a] = true
-	}
-	// A module only pending on the node (novox/hq issue 325) is withdrawn, when it is the act's one module:
-	// that is the undo of an assignment kept while its build runs.
-	if len(modules) == 1 && !runs[modules[0]] {
-		said, withdrawn, err := withdrawPending(ctx, open.inventory, node, modules[0])
-		if err != nil {
-			return "", err
-		}
-		if withdrawn {
-			return said, nil
-		}
-	}
-	for _, module := range modules {
-		if !runs[module] {
-			return "", fmt.Errorf("%s is not assigned to %s", module, node)
-		}
-	}
-	if err := catalogue.UnassignRefusal(shelf, node, assigned, modules); err != nil {
-		return "", err
-	}
-	for _, module := range modules {
-		if err := open.inventory.Unassign(ctx, node, module); err != nil {
-			return "", err
-		}
-	}
-	answer := fmt.Sprintf("%s no longer runs %s — run `push %s` to make it so",
-		node, strings.Join(modules, ", "), node)
-	after := resolvedAfter(ctx, open, shelf, node)
-	for _, line := range unheldChangeTo(shelf, node, assigned, after.modules, after.unheld) {
-		answer += "\n  " + line
-	}
-	// Whether the node itself still resolves, from the same resolution: before, only the rest of the
-	// mesh's reads said it, on standard error and once per other machine.
-	if after.err != nil {
-		if unresolvable(after.err) {
-			answer += fmt.Sprintf("\n  but %s does not resolve now, so nothing will be sent to it:", node)
-		} else {
-			answer += fmt.Sprintf("\n  but whether %s still resolves could not be read:", node)
-		}
-		for _, line := range strings.Split(strings.TrimRight(after.err.Error(), "\n"), "\n") {
-			answer += "\n    " + strings.TrimSpace(line)
-		}
-	}
-	// What it leaves behind that is irreplaceable is kept and retired, never removed (novox/hq ADR 0233).
-	for _, line := range keptOnUnassign(ctx, open.inventory, node, modules) {
-		answer += "\n  " + line
-	}
-	return answer + blockedElsewhere(ctx, open, node), nil
-}
-
-// afterAct is the one resolution of a node an act's answer is said from, taken after its write
-// (novox/hq issue 237): the plan or why there is none, the modules it has on the node, and its unmet
-// seat dependencies.
-type afterAct struct {
-	plan    catalogue.Resolution
-	err     error
-	modules []string
-	unheld  []catalogue.Unheld
-}
-
-// resolvedAfter resolves the node as `plan` does, once, after the act's write. When the node resolves,
-// its modules and unmet seat dependencies are the resolution's — the closure, so a holder pulled in by
-// a requirement counts as `plan` counts it. When it does not, they are judged over the assignments read
-// after the write, which can only find more unmet than the closure would: a seat said held there is
-// held in the closure too.
-func resolvedAfter(ctx context.Context, open *stores, shelf map[string]catalogue.Manifest, node string) afterAct {
-	plan, _, err := planFor(ctx, open, node)
-	if err == nil {
-		out := afterAct{plan: plan, unheld: plan.Unheld}
-		for _, m := range plan.Modules {
-			out.modules = append(out.modules, m.Module)
-		}
-		return out
-	}
-	out := afterAct{err: err}
-	assigned, readErr := open.inventory.Assigned(ctx, node)
-	if readErr != nil {
-		return out
-	}
-	out.modules, out.unheld = assigned, unheldOver(shelf, node, assigned)
-	return out
-}
-
-// splitModules is a surface's one `module` field as the modules it names: several, comma-separated,
-// are one act (novox/hq ADR 0207), so the holders that depend on each other go on together from the
-// command API and the controller seat's verbs as they do from the command line.
-func splitModules(field string) []string {
-	var out []string
-	for _, m := range strings.Split(field, ",") {
-		if m = strings.TrimSpace(m); m != "" {
-			out = append(out, m)
-		}
-	}
-	return out
-}
-
-// blockedElsewhere is every OTHER machine that cannot be worked out as things now stand.
-//
-// **The state, not the cause.** Saying "this assignment broke laptop" would mean resolving the
-// whole mesh twice and would still be a guess about which of several changes did it; saying
-// "laptop cannot be worked out, and here is what it says" is true, is what somebody has to fix,
-// and cannot mislead. The machine that was just changed is left out because its own refusal is
-// already the answer beside this one.
-//
-// Nothing here can fail the act it reports on. A mesh that cannot be read is worth saying and is
-// not a reason to claim the assignment did not happen — it did.
-func blockedElsewhere(ctx context.Context, open *stores, except string) string {
-	nodes, err := open.inventory.Nodes(ctx)
-	if err != nil {
-		return "\n\nThe rest of the mesh could not be checked: " + err.Error()
-	}
-	blocked := map[string]string{}
-	for _, n := range nodes {
-		if n.Name == except {
-			continue
-		}
-		if _, _, err := planFor(ctx, open, n.Name); err != nil {
-			blocked[n.Name] = err.Error()
-		}
-	}
-	if len(blocked) == 0 {
-		return ""
-	}
-	names := make([]string, 0, len(blocked))
-	for name := range blocked {
-		names = append(names, name)
-	}
-	sort.Strings(names)
-
-	var out strings.Builder
-	fmt.Fprintf(&out, "\n\nAND %d other machine(s) cannot be worked out as things stand, so "+
-		"nothing will be sent to them:\n", len(names))
-	for _, name := range names {
-		fmt.Fprintf(&out, "  %s\n", name)
-		for _, line := range strings.Split(strings.TrimRight(blocked[name], "\n"), "\n") {
-			fmt.Fprintf(&out, "    %s\n", strings.TrimSpace(line))
-		}
-	}
-	out.WriteString("\nThis may or may not be what just changed — it is what is true now.")
-	return out.String()
-}
-
-// issueOnAssign gives a newly assigned module its bus credential, the way `module issue` does, and
-// says what it did in one line. Nothing for a module that declares no broker secret; nothing for one
-// whose user is already minted (a credential is rotated on purpose, never by re-assigning); and when
-// the bus cannot be reached from here, the line names the verb and the push that would refuse the
-// module until it is run — never a silent placeholder (novox/hq issue 203).
-func issueOnAssign(ctx context.Context, open *stores, node, module string) string {
-	inv := open.inventory
-	shelf, err := inv.Catalogue(ctx)
-	if err != nil {
-		return ""
-	}
-	m, known := shelf[module]
-	if !known || mayIssue(m) != nil {
-		return ""
-	}
-	user := broker.Principal{Kind: broker.KindModule, Node: node, Module: module}.Username()
-	if _, minted, err := inv.BusUserHash(ctx, user); err != nil || minted {
-		return ""
-	}
-	busAddress, err := broker.BusAddress()
-	if err == nil {
-		err = issueOnTheNewBus(ctx, inv, m, node, busAddress)
-	}
-	if err != nil {
-		return fmt.Sprintf("its bus credential is not issued (%v): `module issue %s --node %s` first — "+
-			"`push %s` refuses to send %s until it is", err, module, node, node, module)
-	}
-	return fmt.Sprintf("its bus credential is issued and sealed to %s, and arrives with the push", node)
-}
-
-// refusedMovingTheController refuses assigning or unassigning the controller's module through a verb (review of
-// novox/hq ADR 0272): the node it is assigned to is the control-node, and the control-node's operator account is
-// the controller's terminal, so whoever moves the module chooses the terminal. At the terminal alone, as every
-// change that says who may change what.
-func refusedMovingTheController(modules []string) error {
-	verb, through := throughAVerb()
-	if !through || !slices.Contains(modules, controllerModule) {
-		return nil
-	}
-	return fmt.Errorf("%s is assigned and unassigned at the controller's terminal only (mesh-cli on the control-node), "+
-		"never through a verb (this came through %q): the node it runs on is the control-node, whose operator is the "+
-		"terminal (novox/hq ADR 0272). Nothing was assigned", controllerModule, verb)
-}

cmd/mesh-controller/acts_test.go

@@ -1,133 +0,0 @@
-package main
-
-import (
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-)
-
-// What an assignment says about the machines it was not about.
-
-// **An assignment that blocks another machine says so.**
-//
-// The shape found on a four-node raise: a module offering a mesh-scoped provision stops offering it
-// the moment its own node stops resolving, so an assignment to the provider's machine silently took
-// a provision away from every consumer elsewhere. Those consumers were then told *nothing in this
-// mesh provides it*, naming as the remedy a module that was already assigned — which read, on the
-// way back, as a version bump breaking provider recognition. It was neither the version nor the
-// provider: it was one machine's set of assignments, and nothing said so.
-//
-// novox/hq 04-ISSUES/017 names the general shape — an action succeeding into a state its own verify
-// rejects, because the action's test is not the test the verify uses. `assign` tested one node; the
-// verify is resolution over all of them.
-func TestAnAssignmentThatBlocksAnotherMachineSaysWhichAndWhy(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-
-	// A provider on the hub and a consumer on the other machine, both resolving.
-	register(t, open, catalogue.Manifest{Module: "step-ca", Version: "1",
-		Provides: []catalogue.Offer{{Name: "acme-ca", Scope: catalogue.ScopeMesh}},
-		Serves:   map[string]map[string]any{"acme-ca": {"path": "/acme/directory"}}})
-	register(t, open, catalogue.Manifest{Module: "route-proxy", Version: "1",
-		Requires: []string{"acme-ca"}})
-	if _, err := assign(ctx, open, "anchor", "step-ca"); err != nil {
-		t.Fatal(err)
-	}
-	said, err := assign(ctx, open, "laptop", "route-proxy")
-	if err != nil {
-		t.Fatalf("a mesh that should resolve did not: %v\n%s", err, said)
-	}
-	if strings.Contains(said, "cannot be worked out") {
-		t.Fatalf("a well mesh was reported as blocked:\n%s", said)
-	}
-
-	// Now break the hub's own set, with nothing but the command a person has.
-	one, two := rivals()
-	register(t, open, one)
-	register(t, open, two)
-	if _, err := assign(ctx, open, "anchor", "rival-one"); err != nil {
-		t.Fatal(err)
-	}
-	said, err = assign(ctx, open, "anchor", "rival-two")
-	if err == nil {
-		t.Fatal("an assignment that makes its own node incoherent was not reported at all")
-	}
-
-	// The node's own refusal is the error, as it always was. What is new is that the machines this
-	// just took a provision away from are named in the same breath.
-	if !strings.Contains(said, "laptop") {
-		t.Fatalf("the machine this blocked is not named:\n%s\n\n%v", said, err)
-	}
-	if !strings.Contains(said, "acme-ca") {
-		t.Fatalf("what laptop is now missing is not said:\n%s", said)
-	}
-	if !strings.Contains(said, "cannot be worked out as things stand") {
-		t.Fatalf("the report does not say what state the mesh is in:\n%s", said)
-	}
-	// And the assignment is kept: it is what a person meant, and assignment is not an ordering.
-	assigned, err := open.inventory.Assigned(ctx, "anchor")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !contains(assigned, "rival-two") {
-		t.Fatalf("the assignment was not kept: %v", assigned)
-	}
-}
-
-// A consumer assigned before its provider is refused for itself and kept, because assignment is not
-// an ordering — refusing the first half of a pair would make the order somebody types two commands
-// in part of the mesh's rules.
-func TestAConsumerAssignedBeforeItsProviderIsStillAssigned(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	register(t, open, catalogue.Manifest{Module: "route-proxy", Version: "1",
-		Requires: []string{"acme-ca"}})
-
-	said, err := assign(ctx, open, "laptop", "route-proxy")
-	if err == nil {
-		t.Fatalf("a consumer with nothing to consume resolved:\n%s", said)
-	}
-	assigned, err := open.inventory.Assigned(ctx, "laptop")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !contains(assigned, "route-proxy") {
-		t.Fatalf("assignment became an ordering: %v", assigned)
-	}
-}
-
-// Unassigning is the ordinary way to stop providing something to another machine, and it reports
-// the same way for the same reason.
-func TestUnassigningAProviderNamesWhoIsNowBlocked(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	register(t, open, catalogue.Manifest{Module: "step-ca", Version: "1",
-		Provides: []catalogue.Offer{{Name: "acme-ca", Scope: catalogue.ScopeMesh}},
-		Serves:   map[string]map[string]any{"acme-ca": {"path": "/acme/directory"}}})
-	register(t, open, catalogue.Manifest{Module: "route-proxy", Version: "1",
-		Requires: []string{"acme-ca"}})
-	if _, err := assign(ctx, open, "anchor", "step-ca"); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := assign(ctx, open, "laptop", "route-proxy"); err != nil {
-		t.Fatal(err)
-	}
-
-	said, err := unassign(ctx, open, "anchor", "step-ca")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !strings.Contains(said, "laptop") || !strings.Contains(said, "acme-ca") {
-		t.Fatalf("taking the provider away said nothing about who was consuming it:\n%s", said)
-	}
-}
-
-func contains(all []string, one string) bool {
-	for _, s := range all {
-		if s == one {
-			return true
-		}
-	}
-	return false
-}

cmd/mesh-controller/addresses_test.go

@@ -1,352 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"os"
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/licences"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// An address is read from the node's settings where it is used, never recorded with a port
-// (novox/hq 04-ISSUES/102). Three readers did not follow the setting; each is held to it here.
-
-var aDigest = "sha256:" + strings.Repeat("e", 64)
-
-// **A build is recorded by digest and path**, whatever address the builder pushed to — what it
-// made and what it stood on both; an image the module runs from elsewhere is left where it says.
-func TestABuildIsRecordedWithoutTheStoresAddress(t *testing.T) {
-	manifest, _ := json.Marshal(map[string]any{
-		"module": "gitea", "version": "1",
-		"resources": []map[string]any{
-			{"id": "server", "type": "container", "name": "mesh-gitea",
-				"image": "anchor.internal:5100/gitea/server@" + aDigest},
-			{"id": "config", "type": "archive", "path": "/etc/gitea", "digest": aDigest,
-				"source": "http://anchor.internal:5100/v2/gitea/config/blobs/" + aDigest},
-			{"id": "cache", "type": "container", "name": "mesh-gitea-cache",
-				"image": "valkey/valkey@" + aDigest},
-		},
-	})
-	kept := buildFrom(link.BuildResult{
-		ID: "b1", Repository: "https://forge.example/gitea.git", Commit: "abc", On: "laptop",
-		Manifest: manifest,
-		Made: []link.MadeArtifact{
-			{Name: "server", Kind: "image", Reference: "anchor.internal:5100/gitea/server@" + aDigest},
-			{Name: "config", Kind: "archive", Reference: "http://anchor.internal:5100/v2/gitea/config/blobs/" + aDigest},
-		},
-		Against: []string{"anchor.internal:5100/mesh-tools/runtime@" + aDigest},
-	})
-	if kept.Module != "gitea" {
-		t.Fatalf("the module was not read from the recorded manifest: %q", kept.Module)
-	}
-	if kept.Made[0].Reference != catalogue.ArtifactStoreScheme+"gitea/server@"+aDigest {
-		t.Errorf("the image is recorded as %q, address and all", kept.Made[0].Reference)
-	}
-	if kept.Made[1].Reference != catalogue.ArtifactStoreScheme+"gitea/config/blobs/"+aDigest {
-		t.Errorf("the archive is recorded as %q, address and all", kept.Made[1].Reference)
-	}
-	recorded, err := catalogue.ParseManifest(kept.Manifest)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if got := recorded.Resources[0]["image"]; got != catalogue.ArtifactStoreScheme+"gitea/server@"+aDigest {
-		t.Errorf("the recorded manifest's image is %v", got)
-	}
-	if got := recorded.Resources[1]["source"]; got != catalogue.ArtifactStoreScheme+"gitea/config/blobs/"+aDigest {
-		t.Errorf("the recorded manifest's archive is %v", got)
-	}
-	if got := recorded.Resources[2]["image"]; got != "valkey/valkey@"+aDigest {
-		t.Errorf("an image the build did not make was rewritten: %v", got)
-	}
-	if strings.Contains(string(kept.Manifest), "anchor.internal:5100") {
-		t.Errorf("the recorded manifest still carries the store's address:\n%s", kept.Manifest)
-	}
-	// What the build stood on is an edge to another module's artifact, and it is recorded the way
-	// that artifact is: by path in the store, so the edge still names the same thing when the
-	// store answers at another address.
-	if kept.Against[0] != catalogue.ArtifactStoreScheme+"mesh-tools/runtime@"+aDigest {
-		t.Errorf("what the build stood on was recorded by address: %v", kept.Against)
-	}
-}
-
-// aStore is a module offering the artifact store on 5000, published the long way as the
-// distribution module does, so a node may be given another number for it.
-func aStore() catalogue.Manifest {
-	return catalogue.Manifest{Module: "distribution", Version: "1",
-		Provides: []catalogue.Offer{{Name: catalogue.ArtifactStoreProvision, Scope: catalogue.ScopeMesh}},
-		Serves:   map[string]map[string]any{catalogue.ArtifactStoreProvision: {"port": float64(5000)}},
-		Listens:  []catalogue.Listening{{Port: 5000, From: catalogue.FromMesh}},
-		Resources: []map[string]any{{"id": "store", "type": "container", "name": "mesh-registry",
-			"ports": []any{"5000:5000"}, "image": "registry@" + aDigest}}}
-}
-
-// **The trust a machine writes for the store, and the address every built image is fetched
-// through, say the port the node gave the store** — not the catalogue's number.
-func TestTheRegistryTrustAndEveryImageFollowThePortTheNodeGaveTheStore(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	register(t, open, aStore())
-	if _, err := assign(ctx, open, "anchor", "distribution"); err != nil {
-		t.Fatal(err)
-	}
-	if err := open.inventory.SetSettings(ctx, "anchor", "distribution",
-		map[string]any{catalogue.PortsSetting: map[string]any{"5000": 5101}}); err != nil {
-		t.Fatal(err)
-	}
-	// A module the mesh built, recorded by digest and path, running on the other machine.
-	if err := open.inventory.RecordBuild(ctx, inventory.Build{
-		ID: "b1", Repository: "r", Module: "app", Commit: "abc",
-		Made: []inventory.Artifact{{Name: "server", Kind: "image",
-			Reference: catalogue.ArtifactStoreScheme + "app/server@" + aDigest}},
-	}); err != nil {
-		t.Fatal(err)
-	}
-	register(t, open, catalogue.Manifest{Module: "app", Version: "1",
-		Resources: []map[string]any{{"id": "server", "type": "container", "name": "mesh-app",
-			"image": catalogue.ArtifactStoreScheme + "app/server@" + aDigest}}})
-	if _, err := assign(ctx, open, "laptop", "app"); err != nil {
-		t.Fatal(err)
-	}
-	// The runtime's trust is the runtime's module's to write (novox/hq ADR 0222): a stand-in for it
-	// asks where this machine reaches the store, as the docker module does.
-	register(t, open, catalogue.Manifest{Module: "runtime", Version: "1",
-		Resources: []map[string]any{{"id": "daemon", "type": "file", "path": "/etc/docker/daemon.json",
-			"into": "json", "content": `{"insecure-registries": ["${seat:mesh-artifact-store:reach}"]}` + "\n"}}})
-	if _, err := assign(ctx, open, "laptop", "runtime"); err != nil {
-		t.Fatal(err)
-	}
-
-	on := map[string]bool{"anchor": true, "laptop": true}
-	node, port, found, err := artifactStoreOnNetwork(ctx, open.inventory, on)
-	if err != nil || !found || node != "anchor" || port != "5101" {
-		t.Fatalf("the store is found on %q:%q (%v, %v); the node put it on 5101", node, port, found, err)
-	}
-
-	var trust string
-	for _, r := range composed(t, open, "laptop").Resources {
-		if r["path"] == "/etc/docker/daemon.json" {
-			trust, _ = r["content"].(string)
-		}
-		if r["id"] == "app.server" && r["image"] != "anchor.internal:5101/app/server@"+aDigest {
-			t.Errorf("the image the mesh built is fetched as %v", r["image"])
-		}
-	}
-	if !strings.Contains(trust, "anchor.internal:5101") || strings.Contains(trust, ":5000") {
-		t.Fatalf("the runtime is told to trust %q; the node put the store on 5101", trust)
-	}
-
-	// And a replay to the catalogue says where the store is now.
-	announced, err := following{open}.Announceable(ctx)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(announced) != 1 || announced[0].Made[0].Reference != "anchor.internal:5101/app/server@"+aDigest {
-		t.Fatalf("the replay announces %+v", announced)
-	}
-}
-
-// **The control plane's own connections say the port the node gave the store and the broker.**
-//
-// Composed from the control plane's own manifest against a real inventory: the store's module is
-// given 6852 on this node the way genesis or an operator gives it, and the control plane's
-// process is told so beside the sealed connection genesis wrote.
-func TestTheControlPlaneIsToldWhereTheNodePutTheStoreAndTheBroker(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	raw, err := os.ReadFile("../../module.json")
-	if err != nil {
-		t.Fatal(err)
-	}
-	m, err := catalogue.ParseManifest(raw)
-	if err != nil {
-		t.Fatal(err)
-	}
-	control, err := withSeatPorts(m).Resolve([]catalogue.Built{{Name: "controller", Kind: catalogue.ArtifactBundle,
-		Reference: "https://registry.example/mesh-controller/controller.tar.gz", Digest: aDigest}})
-	if err != nil {
-		t.Fatal(err)
-	}
-	register(t, open, control)
-	register(t, open, catalogue.Manifest{Module: "postgres", Version: "1",
-		Claims:  []catalogue.Claim{{Name: "mesh-store", Scope: catalogue.ScopeMesh}},
-		Listens: []catalogue.Listening{{Port: 5432, From: catalogue.FromMesh}},
-		Resources: []map[string]any{{"id": "server", "type": "container", "name": "mesh-store",
-			"ports": []any{"5432:5432"}, "image": "pg@" + aDigest}}})
-	register(t, open, catalogue.Manifest{Module: "lavinmq", Version: "1",
-		Claims: []catalogue.Claim{{Name: "mesh-broker", Scope: catalogue.ScopeMesh}},
-		Listens: []catalogue.Listening{{Port: 5671, From: catalogue.FromMesh},
-			{Port: 5672, From: catalogue.FromMesh}},
-		Guards: []int{15672},
-		Resources: []map[string]any{{"id": "server", "type": "container", "name": "mesh-broker",
-			"ports": []any{"5671:5671", "5672:5672", "127.0.0.1:15672:15672"}, "image": "mq@" + aDigest}}})
-	// The control plane's own bus user is the installer's, seeded at genesis before the controller
-	// runs (SeedBusUser); without it a push now refuses the credential nobody issued (issue 203).
-	if err := open.inventory.SeedBusUser(ctx, inventory.BusUser{Username: "anchor.mesh-controller",
-		Kind: inventory.BusController, Node: "anchor", Module: "mesh-controller"}, "bootstrap"); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := assign(ctx, open, "anchor", "mesh-controller"); err != nil {
-		t.Fatal(err)
-	}
-	// The store's module is registered and given its port, and NOT assigned: the state genesis
-	// leaves a given-port node in before the foundation is adopted as modules (04-ISSUES/085).
-	if err := open.inventory.SetSettings(ctx, "anchor", "postgres",
-		map[string]any{catalogue.PortsSetting: map[string]any{"5432": 6852}}); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := assign(ctx, open, "anchor", "lavinmq"); err != nil {
-		t.Fatal(err)
-	}
-	if err := open.inventory.SetSettings(ctx, "anchor", "lavinmq",
-		map[string]any{catalogue.PortsSetting: map[string]any{"5672": 5679}}); err != nil {
-		t.Fatal(err)
-	}
-
-	var env map[string]any
-	for _, r := range composed(t, open, "anchor").Resources {
-		if r["id"] == "mesh-controller.controller" {
-			env, _ = r["env"].(map[string]any)
-		}
-	}
-	if env == nil {
-		t.Fatal("the control plane's process is not in its own node's declaration")
-	}
-	for key, want := range map[string]string{
-		"MESH_STORE_INVENTORY_PORT": "6852",
-		"MESH_STORE_IDENTITY_PORT":  "6852",
-		"MESH_STORE_LICENCES_PORT":  "6852",
-		"MESH_BROKER_AMQP_PORT":     "5679",
-		// Neither given nor assigned by the mesh: the manifest's own number is NOT the answer,
-		// because the sealed value beside it carries the port genesis wrote (finding F3).
-		"MESH_BROKER_ADDRESS_PORT":    "",
-		"MESH_BROKER_MANAGEMENT_PORT": "",
-	} {
-		if env[key] != want {
-			t.Errorf("the control plane is told %s=%v; the node says %q", key, env[key], want)
-		}
-	}
-}
-
-// withSeatPorts is the control plane's manifest with the seat placeholders in its environment —
-// added here until module.json carries them (the manifest lands one commit after the code that
-// fills it, so a control plane one build behind never sees a placeholder it cannot fill).
-func withSeatPorts(m catalogue.Manifest) catalogue.Manifest {
-	seatPorts := map[string]string{
-		"MESH_STORE_INVENTORY_PORT":   "${seat:mesh-store:5432}",
-		"MESH_STORE_IDENTITY_PORT":    "${seat:mesh-store:5432}",
-		"MESH_STORE_LICENCES_PORT":    "${seat:mesh-store:5432}",
-		"MESH_BROKER_AMQP_PORT":       "${seat:mesh-broker:5672}",
-		"MESH_BROKER_MANAGEMENT_PORT": "${seat:mesh-broker:15672}",
-		"MESH_BROKER_ADDRESS_PORT":    "${seat:mesh-broker:5671}",
-	}
-	out := m
-	out.Resources = nil
-	for _, r := range m.Resources {
-		if r["type"] != "container" && r["type"] != "process" {
-			out.Resources = append(out.Resources, r)
-			continue
-		}
-		copied := map[string]any{}
-		for k, v := range r {
-			copied[k] = v
-		}
-		env := map[string]any{}
-		if had, ok := r["env"].(map[string]any); ok {
-			for k, v := range had {
-				env[k] = v
-			}
-		}
-		for k, v := range seatPorts {
-			if _, said := env[k]; !said {
-				env[k] = v
-			}
-		}
-		copied["env"] = env
-		out.Resources = append(out.Resources, copied)
-	}
-	return out
-}
-
-// aLoneNode is one capable machine with nothing placed on any network — the control-node during
-// genesis, before the "network" step, which is after the store, the broker, the vault and the
-// catalogue have each been built and pushed (finding F2).
-func aLoneNode(t *testing.T) *stores {
-	t.Helper()
-	inventory.ForTest(t)
-	licences.ForTest(t)
-	open, err := openStores(t.Context())
-	if err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(open.Close)
-	for _, m := range provided {
-		if err := open.inventory.Provide(t.Context(), m); err != nil {
-			t.Fatal(err)
-		}
-	}
-	record, err := open.inventory.AddNode(t.Context(), "anchor")
-	if err != nil {
-		t.Fatal(err)
-	}
-	reported, _ := json.Marshal(map[string]any{"capabilities": []map[string]any{
-		{"name": "container-runtime", "present": true}}})
-	var profile map[string]any
-	_ = json.Unmarshal(reported, &profile)
-	if err := open.inventory.RecordProfile(t.Context(), record.ID, profile); err != nil {
-		t.Fatal(err)
-	}
-	if err := open.inventory.RecordSealingKey(t.Context(), record.ID, aPublicKey(t)); err != nil {
-		t.Fatal(err)
-	}
-	return open
-}
-
-// **Before the network exists, the store's own node reaches it by loopback** — never refused,
-// never handed the scheme: a genesis pushes the store, the broker, the vault and the catalogue to
-// a node on no network, and builds the catalogue on a base it must be able to pull.
-func TestOnANodeWithNoNetworkTheStoreIsReachedByLoopback(t *testing.T) {
-	open := aLoneNode(t)
-	ctx := t.Context()
-	register(t, open, aStore())
-	register(t, open, catalogue.Manifest{Module: "builder", Version: "1",
-		Requires: []string{catalogue.ArtifactStoreProvision},
-		Resources: []map[string]any{{"id": "server", "type": "container", "name": "mesh-builder",
-			"image": "registry.example/mesh-builder@" + aDigest}}})
-	if err := open.inventory.RecordBuild(ctx, inventory.Build{
-		ID: "b1", Repository: "r", Module: "postgres", Commit: "abc",
-		Made: []inventory.Artifact{{Name: "runtime", Kind: "image",
-			Reference: catalogue.ArtifactStoreScheme + "postgres/runtime@" + aDigest}},
-	}); err != nil {
-		t.Fatal(err)
-	}
-	register(t, open, catalogue.Manifest{Module: "postgres", Version: "1",
-		Resources: []map[string]any{{"id": "runtime", "type": "container", "name": "mesh-postgres",
-			"image": catalogue.ArtifactStoreScheme + "postgres/runtime@" + aDigest}}})
-	for _, module := range []string{"distribution", "builder", "postgres"} {
-		if _, err := assign(ctx, open, "anchor", module); err != nil {
-			t.Fatal(err)
-		}
-	}
-	if err := open.inventory.SetSettings(ctx, "anchor", "distribution",
-		map[string]any{catalogue.PortsSetting: map[string]any{"5000": 5100}}); err != nil {
-		t.Fatal(err)
-	}
-
-	var image any
-	for _, r := range composed(t, open, "anchor").Resources {
-		if r["id"] == "postgres.runtime" {
-			image = r["image"]
-		}
-	}
-	if image != "127.0.0.1:5100/postgres/runtime@"+aDigest {
-		t.Fatalf("on the store's own node, off any network, the image is fetched as %v", image)
-	}
-	held := heldBy(ctx)
-	if got := held["postgres/runtime"]; got != "127.0.0.1:5100/postgres/runtime@"+aDigest {
-		t.Fatalf("a builder beside the store is handed the base %q", got)
-	}
-}

cmd/mesh-controller/adopting_test.go

@@ -1,641 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"net/http"
-	"reflect"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-	"github.com/novox/mesh-controller/internal/overlay"
-)
-
-// novox/hq ADR 0100: taking a module is its cutover; converging a node is one act, previewed, and
-// refused while a found container is held; returning to adopted keeps what was taken.
-
-// anAdoptedAnchor is aMesh with the anchor adopted, running a served module the predecessor also
-// runs and a module with only a file, and a filter module in the catalogue.
-func anAdoptedAnchor(t *testing.T) (*stores, *[]string) {
-	t.Helper()
-	open := aMesh(t)
-	ctx := t.Context()
-	register(t, open, catalogue.Manifest{Module: "hello-web", Version: "1",
-		Listens: []catalogue.Listening{{Port: 8080, From: catalogue.FromEverywhere}},
-		Resources: []map[string]any{
-			{"id": "page", "type": "file", "path": "/var/lib/hello-web/index.html", "content": "hi"},
-			{"id": "server", "type": "container", "name": "hello-web", "ports": []any{"8080:80"},
-				"image": "registry.example/hello@sha256:" + strings.Repeat("a", 64)},
-		}})
-	register(t, open, catalogue.Manifest{Module: "notes", Version: "1",
-		Resources: []map[string]any{
-			{"id": "conf", "type": "file", "path": "/etc/notes.conf", "content": "x"},
-		}})
-	register(t, open, catalogue.Manifest{Module: "nftables", Version: "1",
-		Filtering: &catalogue.Filtering{Into: "/etc/nftables.conf"},
-		Resources: []map[string]any{{"id": "load", "type": "service", "unit": "mesh-filter.service",
-			"state": "running", "restart-on": []any{"filtering"}}}})
-	if err := open.inventory.SetAdopted(ctx, "anchor", true); err != nil {
-		t.Fatal(err)
-	}
-	for _, m := range []string{"hello-web", "notes"} {
-		if _, err := assign(ctx, open, "anchor", m); err != nil {
-			t.Fatal(err)
-		}
-	}
-	sent := &[]string{}
-	saved := sendNodes
-	sendNodes = func(_ context.Context, _ *stores, names []string) error {
-		*sent = append(*sent, names...)
-		return nil
-	}
-	t.Cleanup(func() { sendNodes = saved })
-	return open, sent
-}
-
-// reportsHolding has the anchor report, on what it was last sent, holding what is given.
-func reportsHolding(t *testing.T, open *stores, held ...link.Held) {
-	t.Helper()
-	reportsReaching(t, open, []link.Reach{
-		{Protocol: "tcp", Address: "0.0.0.0", Port: 22, By: "sshd"},
-		{Protocol: "tcp", Address: "0.0.0.0", Port: 8080, By: "hello-web", Published: true,
-			ContainerPort: 80},
-		{Protocol: "tcp", Address: "0.0.0.0", Port: 5000, By: "predecessor-registry",
-			Published: true, ContainerPort: 5000},
-		{Protocol: "tcp", Address: "127.0.0.1", Port: 15672, By: "mesh-broker",
-			Published: true, ContainerPort: 15672},
-	}, held...)
-}
-
-// reportsReaching has the anchor report, on what it was last sent, what is reachable on it and
-// holding what is given.
-func reportsReaching(t *testing.T, open *stores, reachable []link.Reach, held ...link.Held) {
-	t.Helper()
-	ctx := t.Context()
-	body, err := composed(t, open, "anchor").Body()
-	if err != nil {
-		t.Fatal(err)
-	}
-	record, err := open.inventory.NodeByName(ctx, "anchor")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := open.inventory.RecordSent(ctx, record.ID, digestOf(body), nil); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := (link.Enrolment{Inventory: open.inventory}).Heard(ctx, link.Report{
-		Node: "anchor", Applied: []string{"hello-web.x"}, Declared: digestOf(body),
-		Firewall: "ufw", Held: held, Reachable: reachable,
-		// A machine says which of its links face outside on every apply (novox/hq ADR 0140), and a
-		// filter is not sent to one that has not. The anchor reports one, as a real host does; this
-		// fixture lacked it from 2026-09-28 and nothing ran the test (issue 177).
-		Outward: []string{"eth0"},
-		// And what filters it (ADR 0168): its front end, the runtime's own, and a chain a
-		// predecessor left in the runtime's user chain.
-		Filters: anchorFilters,
-	}); err != nil {
-		t.Fatal(err)
-	}
-}
-
-// anchorFilters is what the adopted anchor says filters it: ufw's chains, the runtime's, and a
-// predecessor's chain the mesh did not write.
-var anchorFilters = []link.Filter{
-	{Where: "table ip filter, chain ufw-reject-input", Owner: "found-firewall", Refuses: "reject"},
-	{Where: "table ip filter, chain DOCKER", Owner: "runtime", Refuses: `iifname != "docker0" oifname "docker0" drop`},
-	{Where: "table ip filter, chain DOCKER-USER", Owner: "other", Refuses: `iifname "eth0" tcp dport 6000 drop`},
-}
-
-var (
-	heldContainer = link.Held{ID: "hello-web.server", Module: "hello-web", Kind: "container",
-		Target: "hello-web", Since: time.Now()}
-	heldFile = link.Held{ID: "notes.conf", Module: "notes", Kind: "file",
-		Target: "/etc/notes.conf", Since: time.Now(), Kept: "/var/lib/mesh-host/kept/abc-notes.conf"}
-)
-
-func TestTakingAModuleNotOnTheNodeIsRefused(t *testing.T) {
-	open, _ := anAdoptedAnchor(t)
-	if _, err := take(t.Context(), open, "anchor", "nftables", takeOptions{Yes: true}); !errors.Is(err, inventory.ErrNotAssigned) {
-		t.Fatalf("taking an unassigned module gave %v", err)
-	}
-	if _, err := take(t.Context(), open, "laptop", "network", takeOptions{Yes: true}); !errors.Is(err, inventory.ErrNotAdopted) {
-		t.Fatalf("taking on a converged node gave %v", err)
-	}
-}
-
-func TestConvergingIsRefusedOnAPreviewThatWouldBeStale(t *testing.T) {
-	open, sent := anAdoptedAnchor(t)
-	_, err := converge(t.Context(), open, "anchor", false, "", "")
-	if err == nil || !strings.Contains(err.Error(), "has not reported") {
-		t.Fatalf("a node that never reported was previewed: %v", err)
-	}
-	if len(*sent) != 0 {
-		t.Fatal("a refused converge sent something")
-	}
-}
-
-func TestTheFlipIsRefusedWhileAFoundContainerIsHeld(t *testing.T) {
-	open, sent := anAdoptedAnchor(t)
-	reportsHolding(t, open, heldContainer, heldFile)
-	_, err := converge(t.Context(), open, "anchor", true, "", "")
-	if err == nil || !strings.Contains(err.Error(), "take anchor hello-web once its data has moved") {
-		t.Fatalf("the flip was not refused while hello-web holds its found container: %v", err)
-	}
-	if n, _ := open.inventory.NodeByName(t.Context(), "anchor"); !n.Adopted || len(*sent) != 0 {
-		t.Fatal("a refused flip changed something")
-	}
-}
-
-func TestTakingNamesWhatItReplaces(t *testing.T) {
-	open, _ := anAdoptedAnchor(t)
-	reportsHolding(t, open, heldContainer, heldFile)
-	ctx := t.Context()
-	// The machine holds something for the module, so the take acts on the preview the operator
-	// saw and names its digest (novox/hq ADR 0163).
-	preview, err := take(ctx, open, "anchor", "hello-web", takeOptions{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	saw := takeDigestIn(t, preview)
-	if !strings.Contains(preview, "nothing taken; `take anchor hello-web --yes "+saw+"`") {
-		t.Fatalf("the preview does not say how to act on it:\n%s", preview)
-	}
-	if taken, _ := open.inventory.Taken(ctx, "anchor"); len(taken) != 0 {
-		t.Fatal("the preview took something")
-	}
-	if _, err := take(ctx, open, "anchor", "hello-web", takeOptions{Yes: true}); err == nil || !strings.Contains(err.Error(), "name its digest") {
-		t.Fatalf("--yes without the digest was not refused: %v", err)
-	}
-	said, err := take(ctx, open, "anchor", "hello-web", takeOptions{Yes: true, Digest: saw})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !strings.Contains(said, "container hello-web (hello-web.server)") ||
-		!strings.Contains(said, "push anchor") {
-		t.Fatalf("taking did not say what it replaces and what to run:\n%s", said)
-	}
-}
-
-// takeDigestIn is the digest a take's preview printed.
-func takeDigestIn(t *testing.T, preview string) string {
-	t.Helper()
-	for _, line := range strings.Split(preview, "\n") {
-		if fields := strings.Fields(line); len(fields) == 2 && fields[0] == "preview" {
-			return fields[1]
-		}
-	}
-	t.Fatalf("the preview printed no digest:\n%s", preview)
-	return ""
-}
-
-// A take acts on the preview the operator saw, and on an account of the machine that is still the
-// machine: a changed preview and a stale account refuse (novox/hq ADR 0163, rule 1).
-func TestATakeIsRefusedOnAChangedPreviewOrAStaleAccount(t *testing.T) {
-	open, _ := anAdoptedAnchor(t)
-	ctx := t.Context()
-	reportsHolding(t, open, heldContainer, heldFile)
-	preview, err := take(ctx, open, "anchor", "hello-web", takeOptions{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	saw := takeDigestIn(t, preview)
-
-	// The machine reports again, and what it holds has changed: the found container now carries
-	// facts the preview never showed.
-	changed := heldContainer
-	changed.Facts = map[string]any{"image": "hello:2", "declared_image": "registry.example/hello"}
-	reportsHolding(t, open, changed, heldFile)
-	_, err = take(ctx, open, "anchor", "hello-web", takeOptions{Yes: true, Digest: saw})
-	if err == nil || !strings.Contains(err.Error(), "has changed since preview "+saw) {
-		t.Fatalf("a changed preview was acted on: %v", err)
-	}
-	if taken, _ := open.inventory.Taken(ctx, "anchor"); len(taken) != 0 {
-		t.Fatal("a refused take took something")
-	}
-
-	// And an account older than the flip allows.
-	preview, err = take(ctx, open, "anchor", "hello-web", takeOptions{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	saw = takeDigestIn(t, preview)
-	saved := reportFreshFor
-	reportFreshFor = -time.Second
-	defer func() { reportFreshFor = saved }()
-	_, err = take(ctx, open, "anchor", "hello-web", takeOptions{Yes: true, Digest: saw})
-	if err == nil || !strings.Contains(err.Error(), "a take acts only on an account newer than") {
-		t.Fatalf("a stale account was acted on: %v", err)
-	}
-	reportFreshFor = saved
-	if _, err := take(ctx, open, "anchor", "hello-web", takeOptions{Yes: true, Digest: saw}); err != nil {
-		t.Fatal(err)
-	}
-	// A module the machine holds nothing for has nothing to compare: --yes alone suffices.
-	if _, err := take(ctx, open, "anchor", "notes", takeOptions{Yes: true}); err == nil {
-		// notes holds a file, so this one needs the digest too.
-		t.Fatal("notes holds a found file and was taken without a digest")
-	}
-}
-
-func TestConvergingPreviewsThenChangesAndAdoptingKeepsWhatWasTaken(t *testing.T) {
-	open, sent := anAdoptedAnchor(t)
-	ctx := t.Context()
-	if _, err := take(ctx, open, "anchor", "hello-web", takeOptions{Yes: true}); err != nil {
-		t.Fatal(err)
-	}
-	reportsHolding(t, open, heldFile)
-
-	preview, err := converge(ctx, open, "anchor", false, "", "")
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, want := range []string{
-		"tcp/8080 hello-web (published, container port 80)",
-		"declared by hello-web (from anywhere)",
-		"WILL CLOSE — no module assigned here declares it",
-		// The anchor faces inward and is on the private network: the derived filter admits ssh
-		// from the mesh only.
-		"WILL CLOSE to everything outside the private network — ssh stays open from the mesh",
-		"notes\n      replacing the found file /etc/notes.conf (notes.conf), original kept at",
-		"assigns nftables",
-		"the found firewall (ufw) is disabled, never flushed",
-		// What it routes is not a listener: said not to be previewed, and to be dropped.
-		"not previewed: traffic the machine routes that is not a published port",
-		"the derived filter drops it unless a module declares it",
-	} {
-		if !strings.Contains(preview, want) {
-			t.Errorf("the preview does not say %q:\n%s", want, preview)
-		}
-	}
-	if strings.Contains(preview, "15672") {
-		t.Errorf("a loopback listener is in the preview:\n%s", preview)
-	}
-	// What filters the machine now, and the fate of each (novox/hq ADR 0168): the predecessor's
-	// chain is named as not the mesh's and left, so the reader knows before the flip.
-	for _, want := range []string{
-		"table ip filter, chain DOCKER-USER",
-		"NOT THE MESH'S; left in force",
-		`iifname "eth0" tcp dport 6000 drop`,
-		"table ip filter, chain ufw-reject-input",
-		"the found firewall's; retired with it",
-		"the container runtime's own; left",
-	} {
-		if !strings.Contains(preview, want) {
-			t.Errorf("the preview does not say %q:\n%s", want, preview)
-		}
-	}
-	for _, line := range strings.Split(preview, "\n") {
-		if strings.Contains(line, "5000") && !strings.Contains(line, "WILL CLOSE") {
-			t.Errorf("an undeclared published port is not said to close: %s", line)
-		}
-	}
-	if n, _ := open.inventory.NodeByName(ctx, "anchor"); !n.Adopted || len(*sent) != 0 {
-		t.Fatal("the preview changed something")
-	}
-
-	if _, err := converge(ctx, open, "anchor", true, digestIn(t, preview), ""); err != nil {
-		t.Fatal(err)
-	}
-	n, _ := open.inventory.NodeByName(ctx, "anchor")
-	if n.Adopted {
-		t.Fatal("converge --yes left the node adopted")
-	}
-	taken, _ := open.inventory.Taken(ctx, "anchor")
-	if !reflect.DeepEqual(taken, []string{"hello-web", overlay.Name, "nftables", "notes"}) {
-		t.Fatalf("the flip took %v", taken)
-	}
-	if !reflect.DeepEqual(*sent, []string{"anchor"}) {
-		t.Fatalf("the flip sent %v", *sent)
-	}
-	declared := composed(t, open, "anchor")
-	if declared.Adoption != nil {
-		t.Fatal("a converged node is still sent an adoption envelope")
-	}
-	if !hasID(declared.Resources, "nftables.filtering") {
-		t.Fatal("the converged node is not declared the mesh's filter")
-	}
-
-	if _, err := adopt(ctx, open, "anchor"); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := adopt(ctx, open, "anchor"); err == nil {
-		t.Fatal("adopting an adopted node was not refused")
-	}
-	again, _ := open.inventory.Taken(ctx, "anchor")
-	if !reflect.DeepEqual(again, taken) {
-		t.Fatalf("returning to adopted lost what was taken: %v", again)
-	}
-	declared = composed(t, open, "anchor")
-	if declared.Adoption == nil || len(declared.Adoption.Untaken) != 0 {
-		t.Fatalf("returned to adopted, the envelope is %+v", declared.Adoption)
-	}
-	if hasID(declared.Resources, "nftables.filtering") || hasID(declared.Resources, "nftables.load") {
-		t.Fatal("returned to adopted, the mesh's filter is still declared")
-	}
-}
-
-func hasID(resources []map[string]any, id string) bool {
-	for _, r := range resources {
-		if r["id"] == id {
-			return true
-		}
-	}
-	return false
-}
-
-// The command API refuses a flip exactly as the command line does, in the same words.
-func TestTheApiRefusesTheFlipInTheCommandLinesWords(t *testing.T) {
-	open, _ := anAdoptedAnchor(t)
-	reportsHolding(t, open, heldContainer)
-	_, direct := converge(t.Context(), open, "anchor", true, "", "")
-	if direct == nil {
-		t.Fatal("the flip was not refused")
-	}
-	got := asking(t, letIn{}, "POST", "/converge", `{"node":"anchor","yes":true}`)
-	if got.Code != http.StatusConflict {
-		t.Fatalf("got %d: %s", got.Code, got.Body.String())
-	}
-	var said map[string]any
-	if err := json.Unmarshal(got.Body.Bytes(), &said); err != nil {
-		t.Fatal(err)
-	}
-	if said["refused"] != direct.Error() {
-		t.Fatalf("the API said %q and the command line %q", said["refused"], direct.Error())
-	}
-	if got := asking(t, letIn{}, "POST", "/take", `{"node":"anchor"}`); got.Code != http.StatusBadRequest {
-		t.Fatalf("a take naming no module got %d", got.Code)
-	}
-}
-
-// novox/hq ADR 0100: the preview says what the derived filter does, rendered as it is rendered. On
-// a machine that faces inward, ssh is admitted from the private network only, and a port a module
-// admits from the mesh only closes to everything outside it: both are said to close.
-func TestThePreviewSaysWhatNarrowsToTheMeshCloses(t *testing.T) {
-	open, _ := anAdoptedAnchor(t)
-	ctx := t.Context()
-	register(t, open, catalogue.Manifest{Module: "store", Version: "1",
-		Listens: []catalogue.Listening{{Port: 5432, From: catalogue.FromMesh}}})
-	if _, err := assign(ctx, open, "anchor", "store"); err != nil {
-		t.Fatal(err)
-	}
-	reportsReaching(t, open, []link.Reach{
-		{Protocol: "tcp", Address: "0.0.0.0", Port: 22, By: "sshd"},
-		{Protocol: "tcp", Address: "0.0.0.0", Port: 5432, By: "postgres"},
-		{Protocol: "tcp", Address: "10.77.0.1", Port: 5432, By: "postgres"},
-		{Protocol: "tcp", Address: "0.0.0.0", Port: 8080, By: "hello-web", Published: true,
-			ContainerPort: 80},
-	})
-	preview, err := converge(ctx, open, "anchor", false, "", "")
-	if err != nil {
-		t.Fatal(err)
-	}
-	lines := map[string]string{}
-	for _, line := range strings.Split(preview, "\n") {
-		fields := strings.Fields(line)
-		if len(fields) > 1 && strings.HasPrefix(fields[0], "tcp/") {
-			lines[fields[0]+" "+fields[1]] += line + "\n"
-		}
-	}
-	if got := lines["tcp/22 sshd"]; !strings.Contains(got, "WILL CLOSE to everything outside "+
-		"the private network") {
-		t.Errorf("ssh on an inward machine is not said to close outside the mesh:\n%s", preview)
-	}
-	store := lines["tcp/5432 postgres"]
-	if strings.Count(store, "WILL CLOSE to everything outside the private network") != 1 ||
-		!strings.Contains(store, "declared by store (from mesh)") {
-		t.Errorf("the store's narrowing is not said to close, or its mesh address is:\n%s", preview)
-	}
-	if got := lines["tcp/8080 hello-web"]; !strings.Contains(got, "declared by hello-web (from anywhere)") {
-		t.Errorf("a port open to everywhere is not said to stay:\n%s", preview)
-	}
-}
-
-// digestIn is the digest a converge preview printed.
-func digestIn(t *testing.T, preview string) string {
-	t.Helper()
-	for _, line := range strings.Split(preview, "\n") {
-		if fields := strings.Fields(line); len(fields) == 2 && fields[0] == "preview" {
-			return fields[1]
-		}
-	}
-	t.Fatalf("the preview printed no digest:\n%s", preview)
-	return ""
-}
-
-// The flip acts on the preview the operator saw: it names that preview's digest, and it is refused
-// when the digest is missing, when anything the preview says has changed since, or when the node's
-// account of itself is too old to be the machine as it is.
-func TestTheFlipActsOnlyOnThePreviewTheOperatorSaw(t *testing.T) {
-	open, sent := anAdoptedAnchor(t)
-	ctx := t.Context()
-	if _, err := take(ctx, open, "anchor", "hello-web", takeOptions{Yes: true}); err != nil {
-		t.Fatal(err)
-	}
-	reportsHolding(t, open, heldFile)
-	preview, err := converge(ctx, open, "anchor", false, "", "")
-	if err != nil {
-		t.Fatal(err)
-	}
-	saw := digestIn(t, preview)
-	if !strings.Contains(preview, "converge anchor --yes "+saw) {
-		t.Fatalf("the preview does not say how to act on it:\n%s", preview)
-	}
-	unchanged := func() {
-		t.Helper()
-		if n, _ := open.inventory.NodeByName(ctx, "anchor"); !n.Adopted || len(*sent) != 0 {
-			t.Fatal("a refused flip changed something")
-		}
-	}
-
-	if _, err := converge(ctx, open, "anchor", true, "", ""); err == nil ||
-		!strings.Contains(err.Error(), "--yes "+saw) {
-		t.Fatalf("a flip naming no preview was not refused: %v", err)
-	}
-	unchanged()
-
-	// Something new is reachable: the preview the operator saw is not what would happen.
-	reportsReaching(t, open, []link.Reach{
-		{Protocol: "tcp", Address: "0.0.0.0", Port: 22, By: "sshd"},
-		{Protocol: "tcp", Address: "0.0.0.0", Port: 8080, By: "hello-web", Published: true,
-			ContainerPort: 80},
-		{Protocol: "tcp", Address: "0.0.0.0", Port: 6000, By: "something-new"},
-	}, heldFile)
-	_, err = converge(ctx, open, "anchor", true, saw, "")
-	if err == nil || !strings.Contains(err.Error(), "has changed since preview "+saw) {
-		t.Fatalf("a flip on a changed preview was not refused: %v", err)
-	}
-	unchanged()
-
-	// An account older than the flip trusts is refused, whatever digest is named.
-	again, err := converge(ctx, open, "anchor", false, "", "")
-	if err != nil {
-		t.Fatal(err)
-	}
-	saved := reportFreshFor
-	reportFreshFor = time.Nanosecond
-	_, err = converge(ctx, open, "anchor", true, digestIn(t, again), "")
-	reportFreshFor = saved
-	if err == nil || !strings.Contains(err.Error(), "wait for its next report") {
-		t.Fatalf("a flip on an old account was not refused: %v", err)
-	}
-	unchanged()
-
-	if _, err := converge(ctx, open, "anchor", true, digestIn(t, again), ""); err != nil {
-		t.Fatalf("the flip on the preview just seen was refused: %v", err)
-	}
-	if n, _ := open.inventory.NodeByName(ctx, "anchor"); n.Adopted {
-		t.Fatal("the flip did not converge the node")
-	}
-}
-
-// The flip holds the node from its checks to its send, so a push composed meanwhile waits and is
-// composed after it — never sent after it with the node still adopted. And the send inside the
-// flip is not made to wait on the flip's own hold.
-func TestTheFlipHoldsTheNodeWhileItSends(t *testing.T) {
-	open, _ := anAdoptedAnchor(t)
-	ctx := t.Context()
-	if _, err := take(ctx, open, "anchor", "hello-web", takeOptions{Yes: true}); err != nil {
-		t.Fatal(err)
-	}
-	reportsHolding(t, open, heldFile)
-	preview, err := converge(ctx, open, "anchor", false, "", "")
-	if err != nil {
-		t.Fatal(err)
-	}
-	var heldElsewhere, heldHere error
-	sendNodes = func(inner context.Context, open *stores, names []string) error {
-		// Another caller cannot hold the node while the flip sends it.
-		waiting, cancel := context.WithTimeout(ctx, 300*time.Millisecond)
-		defer cancel()
-		if release, err := open.inventory.HoldNodes(waiting, names); err == nil {
-			release()
-			heldElsewhere = errors.New("another caller held the node while the flip sent it")
-		}
-		// The flip's own send holds it without waiting on itself.
-		_, release, err := holdNodes(inner, open, names)
-		if err != nil {
-			heldHere = err
-			return err
-		}
-		release()
-		return nil
-	}
-	if _, err := converge(ctx, open, "anchor", true, digestIn(t, preview), ""); err != nil {
-		t.Fatal(err)
-	}
-	if heldElsewhere != nil || heldHere != nil {
-		t.Fatalf("%v %v", heldElsewhere, heldHere)
-	}
-	// And given back once it is done.
-	release, err := open.inventory.HoldNodes(ctx, []string{"anchor"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	release()
-}
-
-// novox/hq ADR 0103: the preview names every kind of thing a module the flip takes holds as found,
-// not only its files, and the digest changes when any of them does.
-func TestThePreviewNamesEveryHeldKind(t *testing.T) {
-	open, _ := anAdoptedAnchor(t)
-	ctx := t.Context()
-	if _, err := take(ctx, open, "anchor", "hello-web", takeOptions{Yes: true}); err != nil {
-		t.Fatal(err)
-	}
-	since := time.Now()
-	held := []link.Held{heldFile,
-		{ID: "notes.data", Module: "notes", Kind: "directory", Target: "/var/lib/notes", Since: since},
-		{ID: "notes.daemon", Module: "notes", Kind: "service", Target: "notes.service", Since: since},
-		{ID: "notes.seed", Module: "notes", Kind: "archive", Target: "/srv/notes", Since: since},
-		{ID: "notes.worker", Module: "notes", Kind: "process", Target: "notes-worker", Since: since},
-		{ID: "notes.account", Module: "notes", Kind: "user", Target: "notes", Since: since},
-	}
-	reportsHolding(t, open, held...)
-	preview, err := converge(ctx, open, "anchor", false, "", "")
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, want := range []string{
-		"replacing the found directory /var/lib/notes (notes.data)",
-		"replacing the found service notes.service (notes.daemon)",
-		"replacing the found archive /srv/notes (notes.seed)",
-		"replacing the found process notes-worker (notes.worker)",
-		"replacing the found user notes (notes.account)",
-	} {
-		if !strings.Contains(preview, want) {
-			t.Errorf("the preview does not say %q:\n%s", want, preview)
-		}
-	}
-	reportsHolding(t, open, held[:len(held)-1]...)
-	fewer, err := converge(ctx, open, "anchor", false, "", "")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if digestIn(t, fewer) == digestIn(t, preview) {
-		t.Fatal("the digest does not change with what is held")
-	}
-}
-
-// novox/hq ADR 0100: the flip acts on what the node said is reachable, so an account naming nothing
-// is refused. Every machine that is up answers on ssh; nothing reported means the host's collectors
-// did not, and flipping would close ports the preview never named.
-func TestTheFlipIsRefusedOnAnAccountNamingNothingReachable(t *testing.T) {
-	open, sent := anAdoptedAnchor(t)
-	ctx := t.Context()
-	if _, err := take(ctx, open, "anchor", "hello-web", takeOptions{Yes: true}); err != nil {
-		t.Fatal(err)
-	}
-	// Only a loopback listener: nothing off the machine, which is the same silence.
-	reportsReaching(t, open, []link.Reach{
-		{Protocol: "tcp", Address: "127.0.0.1", Port: 15672, By: "mesh-broker"},
-	}, heldFile)
-	preview, err := converge(ctx, open, "anchor", false, "", "")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !strings.Contains(preview, "this account looks partial") {
-		t.Errorf("the preview does not mark a partial account:\n%s", preview)
-	}
-	_, err = converge(ctx, open, "anchor", true, digestIn(t, preview), "")
-	if err == nil || !strings.Contains(err.Error(), "says nothing is reachable on it") {
-		t.Fatalf("the flip was not refused on an account naming nothing: %v", err)
-	}
-	if n, _ := open.inventory.NodeByName(ctx, "anchor"); !n.Adopted || len(*sent) != 0 {
-		t.Fatal("a refused flip changed something")
-	}
-}
-
-// An assignment cannot land between a preview and the flip that takes every module: assigning
-// holds the node, so it waits for whatever is converging it.
-func TestAssigningWaitsForWhateverIsConvergingTheNode(t *testing.T) {
-	open, _ := anAdoptedAnchor(t)
-	ctx := t.Context()
-	if _, err := take(ctx, open, "anchor", "hello-web", takeOptions{Yes: true}); err != nil {
-		t.Fatal(err)
-	}
-	reportsHolding(t, open, heldFile)
-	preview, err := converge(ctx, open, "anchor", false, "", "")
-	if err != nil {
-		t.Fatal(err)
-	}
-	saved, savedPoll := inventory.HoldWaitFor, inventory.HoldPoll
-	inventory.HoldWaitFor, inventory.HoldPoll = time.Second, 50*time.Millisecond
-	defer func() { inventory.HoldWaitFor, inventory.HoldPoll = saved, savedPoll }()
-
-	var whileFlipping error
-	sendNodes = func(context.Context, *stores, []string) error {
-		_, whileFlipping = assign(ctx, open, "anchor", "notes")
-		return nil
-	}
-	if _, err := converge(ctx, open, "anchor", true, digestIn(t, preview), ""); err != nil {
-		t.Fatal(err)
-	}
-	if !errors.Is(whileFlipping, inventory.ErrNodeBusy) {
-		t.Fatalf("an assignment landed while the node was being converged: %v", whileFlipping)
-	}
-}

cmd/mesh-controller/advisories_counted_test.go

@@ -1,180 +0,0 @@
-package main
-
-import (
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// **A refusal the bus said once is counted once** (novox/hq issue 402). The bus refused the controller
-// one publish at 18:52:59 UTC on 2026-10-10 and never again, yet S9 looked at the one remembered
-// advisory every half minute for the hour it is kept, and the condition said "observed 15 time(s), last
-// 13s ago" with a refusal in its evidence every 30 seconds: two of us read it as a refusal going on and
-// went looking for a missing grant. The condition counts what the bus said, with when it last said it,
-// never how often the controller looked.
-func TestARefusalSaidOnceIsCountedOnceHoweverOftenItIsLookedAt(t *testing.T) {
-	refused := time.Date(2026, 10, 10, 18, 52, 59, 0, time.UTC)
-	now := refused.Add(10 * time.Second)
-	store := conditions.NewInMemory()
-	k := conditions.NewKeeper(t.Context(), conditions.Options{Store: store, History: store,
-		Teller: &conditions.Told{}, Now: func() time.Time { return now }})
-	t.Cleanup(func() { k.Close(t.Context()) })
-
-	// The words the live condition bus.controller.refused carried on 2026-10-10.
-	said := "the bus refused the controller: nats: permissions violation: Permissions Violation for " +
-		`Publish to "mesh.seat.mesh-delivery.tool.times"`
-	advisory := link.Advisory{Kind: link.AdvisoryRefused, ID: "controller", Said: said,
-		First: refused, Last: refused, Count: 1}
-	look := func() conditions.Condition {
-		t.Helper()
-		f := &signalFacts{now: now, host: "novox", advisories: []link.Advisory{advisory}}
-		if err := k.Reconcile(t.Context(), "S9", watchAdvisories(f)); err != nil {
-			t.Fatal(err)
-		}
-		c, found, err := conditions.ReadOne(t.Context(), store, "bus.controller.refused")
-		if err != nil || !found {
-			t.Fatalf("bus.controller.refused: found %v, %v", found, err)
-		}
-		return c
-	}
-
-	var c conditions.Condition
-	for range 15 {
-		c = look()
-		now = now.Add(30 * time.Second)
-	}
-	if c.Observations != 1 || len(c.Evidence) != 1 {
-		t.Fatalf("one refusal, looked at 15 times, reads as observed %d time(s) with %d evidence lines: %+v",
-			c.Observations, len(c.Evidence), c.Evidence)
-	}
-	if !c.LastObserved.Equal(refused) || !c.Evidence[0].At.Equal(refused) {
-		t.Fatalf("last observed %s, evidence at %s: the refusal was at %s", c.LastObserved, c.Evidence[0].At, refused)
-	}
-
-	// The bus refuses it three times more between two looks: the condition counts four refusals, says
-	// the newest, and adds one line of evidence for the look that saw them.
-	again := now.Add(-5 * time.Second)
-	advisory.Last, advisory.Count = again, 4
-	c = look()
-	if c.Observations != 4 || len(c.Evidence) != 2 || !c.LastObserved.Equal(again) || !c.Evidence[0].At.Equal(again) {
-		t.Fatalf("four refusals read as observed %d time(s), last %s, evidence %+v", c.Observations, c.LastObserved, c.Evidence)
-	}
-	if !strings.Contains(c.Summary, "(4 times since 18:52 UTC)") {
-		t.Fatalf("summary %q", c.Summary)
-	}
-	now = now.Add(30 * time.Second)
-	if c = look(); c.Observations != 4 || len(c.Evidence) != 2 {
-		t.Fatalf("a look with nothing new counted: observed %d time(s), evidence %+v", c.Observations, c.Evidence)
-	}
-}
-
-// **A condition that looks at the present still counts its looks** (novox/hq issue 402 changes only
-// what reads a record): a machine silent for three looks was observed three times, and says so.
-func TestAConditionOfThePresentCountsItsLooks(t *testing.T) {
-	now := time.Date(2026, 10, 10, 19, 0, 0, 0, time.UTC)
-	store := conditions.NewInMemory()
-	k := conditions.NewKeeper(t.Context(), conditions.Options{Store: store, History: store,
-		Teller: &conditions.Told{}, Now: func() time.Time { return now }})
-	t.Cleanup(func() { k.Close(t.Context()) })
-	var c conditions.Condition
-	for range 3 {
-		var err error
-		if c, err = k.Observe(t.Context(), conditions.Observation{Scope: conditions.ScopeMachine, ID: "ace",
-			Kind: "silent", Machine: "ace", Severity: conditions.Warning, Summary: "ace has not been heard from",
-			Source: "S1"}); err != nil {
-			t.Fatal(err)
-		}
-		now = now.Add(30 * time.Second)
-	}
-	if c.Observations != 3 || len(c.Evidence) != 3 || !c.LastObserved.Equal(now.Add(-30*time.Second)) {
-		t.Fatalf("observed %d time(s), %d evidence lines, last %s", c.Observations, len(c.Evidence), c.LastObserved)
-	}
-}
-
-// **One key, one watcher** (novox/hq issue 440). A consumer's max-deliveries condition is said from
-// DEAD_LETTERS while it holds a message the consumer gave up on (issue 330). A max-deliveries advisory
-// without a token names the same key; read beside it, each look added an observation and a line of
-// evidence through the dead-letter half, and the two summaries overwrote each other on every look. The
-// dead-letter row alone says that key, and counts the messages given up on, never the looks.
-func TestAHeldDeadLetterIsCountedByWhatWasGivenUpNotByTheLooks(t *testing.T) {
-	gaveUp := time.Date(2026, 10, 10, 21, 4, 0, 0, time.UTC)
-	now := gaveUp.Add(20 * time.Second)
-	store := conditions.NewInMemory()
-	k := conditions.NewKeeper(t.Context(), conditions.Options{Store: store, History: store,
-		Teller: &conditions.Told{}, Now: func() time.Time { return now }})
-	t.Cleanup(func() { k.Close(t.Context()) })
-
-	const key = "bus.EVENTS.media_sonarr.max-deliveries"
-	held := map[string]int{"EVENTS.media_sonarr": 1}
-	newest := map[string]time.Time{"EVENTS.media_sonarr": gaveUp}
-	advisory := link.Advisory{Kind: link.AdvisoryMaxDeliveries, ID: "EVENTS.media_sonarr", Stream: "EVENTS",
-		Consumer: "media_sonarr", Said: "sonarr on media handed message 7 over 5 times and gave up on it",
-		First: gaveUp, Last: gaveUp, Count: 1}
-	look := func() conditions.Condition {
-		t.Helper()
-		f := &signalFacts{now: now, host: "novox", advisories: []link.Advisory{advisory},
-			deadLetters: held, deadLettersNewest: newest}
-		if err := k.Reconcile(t.Context(), "S9", watchAdvisories(f)); err != nil {
-			t.Fatal(err)
-		}
-		c, found, err := conditions.ReadOne(t.Context(), store, key)
-		if err != nil || !found {
-			t.Fatalf("%s: found %v, %v", key, found, err)
-		}
-		if !strings.Contains(c.Summary, "dead-letters verb") {
-			t.Fatalf("the summary is not the dead-letter row's: %q", c.Summary)
-		}
-		return c
-	}
-
-	var c conditions.Condition
-	for range 5 {
-		c = look()
-		now = now.Add(30 * time.Second)
-	}
-	if c.Observations != 1 || len(c.Evidence) != 1 || !c.LastObserved.Equal(gaveUp) {
-		t.Fatalf("one message given up on, looked at five times, reads as observed %d time(s), last %s, "+
-			"with %d evidence lines: %+v", c.Observations, c.LastObserved, len(c.Evidence), c.Evidence)
-	}
-
-	// The consumer gives up on a second message between two looks: two given up on, one more line.
-	again := now.Add(-10 * time.Second)
-	held["EVENTS.media_sonarr"], newest["EVENTS.media_sonarr"] = 2, again
-	c = look()
-	if c.Observations != 2 || len(c.Evidence) != 2 || !c.LastObserved.Equal(again) {
-		t.Fatalf("two given up on read as observed %d time(s), last %s, evidence %+v", c.Observations,
-			c.LastObserved, c.Evidence)
-	}
-	now = now.Add(30 * time.Second)
-	if c = look(); c.Observations != 2 || len(c.Evidence) != 2 {
-		t.Fatalf("a look with nothing new counted: observed %d time(s), evidence %+v", c.Observations, c.Evidence)
-	}
-}
-
-// The advisory still says the max-deliveries it alone knows: a message given up on that could not be
-// kept, under a key of its own (issue 330), which issue 440's change leaves as it was.
-func TestAMessageThatCouldNotBeKeptIsStillSaidFromTheAdvisory(t *testing.T) {
-	at := time.Date(2026, 10, 10, 21, 4, 0, 0, time.UTC)
-	f := &signalFacts{now: at, host: "novox", advisories: []link.Advisory{{Kind: link.AdvisoryMaxDeliveries,
-		ID: "EVENTS.media_sonarr", Stream: "EVENTS", Consumer: "media_sonarr", Token: link.AdvisoryNotKept,
-		Said: "sonarr on media gave up on message 7, and it could not be kept", First: at, Last: at, Count: 1}}}
-	said := watchAdvisories(f)
-	if len(said) != 1 || said[0].Key() != "bus.EVENTS.media_sonarr.not-kept" {
-		t.Fatalf("%+v", said)
-	}
-}
-
-// A max-deliveries advisory without a token names a consumer's dead-letter key, which only DEAD_LETTERS
-// says (novox/hq issues 330 and 440): with nothing held, the advisory alone raises nothing.
-func TestAMaxDeliveriesAdvisoryAloneRaisesNothing(t *testing.T) {
-	at := time.Date(2026, 10, 10, 21, 4, 0, 0, time.UTC)
-	f := &signalFacts{now: at, host: "novox", advisories: []link.Advisory{{Kind: link.AdvisoryMaxDeliveries,
-		ID: "EVENTS.media_sonarr", Stream: "EVENTS", Consumer: "media_sonarr",
-		Said: "sonarr on media handed message 7 over 5 times and gave up on it", First: at, Last: at, Count: 1}}}
-	if said := watchAdvisories(f); len(said) != 0 {
-		t.Fatalf("said %+v", said)
-	}
-}

cmd/mesh-controller/agent_account.go

@@ -1,253 +0,0 @@
-package main
-
-// The account agents run as (novox/hq ADR 0266).
-//
-// On the control node every agent session ran as the operator's account, which may become root without a
-// password — so any agent there could become root without a person, and ADR 0259 §8 (an answer from the
-// operator's phone authorises an act) rests on that being false where the router and its channels run. The
-// decision: a node may name an account its agents run as, of their own and without sudo; the operator's
-// account keeps its sudo.
-//
-//   - **Named at the controller's terminal only** (`node agent-account`): not a verb, not a setting, so no
-//     agent can name itself another account. Empty is a real state: agents run as the operator there.
-//   - **Composed** as `${machine:agent-account}`, `${machine:agent-home}` and `${machine:agent-root}` for the
-//     agent's module, which declares the account with `root: never`, and as MESH_AGENT_ACCOUNT and
-//     MESH_AGENT_HOME for its tools (catalogue/machine_into_files.go, runtime.go).
-//   - **Judged by the machine itself.** The node-engine reads, on every look, whether an account declared
-//     `root: never` can become root without a person — uid 0, a group that grants root, a sudo rule, a
-//     secret of the mesh it may read — and says it as the declaring module's account verdict, marked
-//     Root "never". agentConfined reads that verdict; the self-check (probe DA) raises
-//     `agent-can-become-root` while it does not hold, and `node show` says it.
-//
-// A verdict not given is never a pass: an engine older than the judging, an account not yet declared, a
-// statement that says nothing of it — each is "not judged", and fails.
-
-import (
-	"context"
-	"fmt"
-	"sort"
-	"strings"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// kindAgentCanBecomeRoot is the condition raised while a machine's agent account can become root without
-// a person, or is not judged (ADR 0266).
-const kindAgentCanBecomeRoot = "agent-can-become-root"
-
-// agentAccountProbe is the self-check's probe of it.
-const agentAccountProbe = "DA"
-
-// agentConfined says whether the agents of a machine that names an agent account are confined: the
-// machine's newest statement holds a healthy account verdict, judged for root, on that account. named is
-// false for a machine that names none — agents run as the operator account there, which this does not
-// judge. why is said either way, in the mesh's words; err is a store that could not be read.
-//
-// The one judgement: `node show`, the self-check, and ADR 0259's router honouring a verified sender read
-// it here.
-// now is the judging clock, threaded so a caller judging several things at one instant judges them all at it.
-func agentConfined(ctx context.Context, inv *inventory.Inventory, node string, now time.Time) (named, confined bool, why string, err error) {
-	n, err := inv.NodeByName(ctx, node)
-	if err != nil {
-		return false, false, "", err
-	}
-	if n.AgentAccount == "" {
-		return false, false, fmt.Sprintf("%s names no agent account: agents run as the operator account (%s)",
-			node, orNoneKnown(n.Account)), nil
-	}
-	h, had, err := inv.HealthOf(ctx, node)
-	if err != nil {
-		return true, false, "", err
-	}
-	confined, why = judgedConfined(n.AgentAccount, h, had, now)
-	return true, confined, why, nil
-}
-
-// verdictFreshFor is how old the statement holding the verdict may be, by this controller's clock. A
-// node-engine states its health on every change and at least every five minutes (mesh-host's sayAnyway), so
-// three statements missed is a node-engine stopped, or a machine away. **A stale verdict is not a pass**: an
-// agent that stopped the node-engine must not leave "cannot become root" standing from before.
-const verdictFreshFor = 15 * time.Minute
-
-// judgedConfined is the judgement over one statement, without the store, at now.
-func judgedConfined(agent string, h inventory.NodeHealth, had bool, now time.Time) (bool, string) {
-	if !had {
-		return false, fmt.Sprintf("the agent account %s is not judged: the machine's node-engine has stated "+
-			"nothing of what it runs", agent)
-	}
-	if age := now.Sub(h.HeardAt); age > verdictFreshFor {
-		return false, fmt.Sprintf("the agent account %s is not judged: the machine's newest statement was heard at "+
-			"%s, more than %d minutes ago, and a verdict that old is not a verdict on now", agent,
-			h.HeardAt.Local().Format("2006-01-02 15:04"), int(verdictFreshFor.Minutes()))
-	}
-	if h.Contract < link.RootContract {
-		return false, fmt.Sprintf("the agent account %s is not judged: the machine's node-engine is older than "+
-			"the judging of an account's root (its statement's contract is %d, the judging is %d)",
-			agent, h.Contract, link.RootContract)
-	}
-	var verdicts []inventory.ResourceHealth
-	for _, r := range h.Resources {
-		if r.Kind == link.KindAccount && r.Target == agent && r.Root == link.RootNever {
-			verdicts = append(verdicts, r)
-		}
-	}
-	if len(verdicts) == 0 {
-		return false, fmt.Sprintf("the agent account %s is not judged: the machine's newest statement holds no "+
-			"verdict on it — no module there declares it never to become root, or the declaration naming it "+
-			"has not been applied", agent)
-	}
-	sort.Slice(verdicts, func(i, j int) bool {
-		return verdicts[i].Module+verdicts[i].Resource < verdicts[j].Module+verdicts[j].Resource
-	})
-	for _, v := range verdicts {
-		switch v.State {
-		case link.StateHealthy:
-		case link.StateUnhealthy:
-			// The engine's own words, which start with link.ReasonRoot when it found a way to root.
-			return false, fmt.Sprintf("the agent account %s %s (said by %s's %s)", agent,
-				orNoneKnown(v.Reason), v.Module, v.Resource)
-		default:
-			return false, fmt.Sprintf("the agent account %s is not judged: %s (%s's %s, %s)", agent,
-				orNoneKnown(v.Reason), v.Module, v.Resource, v.State)
-		}
-	}
-	return true, fmt.Sprintf("the agent account %s cannot become root without a person (judged %s)", agent,
-		h.SaidAt.Local().Format("2006-01-02 15:04"))
-}
-
-// searchQuietFor is how long the controller lets an agent account's verdict wait for the node-engine's setuid
-// search before that is itself the urgent condition: the longest a search is expected to take (link.RootSearchQuiet,
-// the engine's own value; novox/hq issue 361 — the search runs to completion, with no bound of its own), counted
-// from when this controller first saw it waiting, never from the engine's start. Quiet raises nothing; it never
-// makes the agent account confined, which only a healthy verdict from a complete, fresh search does.
-const searchQuietFor = link.RootSearchQuiet
-
-// The kinds of an agent account's verdict, for the quiet a search earns.
-const (
-	verdictOther    = iota // anything else: a stale statement, an older engine, no verdict, another unknown
-	verdictPending         // waiting for the search, and otherwise healthy
-	verdictComplete        // judged: healthy, or a way to root found
-)
-
-// rootVerdictKind reads a statement for the agent account (novox/hq ADR 0266): pending when every verdict on it
-// is healthy or not judged yet because the engine's setuid search runs, at least one of them that; complete when
-// every verdict is healthy or one found a way to root. The engine's own "since" is not read: it starts again at
-// every restart of the engine.
-func rootVerdictKind(agent string, h inventory.NodeHealth, had bool, now time.Time) int {
-	if !had || now.Sub(h.HeardAt) > verdictFreshFor || h.Contract < link.RootContract {
-		return verdictOther
-	}
-	pending, any := false, false
-	for _, r := range h.Resources {
-		if r.Kind != link.KindAccount || r.Target != agent || r.Root != link.RootNever {
-			continue
-		}
-		any = true
-		switch {
-		case r.State == link.StateHealthy:
-		case r.State == link.StateUnhealthy:
-			return verdictComplete
-		case r.State == link.StateUnknown && strings.HasPrefix(r.Reason, link.ReasonRootPending):
-			pending = true
-		default:
-			return verdictOther
-		}
-	}
-	switch {
-	case !any:
-		return verdictOther
-	case pending:
-		return verdictPending
-	}
-	return verdictComplete
-}
-
-// searchStillRunning says the one thing keeping an agent account from being judged is the node-engine's setuid
-// search, and that this controller first saw it waiting less than searchQuietFor ago — kept in the store, so a
-// node-engine restarted in a loop does not keep it quiet. A complete verdict forgets when it began.
-func searchStillRunning(ctx context.Context, inv *inventory.Inventory, node, agent string, h inventory.NodeHealth,
-	had bool, now time.Time) (bool, error) {
-	switch rootVerdictKind(agent, h, had, now) {
-	case verdictComplete:
-		return false, inv.RootSearchJudged(ctx, node)
-	case verdictPending:
-		since, err := inv.RootSearchPending(ctx, node, now)
-		if err != nil {
-			return false, err
-		}
-		return now.Sub(since) <= searchQuietFor, nil
-	}
-	return false, nil
-}
-
-// probeAgentAccounts is DA: every machine that names an agent account has it judged, on its node-engine's
-// newest statement, unable to become root without a person (ADR 0266).
-func probeAgentAccounts(ctx context.Context, d *doctor) ([]conditions.Observation, error) {
-	inv := d.open.inventory
-	nodes, err := inv.Nodes(ctx)
-	if err != nil {
-		return nil, err
-	}
-	var out []conditions.Observation
-	for _, n := range nodes {
-		if n.AgentAccount == "" {
-			continue
-		}
-		h, had, err := inv.HealthOf(ctx, n.Name)
-		if err != nil {
-			return nil, err
-		}
-		now := time.Now()
-		quiet, err := searchStillRunning(ctx, inv, n.Name, n.AgentAccount, h, had, now)
-		if err != nil {
-			return nil, err
-		}
-		confined, why := judgedConfined(n.AgentAccount, h, had, now)
-		if confined {
-			continue
-		}
-		// Not judged yet only because the node-engine's search runs and no complete, fresh one judges: not the
-		// urgent condition after every restart. The agent is still not confined — ADR 0259's router reads
-		// agentConfined, not this — and `node show` still says not judged. Loud again once the search fails,
-		// waits past searchQuietFor, or the statement goes stale.
-		if quiet {
-			continue
-		}
-		out = append(out, conditions.Observation{Scope: conditions.ScopeMachine, ID: n.Name, Token: "agent-root",
-			Machine: n.Name, Severity: conditions.Urgent,
-			Summary: fmt.Sprintf("on %s, %s (ADR 0266): an agent there may become root without a person, and "+
-				"no answer from a channel authorises an act there (ADR 0259 §8)", n.Name, why),
-			Said: why})
-	}
-	return sortedFound(out), nil
-}
-
-// agentAccountLines is what `node show` says of the account agents run as.
-func agentAccountLines(ctx context.Context, inv *inventory.Inventory, n inventory.Node) []string {
-	if n.AgentAccount == "" {
-		return []string{fmt.Sprintf("  agents run as      the operator account (%s); no agent account is named",
-			orNoneKnown(n.Account))}
-	}
-	_, confined, why, err := agentConfined(ctx, inv, n.Name, time.Now())
-	if err != nil {
-		return []string{fmt.Sprintf("  agents run as      %s (home %s); whether it can become root could NOT be read: %v",
-			n.AgentAccount, n.AgentHome(), err)}
-	}
-	verdict := "CAN become root, or is not judged: " + why
-	if confined {
-		verdict = why
-	}
-	return []string{fmt.Sprintf("  agents run as      %s (home %s)", n.AgentAccount, n.AgentHome()),
-		"                     " + verdict}
-}
-
-// orNoneKnown is a value, or that none is known.
-func orNoneKnown(s string) string {
-	if strings.TrimSpace(s) == "" {
-		return "none known"
-	}
-	return s
-}

cmd/mesh-controller/agent_account_test.go

@@ -1,279 +0,0 @@
-package main
-
-import (
-	"github.com/novox/mesh-host/rootsearch"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-	snapshot "github.com/novox/mesh-controller/internal/facts"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// The agent account's judgement (novox/hq ADR 0266): confined only on a healthy account verdict judged for
-// root, on the very account; every verdict not given — no statement, an older engine, no verdict on it, a
-// verdict of unknown — is "not judged" and fails, never a pass.
-func TestAnAgentAccountIsConfinedOnlyOnAHealthyVerdictJudgedForRoot(t *testing.T) {
-	at := time.Date(2026, 10, 8, 19, 21, 0, 0, time.UTC)
-	verdict := func(target, root, state, reason string) inventory.ResourceHealth {
-		return inventory.ResourceHealth{Module: "claude-code", Resource: "claude-code.agent-account",
-			Kind: link.KindAccount, Target: target, State: state, Reason: reason, Root: root, Account: target}
-	}
-	statement := func(contract int, rs ...inventory.ResourceHealth) inventory.NodeHealth {
-		return inventory.NodeHealth{Node: "anchor", Contract: contract, SaidAt: at, HeardAt: at, Resources: rs}
-	}
-	for _, c := range []struct {
-		name     string
-		h        inventory.NodeHealth
-		had      bool
-		confined bool
-		says     string
-	}{
-		{"judged and unable", statement(link.RootContract, verdict("agent", link.RootNever, link.StateHealthy, "")),
-			true, true, "cannot become root without a person"},
-		{"judged and able", statement(link.RootContract, verdict("agent", link.RootNever, link.StateUnhealthy,
-			link.ReasonRoot+": in the group docker, which grants root")), true, false, "in the group docker"},
-		{"a verdict of unknown", statement(link.RootContract, verdict("agent", link.RootNever, link.StateUnknown,
-			"sudo could not be read")), true, false, "not judged"},
-		{"no statement", inventory.NodeHealth{}, false, false, "not judged"},
-		{"an older engine", statement(link.ReadinessContract, verdict("agent", "", link.StateHealthy, "")),
-			true, false, "older than the judging"},
-		{"a verdict on groups only", statement(link.RootContract, verdict("agent", "", link.StateHealthy, "")),
-			true, false, "no verdict on it"},
-		{"a verdict on another account", statement(link.RootContract, verdict("ops", link.RootNever, link.StateHealthy, "")),
-			true, false, "no verdict on it"},
-	} {
-		confined, why := judgedConfined("agent", c.h, c.had, at.Add(time.Minute))
-		if confined != c.confined || !strings.Contains(why, c.says) {
-			t.Errorf("%s: confined %v, %q; want %v saying %q", c.name, confined, why, c.confined, c.says)
-		}
-	}
-	// A verdict heard longer ago than the bound is no verdict: an agent that stopped the node-engine must not
-	// leave "healthy" standing.
-	fresh := statement(link.RootContract, verdict("agent", link.RootNever, link.StateHealthy, ""))
-	if ok, _ := judgedConfined("agent", fresh, true, at.Add(verdictFreshFor)); !ok {
-		t.Error("a verdict exactly at the bound is still one")
-	}
-	if ok, why := judgedConfined("agent", fresh, true, at.Add(verdictFreshFor+time.Second)); ok ||
-		!strings.Contains(why, "not judged") {
-		t.Errorf("a stale healthy verdict passed: %q", why)
-	}
-}
-
-// DA raises an urgent condition, with plain words, on a machine whose agent account is not judged unable to
-// become root; a machine that names none is not its to judge.
-func TestTheSelfCheckSaysAnAgentAccountThatCanBecomeRoot(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	inv := open.inventory
-	for _, n := range []string{"anchor", "laptop"} {
-		if _, err := inv.NodeByName(ctx, n); err != nil {
-			if _, err := inv.AddNode(ctx, n); err != nil {
-				t.Fatal(err)
-			}
-		}
-		if err := inv.SetAccount(ctx, n, "ops", ""); err != nil {
-			t.Fatal(err)
-		}
-	}
-	if err := inv.SetAgentAccount(ctx, "anchor", "agent", ""); err != nil {
-		t.Fatal(err)
-	}
-	d := &doctor{open: open}
-	found, err := probeAgentAccounts(ctx, d)
-	if err != nil {
-		t.Fatal(err)
-	}
-	found = onlyMachine(found, "anchor")
-	if len(found) != 1 || found[0].Machine != "anchor" || found[0].Severity != conditions.Urgent ||
-		!strings.Contains(found[0].Said, "not judged") {
-		t.Fatalf("a named agent account with no verdict: %+v", found)
-	}
-	w := plainWordings[kindAgentCanBecomeRoot](conditions.Observation{Kind: kindAgentCanBecomeRoot, Machine: "anchor"})
-	if w.Headline == "" || w.Needs == "" || w.Resolved == "" {
-		t.Errorf("the condition has no plain words: %+v", w)
-	}
-
-	healthy := inventory.ResourceHealth{Module: "claude-code", Resource: "claude-code.agent-account",
-		Kind: link.KindAccount, Target: "agent", State: link.StateHealthy, Root: link.RootNever, Account: "agent"}
-	if _, err := inv.RecordHealth(ctx, inventory.NodeHealth{Node: "anchor", Contract: link.RootContract,
-		SaidAt: time.Now(), HeardAt: time.Now(), Resources: []inventory.ResourceHealth{healthy}}); err != nil {
-		t.Fatal(err)
-	}
-	if found, err = probeAgentAccounts(ctx, d); err != nil || len(onlyMachine(found, "anchor")) != 0 {
-		t.Fatalf("a judged agent account still fails: %+v %v", found, err)
-	}
-	if named, confined, why, err := agentConfined(ctx, inv, "anchor", time.Now()); err != nil || !named || !confined {
-		t.Fatalf("agentConfined on anchor: %v %v %q %v", named, confined, why, err)
-	}
-	if named, _, why, err := agentConfined(ctx, inv, "laptop", time.Now()); err != nil || named ||
-		!strings.Contains(why, "operator account") {
-		t.Fatalf("agentConfined on a machine naming none: %v %q %v", named, why, err)
-	}
-}
-
-func TestTheAgentRootWordsArePlain(t *testing.T) {
-	w := plainWordings[kindAgentCanBecomeRoot](conditions.Observation{Kind: kindAgentCanBecomeRoot, Machine: "anchor"})
-	if why, ok := conditions.PlainWords(w, "anchor"); !ok {
-		t.Fatalf("not plain: %s: %+v", why, w)
-	}
-}
-
-func onlyMachine(obs []conditions.Observation, machine string) []conditions.Observation {
-	var out []conditions.Observation
-	for _, o := range obs {
-		if o.Machine == machine {
-			out = append(out, o)
-		}
-	}
-	return out
-}
-
-// The snapshot a merge check composes from carries the agent account as a pseudonym (novox/hq ADR 0266),
-// so a change is judged against machines that name one, and the name never leaves.
-func TestTheFactsCarryTheAgentAccountAsAPseudonym(t *testing.T) {
-	open, _ := aMeshWithSecrets(t)
-	ctx := t.Context()
-	if err := open.inventory.SetAccount(ctx, "anchor", "keeper", ""); err != nil {
-		t.Fatal(err)
-	}
-	if err := open.inventory.SetAgentAccount(ctx, "anchor", "warden", ""); err != nil {
-		t.Fatal(err)
-	}
-	f, err := gatherFacts(ctx, open, "2.11.17")
-	if err != nil {
-		t.Fatal(err)
-	}
-	body, _ := f.Encode()
-	if strings.Contains(string(body), "warden") {
-		t.Error("the agent account's name is in the snapshot")
-	}
-	m, ok := f.Machine(snapshot.Pseudonym("machine", "anchor"))
-	if !ok || m.AgentAccount != snapshot.Pseudonym("account", "warden") || m.Account == m.AgentAccount {
-		t.Fatalf("the anchor's agent account reads as %q (operator %q)", m.AgentAccount, m.Account)
-	}
-}
-
-// No verb runs a `node` command that sets something: through the generic `command` verb, `node account`,
-// `node agent-account` and every other `node` subcommand but list and show are refused, naming the terminal.
-func TestNoVerbSetsANodesAccounts(t *testing.T) {
-	for _, line := range []string{
-		"node agent-account novox --clear",
-		"node agent-account novox ops",
-		"node account novox agent",
-		"node account novox",
-		"node add intruder",
-		"node public-domain novox --clear",
-		"node",
-		"node frobnicate",
-	} {
-		argv, err := argvFor("command", map[string]any{"command": line})
-		if err == nil || !strings.Contains(err.Error(), "controller's terminal") ||
-			!strings.Contains(err.Error(), "ADR 0266") {
-			t.Errorf("%q ran as %v (%v); want a refusal naming the terminal", line, argv, err)
-		}
-	}
-	for _, line := range []string{"node show novox", "node list --json", "status --json"} {
-		if _, err := argvFor("command", map[string]any{"command": line}); err != nil {
-			t.Errorf("%q, a read, was refused: %v", line, err)
-		}
-	}
-	if err := terminalOnly([]string{"node", "account", "a", "b"}); err == nil {
-		t.Error("the refusal is not only the command verb's")
-	}
-}
-
-// Naming the agent account is the controller's terminal's alone: the `node` verb only shows.
-func TestTheNodeVerbOnlyShows(t *testing.T) {
-	argv, err := argvFor("node", map[string]any{"node": "anchor"})
-	if err != nil || strings.Join(argv, " ") != "node show anchor" {
-		t.Fatalf("the node verb runs %v (%v)", argv, err)
-	}
-	for _, v := range catalogue.ControllerVerbs {
-		if strings.Contains(v.Name, "agent") {
-			t.Errorf("a verb %q may name the agent account", v.Name)
-		}
-	}
-}
-
-// Until a complete search for setuid programs judges — none since the node-engine's state was kept, or the last
-// older than the engine lets one judge — the agent account is not judged, and the search runs to its end with no
-// bound (novox/hq issue 361). DA does not raise that as urgent within searchQuietFor, counted from when this
-// controller first saw it waiting — never from the engine's own "since", which a restart resets, so an engine
-// restarted in a loop does not keep it quiet. The account is still not confined, and `node show` still says not
-// judged; a search that failed, or a way to root found, is urgent at once.
-func TestASearchStillRunningAfterARestartIsNotUrgent(t *testing.T) {
-	if searchQuietFor != rootsearch.Quiet {
-		t.Fatalf("the quiet is %s and the node-engine's %s: they are one value", searchQuietFor, rootsearch.Quiet)
-	}
-	// A daily search that finishes within the quiet never leaves the account unjudged between two of them.
-	if rootsearch.FreshFor < rootsearch.Every+rootsearch.Quiet {
-		t.Fatalf("a complete search judges for %s, less than a day's search (%s) and the quiet (%s)",
-			rootsearch.FreshFor, rootsearch.Every, rootsearch.Quiet)
-	}
-	open := aMesh(t)
-	ctx := t.Context()
-	inv := open.inventory
-	if _, err := inv.NodeByName(ctx, "anchor"); err != nil {
-		if _, err := inv.AddNode(ctx, "anchor"); err != nil {
-			t.Fatal(err)
-		}
-	}
-	if err := inv.SetAgentAccount(ctx, "anchor", "agent", ""); err != nil {
-		t.Fatal(err)
-	}
-	d := &doctor{open: open}
-	say := func(state, reason string) []conditions.Observation {
-		t.Helper()
-		// The engine's since is always now: it was just restarted.
-		v := inventory.ResourceHealth{Module: "claude-code", Resource: "claude-code.agent-account",
-			Kind: link.KindAccount, Target: "agent", State: state, Reason: reason, Root: link.RootNever,
-			Account: "agent", Since: time.Now()}
-		if _, err := inv.RecordHealth(ctx, inventory.NodeHealth{Node: "anchor", Contract: link.RootContract,
-			SaidAt: time.Now(), HeardAt: time.Now(), Resources: []inventory.ResourceHealth{v}}); err != nil {
-			t.Fatal(err)
-		}
-		found, err := probeAgentAccounts(ctx, d)
-		if err != nil {
-			t.Fatal(err)
-		}
-		return onlyMachine(found, "anchor")
-	}
-	running := link.ReasonRootPending + ": the search for setuid programs, started at 19:21, has not finished yet"
-	healthy := func() {
-		t.Helper()
-		if found := say(link.StateHealthy, ""); len(found) != 0 {
-			t.Fatalf("a healthy verdict raised: %+v", found)
-		}
-	}
-	if found := say(link.StateUnknown, running); len(found) != 0 {
-		t.Fatalf("a search first seen now was raised: %+v", found)
-	}
-	if _, confined, why, _ := agentConfined(ctx, inv, "anchor", time.Now()); confined || !strings.Contains(why, "not judged") {
-		t.Fatalf("an account whose search runs was read as confined: %q", why)
-	}
-	// The engine restarted again and again, each statement's own since fresh: the controller's clock runs on.
-	if _, err := inv.RootSearchPending(ctx, "anchor", time.Now().Add(-searchQuietFor-time.Minute)); err != nil {
-		t.Fatal(err)
-	}
-	healthy() // a complete verdict forgets when the waiting began …
-	if _, err := inv.RootSearchPending(ctx, "anchor", time.Now().Add(-searchQuietFor-time.Minute)); err != nil {
-		t.Fatal(err) // … and this restart loop began past the bound
-	}
-	if found := say(link.StateUnknown, running); len(found) != 1 || found[0].Severity != conditions.Urgent {
-		t.Fatalf("a search pending past the bound, by the controller's clock, was not urgent: %+v", found)
-	}
-	healthy()
-	incomplete := rootsearch.ReasonIncomplete + ": the search for setuid programs did not finish (last tried at " +
-		"19:23: timeout); it is tried again later"
-	if found := say(link.StateUnknown, incomplete); len(found) != 1 || found[0].Severity != conditions.Urgent {
-		t.Fatalf("a search that did not finish was not urgent: %+v", found)
-	}
-	if found := say(link.StateUnhealthy, link.ReasonRoot+": in the group docker; "+running); len(found) != 1 ||
-		found[0].Severity != conditions.Urgent {
-		t.Fatalf("a way to root found while the search runs was not urgent: %+v", found)
-	}
-}

cmd/mesh-controller/api.go

@@ -1,186 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"flag"
-	"fmt"
-	"net/http"
-	"strings"
-	"time"
-)
-
-// The command API: what the mesh can be asked to do, over a network.
-//
-// **An adapter and nothing else** (novox/hq ADR 0035). Every route here calls the same function
-// the command line calls, so a refusal is the same refusal in the same words. Nothing is decided
-// in this file — the moment it validates something the command line does not, the mesh has two
-// answers to one question.
-//
-// **It refuses everything unless it was told how to know who is asking.** The board is published
-// on a public name, and this is what stands behind it: an unauthenticated command surface reachable
-// from the internet is authority over the mesh handed to whoever finds it. So there is no
-// permissive default and no flag that removes the check — a mesh that has not been told how to
-// authenticate serves nothing, loudly.
-//
-// The intended authenticator is an OAuth2 provider (ADR 0035), which is an ordinary module. Until
-// one is configured this refuses, which is the correct behaviour rather than a placeholder: a
-// surface that worked without authentication would be one somebody left running.
-func apiCommand(ctx context.Context, args []string) error {
-	set := flag.NewFlagSet("api", flag.ContinueOnError)
-	listen := set.String("listen", "127.0.0.1:8081", "where to serve it")
-	issuer := set.String("issuer", "",
-		"the OAuth2 issuer whose tokens this accepts; without it, nothing is served")
-	if _, err := parseAround(set, args); err != nil {
-		return err
-	}
-	if strings.TrimSpace(*issuer) == "" {
-		// Refused at start rather than per request, so it is discovered by whoever ran it rather
-		// than by whoever finds it.
-		return errors.New(
-			"--issuer is not set, and this serves commands rather than pages: it will not run " +
-				"without being told whose tokens to believe. An OAuth2 provider is an ordinary " +
-				"module (novox/hq ADR 0035)")
-	}
-
-	server := &http.Server{
-		Addr:              *listen,
-		ReadHeaderTimeout: 10 * time.Second,
-		Handler:           commands(mustAuthenticate(*issuer)),
-	}
-	fmt.Printf("the command API is on http://%s\n", *listen)
-	fmt.Printf("  it accepts tokens from %s and refuses everything else\n", *issuer)
-	fmt.Printf("  every route calls what the command line calls\n")
-
-	go func() {
-		<-ctx.Done()
-		closing, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-		defer cancel()
-		_ = server.Shutdown(closing)
-	}()
-	if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
-		return err
-	}
-	return nil
-}
-
-// Authenticator says whether a request may act, and as whom.
-//
-// An interface so the check can be driven by a test without an identity provider, and so the one
-// real implementation is the only thing that has to be right.
-type Authenticator interface {
-	// Who returns the subject a request is acting as, or an error naming why it may not.
-	Who(r *http.Request) (string, error)
-}
-
-// mustAuthenticate is the real one: a bearer token from the configured issuer.
-//
-// **Not yet verifying the signature**, and it says so rather than pretending. Verification needs
-// the issuer's keys, which needs an identity provider to exist — so this refuses every request
-// until that is built, which is the same answer as having no API at all and is honest about why.
-func mustAuthenticate(issuer string) Authenticator { return notYet{issuer: issuer} }
-
-type notYet struct{ issuer string }
-
-func (n notYet) Who(*http.Request) (string, error) {
-	return "", fmt.Errorf(
-		"this mesh has no way to verify a token from %s yet: the identity provider is a module "+
-			"and none is running. Use the command line, which authenticates through nothing "+
-			"because it is already behind the machine's own login", n.issuer)
-}
-
-// commands is the routing, separate so a test can drive it without a listener.
-func commands(who Authenticator) http.Handler {
-	mux := http.NewServeMux()
-
-	mux.HandleFunc("POST /assign", acting(who, true, func(ctx context.Context, open *stores, in request) (string, error) {
-		return assign(ctx, open, in.Node, splitModules(in.Module)...)
-	}))
-	mux.HandleFunc("POST /unassign", acting(who, true, func(ctx context.Context, open *stores, in request) (string, error) {
-		return unassign(ctx, open, in.Node, splitModules(in.Module)...)
-	}))
-	// Adoption (novox/hq ADR 0100): the same acts as `take`, `converge` and `adopt`.
-	mux.HandleFunc("POST /take", acting(who, true, func(ctx context.Context, open *stores, in request) (string, error) {
-		return take(ctx, open, in.Node, in.Module, takeOptions{Yes: in.Yes, Digest: in.Digest})
-	}))
-	mux.HandleFunc("POST /converge", acting(who, false, func(ctx context.Context, open *stores, in request) (string, error) {
-		return converge(ctx, open, in.Node, in.Yes, in.Digest, in.Filter)
-	}))
-	mux.HandleFunc("POST /adopt", acting(who, false, func(ctx context.Context, open *stores, in request) (string, error) {
-		return adopt(ctx, open, in.Node)
-	}))
-
-	// Anything else is said plainly, because a command surface answering 404 to a verb somebody
-	// expected is indistinguishable from one that is down.
-	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
-		refuse(w, http.StatusNotFound, fmt.Errorf(
-			"%s %s is not something this mesh can be asked; it accepts POST /assign, "+
-				"POST /unassign, POST /take, POST /converge and POST /adopt", r.Method, r.URL.Path))
-	})
-	return mux
-}
-
-type request struct {
-	Node   string `json:"node"`
-	Module string `json:"module"`
-	// Yes, Digest and Filter are converge's and take's: do it rather than preview it, the digest
-	// of the preview it acts on, and (converge) which module loads the mesh's filter.
-	Yes    bool   `json:"yes,omitempty"`
-	Digest string `json:"digest,omitempty"`
-	Filter string `json:"filter,omitempty"`
-}
-
-// acting is the shape every route shares: authenticate, read, act, answer.
-func acting(
-	who Authenticator,
-	needsModule bool,
-	do func(context.Context, *stores, request) (string, error),
-) http.HandlerFunc {
-	return func(w http.ResponseWriter, r *http.Request) {
-		if _, err := who.Who(r); err != nil {
-			refuse(w, http.StatusUnauthorized, err)
-			return
-		}
-		var in request
-		if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
-			refuse(w, http.StatusBadRequest, fmt.Errorf("this is not a request this understands: %w", err))
-			return
-		}
-		if in.Node == "" || (needsModule && in.Module == "") {
-			if needsModule {
-				refuse(w, http.StatusBadRequest, errors.New(`both "node" and "module" are needed`))
-			} else {
-				refuse(w, http.StatusBadRequest, errors.New(`"node" is needed`))
-			}
-			return
-		}
-
-		open, err := openStores(r.Context())
-		if err != nil {
-			refuse(w, http.StatusServiceUnavailable, err)
-			return
-		}
-		defer open.Close()
-
-		said, err := do(r.Context(), open, in)
-		if err != nil {
-			// **The refusal the command line would have given, unchanged.** Carrying `said` with
-			// it matters: an assignment that was kept and still does not resolve is two facts,
-			// and dropping either makes the answer wrong.
-			answer(w, http.StatusConflict, map[string]any{"said": said, "refused": err.Error()})
-			return
-		}
-		answer(w, http.StatusOK, map[string]any{"said": said})
-	}
-}
-
-func answer(w http.ResponseWriter, status int, body map[string]any) {
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(status)
-	_ = json.NewEncoder(w).Encode(body)
-}
-
-func refuse(w http.ResponseWriter, status int, err error) {
-	answer(w, status, map[string]any{"refused": err.Error()})
-}

cmd/mesh-controller/api_test.go

@@ -1,77 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"testing"
-)
-
-type letIn struct{}
-
-func (letIn) Who(*http.Request) (string, error) { return "somebody", nil }
-
-func asking(t *testing.T, who Authenticator, method, path, body string) *httptest.ResponseRecorder {
-	t.Helper()
-	recorded := httptest.NewRecorder()
-	commands(who).ServeHTTP(recorded, httptest.NewRequest(method, path, strings.NewReader(body)))
-	return recorded
-}
-
-// **Nothing is served to somebody the mesh cannot identify**, and that is the default rather than
-// a setting. The board this stands behind is published on a public name (novox/hq 11-a-board), so
-// an unauthenticated command surface is authority over the mesh handed to whoever finds it.
-func TestAnUnauthenticatedRequestIsRefused(t *testing.T) {
-	got := asking(t, mustAuthenticate("https://identity.example/realms/mesh"),
-		"POST", "/assign", `{"node":"anchor","module":"umami"}`)
-	if got.Code != http.StatusUnauthorized {
-		t.Fatalf("an unidentified caller got %d", got.Code)
-	}
-	// And it says what to do instead, because the answer is not "give up".
-	if !strings.Contains(got.Body.String(), "command line") {
-		t.Errorf("the refusal does not say what still works: %s", got.Body.String())
-	}
-}
-
-// The API refuses to start at all without being told whose tokens to believe.
-//
-// At start rather than per request, so it is found by whoever ran it rather than by whoever
-// finds it.
-func TestTheApiWillNotRunWithoutAnIssuer(t *testing.T) {
-	err := apiCommand(context.Background(), []string{})
-	if err == nil {
-		t.Fatal("it served commands without being told who may give them")
-	}
-	if !strings.Contains(err.Error(), "issuer") {
-		t.Errorf("the refusal does not name what is missing: %v", err)
-	}
-}
-
-// A request missing what it acts on is refused before anything is opened.
-func TestARequestThatNamesNothingIsRefused(t *testing.T) {
-	// **The exact refusal, not merely "not accepted".** Asserting non-200 passes even when the
-	// request got as far as opening a store and failing there, which proves nothing about whether
-	// anything was checked — that is what the first version of this test did.
-	for _, body := range []string{`{}`, `{"node":"anchor"}`, `{"module":"umami"}`, `not json`} {
-		got := asking(t, letIn{}, "POST", "/assign", body)
-		if got.Code != http.StatusBadRequest {
-			t.Errorf("%s got %d, and a request naming nothing is a bad request", body, got.Code)
-		}
-	}
-}
-
-// A verb nobody implemented is said plainly. A command surface answering 404 to something
-// somebody expected is indistinguishable from one that is down.
-func TestAnUnknownRouteSaysWhatIsAccepted(t *testing.T) {
-	got := asking(t, letIn{}, "POST", "/rotate", `{}`)
-	if got.Code != http.StatusNotFound {
-		t.Fatalf("got %d", got.Code)
-	}
-	var said map[string]any
-	_ = json.Unmarshal(got.Body.Bytes(), &said)
-	if !strings.Contains(said["refused"].(string), "/assign") {
-		t.Errorf("it does not say what it does accept: %v", said)
-	}
-}

cmd/mesh-controller/apply_failing.go

@@ -1,118 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"sort"
-	"strings"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// kindApplyFailing is S21's kind: a machine whose declarations have been refused, or applied only in part,
-// for longer than one apply interval (novox/hq issue 233).
-const kindApplyFailing = "apply-failing"
-
-// applyEvery is how often a node-engine applies what it was last told when nothing new arrives: its
-// ReconcileEvery. A failure still there after one more of them is not one the next apply clears.
-const applyEvery = 5 * time.Minute
-
-// packageManagerKey is how a node-engine names a package manager that does not answer among what failed
-// (mesh-host's probe.go): "the package manager (pacman)".
-const packageManagerKey = "the package manager ("
-
-// watchApplyFailing is S21: **a machine that does not apply what it was sent is said by the mesh, not only
-// to someone who asks for `status`** (novox/hq issue 233, issue 187's family). A workstation refused every
-// declaration for an hour and a half because its package manager did not answer, and the mesh's only word
-// on it was a line in `status`. Raised once the machine's first report of this failure is older than one apply
-// interval **while the machine is heard** — judged by time, not by how many reports said it: a node-engine
-// says a re-apply only when how it went changed, so the same failure is one report however long it lasts.
-// Names the refusal's or the failure's words; cleared by the clean apply the node-engine then says. Not while
-// the machine is silent, asleep or not known: S1 says silent, and asleep is not lost.
-func watchApplyFailing(f *signalFacts) []conditions.Observation {
-	heard := map[string]bool{}
-	for _, m := range f.machines {
-		if !m.asleep() && !m.lastHeard.IsZero() && f.now.Sub(m.lastHeard) <= heartbeatBound(m.every) {
-			heard[m.name] = true
-		}
-	}
-	var out []conditions.Observation
-	for _, d := range f.doing {
-		if !d.Wrong() || d.Since == nil || f.now.Sub(*d.Since) <= applyEvery || !heard[d.Node] {
-			continue
-		}
-		out = append(out, applyFailing(d, f.now))
-	}
-	return out
-}
-
-// applyFailing is one machine's S21 condition.
-func applyFailing(d inventory.Doing, now time.Time) conditions.Observation {
-	m := d.Node
-	since := d.Since.UTC().Format("2006-01-02 15:04 MST")
-	o := conditions.Observation{Scope: conditions.ScopeMachine, ID: m, Kind: kindApplyFailing, Machine: m,
-		Severity: conditions.Warning, Said: doingWords(d),
-		Resolved: m + " applies what it is sent again"}
-	how := "refused its declaration whole"
-	if d.Outcome != inventory.OutcomeRefused {
-		how = "applied its declaration only in part"
-	}
-	o.Summary = fmt.Sprintf("%s has %s since %s (bound %s): %s", m, how, since, ago(applyEvery), failedNames(d))
-	o.Headline = m + " is not applying its update"
-	o.Explanation = fmt.Sprintf("%s has %s for %s, and trying again has not helped. The details say what fails.",
-		m, plainHow(d), humanDuration(now.Sub(*d.Since)))
-	if tool := unansweringTool(d); tool != "" {
-		o.Summary = fmt.Sprintf("%s: %s does not answer, so no package reaches it; everything else it was sent "+
-			"is applied, since %s (bound %s)", m, tool, since, ago(applyEvery))
-		o.Headline = fmt.Sprintf("%s cannot install packages", m)
-		o.Explanation = fmt.Sprintf("The package manager on %s (%s) has not answered for %s, so no package reaches "+
-			"it. Everything else is still applied, so an update that repairs it can land; if none does, it needs a "+
-			"look on the machine.", m, tool, humanDuration(now.Sub(*d.Since)))
-	}
-	return o
-}
-
-// plainHow is how a machine failed, as the operator reads it.
-func plainHow(d inventory.Doing) string {
-	if d.Outcome == inventory.OutcomeRefused {
-		return "refused every update"
-	}
-	return "applied its updates only in part"
-}
-
-// unansweringTool is the package manager a machine said does not answer, or "".
-func unansweringTool(d inventory.Doing) string {
-	for _, r := range d.Failed {
-		if rest, ok := strings.CutPrefix(r.ID, packageManagerKey); ok {
-			return strings.TrimSuffix(rest, ")")
-		}
-	}
-	return ""
-}
-
-// failedNames is what failed, by name: the refusal, or the failed resources' ids.
-func failedNames(d inventory.Doing) string {
-	if d.Outcome == inventory.OutcomeRefused {
-		return "refused"
-	}
-	ids := make([]string, 0, len(d.Failed))
-	for _, r := range d.Failed {
-		ids = append(ids, r.ID)
-	}
-	sort.Strings(ids)
-	return "failed " + strings.Join(ids, ", ")
-}
-
-// doingWords is the machine's own words on what failed: the evidence, kept inside the mesh.
-func doingWords(d inventory.Doing) string {
-	if d.Outcome == inventory.OutcomeRefused {
-		return "refused: " + oneLine(d.Refused)
-	}
-	var parts []string
-	for _, r := range d.Failed {
-		parts = append(parts, r.ID+": "+oneLine(r.Error))
-	}
-	sort.Strings(parts)
-	return strings.Join(parts, "; ")
-}

cmd/mesh-controller/apply_failing_test.go

@@ -1,123 +0,0 @@
-package main
-
-import (
-	"context"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// unansweringPackageManager is anchor's last report as the workstation's read on 2026-10-04, once its
-// node-engine applies the rest (novox/hq issue 233): the package failed and the package manager did not answer,
-// the same failure on times reports since for before now.
-func unansweringPackageManager(now time.Time, forHowLong time.Duration, times int) inventory.Doing {
-	since := now.Add(-forHowLong)
-	return inventory.Doing{Node: "anchor", Outcome: inventory.OutcomeFailed, At: now.Add(-time.Second),
-		Since: &since, Times: times, Applied: 41, Failed: []inventory.FailedResource{
-			{ID: "apply", Error: `applying "pacman.base": nothing can be said about "base": this is the arch host and ` +
-				"pacman does not answer here. Either this machine is not Arch, or its package database is broken: " +
-				"pacman exited 1: error: config file /etc/pacman.conf could not be read: No such file or directory"},
-			{ID: "the package manager (pacman)", Error: "pacman does not answer here, so every package in this " +
-				"declaration fails and the rest of it is applied (novox/hq issue 233): pacman exited 1: error: config " +
-				"file /etc/pacman.conf could not be read: No such file or directory"}}}
-}
-
-// **A machine whose package manager does not answer is raised by the mesh itself, naming the tool and the
-// probe's words** (novox/hq issue 233): the words in the evidence, the path kept out of the summary.
-func TestAPackageManagerThatDoesNotAnswerIsRaisedNamingItsWords(t *testing.T) {
-	now := time.Date(2026, 10, 4, 14, 0, 0, 0, time.UTC)
-	f := calm(now)
-	f.doing = []inventory.Doing{unansweringPackageManager(now, 90*time.Minute, 18)}
-	got := watchApplyFailing(f)
-	if len(got) != 1 {
-		t.Fatalf("raised %d conditions, want one: %+v", len(got), got)
-	}
-	o := got[0]
-	if o.Key() != "machine.anchor.apply-failing" || o.Machine != "anchor" {
-		t.Errorf("the condition is not the machine's: %s", o.Key())
-	}
-	if !strings.Contains(o.Summary, "pacman does not answer") || !strings.Contains(o.Summary, "since 2026-10-04 12:30") {
-		t.Errorf("the summary does not name the tool and since when: %s", o.Summary)
-	}
-	if strings.Contains(o.Summary, "/etc/") {
-		t.Errorf("the summary carries a path, which belongs in the evidence: %s", o.Summary)
-	}
-	if !strings.Contains(o.Said, "could not be read") {
-		t.Errorf("the evidence does not carry the probe's words: %s", o.Said)
-	}
-	if !strings.Contains(o.Headline, "cannot install packages") || o.Explanation == "" || o.Resolved == "" {
-		t.Errorf("the plain words do not say it: %+v", o)
-	}
-}
-
-// **A whole refusal is raised too**, with the node-engine's words: what the workstation's report said before the
-// node-engine applied the rest.
-func TestARefusalThatGoesOnIsRaised(t *testing.T) {
-	now := time.Date(2026, 10, 4, 14, 0, 0, 0, time.UTC)
-	since := now.Add(-time.Hour)
-	f := calm(now)
-	f.doing = []inventory.Doing{{Node: "anchor", Outcome: inventory.OutcomeRefused, Since: &since, Times: 12,
-		Refused: "this is the arch host and pacman does not answer here", At: now.Add(-time.Minute)}}
-	got := watchApplyFailing(f)
-	if len(got) != 1 || !strings.Contains(got[0].Summary, "refused its declaration whole") ||
-		!strings.Contains(got[0].Said, "pacman does not answer") {
-		t.Fatalf("a refusal that went on for an hour was not raised with its words: %+v", got)
-	}
-}
-
-// **Judged by time while the machine is heard, not by how many reports said it** (review of novox/hq issue 233):
-// a node-engine says the same failure once, so one report an apply interval old is a fault that goes on; one
-// younger is not yet; and a silent or sleeping machine is S1's.
-func TestOneReportOlderThanAnApplyIsRaisedAndAQuietMachineIsNot(t *testing.T) {
-	now := time.Date(2026, 10, 4, 14, 0, 0, 0, time.UTC)
-	f := calm(now)
-	f.doing = []inventory.Doing{unansweringPackageManager(now, 6*time.Minute, 1)}
-	if got := watchApplyFailing(f); len(got) != 1 {
-		t.Errorf("one report of a failure six minutes old was not raised: %+v", got)
-	}
-	f.doing = []inventory.Doing{unansweringPackageManager(now, 4*time.Minute, 1)}
-	if got := watchApplyFailing(f); len(got) != 0 {
-		t.Errorf("a failure four minutes old was raised before one apply could clear it: %+v", got)
-	}
-	f.doing = []inventory.Doing{unansweringPackageManager(now, time.Hour, 1)}
-	f.machines[0].lastHeard = now.Add(-time.Hour)
-	if got := watchApplyFailing(f); len(got) != 0 {
-		t.Errorf("a silent machine was raised for its last report: %+v", got)
-	}
-	f = calm(now)
-	f.doing = []inventory.Doing{unansweringPackageManager(now, time.Hour, 1)}
-	f.doing[0].Node = "a-machine-the-mesh-does-not-know"
-	if got := watchApplyFailing(f); len(got) != 0 {
-		t.Errorf("a machine not heard of was raised: %+v", got)
-	}
-}
-
-// **A failed re-apply followed by a clean one clears S21** (review of novox/hq issue 233): the node-engine says
-// the clean re-apply, the store keeps it as applied with no failure since, and the condition the failure raised
-// is cleared through the keeper on the next tick.
-func TestACleanReapplyAfterAFailedOneClearsTheCondition(t *testing.T) {
-	now := time.Date(2026, 10, 4, 14, 0, 0, 0, time.UTC)
-	store := conditions.NewInMemory()
-	k := conditions.NewKeeper(t.Context(), conditions.Options{Store: store, History: store,
-		Teller: &conditions.Told{}, Now: func() time.Time { return now }})
-	defer k.Close(context.Background())
-	w := &watchdogs{keeper: k, started: now.Add(-time.Hour)}
-
-	failing := calm(now)
-	failing.doing = []inventory.Doing{unansweringPackageManager(now, 20*time.Minute, 1)}
-	w.see(t.Context(), failing)
-	open, err := k.Open(t.Context())
-	if err != nil || len(open) != 1 || open[0].Kind != kindApplyFailing {
-		t.Fatalf("the failed re-apply raised %+v (%v), want apply-failing", open, err)
-	}
-
-	clean := calm(now.Add(5 * time.Minute))
-	clean.doing = nil // the clean re-apply recorded: NotDoingWhatTheyWereTold no longer lists the machine
-	w.see(t.Context(), clean)
-	if open, _ := k.Open(t.Context()); len(open) != 0 {
-		t.Fatalf("the condition stayed open after the clean re-apply: %+v", open)
-	}
-}

cmd/mesh-controller/ask.go

@@ -1,62 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"flag"
-	"fmt"
-	"os"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// ask calls one of a module's tools, through the control plane's own broker connection.
-//
-// A module serves tools under an account scoped to exactly that (novox/hq ADR 0047), and nothing
-// else in the mesh held an account that could ask one — not an operator at a terminal, not an agent
-// acting for one (novox/hq 04-ISSUES/049). The control plane does, so it is the way in: one
-// process, one connection, one place a question can be seen to have been asked (ADR 0095).
-func askCommand(ctx context.Context, args []string) error {
-	positionals, flags := split(args)
-	set := flag.NewFlagSet("ask", flag.ContinueOnError)
-	wait := set.Duration("wait", 60*time.Second, "how long to wait for the module's answer")
-	if err := set.Parse(flags); err != nil {
-		return err
-	}
-	if len(positionals) < 2 || len(positionals) > 3 {
-		return errors.New("ask <module> <tool> [json arguments] [--wait 60s]")
-	}
-	module, tool := positionals[0], positionals[1]
-	var arguments json.RawMessage
-	if len(positionals) == 3 {
-		if !json.Valid([]byte(positionals[2])) {
-			return fmt.Errorf("the arguments are not JSON: %s", positionals[2])
-		}
-		arguments = json.RawMessage(positionals[2])
-	}
-
-	server, err := connectLink(ctx, nil, nil, nil)
-	if err != nil {
-		return err
-	}
-	defer server.Close()
-
-	answer, err := link.Ask(ctx, server.Bus(), module, tool, arguments, *wait)
-	if err != nil {
-		return err
-	}
-	// The answer as the module gave it, to standard output, for a person or a program. A tool
-	// that answered with an error has still answered: printed the same way, and the exit status
-	// says which.
-	body, err := json.Marshal(answer)
-	if err != nil {
-		return err
-	}
-	fmt.Fprintln(os.Stdout, string(body))
-	if answer.Error != "" {
-		return fmt.Errorf("%s.%s answered with an error: %s", module, tool, answer.Error)
-	}
-	return nil
-}

cmd/mesh-controller/asker.go

@@ -1,946 +0,0 @@
-package main
-
-// The controller asks, and acts on the operator's warrant (novox/hq ADR 0259 §6). It holds no channel, no
-// identity and no factor: it asks the router like any other module, and performs the answer chosen with its
-// own grant.
-//
-//   - **For every open, unsilenced condition that needs the operator and names its answers**, one ask is
-//     published on the `operator-channel` seat under the controller's own name: the condition's words, its
-//     actions as options at their levels (Silence acknowledges; Release, Stop, Start and Restart approve),
-//     answered by the operator, expiring after a day (a week when every option only acknowledges). A
-//     condition that clears, is silenced, or changes its answers has its ask cancelled; an ask that expired
-//     unanswered is asked again while the condition lasts; one the router refused is asked again after a wait
-//     that grows with each refusal in a row, at most half an hour, so a refusal is never believed longer. Each ask is kept in the controller's bucket
-//     `asked`, so a restart neither asks twice nor forgets.
-//   - **On a warrant**, heard on the seat's event under the controller's own name (which only the router may
-//     say), the controller acts once per ask: only for an ask it holds, only for the option it offered at
-//     that option's level, and only while the condition is still open. It performs the action as itself —
-//     a silence through its own conditions, any other through the verb the action names — with the warrant's
-//     words as its why, and records it in the hand-act log as the operator's decision, naming the channel,
-//     the ask and the proofs. An ask that ended without a choice is recorded and nothing is done.
-//   - **A warrant it missed** while away is read from the router's record of its asks, under its own name.
-
-import (
-	"context"
-	"crypto/rand"
-	"encoding/hex"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"sort"
-	"strings"
-	"sync"
-	"time"
-
-	"git.novox.be/novox/mesh-sdk/go/asks"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// The asker's name on the seat: the controller's module.
-const askerName = broker.ControllerSeat
-
-// How long an ask lasts: a day when an answer approves, a week when every answer only acknowledges.
-const (
-	// askApproveFor is a day less a margin, so an ask is never refused at the router for lasting a day and
-	// a moment (the SDK's bound is a day).
-	askApproveFor     = 24*time.Hour - 10*time.Minute
-	askAcknowledgeFor = 7 * 24 * time.Hour
-	// askEvery is how often what is open is asked about again, beside every change.
-	askEvery = time.Minute
-	// askCatchUpAfter is how old an open ask is before the router's record of it is read: a warrant heard
-	// on the event needs no reading.
-	askCatchUpAfter = 2 * time.Minute
-	// askAgainAfterAnswer is how long a condition the operator answered is not asked about again with the
-	// same answers: what was chosen takes a while to clear it, and asking again at once would ask twice.
-	askAgainAfterAnswer = time.Hour
-	// askMostOpen is how many asks the controller holds open at once (the router refuses a fourth): the
-	// most urgent conditions first, then the oldest.
-	askMostOpen = asks.MostOpen
-	// askRefusedRetryMost is the longest a refusal is believed without asking again (novox/hq issue 369): the
-	// router refused while its channels had not yet said they could send, the channels could send twenty
-	// minutes later, and the controller repeated that refusal for eleven hours. A refused ask is asked again
-	// after askEvery, then twice as long after each refusal in a row, never longer than this — and at once when
-	// the channels change.
-	askRefusedRetryMost = 30 * time.Minute
-	// askRefusedCounted is how far back refusals in a row are counted for that wait.
-	askRefusedCounted = 6 * time.Hour
-	// askVerdictWait is how long an ask made again after a refusal waits for the router's word before it is
-	// taken as taken: the router refuses an ask as it reads it, so a refusal comes within seconds. Meanwhile
-	// the condition saying it was not delivered stands as it was, neither cleared nor raised again.
-	askVerdictWait = 2 * time.Minute
-)
-
-// refusedRetryAfter is how long a part refused n times in a row waits before it is asked again.
-func refusedRetryAfter(n int) time.Duration {
-	wait := askEvery
-	for i := 1; i < n && wait < askRefusedRetryMost; i++ {
-		wait *= 2
-	}
-	return min(wait, askRefusedRetryMost)
-}
-
-// What became of an ask, as the controller keeps it.
-const (
-	askOpen      = "open"
-	askCancelled = "cancelled"
-)
-
-// asked is one ask the controller made, as it keeps it.
-type asked struct {
-	ID        string `json:"id"`
-	Condition string `json:"condition"`
-	// Channels is what the channels were when it was asked (asker.channels): an ask the router refused is asked
-	// again at once when the condition's answers or the channels change, and otherwise after a wait that grows
-	// with each refusal in a row (refusedRetryAfter, novox/hq issue 369).
-	Channels string              `json:"channels,omitempty"`
-	Ask      asks.Ask            `json:"ask"`
-	Actions  []conditions.Action `json:"actions"`
-	// Options are the actions by option id.
-	Options map[string]int `json:"options"`
-	State   string         `json:"state"`
-	Opened  time.Time      `json:"opened"`
-	Ended   time.Time      `json:"ended,omitempty"`
-	Warrant *asks.Warrant  `json:"warrant,omitempty"`
-	// Acted is what the controller did on the warrant: empty before it did anything, "acting" while it acts,
-	// then "done", "failed: …" or "nothing: …". Anything but empty is never acted on again.
-	Acted string `json:"acted,omitempty"`
-	// Part is which ask of its condition this is (askPart): empty for the one that carries the condition's
-	// answers, or the authorising ones where it has both; "acknowledge" for its acknowledging answers asked
-	// apart (the review of 2026-10-09, M1).
-	Part string `json:"part,omitempty"`
-	// Rehearsal is an ask started at the controller's terminal (rehearse.go): about no condition, its answers
-	// perform nothing, and the reconciling of conditions leaves it alone.
-	Rehearsal bool `json:"rehearsal,omitempty"`
-	// Proposal is a settings layer proposed through a verb (proposals.go, novox/hq ADR 0277): about no
-	// condition, set on Approve by the serving controller itself, and left alone by the reconciling of conditions.
-	Proposal *settingsProposal `json:"proposal,omitempty"`
-}
-
-// ofACondition says an ask is one of a condition's: not a rehearsal, not a proposal.
-func (r asked) ofACondition() bool { return !r.Rehearsal && r.Proposal == nil }
-
-// partKey is an ask's place among what is asked: its condition and its part.
-func partKey(condition, part string) string { return condition + "#" + part }
-
-// partAcknowledge is the part of a condition asked apart for its acknowledging answers.
-const partAcknowledge = "acknowledge"
-
-// askPart is one ask a condition is asked with: its part, what it is about, and its answers.
-type askPart struct {
-	name    string
-	about   string
-	actions []conditions.Action
-}
-
-// levelOf is an action's level as an option offers it: one that says none is never taken for less than
-// approve.
-func levelOf(act conditions.Action) asks.Level {
-	if act.Level == "" {
-		return asks.Approve
-	}
-	return asks.Level(act.Level)
-}
-
-// partsOf is the asks a condition is asked with (the review of 2026-10-09, M1): one, when its answers are all
-// of one kind; else its authorising answers (Release, Stop, Restart) in one ask, about the condition, and its
-// acknowledging ones (Silence) in another. **An acknowledgement never shares an ask with an approval**: a
-// channel that only acknowledges would otherwise answer the ask, and end the approval with it.
-func partsOf(c conditions.Condition) []askPart {
-	var ack, auth []conditions.Action
-	for _, act := range c.Actions {
-		if levelOf(act) == asks.Acknowledge {
-			ack = append(ack, act)
-		} else {
-			auth = append(auth, act)
-		}
-	}
-	if len(ack) == 0 || len(auth) == 0 {
-		return []askPart{{about: c.Key, actions: c.Actions}}
-	}
-	return []askPart{{about: c.Key, actions: auth},
-		{name: partAcknowledge, about: c.Key + "." + partAcknowledge, actions: ack}}
-}
-
-// askedStore keeps the asks (broker.AskedBucket). **Every write after the first is a compare-and-set** (the
-// review of 2026-10-09, L2): an ask is created once, and changed only over the revision it was read at, the
-// change decided again on what is read — so two controllers, or two deliveries of one warrant, never write
-// over each other, and of two that would act only the one whose write stands does.
-type askedStore interface {
-	Get(ctx context.Context, id string) (*asked, error)
-	// Create keeps a new ask, and refuses one already kept under its id.
-	Create(ctx context.Context, a asked) error
-	// Change applies change to the ask kept under id, by compare-and-set, and says whether its write stood.
-	// change says whether to write at all; on a write that came between, it is asked again on what is read.
-	Change(ctx context.Context, id string, change func(*asked) bool) (bool, error)
-	All(ctx context.Context) ([]asked, error)
-}
-
-// askChangeTries is how often a change is read and tried again when another write came between.
-const askChangeTries = 5
-
-// asker is the controller asking the operator and acting on the answer.
-type asker struct {
-	open    func(ctx context.Context) ([]conditions.Condition, error)
-	silence func(ctx context.Context, key string, d time.Duration, by, why string) error
-	store   askedStore
-	// publish puts a message on a subject's stream, de-duplicated by id.
-	publish func(ctx context.Context, subject string, body []byte, id string) error
-	// call performs an action's verb with its arguments, as the controller.
-	call func(ctx context.Context, a conditions.Action, args map[string]string) error
-	// setLayer sets a proposed settings layer on the operator's warrant (novox/hq ADR 0277); nil cannot.
-	setLayer setOnWarrant
-	// record writes the hand-act log.
-	record func(ctx context.Context, act link.HandAct) error
-	// routerRecord reads the router's record of an ask for a warrant missed; nil reads nothing.
-	routerRecord func(ctx context.Context, id string) (*asks.Warrant, error)
-	// routerHere says whether a router holds the seat and takes asks under the asker's name; nil is yes.
-	routerHere func(ctx context.Context) (bool, error)
-	// grantHeld says whether the bus holds the controller's grant to ask: the user list the bus's machine was
-	// last sent is the one the mesh composes now (novox/hq issue 353). The grant is composed from the router's
-	// assignment and reaches the bus only when that machine is next pushed, so between `assign` and `push`
-	// the record says a router is here and the bus refuses every ask. why says what to do; nil is yes.
-	grantHeld func(ctx context.Context) (held bool, why string, err error)
-	// channels is what the channels are now, as a fingerprint: who holds which kind, promising what.
-	channels func(ctx context.Context) string
-	// raise keeps the asker's own condition (sourceAsker): which conditions needing the operator could not be
-	// asked, and why. Nil raises nothing (a test that does not look).
-	raise func(ctx context.Context, obs []conditions.Observation) error
-	now   func() time.Time
-	logf  func(string, ...any)
-
-	saidNoRouter bool
-	saidNoGrant  bool
-	// saidGrantCaveat is whether a grant held with a caveat was said, so it is said once.
-	saidGrantCaveat bool
-
-	mu     sync.Mutex
-	nudged chan struct{}
-}
-
-func (a *asker) nudge() {
-	if a == nil {
-		return
-	}
-	a.mu.Lock()
-	if a.nudged == nil {
-		a.nudged = make(chan struct{}, 1)
-	}
-	ch := a.nudged
-	a.mu.Unlock()
-	select {
-	case ch <- struct{}{}:
-	default:
-	}
-}
-
-// keep asks until ctx ends: now, on every change of a condition, and every askEvery.
-func (a *asker) keep(ctx context.Context) {
-	a.nudge()
-	tick := time.NewTicker(askEvery)
-	defer tick.Stop()
-	a.mu.Lock()
-	nudged := a.nudged
-	a.mu.Unlock()
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-tick.C:
-		case <-nudged:
-		}
-		if err := a.reconcile(ctx); err != nil {
-			a.logf("what the operator is asked could not be brought up to date: %v", err)
-		}
-	}
-}
-
-// wants says whether a condition is one to ask about now.
-func wants(c conditions.Condition, now time.Time) bool {
-	return len(c.Actions) > 0 && c.Needs != "" && !c.SilencedAt(now)
-}
-
-func sameAsked(a []conditions.Action, b []conditions.Action) bool {
-	x, _ := json.Marshal(a)
-	y, _ := json.Marshal(b)
-	return string(x) == string(y)
-}
-
-// reconcile brings what is asked in line with what is open.
-func (a *asker) reconcile(ctx context.Context) error {
-	now := a.now()
-	if a.routerHere != nil {
-		here, err := a.routerHere(ctx)
-		if err != nil {
-			return err
-		}
-		if !here {
-			if !a.saidNoRouter {
-				a.logf("no router takes asks under the controller's name (a module declaring %s with its ask "+
-					"named by its caller, assigned): the operator is asked nothing until one is", broker.AsksSeat)
-				a.saidNoRouter = true
-			}
-			open, err := a.open(ctx)
-			if err != nil {
-				return err
-			}
-			var unasked []conditions.Condition
-			for _, c := range open {
-				if wants(c, now) {
-					unasked = append(unasked, c)
-				}
-			}
-			return a.sayUnasked(ctx, unasked, "no router takes the controller's asks: no module holding "+
-				broker.AsksSeat+" that takes an ask under its asker's name is assigned")
-		}
-		a.saidNoRouter = false
-	}
-	if a.grantHeld != nil {
-		held, why, err := a.grantHeld(ctx)
-		if err != nil {
-			return err
-		}
-		if !held {
-			if !a.saidNoGrant {
-				a.logf("the bus does not hold the controller's grant to ask yet: %s; the operator is asked nothing until it does", why)
-				a.saidNoGrant = true
-			}
-			open, err := a.open(ctx)
-			if err != nil {
-				return err
-			}
-			var unasked []conditions.Condition
-			for _, c := range open {
-				if wants(c, now) {
-					unasked = append(unasked, c)
-				}
-			}
-			return a.sayUnasked(ctx, unasked, "the bus does not hold the controller's grant to ask yet: "+why)
-		}
-		if why != "" && !a.saidGrantCaveat {
-			// Held, with a caveat worth one line (an older bus module cannot confirm the reload).
-			a.logf("the controller asks: %s", why)
-			a.saidGrantCaveat = true
-		} else if why == "" {
-			a.saidGrantCaveat = false
-		}
-		a.saidNoGrant = false
-	}
-	channels := ""
-	if a.channels != nil {
-		channels = a.channels(ctx)
-	}
-	open, err := a.open(ctx)
-	if err != nil {
-		return err
-	}
-	all, err := a.store.All(ctx)
-	if err != nil {
-		return err
-	}
-	byCondition := map[string]asked{} // by partKey
-	// What is open and not a condition's — a rehearsal, a proposal — still counts toward what the router holds
-	// open for the controller (askMostOpen); expired unanswered, it is kept so, as the router says it too.
-	otherOpen := 0
-	for _, r := range all {
-		if r.State == askOpen && !r.ofACondition() && !now.Before(r.Ask.Expires) {
-			if _, err := a.store.Change(ctx, r.ID, func(x *asked) bool {
-				if x.State != askOpen || x.Acted != "" {
-					return false
-				}
-				x.State, x.Ended, x.Acted = string(asks.OutcomeExpired), now, "nothing: the ask expired unanswered"
-				return true
-			}); err != nil {
-				return err
-			}
-			continue
-		}
-		if r.State == askOpen && !r.ofACondition() {
-			otherOpen++
-		}
-		if r.State == askOpen && r.ofACondition() {
-			k := partKey(r.Condition, r.Part)
-			if prior, held := byCondition[k]; !held || r.Opened.After(prior.Opened) {
-				byCondition[k] = r
-			}
-		}
-	}
-	// A warrant missed while away, read from the router's record: for a condition's ask, and for a proposal's or a
-	// rehearsal's alike.
-	if a.routerRecord != nil {
-		var lookedUp []asked
-		for _, r := range byCondition {
-			lookedUp = append(lookedUp, r)
-		}
-		for _, r := range all {
-			if r.State == askOpen && !r.ofACondition() {
-				lookedUp = append(lookedUp, r)
-			}
-		}
-		for _, r := range lookedUp {
-			if now.Sub(r.Opened) < askCatchUpAfter {
-				continue
-			}
-			if w, err := a.routerRecord(ctx, r.ID); err == nil && w != nil {
-				body, _ := json.Marshal(w)
-				if err := a.Decided(ctx, body); err != nil {
-					return err
-				}
-			}
-		}
-		if all, err = a.store.All(ctx); err != nil {
-			return err
-		}
-		byCondition = map[string]asked{}
-		for _, r := range all {
-			if r.State == askOpen && r.ofACondition() {
-				byCondition[partKey(r.Condition, r.Part)] = r
-			}
-		}
-	}
-	// What the operator answered lately, by condition: not asked again at once; and what the router refused,
-	// newest first: not asked again until the answers or the channels change.
-	answered, refused := map[string]asked{}, map[string]asked{}
-	for _, r := range all {
-		k := partKey(r.Condition, r.Part)
-		if r.State == string(asks.OutcomeChosen) && now.Sub(r.Ended) < askAgainAfterAnswer {
-			answered[k] = r
-		}
-		if r.State == string(asks.OutcomeRefused) {
-			if prior, has := refused[k]; !has || r.Opened.After(prior.Opened) {
-				refused[k] = r
-			}
-		}
-	}
-	// Refusals in a row, by part: those since the last ask that was not refused, within askRefusedCounted.
-	// superseded: a part asked since its last refusal, by an ask the router did not refuse — open, answered,
-	// expired or cancelled. Its refusal is history then, never said again (the review of PR 198: an answered
-	// retry brought the refusal back).
-	inRow, superseded := map[string]int{}, map[string]asked{}
-	for k, last := range refused {
-		for _, r := range all {
-			if partKey(r.Condition, r.Part) == k && r.State != string(asks.OutcomeRefused) && r.State != askUnsent &&
-				r.Opened.After(last.Opened) && r.Opened.After(superseded[k].Opened) {
-				superseded[k] = r
-			}
-		}
-		var since time.Time
-		for _, r := range all {
-			if partKey(r.Condition, r.Part) == k && r.State != string(asks.OutcomeRefused) && r.State != askUnsent &&
-				!r.Opened.After(last.Opened) && r.Opened.After(since) {
-				since = r.Opened
-			}
-		}
-		for _, r := range all {
-			if partKey(r.Condition, r.Part) == k && r.State == string(asks.OutcomeRefused) && r.Opened.After(since) &&
-				now.Sub(r.Opened) < askRefusedCounted {
-				inRow[k]++
-			}
-		}
-	}
-	wanted := map[string]bool{}
-	var unasked []conditions.Condition // refused by the router, and nothing it was refused for changed
-	var refusedWords []string
-	// The most urgent first, then the oldest: those are asked when no more than askMostOpen may be.
-	sort.SliceStable(open, func(i, j int) bool {
-		ui, uj := open[i].Severity == conditions.Urgent, open[j].Severity == conditions.Urgent
-		if ui != uj {
-			return ui
-		}
-		if !open[i].Raised.Equal(open[j].Raised) {
-			return open[i].Raised.Before(open[j].Raised)
-		}
-		return open[i].Key < open[j].Key
-	})
-	openNow := otherOpen
-	for _, c := range open {
-		if !wants(c, now) {
-			continue
-		}
-		for _, p := range partsOf(c) {
-			if r, held := byCondition[partKey(c.Key, p.name)]; held && sameAsked(r.Actions, p.actions) && now.Before(r.Ask.Expires) {
-				openNow++
-			}
-		}
-	}
-	for _, c := range open {
-		if !wants(c, now) {
-			continue
-		}
-		saidUnasked := false
-		for _, p := range partsOf(c) {
-			key := partKey(c.Key, p.name)
-			wanted[key] = true
-			if r, was := refused[key]; was && sameAsked(r.Actions, p.actions) {
-				cur, held := byCondition[key]
-				ended := r.Ended
-				if ended.IsZero() {
-					ended = r.Opened
-				}
-				later, asked := superseded[key]
-				waiting := !held && !asked && r.Channels == channels && now.Sub(ended) < refusedRetryAfter(inRow[key])
-				// Asked again now (the wait over), or lately and the router's word not in yet: said as it was until
-				// that word, so the condition neither clears nor is raised again at each try.
-				retrying := !held && !asked && !waiting
-				verdictDue := held && asked && later.ID == cur.ID && now.Sub(cur.Opened) < askVerdictWait
-				if waiting || retrying || verdictDue {
-					if !saidUnasked {
-						unasked, saidUnasked = append(unasked, c), true
-					}
-					if r.Warrant != nil && r.Warrant.Words != "" {
-						refusedWords = append(refusedWords, r.Warrant.Words)
-					}
-				}
-				if waiting {
-					continue // refused lately, and nothing it was refused for has changed: asked again after the wait
-				}
-			}
-			if r, done := answered[key]; done && sameAsked(r.Actions, p.actions) {
-				if _, held := byCondition[key]; !held {
-					continue
-				}
-			}
-			if r, held := byCondition[key]; held {
-				switch {
-				case !sameAsked(r.Actions, p.actions):
-					if err := a.cancel(ctx, r, "its answers changed"); err != nil {
-						return err
-					}
-				case !now.Before(r.Ask.Expires):
-					// Expired unanswered: the router says so too; asked again below while it lasts.
-					if _, err := a.store.Change(ctx, r.ID, func(x *asked) bool {
-						if x.State != askOpen {
-							return false
-						}
-						x.State, x.Ended = string(asks.OutcomeExpired), now
-						return true
-					}); err != nil {
-						return err
-					}
-					openNow--
-				default:
-					continue
-				}
-			}
-			if openNow >= askMostOpen {
-				continue // asked when one of the open ones ends, most urgent first
-			}
-			if err := a.ask(ctx, c, p, channels); err != nil {
-				a.logf("the operator could not be asked about %s: %v", c.Key, err)
-				continue
-			}
-			openNow++
-		}
-	}
-	stillOpen := map[string]conditions.Condition{}
-	for _, c := range open {
-		stillOpen[c.Key] = c
-	}
-	for key, r := range byCondition {
-		if wanted[key] {
-			continue
-		}
-		// **A silence never takes an approval back** (the confirmation review of 2026-10-09, M1). Silence is an
-		// acknowledgement — anyone at the desk may give it — so a condition silenced while its approval is asked
-		// keeps that ask open, unchanged, until it is answered on a channel that proves who answered, or expires.
-		// It is not asked again once it ends, while the silence lasts.
-		if c, open := stillOpen[r.Condition]; open && c.SilencedAt(now) && r.Ask.Highest() != asks.Acknowledge &&
-			now.Before(r.Ask.Expires) && keepsItsAnswers(c, r) {
-			continue
-		}
-		if err := a.cancel(ctx, r, "the condition ended, was silenced or needs nothing now"); err != nil {
-			return err
-		}
-	}
-	why := "the router refused the ask"
-	if len(refusedWords) > 0 {
-		why += ": " + refusedWords[0]
-	}
-	return a.sayUnasked(ctx, unasked, why)
-}
-
-// keepsItsAnswers says a condition still offers the answers an ask kept was asked with.
-func keepsItsAnswers(c conditions.Condition, r asked) bool {
-	for _, p := range partsOf(c) {
-		if partKey(c.Key, p.name) == partKey(r.Condition, r.Part) {
-			return sameAsked(r.Actions, p.actions)
-		}
-	}
-	return false
-}
-
-// sourceAsker raises the asker's own condition.
-const sourceAsker = "asker"
-
-// sayUnasked keeps the asker's one condition: while a condition that needs the operator could not be asked
-// on any channel, said loudly (failure must be loud), cleared when every one could be.
-func (a *asker) sayUnasked(ctx context.Context, unasked []conditions.Condition, why string) error {
-	if a.raise == nil {
-		return nil
-	}
-	var obs []conditions.Observation
-	if len(unasked) > 0 {
-		keys := make([]string, 0, len(unasked))
-		severity := conditions.Warning
-		for _, c := range unasked {
-			keys = append(keys, c.Key)
-			if c.Severity == conditions.Urgent {
-				severity = conditions.Urgent
-			}
-		}
-		sort.Strings(keys)
-		obs = append(obs, conditions.Observation{Scope: conditions.ScopeSeat, ID: broker.AsksSeat, Token: "unasked",
-			Kind: "asks-undelivered", Severity: severity, Source: sourceAsker,
-			Summary: fmt.Sprintf("%d condition(s) that need the operator could not be asked on any channel: %s; %s",
-				len(keys), strings.Join(keys, ", "), why),
-			Headline:    "Questions for you not delivered",
-			Explanation: "The mesh could not send you its questions on any channel.",
-			Needs:       "answer them from the mesh MCP server, and check why no channel carries them.",
-			Resolved:    "The mesh can ask you again"})
-	}
-	if err := a.raise(ctx, obs); err != nil {
-		a.logf("whether the operator could be asked could not be kept as a condition: %v", err)
-	}
-	return nil
-}
-
-// optionID is an action's label as an option's id: "Silence for a week" is silence-for-a-week.
-func optionID(label string) string {
-	var b strings.Builder
-	dash := false
-	for _, r := range strings.ToLower(label) {
-		switch {
-		case r >= 'a' && r <= 'z', r >= '0' && r <= '9':
-			b.WriteRune(r)
-			dash = false
-		case !dash && b.Len() > 0:
-			b.WriteByte('-')
-			dash = true
-		}
-	}
-	return strings.TrimSuffix(b.String(), "-")
-}
-
-// doesWords is what an action does, in the words an option says it with.
-func doesWords(act conditions.Action) string {
-	switch {
-	case act.Arguments["silence"] != "":
-		return "nothing more is said of it for a week"
-	case act.Verb == "mesh-delivery.release":
-		return "the delivery goes on"
-	case act.Verb == "mesh-delivery.stop":
-		return "the delivery ends"
-	case act.Verb == broker.ControllerSeat+".plans" && act.Arguments["go"] != "":
-		return "the delivery starts"
-	case act.Verb == broker.ControllerSeat+".plans" && act.Arguments["stop"] != "":
-		return "the delivery is stopped"
-	case strings.HasSuffix(act.Verb, ".restart"):
-		return "its service is restarted on " + act.Machine
-	}
-	return strings.ToLower(act.Label)
-}
-
-// askText is a condition's words as an ask says them: without where an answer is given when no channel can
-// give it (FromMeshMCPServer), since the ask is answered on a channel and the router says where else.
-func askText(s string) string {
-	for _, with := range []string{", " + FromMeshMCPServer, " " + FromMeshMCPServer} {
-		s = strings.ReplaceAll(s, with, ".")
-	}
-	return strings.ReplaceAll(s, "..", ".")
-}
-
-// askOf is the ask one part of a condition is asked with.
-func askOf(id string, c conditions.Condition, p askPart, now time.Time) (asks.Ask, map[string]int) {
-	q := asks.Ask{ID: id, Headline: c.Headline, Explanation: askText(c.Explanation), Who: asks.Operator,
-		OnExpiry: "nothing is done, and you are asked again while it lasts", About: p.about,
-		Urgent: c.Severity == conditions.Urgent}
-	options := map[string]int{}
-	approves := false
-	for i, act := range p.actions {
-		level := levelOf(act) // an action that says nothing of its level is never taken for less than approve
-		approves = approves || level != asks.Acknowledge
-		oid := optionID(act.Label)
-		options[oid] = i
-		// Every option binds the exact act it stands for (novox/hq ADR 0259 §6): the verb, the machine and
-		// every argument. The warrant then authorises that act and no other.
-		binds, _ := asks.ActDigest(boundAct(act))
-		q.Options = append(q.Options, asks.Option{ID: oid, Label: act.Label, Does: doesWords(act), Level: level,
-			Binds: binds})
-	}
-	q.Expires = now.Add(askAcknowledgeFor)
-	if approves {
-		q.Expires = now.Add(askApproveFor)
-	}
-	return q, options
-}
-
-// boundAct is what an option's Binds digests: the act exactly as the controller will perform it — its verb,
-// machine, level, and each argument as "arg.<name>" — and never its label or words.
-func boundAct(act conditions.Action) asks.Act {
-	out := asks.Act{"verb": act.Verb, "machine": act.Machine, "level": act.Level}
-	for k, v := range act.Arguments {
-		out["arg."+k] = v
-	}
-	return out
-}
-
-func newAskID() string {
-	var b [8]byte
-	_, _ = rand.Read(b[:])
-	return "c" + hex.EncodeToString(b[:])
-}
-
-// askUnsent is an ask kept and never published: asked again at the next look.
-const askUnsent = "unsent"
-
-// ask publishes one ask about a part of a condition, kept before it is published (the review of 2026-10-09,
-// L3): a warrant for it then always finds it, and one whose publishing failed is marked so and asked again.
-func (a *asker) ask(ctx context.Context, c conditions.Condition, p askPart, channels string) error {
-	now := a.now()
-	id := newAskID()
-	q, options := askOf(id, c, p, now)
-	if err := q.Check(now); err != nil {
-		return err
-	}
-	body, err := json.Marshal(q)
-	if err != nil {
-		return err
-	}
-	if err := a.store.Create(ctx, asked{ID: id, Condition: c.Key, Part: p.name, Ask: q, Actions: p.actions,
-		Options: options, State: askOpen, Opened: now, Channels: channels}); err != nil {
-		return fmt.Errorf("the ask could not be kept, so it was not asked: %w", err)
-	}
-	if err := a.publish(ctx, asks.AskSubject(askerName), body, "ask."+id); err != nil {
-		if _, cerr := a.store.Change(ctx, id, func(x *asked) bool {
-			if x.State != askOpen || x.Acted != "" {
-				return false
-			}
-			x.State, x.Ended, x.Acted = askUnsent, a.now(), "nothing: it could not be published: "+err.Error()
-			return true
-		}); cerr != nil {
-			a.logf("the ask %s could not be published, and could not be marked so: %v", id, cerr)
-		}
-		return err
-	}
-	a.logf("asked the operator about %s (%s): %d answer(s)", c.Key, id, len(q.Options))
-	return nil
-}
-
-// cancel takes an ask back: kept cancelled first, so a warrant that comes after is refused, then said to the
-// router; a cancel the router did not hear leaves the ask to expire there, and nothing is done on it here.
-func (a *asker) cancel(ctx context.Context, r asked, why string) error {
-	stood, err := a.store.Change(ctx, r.ID, func(x *asked) bool {
-		if x.State != askOpen {
-			return false
-		}
-		x.State, x.Ended = askCancelled, a.now()
-		return true
-	})
-	if err != nil || !stood {
-		return err
-	}
-	body, _ := json.Marshal(map[string]string{"id": r.ID})
-	if err := a.publish(ctx, asks.CancelSubject(askerName), body, "cancel."+r.ID); err != nil {
-		a.logf("the ask %s about %s is taken back here, and the router could not be told (%v): it expires there, "+
-			"and no answer to it is acted on", r.ID, r.Condition, err)
-		return nil
-	}
-	a.logf("took back the ask %s about %s: %s", r.ID, r.Condition, why)
-	return nil
-}
-
-// Decided takes the router's word on one of the controller's asks (link.Decider). An error is returned only
-// when what was decided could not be kept, so the word is held and heard again.
-func (a *asker) Decided(ctx context.Context, body []byte) error {
-	var w asks.Warrant
-	if err := json.Unmarshal(body, &w); err != nil {
-		a.logf("the router's word on an ask could not be read; ignored: %v", err)
-		return nil
-	}
-	if w.Asker != askerName {
-		a.logf("REFUSED a warrant for %s's ask %s: the controller acts only on its own", w.Asker, w.Ask)
-		return nil
-	}
-	r, err := a.store.Get(ctx, w.Ask)
-	if err != nil {
-		return err
-	}
-	if r == nil {
-		a.logf("REFUSED a warrant for the ask %s, which the controller does not hold", w.Ask)
-		return nil
-	}
-	if r.Acted != "" {
-		return nil // heard again: acted on once
-	}
-	now := a.now()
-	if w.Outcome != asks.OutcomeChosen {
-		acted := "nothing: the ask " + string(w.Outcome)
-		if w.Words != "" {
-			acted += ": " + w.Words
-		}
-		if _, err := a.store.Change(ctx, r.ID, func(x *asked) bool {
-			if x.Acted != "" {
-				return false
-			}
-			x.State, x.Ended, x.Warrant, x.Acted = string(w.Outcome), now, &w, acted
-			return true
-		}); err != nil {
-			return err
-		}
-		a.logf("the ask %s about %s ended %s; nothing is done", r.ID, r.Condition, w.Outcome)
-		return nil
-	}
-	if r.State != askOpen {
-		// Cancelled, replaced or expired in the controller's own record: no answer to it is acted on.
-		a.logf("REFUSED a warrant for the ask %s, which is %s in the controller's own record", r.ID, r.State)
-		return nil
-	}
-	option, err := w.For(askerName, r.Ask)
-	if err != nil {
-		a.logf("REFUSED a warrant for the ask %s: %v", r.ID, err)
-		return nil
-	}
-	index, offered := r.Options[option.ID]
-	if !offered || index >= len(r.Actions) {
-		a.logf("REFUSED a warrant for the ask %s: it chose %s, which no action stands for", r.ID, option.ID)
-		return nil
-	}
-	act := r.Actions[index]
-	// The act about to be performed is the one the option bound when the controller asked: a record changed
-	// since is refused, never performed.
-	if err := option.Performs(boundAct(act)); err != nil {
-		a.logf("REFUSED a warrant for the ask %s: %v", r.ID, err)
-		return nil
-	}
-	open, err := a.open(ctx)
-	if err != nil {
-		return err
-	}
-	stillOpen := r.Rehearsal || r.Proposal != nil // a rehearsal and a proposal are about no condition
-	for _, c := range open {
-		stillOpen = stillOpen || c.Key == r.Condition
-	}
-	if !stillOpen {
-		// The asker checks the state is still what it asked about before it acts (to-be 46 §10, step 7).
-		if _, err := a.store.Change(ctx, r.ID, func(x *asked) bool {
-			if x.State != askOpen || x.Acted != "" {
-				return false
-			}
-			x.State, x.Warrant, x.Ended, x.Acted = string(asks.OutcomeChosen), &w, now,
-				"nothing: the condition ended before the answer"
-			return true
-		}); err != nil {
-			return err
-		}
-		a.logf("%s, for %s, which ended meanwhile: nothing is done", w.Says(), r.Condition)
-		return nil
-	}
-	// Claimed before acting, by compare-and-set: only the delivery whose write stands acts (security review
-	// of 2026-10-08, finding 9). Not by the warrant's message id, which another publisher could take first:
-	// the controller's own record decides.
-	claimed, err := a.store.Change(ctx, r.ID, func(x *asked) bool {
-		if x.State != askOpen || x.Acted != "" {
-			return false
-		}
-		x.State, x.Warrant, x.Acted = string(asks.OutcomeChosen), &w, "acting"
-		return true
-	})
-	if err != nil {
-		return err
-	}
-	if !claimed {
-		a.logf("the warrant for the ask %s was already taken by another delivery; nothing more is done", r.ID)
-		return nil
-	}
-	r.Acted = "acting"
-
-	why := fmt.Sprintf("%s (ask %s)", w.Says(), r.ID)
-	args := map[string]string{}
-	for k, v := range act.Arguments {
-		args[k] = v
-	}
-	if v, takes := args["why"]; takes && v == "" {
-		args["why"] = why
-	}
-	var acted error
-	outcome := "done"
-	switch {
-	case r.Rehearsal && act.Verb == rehearsalVerb:
-		// A rehearsal's answer performs nothing: it is recorded below as the operator's decision.
-	case r.Proposal != nil && act.Verb == proposalVerb:
-		// A proposed settings layer, set by this controller itself on Approve (novox/hq ADR 0277): the act's
-		// digest of the values is held to the record's own values before anything is set.
-		outcome, acted = a.decideProposal(ctx, *r, act, w)
-		if acted == nil && outcome != "" && !strings.HasPrefix(outcome, "nothing") {
-			outcome = "done: " + outcome
-		}
-	case act.Arguments["silence"] != "":
-		acted = a.silence(ctx, act.Arguments["silence"], conditions.MaxSilence, byWords(w), why)
-	default:
-		acted = a.call(ctx, act, args)
-	}
-	ended := a.now()
-	if acted != nil {
-		outcome = "failed: " + acted.Error()
-	}
-	r.Ended, r.Acted = ended, outcome
-	if _, err := a.store.Change(ctx, r.ID, func(x *asked) bool {
-		if x.Acted != "acting" {
-			return false
-		}
-		x.Ended, x.Acted = ended, outcome
-		return true
-	}); err != nil {
-		a.logf("%s was acted on (%s), and how it ended could NOT be kept: %v", r.ID, outcome, err)
-	}
-	verbArgs := []string{act.Verb}
-	if act.Machine != "" {
-		verbArgs = append(verbArgs, "on "+act.Machine)
-	}
-	keys := make([]string, 0, len(args))
-	for k := range args {
-		keys = append(keys, k)
-	}
-	sort.Strings(keys)
-	for _, k := range keys {
-		if k != "why" {
-			verbArgs = append(verbArgs, k+"="+args[k])
-		}
-	}
-	if err := a.record(ctx, link.HandAct{Verb: handActWarrant, Args: verbArgs, Why: why, By: byWords(w),
-		Cause: conditions.CauseOperatorAnswer, Condition: r.Condition, Via: viaWords(w), Ask: r.ID,
-		Proofs: w.Proofs, RequestedBy: r.Condition, Outcome: r.Acted}); err != nil {
-		a.logf("%s was done, and could NOT be recorded in the hand-act log: %v", why, err)
-	}
-	a.logf("%s: %s", why, r.Acted)
-	return nil
-}
-
-// handActWarrant is the verb an act the operator chose on a warrant is recorded under: a person's decision,
-// never a repair (handActVerbs).
-const handActWarrant = "warrant"
-
-// byWords is who chose, as the hand-act log says it: "the operator, as telegram identity 42".
-func byWords(w asks.Warrant) string {
-	if w.By == nil {
-		return "the operator"
-	}
-	return fmt.Sprintf("the %s, as %s identity %s", w.By.Who, w.By.Kind, w.By.Identity)
-}
-
-// viaWords is the channel an answer came through: its module and kind, and how the sender was known.
-func viaWords(w asks.Warrant) string {
-	if w.By == nil {
-		return w.Channel
-	}
-	via := w.Channel + " (" + w.By.Kind + ")"
-	if w.By.Verified != "" {
-		via += ", " + w.By.Verified
-	}
-	return via
-}
-
-// errNotGranted is an action whose verb the controller's grant does not name.
-var errNotGranted = errors.New("the controller's grant does not name this verb")

cmd/mesh-controller/asker_bus_test.go

@@ -1,151 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/nats-io/nats.go"
-	"github.com/nats-io/nats.go/jetstream"
-
-	"git.novox.be/novox/mesh-sdk/go/asks"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/link"
-	"github.com/novox/mesh-controller/internal/testbus"
-)
-
-// busAsker is an asker on a real bus's `asked` bucket, counting what it performs: two of them are two
-// controllers sharing one record.
-type busAskerRig struct {
-	mu     sync.Mutex
-	called int
-	acts   int
-	open   []conditions.Condition
-	sent   [][]byte
-}
-
-func (rig *busAskerRig) asker(t *testing.T, conn *nats.Conn, now time.Time) *asker {
-	return &asker{
-		open: func(context.Context) ([]conditions.Condition, error) {
-			rig.mu.Lock()
-			defer rig.mu.Unlock()
-			return rig.open, nil
-		},
-		silence: func(context.Context, string, time.Duration, string, string) error { return nil },
-		store:   busAsked{conn: conn},
-		publish: func(_ context.Context, subject string, body []byte, _ string) error {
-			rig.mu.Lock()
-			defer rig.mu.Unlock()
-			if subject == asks.AskSubject(askerName) {
-				rig.sent = append(rig.sent, body)
-			}
-			return nil
-		},
-		call: func(context.Context, conditions.Action, map[string]string) error {
-			time.Sleep(20 * time.Millisecond) // long enough for the other delivery to arrive meanwhile
-			rig.mu.Lock()
-			defer rig.mu.Unlock()
-			rig.called++
-			return nil
-		},
-		record: func(context.Context, link.HandAct) error {
-			rig.mu.Lock()
-			defer rig.mu.Unlock()
-			rig.acts++
-			return nil
-		},
-		now:  func() time.Time { return now },
-		logf: t.Logf,
-	}
-}
-
-func askedBus(t *testing.T) *nats.Conn {
-	t.Helper()
-	conn, err := nats.Connect(testbus.URL(t))
-	if err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(conn.Close)
-	js, err := jetstream.New(conn)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if _, err := js.CreateKeyValue(context.Background(), jetstream.KeyValueConfig{Bucket: broker.AskedBucket}); err != nil {
-		t.Fatal(err)
-	}
-	return conn
-}
-
-// The review of 2026-10-09 (L7): two deliveries of one warrant, to two controllers at once, perform its act
-// exactly once and record it once — the record's compare-and-set decides, never the warrant's message id.
-func TestTwoAnswersAtOnceActOnce(t *testing.T) {
-	conn := askedBus(t)
-	now := time.Date(2026, 10, 9, 14, 0, 0, 0, time.UTC)
-	rig := &busAskerRig{open: []conditions.Condition{heldCondition()}}
-	first, second := rig.asker(t, conn, now), rig.asker(t, conn, now)
-	if err := first.reconcile(context.Background()); err != nil {
-		t.Fatal(err)
-	}
-	if len(rig.sent) != 1 {
-		t.Fatalf("asked %d times", len(rig.sent))
-	}
-	var q asks.Ask
-	_ = json.Unmarshal(rig.sent[0], &q)
-	release, _ := q.Option("release")
-	w := asks.Warrant{Ask: q.ID, Asker: askerName, About: q.About, Outcome: asks.OutcomeChosen, Option: release.ID,
-		Label: release.Label, Level: release.Level, Channel: "telegram", Proofs: []string{"P1"}, At: now,
-		AskDigest: q.Digest(), By: &asks.Person{Who: asks.Operator, Kind: "telegram", Identity: "42", Verified: "user id verified"}}
-	body, _ := json.Marshal(w)
-	var wg sync.WaitGroup
-	for _, a := range []*asker{first, second, first, second} {
-		wg.Add(1)
-		go func(a *asker) {
-			defer wg.Done()
-			if err := a.Decided(context.Background(), body); err != nil {
-				t.Error(err)
-			}
-		}(a)
-	}
-	wg.Wait()
-	if rig.called != 1 || rig.acts != 1 {
-		t.Fatalf("performed %d time(s), recorded %d time(s)", rig.called, rig.acts)
-	}
-	got, err := busAsked{conn: conn}.Get(context.Background(), q.ID)
-	if err != nil || got == nil || got.Acted != "done" {
-		t.Fatalf("kept as %+v (%v)", got, err)
-	}
-}
-
-// The review of 2026-10-09 (L2): a write decided on a record read earlier never lands over one made since. A
-// cancel read before the answer was acted on leaves the act's record as it is.
-func TestAStaleCancelDoesNotWriteOverAnAct(t *testing.T) {
-	conn := askedBus(t)
-	now := time.Date(2026, 10, 9, 14, 0, 0, 0, time.UTC)
-	rig := &busAskerRig{open: []conditions.Condition{heldCondition()}}
-	a := rig.asker(t, conn, now)
-	if err := a.reconcile(context.Background()); err != nil {
-		t.Fatal(err)
-	}
-	var q asks.Ask
-	_ = json.Unmarshal(rig.sent[0], &q)
-	stale, _ := busAsked{conn: conn}.Get(context.Background(), q.ID)
-	release, _ := q.Option("release")
-	w := asks.Warrant{Ask: q.ID, Asker: askerName, About: q.About, Outcome: asks.OutcomeChosen, Option: release.ID,
-		Label: release.Label, Level: release.Level, Channel: "telegram", At: now, AskDigest: q.Digest(),
-		By: &asks.Person{Who: asks.Operator, Kind: "telegram", Identity: "42", Verified: "user id verified"}}
-	body, _ := json.Marshal(w)
-	if err := a.Decided(context.Background(), body); err != nil {
-		t.Fatal(err)
-	}
-	if err := a.cancel(context.Background(), *stale, "the condition ended"); err != nil {
-		t.Fatal(err)
-	}
-	got, _ := busAsked{conn: conn}.Get(context.Background(), q.ID)
-	if got.State != string(asks.OutcomeChosen) || got.Acted != "done" {
-		t.Errorf("a stale cancel wrote over the act: %+v", got)
-	}
-}

cmd/mesh-controller/asker_wire.go

@@ -1,589 +0,0 @@
-package main
-
-// The asker on the bus: its asks in the controller's bucket `asked`, its asks and cancels published on the
-// seat under the controller's name, the verbs a warrant chooses called with the controller's grant, and the
-// router's record of its asks read under its name (novox/hq ADR 0259).
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"sort"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/nats-io/nats.go"
-	"github.com/nats-io/nats.go/jetstream"
-
-	"git.novox.be/novox/mesh-sdk/go/asks"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// askerFrom is the serving controller's asker; nil in any other process.
-var askerFrom *asker
-
-// askWithin is how long a verb a warrant chose is given to answer.
-const askWithin = time.Minute
-
-type busAsked struct{ conn *nats.Conn }
-
-func (b busAsked) kv(ctx context.Context) (jetstream.KeyValue, error) {
-	js, err := jetstream.New(b.conn)
-	if err != nil {
-		return nil, err
-	}
-	return js.KeyValue(ctx, broker.AskedBucket)
-}
-
-func (b busAsked) Get(ctx context.Context, id string) (*asked, error) {
-	kv, err := b.kv(ctx)
-	if err != nil {
-		return nil, err
-	}
-	e, err := kv.Get(ctx, id)
-	if errors.Is(err, jetstream.ErrKeyNotFound) {
-		return nil, nil
-	}
-	if err != nil {
-		return nil, err
-	}
-	var r asked
-	return &r, json.Unmarshal(e.Value(), &r)
-}
-
-// Create keeps a new ask under its id, and only where none is kept: never over another.
-func (b busAsked) Create(ctx context.Context, r asked) error {
-	kv, err := b.kv(ctx)
-	if err != nil {
-		return err
-	}
-	body, err := json.Marshal(r)
-	if err != nil {
-		return err
-	}
-	_, err = kv.Create(ctx, r.ID, body)
-	return err
-}
-
-// Change applies change to the ask kept under id by compare-and-set on its key's revision (the review of
-// 2026-10-09, L2): read, changed, and written only over the revision read; when another write came between,
-// read again and asked again, at most askChangeTries times. change says whether to write at all.
-func (b busAsked) Change(ctx context.Context, id string, change func(*asked) bool) (bool, error) {
-	kv, err := b.kv(ctx)
-	if err != nil {
-		return false, err
-	}
-	for try := 0; try < askChangeTries; try++ {
-		e, err := kv.Get(ctx, id)
-		if errors.Is(err, jetstream.ErrKeyNotFound) {
-			return false, nil
-		}
-		if err != nil {
-			return false, err
-		}
-		var r asked
-		if err := json.Unmarshal(e.Value(), &r); err != nil {
-			return false, err
-		}
-		if !change(&r) {
-			return false, nil
-		}
-		body, err := json.Marshal(r)
-		if err != nil {
-			return false, err
-		}
-		if _, err := kv.Update(ctx, id, body, e.Revision()); err != nil {
-			var api *jetstream.APIError
-			if errors.Is(err, jetstream.ErrKeyExists) || (errors.As(err, &api) && api.ErrorCode == jetstream.JSErrCodeStreamWrongLastSequence) {
-				continue
-			}
-			return false, err
-		}
-		return true, nil
-	}
-	return false, fmt.Errorf("the ask %s changed under every one of %d tries", id, askChangeTries)
-}
-
-func (b busAsked) All(ctx context.Context) ([]asked, error) {
-	kv, err := b.kv(ctx)
-	if err != nil {
-		return nil, err
-	}
-	lister, err := kv.ListKeys(ctx)
-	if err != nil {
-		return nil, err
-	}
-	defer func() { _ = lister.Stop() }()
-	var out []asked
-	for k := range lister.Keys() {
-		e, err := kv.Get(ctx, k)
-		if err != nil {
-			continue
-		}
-		var r asked
-		if json.Unmarshal(e.Value(), &r) == nil {
-			out = append(out, r)
-		}
-	}
-	return out, nil
-}
-
-// callAction performs an action's verb as the controller, through the grant that names it.
-func callAction(conn *nats.Conn) func(ctx context.Context, a conditions.Action, args map[string]string) error {
-	return func(ctx context.Context, a conditions.Action, args map[string]string) error {
-		seat, verb, ok := strings.Cut(a.Verb, ".")
-		if !ok {
-			return fmt.Errorf("%q names no seat and verb", a.Verb)
-		}
-		body := map[string]any{}
-		for k, v := range args {
-			body[k] = v
-		}
-		if seat == catalogue.DeliverySeat {
-			_, err := askDeliveryOwner(ctx, conn, verb, body)
-			return err
-		}
-		granted := false
-		for _, v := range broker.VerbsTheControllerActsOnAWarrant {
-			granted = granted || (v.Seat == seat && v.Verb == verb)
-		}
-		if !granted {
-			return fmt.Errorf("%s: %w", a.Verb, errNotGranted)
-		}
-		var answer link.Answer
-		var err error
-		if a.Machine != "" {
-			answer, err = link.AskSeatTool(ctx, conn, seat, verb, a.Machine, body, askWithin)
-		} else {
-			answer, err = link.AskMeshSeatTool(ctx, conn, seat, verb, body, askWithin)
-		}
-		if err != nil {
-			return err
-		}
-		if answer.Error != "" {
-			return fmt.Errorf("%s refused: %s", a.Verb, answer.Error)
-		}
-		return nil
-	}
-}
-
-// routerRecordOf reads the router's record of one of the controller's asks, under its name, and answers
-// how it ended when it did: the bucket is the one the asks seat's declarer names as its records.
-func routerRecordOf(conn *nats.Conn, inv *inventory.Inventory) func(ctx context.Context, id string) (*asks.Warrant, error) {
-	return func(ctx context.Context, id string) (*asks.Warrant, error) {
-		bucket, err := asksRecords(ctx, inv)
-		if err != nil || bucket == "" {
-			return nil, err
-		}
-		reply, err := conn.RequestWithContext(ctx, "$JS.API.DIRECT.GET.KV_"+bucket+".$KV."+bucket+"."+askerName+"."+id, nil)
-		if err != nil {
-			return nil, err
-		}
-		if reply.Header.Get("Status") != "" {
-			return nil, nil // none, or not readable: the event says it
-		}
-		var rec struct {
-			State   string        `json:"state"`
-			Warrant *asks.Warrant `json:"warrant"`
-		}
-		if json.Unmarshal(reply.Data, &rec) != nil || rec.State == "open" || rec.Warrant == nil {
-			return nil, nil
-		}
-		return rec.Warrant, nil
-	}
-}
-
-// asksRecords is the bucket the asks seat's declarer keeps its record of asks in.
-func asksRecords(ctx context.Context, inv *inventory.Inventory) (string, error) {
-	declared, err := inv.Catalogue(ctx)
-	if err != nil {
-		return "", err
-	}
-	for _, m := range declared {
-		for _, s := range m.DefinesSeats {
-			if s.Name == broker.AsksSeat && len(s.Records) > 0 {
-				return broker.BucketName(m.Module, s.Records[0]), nil
-			}
-		}
-	}
-	return "", nil
-}
-
-// routerHereIn says whether a module declaring the asks seat, with its ask named by its caller, is assigned:
-// without it nothing takes an ask, and asking would only fill a queue nobody reads.
-func routerHereIn(inv *inventory.Inventory) func(ctx context.Context) (bool, error) {
-	return func(ctx context.Context) (bool, error) {
-		entries, err := inv.Catalogued(ctx)
-		if err != nil {
-			return false, err
-		}
-		for _, e := range entries {
-			for _, s := range e.Manifest.DefinesSeats {
-				if s.Name == broker.AsksSeat && s.NamedByCaller("ask") && len(e.On) > 0 {
-					return true, nil
-				}
-			}
-		}
-		return false, nil
-	}
-}
-
-// grantHeldIn says whether the bus holds the controller's grant to ask (novox/hq issue 353), judged on the two
-// facts that make it so, and failing closed on each:
-//
-//  1. **composed**: the user list the mesh composes now grants the controller itself to publish its ask
-//     (controllerMayAsk) — the controller's own grant, not whether any user of the list changed;
-//  2. **in force**: the bus's own module, on the machine holding the bus, says the user list there allows it
-//     and the server reloaded after that list was written (the nats module's `nats_user_can`, `in_force`) — a
-//     list sent is not a list the bus enforces until it reloads.
-//
-// Anything that cannot be worked out is not held, with why, so the conditions that need the operator are said
-// as undelivered rather than asked into a refusal.
-func grantHeldIn(open *stores, conn *nats.Conn) func(ctx context.Context) (bool, string, error) {
-	return grantHeldBy(composedGrantIn(open), busGrantIn(open, conn), time.Now)
-}
-
-// grantJudge is one of the two facts: whether it holds, and why not.
-type grantJudge func(ctx context.Context) (bool, string, error)
-
-// grantHeldBy is the judgement over the two facts, remembered for grantLookEvery: composing the list resolves
-// the bus's machine whole, and asking the bus's module is a call.
-func grantHeldBy(composed, inForce grantJudge, now func() time.Time) func(ctx context.Context) (bool, string, error) {
-	var mu sync.Mutex
-	var at time.Time
-	var held bool
-	var why string
-	return func(ctx context.Context) (bool, string, error) {
-		mu.Lock()
-		defer mu.Unlock()
-		if !at.IsZero() && now().Sub(at) < grantLookEvery {
-			return held, why, nil
-		}
-		held, why = judgeGrant(ctx, composed, inForce)
-		at = now()
-		return held, why, nil
-	}
-}
-
-// judgeGrant is held only when both facts hold; an error is a fact not known, never a yes. A fact that holds
-// with a caveat (a reload not confirmed) gives that caveat as the why of a yes.
-func judgeGrant(ctx context.Context, composed, inForce grantJudge) (bool, string) {
-	var caveat []string
-	for _, fact := range []struct {
-		judge grantJudge
-		what  string
-	}{{composed, "whether the mesh composes the controller a grant to ask"}, {inForce, "whether the bus enforces it"}} {
-		if fact.judge == nil {
-			return false, fact.what + " is not judged here"
-		}
-		ok, why, err := fact.judge(ctx)
-		if err != nil {
-			return false, fact.what + " could not be worked out: " + err.Error()
-		}
-		if !ok {
-			return false, why
-		}
-		if why != "" {
-			caveat = append(caveat, why)
-		}
-	}
-	return true, strings.Join(caveat, "; ")
-}
-
-// controllerMayAsk says whether the controller's own grant, as composed from these records, lets it publish its
-// ask (ADR 0259 §3: composed while a router that takes asks under its asker's name is assigned).
-func controllerMayAsk(records broker.Records) (bool, error) {
-	users, err := broker.Users(records)
-	if err != nil {
-		return false, err
-	}
-	for _, u := range users {
-		if u.Kind != broker.KindController {
-			continue
-		}
-		perms, err := broker.PermissionsFor(u)
-		if err != nil {
-			return false, err
-		}
-		return broker.MayPublish(perms, asks.AskSubject(askerName)), nil
-	}
-	return false, errors.New("the composition holds no controller")
-}
-
-// composedGrantIn is the first fact, from the mesh's records.
-func composedGrantIn(open *stores) grantJudge {
-	return func(ctx context.Context) (bool, string, error) {
-		if open == nil || open.inventory == nil {
-			return false, "", errors.New("the mesh's records are not open")
-		}
-		records, err := open.inventory.BusRecords(ctx)
-		if err != nil {
-			return false, "", err
-		}
-		may, err := controllerMayAsk(records)
-		if err != nil || may {
-			return may, "", err
-		}
-		return false, "the mesh composes the controller no grant to ask: no router that takes asks under its " +
-			"asker's name is assigned", nil
-	}
-}
-
-// busGrantIn is the second fact, asked of the bus's own module on the machine holding the bus, with the check
-// main made before it (novox/hq issue 353, PR 186: is the user list sent to the bus's machine the one composed
-// now) kept for the cases the module's word does not settle.
-func busGrantIn(open *stores, conn *nats.Conn) grantJudge {
-	ask := func(ctx context.Context) (string, json.RawMessage, error) {
-		if open == nil || open.inventory == nil || conn == nil {
-			return "", nil, errors.New("the mesh's records or the bus are not open")
-		}
-		holders, err := seatHolders(ctx, open.inventory)
-		if err != nil {
-			return "", nil, err
-		}
-		h, held := holders[theBrokerSeat]
-		if !held || h.Node == "" || h.Module == "" {
-			return "", nil, nil
-		}
-		a, err := link.AskModuleToolOn(ctx, conn, h.Module, busUserCanTool, h.Node, map[string]any{
-			"user": broker.ControllerName, "action": "publish", "subject": asks.AskSubject(askerName)}, 15*time.Second)
-		if err != nil {
-			return h.Node, nil, err
-		}
-		if a.Error != "" {
-			return h.Node, nil, errors.New(a.Error)
-		}
-		return h.Node, a.Result, nil
-	}
-	list := func(ctx context.Context) (busListState, error) {
-		if open == nil || open.inventory == nil {
-			return busListState{}, errors.New("the mesh's records are not open")
-		}
-		s, err := brokerListState(ctx, open, nil)
-		if err != nil || s.Machine == "" || !s.Behind {
-			return s, err
-		}
-		step, err := busHeld(ctx, open.inventory, []string{s.Machine})
-		if err != nil {
-			return busListState{}, err
-		}
-		s.BusStep = step[s.Machine]
-		return s, nil
-	}
-	return busGrantBy(ask, list)
-}
-
-// busListState is the user list on the bus's machine as the controller's record knows it: whether the list
-// sent there is behind the one composed now, why it could not be composed, and the bus step a send there waits
-// on (that machine cannot be pushed until a person's `bus upgrade`).
-type busListState struct {
-	Machine    string
-	Behind     bool
-	Uncomposed error
-	BusStep    string
-}
-
-// remedy is the one thing that sends the bus's machine the list composed now: the plan's own reason when it
-// cannot be composed, the bus upgrade while sends there wait on it, and otherwise a push of that machine.
-func (s busListState) remedy(node string) string {
-	if s.Machine != "" {
-		node = s.Machine
-	}
-	switch {
-	case s.Uncomposed != nil:
-		return fmt.Sprintf("the user list for %s cannot be composed (%v); `plan %s` says what to fix first",
-			node, s.Uncomposed, node)
-	case s.BusStep != "":
-		return fmt.Sprintf("sends to %s wait on the bus's planned step, so a push will not carry it: %s", node, s.BusStep)
-	}
-	return fmt.Sprintf("`push %s` carries it", node)
-}
-
-// busGrantBy judges the bus's word, and names for each way it is not held the one thing that makes it held:
-//
-//   - **in force**: held;
-//   - **allowed, from a module older than `in_force`**: held, with the caveat that the reload is not confirmed.
-//     The file allows the publish, and the bus reloads within about 5 s of a change to it, so the worst case is
-//     one ask refused in those seconds, which is asked again (issue 369). The list check is not consulted:
-//     while a bus step is pending the bus's machine cannot be pushed, so any change to the composed list would
-//     read as behind for good and silence every ask until a person's bus upgrade (the review of PR 188);
-//   - **allowed, written, not reloaded** (the module gives both times): wait about 5 s;
-//   - **allowed, in force not known** (the module could not read a time): what is not known, said;
-//   - **not allowed, or the module cannot answer**: the list check decides — the remedy that sends the list
-//     when it is behind (busListState.remedy), and, for a module that cannot answer, held while the list sent
-//     is current, as main judged it.
-//
-// ask answers the machine holding the bus and its module's answer ("" when nothing holds the bus); list is the
-// record's word on the list sent to that machine.
-func busGrantBy(ask func(ctx context.Context) (string, json.RawMessage, error),
-	list func(ctx context.Context) (busListState, error)) grantJudge {
-	return func(ctx context.Context) (bool, string, error) {
-		node, raw, askErr := ask(ctx)
-		if askErr == nil && node == "" {
-			return false, "no module holds the bus, so nothing says what it enforces", nil
-		}
-		var answer busAnswer
-		if askErr == nil {
-			if answer, askErr = readBusAnswer(raw); askErr != nil {
-				askErr = fmt.Errorf("its answer could not be read: %w", askErr)
-			}
-		}
-		if askErr != nil {
-			if node == "" {
-				node = "the bus's machine"
-			}
-			s, err := list(ctx)
-			if err != nil {
-				return false, "", fmt.Errorf("the bus module on %s could not answer (%v), and whether the list sent "+
-					"there is the one composed now could not be worked out: %w", node, askErr, err)
-			}
-			if s.Behind {
-				return false, fmt.Sprintf("the bus module on %s could not answer (%v), and the user list sent there is "+
-					"behind what the mesh composes; %s", node, askErr, s.remedy(node)), nil
-			}
-			return true, fmt.Sprintf("the bus module on %s could not answer (%v); judged by the user list sent there, "+
-				"which is the one composed now", node, askErr), nil
-		}
-		notAllowed := func(older string) (bool, string, error) {
-			s, err := list(ctx)
-			if err != nil {
-				return false, "", fmt.Errorf("the user list on %s does not allow the controller to ask%s, and whether "+
-					"the list sent there is the one composed now could not be worked out: %w", node, older, err)
-			}
-			if s.Behind {
-				return false, fmt.Sprintf("the user list on %s does not allow the controller to ask%s: it is behind "+
-					"what the mesh composes; %s", node, older, s.remedy(node)), nil
-			}
-			return false, fmt.Sprintf("the user list on %s does not allow the controller to ask%s, though the list "+
-				"sent there is the one composed now; %s again", node, older, s.remedy(node)), nil
-		}
-		switch {
-		case answer.InForce == nil && answer.Allowed:
-			return true, fmt.Sprintf("the user list on %s allows the controller to ask, but its reload is not "+
-				"confirmed: the bus module there is older than the answer whether a grant is in force, and the bus "+
-				"upgrade (`bus upgrade`) carries one that confirms it", node), nil
-		case answer.InForce == nil:
-			return notAllowed(" (the bus module there is older than the answer whether a grant is in force)")
-		case !answer.Allowed:
-			return notAllowed("")
-		case *answer.InForce:
-			return true, "", nil
-		case answer.FileWritten != "" && answer.ServerLoaded != "":
-			return false, fmt.Sprintf("the bus on %s has the controller's grant to ask written (%s) but has not "+
-				"reloaded since (last load %s); it reloads in place within about 5 s, so nothing is to be done but wait",
-				node, answer.FileWritten, answer.ServerLoaded), nil
-		}
-		why := answer.Why
-		if why == "" {
-			why = "it gives no reason"
-		}
-		return false, fmt.Sprintf("the user list on %s allows the controller to ask, but whether the bus enforces it "+
-			"is not known: %s", node, why), nil
-	}
-}
-
-// busUserCanTool is the bus module's answer to whether a user may do something, and whether it is in force.
-const busUserCanTool = "nats_user_can"
-
-// busAnswer is the bus module's answer to busUserCanTool; InForce is nil from a module older than that field,
-// and FileWritten and ServerLoaded are given only when it could read both times (mesh-catalog's nats InForce).
-type busAnswer struct {
-	Allowed      bool   `json:"allowed"`
-	InForce      *bool  `json:"in_force"`
-	Why          string `json:"why"`
-	FileWritten  string `json:"file_written"`
-	ServerLoaded string `json:"server_loaded"`
-}
-
-func readBusAnswer(raw json.RawMessage) (busAnswer, error) {
-	var answer busAnswer
-	err := json.Unmarshal(raw, &answer)
-	return answer, err
-}
-
-// grantLookEvery is how often the bus's user list is judged against the one its machine was last sent.
-const grantLookEvery = 30 * time.Second
-
-// channelsIn is what the channels are now, as a fingerprint: each module claiming a kind of the channel
-// bench, where, promising what, and whether of its own account. An ask the router refused is asked again
-// once this changes.
-func channelsIn(inv *inventory.Inventory) func(ctx context.Context) string {
-	return func(ctx context.Context) string {
-		entries, err := inv.Catalogued(ctx)
-		if err != nil {
-			return ""
-		}
-		var parts []string
-		for _, e := range entries {
-			for _, c := range e.Manifest.Claims {
-				if c.Kind == "" || !catalogue.KindedBenches[c.Name] {
-					continue
-				}
-				on := append([]string(nil), e.On...)
-				sort.Strings(on)
-				caps := append([]string(nil), c.Capabilities...)
-				sort.Strings(caps)
-				parts = append(parts, fmt.Sprintf("%s/%s=%s@%s[%s]own:%t", c.Name, c.Kind, e.Manifest.Module,
-					strings.Join(on, ","), strings.Join(caps, ","), e.Manifest.RunsAs != ""))
-			}
-		}
-		sort.Strings(parts)
-		return strings.Join(parts, ";")
-	}
-}
-
-// startAsking makes the serving controller's asker and hands it the router's words.
-func startAsking(ctx context.Context, open *stores, server *link.Server, conn *nats.Conn, keeper *conditions.Keeper) {
-	js, err := jetstream.New(conn)
-	if err != nil {
-		fmt.Printf("the operator cannot be asked: %v\n", err)
-		return
-	}
-	a := servingAsker(open, conn, js, keeper)
-	if err := server.Decides(a); err != nil {
-		fmt.Printf("the operator's answers cannot be heard, so nothing is asked: %v\n", err)
-		return
-	}
-	askerFrom = a
-	go a.keep(ctx)
-}
-
-// servingAsker is the serving controller's asker, wired to the mesh: what it reads, publishes, performs and
-// records, and the judgements it asks by — the bus's grant to ask among them (novox/hq issue 353).
-func servingAsker(open *stores, conn *nats.Conn, js jetstream.JetStream, keeper *conditions.Keeper) *asker {
-	return &asker{
-		open: keeper.Open,
-		silence: func(ctx context.Context, key string, d time.Duration, by, why string) error {
-			_, err := keeper.Silence(ctx, key, d, by, why)
-			return err
-		},
-		store: busAsked{conn: conn},
-		publish: func(ctx context.Context, subject string, body []byte, id string) error {
-			_, err := js.Publish(ctx, subject, body, jetstream.WithMsgID(id))
-			return err
-		},
-		call: callAction(conn),
-		// A proposed settings layer is set by this controller itself on the warrant (novox/hq ADR 0277).
-		setLayer: setLayerIn(open),
-		record: func(ctx context.Context, act link.HandAct) error {
-			_, err := link.RecordHandAct(ctx, conn, act)
-			return err
-		},
-		routerRecord: routerRecordOf(conn, open.inventory),
-		routerHere:   routerHereIn(open.inventory),
-		grantHeld:    grantHeldIn(open, conn),
-		channels:     channelsIn(open.inventory),
-		raise: func(ctx context.Context, obs []conditions.Observation) error {
-			return keeper.Reconcile(ctx, sourceAsker, obs)
-		},
-		now:  time.Now,
-		logf: func(format string, args ...any) { fmt.Printf(format+"\n", args...) },
-	}
-}

cmd/mesh-controller/awaiting_push_test.go

@@ -1,281 +0,0 @@
-package main
-
-import (
-	"errors"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/overlay"
-)
-
-// Between `assign` and `push` a module's own secrets are not made yet: the push makes them. D1 composed
-// the machine's declaration without making anything, failed on the missing secret, and raised an urgent
-// "nothing can be sent to <machine>" — seen live on 2026-10-06, a desktop notification for a machine
-// the next push sent to without a word (novox/hq issue 275). D1 now composes as the push would, with a
-// stand-in for what the push makes: pending, not broken, and said only past a bound, as a warning.
-
-// aKeeper is a module with an own secret the mesh makes — a backup repository's password.
-func aKeeper() catalogue.Manifest {
-	return catalogue.Manifest{Module: "keeper", Version: "1",
-		OwnSecrets: catalogue.OwnSecrets{"repository": {Path: "/var/lib/mesh/keeper/repository"}},
-		Resources: []map[string]any{
-			{"id": "state", "type": "directory", "path": "/var/lib/mesh/keeper", "mode": "0700"},
-		}}
-}
-
-// pushedBy records a send to a machine as a push does — composed on the send path, so its own secrets
-// are made — without a bus to carry it.
-func pushedBy(t *testing.T, open *stores, node string) string {
-	t.Helper()
-	ctx := t.Context()
-	plan, settings, err := planFor(ctx, open, node)
-	if err != nil {
-		t.Fatal(err)
-	}
-	declared, err := declarationFor(ctx, open, node, plan, settings)
-	if err != nil {
-		t.Fatal(err)
-	}
-	body, err := declared.Body()
-	if err != nil {
-		t.Fatal(err)
-	}
-	record, err := open.inventory.NodeByName(ctx, node)
-	if err != nil {
-		t.Fatal(err)
-	}
-	digest := digestOf(body)
-	if err := open.inventory.RecordSent(ctx, record.ID, digest, declared.Builds); err != nil {
-		t.Fatal(err)
-	}
-	return digest
-}
-
-// pushedAndApplied is pushedBy, and the machine reporting it applied that declaration.
-func pushedAndApplied(t *testing.T, open *stores, node string) {
-	t.Helper()
-	digest := pushedBy(t, open, node)
-	record, err := open.inventory.NodeByName(t.Context(), node)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if _, err := open.inventory.RecordDoing(t.Context(), record.ID, inventory.Doing{
-		Outcome: inventory.OutcomeApplied, Declared: digest}); err != nil {
-		t.Fatal(err)
-	}
-}
-
-// d1 runs D1 once.
-func d1(t *testing.T, open *stores) []conditions.Observation {
-	t.Helper()
-	got, err := probeDeclarations(t.Context(), &doctor{open: open})
-	if err != nil {
-		t.Fatal(err)
-	}
-	return got
-}
-
-// **THE WINDOW, REPRODUCED**: assigned and not pushed, a module whose own secret the push makes is
-// waiting, not uncomposable; past the bound it is a warning naming what the push makes; pushed, nothing.
-func TestAModuleAssignedAndNotPushedIsAwaitingAPushNotUncomposable(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	register(t, open, aKeeper())
-	pushedBy(t, open, "laptop") // the machine was pushed before; then the module is assigned
-	if _, err := assign(ctx, open, "laptop", "keeper"); err != nil {
-		t.Fatal(err)
-	}
-
-	// The read the rest of the mesh asks still refuses it, with the composer's typed error: nothing
-	// can be compared about a secret that does not exist (status), and nothing here string-matches.
-	plan, settings, err := planFor(ctx, open, "laptop")
-	if err != nil {
-		t.Fatal(err)
-	}
-	gens, err := generators(ctx, open)
-	if err != nil {
-		t.Fatal(err)
-	}
-	_, err = declarationWith(ctx, open, "laptop", plan, settings, gens, Reading)
-	var notMade *catalogue.NotMadeError
-	if !errors.As(err, &notMade) || notMade.Module != "keeper" || notMade.Name != "repository" {
-		t.Fatalf("a read composition did not say which secret is not made, typed: %v", err)
-	}
-	// Foreseen, it composes, names what the push makes, and made nothing.
-	foreseen, err := declarationWith(ctx, open, "laptop", plan, settings, gens, Foreseeing)
-	if err != nil || len(foreseen.foreseen) != 1 || foreseen.foreseen[0] != "keeper/repository" {
-		t.Fatalf("foreseen: %v %v", foreseen.foreseen, err)
-	}
-	if _, held, err := open.inventory.ModuleSecretIfIssued(ctx, "laptop", "keeper", "repository"); err != nil || held {
-		t.Fatalf("asking ahead of the push made the secret (held %v, %v)", held, err)
-	}
-
-	// Within the bound: nothing at all — no urgent, no warning, nobody notified.
-	if got := d1(t, open); len(got) != 0 {
-		t.Fatalf("a machine waiting for a push raised %+v", got)
-	}
-
-	// Past the bound: a warning, not urgent, saying what the push will make.
-	before := awaitingPushBound
-	awaitingPushBound = -time.Minute
-	t.Cleanup(func() { awaitingPushBound = before })
-	got := d1(t, open)
-	if len(got) != 1 || got[0].Key() != "machine.laptop.awaiting-push" || got[0].Severity != conditions.Warning ||
-		!strings.Contains(got[0].Summary, "keeper/repository") || !strings.Contains(got[0].Summary, "push laptop") {
-		t.Fatalf("a machine left un-pushed past the bound: %+v", got)
-	}
-
-	// Pushed: the secret is made and D1 says nothing.
-	pushedBy(t, open, "laptop")
-	if got := d1(t, open); len(got) != 0 {
-		t.Fatalf("a pushed machine still raised %+v", got)
-	}
-}
-
-// **A REAL FAILURE IS STILL URGENT**: a secret the push would be refused on is not one it will make.
-// A bus credential nobody issued (issue 203) fails the push, so D1 says it — urgent, in the push's words.
-func TestASecretThePushCannotMakeIsStillUncomposable(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	register(t, open, aTalker())
-	if _, err := assign(ctx, open, "laptop", "talker"); err != nil {
-		t.Fatal(err)
-	}
-	got := d1(t, open)
-	if len(got) != 1 || got[0].Key() != "machine.laptop.uncomposable" || got[0].Severity != conditions.Urgent ||
-		!strings.Contains(got[0].Summary, "module issue talker --node laptop") {
-		t.Fatalf("a push that will be refused was not said urgently: %+v", got)
-	}
-
-	// And a machine whose composition fails for anything else, with a secret waiting beside it, is
-	// uncomposable for that — the stand-in hides nothing.
-	register(t, open, aKeeper())
-	if _, err := assign(ctx, open, "anchor", "keeper"); err != nil {
-		t.Fatal(err)
-	}
-	one, two := rivals()
-	register(t, open, one)
-	register(t, open, two)
-	_, _ = assign(ctx, open, "anchor", "rival-one")
-	_, _ = assign(ctx, open, "anchor", "rival-two")
-	keys := map[string]conditions.Severity{}
-	for _, o := range d1(t, open) {
-		keys[o.Key()] = o.Severity
-	}
-	if keys["machine.anchor.uncomposable"] != conditions.Urgent {
-		t.Fatalf("a real failure beside a waiting secret: %v", keys)
-	}
-}
-
-// A given secret sealed to a key the machine no longer has is not the mesh's to make again: the push is
-// refused on it, so D1 is too.
-func TestAGivenSecretUnderAnOldKeyIsNotForeseen(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	register(t, open, aKeeper())
-	if _, err := assign(ctx, open, "laptop", "keeper"); err != nil {
-		t.Fatal(err)
-	}
-	if err := open.inventory.AcceptSecretForModule(ctx, "laptop", "keeper", "repository", "given"); err != nil {
-		t.Fatal(err)
-	}
-	record, err := open.inventory.NodeByName(ctx, "laptop")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := open.inventory.RecordSealingKey(ctx, record.ID, aPublicKey(t)); err != nil {
-		t.Fatal(err)
-	}
-	got := d1(t, open)
-	if len(got) != 1 || got[0].Key() != "machine.laptop.uncomposable" || !strings.Contains(got[0].Summary, "issue it again") {
-		t.Fatalf("a given secret under an old key: %+v", got)
-	}
-}
-
-// The bound is read from when the machine began waiting: the oldest assignment since its last send.
-func TestAMachineAwaitsAPushSinceItsOldestAssignmentSinceTheLastSend(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	register(t, open, aKeeper())
-	pushedBy(t, open, "laptop")
-	sent := time.Now()
-	since, err := open.inventory.AwaitingSince(ctx, "laptop")
-	if err != nil || since.After(sent) {
-		t.Fatalf("nothing assigned since the send: waiting since %v (%v), the send was before %v", since, err, sent)
-	}
-	if _, err := assign(ctx, open, "laptop", "keeper"); err != nil {
-		t.Fatal(err)
-	}
-	since, err = open.inventory.AwaitingSince(ctx, "laptop")
-	if err != nil || since.Before(sent.Add(-time.Second)) {
-		t.Fatalf("assigned after the send: waiting since %v (%v), not from the assignment", since, err)
-	}
-}
-
-// **D3 AND D13 WAIT FOR THE SEND**: a holder is expected to answer on a machine once the machine was sent
-// it and had time to report — never between assign and push.
-func TestAHolderIsExpectedOnlyOnceSentAndReported(t *testing.T) {
-	now := time.Now()
-	sent := now.Add(-time.Minute)
-	long := now.Add(-time.Hour)
-	cases := []struct {
-		name string
-		send lastSend
-		want bool
-	}{
-		{"never sent", lastSend{}, false},
-		{"sent without it", lastSend{sent: &long, current: true, carried: map[string]string{"other": "c"}}, false},
-		{"sent with it, not reported yet", lastSend{sent: &sent, carried: map[string]string{"keeper": "c"}}, false},
-		{"sent with it and reported", lastSend{sent: &sent, current: true, carried: map[string]string{"keeper": "c"}}, true},
-		{"sent with it long ago, never reported", lastSend{sent: &long, carried: map[string]string{"keeper": "c"}}, true},
-		{"sent before builds were kept", lastSend{sent: &long, current: true}, true},
-	}
-	for _, c := range cases {
-		if got := c.send.settled("keeper", now); got != c.want {
-			t.Errorf("%s: settled %v, want %v", c.name, got, c.want)
-		}
-	}
-}
-
-// And through the stores: assigned, not in the last send; pushed and reported, carried and settled.
-func TestALastSendIsReadFromTheSendAndTheReport(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	register(t, open, aKeeper())
-	pushedBy(t, open, "laptop")
-	if _, err := assign(ctx, open, "laptop", "keeper"); err != nil {
-		t.Fatal(err)
-	}
-	sends, err := readDeliveries(ctx, open.inventory)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if sends["laptop"].settled("keeper", time.Now()) {
-		t.Fatal("a holder assigned and not pushed is expected to answer")
-	}
-	if !sends["laptop"].settled(overlay.Name, time.Now().Add(time.Hour)) {
-		t.Fatal("a module the machine was sent long ago is not expected to answer")
-	}
-	pushedBy(t, open, "laptop")
-	sends, err = readDeliveries(ctx, open.inventory)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if sends["laptop"].settled("keeper", time.Now()) {
-		t.Fatal("pushed a moment ago and not reported, a holder is already expected")
-	}
-	if !sends["laptop"].settled("keeper", time.Now().Add(reportGrace+time.Minute)) {
-		t.Fatal("pushed past the grace, a holder is not expected")
-	}
-	if _, ok := sends["laptop"].carried["keeper"]; !ok {
-		t.Fatalf("the send's builds do not carry keeper: %v", sends["laptop"].carried)
-	}
-	pushedAndApplied(t, open, "laptop")
-	if sends, err = readDeliveries(ctx, open.inventory); err != nil || !sends["laptop"].settled("keeper", time.Now()) {
-		t.Fatalf("pushed and reported applied, a holder is not expected to answer (%v)", err)
-	}
-}

cmd/mesh-controller/batches_test.go

@@ -1,966 +0,0 @@
-package main
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"io"
-	"os"
-	"slices"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// The suite's tests of a merge, but for the merge window's own (this file's), plan the merge as it is heard: a
-// window of nothing closes at once, so a merge with no walk open is cut into its walk at once, as every merge
-// was planned before novox/hq ADR 0276. The window's tests set it through the controller's settings.
-func init() { mergeWindowDefault = 0 }
-
-// windowed is a mesh whose controller's settings give a merge window of 90 seconds and at most 10 minutes, as its
-// settings file says them, and
-// modules built from the catalogue (app, notes) and from three repositories of their own.
-func windowed(t *testing.T) *stores {
-	t.Helper()
-	open := aMesh(t)
-	ctx := t.Context()
-	inv := open.inventory
-	settings := t.TempDir() + "/merge-window.json"
-	if err := os.WriteFile(settings, []byte(`{"merge-window": "90s", "merge-window-at-most": "10m"}`), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	t.Setenv(mergeWindowFileVar, settings)
-	noGroups(t)
-	if err := inv.RegisterModule(ctx, catalogue.Manifest{Module: "mesh-controller", Version: "1"},
-		inventory.Source{Repository: "novox/mesh-controller", Seat: "git", Ref: "main", BuiltFrom: "c0",
-			Head: "c0"}); err != nil {
-		t.Fatal(err)
-	}
-	for _, m := range []struct{ module, repository, path string }{
-		{"app", "novox/mesh-catalog", "modules/app"},
-		{"notes", "novox/mesh-catalog", "modules/notes"},
-		{"one", "novox/one", ""},
-		{"two", "novox/two", ""},
-		{"three", "novox/three", ""},
-	} {
-		if err := inv.RegisterModule(ctx, catalogue.Manifest{Module: m.module, Version: "1"},
-			inventory.Source{Repository: m.repository, Seat: "git", Path: m.path, Ref: "main", BuiltFrom: "c0",
-				Head: "c0"}); err != nil {
-			t.Fatal(err)
-		}
-	}
-	return open
-}
-
-// t0 is the moment a test's clock starts: merges are dated by it, and heard after it.
-var t0 = time.Now().UTC().Truncate(time.Second)
-
-// catalogueMerge is a merge of the catalogue changing one module's directory, made at a moment, from a pull
-// request's head branch of its own, as the forge announces every merge. Whether its head names a delivery group
-// with a member still to merge is mesh-delivery's word, which windowed stubs as no group at all (noGroups); a test
-// whose merges wait for the window as a group's says so (groupsWaiting).
-func catalogueMerge(commit, module string, made time.Time) link.SourceMoved {
-	return link.SourceMoved{Owner: "novox", Repo: "mesh-catalog", Base: "main", Head: "pr/" + commit, Commit: commit,
-		MergedAt: made.Format(time.RFC3339Nano), Paths: []string{"modules/" + module + "/module.json"},
-		ModuleDirs: []string{"modules/" + module}, ModuleDirsSaid: true}
-}
-
-// repoMerge is a merge of a repository of one module's own, from a head branch of its own (catalogueMerge).
-func repoMerge(repo, commit string, made time.Time) link.SourceMoved {
-	return link.SourceMoved{Owner: "novox", Repo: repo, Base: "main", Head: "pr/" + commit, Commit: commit,
-		MergedAt: made.Format(time.RFC3339Nano), Paths: []string{"main.go"}}
-}
-
-// noGroups stubs mesh-delivery's word on groups for a test: no head names a group.
-func noGroups(t *testing.T) {
-	t.Helper()
-	was := deliveryGroupOf
-	deliveryGroupOf = func(context.Context, bool, string) ([]groupMember, bool, error) { return nil, false, nil }
-	t.Cleanup(func() { deliveryGroupOf = was })
-}
-
-// groupsWaiting stubs mesh-delivery's word on groups for a test: each head named is a group with a member of another
-// repository whose pull request is open (novox/elsewhere, ready), so a merge from it waits for the window (ADR 0306
-// decision 2); every other head names no group.
-func groupsWaiting(t *testing.T, heads ...string) {
-	t.Helper()
-	was := deliveryGroupOf
-	deliveryGroupOf = func(_ context.Context, _ bool, head string) ([]groupMember, bool, error) {
-		if slices.Contains(heads, head) {
-			return []groupMember{{Repository: "novox/elsewhere", State: "ready"}}, true, nil
-		}
-		return nil, false, nil
-	}
-	t.Cleanup(func() { deliveryGroupOf = was })
-}
-
-// everyHeadWaits stubs mesh-delivery's word on groups for a test whose merges each wait for the window as they did
-// before novox/hq ADR 0304: every head is a group with a member of another repository still to merge.
-func everyHeadWaits(t *testing.T) {
-	t.Helper()
-	was := deliveryGroupOf
-	deliveryGroupOf = func(context.Context, bool, string) ([]groupMember, bool, error) {
-		return []groupMember{{Repository: "novox/elsewhere", State: "ready"}}, true, nil
-	}
-	t.Cleanup(func() { deliveryGroupOf = was })
-}
-
-// fromHead is a merge from a head branch a test names: merges from one head are members of one delivery group,
-// related by it (novox/hq ADR 0304 decision 1), so they share a batch whatever else they share.
-func fromHead(m link.SourceMoved, head string) link.SourceMoved {
-	m.Head = head
-	return m
-}
-
-// lone is a merge that names no head: known to be no delivery group's, it waits for no window unless it is
-// related to a batch assembling (ADR 0304 decision 1).
-func lone(m link.SourceMoved) link.SourceMoved {
-	m.Head = ""
-	return m
-}
-
-// hear is a merge heard at a moment.
-func hear(t *testing.T, open *stores, m link.SourceMoved, now time.Time) {
-	t.Helper()
-	if err := (following{open: open}).hearMerge(t.Context(), m, now); err != nil {
-		t.Fatal(err)
-	}
-}
-
-// cutAt is the cutter looking at a moment.
-func cutAt(t *testing.T, open *stores, now time.Time) {
-	t.Helper()
-	if err := cutBatchesHeld(t.Context(), open, now); err != nil {
-		t.Fatal(err)
-	}
-}
-
-// walks is every plan record that is a walk, newest first, and the batches not yet cut.
-func walks(t *testing.T, open *stores) (walks, batches []inventory.Plan) {
-	t.Helper()
-	recent, err := open.inventory.RecentPlans(t.Context(), 50)
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, p := range recent {
-		if p.Batch() {
-			batches = append(batches, p)
-		} else {
-			walks = append(walks, p)
-		}
-	}
-	return walks, batches
-}
-
-// The replay of issue 362: two catalogue merges 18 seconds apart are one batch, cut once into one walk at the
-// later commit, which names both merges — the earlier carried by the later.
-func TestTwoMergesSecondsApartAreOneWalkAtTheLaterCommit(t *testing.T) {
-	open := windowed(t)
-	everyHeadWaits(t)
-	asked := asksWithPaths(t)
-	claude := catalogueMerge("553b7191claude", "app", t0)
-	dunst := catalogueMerge("48bda475dunst", "notes", t0.Add(17*time.Second))
-	hear(t, open, claude, t0.Add(time.Second))
-	hear(t, open, dunst, t0.Add(18*time.Second))
-	if ws, bs := walks(t, open); len(ws) != 0 || len(bs) != 1 {
-		t.Fatalf("within the window: %d walk(s), %d batch(es)", len(ws), len(bs))
-	}
-	cutAt(t, open, t0.Add(18*time.Second+89*time.Second))
-	if ws, _ := walks(t, open); len(ws) != 0 {
-		t.Fatalf("cut before the window closed: %+v", ws)
-	}
-	cutAt(t, open, t0.Add(18*time.Second+90*time.Second))
-	ws, bs := walks(t, open)
-	if len(ws) != 1 || len(bs) != 0 {
-		t.Fatalf("after the window: %d walk(s), %d batch(es)", len(ws), len(bs))
-	}
-	w := ws[0]
-	if w.Commit != dunst.Commit || len(w.Commits) != 1 || w.Commits[0].Commit != dunst.Commit {
-		t.Fatalf("the walk is at %s %+v, not the later commit", w.Commit, w.Commits)
-	}
-	for _, m := range []string{"app", "notes"} {
-		if _, in := w.Modules[m]; !in {
-			t.Fatalf("the walk does not build %s, which one of its merges moved: %v", m, w.Modules)
-		}
-	}
-	want := []inventory.PlanMerge{{Repository: "novox/mesh-catalog", Commit: claude.Commit, Carried: dunst.Commit},
-		{Repository: "novox/mesh-catalog", Commit: dunst.Commit}}
-	if w.Delivery == nil || !slices.EqualFunc(w.Delivery.Merges, want, sameMerge) {
-		t.Fatalf("the walk answers %+v, want %+v", w.Delivery, want)
-	}
-	if len(*asked) != 2 || (*asked)[0][2] != "main" || (*asked)[1][2] != "main" {
-		t.Fatalf("the walk did not ask its modules at the branch, which holds the commit it carries: %v", *asked)
-	}
-	// Heard again, as the bus may hand it over twice: never a second merge, nor a second walk.
-	hear(t, open, claude, t0.Add(5*time.Minute))
-	if ws, bs := walks(t, open); len(ws) != 1 || len(bs) != 0 {
-		t.Fatalf("a merge heard twice made %d walk(s) and %d batch(es)", len(ws), len(bs))
-	}
-}
-
-// Merges of three repositories in one window are one walk, one commit for each.
-func TestThreeRepositoriesInOneWindowAreOneWalk(t *testing.T) {
-	open := windowed(t)
-	groupsWaiting(t, "feat/three")
-	asksRecorded(t)
-	for i, r := range []string{"one", "two", "three"} {
-		hear(t, open, fromHead(repoMerge(r, "c-"+r, t0.Add(time.Duration(i)*20*time.Second)), "feat/three"),
-			t0.Add(time.Duration(i)*20*time.Second+time.Second))
-	}
-	cutAt(t, open, t0.Add(41*time.Second+90*time.Second))
-	ws, bs := walks(t, open)
-	if len(ws) != 1 || len(bs) != 0 {
-		t.Fatalf("%d walk(s), %d batch(es)", len(ws), len(bs))
-	}
-	w := ws[0]
-	if len(w.Commits) != 3 || len(w.Delivery.Merges) != 3 {
-		t.Fatalf("the walk carries %+v and answers %+v", w.Commits, w.Delivery.Merges)
-	}
-	for _, r := range []string{"one", "two", "three"} {
-		if w.CommitOf("novox/"+r) != "c-"+r {
-			t.Fatalf("the walk carries %s at %q", r, w.CommitOf("novox/"+r))
-		}
-		if _, in := w.Modules[r]; !in {
-			t.Fatalf("the walk does not build %s: %v", r, w.Modules)
-		}
-	}
-	// Each module's ask is recorded at its own repository's commit.
-	for _, r := range []string{"one", "two", "three"} {
-		q, found, err := open.inventory.BuildRequestByID(t.Context(), w.Modules[r].Build)
-		if err != nil || !found || q.Commit != "c-"+r {
-			t.Fatalf("%s's build was not recorded at its own commit: %+v %v %v", r, q, found, err)
-		}
-	}
-}
-
-// Each merge restarts the window: a merge at second 80 keeps the batch open until second 170; the window
-// closes at most ten minutes after its first merge however busy.
-func TestAMergeRestartsTheWindowAndTheMaximumClosesIt(t *testing.T) {
-	open := windowed(t)
-	groupsWaiting(t, "feat/both", "feat/busy")
-	asksWithPaths(t)
-	hear(t, open, fromHead(repoMerge("one", "c1", t0), "feat/both"), t0)
-	hear(t, open, fromHead(repoMerge("two", "c2", t0.Add(80*time.Second)), "feat/both"), t0.Add(80*time.Second))
-	cutAt(t, open, t0.Add(100*time.Second))
-	if ws, _ := walks(t, open); len(ws) != 0 {
-		t.Fatal("the window closed 90 seconds after its first merge, not after its last")
-	}
-	cutAt(t, open, t0.Add(170*time.Second))
-	if ws, _ := walks(t, open); len(ws) != 1 || len(ws[0].Commits) != 2 {
-		t.Fatalf("the window did not close 90 seconds after its last merge: %+v", ws)
-	}
-
-	busy := windowed(t)
-	groupsWaiting(t, "feat/both", "feat/busy")
-	asksWithPaths(t)
-	var last time.Time
-	for i := 0; i < 12; i++ {
-		last = t0.Add(time.Duration(i) * time.Minute)
-		repo := []string{"one", "two", "three"}[i%3]
-		hear(t, busy, fromHead(repoMerge(repo, "c"+string(rune('a'+i)), last), "feat/busy"), last)
-		if ws, _ := walks(t, busy); len(ws) > 0 {
-			if i != 10 {
-				t.Fatalf("a busy window closed at merge %d (minute %d), not at its maximum", i, i)
-			}
-			break
-		}
-	}
-	ws, _ := walks(t, busy)
-	if len(ws) != 1 {
-		t.Fatalf("ten minutes of merges a minute apart were never cut: %d walk(s)", len(ws))
-	}
-}
-
-// `plans` lists the batch being assembled first, in the operator's words: how long is left, when at the latest,
-// what is grouped, and that the plan is not yet calculated. It says so on the bus as plan-moved, too.
-func TestTheAssemblingBatchIsShown(t *testing.T) {
-	open := windowed(t)
-	groupsWaiting(t, "pr/553b7191claude")
-	asksWithPaths(t)
-	var said []inventory.Plan
-	was := inventory.PlanSaved
-	inventory.PlanSaved = func(_ *inventory.Inventory, p inventory.Plan) { said = append(said, p) }
-	t.Cleanup(func() { inventory.PlanSaved = was })
-	now := time.Now().UTC()
-	claude := catalogueMerge("553b7191claude", "app", now.Add(-20*time.Second))
-	claude.Number, claude.Title = 174, "claude-code: an agent proposes a section"
-	dunst := catalogueMerge("48bda475dunst", "notes", now.Add(-2*time.Second))
-	dunst.Number, dunst.Title = 175, "dunst: the font the operator chose"
-	hear(t, open, claude, now.Add(-19*time.Second))
-	hear(t, open, dunst, now.Add(-time.Second))
-	hear(t, open, fromHead(repoMerge("one", "a6bc0931one", now), dunst.Head), now)
-	out := captured(t, func() error { return plansCommand(t.Context(), nil) })
-	lines := strings.Split(out, "\n")
-	first := lines[0]
-	for _, want := range []string{"assembling: ", " s left (at the latest ", "grouped: novox/mesh-catalog@48bda475 " +
-		"(answers 553b7191), novox/one@a6bc0931; plan not yet calculated"} {
-		if !strings.Contains(first, want) {
-			t.Fatalf("plans' first line %q does not say %q", first, want)
-		}
-	}
-	// Under it, one line per repository: the pull request, what it answers, what it moves.
-	if len(lines) < 3 || strings.TrimSpace(lines[1]) != "mesh-catalog #175 dunst: the font the operator chose (answers "+
-		"#174 claude-code: an agent proposes a section) · app, notes" ||
-		strings.TrimSpace(lines[2]) != "one a6bc0931 · one" {
-		t.Fatalf("the grouped list reads %q", lines[1:4])
-	}
-	if len(said) == 0 || said[len(said)-1].State != inventory.PlanAssembling || said[len(said)-1].Delivery.Batch == nil ||
-		len(said[len(said)-1].Delivery.Merges) != 3 {
-		t.Fatalf("the batch was not said as assembling with its merges: %+v", said)
-	}
-}
-
-// captured is what a command printed.
-func captured(t *testing.T, run func() error) string {
-	t.Helper()
-	r, w, err := os.Pipe()
-	if err != nil {
-		t.Fatal(err)
-	}
-	was := os.Stdout
-	os.Stdout = w
-	runErr := run()
-	os.Stdout = was
-	_ = w.Close()
-	var b bytes.Buffer
-	_, _ = io.Copy(&b, r)
-	if runErr != nil {
-		t.Fatal(runErr)
-	}
-	return b.String()
-}
-
-// One walk at a time: a merge heard while a walk runs joins the next batch, which is cut when the walk ends;
-// the walk that started is never superseded.
-func TestAMergeDuringAWalkJoinsTheNextBatch(t *testing.T) {
-	open := windowed(t)
-	asksWithPaths(t)
-	hear(t, open, repoMerge("one", "c1", t0), t0)
-	cutAt(t, open, t0.Add(90*time.Second))
-	ws, _ := walks(t, open)
-	if len(ws) != 1 || !ws[0].Open() {
-		t.Fatalf("the first batch was not cut: %+v", ws)
-	}
-	first := ws[0]
-	hear(t, open, repoMerge("two", "c2", t0.Add(2*time.Minute)), t0.Add(2*time.Minute))
-	cutAt(t, open, t0.Add(5*time.Minute))
-	ws, bs := walks(t, open)
-	if len(ws) != 1 || len(bs) != 1 || bs[0].State != inventory.PlanQueued || bs[0].Delivery.Batch.Behind != first.ID {
-		t.Fatalf("the merge during the walk: %d walk(s), batches %+v", len(ws), bs)
-	}
-	if got, _ := open.inventory.PlanByID(t.Context(), first.ID); !got.Open() {
-		t.Fatalf("the started walk was %s by the next merge", got.State)
-	}
-	if !strings.HasPrefix(batchWords(bs[0], t0.Add(5*time.Minute)), "queued behind "+first.ID) {
-		t.Fatalf("a queued batch reads %q", batchWords(bs[0], t0.Add(5*time.Minute)))
-	}
-	first.State = inventory.PlanDone
-	if err := open.inventory.SavePlan(t.Context(), &first); err != nil {
-		t.Fatal(err)
-	}
-	cutAt(t, open, t0.Add(6*time.Minute))
-	ws, bs = walks(t, open)
-	if len(ws) != 2 || len(bs) != 0 || ws[0].Commit != "c2" {
-		t.Fatalf("the queued batch was not cut when the walk ended: %+v %+v", ws, bs)
-	}
-}
-
-// A walk waiting for its delivery's word is folded into the next batch's walk, which answers its merges; it
-// names the walk that took it over.
-func TestAWaitingWalkIsFoldedIntoTheNextBatch(t *testing.T) {
-	open := windowed(t)
-	asksWithPaths(t)
-	ctx := t.Context()
-	if err := open.inventory.RegisterModule(ctx, catalogue.Manifest{Module: "mesh-delivery", Version: "1",
-		Claims: []catalogue.Claim{{Name: catalogue.DeliverySeat, Scope: catalogue.ScopeMesh}}},
-		inventory.Source{Repository: "novox/mesh-catalog", Seat: "git", Path: "modules/mesh-delivery", Ref: "main",
-			BuiltFrom: "c0", Head: "c0"}); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := open.inventory.Assign(ctx, "anchor", "mesh-delivery"); err != nil {
-		t.Fatal(err)
-	}
-	hear(t, open, repoMerge("one", "c1", t0), t0)
-	cutAt(t, open, t0.Add(90*time.Second))
-	ws, _ := walks(t, open)
-	if len(ws) != 1 || !ws[0].Waiting() {
-		t.Fatalf("the walk does not wait for its word: %+v", ws)
-	}
-	waiting := ws[0]
-	hear(t, open, repoMerge("two", "c2", t0.Add(2*time.Minute)), t0.Add(2*time.Minute))
-	cutAt(t, open, t0.Add(2*time.Minute+90*time.Second))
-	ws, bs := walks(t, open)
-	if len(bs) != 0 || len(ws) != 2 {
-		t.Fatalf("%d walk(s), %d batch(es)", len(ws), len(bs))
-	}
-	folded, err := open.inventory.PlanByID(ctx, waiting.ID)
-	if err != nil {
-		t.Fatal(err)
-	}
-	newer := ws[0]
-	if folded.State != inventory.PlanSuperseded || folded.Delivery.TakenOverBy != newer.ID {
-		t.Fatalf("the waiting walk is %s, taken over by %q", folded.State, folded.Delivery.TakenOverBy)
-	}
-	if len(newer.Delivery.Merges) != 2 || newer.CommitOf("novox/one") != "c1" || newer.CommitOf("novox/two") != "c2" {
-		t.Fatalf("the newer walk answers %+v", newer.Delivery.Merges)
-	}
-	if _, in := newer.Modules["one"]; !in {
-		t.Fatalf("what the folded walk was to build is not built: %v", newer.Modules)
-	}
-}
-
-// A merge heard after a later merge of its branch was walked is answered by that walk when it builds all it
-// moves — named at once on a walk done — and joins the next batch when it does not.
-func TestALateMergeIsAnsweredByTheWalkOfTheLaterOne(t *testing.T) {
-	open := windowed(t)
-	everyHeadWaits(t)
-	asksWithPaths(t)
-	ctx := t.Context()
-	later := catalogueMerge("48bda475dunst", "notes", t0.Add(17*time.Second))
-	hear(t, open, later, t0.Add(18*time.Second))
-	cutAt(t, open, t0.Add(2*time.Minute))
-	ws, _ := walks(t, open)
-	w := ws[0]
-	w.State = inventory.PlanDone
-	if err := open.inventory.SavePlan(ctx, &w); err != nil {
-		t.Fatal(err)
-	}
-	// Moves only notes, which the done walk built from the branch after it: answered there, at once.
-	hear(t, open, catalogueMerge("553b7191early", "notes", t0), t0.Add(15*time.Minute))
-	got, _ := open.inventory.PlanByID(ctx, w.ID)
-	if got.State != inventory.PlanDone || len(got.Delivery.Merges) != 2 ||
-		!sameMerge(got.Delivery.Merges[0], inventory.PlanMerge{Repository: "novox/mesh-catalog", Commit: "553b7191early",
-			Carried: later.Commit}) {
-		t.Fatalf("the late merge is not named by the walk that carried it: %+v", got.Delivery.Merges)
-	}
-	// Moves app, which that walk never built: the next batch walks it.
-	hear(t, open, catalogueMerge("1111aaaaapp", "app", t0.Add(time.Second)), t0.Add(16*time.Minute))
-	_, bs := walks(t, open)
-	if len(bs) != 1 || bs[0].Delivery.Merges[0].Commit != "1111aaaaapp" {
-		t.Fatalf("a late merge moving what the walk never built did not join the next batch: %+v", bs)
-	}
-}
-
-// A failed walk marks nothing delivered: its earlier merges are walked alone, on their own commit, the newest
-// first; the first delivered answers the older ones, and the search stops.
-func TestAFailedWalkWalksItsEarlierMergesAlone(t *testing.T) {
-	open := windowed(t)
-	everyHeadWaits(t)
-	asked := asksWithPaths(t)
-	ctx := t.Context()
-	// Made before the cut marks their modules seen, as merges are: walked again, they are news all the same.
-	oldest := catalogueMerge("aaaa0001", "app", t0.Add(-3*time.Minute))
-	middle := catalogueMerge("bbbb0002", "app", t0.Add(-3*time.Minute+10*time.Second))
-	newest := catalogueMerge("cccc0003", "notes", t0.Add(-3*time.Minute+20*time.Second))
-	for i, m := range []link.SourceMoved{oldest, middle, newest} {
-		hear(t, open, m, t0.Add(time.Duration(i)*10*time.Second+time.Second))
-	}
-	cutAt(t, open, t0.Add(2*time.Minute))
-	ws, _ := walks(t, open)
-	failed := ws[0]
-	failed.State, failed.Note = inventory.PlanFailed, "notes failed to build in tier 0"
-	if err := open.inventory.SavePlan(ctx, &failed); err != nil {
-		t.Fatal(err)
-	}
-	cutAt(t, open, t0.Add(3*time.Minute))
-	got, _ := open.inventory.PlanByID(ctx, failed.ID)
-	if got.State != inventory.PlanFailed || len(got.Delivery.Merges) != 3 {
-		t.Fatalf("the failed walk's record changed: %s %+v", got.State, got.Delivery.Merges)
-	}
-	ws, _ = walks(t, open)
-	alone := ws[0]
-	if alone.ID == failed.ID || alone.Commit != middle.Commit || len(alone.Delivery.Merges) != 1 ||
-		!sameMerge(alone.Delivery.Merges[0], inventory.PlanMerge{Repository: "novox/mesh-catalog", Commit: middle.Commit}) {
-		t.Fatalf("the newest earlier merge was not walked alone on its own commit: %+v", alone)
-	}
-	if _, in := alone.Modules["app"]; !in || (*asked)[len(*asked)-1] != [3]string{"novox/mesh-catalog", "modules/app",
-		middle.Commit} {
-		t.Fatalf("the merge walked alone does not build app at its own commit: %v, asked %v", alone.Modules, *asked)
-	}
-	// Retried, the failed walk would name merges the search answers now.
-	if _, err := retryPlan(ctx, open, failed.ID); err == nil || !strings.Contains(err.Error(), "walked alone") {
-		t.Fatalf("a failed walk whose merges are searched was retried: %v", err)
-	}
-	alone.State = inventory.PlanDone
-	if err := open.inventory.SavePlan(ctx, &alone); err != nil {
-		t.Fatal(err)
-	}
-	cutAt(t, open, t0.Add(4*time.Minute))
-	ws, bs := walks(t, open)
-	if ws[0].ID != alone.ID || len(bs) != 0 {
-		t.Fatalf("the search went on after a merge was delivered: %+v", ws[0])
-	}
-	done, _ := open.inventory.PlanByID(ctx, alone.ID)
-	if len(done.Delivery.Merges) != 2 || !sameMerge(done.Delivery.Merges[0], inventory.PlanMerge{Repository: "novox/mesh-catalog",
-		Commit: oldest.Commit, Carried: middle.Commit}) {
-		t.Fatalf("the oldest merge is not answered by the walk that delivered the one after it: %+v", done.Delivery.Merges)
-	}
-	// A stopped walk starts no search: a person ended it.
-	hear(t, open, catalogueMerge("dddd0004", "app", t0.Add(5*time.Minute)), t0.Add(5*time.Minute))
-	hear(t, open, catalogueMerge("eeee0005", "notes", t0.Add(5*time.Minute+time.Second)), t0.Add(5*time.Minute+time.Second))
-	cutAt(t, open, t0.Add(8*time.Minute))
-	ws, _ = walks(t, open)
-	if _, err := stopWalk(ctx, open.inventory, ws[0].ID, "mesh-delivery for jochen", "not now"); err != nil {
-		t.Fatal(err)
-	}
-	cutAt(t, open, t0.Add(9*time.Minute))
-	if again, _ := walks(t, open); again[0].ID != ws[0].ID {
-		t.Fatalf("a stopped walk's earlier merge was walked alone: %+v", again[0])
-	}
-}
-
-// A delivery group's order holds inside the walk (ADR 0249 unchanged): merges of two repositories from one head
-// branch name, the node-engine's before the controller's, are tiered so; without the group, one tier.
-func TestAGroupsOrderBecomesTiersInsideTheWalk(t *testing.T) {
-	for _, grouped := range []bool{true, false} {
-		open := windowed(t)
-		everyHeadWaits(t)
-		asksWithPaths(t)
-		ctx := t.Context()
-		for _, m := range []string{"mesh-host"} {
-			if err := open.inventory.RegisterModule(ctx, catalogue.Manifest{Module: m, Version: "1"},
-				inventory.Source{Repository: "novox/" + m, Seat: "git", Ref: "main", BuiltFrom: "c0", Head: "c0"}); err != nil {
-				t.Fatal(err)
-			}
-		}
-		host := repoMerge("mesh-host", "h1", t0)
-		ctl := repoMerge("mesh-controller", "k1", t0.Add(time.Second))
-		host.Head, ctl.Head = "feat/together", "feat/together"
-		if !grouped {
-			ctl.Head = "feat/alone"
-		}
-		hear(t, open, ctl, t0.Add(2*time.Second))
-		hear(t, open, host, t0.Add(3*time.Second))
-		cutAt(t, open, t0.Add(2*time.Minute))
-		ws, _ := walks(t, open)
-		if len(ws) != 1 {
-			t.Fatalf("%d walks", len(ws))
-		}
-		tiers := ws[0].Tiers
-		if grouped {
-			if len(tiers) != 2 || !slices.Equal(tiers[0], []string{"mesh-host"}) ||
-				!slices.Equal(tiers[1], []string{"mesh-controller"}) {
-				t.Fatalf("the group's order is not the walk's tiers: %v", tiers)
-			}
-		} else if len(tiers) != 1 {
-			t.Fatalf("two merges of no group were ordered: %v", tiers)
-		}
-	}
-}
-
-// A restarted controller resumes the window where it stood: the batch, its merges and their times are in the
-// store, a merge handed over again is not doubled, and the batch is cut when its window closes.
-func TestABatchSurvivesARestart(t *testing.T) {
-	open := windowed(t)
-	groupsWaiting(t, "feat/both")
-	asksWithPaths(t)
-	hear(t, open, fromHead(repoMerge("one", "c1", t0), "feat/both"), t0)
-	hear(t, open, fromHead(repoMerge("two", "c2", t0.Add(30*time.Second)), "feat/both"), t0.Add(30*time.Second))
-
-	// A new controller: nothing of the first one's but the store.
-	again, err := openStores(t.Context())
-	if err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(again.Close)
-	hear(t, again, fromHead(repoMerge("one", "c1", t0), "feat/both"), t0.Add(60*time.Second)) // the bus hands it over again
-	cutAt(t, again, t0.Add(119*time.Second))
-	if ws, bs := walks(t, again); len(ws) != 0 || len(bs) != 1 || len(bs[0].Delivery.Merges) != 2 {
-		t.Fatalf("the restarted controller's batch: %d walk(s), %+v", len(ws), bs)
-	}
-	cutAt(t, again, t0.Add(120*time.Second))
-	ws, bs := walks(t, again)
-	if len(ws) != 1 || len(bs) != 0 || len(ws[0].Delivery.Merges) != 2 {
-		t.Fatalf("the restarted controller did not cut the batch at its window: %+v %+v", ws, bs)
-	}
-}
-
-// The window's settings reach the controller in its settings file, read at every look; one that says no
-// duration, or no file, is the default.
-func TestTheWindowIsTheControllersSetting(t *testing.T) {
-	file := t.TempDir() + "/merge-window.json"
-	t.Setenv(mergeWindowFileVar, file)
-	for _, c := range []struct {
-		content        string
-		window, atMost time.Duration
-	}{
-		{`{"merge-window": "60s", "merge-window-at-most": "5m"}`, time.Minute, 5 * time.Minute},
-		{`{"merge-window": 30, "merge-window-at-most": ""}`, 30 * time.Second, mergeWindowAtMostDefault},
-		{`{"merge-window": "soon"}`, mergeWindowDefault, mergeWindowAtMostDefault},
-	} {
-		if err := os.WriteFile(file, []byte(c.content), 0o600); err != nil {
-			t.Fatal(err)
-		}
-		if w, m := mergeWindowOf(); w != c.window || m != c.atMost {
-			t.Errorf("%s reads as %s and %s, want %s and %s", c.content, w, m, c.window, c.atMost)
-		}
-	}
-	t.Setenv(mergeWindowFileVar, file+".gone")
-	if w, m := mergeWindowOf(); w != mergeWindowDefault || m != mergeWindowAtMostDefault {
-		t.Errorf("no file reads as %s and %s", w, m)
-	}
-}
-
-// S16 names every merge a waiting walk answers, never one commit a supersession may have ended (issue 362).
-func TestAWaitingWalkNamesTheMergesItAnswers(t *testing.T) {
-	f := calm(t0)
-	f.waits = []waitFacts{{id: "plan-2", repository: "novox/mesh-catalog", commit: "48bda475dunst", awaits: "mesh-delivery",
-		since: t0.Add(-31 * time.Minute), merges: []inventory.PlanMerge{
-			{Repository: "novox/mesh-catalog", Commit: "553b7191claude", Carried: "48bda475dunst"},
-			{Repository: "novox/mesh-catalog", Commit: "48bda475dunst"}}}}
-	got := watchWaits(f)
-	if len(got) != 1 || !strings.Contains(got[0].Summary, "novox/mesh-catalog@553b7191") ||
-		!strings.Contains(got[0].Summary, "novox/mesh-catalog@48bda475") {
-		t.Fatalf("the waiting walk does not name both merges: %+v", got)
-	}
-}
-
-// A merge heard after a later merge of its branch was cut is named by that walk however its modules read since
-// the cut, in a repository of one module (review of this change); a walk that never built what it moves names
-// nothing, and the merge joins the next batch.
-func TestALateMergeOfAOneModuleRepositoryIsNamed(t *testing.T) {
-	open := windowed(t)
-	everyHeadWaits(t)
-	asksWithPaths(t)
-	ctx := t.Context()
-	c2 := repoMerge("one", "c2", t0.Add(-50*time.Second))
-	hear(t, open, c2, t0)
-	cutAt(t, open, t0.Add(2*time.Minute))
-	ws, _ := walks(t, open)
-	w := ws[0]
-	w.State = inventory.PlanDone
-	if err := open.inventory.SavePlan(ctx, &w); err != nil {
-		t.Fatal(err)
-	}
-	hear(t, open, repoMerge("one", "c1", t0.Add(-60*time.Second)), t0.Add(15*time.Minute))
-	got, _ := open.inventory.PlanByID(ctx, w.ID)
-	if len(got.Delivery.Merges) != 2 || !sameMerge(got.Delivery.Merges[0], inventory.PlanMerge{Repository: "novox/one",
-		Commit: "c1", Carried: "c2"}) {
-		t.Fatalf("the late merge was not named by the walk that carried it: %+v", got.Delivery.Merges)
-	}
-
-	// A walk of two that built only two: a late merge of one is not its to name.
-	hear(t, open, repoMerge("two", "d2", t0.Add(16*time.Minute)), t0.Add(16*time.Minute))
-	cutAt(t, open, t0.Add(18*time.Minute))
-	ws, _ = walks(t, open)
-	w = ws[0]
-	delete(w.Modules, "two")
-	w.State = inventory.PlanDone
-	if err := open.inventory.SavePlan(ctx, &w); err != nil {
-		t.Fatal(err)
-	}
-	hear(t, open, repoMerge("two", "d1", t0.Add(15*time.Minute)), t0.Add(20*time.Minute))
-	if got, _ := open.inventory.PlanByID(ctx, w.ID); len(got.Delivery.Merges) != 1 {
-		t.Fatalf("a walk that never built what the late merge moves named it: %+v", got.Delivery.Merges)
-	}
-	if _, bs := walks(t, open); len(bs) != 1 || bs[0].Delivery.Merges[0].Commit != "d1" {
-		t.Fatalf("the late merge did not join the next batch: %+v", bs)
-	}
-}
-
-// One walk at a time holds against the delivery's word too: a waiting walk let go beside a started one takes the
-// word and starts once that one ended, asking nothing before.
-func TestAWalkLetGoBesideAStartedOneStartsOnceItEnded(t *testing.T) {
-	open := windowed(t)
-	asked := asksWithPaths(t)
-	ctx := t.Context()
-	hear(t, open, repoMerge("one", "c1", t0), t0)
-	cutAt(t, open, t0.Add(2*time.Minute))
-	started, _ := walks(t, open)
-	waiting := inventory.Plan{ID: "plan-waiting", Repository: "novox/two", Branch: "main", Commit: "d1", Created: t0,
-		State: inventory.PlanBuilding, Tiers: [][]string{{"two"}}, Modules: map[string]*inventory.PlanModule{"two": {}},
-		Delivery: &inventory.PlanDelivery{Awaits: catalogue.DeliverySeat}}
-	if err := open.inventory.SavePlan(ctx, &waiting); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := letGo(ctx, open.inventory, waiting.ID, catalogue.DeliverySeat, "its turn"); err != nil {
-		t.Fatalf("the word was refused beside %s: %v", started[0].ID, err)
-	}
-	before := len(*asked)
-	advanceHeld(ctx, open)
-	got, _ := open.inventory.PlanByID(ctx, waiting.ID)
-	if len(*asked) != before || !strings.Contains(got.Note, "starts once "+started[0].ID) {
-		t.Fatalf("a walk let go beside a started one asked (%d → %d) or does not say it waits: %q", before, len(*asked), got.Note)
-	}
-	// Read as a wait, an hour on: its note on the line, never LATE, and no tier of it late for S3.
-	later := time.Now().Add(time.Hour)
-	if line := planLine(got, later); !strings.Contains(line, "starts once "+started[0].ID) || strings.Contains(line, "LATE") {
-		t.Fatalf("a deferred walk reads %q", line)
-	}
-	facts, _, err := gatherPlans(ctx, open.inventory, later, nil)
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, f := range facts {
-		if f.id == got.ID {
-			t.Fatalf("a deferred walk is watched as a tier running late: %+v", f)
-		}
-	}
-	done := started[0]
-	done.State = inventory.PlanDone
-	if err := open.inventory.SavePlan(ctx, &done); err != nil {
-		t.Fatal(err)
-	}
-	advanceHeld(ctx, open)
-	if len(*asked) != before+1 {
-		t.Fatalf("the walk did not start once the started one ended: asked %v", *asked)
-	}
-}
-
-// A file a merge of the batch removed and a later one brought back is not removed; one removed last is.
-func TestARemovedFileIsTheLastMergesWord(t *testing.T) {
-	ev := func(commit string, paths, removed []string) inventory.BatchedMerge {
-		m := link.SourceMoved{Owner: "novox", Repo: "one", Base: "main", Commit: commit, Paths: paths, Removed: removed}
-		b, _ := json.Marshal(m)
-		return inventory.BatchedMerge{Repository: "novox/one", Branch: "main", Commit: commit, Event: b,
-			Merged: t0.Add(time.Duration(len(commit)) * time.Second)}
-	}
-	got := combinedMerges([]inventory.BatchedMerge{
-		ev("a", []string{"x/module.json", "y/module.json"}, []string{"x/module.json", "y/module.json"}),
-		ev("bb", []string{"x/module.json"}, nil),
-		ev("ccc", []string{"z.go"}, nil)})
-	if len(got) != 1 || got[0].Commit != "ccc" || !slices.Equal(got[0].Removed, []string{"y/module.json"}) ||
-		len(got[0].Paths) != 3 {
-		t.Fatalf("combined as %+v", got)
-	}
-}
-
-// The catch-up hands over what the bus lost after its branch's later merges were cut, and the record keeps it:
-// an earlier merge is named by the walk that carried it; a merge made before a cut and heard after it, which
-// no later merge carries, joins the next batch — neither reads as history and is dropped (review of this change).
-func TestTheCatchUpKeepsWhatACutMadeHistory(t *testing.T) {
-	open := windowed(t)
-	asksWithPaths(t)
-	ctx := t.Context()
-	base := time.Now().UTC().Add(-time.Hour).Truncate(time.Second)
-	hear(t, open, repoMerge("one", "c2", base.Add(10*time.Second)), base.Add(11*time.Second))
-	cutAt(t, open, base.Add(2*time.Minute))
-	ws, _ := walks(t, open)
-	w := ws[0]
-	w.State = inventory.PlanDone
-	if err := open.inventory.SavePlan(ctx, &w); err != nil {
-		t.Fatal(err)
-	}
-	lost := []link.AnnouncedMerge{
-		{SourceMoved: repoMerge("one", "c1", base), At: base.Add(time.Second)},
-		{SourceMoved: repoMerge("one", "c3lost", base.Add(20*time.Second)), At: base.Add(21 * time.Second)},
-	}
-	catalogued := func(ctx context.Context) ([]inventory.Entry, map[string][]inventory.ReadRepository, error) {
-		entries, err := open.inventory.Catalogued(ctx)
-		if err != nil {
-			return nil, nil, err
-		}
-		read, err := readForPlanning(ctx, open.inventory)
-		return entries, read, err
-	}
-	if err := catchUpOnMerges(ctx, time.Now(), unheardMerges{announcedList(lost), open.inventory}, catalogued,
-		(following{open}).SourceMoved, t.Logf); err != nil {
-		t.Fatal(err)
-	}
-	got, _ := open.inventory.PlanByID(ctx, w.ID)
-	if len(got.Delivery.Merges) != 2 || !sameMerge(got.Delivery.Merges[0], inventory.PlanMerge{Repository: "novox/one",
-		Commit: "c1", Carried: "c2"}) {
-		t.Fatalf("the earlier merge the catch-up handed over is not named by the walk that carried it: %+v",
-			got.Delivery.Merges)
-	}
-	if _, kept, err := open.inventory.MergeOf(ctx, "novox/one", "c3lost"); err != nil || !kept {
-		t.Fatalf("the merge made before the cut and heard after it was dropped: %v %v", kept, err)
-	}
-}
-
-// A merge on the controller's own path never shares a batch with one that waits for mesh-delivery's word
-// (decided during the build, 2026-10-10): the two are batches of their own, cut one after the other; a walk on
-// the own path folds no waiting catalogue walk but batches its merges again behind it; the catalogue's walk
-// still waits for the word, so no catalogue delivery skips its turn.
-func TestAMergeOnTheControllersPathNeverSharesABatch(t *testing.T) {
-	open := windowed(t)
-	everyHeadWaits(t)
-	asked := asksWithPaths(t)
-	ctx := t.Context()
-	if err := open.inventory.RegisterModule(ctx, catalogue.Manifest{Module: "mesh-delivery", Version: "1",
-		Claims: []catalogue.Claim{{Name: catalogue.DeliverySeat, Scope: catalogue.ScopeMesh}}},
-		inventory.Source{Repository: "novox/mesh-catalog", Seat: "git", Path: "modules/mesh-delivery", Ref: "main",
-			BuiltFrom: "c0", Head: "c0"}); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := open.inventory.Assign(ctx, "anchor", "mesh-delivery"); err != nil {
-		t.Fatal(err)
-	}
-	hear(t, open, catalogueMerge("aaaa0001", "app", t0), t0)
-	hear(t, open, repoMerge("mesh-controller", "k1", t0.Add(10*time.Second)), t0.Add(10*time.Second))
-	hear(t, open, catalogueMerge("bbbb0002", "notes", t0.Add(20*time.Second)), t0.Add(20*time.Second))
-	_, bs := walks(t, open)
-	var ownBatch, catalogueBatch inventory.Plan
-	for _, b := range bs {
-		if b.OwnPath() {
-			ownBatch = b
-		} else {
-			catalogueBatch = b
-		}
-	}
-	if len(bs) != 2 || ownBatch.ID == "" || catalogueBatch.ID == "" || len(catalogueBatch.Delivery.Merges) != 2 ||
-		len(ownBatch.Delivery.Merges) != 1 {
-		t.Fatalf("a controller merge and two catalogue merges in one window: %+v", bs)
-	}
-	if !strings.Contains(batchWords(ownBatch, t0.Add(30*time.Second)), "own path") {
-		t.Fatalf("the own-path batch does not say so: %q", batchWords(ownBatch, t0.Add(30*time.Second)))
-	}
-	// Both windows closed, the controller's batch is cut first and starts; the catalogue batch queues behind it,
-	// is cut when the controller's walk ended, and waits for its word with both merges.
-	cutAt(t, open, t0.Add(2*time.Minute))
-	ws, bs := walks(t, open)
-	if len(ws) != 1 || ws[0].Waiting() || ws[0].CommitOf("novox/mesh-controller") != "k1" {
-		t.Fatalf("the controller's batch was not cut first into a started walk: %+v", ws)
-	}
-	ownWalk := ws[0]
-	for _, m := range []string{"app", "notes"} {
-		if _, in := ownWalk.Modules[m]; in {
-			t.Fatalf("the controller's walk builds %s, a catalogue module: it skipped its turn", m)
-		}
-	}
-	if len(bs) != 1 || bs[0].State != inventory.PlanQueued || bs[0].Delivery.Batch.Behind != ownWalk.ID || bs[0].OwnPath() {
-		t.Fatalf("the catalogue batch does not queue behind the controller's walk: %+v", bs)
-	}
-	ownWalk.State = inventory.PlanDone
-	if err := open.inventory.SavePlan(ctx, &ownWalk); err != nil {
-		t.Fatal(err)
-	}
-	cutAt(t, open, t0.Add(3*time.Minute))
-	ws, bs = walks(t, open)
-	if len(bs) != 0 || ws[0].ID != catalogueBatch.ID || !ws[0].Waiting() || len(ws[0].Delivery.Merges) != 2 {
-		t.Fatalf("the catalogue batch was not cut into a waiting walk once the controller's ended: %+v %+v", ws, bs)
-	}
-	for _, m := range []string{"app", "notes"} {
-		if _, in := ws[0].Modules[m]; !in {
-			t.Fatalf("the catalogue walk does not build %s: %v", m, ws[0].Modules)
-		}
-	}
-	for _, a := range *asked {
-		if a[1] == "modules/app" || a[1] == "modules/notes" {
-			t.Fatalf("a catalogue module was asked without the word: %v", *asked)
-		}
-	}
-
-	// A catalogue walk waiting for its word when an own-path batch is cut keeps waiting beside the own-path
-	// walk, is not folded into it, and its word is taken meanwhile: it starts once the own-path walk ended.
-	catalogueWalk := ws[0]
-	hear(t, open, repoMerge("mesh-controller", "k2", t0.Add(4*time.Minute)), t0.Add(4*time.Minute))
-	cutAt(t, open, t0.Add(6*time.Minute))
-	ws, _ = walks(t, open)
-	kept, _ := open.inventory.PlanByID(ctx, catalogueWalk.ID)
-	if !kept.Waiting() || ws[0].CommitOf("novox/mesh-controller") != "k2" || ws[0].Waiting() {
-		t.Fatalf("the waiting catalogue walk was not kept waiting beside the controller's walk: %s %+v", kept.State, ws)
-	}
-	if _, in := ws[0].Modules["app"]; in {
-		t.Fatalf("the controller's walk folded the waiting catalogue walk in: %v", ws[0].Modules)
-	}
-	if _, err := letGo(ctx, open.inventory, catalogueWalk.ID, catalogue.DeliverySeat, "its turn"); err != nil {
-		t.Fatal(err)
-	}
-	before := len(*asked)
-	advanceHeld(ctx, open)
-	if len(*asked) != before {
-		t.Fatalf("the catalogue walk started beside the controller's: asked %v", (*asked)[before:])
-	}
-	own2 := ws[0]
-	own2.State = inventory.PlanDone
-	if err := open.inventory.SavePlan(ctx, &own2); err != nil {
-		t.Fatal(err)
-	}
-	advanceHeld(ctx, open)
-	if len(*asked) < before+1 || (*asked)[before][1] != "modules/app" {
-		t.Fatalf("the catalogue walk did not start once the controller's ended: %v", (*asked)[before:])
-	}
-}
-
-// `plans` names a walk by what it moves (asked by the operator, 2026-10-10): the repository's pull request and
-// title, the modules it moves and the machines running them, then the state words; a record naming no pull
-// request is named by its commit, and a title is cut at fifty runes.
-func TestAPlanLineNamesWhatItMoves(t *testing.T) {
-	now := time.Date(2026, 10, 10, 12, 0, 0, 0, time.UTC)
-	p := inventory.Plan{ID: "plan-1", Repository: "novox/mesh-catalog", Branch: "main", Commit: "c1c1c1c1c1",
-		State: inventory.PlanBuilding, Tiers: [][]string{{"messenger", "telegram"}}, TierEntered: now.Add(-2 * time.Minute),
-		Modules: map[string]*inventory.PlanModule{"messenger": {State: "asked"}, "telegram": {State: "asked"}},
-		Commits: []inventory.PlanCommit{{Repository: "novox/mesh-catalog", Branch: "main", Commit: "c1c1c1c1c1"}},
-		Delivery: &inventory.PlanDelivery{Merges: []inventory.PlanMerge{{Repository: "novox/mesh-catalog",
-			Commit: "c1c1c1c1c1", Number: 175, Title: "a tap shows its outcome", Moves: []string{"telegram", "messenger"}}}}}
-	running := func(module string) []string {
-		if module == "messenger" || module == "telegram" {
-			return []string{"novox"}
-		}
-		return nil
-	}
-	if got, want := planLineOn(p, now, pauseView{}, tierAtLeast, running),
-		"mesh-catalog #175 a tap shows its outcome · messenger, telegram → novox · tier 1 of 1, building for 2m0s"; got != want {
-		t.Fatalf("the line reads %q, want %q", got, want)
-	}
-	if got := planLine(p, now); !strings.HasPrefix(got, "mesh-catalog #175 a tap shows its outcome · messenger, telegram · tier") {
-		t.Fatalf("without the machines the line reads %q", got)
-	}
-	old := p
-	old.Commits, old.Delivery = nil, nil
-	if got := planLine(old, now); !strings.HasPrefix(got, "mesh-catalog c1c1c1c1 · tier 1 of 1") {
-		t.Fatalf("a record naming no pull request reads %q", got)
-	}
-	long := p
-	long.Delivery.Merges[0].Title = strings.Repeat("abcdefghij", 6)
-	if got := planHeadline(long, nil); !strings.Contains(got, "#175 "+strings.Repeat("abcdefghij", 4)+"abcdefghi…") {
-		t.Fatalf("a long title is not cut at fifty runes: %q", got)
-	}
-}
-
-// sameMerge compares what a walk names of a merge: its repository, commit and the commit carrying it.
-func sameMerge(a, b inventory.PlanMerge) bool {
-	return a.Repository == b.Repository && a.Commit == b.Commit && a.Carried == b.Carried
-}
-
-// A catalogue merge heard after a later merge of its branch was walked without the word (a merge that touched
-// the bus too, on the controller's own path) is not answered by that walk while the delivery seat has a holder:
-// its delivery would skip its turn. It joins the next catalogue batch.
-func TestALateCatalogueMergeIsNotAnsweredByAnOwnPathWalk(t *testing.T) {
-	open := windowed(t)
-	everyHeadWaits(t)
-	asksWithPaths(t)
-	ctx := t.Context()
-	for _, m := range []struct {
-		module string
-		claims []catalogue.Claim
-	}{
-		{"nats", nil},
-		{"mesh-delivery", []catalogue.Claim{{Name: catalogue.DeliverySeat, Scope: catalogue.ScopeMesh}}},
-	} {
-		if err := open.inventory.RegisterModule(ctx, catalogue.Manifest{Module: m.module, Version: "1", Claims: m.claims},
-			inventory.Source{Repository: "novox/mesh-catalog", Seat: "git", Path: "modules/" + m.module, Ref: "main",
-				BuiltFrom: "c0", Head: "c0"}); err != nil {
-			t.Fatal(err)
-		}
-	}
-	if _, err := open.inventory.Assign(ctx, "anchor", "mesh-delivery"); err != nil {
-		t.Fatal(err)
-	}
-	mixed := link.SourceMoved{Owner: "novox", Repo: "mesh-catalog", Base: "main", Commit: "m1xed", MergedAt: t0.Format(time.RFC3339Nano),
-		Paths: []string{"modules/nats/module.json", "modules/app/module.json"}, ModuleDirs: []string{"modules/nats", "modules/app"},
-		ModuleDirsSaid: true}
-	hear(t, open, mixed, t0.Add(time.Second))
-	cutAt(t, open, t0.Add(2*time.Minute))
-	ws, _ := walks(t, open)
-	if len(ws) != 1 || ws[0].Waiting() {
-		t.Fatalf("the mixed merge's walk waited, or was not cut: %+v", ws)
-	}
-	done := ws[0]
-	done.State = inventory.PlanDone
-	if err := open.inventory.SavePlan(ctx, &done); err != nil {
-		t.Fatal(err)
-	}
-	hear(t, open, catalogueMerge("ear1ier", "app", t0.Add(-30*time.Second)), t0.Add(3*time.Minute))
-	got, _ := open.inventory.PlanByID(ctx, done.ID)
-	_, bs := walks(t, open)
-	if len(got.Delivery.Merges) != 1 || len(bs) != 1 || bs[0].OwnPath() || bs[0].Delivery.Merges[0].Commit != "ear1ier" {
-		t.Fatalf("the late catalogue merge was answered by the own-path walk (%+v) rather than the next catalogue batch (%+v)",
-			got.Delivery.Merges, bs)
-	}
-}

cmd/mesh-controller/batches_watch.go

@@ -1,107 +0,0 @@
-package main
-
-import (
-	"context"
-	"fmt"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// **Every wait of a batch has a bound and a condition** (novox/hq ADR 0276 decision 9): a batch still
-// assembling a minute past its maximum while no walk is open is a cut the controller failed to make (S18),
-// and a batch waiting behind an open walk longer than that walk's bound waits on a walk gone wrong (S19).
-
-// The kinds S18 and S19 raise.
-const (
-	kindBatchNotCut     = "batch-not-cut"
-	kindBatchBehindWalk = "batch-behind-walk"
-)
-
-// batchFacts is one batch not yet cut, as the watchdogs read it.
-type batchFacts struct {
-	id, state, grouped string
-	// atMost is when its window closes at the latest; closed when it closed.
-	atMost, closed time.Time
-	// behind is the open walk it waits behind, and walkBound that walk's bound: a tier's bound for each of its
-	// tiers.
-	behind    string
-	walkBound time.Duration
-}
-
-// gatherBatches is every batch not yet cut, with the bound of the walk it waits behind.
-func gatherBatches(ctx context.Context, inv *inventory.Inventory, now time.Time) ([]batchFacts, error) {
-	batches, err := inv.Batches(ctx)
-	if err != nil || len(batches) == 0 {
-		return nil, err
-	}
-	bounds, err := measuredTierBounds(ctx, inv, now)
-	if err != nil {
-		return nil, err
-	}
-	var out []batchFacts
-	for _, b := range batches {
-		f := batchFacts{id: b.ID, state: b.State, grouped: groupedWords(b)}
-		if w := b.Delivery; w != nil && w.Batch != nil {
-			f.atMost, f.closed, f.behind = w.Batch.AtMost, w.Batch.ClosesAt, w.Batch.Behind
-			if f.atMost.Before(f.closed) {
-				f.closed = f.atMost
-			}
-			if w.Batch.CutAtOnce && !b.Created.IsZero() {
-				// Its window closed when it was made, which is its latest too (ADR 0304 decision 1).
-				f.atMost, f.closed = b.Created, b.Created
-			}
-		}
-		if f.behind != "" {
-			if walk, err := inv.PlanByID(ctx, f.behind); err == nil {
-				f.walkBound = bounds.of(walk.Repository) * time.Duration(max(1, len(walk.Tiers)))
-			}
-		}
-		out = append(out, f)
-	}
-	return out, nil
-}
-
-// watchBatchesNotCut is S18: a batch still assembling a minute past its maximum, while no walk is open.
-func watchBatchesNotCut(f *signalFacts) []conditions.Observation {
-	var out []conditions.Observation
-	for _, b := range f.batches {
-		if b.state != inventory.PlanAssembling || b.atMost.IsZero() || f.now.Sub(b.atMost) <= batchLateAfter {
-			continue
-		}
-		late := f.now.Sub(b.atMost)
-		out = append(out, conditions.Observation{Scope: conditions.ScopePlan, ID: b.id, Kind: kindBatchNotCut,
-			Severity: conditions.Warning,
-			Summary: fmt.Sprintf("the batch %s is still assembling %s past its latest close (%s), with no walk open: "+
-				"the controller did not cut it; grouped: %s", b.id, ago(late), b.atMost.UTC().Format(time.RFC3339), b.grouped),
-			Said:     fmt.Sprintf("assembling since %s past its maximum", ago(late)),
-			Headline: "Merged changes are not being delivered",
-			Explanation: fmt.Sprintf("Merges collected for one delivery should have been planned %s ago and were not. "+
-				"Nothing is lost; the mesh keeps them until it plans them.", humanDuration(late)),
-			Resolved: "Merged changes are being delivered again"})
-	}
-	return out
-}
-
-// watchBatchesBehind is S19: a batch waiting behind an open walk longer than that walk's bound, naming it.
-func watchBatchesBehind(f *signalFacts) []conditions.Observation {
-	var out []conditions.Observation
-	for _, b := range f.batches {
-		if b.state != inventory.PlanQueued || b.behind == "" || b.walkBound <= 0 || f.now.Sub(b.closed) <= b.walkBound {
-			continue
-		}
-		in := f.now.Sub(b.closed)
-		out = append(out, conditions.Observation{Scope: conditions.ScopePlan, ID: b.id, Kind: kindBatchBehindWalk,
-			Severity: conditions.Warning,
-			Summary: fmt.Sprintf("the batch %s has waited %s behind the walk %s, longer than that walk's bound (%s); "+
-				"grouped: %s; `plans %s` says where that walk stands", b.id, ago(in), b.behind, ago(b.walkBound),
-				b.grouped, b.behind),
-			Said:     fmt.Sprintf("queued behind %s for %s", b.behind, ago(in)),
-			Headline: "Merged changes wait behind a slow delivery",
-			Explanation: fmt.Sprintf("Merges collected for the next delivery have waited %s for the delivery before "+
-				"them, which is taking longer than it should. Nothing is lost.", humanDuration(in)),
-			Resolved: "Merged changes no longer wait behind a slow delivery"})
-	}
-	return out
-}

cmd/mesh-controller/bindings.go

@@ -1,140 +0,0 @@
-package main
-
-import (
-	"context"
-	"fmt"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-)
-
-// A binding to data moves only by a person (novox/hq ADR 0232, issue 273).
-//
-// The resolver keeps each consumer of a provision that keeps its data at the provider it was last
-// sent (catalogue/bound.go) and says what it would have moved. This is where that is said: on the
-// push that composed it, and by the self-check's D12 every run, as an urgent condition naming the
-// consumer, both providers and the pin that confirms the move.
-
-// The condition kinds of D12.
-const (
-	// kindBindingKept is a move the resolver refused: the consumer is still where its data is.
-	kindBindingKept = "binding-kept"
-	// kindBindingMoved is a consumer about to be sent another provider than the one on record with
-	// no pin naming it — what the resolver exists to make impossible, said if it ever is not.
-	kindBindingMoved = "binding-moved"
-	// kindBindingMoving is a move a pin asked for, not yet sent: a person's act, said so that the
-	// data is moved before the push that carries it.
-	kindBindingMoving = "binding-moving"
-)
-
-// probeBindingsID is the self-check's id for this probe, and the source of what it raises.
-const probeBindingsID = "D12"
-
-// keptObservation is the urgent condition for one refused move.
-func keptObservation(k catalogue.KeptBinding) conditions.Observation {
-	return conditions.Observation{Scope: conditions.ScopeMachine, ID: bindingID(k.Machine, k.Consumer, k.Provision),
-		Token: kindBindingKept, Kind: kindBindingKept, Machine: k.Machine, Also: otherMachines(k.Machine, k.Bound.Node, k.Would.Node),
-		Severity: conditions.Urgent, Resolver: conditions.ResolverOperator,
-		Summary: fmt.Sprintf("on %s, the mesh %s", k.Machine, k.String())}
-}
-
-func bindingID(machine, consumer, provision string) string {
-	return machine + "." + consumer + "." + provision
-}
-
-func otherMachines(machine string, nodes ...string) []string {
-	var out []string
-	seen := map[string]bool{machine: true}
-	for _, n := range nodes {
-		if n != "" && !seen[n] {
-			seen[n] = true
-			out = append(out, n)
-		}
-	}
-	return out
-}
-
-// reportKept says every move a machine's resolution refused, on the push composing it, and raises its
-// condition at once where this process keeps the conditions: a push is when a person is looking.
-func reportKept(ctx context.Context, plan catalogue.Resolution) {
-	for _, k := range plan.Kept {
-		fmt.Printf("%s: the mesh %s\n", plan.Node, k)
-		if conditionsFrom != nil {
-			o := keptObservation(k)
-			o.Source = probeBindingsID
-			if _, err := conditionsFrom.Observe(ctx, o); err != nil {
-				fmt.Printf("%s: and the condition for it could not be raised: %v\n", plan.Node, err)
-			}
-		}
-	}
-}
-
-// probeBindings is D12: every consumer of a provision that keeps its data is bound where it was last
-// sent, on every machine — the resolver kept it there (said, urgent, until a person pins), or a pin
-// moves it (said, so the data goes first), and never anything else.
-func probeBindings(ctx context.Context, d *doctor) ([]conditions.Observation, error) {
-	inv := d.open.inventory
-	nodes, err := inv.Nodes(ctx)
-	if err != nil {
-		return nil, err
-	}
-	var out []conditions.Observation
-	for _, n := range nodes {
-		plan, _, err := planFor(ctx, d.open, n.Name)
-		if err != nil {
-			if unresolvable(err) {
-				// D1 says it, with the binding that refused it when that is why.
-				continue
-			}
-			return nil, fmt.Errorf("%s cannot be worked out: %w", n.Name, err)
-		}
-		bound, err := inv.BindingsFor(ctx, n.Name)
-		if err != nil {
-			return nil, err
-		}
-		pins, err := inv.PinsFor(ctx, n.Name)
-		if err != nil {
-			return nil, err
-		}
-		out = append(out, bindingFindings(plan, bound, pins)...)
-	}
-	return out, nil
-}
-
-// bindingFindings is what one machine's resolution says against its record.
-func bindingFindings(plan catalogue.Resolution, bound map[string]map[string]catalogue.Chosen,
-	pins map[string]catalogue.Chosen) []conditions.Observation {
-	var out []conditions.Observation
-	for _, k := range plan.Kept {
-		out = append(out, keptObservation(k))
-	}
-	said := map[string]bool{}
-	for _, need := range plan.Needs {
-		if !need.KeepsData || need.ByRecord {
-			continue
-		}
-		was, recorded := bound[need.For][need.Name]
-		now := catalogue.Chosen{Node: need.From, Module: need.Module}
-		if !recorded || was == now || (was.Module == "" && was.Node == now.Node) {
-			continue
-		}
-		id := bindingID(plan.Node, need.For, need.Name)
-		if said[id] {
-			continue
-		}
-		said[id] = true
-		o := conditions.Observation{Scope: conditions.ScopeMachine, ID: id, Machine: plan.Node,
-			Also: otherMachines(plan.Node, was.Node, now.Node), Resolver: conditions.ResolverOperator}
-		if pin, pinned := pins[need.Name]; pinned && pin.Node == now.Node && (pin.Module == "" || pin.Module == now.Module) {
-			o.Token, o.Kind, o.Severity = kindBindingMoving, kindBindingMoving, conditions.Warning
-			o.Summary = fmt.Sprintf("on %s, %s's %s moves from %s to %s at the next push, by the pin — its data "+
-				"is on %s: move it first", plan.Node, need.For, need.Name, was, now, was)
-		} else {
-			o.Token, o.Kind, o.Severity = kindBindingMoved, kindBindingMoved, conditions.Urgent
-			o.Summary = fmt.Sprintf("on %s, %s's %s would be sent %s, and it is bound to %s, where its data is, "+
-				"with no pin naming %s — a move nothing asked for", plan.Node, need.For, need.Name, now, was, now)
-		}
-		out = append(out, o)
-	}
-	return out
-}

cmd/mesh-controller/bindings_test.go

@@ -1,183 +0,0 @@
-package main
-
-import (
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-)
-
-// novox/hq issue 273, ADR 0232: a consumer of a provision that keeps its data moves only by a pin.
-
-func storeManifests() []catalogue.Manifest {
-	return []catalogue.Manifest{
-		{Module: "store", Version: "1",
-			Provides: []catalogue.Offer{{Name: "postgres-database", Scope: catalogue.ScopeMesh}},
-			Claims:   []catalogue.Claim{{Name: "mesh-store", Scope: catalogue.ScopeMesh}},
-			Serves:   map[string]map[string]any{"postgres-database": {"port": 5432}},
-			Grants:   map[string]string{"postgres-database": "/var/lib/mesh/store/grants"}},
-		{Module: "resolver", Version: "1",
-			Provides: []catalogue.Offer{{Name: "wildcard-resolution", Scope: catalogue.ScopeMesh}},
-			Claims:   []catalogue.Claim{{Name: "mesh-dns-resolver", Scope: catalogue.ScopeMesh}}},
-		{Module: "network", Version: "1", Requires: []string{"wildcard-resolution"}},
-		{Module: "board", Version: "1", Requires: []string{"postgres-database"}},
-	}
-}
-
-func need(t *testing.T, plan catalogue.Resolution, consumer, provision string) catalogue.Needed {
-	t.Helper()
-	for _, n := range plan.Needs {
-		if n.For == consumer && n.Name == provision {
-			return n
-		}
-	}
-	t.Fatalf("no %s for %s: %+v", provision, consumer, plan.Needs)
-	return catalogue.Needed{}
-}
-
-// The incident through the stores: the laptop runs its own store and a consumer of it, the anchor's
-// store holds the mesh's seat. The consumer stays beside its data, the resolver follows its seat, the
-// binding is recorded as sent, and a pin — only a pin — moves it, said before the push that carries it.
-func TestTheIncidentAConsumerStaysBesideItsDataUntilAPersonPinsIt(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	inv := open.inventory
-	if _, err := inv.SeedSeats(ctx, catalogue.DefaultSeats()); err != nil {
-		t.Fatal(err)
-	}
-	for _, m := range storeManifests() {
-		register(t, open, m)
-	}
-	assignAll := func(pairs ...[2]string) {
-		for _, a := range pairs {
-			if _, err := assign(ctx, open, a[0], a[1]); err != nil {
-				t.Fatalf("assign %s %s: %v", a[0], a[1], err)
-			}
-		}
-	}
-	// The anchor's store and resolver hold the mesh's seats, on record; the laptop runs its own of each.
-	assignAll([2]string{"anchor", "store"}, [2]string{"anchor", "resolver"})
-	for _, seat := range [][2]string{{"mesh-store", "store"}, {"mesh-dns-resolver", "resolver"}} {
-		if err := inv.HoldSeat(ctx, seat[0], catalogue.ScopeMesh, "anchor", seat[1]); err != nil {
-			t.Fatal(err)
-		}
-	}
-	assignAll([2]string{"laptop", "store"}, [2]string{"laptop", "resolver"}, [2]string{"laptop", "network"},
-		[2]string{"laptop", "board"})
-
-	plan, _, err := planFor(ctx, open, "laptop")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if n := need(t, plan, "board", "postgres-database"); n.From != "laptop" || n.Module != "store" || !n.KeepsData {
-		t.Fatalf("the consumer was bound to %s/%s (keeps data: %v); its data is beside it", n.From, n.Module, n.KeepsData)
-	}
-	if n := need(t, plan, "network", "wildcard-resolution"); n.From != "anchor" || n.KeepsData {
-		t.Fatalf("the resolver was bound to %s (keeps data: %v); its seat is held on anchor (issue 258)", n.From, n.KeepsData)
-	}
-
-	// Sent, and recorded: only the binding to data.
-	bindings := boundToData(plan, nil)
-	if len(bindings) != 1 || bindings[0].Provider != (catalogue.Chosen{Node: "laptop", Module: "store"}) {
-		t.Fatalf("recorded %+v", bindings)
-	}
-	if err := inv.RecordBindings(ctx, "laptop", bindings); err != nil {
-		t.Fatal(err)
-	}
-	if found, err := probeBindings(ctx, &doctor{open: open}); err != nil || len(found) != 0 {
-		t.Fatalf("a mesh bound where it was sent: %+v, %v", found, err)
-	}
-
-	// The laptop's store taken away: refused, not moved to the anchor's empty one.
-	if err := inv.Unassign(ctx, "laptop", "store"); err != nil {
-		t.Fatal(err)
-	}
-	if _, _, err := planFor(ctx, open, "laptop"); err == nil || !unresolvable(err) ||
-		!strings.Contains(err.Error(), "board on laptop is bound to laptop/store") ||
-		!strings.Contains(err.Error(), "pin laptop postgres-database anchor store") {
-		t.Fatalf("the consumer's store went and it was answered elsewhere: %v", err)
-	}
-
-	// A person pins the anchor's: it moves, said before it is sent, and the record keeps where it was.
-	if err := inv.PinProvision(ctx, "laptop", "postgres-database", "anchor", "store"); err != nil {
-		t.Fatal(err)
-	}
-	plan, _, err = planFor(ctx, open, "laptop")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if n := need(t, plan, "board", "postgres-database"); n.From != "anchor" {
-		t.Fatalf("pinned to the anchor and bound to %s", n.From)
-	}
-	found, err := probeBindings(ctx, &doctor{open: open})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(found) != 1 || found[0].Kind != kindBindingMoving || found[0].Severity != conditions.Warning ||
-		!strings.Contains(found[0].Summary, "board's postgres-database moves from laptop/store to anchor/store") {
-		t.Fatalf("a pinned move is not said before it is sent: %+v", found)
-	}
-	if err := inv.RecordBindings(ctx, "laptop", boundToData(plan, nil)); err != nil {
-		t.Fatal(err)
-	}
-	all, err := inv.Bindings(ctx)
-	if err != nil || len(all) != 1 || all[0].MovedFrom != "laptop/store" {
-		t.Fatalf("%+v, %v", all, err)
-	}
-	if found, err := probeBindings(ctx, &doctor{open: open}); err != nil || len(found) != 0 {
-		t.Fatalf("a move sent is still said: %+v, %v", found, err)
-	}
-}
-
-// What one machine's resolution says against its record.
-func TestBindingFindingsSayAKeptMoveAndAMoveNothingAskedFor(t *testing.T) {
-	home, anchor := catalogue.Chosen{Node: "home", Module: "store"}, catalogue.Chosen{Node: "anchor", Module: "store"}
-	plan := catalogue.Resolution{Node: "laptop",
-		Kept: []catalogue.KeptBinding{{Machine: "laptop", Consumer: "board", Provision: "postgres-database",
-			Bound: home, Would: anchor}},
-		Needs: []catalogue.Needed{
-			{Name: "postgres-database", For: "board", From: "home", Module: "store", KeepsData: true},
-			{Name: "postgres-database", For: "game", From: "anchor", Module: "store", KeepsData: true},
-			{Name: "wildcard-resolution", For: "network", From: "anchor", Module: "resolver"},
-		}}
-	bound := map[string]map[string]catalogue.Chosen{
-		"board":   {"postgres-database": home},
-		"game":    {"postgres-database": home},
-		"network": {"wildcard-resolution": {Node: "home", Module: "resolver"}},
-	}
-	found := linted(bindingFindings(plan, bound, nil))
-	if len(found) != 2 {
-		t.Fatalf("found %+v", found)
-	}
-	kept, moved := found[0], found[1]
-	if kept.Kind != kindBindingKept || kept.Severity != conditions.Urgent || kept.Machine != "laptop" ||
-		!strings.Contains(kept.Summary, "would move board's postgres-database from home/store to anchor/store") ||
-		!strings.Contains(kept.Summary, "its data is on home/store") ||
-		!strings.Contains(kept.Summary, "`pin laptop postgres-database anchor store` to confirm a move (and move the data first)") {
-		t.Errorf("kept: %+v", kept)
-	}
-	if moved.Kind != kindBindingMoved || moved.Severity != conditions.Urgent ||
-		!strings.Contains(moved.Summary, "game's postgres-database would be sent anchor/store") {
-		t.Errorf("moved: %+v", moved)
-	}
-	if kept.Key() == moved.Key() {
-		t.Error("two consumers, one condition")
-	}
-}
-
-// A push says the move it refused, and raises its condition at once.
-func TestAPushSaysAKeptMoveAndRaisesItsCondition(t *testing.T) {
-	k, _ := withConditionsInMemory(t)
-	reportKept(t.Context(), catalogue.Resolution{Node: "laptop", Kept: []catalogue.KeptBinding{{Machine: "laptop",
-		Consumer: "board", Provision: "postgres-database", Bound: catalogue.Chosen{Node: "home", Module: "store"},
-		Would: catalogue.Chosen{Node: "anchor", Module: "store"}}}})
-	open, err := k.Open(t.Context())
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(open) != 1 || open[0].Kind != kindBindingKept || open[0].Severity != conditions.Urgent ||
-		open[0].Source != probeBindingsID {
-		t.Fatalf("raised %+v", open)
-	}
-}

cmd/mesh-controller/board.go

@@ -1,324 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"flag"
-	"fmt"
-	"html/template"
-	"net/http"
-	"sort"
-	"strings"
-	"time"
-)
-
-// boardCommand serves the three questions as a page.
-//
-// **It reads through the same functions everything else does and holds nothing**
-// (novox/hq 03-DESIGN/01-to-be/11-a-board.md). The board being replaced is one service that reads
-// every context's database directly — [ADR 0008](novox/hq) violated by the one component with a
-// reason to violate it, and the cost is that a boundary nothing may cross can move, while one
-// thing crossing it is enough to freeze it. A board that reads the provisioning tables is a board
-// that breaks when provisioning changes its tables, and the change then gets weighed against the
-// board.
-//
-// **It stores nothing of its own.** No cache that can disagree, no table of what the mesh looked
-// like last time. Every request reads the mesh now; if that is slow, the answer belongs in the
-// context that owns it, where everything else asking gets it too.
-//
-// **Reading is the whole of it.** Every action a board could offer already exists as a command,
-// and a button that does something no command does is a second implementation of a decision.
-func boardCommand(ctx context.Context, args []string) error {
-	set := flag.NewFlagSet("board", flag.ContinueOnError)
-	// The private network, not everything. A board says which machines are broken and what they
-	// are running, which is exactly the map somebody attacking this would like — and there is no
-	// reason for it to be reachable from further away than the mesh.
-	listen := set.String("listen", "127.0.0.1:8080", "where to serve it")
-	if _, err := parseAround(set, args); err != nil {
-		return err
-	}
-
-	server := &http.Server{
-		Addr:              *listen,
-		ReadHeaderTimeout: 10 * time.Second,
-		Handler:           board(),
-	}
-	fmt.Printf("the board is on http://%s\n", *listen)
-	fmt.Printf("  it reads the mesh on every request and keeps nothing\n")
-
-	go func() {
-		<-ctx.Done()
-		closing, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-		defer cancel()
-		_ = server.Shutdown(closing)
-	}()
-	if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
-		return err
-	}
-	return nil
-}
-
-// board is the handler, separate so a test can drive it without a listener.
-func board() http.Handler {
-	mux := http.NewServeMux()
-	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/" {
-			http.NotFound(w, r)
-			return
-		}
-		asked, err := ask(r.Context())
-		if err != nil {
-			// **Said, not blank.** A board that cannot reach the mesh and renders an empty page
-			// says "nothing is wrong" in the one situation where nobody can know that.
-			w.Header().Set("Content-Type", "text/html; charset=utf-8")
-			w.WriteHeader(http.StatusServiceUnavailable)
-			_ = page.Execute(w, view{Unreachable: err.Error()})
-			return
-		}
-		w.Header().Set("Content-Type", "text/html; charset=utf-8")
-		if err := page.Execute(w, asked); err != nil {
-			// The page is half-written by now; there is nothing useful left to say to the
-			// browser, and saying it here is what stops the failure being silent.
-			fmt.Printf("the board could not render: %v\n", err)
-		}
-	})
-	// The same answers for something that is not a person, from the same read. A board and a
-	// script disagreeing about which machine is broken would be worse than either alone.
-	mux.HandleFunc("/mesh.json", func(w http.ResponseWriter, r *http.Request) {
-		open, err := openStores(r.Context())
-		if err != nil {
-			http.Error(w, err.Error(), http.StatusServiceUnavailable)
-			return
-		}
-		defer open.Close()
-		asked, err := theThreeQuestions(r.Context(), open)
-		if err != nil {
-			http.Error(w, err.Error(), http.StatusServiceUnavailable)
-			return
-		}
-		body, err := statusAsJSON(asked)
-		if err != nil {
-			http.Error(w, err.Error(), http.StatusInternalServerError)
-			return
-		}
-		w.Header().Set("Content-Type", "application/json")
-		_, _ = w.Write(append(body, '\n'))
-	})
-	return mux
-}
-
-// ask reads the mesh for one request.
-func ask(ctx context.Context) (view, error) {
-	open, err := openStores(ctx)
-	if err != nil {
-		return view{}, err
-	}
-	defer open.Close()
-
-	asked, err := theThreeQuestions(ctx, open)
-	if err != nil {
-		return view{}, err
-	}
-	return viewOf(asked), nil
-}
-
-// view is what the page is given. Nothing is derived here that the reader could not derive.
-type view struct {
-	Unreachable string
-	Machines    int
-	Broken      []brokenMachine
-	Quiet       []quietMachine
-	Behind      []staleModule
-	Waiting     []waitingMachine
-	// Unresolved is every machine that cannot be worked out at all. Shown above everything else,
-	// because a machine here is in none of the other lists: nothing was computed for it, so it is
-	// not broken, not quiet and not behind — and a page without this said "all well" about a mesh
-	// where nothing could be sent anywhere.
-	Unresolved []blockedMachine
-	// Network is why the private network could not be computed, when it could not.
-	Network string
-	// Adopted is every node still adopted (novox/hq ADR 0100). Not broken: nothing forces the
-	// flip, so a node left adopted is shown rather than read as converged.
-	Adopted []string
-	At      string
-}
-
-type blockedMachine struct {
-	Node string
-	// Said is the mesh's own words, a line at a time. Every unmet requirement, not the first:
-	// a machine is usually blocked by more than one and fixing one of them changes nothing.
-	Said []string
-}
-
-type waitingMachine struct {
-	Node string
-	// Never told is not out of date: nobody has ever asked this machine to be anything. Same
-	// remedy, different situation, and the page says which.
-	Never bool
-}
-
-type brokenMachine struct {
-	Node string
-	// Outcome is refused or failed, and stays distinct all the way to the page. **Refused means
-	// the machine is exactly as it was and what is wrong is in what was sent; failed means it is
-	// in a state nobody declared and what is wrong is on the machine.** They are fixed in
-	// different places, so one word for both would send half the readers to the wrong one.
-	Outcome string
-	Said    []string
-	When    string
-}
-
-type quietMachine struct {
-	Node string
-	// Heard is "never" or how long ago. Never heard from is not the same as quiet for a while:
-	// one may be a machine that was never sent anything.
-	Heard string
-}
-
-type staleModule struct {
-	Module  string
-	Holds   string
-	Source  string
-	Running []string
-}
-
-func viewOf(asked answers) view {
-	out := view{Machines: len(asked.nodes), At: time.Now().Format("15:04:05"),
-		Network: asked.network, Adopted: adoptedNodes(asked.nodes)}
-	var blocked []string
-	for name := range asked.refused {
-		blocked = append(blocked, name)
-	}
-	sort.Strings(blocked)
-	for _, name := range blocked {
-		one := blockedMachine{Node: name}
-		for _, line := range strings.Split(strings.TrimRight(asked.refused[name], "\n"), "\n") {
-			one.Said = append(one.Said, strings.TrimSpace(line))
-		}
-		out.Unresolved = append(out.Unresolved, one)
-	}
-	for _, d := range asked.wrong {
-		one := brokenMachine{Node: d.Node, Outcome: d.Outcome,
-			When: d.At.Local().Format("2006-01-02 15:04")}
-		if d.Refused != "" {
-			// The host's own words. It says exactly what it could not accept, and nothing
-			// written here would say it better.
-			one.Said = append(one.Said, firstLine(d.Refused))
-		}
-		for _, f := range d.Failed {
-			one.Said = append(one.Said, f.ID+": "+firstLine(f.Error))
-		}
-		out.Broken = append(out.Broken, one)
-	}
-	for _, n := range asked.quiet {
-		out.Quiet = append(out.Quiet, quietMachine{Node: n.Name, Heard: heardFrom(n)})
-	}
-	for _, m := range asked.waiting {
-		out.Waiting = append(out.Waiting, waitingMachine{Node: m.Node, Never: m.Never})
-	}
-	for module, on := range asked.behind {
-		from := asked.sources[module]
-		out.Behind = append(out.Behind, staleModule{
-			Module: module, Holds: short(from.BuiltFrom), Source: short(from.Head), Running: on,
-		})
-	}
-	return out
-}
-
-// The page. Deliberately one file with no assets: a board that cannot render without fetching
-// something is a board that is blank exactly when the mesh is unwell.
-var page = template.Must(template.New("board").Parse(`<!doctype html>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>the mesh</title>
-<style>
-  :root { color-scheme: light dark; }
-  body { font: 15px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; margin: 2rem auto;
-         max-width: 52rem; padding: 0 1rem; }
-  h1 { font-size: 1.1rem; font-weight: 600; margin: 0 0 1.5rem; }
-  h2 { font-size: 1rem; font-weight: 600; margin: 2rem 0 .5rem; }
-  .quiet { opacity: .65; }
-  .said { opacity: .8; padding-left: 1.5rem; }
-  .outcome { display: inline-block; min-width: 4.5rem; }
-  .refused { color: #b26b00; }
-  .failed { color: #c0392b; }
-  ul { list-style: none; padding: 0; margin: 0; }
-  li { padding: .15rem 0; }
-  footer { margin-top: 3rem; opacity: .6; font-size: .85rem; }
-</style>
-{{if .Unreachable}}
-<h1>the mesh cannot be read</h1>
-<p class="failed">{{.Unreachable}}</p>
-<p class="quiet">This says nothing about whether the mesh is well — only that this page could not
-find out.</p>
-{{else}}
-<h1>{{.Machines}} machine{{if ne .Machines 1}}s{{end}}</h1>
-
-{{if .Unresolved}}
-<h2>Can everything be worked out?</h2>
-<ul>
-  {{range .Unresolved}}
-  <li><span class="outcome failed">blocked</span> <strong>{{.Node}}</strong>
-    {{range .Said}}<div class="said">{{.}}</div>{{end}}
-  </li>
-  {{end}}
-</ul>
-<p class="quiet">Nothing can be sent to a machine here, and it appears in none of the lists below:
-nothing was computed for it, so there is nothing it can be behind.</p>
-{{end}}
-{{if .Network}}
-<p class="failed">The private network could not be computed: {{.Network}}</p>
-{{end}}
-
-<h2>Is anything broken?</h2>
-{{if .Broken}}
-<ul>
-  {{range .Broken}}
-  <li>
-    <span class="outcome {{.Outcome}}">{{.Outcome}}</span>
-    <strong>{{.Node}}</strong> <span class="quiet">{{.When}}</span>
-    {{range .Said}}<div class="said">{{.}}</div>{{end}}
-  </li>
-  {{end}}
-</ul>
-{{else}}<p class="quiet">No. Every machine is doing what it was told.</p>{{end}}
-
-<h2>Is anything not answering?</h2>
-{{if .Quiet}}
-<ul>{{range .Quiet}}<li><strong>{{.Node}}</strong> <span class="quiet">{{.Heard}}</span></li>{{end}}</ul>
-<p class="quiet">Not heard from is not the same as tried and could not — a machine here may be
-new, switched off, or unreachable.</p>
-{{else}}<p class="quiet">No. Every machine has been heard from.</p>{{end}}
-
-<h2>Is anything out of date?</h2>
-{{if .Behind}}
-<ul>
-  {{range .Behind}}
-  <li><strong>{{.Module}}</strong> holds {{.Holds}}, source has {{.Source}}
-    {{if .Running}}<div class="said">running on {{range $i, $n := .Running}}{{if $i}}, {{end}}{{$n}}{{end}}</div>
-    {{else}}<div class="said quiet">assigned to nothing</div>{{end}}
-  </li>
-  {{end}}
-</ul>
-{{else}}<p class="quiet">No. Every module is what its source last had.</p>{{end}}
-
-{{if .Waiting}}
-<ul>
-  {{range .Waiting}}
-  <li><strong>{{.Node}}</strong>
-    {{if .Never}}<span class="quiet">has never been sent anything</span>
-    {{else}}<span class="quiet">is not running what the mesh would send it</span>{{end}}
-  </li>
-  {{end}}
-</ul>
-<p class="quiet">Never told is not out of date: nobody has asked that machine to be anything yet.
-Both are sent by <code>push --behind</code>.</p>
-{{else}}<p class="quiet">Every machine is running what the mesh would send it.</p>{{end}}
-{{if .Adopted}}
-<h2>Which machines are adopted?</h2>
-<ul>{{range .Adopted}}<li><strong>{{.}}</strong> <span class="quiet">adopted — what was found on it is kept until each module is taken</span></li>{{end}}</ul>
-{{end}}
-{{end}}
-
-<footer>Read at {{.At}}. This page holds nothing and changes nothing.</footer>
-`))

cmd/mesh-controller/board_test.go

@@ -1,154 +0,0 @@
-package main
-
-import (
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// Refused and failed stay distinct all the way to the page.
-//
-// **Refused means the machine is exactly as it was and what is wrong is in what was sent; failed
-// means it is in a state nobody declared and what is wrong is on the machine.** They are fixed in
-// different places, so a page saying "error" for both sends half its readers to the wrong one.
-func TestRefusedAndFailedReachThePageAsDifferentThings(t *testing.T) {
-	rendered := render(t, viewOf(answers{
-		nodes: []inventory.Node{{Name: "anchor"}, {Name: "laptop"}},
-		wrong: []inventory.Doing{
-			{Node: "anchor", Outcome: "refused", Refused: "not a declaration this host speaks",
-				At: time.Now()},
-			{Node: "laptop", Outcome: "failed", At: time.Now(),
-				Failed: []inventory.FailedResource{{ID: "web.container", Error: "no such image"}}},
-		},
-	}))
-	// The rendered outcome, not the word anywhere on the page: both words appear in the
-	// stylesheet, so a plain Contains passes whatever the machine actually said. It did.
-	for _, want := range []string{`<span class="outcome refused">refused</span>`,
-		`<span class="outcome failed">failed</span>`} {
-		if !strings.Contains(rendered, want) {
-			t.Fatalf("the page does not distinguish the two — missing %s:\n%s", want, rendered)
-		}
-	}
-	// And the host's own words, which say exactly what it could not accept.
-	for _, want := range []string{"not a declaration this host speaks", "web.container", "no such image"} {
-		if !strings.Contains(rendered, want) {
-			t.Fatalf("the page does not say %q, so a reader must go and ask:\n%s", want, rendered)
-		}
-	}
-}
-
-// Nothing wrong is said, not left blank. An empty page and a well mesh must not look alike.
-func TestAWellMeshSaysSoRatherThanShowingNothing(t *testing.T) {
-	rendered := render(t, viewOf(answers{nodes: []inventory.Node{{Name: "anchor"}}}))
-	for _, want := range []string{
-		"Every machine is doing what it was told",
-		"Every machine has been heard from",
-		"Every module is what its source last had",
-	} {
-		if !strings.Contains(rendered, want) {
-			t.Fatalf("a well mesh does not say %q:\n%s", want, rendered)
-		}
-	}
-}
-
-// A board that cannot reach the mesh must not render an empty page: that says "nothing is wrong"
-// in the one situation where nobody can know it.
-func TestABoardThatCannotReadTheMeshSaysSo(t *testing.T) {
-	rendered := render(t, view{Unreachable: "the store did not answer"})
-	if !strings.Contains(rendered, "the store did not answer") {
-		t.Fatalf("the reason is not on the page:\n%s", rendered)
-	}
-	if strings.Contains(rendered, "Every machine is doing what it was told") {
-		t.Fatal("a board that could not read the mesh reported that the mesh is well")
-	}
-}
-
-// Quiet is not broken, and the page says which it is.
-func TestQuietIsNotReportedAsBroken(t *testing.T) {
-	rendered := render(t, viewOf(answers{
-		nodes: []inventory.Node{{Name: "laptop"}},
-		quiet: []inventory.Node{{Name: "laptop"}},
-	}))
-	if !strings.Contains(rendered, "not the same as tried and could not") {
-		t.Fatalf("the page does not separate quiet from broken:\n%s", rendered)
-	}
-	if !strings.Contains(rendered, "Every machine is doing what it was told") {
-		t.Fatalf("a quiet machine was counted as broken:\n%s", rendered)
-	}
-}
-
-// The page renders what a machine said, and a hostile string in it is not markup.
-//
-// What is on this page comes from machines, and a machine's own words are the whole reason the
-// page is useful. They are also the one thing here that nobody in this repository wrote.
-func TestWhatAMachineSaidIsNotMarkup(t *testing.T) {
-	rendered := render(t, viewOf(answers{
-		nodes: []inventory.Node{{Name: "anchor"}},
-		wrong: []inventory.Doing{{Node: "anchor", Outcome: "refused",
-			Refused: `<script>alert("from the machine")</script>`, At: time.Now()}},
-	}))
-	if strings.Contains(rendered, "<script>alert") {
-		t.Fatalf("a machine's words were rendered as markup:\n%s", rendered)
-	}
-	if !strings.Contains(rendered, "&lt;script&gt;") {
-		t.Fatalf("the words were not shown at all, so the reader cannot see what it said:\n%s", rendered)
-	}
-}
-
-// A module behind its source names the machines running the old one — the part with consequences.
-func TestBeingBehindNamesTheMachinesRunningTheOldOne(t *testing.T) {
-	rendered := render(t, viewOf(answers{
-		nodes:   []inventory.Node{{Name: "laptop"}},
-		behind:  map[string][]string{"web": {"laptop"}},
-		sources: map[string]inventory.Source{"web": {BuiltFrom: "aaaaaaaaaa", Head: "bbbbbbbbbb"}},
-	}))
-	for _, want := range []string{"web", "aaaaaaaa", "bbbbbbbb", "running on laptop"} {
-		if !strings.Contains(rendered, want) {
-			t.Fatalf("the page does not say %q:\n%s", want, rendered)
-		}
-	}
-}
-
-func render(t *testing.T, v view) string {
-	t.Helper()
-	var out strings.Builder
-	if err := page.Execute(&out, v); err != nil {
-		t.Fatal(err)
-	}
-	return out.String()
-}
-
-// The board and the command must answer the same question the same way.
-//
-// A machine not running what the mesh would send it was added to `status` and would have been
-// missing here — which is the one thing this page's design forbids: two answers to the same
-// question, disagreeing, with a person in front of each.
-func TestTheBoardSaysWhichMachinesHaveNotBeenSentWhatTheyShouldBe(t *testing.T) {
-	rendered := render(t, viewOf(answers{
-		nodes: []inventory.Node{{Name: "anchor"}, {Name: "laptop"}},
-		waiting: []inventory.Machine{
-			{Node: "anchor"},
-			{Node: "laptop", Never: true},
-		},
-	}))
-	if !strings.Contains(rendered, "is not running what the mesh would send it") {
-		t.Fatalf("the page does not say a machine is out of date:\n%s", rendered)
-	}
-	// Never told is a different situation with the same remedy, and the page keeps them apart.
-	if !strings.Contains(rendered, "has never been sent anything") {
-		t.Fatalf("the page does not separate never told from out of date:\n%s", rendered)
-	}
-	if !strings.Contains(rendered, "push --behind") {
-		t.Fatalf("the page does not say what sends them:\n%s", rendered)
-	}
-}
-
-// And says so when there is nothing waiting, rather than leaving the question unanswered.
-func TestAMeshWithNothingWaitingSaysSo(t *testing.T) {
-	rendered := render(t, viewOf(answers{nodes: []inventory.Node{{Name: "anchor"}}}))
-	if !strings.Contains(rendered, "Every machine is running what the mesh would send it") {
-		t.Fatalf("the page leaves the question unanswered:\n%s", rendered)
-	}
-}

cmd/mesh-controller/bucket_log_fill.go

@@ -1,207 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"sort"
-
-	"github.com/nats-io/nats.go"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-)
-
-// **A filling bucket or log is said before it is full** (novox/hq ADR 0297 §6, issue 501).
-//
-// A module's bucket and its log each have a cap on the bus, and when either is full the bus refuses
-// the next write: the module stops doing what it writes for, and nothing said so before. On
-// 2026-10-11 the issue tracker's bucket held a sixth of its cap after two days, growing toward a stop
-// nobody would have heard coming. So the self-check reads every module's bucket and log, and one at
-// fillRaiseAt of its cap or more raises a condition naming the module, the bucket or log, and how full
-// it is.
-//
-// **Cleared by observation below fillClearBelow, not below fillRaiseAt**: a bucket or log hovering at
-// its threshold would otherwise be raised and cleared on every run. Between the two, an open condition
-// is kept and none is raised.
-//
-// **One that cannot be read is said, and the rest are still judged.** An unanswered question about one
-// stream is no reason to know nothing of the others: it is a finding of its own, naming the bucket or
-// log and why, and a fill condition already open for it is kept, because not knowing is not a pass.
-
-// The fill thresholds, in percent of a bucket's or log's cap.
-const (
-	fillRaiseAt    = 75
-	fillClearBelow = 70
-)
-
-// The conditions the fill probe raises: one filling, and one that could not be read.
-const (
-	kindBucketOrLogFilling = "bucket-or-log-filling"
-	kindBucketOrLogUnread  = "bucket-or-log-unread"
-)
-
-// probeFillID is the probe's id in the registry.
-const probeFillID = "D-fill"
-
-// bucketOrLog is one module's bucket or log as the fill probe reads it.
-type bucketOrLog struct {
-	Module string
-	// Kind is `bucket` or `log`; Name its local name; Stream the stream it is on the bus.
-	Kind, Name, Stream string
-}
-
-// filled is how full one bucket or log is, read from the bus.
-type filled struct {
-	Bytes, Max uint64
-}
-
-// percent is how full, in whole percent, rounded down.
-func (f filled) percent() uint64 {
-	if f.Max == 0 {
-		return 0
-	}
-	return f.Bytes * 100 / f.Max
-}
-
-// fillKey is where a bucket's or log's fill condition is kept.
-func fillKey(s bucketOrLog) string { return conditions.Key(conditions.ScopeBus, s.Stream, "filling") }
-
-// fillObservation is what one bucket's or log's fill says: a finding at fillRaiseAt or above, and,
-// while its condition is open, at fillClearBelow or above too; nothing otherwise, which is what clears
-// it. The operator's words are the kind's (plain_words.go); the summary and the evidence name the
-// module, the bucket or log, and the fill.
-func fillObservation(s bucketOrLog, f filled, open bool) (conditions.Observation, bool) {
-	if f.Max == 0 {
-		return conditions.Observation{}, false // one with no cap cannot fill
-	}
-	// Compared in bytes, not rounded percent: 74.9% is not 75%.
-	atRaise := f.Bytes*100 >= f.Max*fillRaiseAt
-	aboveClear := f.Bytes*100 >= f.Max*fillClearBelow
-	if !atRaise && !(open && aboveClear) {
-		return conditions.Observation{}, false
-	}
-	pct := f.percent()
-	return conditions.Observation{
-		Scope: conditions.ScopeBus, ID: s.Stream, Token: "filling", Kind: kindBucketOrLogFilling,
-		Severity: conditions.Warning,
-		Summary: fmt.Sprintf("%s's %s %s holds %s of %s, %d%%: at its cap the bus refuses the module's next write",
-			s.Module, s.Kind, s.Name, mibWords(f.Bytes), mibWords(f.Max), pct),
-		Said: fmt.Sprintf("module %s, %s %s (stream %s): %d of %d bytes, %d%%", s.Module, s.Kind, s.Name,
-			s.Stream, f.Bytes, f.Max, pct),
-	}, true
-}
-
-// unreadObservation says one bucket or log could not be read, and why. Asked over the network, so one
-// look can be wrong: raised on the second look in a row (confirm.go).
-func unreadObservation(s bucketOrLog, why error) conditions.Observation {
-	return conditions.Observation{
-		Scope: conditions.ScopeBus, ID: s.Stream, Token: "unread", Kind: kindBucketOrLogUnread,
-		Severity: conditions.Warning, Confirm: true,
-		Summary: fmt.Sprintf("%s's %s %s could not be read, so how full it is is not known", s.Module, s.Kind, s.Name),
-		Said:    fmt.Sprintf("module %s, %s %s (stream %s): %v", s.Module, s.Kind, s.Name, s.Stream, why),
-	}
-}
-
-// keptFilling is an open fill condition said again for a bucket or log that could not be read this
-// time: not knowing how full it is now is no reason to say it has room. Only ever made from a condition
-// read back as open — its own summary and severity, never words made up for it.
-func keptFilling(s bucketOrLog, open conditions.Condition, why error) conditions.Observation {
-	return conditions.Observation{
-		Scope: conditions.ScopeBus, ID: s.Stream, Token: "filling", Kind: kindBucketOrLogFilling,
-		Severity: open.Severity, Summary: open.Summary,
-		Said: fmt.Sprintf("module %s, %s %s (stream %s): not read this time (%v); kept open as it was",
-			s.Module, s.Kind, s.Name, s.Stream, why),
-	}
-}
-
-// mibWords is a size as a person reads it, in MiB with one decimal.
-func mibWords(b uint64) string {
-	return fmt.Sprintf("%.1f MiB", float64(b)/(1024*1024))
-}
-
-// readFill is how full one bucket or log is on the bus; found false when it is not on the bus.
-type readFill func(ctx context.Context, s bucketOrLog) (f filled, found bool, err error)
-
-// openFill is the fill condition open under a key, if one is, or why it could not be read.
-type openFill func(ctx context.Context, key string) (conditions.Condition, bool, error)
-
-// judgeFills judges every bucket and log on its own: one that cannot be read is said as unread, with
-// its fill condition kept only when that condition was read back and is open — when it cannot be read
-// either, nothing is said of its fill, which the unread finding already covers. Every other is judged
-// by its fill; for one of those, a condition that cannot be read is taken as open, so an unknown never
-// clears a fill measured between fillClearBelow and fillRaiseAt.
-func judgeFills(ctx context.Context, all []bucketOrLog, read readFill, open openFill) []conditions.Observation {
-	var out []conditions.Observation
-	for _, s := range all {
-		f, found, err := read(ctx, s)
-		if err != nil {
-			out = append(out, unreadObservation(s, err))
-			if c, isOpen, cerr := open(ctx, fillKey(s)); cerr == nil && isOpen {
-				out = append(out, keptFilling(s, c, err))
-			}
-			continue
-		}
-		if !found {
-			continue // not on the bus: created on the controller's next raise, and nothing there can fill
-		}
-		_, isOpen, cerr := open(ctx, fillKey(s))
-		isOpen = isOpen || cerr != nil
-		if o, said := fillObservation(s, f, isOpen); said {
-			out = append(out, o)
-		}
-	}
-	sort.SliceStable(out, func(i, j int) bool { return out[i].Key() < out[j].Key() })
-	return out
-}
-
-// declaredBucketsAndLogs is every module's bucket and log the catalogue declares, by its stream.
-func declaredBucketsAndLogs(ctx context.Context, d *doctor) ([]bucketOrLog, error) {
-	buckets, err := d.open.inventory.DeclaredBuckets(ctx)
-	if err != nil {
-		return nil, err
-	}
-	logs, err := d.open.inventory.DeclaredLogs(ctx)
-	if err != nil {
-		return nil, err
-	}
-	var out []bucketOrLog
-	for _, b := range buckets {
-		out = append(out, bucketOrLog{Module: b.Module, Kind: "bucket", Name: b.Name, Stream: "KV_" + b.Bucket()})
-	}
-	for _, l := range logs {
-		out = append(out, bucketOrLog{Module: l.Module, Kind: "log", Name: l.Name, Stream: l.Stream()})
-	}
-	return out, nil
-}
-
-// probeFill reads every module's bucket and log on the bus and says each one filling toward its cap,
-// and each one that could not be read.
-func probeFill(ctx context.Context, d *doctor) ([]conditions.Observation, error) {
-	all, err := declaredBucketsAndLogs(ctx, d)
-	if err != nil {
-		return nil, err
-	}
-	js := d.js.Context()
-	read := func(ctx context.Context, s bucketOrLog) (filled, bool, error) {
-		if err := ctx.Err(); err != nil {
-			return filled{}, false, err
-		}
-		info, err := js.StreamInfo(s.Stream, nats.Context(ctx))
-		switch {
-		case errors.Is(err, nats.ErrStreamNotFound):
-			return filled{}, false, nil
-		case err != nil:
-			return filled{}, false, err
-		case info.Config.MaxBytes <= 0:
-			return filled{}, true, nil
-		}
-		return filled{Bytes: info.State.Bytes, Max: uint64(info.Config.MaxBytes)}, true, nil
-	}
-	open := func(ctx context.Context, key string) (conditions.Condition, bool, error) {
-		if d.keeper == nil {
-			return conditions.Condition{}, false, nil
-		}
-		return d.keeper.Get(ctx, key)
-	}
-	return judgeFills(ctx, all, read, open), nil
-}

cmd/mesh-controller/bucket_log_fill_test.go

@@ -1,165 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-)
-
-// **A filling log or bucket is said at three quarters of its cap and cleared below seven tenths**
-// (novox/hq ADR 0297 §6): raised at 75% naming the module, the bucket or log and its fill; not at 74.9%;
-// kept between 70% and 75% while it is open, and not raised there when it is not; and cleared — said no
-// more — once it reads below 70%, open or not.
-func TestAFillingBucketOrLogIsRaisedAtThreeQuartersAndClearedBelowSevenTenths(t *testing.T) {
-	const mib = 1024 * 1024
-	log := bucketOrLog{Module: "mesh-issues", Kind: "log", Name: "changes", Stream: "LOG_mesh-issues_changes"}
-	bucket := bucketOrLog{Module: "mesh-issues", Kind: "bucket", Name: "issues", Stream: "KV_mesh-issues_issues"}
-	for _, c := range []struct {
-		name  string
-		of    bucketOrLog
-		bytes uint64
-		max   uint64
-		open  bool
-		said  bool
-	}{
-		{"a log at exactly 75%", log, 768 * mib, 1024 * mib, false, true},
-		{"a bucket at exactly 75%", bucket, 48 * mib, 64 * mib, false, true},
-		{"a bucket full", bucket, 64 * mib, 64 * mib, false, true},
-		{"a log just under 75%", log, 768*mib - 1, 1024 * mib, false, false},
-		{"a bucket at 72%, not open", bucket, 64 * mib * 72 / 100, 64 * mib, false, false},
-		{"a bucket at 72%, open: kept", bucket, 64 * mib * 72 / 100, 64 * mib, true, true},
-		{"a log at exactly 70%, open: kept", log, 700 * mib, 1000 * mib, true, true},
-		{"a log just under 70%, open: cleared", log, 700*mib - 1, 1000 * mib, true, false},
-		{"a bucket at 10%, open: cleared", bucket, 64 * mib / 10, 64 * mib, true, false},
-		{"a bucket with no cap", bucket, 100, 0, true, false},
-	} {
-		o, said := fillObservation(c.of, filled{Bytes: c.bytes, Max: c.max}, c.open)
-		if said != c.said {
-			t.Errorf("%s: said %v, want %v", c.name, said, c.said)
-			continue
-		}
-		if !said {
-			continue
-		}
-		if o.Key() != fillKey(c.of) || o.Kind != kindBucketOrLogFilling || o.Severity != conditions.Warning {
-			t.Errorf("%s: raised as %s (%s, %s)", c.name, o.Key(), o.Kind, o.Severity)
-		}
-		for _, part := range []string{c.of.Module, c.of.Kind + " " + c.of.Name, "%", " of "} {
-			if !strings.Contains(o.Summary, part) {
-				t.Errorf("%s: does not name %q: %q", c.name, part, o.Summary)
-			}
-		}
-		if !strings.Contains(o.Said, "bytes") {
-			t.Errorf("%s: the evidence does not say the fill in bytes: %q", c.name, o.Said)
-		}
-	}
-	o, _ := fillObservation(log, filled{Bytes: 800 * mib, Max: 1024 * mib}, false)
-	if !strings.Contains(o.Summary, "800.0 MiB of 1024.0 MiB, 78%") {
-		t.Errorf("the fill is said as %q", o.Summary)
-	}
-}
-
-// **One bucket or log that cannot be read does not stop the others being judged** (review of #231): it is
-// said as unread with its reason, a fill condition open for it is kept, and every other bucket and log
-// is judged by its own fill.
-func TestAnUnreadableBucketOrLogIsSaidAndTheRestAreStillJudged(t *testing.T) {
-	const mib = 1024 * 1024
-	broken := bucketOrLog{Module: "a", Kind: "bucket", Name: "broken", Stream: "KV_a_broken"}
-	brokenOpen := bucketOrLog{Module: "a", Kind: "log", Name: "was-filling", Stream: "LOG_a_was-filling"}
-	full := bucketOrLog{Module: "b", Kind: "log", Name: "changes", Stream: "LOG_b_changes"}
-	empty := bucketOrLog{Module: "c", Kind: "bucket", Name: "quiet", Stream: "KV_c_quiet"}
-	absent := bucketOrLog{Module: "d", Kind: "bucket", Name: "not-yet", Stream: "KV_d_not-yet"}
-	refusal := errors.New("the bus did not answer")
-	read := func(_ context.Context, s bucketOrLog) (filled, bool, error) {
-		switch s {
-		case broken, brokenOpen:
-			return filled{}, false, refusal
-		case full:
-			return filled{Bytes: 900 * mib, Max: 1000 * mib}, true, nil
-		case empty:
-			return filled{Bytes: 1, Max: 64 * mib}, true, nil
-		}
-		return filled{}, false, nil
-	}
-	open := func(_ context.Context, key string) (conditions.Condition, bool, error) {
-		if key == fillKey(brokenOpen) {
-			return conditions.Condition{Key: key, Severity: conditions.Warning,
-				Summary: "a's log was-filling holds 800.0 MiB of 1024.0 MiB, 78%"}, true, nil
-		}
-		return conditions.Condition{}, false, nil
-	}
-	got := map[string]conditions.Observation{}
-	for _, o := range judgeFills(context.Background(), []bucketOrLog{broken, brokenOpen, full, empty, absent}, read, open) {
-		got[o.Key()] = o
-	}
-	for _, s := range []bucketOrLog{broken, brokenOpen} {
-		o, said := got[conditions.Key(conditions.ScopeBus, s.Stream, "unread")]
-		if !said || o.Kind != kindBucketOrLogUnread || !o.Confirm || !strings.Contains(o.Said, refusal.Error()) {
-			t.Errorf("%s could not be read and was said as %+v", s.Stream, o)
-		}
-	}
-	if o, kept := got[fillKey(brokenOpen)]; !kept || !strings.Contains(o.Said, "kept open") {
-		t.Errorf("an open fill condition of a log not read this time was not kept: %+v", o)
-	}
-	if _, said := got[fillKey(broken)]; said {
-		t.Error("a bucket not read and not filling was said filling")
-	}
-	if o, said := got[fillKey(full)]; !said || o.Kind != kindBucketOrLogFilling {
-		t.Errorf("a log at 90%% beside an unreadable one was not judged: %+v", got)
-	}
-	if len(got) != 4 {
-		t.Errorf("said %d findings, want 4 (two unread, one kept, one filling): %v", len(got), got)
-	}
-}
-
-// Both kinds have plain words of their own, which hold to the plain rule (novox/hq ADR 0253).
-func TestAFillingOrUnreadBucketOrLogIsSaidInPlainWords(t *testing.T) {
-	for _, kind := range []string{kindBucketOrLogFilling, kindBucketOrLogUnread} {
-		wording, has := plainWordings[kind]
-		if !has {
-			t.Errorf("%s has no plain words", kind)
-			continue
-		}
-		if why, ok := conditions.PlainWords(wording(conditions.Observation{Kind: kind})); !ok {
-			t.Errorf("%s: %s", kind, why)
-		}
-	}
-}
-
-// **When neither the bucket or log nor its condition can be read, nothing is said of its fill** (second
-// review of #231): the unread finding covers it, and no fill is invented for it. For one that is read and
-// measured between seven tenths and three quarters, a condition that cannot be read is taken as open, so
-// an unknown never clears it.
-func TestNothingIsSaidOfAFillWhenNeitherItNorItsConditionCanBeRead(t *testing.T) {
-	const mib = 1024 * 1024
-	broken := bucketOrLog{Module: "a", Kind: "log", Name: "changes", Stream: "LOG_a_changes"}
-	between := bucketOrLog{Module: "b", Kind: "bucket", Name: "issues", Stream: "KV_b_issues"}
-	read := func(_ context.Context, s bucketOrLog) (filled, bool, error) {
-		if s == broken {
-			return filled{}, false, errors.New("the bus did not answer")
-		}
-		return filled{Bytes: 72 * mib, Max: 100 * mib}, true, nil
-	}
-	open := func(context.Context, string) (conditions.Condition, bool, error) {
-		return conditions.Condition{}, false, errors.New("the conditions bucket did not answer")
-	}
-	got := map[string]conditions.Observation{}
-	for _, o := range judgeFills(context.Background(), []bucketOrLog{broken, between}, read, open) {
-		got[o.Key()] = o
-	}
-	if o, said := got[fillKey(broken)]; said {
-		t.Fatalf("a fill was said for a log whose fill and condition could not be read: %+v", o)
-	}
-	if _, said := got[conditions.Key(conditions.ScopeBus, broken.Stream, "unread")]; !said {
-		t.Error("the log that could not be read was not said as unread")
-	}
-	if _, kept := got[fillKey(between)]; !kept {
-		t.Error("a bucket at 72% whose condition could not be read was cleared")
-	}
-	if len(got) != 2 {
-		t.Errorf("said %d findings, want 2: %v", len(got), got)
-	}
-}

cmd/mesh-controller/build_seat_test.go

@@ -1,43 +0,0 @@
-package main
-
-import (
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-func claiming(module, seat string, on ...string) inventory.Entry {
-	return inventory.Entry{
-		Manifest: catalogue.Manifest{Module: module, Claims: []catalogue.Claim{{Name: seat}}},
-		On:       on,
-	}
-}
-
-// The controller asks the build role that has a holder (novox/hq ADR 0190 handover): the retired
-// one while only the builder is assigned, the current one from the first build-agent on, and the
-// current one when nothing holds either — where every ask goes once the handover is done.
-func TestTheControllerAsksTheBuildRoleThatHasAHolder(t *testing.T) {
-	onlyTheBuilder := []inventory.Entry{
-		claiming("builder", link.TheBuildMachineBefore, "anchor"),
-		claiming("build-agent", link.TheBuildMachine), // registered, assigned nowhere yet
-	}
-	if got := buildSeatAmong(onlyTheBuilder); got != link.TheBuildMachineBefore {
-		t.Errorf("with only the builder assigned, asked %q", got)
-	}
-	bothHeld := []inventory.Entry{
-		claiming("builder", link.TheBuildMachineBefore, "anchor"),
-		claiming("build-agent", link.TheBuildMachine, "home-server"),
-	}
-	if got := buildSeatAmong(bothHeld); got != link.TheBuildMachine {
-		t.Errorf("with a build-agent assigned anywhere, asked %q", got)
-	}
-	neither := []inventory.Entry{claiming("builder", link.TheBuildMachineBefore)}
-	if got := buildSeatAmong(neither); got != link.TheBuildMachine {
-		t.Errorf("with no holder of either, asked %q, want the current role", got)
-	}
-	if got := buildSeatAmong(nil); got != link.TheBuildMachine {
-		t.Errorf("an empty catalogue asks %q", got)
-	}
-}

cmd/mesh-controller/build_source.go

@@ -1,547 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"os"
-	"regexp"
-	"strings"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// Where a build may register a module from (novox/hq ADR 0266).
-//
-// A build's outcome registers its module, and a registered module is what the next push sends. Before this,
-// an outcome registered whatever its manifest named, from whichever repository it was built from: an agent
-// that made a repository of its own, committed `modules/sudo/module.json` granting itself a rule without a
-// password, and asked the `build` verb for it had its repository registered as the module `sudo` — whose next
-// push made the agent root on every node. A fork of the node-engine did the same everywhere. The trunk rule
-// (ADR 0238) did not stop it: the trunk it checked was the trunk of the repository built, which was the
-// agent's own.
-//
-// So **an outcome registers a module only from the repository the catalogue already builds that module
-// from**; and a module new to the catalogue only from a repository the catalogue already builds another
-// module from — whose trunk takes a reviewed, approved merge, which is how a merge adds a module (novox/hq
-// issue 300). Anything else — a module moved to another repository, a module from a repository the
-// catalogue has never built — is the operator's, at the controller's terminal: allowed only when the build
-// request was kept as asked there. Judged at the take-in, which every outcome reaches whoever hears it and
-// whichever verb asked it (`build`, `rebuild`, `replay --register`, `assign` with build), and before the ask
-// for a call through a verb, so an agent cannot have a build node run a repository the catalogue does not
-// build from at all.
-
-// errNotItsSource is an outcome refused for where it was built from.
-var errNotItsSource = errors.New("not built from the repository the catalogue builds it from")
-
-// servedVar marks every process the serving controller starts — each verb's command, each child — and the serving
-// process itself, so none of them can read as the operator at the terminal (novox/hq ADR 0266). Set by serve
-// before it answers anything, inherited by every child through os.Environ.
-const servedVar = "MESH_SERVED_BY_THE_CONTROLLER"
-
-// startedAtTheTerminal says this process was started at the controller's terminal: not the serving controller,
-// not anything it started, not a verb's command, not a seat call's. The serving controller marks its own
-// environment (servedVar), so a build asked in it, or by any process it starts, never reads as the terminal's;
-// runVerb also names the verb and the caller.
-//
-// **And a line mesh-cli asked as the controller's terminal** (novox/hq ADR 0272 §4): the serving controller runs it
-// without the served mark and without a verb, names its caller, and marks it with cliTerminalVar — a mark only the
-// mesh-cli path sets and every other command line the controller runs is stripped of (commandEnvironment).
-func startedAtTheTerminal() bool {
-	if os.Getenv(servedVar) != "" || os.Getenv(verbVar) != "" {
-		return false
-	}
-	return os.Getenv(link.CallerVar) == "" || os.Getenv(cliTerminalVar) != ""
-}
-
-// cliTerminalVar marks a command line the serving controller runs as the controller's terminal for mesh-cli.
-const cliTerminalVar = "MESH_CLI_TERMINAL"
-
-// markServed marks this process, and so everything it starts, as the serving controller's.
-func markServed() {
-	if err := os.Setenv(servedVar, "1"); err != nil {
-		panic("the serving controller could not mark its environment: " + err.Error())
-	}
-}
-
-// sourceForms compares sources however each is spelled: a path on a seat's holder (ADR 0111) or a URL — a
-// build asked of a seat's path is registered with the URL composed from it when its outcome does not echo
-// the seat. A seat's path is composed into its URL where the seat's holder is known, so both spellings of
-// one repository are one; where it is not, a seat's path matches only the same seat's same path.
-type sourceForms struct {
-	bases map[string]string // the seat's clone base, `scheme://host:port`, by seat; "" where it is not known
-	base  func(seat string) string
-}
-
-// newSourceForms reads the seats' bases from the mesh once, when first needed.
-func newSourceForms(ctx context.Context, inv *inventory.Inventory) *sourceForms {
-	f := &sourceForms{bases: map[string]string{}}
-	var world *catalogue.World
-	f.base = func(seat string) string {
-		if b, known := f.bases[seat]; known {
-			return b
-		}
-		if world == nil {
-			w := catalogue.World{}
-			if shelf, err := inv.Catalogue(ctx); err == nil {
-				if read, err := theRestOfTheMesh(ctx, inv, shelf, ""); err == nil {
-					w = read
-				}
-			}
-			world = &w
-		}
-		b, err := seatBase(*world, seat)
-		if err != nil {
-			b = ""
-		}
-		f.bases[seat] = b
-		return b
-	}
-	return f
-}
-
-// canonical is one spelling of a repository: lower case, no `.git`, no trailing slash, and a seat's path as
-// the URL its holder serves it at where that is known.
-func (f *sourceForms) canonical(repository, seat string) string {
-	trim := func(s string) string {
-		s = strings.TrimSpace(strings.ToLower(s))
-		s = strings.TrimRight(s, "/")
-		return strings.TrimRight(strings.TrimSuffix(s, ".git"), "/")
-	}
-	if seat == "" {
-		return trim(repository)
-	}
-	if b := f.base(seat); b != "" {
-		return trim(b + "/" + strings.Trim(repository, "/"))
-	}
-	return "seat:" + seat + ":" + trim(strings.Trim(repository, "/"))
-}
-
-// same says two sources are one repository.
-func (f *sourceForms) same(aRepository, aSeat, bRepository, bSeat string) bool {
-	if aRepository == "" || bRepository == "" {
-		return false
-	}
-	return f.canonical(aRepository, aSeat) == f.canonical(bRepository, bSeat)
-}
-
-// buildsFrom says the catalogue builds some module from this repository.
-func (f *sourceForms) buildsFrom(entries []inventory.Entry, repository, seat string) bool {
-	for _, e := range entries {
-		if e.Provided || e.Source.Repository == "" {
-			continue
-		}
-		if f.same(e.Source.Repository, e.Source.Seat, repository, seat) {
-			return true
-		}
-	}
-	return false
-}
-
-// forgeFacts is what the mesh's forge says of a repository a module is registered from (novox/hq ADR 0266).
-type forgeFacts struct {
-	// ID is the forge's own id of the repository: what tells it from one deleted and made again by its name.
-	ID int64
-	// Guarded is whether the branch is protected as a module's trunk must be: no direct push, at least one
-	// required status, and no administrator merging past one. Why says what is missing when it is not.
-	Guarded bool
-	Why     string
-}
-
-// askTheForge asks the forge, through its module's tools on the bus, for a repository's id and its branch's
-// protection, waiting out a forge not served for a moment (novox/hq issue 486). A variable so a test needs no
-// forge.
-var askTheForge = func(ctx context.Context, owner, repo, branch string) (forgeFacts, error) {
-	return forgeWaitedOut(ctx, forgeWait, owner+"/"+repo, func(ctx context.Context) (forgeFacts, error) {
-		return askTheForgeOnce(ctx, owner, repo, branch)
-	})
-}
-
-// waitOut bounds how long a question is asked again while its answer is "not now": a pause of first, doubling
-// to most, for at most bound in all. now and sleep are the clock, so a test waits in no real time.
-type waitOut struct {
-	bound, first, most time.Duration
-	now                func() time.Time
-	sleep              func(context.Context, time.Duration) error
-}
-
-// forgeWait is the registration's wait for the forge (novox/hq issue 486). On 2026-10-11 a build's registration
-// asked the forge while node-tools on the control-node re-served after a rollout of the tool runner, heard
-// "nothing serves gitea.gitea_api", and failed its plan; the forge answered again seconds later. A re-serve takes
-// about 10 s, so 60 s waits one out with room to spare. It is a cap on the whole wait, an ask in flight included:
-// the registration holds the controller's one receive loop while it waits, and a loop held two minutes reads as
-// deaf. The pauses are those the build machine waits the registry with (novox/hq issue 457).
-var forgeWait = waitOut{bound: 60 * time.Second, first: time.Second, most: 10 * time.Second,
-	now: time.Now, sleep: sleepOrDone}
-
-// sleepOrDone pauses for d, or less when ctx ends first.
-func sleepOrDone(ctx context.Context, d time.Duration) error {
-	t := time.NewTimer(d)
-	defer t.Stop()
-	select {
-	case <-ctx.Done():
-		return ctx.Err()
-	case <-t.C:
-		return nil
-	}
-}
-
-// forgeNotNow is an answer that says the forge's tool is not served now — the tool runner re-serving — not that
-// the forge refused. Only that is asked again: a refusal, an unreadable answer or a repository with no id is the
-// forge's word, and a tool that did not answer in time has already held the receive loop its whole wait.
-func forgeNotNow(err error) bool { return errors.Is(err, link.ErrNothingServes) }
-
-// forgeWaitedOut asks the forge about repository, asking again while it answers "not served now", all of it
-// within w's bound, an ask in flight included (novox/hq issue 486). Past the bound it fails, saying it waited,
-// for how long, and what the forge last said; when the caller's own context ends, it says that instead.
-func forgeWaitedOut(ctx context.Context, w waitOut, repository string,
-	ask func(context.Context) (forgeFacts, error)) (forgeFacts, error) {
-	capped, cancel := context.WithTimeout(ctx, w.bound)
-	defer cancel()
-	began := w.now()
-	pause := w.first
-	for asked := 1; ; asked++ {
-		facts, err := ask(capped)
-		if err == nil {
-			if asked > 1 {
-				fmt.Printf("the forge answered about %s again, after %s (novox/hq issue 486)\n", repository,
-					w.now().Sub(began).Round(time.Second))
-			}
-			return facts, nil
-		}
-		if ctx.Err() != nil {
-			return forgeFacts{}, err // the caller's own context ended: no wait of ours to speak of
-		}
-		gaveUp := func() (forgeFacts, error) {
-			return forgeFacts{}, fmt.Errorf("waited %s for the forge to answer about %s, asking %d times, and it "+
-				"did not (novox/hq issue 486): %w", w.now().Sub(began).Round(time.Second), repository, asked, err)
-		}
-		if capped.Err() != nil {
-			return gaveUp() // the bound ended an ask in flight
-		}
-		if !forgeNotNow(err) {
-			return forgeFacts{}, err
-		}
-		if w.now().Sub(began)+pause > w.bound {
-			return gaveUp()
-		}
-		fmt.Printf("the forge cannot be asked about %s now (%v); asking again in %s, for at most %s in all "+
-			"(novox/hq issue 486)\n", repository, err, pause, w.bound)
-		if serr := w.sleep(capped, pause); serr != nil {
-			if ctx.Err() != nil {
-				return forgeFacts{}, fmt.Errorf("stopped waiting for the forge to answer about %s: %w", repository,
-					ctx.Err())
-			}
-			return gaveUp()
-		}
-		pause = min(2*pause, w.most)
-	}
-}
-
-// askTheForgeOnce asks the forge once, through its module's tools on the bus.
-func askTheForgeOnce(ctx context.Context, owner, repo, branch string) (forgeFacts, error) {
-	js, err := aBus()
-	if err != nil {
-		return forgeFacts{}, err
-	}
-	defer js.Close()
-	bus := link.OverNATS{Conn: js.Conn()}
-	ask := func(tool string, args map[string]any, into any) error {
-		raw, _ := json.Marshal(args)
-		answer, err := link.Ask(ctx, bus, "gitea", tool, raw, 30*time.Second)
-		if err != nil {
-			return err
-		}
-		if answer.Error != "" {
-			return fmt.Errorf("gitea.%s: %s", tool, answer.Error)
-		}
-		return json.Unmarshal(answer.Result, into)
-	}
-	var found struct {
-		Result struct {
-			ID       int64  `json:"id"`
-			FullName string `json:"full_name"`
-		} `json:"result"`
-	}
-	if err := ask("gitea_api", map[string]any{"path": "/repos/" + owner + "/" + repo}, &found); err != nil {
-		return forgeFacts{}, err
-	}
-	if found.Result.ID == 0 {
-		return forgeFacts{}, fmt.Errorf("the forge named no id for %s/%s", owner, repo)
-	}
-	var rules struct {
-		Rules []protectionRule `json:"rules"`
-	}
-	if err := ask("gitea_branch_protection_get", map[string]any{"owner": owner, "repo": repo}, &rules); err != nil {
-		return forgeFacts{}, err
-	}
-	facts := judgedRule(rules.Rules, branch)
-	facts.ID = found.Result.ID
-	return facts, nil
-}
-
-// protectionRule is a branch protection rule as the forge's tool summarises it.
-type protectionRule struct {
-	Rule             string   `json:"rule"`
-	Push             bool     `json:"push"`
-	RequiredStatuses []string `json:"required_statuses"`
-	AdminMayOverride bool     `json:"admin_may_override"`
-}
-
-// judgedRule judges the one rule the forge applies to a branch, as the forge picks it: the rule named for the
-// branch, else the first glob rule, in the forge's order, that covers it (gitea's first matching rule). Never a
-// later rule that happens to be stronger: the forge does not read it.
-func judgedRule(rules []protectionRule, branch string) forgeFacts {
-	var applied *protectionRule
-	for i := range rules {
-		if rules[i].Rule == branch {
-			applied = &rules[i]
-			break
-		}
-	}
-	if applied == nil {
-		for i := range rules {
-			if ruleCovers(rules[i].Rule, branch) {
-				applied = &rules[i]
-				break
-			}
-		}
-	}
-	switch r := applied; {
-	case r == nil:
-		return forgeFacts{Why: fmt.Sprintf("no protection rule covers %s", branch)}
-	case r.Push:
-		return forgeFacts{Why: fmt.Sprintf("the rule %s lets a person push to %s directly", r.Rule, branch)}
-	case len(r.RequiredStatuses) == 0:
-		return forgeFacts{Why: fmt.Sprintf("the rule %s requires no status before a merge into %s", r.Rule, branch)}
-	case r.AdminMayOverride:
-		return forgeFacts{Why: fmt.Sprintf("the rule %s lets an administrator merge into %s past a status", r.Rule, branch)}
-	}
-	return forgeFacts{Guarded: true}
-}
-
-// ruleCovers says a protection rule's name — a branch, or a glob of them — covers a branch, as the forge reads it.
-func ruleCovers(rule, branch string) bool {
-	if rule == branch {
-		return true
-	}
-	if !strings.ContainsAny(rule, "*?[") {
-		return false
-	}
-	var re strings.Builder
-	re.WriteString("^")
-	for i := 0; i < len(rule); i++ {
-		switch c := rule[i]; {
-		case c == '*' && i+1 < len(rule) && rule[i+1] == '*':
-			re.WriteString(".*")
-			i++
-		case c == '*':
-			re.WriteString("[^/]*")
-		case c == '?':
-			re.WriteString("[^/]")
-		default:
-			re.WriteString(regexp.QuoteMeta(string(c)))
-		}
-	}
-	re.WriteString("$")
-	ok, _ := regexp.MatchString(re.String(), branch)
-	return ok
-}
-
-// onTheForge is a source's owner and name on the mesh's own forge (the git seat's holder), and whether it is
-// there at all.
-func (f *sourceForms) onTheForge(repository, seat string) (owner, name string, ok bool) {
-	var rest string
-	switch {
-	case seat == gitSeat:
-		rest = strings.Trim(repository, "/")
-	case seat == "":
-		base := f.base(gitSeat)
-		if base == "" {
-			return "", "", false
-		}
-		url, prefix := f.canonical(repository, ""), f.canonical(base, "")+"/"
-		if !strings.HasPrefix(url, prefix) {
-			return "", "", false
-		}
-		// The case the forge spells it with: the URL as given, past the base.
-		rest = strings.TrimSuffix(strings.Trim(repository[len(prefix):], "/"), ".git")
-	default:
-		return "", "", false
-	}
-	parts := strings.Split(rest, "/")
-	if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
-		return "", "", false
-	}
-	return parts[0], parts[1], true
-}
-
-// mayRegisterFrom says whether a build's outcome may register module from the source it was built from, and the
-// forge's id of that repository to record (novox/hq ADR 0266). Through any verb, only:
-//
-//   - from the module's registered repository — the same repository by the forge's own id, not only its name; or,
-//     for a module new to the catalogue, from a repository the catalogue builds another module from;
-//   - and from a repository on the mesh's forge whose trunk is protected as a trunk must be: no direct push, at
-//     least one required status, no administrator merging past one.
-//
-// Anything else only when the build request was kept as asked at the controller's terminal, for this very
-// repository and path. path is the module's directory as built; branch the trunk it is registered from.
-func mayRegisterFrom(ctx context.Context, inv *inventory.Inventory, module string, built inventory.Source,
-	buildID, path, branch string) (int64, error) {
-	forms := newSourceForms(ctx, inv)
-	was, err := inv.SourceOf(ctx, module)
-	isNew := errors.Is(err, inventory.ErrNoSuchModule)
-	if err != nil && !isNew {
-		return 0, err
-	}
-	terminal, err := askedHereFor(ctx, inv, forms, buildID, built, path)
-	if err != nil {
-		return 0, err
-	}
-	refuse := func(why string) (int64, error) {
-		return 0, fmt.Errorf("%w: %s. A module is registered from such a source only by a build asked at the "+
-			"controller's terminal, never through a verb: a registered module is what the next push sends, and whoever "+
-			"may call a verb includes agents (novox/hq ADR 0266)", errNotItsSource, why)
-	}
-
-	var why string
-	var alongside []inventory.Entry // the modules a new one's repository already builds
-	switch {
-	case !isNew && forms.same(was.Repository, was.Seat, built.Repository, built.Seat):
-	case !isNew:
-		registered := was.Repository
-		if registered == "" {
-			registered = "no repository (it was handed over by hand)"
-		}
-		why = fmt.Sprintf("%s is built from %s, and this build is of %s", module, sourceWords(registered, was.Seat),
-			sourceWords(built.Repository, built.Seat))
-	default:
-		entries, err := inv.Catalogued(ctx)
-		if err != nil {
-			return 0, err
-		}
-		for _, e := range entries {
-			if !e.Provided && e.Source.Repository != "" &&
-				forms.same(e.Source.Repository, e.Source.Seat, built.Repository, built.Seat) {
-				alongside = append(alongside, e)
-			}
-		}
-		if len(alongside) == 0 {
-			why = fmt.Sprintf("%s is new to the catalogue, and %s is no repository the catalogue builds a module from",
-				module, sourceWords(built.Repository, built.Seat))
-		}
-	}
-	if why != "" && !terminal {
-		return refuse(why)
-	}
-
-	owner, name, onForge := forms.onTheForge(built.Repository, built.Seat)
-	if !onForge {
-		if terminal {
-			fmt.Printf("%s: %s is not on the mesh's forge — registered, as asked at the controller's terminal\n",
-				buildID, sourceWords(built.Repository, built.Seat))
-			return 0, nil
-		}
-		return refuse(fmt.Sprintf("%s is not on the mesh's forge, so whether its trunk is protected cannot be read",
-			sourceWords(built.Repository, built.Seat)))
-	}
-	facts, err := askTheForge(ctx, owner, name, branch)
-	if err != nil {
-		if terminal {
-			fmt.Printf("%s: the forge could not be asked about %s/%s (%v) — registered, as asked at the controller's "+
-				"terminal\n", buildID, owner, name, err)
-			return 0, nil
-		}
-		return refuse(fmt.Sprintf("the forge could not say whether %s/%s's %s is protected: %v", owner, name, branch, err))
-	}
-	if terminal {
-		if why != "" || !facts.Guarded {
-			fmt.Printf("%s: %s — registered, as asked at the controller's terminal\n", buildID,
-				strings.Trim(why+"; "+facts.Why, "; "))
-		}
-		return facts.ID, nil
-	}
-	if !facts.Guarded {
-		return refuse(fmt.Sprintf("%s/%s's %s is not protected as a module's trunk must be: %s", owner, name, branch,
-			facts.Why))
-	}
-	// The same repository by the forge's id, not only its name: one deleted and made again is another.
-	recorded := map[string]int64{}
-	if !isNew {
-		id, err := inv.SourceIdentity(ctx, module)
-		if err != nil {
-			return 0, err
-		}
-		recorded[module] = id
-	}
-	for _, e := range alongside {
-		id, err := inv.SourceIdentity(ctx, e.Manifest.Module)
-		if err != nil {
-			return 0, err
-		}
-		recorded[e.Manifest.Module] = id
-	}
-	for m, id := range recorded {
-		if id != 0 && id != facts.ID {
-			return refuse(fmt.Sprintf("%s/%s is not the repository %s was registered from: the forge knows it as "+
-				"repository %d, and %s was registered from repository %d — one of that name deleted and made again",
-				owner, name, m, facts.ID, m, id))
-		}
-	}
-	return facts.ID, nil
-}
-
-// askedHereFor says the build was asked at the controller's terminal, for this repository and this path: a kept
-// request marked so, whose source is the outcome's (novox/hq ADR 0266).
-func askedHereFor(ctx context.Context, inv *inventory.Inventory, forms *sourceForms, buildID string,
-	built inventory.Source, path string) (bool, error) {
-	r, found, err := inv.BuildRequestByID(ctx, buildID)
-	if err != nil || !found || !r.AtTerminal {
-		return false, err
-	}
-	if !forms.same(r.Repository, r.Seat, built.Repository, built.Seat) ||
-		strings.Trim(r.Path, "/") != strings.Trim(path, "/") {
-		fmt.Printf("%s was asked at the terminal of %s at %q, and its outcome is of %s at %q: not the terminal's\n",
-			buildID, sourceWords(r.Repository, r.Seat), r.Path, sourceWords(built.Repository, built.Seat), path)
-		return false, nil
-	}
-	return true, nil
-}
-
-// sourceWords is a source as a person reads it.
-func sourceWords(repository, seat string) string {
-	if seat == "" {
-		return repository
-	}
-	return buildSource{Repository: repository, Seat: seat}.String()
-}
-
-// verbMayAsk refuses, for a call through a verb, a build of a repository the catalogue builds no module from
-// (novox/hq ADR 0266): the build node would run what an agent wrote, and its outcome could never be
-// registered anyway. url is the repository as it is cloned. At the terminal anything may be asked.
-func verbMayAsk(ctx context.Context, source buildSource, url string) error {
-	if startedAtTheTerminal() {
-		return nil
-	}
-	open, err := openStores(ctx)
-	if err != nil {
-		return err
-	}
-	defer open.Close()
-	entries, err := open.inventory.Catalogued(ctx)
-	if err != nil {
-		return err
-	}
-	forms := newSourceForms(ctx, open.inventory)
-	if forms.buildsFrom(entries, source.Repository, source.Seat) || forms.buildsFrom(entries, url, "") {
-		return nil
-	}
-	return terminalRefusal("%s is no repository the catalogue builds a module from, and a build of any other is "+
-		"asked at the controller's terminal only, never through a verb: a build node runs what the repository "+
-		"says, and its outcome would register a module the next push sends — whoever may call a verb includes "+
-		"agents (novox/hq ADR 0266). Nothing was asked", source)
-}

cmd/mesh-controller/build_source_test.go

@@ -1,384 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"hash/fnv"
-	"os"
-	"os/exec"
-	"slices"
-	"strings"
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// The routes to root a review of ADR 0266 found (novox/hq ADR 0266 §7): an agent makes a repository of its
-// own — or forks one the mesh builds from — commits a module.json naming a module the mesh runs everywhere
-// (`sudo`, granting itself a rule without a password; `mesh-host`, the node-engine), and asks the `build` verb
-// for it. Its outcome was registered under that name from the agent's repository, and the next push sent it.
-
-// onTrunk is an outcome of a commit on its repository's trunk, as the build seat says it.
-func onTrunk(id, repository, seat, path string, manifest map[string]any) link.BuildResult {
-	raw, _ := json.Marshal(manifest)
-	r := link.BuildResult{ID: id, Repository: "http://forge.internal:20000/" + repository + ".git", Path: path,
-		Ref: "main", On: "anchor", Commit: "c0ffee0123456789", Manifest: raw,
-		Trunk: "main", OnTrunk: true, Branches: []string{"main"}}
-	if seat != "" {
-		r.Source = &link.SourceOnSeat{Seat: seat, Repository: repository}
-	}
-	return r
-}
-
-// keptAsked keeps a build request as the asker would: through a verb, or at the terminal.
-func keptAsked(t *testing.T, inv *inventory.Inventory, id, repository, path string, atTerminal bool) {
-	t.Helper()
-	if err := inv.RecordBuildRequest(t.Context(), inventory.BuildRequest{ID: id, Repository: repository, Seat: "git",
-		Path: path, For: "build", AtTerminal: atTerminal}); err != nil {
-		t.Fatal(err)
-	}
-}
-
-// theCatalogue is a mesh whose sudo is built from the catalogue repository and whose node-engine from its own.
-func theCatalogue(t *testing.T) *stores {
-	t.Helper()
-	open := aMesh(t)
-	ctx := t.Context()
-	for _, b := range []link.BuildResult{
-		onTrunk("build-sudo", "novox/mesh-catalog", "git", "modules/sudo", map[string]any{"module": "sudo", "version": "1"}),
-		onTrunk("build-host", "novox/mesh-host", "git", "", map[string]any{"module": "mesh-host", "version": "1"}),
-	} {
-		keptAsked(t, open.inventory, b.ID, b.Source.Repository, b.Path, true)
-		if _, _, err := takeIn(ctx, open.inventory, b); err != nil {
-			t.Fatal(err)
-		}
-	}
-	return open
-}
-
-func TestABuildFromAnAgentsRepositoryIsNotRegisteredAsAModuleTheMeshHolds(t *testing.T) {
-	open := theCatalogue(t)
-	ctx := t.Context()
-	for _, c := range []struct {
-		name, repository, path, module string
-	}{
-		{"its own repository naming sudo", "agent/sudo", "modules/sudo", "sudo"},
-		{"a fork of the catalogue", "agent/mesh-catalog", "modules/sudo", "sudo"},
-		{"a fork of the node-engine", "agent/mesh-host", "", "mesh-host"},
-	} {
-		t.Run(c.name, func(t *testing.T) {
-			id := "build-" + strings.ReplaceAll(c.repository, "/", "-")
-			keptAsked(t, open.inventory, id, c.repository, c.path, false) // through the build verb
-			evil := onTrunk(id, c.repository, "git", c.path, map[string]any{"module": c.module, "version": "evil"})
-			_, _, err := takeIn(ctx, open.inventory, evil)
-			if !errors.Is(err, errNotItsSource) {
-				t.Fatalf("a build of %s was taken in as %s: %v", c.repository, c.module, err)
-			}
-			shelf, err := open.inventory.Catalogue(ctx)
-			if err != nil {
-				t.Fatal(err)
-			}
-			if got := shelf[c.module].Version; got != "1" {
-				t.Fatalf("%s is now %q, from %s", c.module, got, c.repository)
-			}
-			if _, found, _ := open.inventory.BuildByID(ctx, id); !found {
-				t.Errorf("the refused build %s is not recorded", id)
-			}
-		})
-	}
-}
-
-func TestANewModuleFromARepositoryTheCatalogueDoesNotBuildFromIsNotRegistered(t *testing.T) {
-	open := theCatalogue(t)
-	ctx := t.Context()
-	keptAsked(t, open.inventory, "build-new", "agent/tools", "", false)
-	_, _, err := takeIn(ctx, open.inventory, onTrunk("build-new", "agent/tools", "git", "",
-		map[string]any{"module": "agent-tools", "version": "1"}))
-	if !errors.Is(err, errNotItsSource) {
-		t.Fatalf("a new module from an agent's repository was taken in: %v", err)
-	}
-	// And one asked of nobody here — an outcome on the bus no request was kept for — the same.
-	_, _, err = takeIn(ctx, open.inventory, onTrunk("build-unasked", "agent/tools", "git", "",
-		map[string]any{"module": "agent-tools", "version": "1"}))
-	if !errors.Is(err, errNotItsSource) {
-		t.Fatalf("an outcome nobody asked for was taken in: %v", err)
-	}
-	if shelf, _ := open.inventory.Catalogue(ctx); shelf["agent-tools"].Module != "" {
-		t.Fatal("the refused module is in the catalogue")
-	}
-}
-
-// The operator at the terminal may still move a module, or add one from a new repository.
-func TestAtTheTerminalAnotherRepositoryIsRegistered(t *testing.T) {
-	open := theCatalogue(t)
-	ctx := t.Context()
-	keptAsked(t, open.inventory, "build-moved", "novox/sudo", "", true)
-	if _, _, err := takeIn(ctx, open.inventory, onTrunk("build-moved", "novox/sudo", "git", "",
-		map[string]any{"module": "sudo", "version": "2"})); err != nil {
-		t.Fatalf("a move the operator asked for at the terminal was refused: %v", err)
-	}
-	if src, _ := open.inventory.SourceOf(ctx, "sudo"); src.Repository != "novox/sudo" {
-		t.Fatalf("sudo is built from %q", src.Repository)
-	}
-	if err := open.inventory.RecordBuildRequest(ctx, inventory.BuildRequest{ID: "build-external",
-		Repository: "http://forge.internal:20000/someone/app.git", For: "build", AtTerminal: true}); err != nil {
-		t.Fatal(err)
-	}
-	if _, _, err := takeIn(ctx, open.inventory, onTrunk("build-external", "someone/app", "", "",
-		map[string]any{"module": "app", "version": "1"})); err != nil {
-		t.Fatalf("a new module the operator asked for at the terminal was refused: %v", err)
-	}
-}
-
-// The delivery's flow is untouched: a merge's rebuild of a module from its own repository, and a merge adding
-// a module to a repository the catalogue builds from (novox/hq issue 300), are registered with no terminal.
-func TestADeliveryFromTheRegisteredRepositoryIsRegistered(t *testing.T) {
-	open := theCatalogue(t)
-	ctx := t.Context()
-	rebuilt := onTrunk("build-plan", "novox/mesh-catalog", "git", "modules/sudo", map[string]any{"module": "sudo", "version": "2"})
-	if err := open.inventory.RecordBuildRequest(ctx, inventory.BuildRequest{ID: rebuilt.ID,
-		Repository: "novox/mesh-catalog", Seat: "git", Path: "modules/sudo", For: "plan"}); err != nil {
-		t.Fatal(err)
-	}
-	if _, _, err := takeIn(ctx, open.inventory, rebuilt); err != nil {
-		t.Fatalf("a plan's build of the module's own repository was refused: %v", err)
-	}
-	added := onTrunk("build-merge", "novox/mesh-catalog", "git", "modules/zram", map[string]any{"module": "zram", "version": "1"})
-	if _, _, err := takeIn(ctx, open.inventory, added); err != nil {
-		t.Fatalf("a module a merge added to the catalogue repository was refused: %v", err)
-	}
-	shelf, _ := open.inventory.Catalogue(ctx)
-	if shelf["sudo"].Version != "2" || shelf["zram"].Module == "" {
-		t.Fatalf("not registered: sudo %q, zram %q", shelf["sudo"].Version, shelf["zram"].Module)
-	}
-}
-
-// Through a verb, a build of a repository the catalogue builds nothing from is not even asked: the build node
-// would run what the agent wrote.
-func TestAVerbAsksNoBuildOfARepositoryTheCatalogueDoesNotBuildFrom(t *testing.T) {
-	theCatalogue(t)
-	ctx := t.Context()
-	t.Setenv(verbVar, "build")
-	t.Setenv(link.CallerVar, "node-tools.anchor, through the mesh-controller seat")
-	err := verbMayAsk(ctx, buildSource{Repository: "agent/sudo", Seat: "git"}, "http://forge.internal:20000/agent/sudo.git")
-	var policy *heldAtTheTerminal
-	if !errors.As(err, &policy) {
-		t.Fatalf("a verb's build of an agent's repository was asked: %v", err)
-	}
-	if err := verbMayAsk(ctx, buildSource{Repository: "novox/mesh-catalog", Seat: "git"},
-		"http://forge.internal:20000/novox/mesh-catalog.git"); err != nil {
-		t.Fatalf("a verb's build of the catalogue repository was refused: %v", err)
-	}
-	t.Setenv(verbVar, "")
-	t.Setenv(link.CallerVar, "")
-	if err := verbMayAsk(ctx, buildSource{Repository: "agent/sudo", Seat: "git"}, ""); err != nil {
-		t.Fatalf("the terminal was refused: %v", err)
-	}
-}
-
-// asTheOperator keeps a build as asked at the controller's terminal, as the operator's first build of a module
-// from a repository the catalogue does not yet build from is (novox/hq ADR 0266), and hands it back.
-func asTheOperator(t *testing.T, inv *inventory.Inventory, b link.BuildResult) link.BuildResult {
-	t.Helper()
-	repository, seat := b.Repository, ""
-	if b.Source != nil {
-		repository, seat = b.Source.Repository, b.Source.Seat
-	}
-	if err := inv.RecordBuildRequest(t.Context(), inventory.BuildRequest{ID: b.ID, Repository: repository, Seat: seat,
-		Path: b.Path, For: "build", AtTerminal: true}); err != nil {
-		t.Fatal(err)
-	}
-	return b
-}
-
-// A rollback puts back only a build of the module's own repository: an agent's build of the module's name,
-// recorded and refused, at the very commit the machine ran before (a fork carries it), is never registered by
-// the back door of a failed gate.
-func TestARollbackNeverPutsBackABuildFromAnotherRepository(t *testing.T) {
-	open := theCatalogue(t)
-	ctx := t.Context()
-	inv := open.inventory
-	fork := onTrunk("build-1791500000000000000", "agent/mesh-catalog", "git", "modules/sudo",
-		map[string]any{"module": "sudo", "version": "evil"})
-	fork.Commit = "c0ffee0123456789" // the commit sudo was registered at
-	keptAsked(t, inv, fork.ID, "agent/mesh-catalog", "modules/sudo", false)
-	if _, _, err := takeIn(ctx, inv, fork); !errors.Is(err, errNotItsSource) {
-		t.Fatalf("the fork's build was taken in: %v", err)
-	}
-	// Asked after the registered build, whenever the test runs: an id naming a fixed moment read as older
-	// than the registered build once the clock passed it (2026-10-10 02:40 UTC), and the test failed on main.
-	failed := onTrunk(fmt.Sprintf("build-%d", time.Now().Add(time.Hour).UnixNano()), "novox/mesh-catalog", "git", "modules/sudo",
-		map[string]any{"module": "sudo", "version": "2"})
-	failed.Commit = "badbadbad0123456"
-	if _, _, err := takeIn(ctx, inv, failed); err != nil {
-		t.Fatal(err)
-	}
-	record, _, err := inv.BuildByID(ctx, failed.ID)
-	if err != nil {
-		t.Fatal(err)
-	}
-	previous, found, err := inv.PreviousBuild(ctx, "sudo", "c0ffee0123456789", record)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if found && previous.ID == fork.ID {
-		t.Fatalf("a rollback would put back the fork's build %s", previous.ID)
-	}
-	if !found || previous.ID != "build-sudo" {
-		t.Fatalf("a rollback puts back %q (found %v), want the registered build-sudo", previous.ID, found)
-	}
-}
-
-// theForge is what the forge says in a test, by owner/name: a repository not named here is protected as a
-// trunk must be, with an id of its own.
-var theForge sync.Map
-
-func init() {
-	askTheForge = func(_ context.Context, owner, repo, _ string) (forgeFacts, error) {
-		if said, ok := theForge.Load(owner + "/" + repo); ok {
-			switch f := said.(type) {
-			case error:
-				return forgeFacts{}, f
-			case forgeFacts:
-				return f, nil
-			}
-		}
-		h := fnv.New32a()
-		_, _ = h.Write([]byte(owner + "/" + repo))
-		return forgeFacts{ID: int64(h.Sum32()), Guarded: true}, nil
-	}
-}
-
-// A module's trunk the forge does not protect — direct pushes, no required status — or a forge that cannot say,
-// registers nothing through a verb: the trunk rule means nothing on a branch anyone pushes to.
-func TestATrunkTheForgeDoesNotProtectRegistersNothing(t *testing.T) {
-	open := theCatalogue(t)
-	ctx := t.Context()
-	theForge.Store("novox/unguarded", forgeFacts{ID: 7, Why: "the rule main lets a person push to main directly"})
-	t.Cleanup(func() { theForge.Delete("novox/unguarded") })
-	first := onTrunk("build-unguarded-1", "novox/unguarded", "git", "", map[string]any{"module": "unguarded", "version": "1"})
-	keptAsked(t, open.inventory, first.ID, "novox/unguarded", "", true)
-	if _, _, err := takeIn(ctx, open.inventory, first); err != nil {
-		t.Fatalf("at the terminal: %v", err)
-	}
-	again := onTrunk("build-unguarded-2", "novox/unguarded", "git", "", map[string]any{"module": "unguarded", "version": "2"})
-	if _, _, err := takeIn(ctx, open.inventory, again); !errors.Is(err, errNotItsSource) ||
-		!strings.Contains(err.Error(), "push to main directly") {
-		t.Fatalf("a rebuild from an unprotected trunk was taken in: %v", err)
-	}
-	theForge.Store("novox/unguarded", errors.New("nothing serves gitea.gitea_api"))
-	if _, _, err := takeIn(ctx, open.inventory, onTrunk("build-unguarded-3", "novox/unguarded", "git", "",
-		map[string]any{"module": "unguarded", "version": "3"})); !errors.Is(err, errNotItsSource) {
-		t.Fatalf("a forge that could not say was read as a protected trunk: %v", err)
-	}
-	if shelf, _ := open.inventory.Catalogue(ctx); shelf["unguarded"].Version != "1" {
-		t.Fatalf("unguarded is %q", shelf["unguarded"].Version)
-	}
-}
-
-// A repository deleted and made again under the module's repository's name is another repository: the forge's
-// id, recorded at registration, tells them apart.
-func TestARepositoryMadeAgainUnderItsNameIsNotTheModulesSource(t *testing.T) {
-	open := theCatalogue(t)
-	ctx := t.Context()
-	theForge.Store("novox/remade", forgeFacts{ID: 100, Guarded: true})
-	t.Cleanup(func() { theForge.Delete("novox/remade") })
-	first := onTrunk("build-remade-1", "novox/remade", "git", "", map[string]any{"module": "remade", "version": "1"})
-	keptAsked(t, open.inventory, first.ID, "novox/remade", "", true)
-	if _, _, err := takeIn(ctx, open.inventory, first); err != nil {
-		t.Fatal(err)
-	}
-	if id, _ := open.inventory.SourceIdentity(ctx, "remade"); id != 100 {
-		t.Fatalf("the forge's id was not recorded: %d", id)
-	}
-	theForge.Store("novox/remade", forgeFacts{ID: 101, Guarded: true}) // deleted, and made again by an agent
-	if _, _, err := takeIn(ctx, open.inventory, onTrunk("build-remade-2", "novox/remade", "git", "",
-		map[string]any{"module": "remade", "version": "evil"})); !errors.Is(err, errNotItsSource) ||
-		!strings.Contains(err.Error(), "made again") {
-		t.Fatalf("a repository made again under the name was taken in: %v", err)
-	}
-	// And a new module from it, beside the one registered from the first, the same.
-	if _, _, err := takeIn(ctx, open.inventory, onTrunk("build-remade-3", "novox/remade", "git", "modules/other",
-		map[string]any{"module": "other", "version": "1"})); !errors.Is(err, errNotItsSource) {
-		t.Fatalf("a new module from a repository made again was taken in: %v", err)
-	}
-}
-
-// The terminal's mark is the operator's for the repository and path they asked: an outcome of another, under that
-// build's id, is not theirs.
-func TestATerminalRequestCoversOnlyWhatItAsked(t *testing.T) {
-	open := theCatalogue(t)
-	ctx := t.Context()
-	if err := open.inventory.RecordBuildRequest(ctx, inventory.BuildRequest{ID: "build-asked", Repository: "novox/app",
-		Seat: "git", Path: "modules/app", For: "build", AtTerminal: true}); err != nil {
-		t.Fatal(err)
-	}
-	other := onTrunk("build-asked", "agent/sudo", "git", "modules/app", map[string]any{"module": "sudo", "version": "evil"})
-	if _, _, err := takeIn(ctx, open.inventory, other); !errors.Is(err, errNotItsSource) {
-		t.Fatalf("an outcome of another repository under a terminal request's id was taken in: %v", err)
-	}
-	elsewhere := onTrunk("build-asked", "novox/app", "git", "modules/sudo", map[string]any{"module": "sudo", "version": "evil"})
-	if _, _, err := takeIn(ctx, open.inventory, elsewhere); !errors.Is(err, errNotItsSource) {
-		t.Fatalf("an outcome of another path under a terminal request's id was taken in: %v", err)
-	}
-}
-
-// The serving controller, and everything it starts, is never the terminal: a build asked in it reads as asked
-// through the mesh even when no verb and no caller is named.
-func TestTheServingControllerIsNeverTheTerminal(t *testing.T) {
-	t.Setenv(verbVar, "")
-	t.Setenv(link.CallerVar, "")
-	t.Setenv(servedVar, "")
-	if !startedAtTheTerminal() {
-		t.Fatal("a process started by hand is not the terminal")
-	}
-	markServed()
-	if startedAtTheTerminal() {
-		t.Fatal("the serving controller reads as the terminal")
-	}
-	child := exec.Command(os.Args[0], "-test.run=^$")
-	child.Env = os.Environ()
-	if !slices.Contains(child.Env, servedVar+"=1") {
-		t.Fatal("what the serving controller starts does not carry its mark")
-	}
-}
-
-// The forge applies one rule to a branch: the rule named for it, else the first glob that covers it. A stronger
-// rule later in the list is not what guards the branch, and is not read as if it were (the confirmation review).
-func TestTheRuleJudgedIsTheOneTheForgeApplies(t *testing.T) {
-	guarded := protectionRule{Rule: "*", RequiredStatuses: []string{"mesh/merge-gate"}}
-	open := protectionRule{Rule: "main", Push: true, RequiredStatuses: []string{"mesh/merge-gate"}}
-	if f := judgedRule([]protectionRule{guarded, open}, "main"); f.Guarded {
-		t.Error("an exact rule letting pushes was passed over for a glob that guards")
-	}
-	if f := judgedRule([]protectionRule{{Rule: "ma*", RequiredStatuses: nil}, {Rule: "*", RequiredStatuses: []string{"x"}}},
-		"main"); f.Guarded || !strings.Contains(f.Why, "ma*") {
-		t.Errorf("the first glob covering the branch was not the one judged: %+v", f)
-	}
-	if f := judgedRule([]protectionRule{{Rule: "release/*"}, {Rule: "main", RequiredStatuses: []string{"x"}}}, "main"); !f.Guarded {
-		t.Errorf("the rule named for the branch was not judged: %+v", f)
-	}
-	if f := judgedRule(nil, "main"); f.Guarded {
-		t.Error("no rule is no protection")
-	}
-}
-
-// An id the forge could not give keeps the id already recorded.
-func TestAnUnknownIdentityKeepsTheRecordedOne(t *testing.T) {
-	open := theCatalogue(t)
-	ctx := t.Context()
-	if err := open.inventory.SetSourceIdentity(ctx, "sudo", 100); err != nil {
-		t.Fatal(err)
-	}
-	if err := open.inventory.SetSourceIdentity(ctx, "sudo", 0); err != nil {
-		t.Fatal(err)
-	}
-	if id, _ := open.inventory.SourceIdentity(ctx, "sudo"); id != 100 {
-		t.Fatalf("the recorded id became %d", id)
-	}
-}

cmd/mesh-controller/build_test.go

@@ -1,152 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"errors"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// A build's outcome is taken in the same way whoever hears it (novox/hq issue 176): recorded, and
-// the module registered with its source as the seat and path when the request said so — never the
-// URL. A definition naming an installation is recorded and not registered; a failure is recorded
-// and said.
-func TestABuildHeardIsRecordedAndRegistered(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	manifest, _ := json.Marshal(map[string]any{"module": "shop", "version": "3"})
-	m, _, err := takeIn(ctx, open.inventory, asTheOperator(t, open.inventory, link.BuildResult{
-		ID: "b-1", Repository: "http://forge.internal:20000/novox/shop.git", Path: "modules/shop",
-		Ref: "main", On: "anchor", Commit: "abcdef0123", Manifest: manifest,
-		Source: &link.SourceOnSeat{Seat: "git", Repository: "novox/shop"},
-	}))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if m.Module != "shop" {
-		t.Fatalf("registered %q", m.Module)
-	}
-	shelf, err := open.inventory.Catalogue(ctx)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if _, held := shelf["shop"]; !held {
-		t.Fatal("the module a heard build produced is not in the catalogue")
-	}
-	src, err := open.inventory.SourceOf(ctx, "shop")
-	if err != nil || src.Seat != "git" || src.Repository != "novox/shop" || src.BuiltFrom != "abcdef0123" {
-		t.Fatalf("the source is the seat and the path, never the URL: %+v %v", src, err)
-	}
-	builds, err := open.inventory.Builds(ctx, "shop", 5)
-	if err != nil || len(builds) != 1 || builds[0].ID != "b-1" {
-		t.Fatalf("the build is not recorded once: %v %v", builds, err)
-	}
-
-	named, _ := json.Marshal(map[string]any{"module": "idp", "version": "1", "resources": []any{
-		map[string]any{"id": "server", "type": "container", "image": "x@sha256:aa",
-			"env": map[string]any{"KC_HOSTNAME": "https://login.mesh-one.be"}}}})
-	_, _, err = takeIn(ctx, open.inventory, link.BuildResult{
-		ID: "b-2", Repository: "/r", On: "anchor", Commit: "0123456789", Manifest: named})
-	if err == nil || !strings.Contains(err.Error(), "does not register it") {
-		t.Fatalf("a definition naming an installation was taken in: %v", err)
-	}
-	if shelf, _ := open.inventory.Catalogue(ctx); shelf["idp"].Module != "" {
-		t.Fatal("the refused module was registered anyway")
-	}
-	if builds, _ := open.inventory.Builds(ctx, "idp", 5); len(builds) != 1 {
-		t.Fatalf("the refused build was not recorded: %v", builds)
-	}
-
-	_, _, err = takeIn(ctx, open.inventory, link.BuildResult{ID: "b-3", Repository: "/r", On: "anchor", Failed: "no compiler"})
-	if err == nil || !strings.Contains(err.Error(), "no compiler") {
-		t.Fatalf("a failure is said in the builder's words: %v", err)
-	}
-}
-
-// novox/hq 04-ISSUES/215: a build asked at a commit is recorded as built from that commit, and the
-// module keeps following the branch it followed — a new one, the default branch.
-func TestABuildAtACommitKeepsTheBranchTheModuleFollows(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	manifest, _ := json.Marshal(map[string]any{"module": "unifi", "version": "1"})
-	result := func(id, ref, commit string) link.BuildResult {
-		return link.BuildResult{ID: id, Repository: "http://forge.internal:20000/novox/mesh-catalog.git",
-			Path: "modules/unifi", Ref: ref, On: "anchor", Commit: commit, Manifest: manifest,
-			Source: &link.SourceOnSeat{Seat: "git", Repository: "novox/mesh-catalog"}}
-	}
-	if _, _, err := takeIn(ctx, open.inventory, asTheOperator(t, open.inventory, result("b-1", "main", "1111111aaaa"))); err != nil {
-		t.Fatal(err)
-	}
-	if _, _, err := takeIn(ctx, open.inventory, result("b-2", "9c97a8a", "9c97a8a1d2c3")); err != nil {
-		t.Fatal(err)
-	}
-	src, err := open.inventory.SourceOf(ctx, "unifi")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if src.Ref != "main" || src.BuiltFrom != "9c97a8a1d2c3" {
-		t.Errorf("after a build at a commit the module follows %q, built from %q; want main, 9c97a8a1d2c3", src.Ref, src.BuiltFrom)
-	}
-
-	// One new to the catalogue, first built at a commit, follows the default branch.
-	other, _ := json.Marshal(map[string]any{"module": "letta", "version": "1"})
-	r := result("b-3", "deadbeef", "deadbeefcafe")
-	r.Manifest, r.Path = other, "modules/letta"
-	if _, _, err := takeIn(ctx, open.inventory, r); err != nil {
-		t.Fatal(err)
-	}
-	if src, _ := open.inventory.SourceOf(ctx, "letta"); src.Ref != "" {
-		t.Errorf("a module first built at a commit follows %q, want the default branch", src.Ref)
-	}
-}
-
-// novox/hq 04-ISSUES/219: an older request heard after a newer one is recorded and not registered,
-// so a push sends what the newer request built.
-func TestAnOlderBuildHeardLaterDoesNotReplaceTheNewer(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	older := time.Date(2026, 10, 3, 21, 33, 45, 0, time.UTC)
-	newer := time.Date(2026, 10, 3, 21, 51, 57, 0, time.UTC)
-	result := func(asked time.Time, image string) link.BuildResult {
-		manifest, _ := json.Marshal(map[string]any{"module": "postgres", "version": image})
-		return link.BuildResult{ID: link.NewBuildID(asked), Repository: "http://forge.internal:20000/novox/mesh-catalog.git",
-			Path: "modules/postgres", Ref: "main", On: "anchor", Commit: "efff5415", Manifest: manifest,
-			Source: &link.SourceOnSeat{Seat: "git", Repository: "novox/mesh-catalog"}}
-	}
-	if _, _, err := takeIn(ctx, open.inventory, asTheOperator(t, open.inventory, result(newer, "4bcd5f73"))); err != nil {
-		t.Fatal(err)
-	}
-	_, _, err := takeIn(ctx, open.inventory, result(older, "0ab07fa9"))
-	if !errors.Is(err, inventory.ErrSuperseded) {
-		t.Fatalf("the older request's outcome was taken in as current: %v", err)
-	}
-	shelf, err := open.inventory.Catalogue(ctx)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if got := shelf["postgres"].Version; got != "4bcd5f73" {
-		t.Errorf("postgres is %q; want the newer request's 4bcd5f73", got)
-	}
-	if builds, _ := open.inventory.Builds(ctx, "postgres", 5); len(builds) != 2 {
-		t.Errorf("the late build was not recorded: %v", builds)
-	}
-}
-
-func TestABuildIDSaysWhenItWasAsked(t *testing.T) {
-	at := time.Date(2026, 10, 3, 21, 51, 57, 392539762, time.UTC)
-	if got, ok := link.BuildAskedAt(link.NewBuildID(at)); !ok || !got.Equal(at) {
-		t.Errorf("read back %v %v; want %v", got, ok, at)
-	}
-	if got, ok := link.BuildAskedAt("build-1791064317392539762"); !ok || got.Format(time.TimeOnly) != "21:51:57" {
-		t.Errorf("the incident's id reads as %v %v", got, ok)
-	}
-	for _, id := range []string{"b-1", "build-2", "build-", "build-x", ""} {
-		if _, ok := link.BuildAskedAt(id); ok {
-			t.Errorf("%q read as a request time", id)
-		}
-	}
-}

cmd/mesh-controller/bus_step.go

@@ -1,410 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"flag"
-	"fmt"
-	"sort"
-	"strings"
-	"time"
-
-	"github.com/nats-io/nats.go"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// The bus as a planned step (novox/hq to-be 45 §8, ADR 0227 rule 8, ADR 0236).
-//
-// **A bus upgrade is never rolled out.** The bus carries every declaration, every report and the
-// controller's own lease; a new bus build that does not come up is a mesh nobody can tell anything,
-// and a version whose data format moved (2.10 → 2.11) cannot be undone by putting the old one back.
-// So nothing sends a new bus build on its own: its policy is `record` whatever anyone says (the
-// catalogue's DerivedUpgrade, and `upgrade` refuses a roll-out), a plan builds it and sends nothing, a
-// cascade holds the machine (ADR 0221), and a push naming that machine is refused while a new bus build
-// waits for it (busHeld). The one way is this verb: a person, with why, the streams snapshotted first,
-// whether it can be reverted said before it starts, the step said as `bus-maintenance` while it runs,
-// and every stream, durable consumer and a round trip checked after (H-bus) — or the step said failed,
-// with its snapshot as the way back.
-
-// busStepProbe is the registry's row for the step; its kinds.
-const (
-	busStepProbe         = "DB"
-	kindBusMaintenance   = "bus-maintenance"
-	kindBusUpgradeFailed = "bus-upgrade-failed"
-)
-
-// busStepBound is how long after its start a bus upgrade must be followed by a healthy bus.
-var busStepBound = 15 * time.Minute
-
-// takeBusSnapshot snapshots every stream before a bus upgrade and answers where the snapshot is: the bus
-// machine's backup holder backs the bus module up now, whose dump is the streams' snapshot (novox/hq ADR
-// 0235). A variable so a test takes none. A person who took one by hand says where with --snapshot-taken,
-// and then none is taken — for a bus whose module does not yet carry the snapshot program.
-var takeBusSnapshot = snapshotTheBusNow
-
-// busPending is what a bus upgrade would do: the bus's module, the machines running it, and, per
-// machine, the build it was last sent against the build the mesh holds. Empty machines: the mesh holds
-// no bus module.
-type busPending struct {
-	module   string
-	machines []string
-	from     map[string]string
-	to       string
-	// same are the commits whose build was made from the same source as the build the mesh holds, or
-	// made the same artifacts and manifest (novox/hq issue 280).
-	same map[string]bool
-}
-
-// moves is whether sending the machine would replace its bus: a build it was not last sent, unless the
-// two builds were made from the same source, or made the same artifacts from the same manifest — a
-// rebuild of the same source for another module's merge changes nothing the machine runs, whatever
-// image digest it made (novox/hq issue 280).
-func (b busPending) moves(machine string) bool {
-	from, known := b.from[machine]
-	if b.module == "" || b.to == "" || (known && sameCommit(from, b.to)) {
-		return false
-	}
-	return !known || !b.same[from]
-}
-
-// pendingBus reads what a bus upgrade would do.
-func pendingBus(ctx context.Context, inv *inventory.Inventory) (busPending, error) {
-	var b busPending
-	shelf, err := inv.Catalogue(ctx)
-	if err != nil {
-		return b, err
-	}
-	for name, m := range shelf {
-		if catalogue.ProvidesBus(m) {
-			b.module = name
-		}
-	}
-	if b.module == "" {
-		return b, nil
-	}
-	current, err := inv.CurrentBuilds(ctx)
-	if err != nil {
-		return b, err
-	}
-	b.to = current[b.module].Commit
-	if b.machines, err = inv.Running(ctx, b.module); err != nil {
-		return b, err
-	}
-	b.from, b.same = map[string]string{}, map[string]bool{}
-	made, err := inv.BuildFingerprints(ctx, b.module)
-	if err != nil {
-		return b, err
-	}
-	for commit, refs := range made {
-		b.same[commit] = refs != "" && refs == made[b.to]
-	}
-	sources, err := inv.BuildSourceFingerprints(ctx, b.module)
-	if err != nil {
-		return b, err
-	}
-	for commit, src := range sources {
-		if src != "" && src == sources[b.to] {
-			b.same[commit] = true
-		}
-	}
-	for _, n := range b.machines {
-		sent, known, err := inv.SentBuilds(ctx, n)
-		if err != nil {
-			return b, err
-		}
-		if known {
-			if c, carried := sent[b.module]; carried {
-				b.from[n] = c
-			}
-		}
-	}
-	return b, nil
-}
-
-// busHeld names the machines a push may not send because sending them would replace the bus: the
-// planned step's, not a push's (ADR 0236). Said with the remedy.
-func busHeld(ctx context.Context, inv *inventory.Inventory, machines []string) (map[string]string, error) {
-	b, err := pendingBus(ctx, inv)
-	if err != nil {
-		return nil, err
-	}
-	out := map[string]string{}
-	for _, n := range machines {
-		for _, holder := range b.machines {
-			if n == holder && b.moves(n) {
-				out[n] = fmt.Sprintf("sending %s would replace the bus (%s %s → %s), which is a planned step: "+
-					"`bus upgrade --why …` snapshots its streams first and checks them after (novox/hq ADR 0236)",
-					n, b.module, short(orNotKnown(b.from[n])), short(b.to))
-			}
-		}
-	}
-	return out, nil
-}
-
-// busCommand is `bus` — what a bus upgrade would do and how the last went — and `bus upgrade`.
-func busCommand(ctx context.Context, args []string) error {
-	sub := ""
-	if len(args) > 0 && !strings.HasPrefix(args[0], "-") {
-		sub, args = args[0], args[1:]
-	}
-	set := flag.NewFlagSet("bus", flag.ContinueOnError)
-	snapshot := set.String("snapshot-taken", "", "where the streams' snapshot a person took is, while the mesh takes none itself")
-	reversible := set.Bool("reversible", false, "the new version can be undone by putting the old one back")
-	irreversible := set.Bool("irreversible", false, "the new version cannot be undone by putting the old one back, "+
-		"and this is the person's explicit word that it runs anyway")
-	why := addHandActFlags(set)
-	if rest, err := parseAround(set, args); err != nil {
-		return err
-	} else if len(rest) > 0 {
-		return errors.New("bus [upgrade --why … --reversible|--irreversible [--snapshot-taken <where>]]")
-	}
-	switch sub {
-	case "":
-		return busStatus(ctx)
-	case "upgrade":
-	default:
-		return fmt.Errorf("bus says what a bus upgrade would do, or `bus upgrade` — not %q", sub)
-	}
-	// Everything refused before anything is done.
-	if err := why.require("bus upgrade"); err != nil {
-		return err
-	}
-	if *reversible == *irreversible {
-		return errors.New("bus upgrade says, before it starts, whether the new version can be undone by putting the " +
-			"old one back: --reversible, or --irreversible as your explicit word that it runs anyway (to-be 45 §8). " +
-			"Nothing was done")
-	}
-	open, err := openStores(ctx)
-	if err != nil {
-		return err
-	}
-	defer open.Close()
-	inv := open.inventory
-	b, err := pendingBus(ctx, inv)
-	if err != nil {
-		return err
-	}
-	if b.module == "" {
-		return errors.New("the mesh holds no module that provides its bus: there is nothing to upgrade")
-	}
-	var moving []string
-	for _, n := range b.machines {
-		if b.moves(n) {
-			moving = append(moving, n)
-		}
-	}
-	if len(moving) == 0 {
-		fmt.Printf("every machine running %s runs the build the mesh holds (%s): nothing to upgrade\n", b.module, short(b.to))
-		return nil
-	}
-	where := strings.TrimSpace(*snapshot)
-	if where == "" {
-		for _, n := range moving {
-			fmt.Printf("snapshotting the bus's streams on %s first (its backup holder, ADR 0235)…\n", n)
-			if where, err = takeBusSnapshot(ctx, b.module, n); err != nil {
-				return fmt.Errorf("the streams could not be snapshotted, so the bus is not replaced: %w — a snapshot "+
-					"taken by hand is said with --snapshot-taken <where>", err)
-			}
-		}
-	}
-	from := map[string]bool{}
-	for _, n := range moving {
-		from[orNotKnown(b.from[n])] = true
-	}
-	step, err := inv.StartBusStep(ctx, inventory.BusStep{Module: b.module, Machines: moving,
-		From: strings.Join(sortedKeys(from), ", "), To: b.to, Snapshot: where, Reversible: *reversible,
-		By: link.Caller(), Why: strings.TrimSpace(*why.why)})
-	if err != nil {
-		return err
-	}
-	cause := "bus-upgrade"
-	if strings.TrimSpace(*why.cause) == "" {
-		why.cause = &cause
-	}
-	why.record(ctx, "bus upgrade", append([]string{b.module}, moving...))
-	fmt.Printf("bus upgrade %d: %s %s → %s on %s; streams snapshotted at %s; %s\n", step.ID, b.module, step.From,
-		short(b.to), strings.Join(moving, ", "), where, map[bool]string{true: "reversible: putting the old build back undoes it",
-			false: "NOT reversible: the snapshot is the only way back"}[*reversible])
-	sent, err := sendRollout(withBusStep(withScope(ctx, sendScope{person: true})), open, moving)
-	if err != nil {
-		_ = inv.EndBusStep(ctx, step.ID, "failed", "the send was refused: "+err.Error())
-		return fmt.Errorf("the bus's machine could not be sent its new build: %w — nothing was replaced", err)
-	}
-	fmt.Printf("sent %s; `bus-maintenance` is open until the bus answers healthy again — every stream, every durable "+
-		"consumer, a round trip to the machines (H-bus) — within %s, or the step is said failed with its snapshot "+
-		"as the way back. `bus` says how it went\n", strings.Join(sent, ", "), busStepBound)
-	return nil
-}
-
-// busStatus is `bus`: what an upgrade would do, and the last step.
-func busStatus(ctx context.Context) error {
-	open, err := openStores(ctx)
-	if err != nil {
-		return err
-	}
-	defer open.Close()
-	b, err := pendingBus(ctx, open.inventory)
-	if err != nil {
-		return err
-	}
-	if b.module == "" {
-		fmt.Println("the mesh holds no module that provides its bus")
-	} else {
-		fmt.Printf("the bus is %s, built %s, on %s; never rolled out — a planned step (`bus upgrade`)\n", b.module,
-			short(b.to), orNone(strings.Join(b.machines, ", ")))
-		for _, n := range b.machines {
-			state := "runs it"
-			if b.moves(n) {
-				state = "runs " + short(orNotKnown(b.from[n])) + ": `bus upgrade` replaces it"
-			}
-			fmt.Printf("  %-10s %s\n", n, state)
-		}
-	}
-	fmt.Println("  `bus upgrade` has the bus machine's backup holder snapshot the streams first (ADR 0235)")
-	s, found, err := open.inventory.LatestBusStep(ctx)
-	if err != nil || !found {
-		return err
-	}
-	state := "running since " + s.Started.Local().Format("2006-01-02 15:04")
-	if s.Ended != nil {
-		state = s.Outcome + " at " + s.Ended.Local().Format("2006-01-02 15:04")
-	}
-	fmt.Printf("last step %d: %s → %s on %s by %s (%s): %s; snapshot %s\n", s.ID, s.From, short(s.To),
-		strings.Join(s.Machines, ", "), orNone(s.By), s.Why, state, s.Snapshot)
-	if s.Found != "" {
-		fmt.Printf("  %s\n", s.Found)
-	}
-	return nil
-}
-
-// probeBusStep is DB: a bus upgrade running is said as `bus-maintenance`; the bus healthy again after
-// the machines reported the new build ends it done; past its bound, unhealthy, it ends failed and is
-// said — urgent, with its snapshot — while the bus is still not healthy.
-func probeBusStep(ctx context.Context, d *doctor) ([]conditions.Observation, error) {
-	inv := d.open.inventory
-	s, found, err := inv.LatestBusStep(ctx)
-	if err != nil || !found {
-		return nil, err
-	}
-	if s.Ended != nil && s.Outcome != "failed" {
-		return nil, nil
-	}
-	problems, err := busHealth(ctx, d)
-	if err != nil {
-		return nil, err
-	}
-	reports, err := inv.LastReports(ctx)
-	if err != nil {
-		return nil, err
-	}
-	applied := true
-	for _, r := range reports {
-		for _, n := range s.Machines {
-			if r.Node == n && (!r.Current || r.Outcome != inventory.OutcomeApplied || r.At == nil || r.At.Before(s.Started)) {
-				applied = false
-				problems = append(problems, n+" has not reported the new bus applied")
-			}
-		}
-	}
-	id := s.Module
-	if s.Ended == nil {
-		switch {
-		case applied && len(problems) == 0:
-			return nil, inv.EndBusStep(ctx, s.ID, "done", "the bus answered healthy after the upgrade")
-		case time.Since(s.Started) > busStepBound:
-			found := strings.Join(problems, "; ")
-			if err := inv.EndBusStep(ctx, s.ID, "failed", found); err != nil {
-				return nil, err
-			}
-			s.Found = found
-		default:
-			return []conditions.Observation{{Scope: conditions.ScopeBus, ID: id, Token: "maintenance",
-				Kind: kindBusMaintenance, Severity: conditions.Warning,
-				Summary: fmt.Sprintf("the bus is being upgraded (step %d, %s → %s on %s, by %s: %s); its snapshot is %s",
-					s.ID, s.From, short(s.To), strings.Join(s.Machines, ", "), orNone(s.By), s.Why, s.Snapshot),
-				Said: orNone(strings.Join(problems, "; "))}}, nil
-		}
-	}
-	if len(problems) == 0 {
-		return nil, nil // failed, and healthy since: nothing wrong now
-	}
-	way := "put the old build back"
-	if !s.Reversible {
-		way = "restore the snapshot"
-	}
-	return []conditions.Observation{{Scope: conditions.ScopeBus, ID: id, Token: "upgrade-failed",
-		Kind: kindBusUpgradeFailed, Severity: conditions.Urgent, Resolver: conditions.ResolverOperator,
-		Summary: fmt.Sprintf("the bus upgrade (step %d, %s → %s) did not end healthy within %s: %s — the way back is to %s (%s)",
-			s.ID, s.From, short(s.To), busStepBound, strings.Join(problems, "; "), way, s.Snapshot)}}, nil
-}
-
-func sortedKeys(set map[string]bool) []string {
-	out := make([]string, 0, len(set))
-	for k := range set {
-		out = append(out, k)
-	}
-	sort.Strings(out)
-	return out
-}
-
-// busSnapshotWithin is how long the bus machine's backup holder is given to take the bus's snapshot.
-var busSnapshotWithin = 15 * time.Minute
-
-// snapshotTheBusNow asks the bus machine's backup holder to back the bus module up now — its dump is
-// the streams' snapshot (novox/hq ADR 0235) — and waits until it says a backup newer than the ask:
-// where the snapshot is, as a person reads it. The serving controller's connection, or one of its own.
-func snapshotTheBusNow(ctx context.Context, module, node string) (string, error) {
-	var where string
-	err := onTheBus(func(conn *nats.Conn) error {
-		asked := time.Now()
-		answer, err := link.AskSeatTool(ctx, conn, catalogue.BackupSeat, "now", node,
-			map[string]any{"module": module}, 30*time.Second)
-		if err != nil {
-			return fmt.Errorf("%s's backup holder was not asked to take the bus's snapshot: %w", node, err)
-		}
-		if answer.Error != "" {
-			return fmt.Errorf("%s's backup holder would not take the bus's snapshot: %s", node, answer.Error)
-		}
-		deadline := time.Now().Add(busSnapshotWithin)
-		for {
-			answer, err := link.AskSeatTool(ctx, conn, catalogue.BackupSeat, "backed-up", node, map[string]any{}, 10*time.Second)
-			if err == nil && answer.Error == "" {
-				if measured, err := readHolder(answer.Result); err == nil {
-					for item, m := range measured[module] {
-						if m.LastBackup != nil && m.LastBackup.After(asked) && m.Error == "" {
-							where = fmt.Sprintf("%s's restore point of %s (%s) taken %s", node, module, item,
-								m.LastBackup.UTC().Format(time.RFC3339))
-							return nil
-						}
-					}
-				}
-			}
-			if time.Now().After(deadline) {
-				return fmt.Errorf("%s's backup holder did not say the bus's snapshot was taken within %s; the bus is "+
-					"not replaced", node, busSnapshotWithin)
-			}
-			select {
-			case <-ctx.Done():
-				return ctx.Err()
-			case <-time.After(10 * time.Second):
-			}
-		}
-	})
-	return where, err
-}
-
-// errBusWaits is a send refused because it would replace the bus outside its planned step.
-var errBusWaits = errors.New("a new bus build waits for its planned step")
-
-type busStepKey struct{}
-
-// withBusStep marks a send as the bus's planned step: the one send that may replace the bus.
-func withBusStep(ctx context.Context) context.Context {
-	return context.WithValue(ctx, busStepKey{}, true)
-}
-
-func busStepSending(ctx context.Context) bool { on, _ := ctx.Value(busStepKey{}).(bool); return on }

cmd/mesh-controller/bus_waits.go

@@ -1,195 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"sort"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// A send held for the bus's planned step (novox/hq issue 336).
-//
-// **A wait only a person can end is said to that person at once.** No send replaces the bus but its planned
-// step (sendToEach, ADR 0236), and the step is a person's `bus upgrade`. So while a new bus build waits, every
-// walk whose tier sends to the bus's machine is refused, and tries again each tick. The refusal was kept only
-// as the walk's note; nothing was raised, and the operator found the hold by asking why a walk did not move.
-// Row S17 raises it on the first tick after the first refusal, in the bus's scope, for the operator: what
-// waits, behind which bus build, since when, and the verb. A walk held only by it is not late, so S3 leaves it
-// out, as it leaves out a walk under a paused build seat. It clears once the bus's machine has been sent the
-// build the mesh holds — the step was taken, and no send is refused for the bus any more — whatever the walks'
-// notes still say. Whether the new bus came up healthy is the step's own condition (probe DB).
-
-// kindBusStepWaiting is S17's kind: bus.<module>.step-waiting.
-const kindBusStepWaiting = "bus-step-waiting"
-
-// busFacts is a new bus build waiting for its planned step, and the sends held for it.
-type busFacts struct {
-	module, to string
-	// from is the build each machine of the bus runs; machines those whose bus the step would replace.
-	from     map[string]string
-	machines []string
-	waits    []busWaitFacts
-}
-
-// busWaitFacts is one walk whose send was refused because it would replace the bus.
-type busWaitFacts struct {
-	plan, repository, commit string
-	// modules are what its tier sends: what waits.
-	modules []string
-	// since is the first refusal: as this controller saw it, or, read back, the save that kept the refusal.
-	since time.Time
-}
-
-// busRefusedFirst is when this controller first saw each walk refused for the bus's step. The walk's note
-// keeps the refusal across a restart; this keeps its moment more exactly than the walk's last save.
-var busRefusedFirst = &firstSeen{at: map[string]time.Time{}}
-
-type firstSeen struct {
-	mu sync.Mutex
-	at map[string]time.Time
-}
-
-// mark keeps the first moment an id was seen.
-func (s *firstSeen) mark(id string, at time.Time) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	if _, seen := s.at[id]; !seen {
-		s.at[id] = at
-	}
-}
-
-// of is when an id was first seen; zero when it was not.
-func (s *firstSeen) of(id string) time.Time {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	return s.at[id]
-}
-
-// keepOnly forgets every id not given: a walk no longer held is not held since then.
-func (s *firstSeen) keepOnly(ids map[string]bool) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	for id := range s.at {
-		if !ids[id] {
-			delete(s.at, id)
-		}
-	}
-}
-
-// refusedForTheBus is whether an error is the refusal of a send for the bus's planned step.
-func refusedForTheBus(err error) bool {
-	return err != nil && strings.Contains(err.Error(), errBusWaits.Error())
-}
-
-// busWaitsOf is the sends held for the bus's step, from the open walks: each walk not waiting for its
-// delivery's word whose note keeps a refusal for this very bus build, while the build would still replace
-// the bus on a machine. first is when this controller first saw a walk refused, zero when it did not.
-func busWaitsOf(plans []inventory.Plan, b busPending, first func(string) time.Time) busFacts {
-	f := busFacts{module: b.module, to: b.to, from: b.from}
-	for _, n := range b.machines {
-		if b.moves(n) {
-			f.machines = append(f.machines, n)
-		}
-	}
-	if len(f.machines) == 0 {
-		return f
-	}
-	for _, p := range plans {
-		if !p.Open() || p.Waiting() || !strings.Contains(p.Note, errBusWaits.Error()) || !strings.Contains(p.Note, short(b.to)) {
-			continue
-		}
-		since := p.Updated
-		if seen := first(p.ID); !seen.IsZero() && (since.IsZero() || seen.Before(since)) {
-			since = seen
-		}
-		var modules []string
-		if p.Tier >= 0 && p.Tier < len(p.Tiers) {
-			modules = append(modules, p.Tiers[p.Tier]...)
-		} else {
-			modules = planModules(p)
-		}
-		sort.Strings(modules)
-		f.waits = append(f.waits, busWaitFacts{plan: p.ID, repository: p.Repository, commit: p.Commit, modules: modules,
-			since: since})
-	}
-	sort.Slice(f.waits, func(i, j int) bool { return f.waits[i].since.Before(f.waits[j].since) })
-	return f
-}
-
-// heldByTheBus is the walks of a bus's facts, by id: what S3 leaves out.
-func (b busFacts) heldByTheBus() map[string]bool {
-	out := map[string]bool{}
-	for _, w := range b.waits {
-		out[w.plan] = true
-	}
-	return out
-}
-
-// busUpgradeVerb is the call that ends the wait, as the summary names it: through the mesh MCP server, with
-// why, saying whether the new version can be undone ("reversible": "true") or not ("irreversible": "true").
-const busUpgradeVerb = "`mesh_call mesh-controller.bus {\"upgrade\": \"true\", \"why\": \"…\", \"reversible\" or \"irreversible\": \"true\"}`"
-
-// watchBusWaits is S17: a send held for the bus's planned step, said at once to the operator.
-func watchBusWaits(f *signalFacts) []conditions.Observation {
-	b := f.bus
-	if len(b.waits) == 0 || len(b.machines) == 0 {
-		return nil
-	}
-	since := b.waits[0].since
-	var walks, what []string
-	for _, w := range b.waits {
-		walks = append(walks, fmt.Sprintf("%s (%s %s, tier: %s)", w.plan, w.repository, short(w.commit),
-			strings.Join(w.modules, ", ")))
-		what = append(what, deliveryWhat(w.modules, w.repository))
-	}
-	var from []string
-	for _, n := range b.machines {
-		from = append(from, short(orNotKnown(b.from[n])))
-	}
-	machines := namesWords(b.machines, 3)
-	in := f.now.Sub(since)
-	return []conditions.Observation{{Scope: conditions.ScopeBus, ID: b.module, Token: "step-waiting",
-		Kind: kindBusStepWaiting, Severity: conditions.Warning, Resolver: conditions.ResolverOperator,
-		Machine: b.machines[0], Also: b.machines[1:],
-		Summary: fmt.Sprintf("sends to %s wait for the bus's planned step: a new bus build (%s %s → %s) would replace "+
-			"the bus there, which only a person's %s does; waiting since %s: %s", strings.Join(b.machines, ", "),
-			b.module, strings.Join(sortedUnique(from), ", "), short(b.to), busUpgradeVerb,
-			since.UTC().Format(time.RFC3339), strings.Join(walks, "; ")),
-		Said:     fmt.Sprintf("%d walk(s) refused since %s", len(b.waits), since.UTC().Format(time.RFC3339)),
-		Headline: clipWords("Sends to "+machines+" wait for a bus upgrade", conditions.HeadlineMax),
-		Explanation: clipWords(fmt.Sprintf("A new version of the mesh's message system is built, and only a person "+
-			"installs it. Until then nothing else is sent to %s: %s waits, for %s so far.", machines,
-			namesWords(sortedUnique(what), 3), humanDuration(in)), conditions.ExplanationMax),
-		Needs:    "start the bus upgrade " + FromMeshMCPServer,
-		Resolved: "Resolved: the bus upgrade started, and sends go on"}}
-}
-
-// sortedUnique is a list sorted, each once.
-func sortedUnique(xs []string) []string {
-	seen := map[string]bool{}
-	var out []string
-	for _, x := range xs {
-		if !seen[x] {
-			seen[x] = true
-			out = append(out, x)
-		}
-	}
-	sort.Strings(out)
-	return out
-}
-
-// clipWords keeps a plain sentence within a bound, at a word.
-func clipWords(s string, n int) string {
-	if len(s) <= n {
-		return s
-	}
-	cut := strings.LastIndex(s[:n-1], " ")
-	if cut <= 0 {
-		cut = n - 1
-	}
-	return s[:cut] + "…"
-}

cmd/mesh-controller/bus_waits_test.go

@@ -1,159 +0,0 @@
-package main
-
-import (
-	"context"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// novox/hq issue 336: a send held because it would replace the bus outside its planned step waits for a
-// person, so a person is told at once — what waits, behind which bus build, since when, and the verb that
-// ends it — and the wait is not read as a walk running late.
-
-// aBusOnAnchor is a new bus build waiting for its step on anchor: nats 88135ad0 there, 32307bd1 held.
-func aBusOnAnchor() busPending {
-	return busPending{module: "nats", machines: []string{"anchor"}, from: map[string]string{"anchor": "88135ad0aaaa"},
-		to: "32307bd1bbbb", same: map[string]bool{}}
-}
-
-// refusedNote is the note a walk keeps when its send was refused for the bus, as advanceHeld writes it.
-func refusedNote(b busPending, tier int) string {
-	held := "sending anchor would replace the bus (nats " + short(b.from["anchor"]) + " → " + short(b.to) +
-		"), which is a planned step: `bus upgrade --why …` snapshots its streams first and checks them after (novox/hq ADR 0236)"
-	return "tier " + string(rune('0'+tier)) + ": " + errBusWaits.Error() + ": " + held + " — tried again"
-}
-
-func TestASendHeldForTheBusStepIsFoundFromTheWalksItHolds(t *testing.T) {
-	now := time.Date(2026, 10, 8, 18, 30, 0, 0, time.UTC)
-	b := aBusOnAnchor()
-	walk := func(id, repo, note string, updated time.Time) inventory.Plan {
-		return inventory.Plan{ID: id, Repository: repo, Commit: "c0ffee001122", State: inventory.PlanRolling, Tier: 0,
-			Tiers: [][]string{{"mesh-host"}}, Modules: map[string]*inventory.PlanModule{"mesh-host": {}}, Note: note,
-			Updated: updated}
-	}
-	for _, c := range []struct {
-		name  string
-		bus   busPending
-		plans []inventory.Plan
-		first map[string]time.Time
-		want  []string
-		since time.Time
-	}{
-		{"a walk refused for the bus", b,
-			[]inventory.Plan{walk("plan-1", "novox/mesh-host", refusedNote(b, 0), now.Add(-27*time.Minute))}, nil,
-			[]string{"plan-1"}, now.Add(-27 * time.Minute)},
-		{"refused earlier than its last save, as this controller saw it", b,
-			[]inventory.Plan{walk("plan-1", "novox/mesh-host", refusedNote(b, 0), now.Add(-5*time.Minute))},
-			map[string]time.Time{"plan-1": now.Add(-28 * time.Minute)}, []string{"plan-1"}, now.Add(-28 * time.Minute)},
-		{"a walk refused for another reason", b,
-			[]inventory.Plan{walk("plan-1", "novox/mesh-host", "tier 0: the build seat is paused — tried again", now)}, nil,
-			nil, time.Time{}},
-		{"refused for an older bus build than the one held now", func() busPending { o := b; o.to = "99999999cccc"; return o }(),
-			[]inventory.Plan{walk("plan-1", "novox/mesh-host", refusedNote(b, 0), now)}, nil, nil, time.Time{}},
-		{"the bus already runs the build held: its step started", func() busPending {
-			o := aBusOnAnchor()
-			o.from = map[string]string{"anchor": o.to}
-			return o
-		}(), []inventory.Plan{walk("plan-1", "novox/mesh-host", refusedNote(b, 0), now)}, nil, nil, time.Time{}},
-		{"a walk waiting for its delivery's word asks no send", b, func() []inventory.Plan {
-			p := walk("plan-1", "novox/mesh-host", refusedNote(b, 0), now)
-			p.Delivery = &inventory.PlanDelivery{Awaits: "mesh-delivery"}
-			return []inventory.Plan{p}
-		}(), nil, nil, time.Time{}},
-	} {
-		t.Run(c.name, func(t *testing.T) {
-			got := busWaitsOf(c.plans, c.bus, func(id string) time.Time { return c.first[id] })
-			var ids []string
-			for _, w := range got.waits {
-				ids = append(ids, w.plan)
-			}
-			if strings.Join(ids, ",") != strings.Join(c.want, ",") {
-				t.Fatalf("held for the bus: %v, want %v", ids, c.want)
-			}
-			if len(c.want) > 0 {
-				if !got.waits[0].since.Equal(c.since) {
-					t.Errorf("waiting since %s, want %s", got.waits[0].since, c.since)
-				}
-				if strings.Join(got.machines, ",") != "anchor" || got.to != b.to || got.module != "nats" {
-					t.Errorf("behind %+v", got)
-				}
-			}
-		})
-	}
-}
-
-// **Said at once, not as lateness, and cleared when the step starts**: the walk held only for the bus raises
-// the bus's condition on the first tick, before any tier bound, naming what waits, the bus build from and to,
-// since when and `bus upgrade`, for the operator; S3 says nothing of it even past its bound; and the
-// condition clears once the bus's machine runs the new build.
-func TestASendHeldForTheBusStepIsSaidAtOnceAndNotAsLateness(t *testing.T) {
-	now := time.Date(2026, 10, 8, 18, 30, 0, 0, time.UTC)
-	b := aBusOnAnchor()
-	held := func(entered time.Duration) *signalFacts {
-		f := calm(now)
-		f.plans = []planFacts{{id: "plan-1", repository: "novox/mesh-host", commit: "c0ffee00", tier: 0, tiers: 1,
-			entered: now.Add(-entered), bound: 30 * time.Minute, waiting: refusedNote(b, 0), bus: true}}
-		f.bus = busFacts{module: "nats", to: b.to, from: b.from, machines: []string{"anchor"},
-			waits: []busWaitFacts{{plan: "plan-1", repository: "novox/mesh-host", commit: "c0ffee001122",
-				modules: []string{"mesh-host"}, since: now.Add(-time.Minute)}}}
-		return f
-	}
-
-	f := held(time.Minute)
-	got := watchBusWaits(f)
-	if len(got) != 1 {
-		t.Fatalf("a send held for the bus a minute ago raised %+v", got)
-	}
-	o := got[0]
-	if o.Key() != "bus.nats.step-waiting" || o.Kind != kindBusStepWaiting || o.Resolver != conditions.ResolverOperator {
-		t.Fatalf("raised %s (%s), resolver %q", o.Key(), o.Kind, o.Resolver)
-	}
-	for _, want := range []string{"anchor", "mesh-host", "88135ad0", "32307bd1", "mesh_call mesh-controller.bus",
-		`"upgrade": "true"`, `"reversible"`, `"irreversible"`, "2026-10-08T18:29:00Z", "plan-1"} {
-		if !strings.Contains(o.Summary, want) {
-			t.Errorf("its summary does not say %q: %s", want, o.Summary)
-		}
-	}
-	if !strings.Contains(o.Explanation, "mesh-host") || !strings.Contains(o.Headline, "bus upgrade") || o.Needs == "" {
-		t.Errorf("its words do not say what waits and what the operator does: %+v", o)
-	}
-	if why, ok := conditions.PlainWords(conditions.Words{Headline: o.Headline, Explanation: o.Explanation,
-		Resolved: o.Resolved, Needs: o.Needs}, "anchor"); !ok {
-		t.Errorf("its words are not plain: %s", why)
-	}
-
-	// Past S3's bound: still the bus's wait, never a stalled walk.
-	late := held(45 * time.Minute)
-	if s3 := watchPlans(late); len(s3) != 0 {
-		t.Fatalf("a walk held only by the bus step was said stalled: %+v", s3)
-	}
-	// A walk held for something else past its bound is still stalled.
-	other := held(45 * time.Minute)
-	other.plans[0].bus = false
-	if s3 := watchPlans(other); len(s3) != 1 {
-		t.Fatalf("a walk held for something else past its bound raised %+v", s3)
-	}
-
-	// Through the keeper: open at the first tick, cleared when the step started.
-	store := conditions.NewInMemory()
-	k := conditions.NewKeeper(t.Context(), conditions.Options{Store: store, History: store, Teller: &conditions.Told{},
-		Now: func() time.Time { return now }})
-	defer k.Close(context.Background())
-	w := &watchdogs{keeper: k, started: now.Add(-time.Hour)}
-	w.see(t.Context(), held(time.Minute))
-	open, err := k.Open(t.Context())
-	if err != nil || len(open) != 1 || open[0].Key != "bus.nats.step-waiting" {
-		t.Fatalf("after the first tick, open: %+v (%v)", open, err)
-	}
-	started := held(time.Minute)
-	started.bus = busFacts{module: "nats", to: b.to}
-	started.plans[0].bus = false
-	w.see(t.Context(), started)
-	if open, _ := k.Open(t.Context()); len(open) != 0 {
-		t.Fatalf("the step started, and open: %+v", open)
-	}
-}

cmd/mesh-controller/buscertificate.go

@@ -1,258 +0,0 @@
-package main
-
-import (
-	"context"
-	"crypto/rand"
-	"crypto/rsa"
-	"crypto/x509"
-	"crypto/x509/pkix"
-	"encoding/pem"
-	"errors"
-	"fmt"
-	"math/big"
-	"net"
-	"os"
-	"path/filepath"
-	"strings"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/broker"
-)
-
-// The bus's own certificate, made by the mesh rather than borrowed from an image.
-//
-// **The foundation asked a third-party image for a tool it never said must be there** (novox/hq
-// 04-ISSUES/146). The bootstrap made this certificate by running `openssl` inside the broker's
-// image, which worked while the broker was one that happened to carry it and stopped the day the
-// bus changed: the new one has a shell and no openssl, so the step exited 127 and no mesh could be
-// raised. Substituting another image the bundle names does not help — none of them carry it
-// either.
-//
-// So the program that needs a certificate makes one. It is the mesh's own binary, already on the
-// machine at this point in the bootstrap (the schema step ran it), and it needs nothing from the
-// image it writes into but a mounted directory.
-//
-// **Self-signed, and that is the design** — a host pins this server's exact certificate and
-// authenticates with a password (novox/hq ADR 0004). There is no authority above it to ask, and at
-// this moment in a bootstrap there is no mesh to ask one of.
-//
-// Idempotent, because the step is applied again on every reconcile and a second certificate would
-// be one the hosts that pinned the first no longer believe.
-
-// busCertificateNames is what the bus is reached by: the container name on a mesh network, and the
-// loopback address the machine's own foundation dials.
-var busCertificateNames = []string{"mesh-broker"}
-
-const busCertificateLife = 10 * 365 * 24 * time.Hour
-
-// busCertificate makes the bus's certificate in a directory, or says whether one is there.
-//
-//	broker certificate --into /tls           make it if it is not there
-//	broker certificate --check --into /tls   exit non-zero unless a usable pair is
-func busCertificate(args []string) error {
-	into, check := "", false
-	for i := 0; i < len(args); i++ {
-		switch args[i] {
-		case "--check":
-			check = true
-		case "--into":
-			if i+1 >= len(args) {
-				return errors.New("--into needs a directory")
-			}
-			into = args[i+1]
-			i++
-		default:
-			return fmt.Errorf("broker certificate [--check] --into <directory>: %q", args[i])
-		}
-	}
-	if into == "" {
-		return errors.New("broker certificate [--check] --into <directory>")
-	}
-	crt, key := filepath.Join(into, "tls.crt"), filepath.Join(into, "tls.key")
-
-	if usable, err := busCertificateUsable(crt, key); err != nil {
-		return err
-	} else if usable {
-		fmt.Printf("the bus already has a certificate at %s, and it was left alone\n", crt)
-		return nil
-	}
-	if check {
-		// Said as a failure, because that is what the caller asked: a bootstrap's verify runs
-		// this and a false answer is what makes the step run.
-		return fmt.Errorf("no usable certificate and key at %s", into)
-	}
-	return writeBusCertificate(crt, key)
-}
-
-// busCertificateUsable says whether a certificate and its key are both there and parse.
-//
-// Both, and parsed rather than stat'ed: a half-written pair is the state a bootstrap interrupted
-// between the two files leaves behind, and a step that treated it as done would hand the server a
-// certificate with no key and report success.
-func busCertificateUsable(crt, key string) (bool, error) {
-	certPEM, err := os.ReadFile(crt)
-	if errors.Is(err, os.ErrNotExist) {
-		return false, nil
-	}
-	if err != nil {
-		return false, err
-	}
-	keyPEM, err := os.ReadFile(key)
-	if errors.Is(err, os.ErrNotExist) {
-		return false, nil
-	}
-	if err != nil {
-		return false, err
-	}
-	if _, err := tlsPairParses(certPEM, keyPEM); err != nil {
-		return false, nil
-	}
-	return true, nil
-}
-
-func tlsPairParses(certPEM, keyPEM []byte) (*x509.Certificate, error) {
-	block, _ := pem.Decode(certPEM)
-	if block == nil || block.Type != "CERTIFICATE" {
-		return nil, errors.New("not a certificate")
-	}
-	certificate, err := x509.ParseCertificate(block.Bytes)
-	if err != nil {
-		return nil, err
-	}
-	keyBlock, _ := pem.Decode(keyPEM)
-	if keyBlock == nil {
-		return nil, errors.New("not a key")
-	}
-	if _, err := x509.ParsePKCS8PrivateKey(keyBlock.Bytes); err != nil {
-		if _, err := x509.ParsePKCS1PrivateKey(keyBlock.Bytes); err != nil {
-			return nil, err
-		}
-	}
-	return certificate, nil
-}
-
-func writeBusCertificate(crt, key string) error {
-	private, err := rsa.GenerateKey(rand.Reader, 2048)
-	if err != nil {
-		return err
-	}
-	serial, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
-	if err != nil {
-		return err
-	}
-	template := &x509.Certificate{
-		SerialNumber:          serial,
-		Subject:               pkix.Name{CommonName: busCertificateNames[0]},
-		DNSNames:              busCertificateNames,
-		IPAddresses:           []net.IP{net.ParseIP("127.0.0.1")},
-		NotBefore:             time.Now().Add(-time.Hour),
-		NotAfter:              time.Now().Add(busCertificateLife),
-		KeyUsage:              x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment,
-		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
-		BasicConstraintsValid: true,
-	}
-	der, err := x509.CreateCertificate(rand.Reader, template, template, &private.PublicKey, private)
-	if err != nil {
-		return err
-	}
-	pkcs8, err := x509.MarshalPKCS8PrivateKey(private)
-	if err != nil {
-		return err
-	}
-
-	// **The key first, and only then the certificate**, so the pair a reader finds is never a
-	// certificate whose key has not been written yet — the one order in which an interruption
-	// leaves something that looks finished (novox/hq 04-ISSUES/014, a key present and unusable).
-	if err := os.WriteFile(key, pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: pkcs8}), 0o600); err != nil {
-		return err
-	}
-	if err := os.WriteFile(crt, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der}), 0o644); err != nil {
-		return err
-	}
-	fmt.Printf("made the bus a certificate for %v, valid until %s\n  %s\n  %s\n",
-		busCertificateNames, template.NotAfter.Format(time.RFC3339), crt, key)
-	return nil
-}
-
-// busAccounts writes the mesh's composed user list to a file.
-//
-// **For genesis, where no declaration can deliver it** (novox/hq 04-ISSUES/146). Everywhere else
-// the list reaches the machine running the bus as a resource of the module that holds it — which
-// requires that machine to be an enrolled node, and at genesis it is not: the first node cannot
-// enrol because the account it would enrol with cannot be composed onto a bus it has no declaration
-// for. The installer breaks that circle by placing the file itself, once, and the module takes the
-// file over from its first push.
-//
-// The same composition, not a second one: this asks the store for the same records and renders them
-// with the same composer the declaration uses. A genesis that hand-wrote an account would be a
-// second statement of who may say what, able to disagree with the first.
-//
-// **It writes to standard output unless told a file**, and that is the point: the control plane
-// composes and says what it composed, and whoever is raising the machine puts it where that
-// machine's bus reads it. A control plane that wrote into the bus's own directory would have to
-// know where that is and how to make the server re-read it — which is the module's knowledge, and
-// the module is what takes this over on the first push.
-//
-//	broker accounts > /var/lib/mesh-bus-conf/accounts.conf
-func busAccounts(ctx context.Context, args []string) error {
-	into := ""
-	for i := 0; i < len(args); i++ {
-		switch args[i] {
-		case "--into":
-			if i+1 >= len(args) {
-				return errors.New("--into needs a file")
-			}
-			into = args[i+1]
-			i++
-		default:
-			return fmt.Errorf("broker accounts --into <file>: %q", args[i])
-		}
-	}
-
-	open, err := openStores(ctx)
-	if err != nil {
-		return err
-	}
-	defer open.Close()
-
-	records, err := open.inventory.BusRecords(ctx)
-	if err != nil {
-		return err
-	}
-	users, err := broker.Users(records)
-	if err != nil {
-		return err
-	}
-	kept, err := open.inventory.BusUsers(ctx)
-	if err != nil {
-		return err
-	}
-	hashes := make(map[string]string, len(kept))
-	for name, u := range kept {
-		hashes[name] = u.PasswordHash
-	}
-	filled, missing := broker.WithPasswords(users, hashes)
-	if len(missing) > 0 {
-		// To standard error, always: the composed file may be going to standard output, and a
-		// remark in the middle of it is a configuration the server refuses to parse.
-		fmt.Fprintf(os.Stderr, "leaving out %d user(s) the mesh has minted no credential for: %s\n",
-			len(missing), strings.Join(missing, ", "))
-	}
-	if len(filled) == 0 {
-		return errors.New("not one user has a credential, so this list would refuse every " +
-			"connection in the mesh")
-	}
-	accounts, err := broker.ComposeAccounts(filled)
-	if err != nil {
-		return err
-	}
-	if into == "" {
-		fmt.Print(accounts)
-		return nil
-	}
-	if err := os.WriteFile(into, []byte(accounts), 0o600); err != nil {
-		return err
-	}
-	fmt.Printf("wrote %d user(s) to %s\n", len(filled), into)
-	return nil
-}

cmd/mesh-controller/buscertificate_test.go

@@ -1,121 +0,0 @@
-package main
-
-import (
-	"crypto/tls"
-	"crypto/x509"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-)
-
-// novox/hq 04-ISSUES/146. The bootstrap could not make the bus a certificate: it asked an image for
-// `openssl` and the image it asks has none. What replaces it is this command, so what is checked is
-// what the bootstrap needs from it — a pair a TLS server can actually load, made once and only once.
-
-func TestTheBusCertificateLoadsAsAServersWould(t *testing.T) {
-	into := t.TempDir()
-	if err := busCertificate([]string{"--into", into}); err != nil {
-		t.Fatalf("the bus could not be given a certificate: %v", err)
-	}
-
-	// The check a cheaper test would not make. The key was present and valid and the server could
-	// not start, once, because nothing loaded the pair the way a server loads it
-	// (novox/hq 04-ISSUES/014).
-	pair, err := tls.LoadX509KeyPair(filepath.Join(into, "tls.crt"), filepath.Join(into, "tls.key"))
-	if err != nil {
-		t.Fatalf("a TLS server cannot load what was written: %v", err)
-	}
-	leaf := pair.Leaf
-	if leaf == nil {
-		if leaf, err = x509.ParseCertificate(pair.Certificate[0]); err != nil {
-			t.Fatal(err)
-		}
-	}
-	if err := leaf.VerifyHostname("mesh-broker"); err != nil {
-		t.Errorf("the certificate is not for the name the bus is reached by: %v", err)
-	}
-	if len(leaf.IPAddresses) == 0 || leaf.IPAddresses[0].String() != "127.0.0.1" {
-		t.Errorf("the certificate does not cover the loopback address the foundation dials: %v", leaf.IPAddresses)
-	}
-
-	// The key is not readable by anything else on the machine; the certificate is public and is.
-	key, err := os.Stat(filepath.Join(into, "tls.key"))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if key.Mode().Perm() != 0o600 {
-		t.Errorf("the key is %v", key.Mode().Perm())
-	}
-	crt, err := os.Stat(filepath.Join(into, "tls.crt"))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if crt.Mode().Perm() != 0o644 {
-		t.Errorf("the certificate is %v, which the server runs as another user cannot read", crt.Mode().Perm())
-	}
-}
-
-// **Made once.** The step is applied again on every reconcile, and a second certificate is one the
-// hosts that pinned the first no longer believe (novox/hq ADR 0004).
-func TestTheBusCertificateIsMadeOnce(t *testing.T) {
-	into := t.TempDir()
-	if err := busCertificate([]string{"--into", into}); err != nil {
-		t.Fatal(err)
-	}
-	first, err := os.ReadFile(filepath.Join(into, "tls.crt"))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := busCertificate([]string{"--into", into}); err != nil {
-		t.Fatal(err)
-	}
-	again, err := os.ReadFile(filepath.Join(into, "tls.crt"))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if string(first) != string(again) {
-		t.Fatal("running it twice replaced the certificate every host had pinned")
-	}
-}
-
-// The verify half: false before, true after, which is what makes the bootstrap run the step at all.
-func TestTheCheckIsFalseUntilThereIsAPair(t *testing.T) {
-	into := t.TempDir()
-	if err := busCertificate([]string{"--check", "--into", into}); err == nil {
-		t.Fatal("an empty directory reported a usable certificate")
-	}
-	if err := busCertificate([]string{"--into", into}); err != nil {
-		t.Fatal(err)
-	}
-	if err := busCertificate([]string{"--check", "--into", into}); err != nil {
-		t.Fatalf("the certificate it just made does not satisfy its own check: %v", err)
-	}
-}
-
-// A half-written pair is not a pair. An interrupted bootstrap leaves exactly this, and a step that
-// called it done would hand the server a certificate with no key and report success.
-func TestACertificateWithoutItsKeyIsNotUsable(t *testing.T) {
-	into := t.TempDir()
-	if err := busCertificate([]string{"--into", into}); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.Remove(filepath.Join(into, "tls.key")); err != nil {
-		t.Fatal(err)
-	}
-	if err := busCertificate([]string{"--check", "--into", into}); err == nil {
-		t.Fatal("a certificate with no key passed the check")
-	}
-	if err := busCertificate([]string{"--into", into}); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := tls.LoadX509KeyPair(filepath.Join(into, "tls.crt"), filepath.Join(into, "tls.key")); err != nil {
-		t.Fatalf("it did not replace the unusable pair: %v", err)
-	}
-}
-
-func TestWhereToWriteIsRequired(t *testing.T) {
-	if err := busCertificate(nil); err == nil || !strings.Contains(err.Error(), "--into") {
-		t.Fatalf("it did not ask where to write: %v", err)
-	}
-}

cmd/mesh-controller/busobjects.go

@@ -1,210 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"fmt"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// The streams and durable consumers the mesh's own traffic needs, derived once (novox/hq to-be 45 §4,
-// D6 and D7).
-//
-// **What the controller asserts at its start and what the self-check expects to find are one
-// derivation**, run against the bus to make them and against a recorder to list them. Two lists would
-// drift, and a self-check comparing the bus with a second opinion of what should be there would find
-// the drift rather than the fault.
-
-// assertBusObjects brings every stream and consumer into being on r, and answers the machines that
-// can now hear a declaration.
-func assertBusObjects(ctx context.Context, inv *inventory.Inventory, r broker.Raiser) ([]string, error) {
-	nodes, err := inv.Nodes(ctx)
-	if err != nil {
-		return nil, err
-	}
-	names := make([]string, 0, len(nodes))
-	for _, n := range nodes {
-		names = append(names, n.Name)
-	}
-	if err := broker.Raise(r, names); err != nil {
-		return nil, err
-	}
-	// The work queues of the mesh's own roles (novox/hq ADR 0121). The queue before the holder,
-	// deliberately: work queues until somebody arrives to do it, so assigning a build machine a week
-	// after something started asking for builds flushes the backlog instead of having lost it.
-	// With the seats' holders, so each role's work queue gets the consumer its holder takes
-	// work from. Passed as nil until the first live raise, which left the build machine bound to a
-	// consumer nothing had created (2026-09-28).
-	holders, err := seatHolders(ctx, inv)
-	if err != nil {
-		return nil, err
-	}
-	if err := broker.RaiseSeats(r, inventory.MeshSeats(), holders); err != nil {
-		return nil, err
-	}
-	// And how every module hears what it consumes. Derived from the same records the user list is
-	// composed from, so a module the mesh grants a consumer's subjects has that consumer waiting.
-	// Done on every raise, not only when a credential is issued: every module moved onto this bus
-	// by the rollout was issued on the old one, and came up with nothing to bind to (2026-09-28).
-	consumers, err := moduleConsumers(ctx, inv)
-	if err != nil {
-		return nil, err
-	}
-	// And the work queues of seats that name their caller or their kind, with each holder's worker
-	// (novox/hq ADR 0259 §3): an ask queues until the router takes it, a channel's work until that kind
-	// takes it.
-	trafficStreams, trafficWorkers, err := seatTrafficObjects(ctx, inv)
-	if err != nil {
-		return nil, err
-	}
-	// Every one tried, and every failure named: one module's consumer the bus refuses is no reason
-	// the modules after it in the list hear nothing (novox/hq issue 208, where this runs on each send).
-	var failed []error
-	for _, s := range trafficStreams {
-		if err := r.EnsureStream(s); err != nil {
-			failed = append(failed, fmt.Errorf("the work queue %s: %w", s.Name, err))
-		}
-	}
-	for _, c := range trafficWorkers {
-		if err := r.EnsureConsumer(c); err != nil {
-			failed = append(failed, fmt.Errorf("the worker %s on %s: %w", c.Name, c.Stream, err))
-		}
-	}
-	for _, c := range consumers {
-		if err := r.EnsureConsumer(c.Consumer); err != nil {
-			failed = append(failed, fmt.Errorf("how %s on %s hears what it consumes: %w", c.Module, c.Node, err))
-		}
-	}
-	if len(failed) > 0 {
-		return nil, errors.Join(failed...)
-	}
-	return names, nil
-}
-
-// What raises the condition a send says when the objects it implies could not be asserted, and its kind.
-const (
-	sourceBusObjects         = "bus-objects"
-	kindBusObjectsUnasserted = "bus-objects-unasserted"
-)
-
-// assertOnSend asserts, on the bus a send is about to use, every object assertBusObjects derives —
-// **whenever a declaration is sent, not only when the controller starts** (novox/hq issue 208).
-//
-// A module assigned after the controller started was sent its declaration and found no consumer to
-// bind (`consumer not found`, messenger on 2026-10-06), and a seat holder assigned after it found no
-// worker: the objects a declaration implies were asserted at start and nowhere else, so they existed
-// only for what was assigned before the last restart. The same derivation, not a second list of what
-// a send needs: what start asserts, the self-check expects and a send asserts are one answer. Every
-// part is idempotent, so asserting the whole of it again is the no-op a restart already relies on.
-//
-// **A failure is said and raised, and the send goes on.** The objects are the mesh's, not the
-// machines' being sent: holding every machine back for one consumer that none of them may use would
-// turn one fault into all of them, and the declarations are not what is wrong. It is never silent —
-// said in the send's own output and raised as a condition, which the next send that asserts them
-// clears — and the start-time raise still refuses to serve without them.
-func assertOnSend(ctx context.Context, inv *inventory.Inventory, r broker.Raiser, indent string) error {
-	_, err := assertBusObjects(ctx, inv, r)
-	var observed []conditions.Observation
-	if err != nil {
-		fmt.Printf("%sTHE BUS DOES NOT HOLD WHAT THIS SEND IMPLIES: %v\n", indent, err)
-		fmt.Printf("%s  a module may find no consumer to bind, or a holder no worker; sent anyway, raised as "+
-			"condition %s, and asserted again by the next send\n", indent, unassertedObservation(err).Key())
-		observed = append(observed, unassertedObservation(err))
-	}
-	// Observed when it failed, cleared when it did not: a send that asserted everything is the
-	// observation that the bus holds what it should.
-	if kerr := withKeeper(ctx, func(k *conditions.Keeper) error {
-		return k.Reconcile(ctx, sourceBusObjects, observed)
-	}); kerr != nil {
-		fmt.Printf("%sand whether the bus holds what this send implies could not be kept as a condition: %v\n",
-			indent, kerr)
-	}
-	return err
-}
-
-// unassertedObservation is a send's failure to assert the bus's objects, as a condition.
-func unassertedObservation(err error) conditions.Observation {
-	return conditions.Observation{Scope: conditions.ScopeBus, ID: "objects", Token: "unasserted",
-		Kind: kindBusObjectsUnasserted, Severity: conditions.Warning, Source: sourceBusObjects,
-		Summary: "the bus's streams and consumers could not be asserted when a declaration was sent: " +
-			"a module may find no consumer to bind, or a seat's holder no worker",
-		Said: err.Error()}
-}
-
-// moduleConsumers is every module's durable consumer, from the records the user list is composed from.
-func moduleConsumers(ctx context.Context, inv *inventory.Inventory) ([]broker.ModuleConsumer, error) {
-	records, err := inv.BusRecords(ctx)
-	if err != nil {
-		return nil, err
-	}
-	users, err := broker.Users(records)
-	if err != nil {
-		return nil, err
-	}
-	return broker.ConsumersOf(users), nil
-}
-
-// seatTrafficObjects is the work queues and workers of seats that name their caller or their kind, from
-// the records the user list is composed from.
-func seatTrafficObjects(ctx context.Context, inv *inventory.Inventory) ([]broker.Stream, []broker.Consumer, error) {
-	records, err := inv.BusRecords(ctx)
-	if err != nil {
-		return nil, nil, err
-	}
-	users, err := broker.Users(records)
-	if err != nil {
-		return nil, nil, err
-	}
-	streams, workers := broker.SeatTrafficObjects(users)
-	// And the queue of every such seat the catalogue declares, held or not: work queues from registration,
-	// so what is submitted before a holder is assigned waits for it (the correctness review of 2026-10-08).
-	declared, err := inv.DeclaredTrafficSeats(ctx)
-	if err != nil {
-		return nil, nil, err
-	}
-	have := map[string]bool{}
-	for _, s := range streams {
-		have[s.Name] = true
-	}
-	for _, s := range broker.TrafficQueues(declared) {
-		if !have[s.Name] {
-			streams = append(streams, s)
-			have[s.Name] = true
-		}
-	}
-	return streams, workers, nil
-}
-
-// moduleConsumerCount is how many modules hear what they consume, for the raise's one line.
-func moduleConsumerCount(ctx context.Context, inv *inventory.Inventory) (int, error) {
-	consumers, err := moduleConsumers(ctx, inv)
-	return len(consumers), err
-}
-
-// expectedBusObjects is every stream and consumer assertBusObjects would make, made nowhere.
-func expectedBusObjects(ctx context.Context, inv *inventory.Inventory) ([]broker.Stream, []broker.Consumer, error) {
-	var rec recordingRaiser
-	if _, err := assertBusObjects(ctx, inv, &rec); err != nil {
-		return nil, nil, fmt.Errorf("what the bus should hold cannot be worked out: %w", err)
-	}
-	return rec.streams, rec.consumers, nil
-}
-
-// recordingRaiser keeps what it was asked to assert and asserts nothing.
-type recordingRaiser struct {
-	streams   []broker.Stream
-	consumers []broker.Consumer
-}
-
-func (r *recordingRaiser) EnsureStream(s broker.Stream) error {
-	r.streams = append(r.streams, s)
-	return nil
-}
-
-func (r *recordingRaiser) EnsureConsumer(c broker.Consumer) error {
-	r.consumers = append(r.consumers, c)
-	return nil
-}

cmd/mesh-controller/busobjects_test.go

@@ -1,197 +0,0 @@
-package main
-
-import (
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/nats-io/nats.go"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-
-	"github.com/novox/mesh-controller/internal/testbus"
-)
-
-// novox/hq issue 208: the bus's objects a declaration implies are asserted whenever one is sent, not
-// only when the controller starts.
-
-// aCarriedConsumer is the runtime on laptop and, carried by it, a module that consumes an event: the
-// shape of messenger on 2026-10-06, assigned after the controller started.
-func aCarriedConsumer(t *testing.T, open *stores) broker.Consumer {
-	t.Helper()
-	register(t, open, catalogue.Manifest{Module: catalogue.RuntimeModule, Version: "1",
-		OwnSecrets: catalogue.OwnSecrets{"broker": {Path: "/var/lib/mesh/node-tools/broker"}}})
-	register(t, open, catalogue.Manifest{Module: "messenger", Version: "1",
-		Consumes: []string{"billing.order.placed"}})
-	for _, m := range []string{catalogue.RuntimeModule, "messenger"} {
-		if _, err := open.inventory.Assign(t.Context(), "laptop", m); err != nil {
-			t.Fatal(err)
-		}
-	}
-	consumers, err := moduleConsumers(t.Context(), open.inventory)
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, c := range consumers {
-		if c.Module == "messenger" && c.Node == "laptop" {
-			return c.Consumer
-		}
-	}
-	t.Fatalf("messenger on laptop is derived no consumer: %+v", consumers)
-	return broker.Consumer{}
-}
-
-// aLateHolder is a module holding the build agent's seat on anchor, assigned after the controller
-// started, and the worker its seat's queue should have for it.
-func aLateHolder(t *testing.T, open *stores) broker.Consumer {
-	t.Helper()
-	register(t, open, catalogue.Manifest{Module: "late-builder", Version: "1",
-		Claims: []catalogue.Claim{{Name: "node-build-agent", Scope: catalogue.ScopeNode}}})
-	if _, err := open.inventory.Assign(t.Context(), "anchor", "late-builder"); err != nil {
-		t.Fatal(err)
-	}
-	for _, s := range inventory.MeshSeats() {
-		if s.Name == "node-build-agent" {
-			c, needed := broker.HolderConsumerFor("anchor", "late-builder", s)
-			if !needed {
-				t.Fatal("the build agent's seat needs no worker")
-			}
-			return c
-		}
-	}
-	t.Fatal("the mesh declares no build agent's seat")
-	return broker.Consumer{}
-}
-
-// asserted says whether a recording holds a consumer by stream and name.
-func asserted(rec *recordingRaiser, want broker.Consumer) bool {
-	for _, c := range rec.consumers {
-		if c.Stream == want.Stream && c.Name == want.Name {
-			return true
-		}
-	}
-	return false
-}
-
-// What a send asserts includes what was assigned after the start's assertion: a carried module's
-// consumer and a late holder's worker. The derivation is the start's own, so this holds without a bus.
-func TestASendAssertsWhatWasAssignedAfterStart(t *testing.T) {
-	open := aMesh(t)
-	var atStart recordingRaiser
-	if _, err := assertBusObjects(t.Context(), open.inventory, &atStart); err != nil {
-		t.Fatal(err)
-	}
-	consumer := aCarriedConsumer(t, open)
-	worker := aLateHolder(t, open)
-	if asserted(&atStart, consumer) || asserted(&atStart, worker) {
-		t.Fatal("the start asserted what was not yet assigned; the test proves nothing")
-	}
-	var onSend recordingRaiser
-	if err := assertOnSend(t.Context(), open.inventory, &onSend, ""); err != nil {
-		t.Fatal(err)
-	}
-	if !asserted(&onSend, consumer) {
-		t.Fatalf("messenger's consumer %s on %s is not asserted by the send: %+v", consumer.Name, consumer.Stream, onSend.consumers)
-	}
-	if !asserted(&onSend, worker) {
-		t.Fatalf("the late holder's worker %s on %s is not asserted by the send: %+v", worker.Name, worker.Stream, onSend.consumers)
-	}
-}
-
-// failingRaiser refuses one consumer by name and records everything it was asked.
-type failingRaiser struct {
-	recordingRaiser
-	refuse string
-}
-
-func (f *failingRaiser) EnsureConsumer(c broker.Consumer) error {
-	f.consumers = append(f.consumers, c)
-	if c.Name == f.refuse {
-		return errors.New("nats: API error: code=503 description=insufficient resources")
-	}
-	return nil
-}
-
-// A send whose objects cannot be asserted says so in its output and raises a condition — and the next
-// send that asserts them clears it. The consumers after the refused one are still asked for.
-func TestASendThatCannotAssertTheBusSaysSoAndRaisesACondition(t *testing.T) {
-	open := aMesh(t)
-	consumer := aCarriedConsumer(t, open)
-	worker := aLateHolder(t, open)
-	failing := &failingRaiser{refuse: consumer.Name}
-
-	var sendErr error
-	out := stdoutOf(t, func() error {
-		sendErr = assertOnSend(t.Context(), open.inventory, failing, "  ")
-		return nil
-	})
-	if sendErr == nil || !strings.Contains(sendErr.Error(), "how messenger on laptop hears what it consumes") {
-		t.Fatalf("the failure is not answered: %v", sendErr)
-	}
-	if !strings.Contains(out, "THE BUS DOES NOT HOLD WHAT THIS SEND IMPLIES") ||
-		!strings.Contains(out, "insufficient resources") || !strings.Contains(out, "bus.objects.unasserted") {
-		t.Fatalf("the failure is not said in the send's output:\n%s", out)
-	}
-	if !asserted(&failing.recordingRaiser, worker) {
-		t.Fatal("the seat's worker was not asked for")
-	}
-	c, open1, err := conditionsFrom.Get(t.Context(), "bus.objects.unasserted")
-	if err != nil || !open1 {
-		t.Fatalf("no condition raised: %v", err)
-	}
-	if c.Kind != kindBusObjectsUnasserted || c.Source != sourceBusObjects ||
-		len(c.Evidence) == 0 || !strings.Contains(c.Evidence[0].Said, "insufficient resources") {
-		t.Fatalf("the condition does not say what failed: %+v", c)
-	}
-
-	// The next send asserts them, and that observation clears it.
-	if err := assertOnSend(t.Context(), open.inventory, &recordingRaiser{}, ""); err != nil {
-		t.Fatal(err)
-	}
-	if _, stillOpen, err := conditionsFrom.Get(t.Context(), "bus.objects.unasserted"); err != nil || stillOpen {
-		t.Fatalf("a send that asserted everything left the condition open: %v", err)
-	}
-}
-
-// Against a real bus, through the send's own grant: a module assigned after start has its consumer
-// once a declaration is sent, and a holder assigned after start its seat's worker.
-func TestNatsAModuleAssignedAfterStartGetsItsConsumerAtItsFirstSend(t *testing.T) {
-	url := testbus.URL(t)
-	open := aMesh(t)
-	js, err := broker.Dial(url)
-	if err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(js.Close)
-	for _, s := range []string{"CONTROL", "NODES", "ASSIGNMENTS", "EVENTS"} {
-		_ = js.Context().DeleteStream(s)
-	}
-	// The controller starting, before either was assigned.
-	if _, err := assertBusObjects(t.Context(), open.inventory, js); err != nil {
-		t.Fatal(err)
-	}
-	consumer := aCarriedConsumer(t, open)
-	worker := aLateHolder(t, open)
-	_ = js.Context().DeleteConsumer(worker.Stream, worker.Name)
-	for _, c := range []broker.Consumer{consumer, worker} {
-		if _, err := js.Context().ConsumerInfo(c.Stream, c.Name); !errors.Is(err, nats.ErrConsumerNotFound) {
-			t.Fatalf("%s on %s exists before any send; the test proves nothing: %v", c.Name, c.Stream, err)
-		}
-	}
-
-	server := link.ConnectNats(js, nil, nil)
-	if err := (overTheBus{open: open, server: server}).grant(t.Context(), nil); err != nil {
-		t.Fatal(err)
-	}
-	for _, c := range []broker.Consumer{consumer, worker} {
-		if _, err := js.Context().ConsumerInfo(c.Stream, c.Name); err != nil {
-			t.Fatalf("%s on %s is not on the bus after a send: %v", c.Name, c.Stream, err)
-		}
-	}
-	if _, raised, _ := conditionsFrom.Get(t.Context(), "bus.objects.unasserted"); raised {
-		t.Fatal("a send that asserted everything raised a condition")
-	}
-}

cmd/mesh-controller/calls_verb_test.go

@@ -1,79 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// consoleWaits is how long the console waits for an answer (mesh-tools node-tools/internal/bus
-// RequestTimeout) — the shortest wait of a caller the mesh ships.
-const consoleWaits = 30 * time.Second
-
-// **A call's one answer is never later than its caller or the bus allow** (novox/hq issue 265): a
-// holder answers within AnswerWithin, which must be inside both the console's wait and the window the
-// bus gives an answer. Before, the console waited 30s, the bus 60s, and a push ran as long as it ran.
-func TestAVerbAnswersInsideEveryWaitOnIt(t *testing.T) {
-	if link.AnswerWithin >= consoleWaits/2 {
-		t.Errorf("a call answers within %s: not well inside the console's %s", link.AnswerWithin, consoleWaits)
-	}
-	if link.AnswerWithin >= broker.ResponseTTL {
-		t.Errorf("a call answers within %s, after the bus stops permitting an answer at %s", link.AnswerWithin, broker.ResponseTTL)
-	}
-}
-
-// A push — named or through command — answers before it runs: it sends the machine holding the bus
-// first, and the broker reloading its user list forgets the answer it was about to permit.
-func TestAPushAnswersBeforeItSends(t *testing.T) {
-	for _, c := range []struct {
-		verb string
-		args map[string]any
-		want bool
-	}{
-		{"push", map[string]any{"node": "anchor", "why": "w"}, true},
-		{"push", map[string]any{"why": "w"}, true},
-		{"command", map[string]any{"command": "builds"}, false},
-		{"status", map[string]any{}, false},
-		{"assign", map[string]any{"node": "anchor", "module": "m"}, false},
-	} {
-		argv, err := argvFor(c.verb, c.args)
-		if err != nil {
-			t.Fatalf("%s %v: %v", c.verb, c.args, err)
-		}
-		if got := answersFirst(argv); got != c.want {
-			t.Errorf("%s %v answers first: %v, want %v", c.verb, c.args, got, c.want)
-		}
-	}
-}
-
-// `calls` is served, takes a call's id and nothing else, and says plainly when it holds no such call.
-func TestCallsIsServedAndSaysWhatItKeeps(t *testing.T) {
-	handlers, behind, err := seatToolHandlers()
-	if err != nil || len(behind) != 0 {
-		t.Fatalf("%v %v", behind, err)
-	}
-	calls, ok := handlers["calls"]
-	if !ok {
-		t.Fatal("calls is not served")
-	}
-	if _, err := calls(context.Background(), json.RawMessage(`{"node":"anchor"}`)); err == nil ||
-		!strings.Contains(err.Error(), `"node"`) {
-		t.Errorf("calls took an argument it does not declare: %v", err)
-	}
-	if _, err := calls(context.Background(), json.RawMessage(`{"call":"call-0-0"}`)); err == nil ||
-		!strings.Contains(err.Error(), "not across a restart") {
-		t.Errorf("an unknown call was not said plainly: %v", err)
-	}
-	got, err := calls(context.Background(), json.RawMessage(`{}`))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if _, listed := got.(map[string]any)["calls"]; !listed {
-		t.Errorf("calls answered %v", got)
-	}
-}

cmd/mesh-controller/changeplan.go

@@ -1,216 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"path"
-	"slices"
-	"sort"
-	"strings"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// The change plan (novox/hq ADR 0238): **one commit, one plan** — what a change does to the mesh, computed
-// from its diffset (a repository, the branch it merges into, the commit at hand) by the planner, never by
-// a mapping of its own. reachOfMerge answers what moves and what follows it; this adds where each module
-// goes — the deploy plan, machine by machine in the build plan's order — and what is not an ordinary
-// send. A pull request's check posts it with its verdict; the release a merge makes follows the same
-// planner, so the two can be compared.
-
-// policyOf is a module's upgrade policy, as the controller holds it; false when it cannot be read.
-type policyOf func(module string) (inventory.Upgrade, bool)
-
-// changePlanOf is the change plan of a reach: pure, so it is tested without a store.
-func changePlanOf(repository, base, head string, r mergeReach, entries []inventory.Entry, policy policyOf) link.ChangePlan {
-	p := link.ChangePlan{Repository: repository, Base: base, Head: head, Moved: r.Moved(), Dependents: r.Dependents(),
-		New: r.Added, Unread: r.Unread, Tiers: r.Plan.Tiers}
-	byName := map[string]inventory.Entry{}
-	for _, e := range entries {
-		byName[e.Manifest.Module] = e
-	}
-	// The machine holding the bus, whose declaration carries every module's grants (novox/hq issue 490).
-	holder := ""
-	for _, e := range entries {
-		if e.Manifest.BusUsers != "" && e.Manifest.ClaimsSeat(catalogue.BrokerSeat) && len(e.On) > 0 {
-			holder = e.On[0]
-		}
-	}
-	var granting []string
-	machines := map[string]*link.MachinePlan{}
-	machine := func(name string) *link.MachinePlan {
-		if machines[name] == nil {
-			machines[name] = &link.MachinePlan{Machine: name}
-		}
-		return machines[name]
-	}
-	for _, tier := range r.Plan.Tiers {
-		for _, name := range tier {
-			e, held := byName[name]
-			if !held {
-				continue
-			}
-			u, known := policy(name)
-			waits := known && !u.RollOut
-			for _, on := range e.On {
-				if waits {
-					machine(on).Waits = append(machine(on).Waits, name)
-				} else {
-					machine(on).Receives = append(machine(on).Receives, name)
-				}
-			}
-			if !waits && holder != "" && !(len(e.On) == 1 && e.On[0] == holder) && len(e.On) > 0 &&
-				!slices.Contains(granting, name) {
-				granting = append(granting, name)
-			}
-			switch {
-			case (name == "nats" || catalogue.ProvidesBus(e.Manifest)) && len(e.On) > 0:
-				// Said before the merge (novox/hq issue 336): a new bus build holds every send to the bus's machine
-				// until a person takes the step, so merging it is a promise to take it.
-				p.Steps = append(p.Steps, fmt.Sprintf("%s: %s is never sent by an ordinary send, and until %s runs, "+
-					"nothing else is sent to %s either — unless the new build turns out the same as the one running there "+
-					"(issue 280)", busUpgradeNeeded, name, busUpgradeVerb, strings.Join(e.On, ", ")))
-			case name == "nats" || catalogue.ProvidesBus(e.Manifest):
-				p.Steps = append(p.Steps, "a planned bus step: the bus is upgraded by `bus upgrade`, never by an ordinary send")
-			case waits && len(e.On) > 0:
-				p.Steps = append(p.Steps, fmt.Sprintf("%s waits for a person: its policy records (%s)", name,
-					orNone(u.From)))
-			}
-			if len(e.Manifest.Provides) > 0 && len(e.On) > 0 {
-				var offers []string
-				for _, o := range e.Manifest.Provides {
-					offers = append(offers, o.Name)
-				}
-				p.Steps = append(p.Steps, fmt.Sprintf("%s provides %s: its consumers are sent again after it",
-					name, strings.Join(offers, ", ")))
-			}
-			if e.Manifest.Data != nil && len(e.On) > 0 {
-				p.Steps = append(p.Steps, fmt.Sprintf("%s keeps data (ADR 0233): what it holds is backed up before it moves", name))
-			}
-		}
-	}
-	if len(granting) > 0 {
-		// Said before the merge (novox/hq issue 490): what the walk does when the change alters the bus's
-		// user list. Whether it does is known only once the builds are registered, so it is said as a rule.
-		p.Steps = append(p.Steps, fmt.Sprintf("%s: if this changes what the bus's user list says (a new tool, "+
-			"subject or user), %s is sent that list alone, every build there kept, before %s is judged on its first "+
-			"machine", grantsStepWord, holder, strings.Join(granting, ", ")))
-	}
-	var names []string
-	for name := range machines {
-		names = append(names, name)
-	}
-	sort.Strings(names)
-	for _, name := range names {
-		p.Machines = append(p.Machines, *machines[name])
-	}
-	p.Summary = summaryOf(p)
-	p.Class = changeClassOf(p, entries)
-	return p
-}
-
-// classNone is the class of a change that moves no module: nothing for a walk to move (novox/hq ADR 0313 §2).
-const classNone = "none"
-
-// changeClassOf is a change plan's class (novox/hq ADR 0313 §2): that of the slowest-budgeted module it moves,
-// itself or as a dependent — core when one is on the controller's own path or holds the mesh's resolver, leaf
-// otherwise — and none when it moves nothing. A module it adds a directory for counts by its own class: the
-// catalogue names a module's directory by the module, so the directory's last element is its name. The graph holds
-// no manifest of it yet, so a new module is core by its name alone (on the controller's own path), never by a
-// resolver claim its manifest makes.
-func changeClassOf(p link.ChangePlan, entries []inventory.Entry) string {
-	if len(p.Moved) == 0 && len(p.Dependents) == 0 && len(p.New) == 0 {
-		return classNone
-	}
-	modules := append(append([]string{}, p.Moved...), p.Dependents...)
-	for _, dir := range p.New {
-		if name := path.Base(strings.Trim(dir, "/")); name != "." && name != "/" && name != "" {
-			modules = append(modules, name)
-		}
-	}
-	return classOfModules(modules, entries)
-}
-
-// grantsStepWord names the grants step (novox/hq issue 490): the bus's user list sent alone to the machine
-// holding the bus ahead of a walk's gate. Not the bus step, which replaces the bus itself.
-const grantsStepWord = "grants step"
-
-// busUpgradeNeeded is how a change plan says that merging it holds the bus's machine for a person's step.
-const busUpgradeNeeded = "merging this needs a person's bus upgrade"
-
-// summaryOf is a change plan in one line: what it builds, where it goes, and whether the bus moves.
-func summaryOf(p link.ChangePlan) string {
-	if len(p.Moved) == 0 && len(p.New) == 0 {
-		return "builds nothing: the change touches no module of the mesh's graph"
-	}
-	var parts []string
-	what := strings.Join(p.Moved, ", ")
-	if len(p.Dependents) > 0 {
-		what += fmt.Sprintf(" (+%d dependent(s))", len(p.Dependents))
-	}
-	if len(p.New) > 0 {
-		if what != "" {
-			what += ", "
-		}
-		what += "new: " + strings.Join(p.New, ", ")
-	}
-	var to []string
-	for _, m := range p.Machines {
-		if len(m.Receives) > 0 {
-			to = append(to, m.Machine)
-		}
-	}
-	if len(to) > 0 {
-		parts = append(parts, "builds "+what+" → "+strings.Join(to, ", "))
-	} else {
-		parts = append(parts, "builds "+what+", sent nowhere")
-	}
-	bus := "no bus step"
-	for _, s := range p.Steps {
-		switch {
-		case strings.HasPrefix(s, busUpgradeNeeded):
-			bus = busUpgradeNeeded
-		case strings.HasPrefix(s, "a planned bus step") && bus == "no bus step":
-			bus = "a bus step"
-		}
-	}
-	parts = append(parts, bus)
-	waiting := 0
-	for _, m := range p.Machines {
-		waiting += len(m.Waits)
-	}
-	if waiting > 0 {
-		parts = append(parts, fmt.Sprintf("%d wait(s) for a person", waiting))
-	}
-	return strings.Join(parts, "; ")
-}
-
-// planText is a change plan as a person reads it, for the pull request's comment.
-func planText(p link.ChangePlan) string {
-	var b strings.Builder
-	fmt.Fprintf(&b, "change plan of %s at %.8s into %s: %s\n", p.Repository, p.Head, p.Base, p.Summary)
-	for i, tier := range p.Tiers {
-		fmt.Fprintf(&b, "  tier %d: %s\n", i, strings.Join(tier, ", "))
-	}
-	for _, m := range p.Machines {
-		line := "  " + m.Machine + ": "
-		if len(m.Receives) > 0 {
-			line += "receives " + strings.Join(m.Receives, ", ")
-		}
-		if len(m.Waits) > 0 {
-			if len(m.Receives) > 0 {
-				line += "; "
-			}
-			line += "waits for a person: " + strings.Join(m.Waits, ", ")
-		}
-		b.WriteString(line + "\n")
-	}
-	for _, s := range p.Steps {
-		b.WriteString("  - " + s + "\n")
-	}
-	if len(p.Unread) > 0 {
-		fmt.Fprintf(&b, "  read by no module's build: %s\n", strings.Join(p.Unread, ", "))
-	}
-	return b.String()
-}

cmd/mesh-controller/changeplan_test.go

@@ -1,78 +0,0 @@
-package main
-
-import (
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// **One commit, one change plan** (novox/hq ADR 0238): the planner's reach, laid out machine by machine in
-// the build plan's order, with what is not an ordinary send said — the bus step, a module that waits for a
-// person, a provider whose consumers follow it.
-func TestAChangePlanSaysWhatEachMachineReceives(t *testing.T) {
-	const catalogue_ = "http://forge.internal:20000/novox/mesh-catalog.git"
-	entry := func(name, path string, on ...string) inventory.Entry {
-		e := fromRepo(name, catalogue_, path)
-		e.Source.BuiltFrom = "old"
-		e.On = on
-		return e
-	}
-	nats := entry("nats", "modules/nats", "anchor")
-	nats.Manifest.Provides = []catalogue.Offer{{Name: "mesh-bus"}}
-	gitea := entry("gitea", "modules/gitea", "anchor")
-	held := entry("photos", "modules/photos", "anchor", "laptop")
-	tools := fromRepo("node-tools", "http://forge.internal:20000/novox/mesh-tools.git", "node-tools")
-	tools.On = []string{"anchor", "laptop"}
-	entries := []inventory.Entry{nats, gitea, held, tools}
-	edges := []inventory.Edge{{From: "node-tools", To: "nats", Kind: inventory.EdgeStandsOn}}
-	policy := func(module string) (inventory.Upgrade, bool) {
-		if module == "photos" {
-			return inventory.Upgrade{RollOut: false, From: "a person"}, true
-		}
-		return inventory.Upgrade{RollOut: true}, true
-	}
-	plan := func(paths ...string) link.ChangePlan {
-		m := link.SourceMoved{Owner: "novox", Repo: "mesh-catalog", Base: "main", Commit: "head", Paths: paths}
-		return changePlanOf("novox/mesh-catalog", "main", "head", reachOfMerge(m, entries, nil, edges), entries, policy)
-	}
-
-	p := plan("modules/gitea/index.ts")
-	if p.Summary != "builds gitea → anchor; no bus step" {
-		t.Errorf("one module's change reads %q", p.Summary)
-	}
-
-	p = plan("modules/nats/Dockerfile", "modules/photos/x.js")
-	if !strings.Contains(p.Summary, "needs a person's bus upgrade") || !strings.Contains(p.Summary, "2 wait(s) for a person") ||
-		!strings.Contains(p.Summary, "(+1 dependent(s))") {
-		t.Errorf("the bus and a held module read %q", p.Summary)
-	}
-	got := map[string]string{}
-	for _, m := range p.Machines {
-		got[m.Machine] = strings.Join(m.Receives, ",") + "|" + strings.Join(m.Waits, ",")
-	}
-	// The bus first, what stands on it after: the build plan's order, per machine.
-	if got["anchor"] != "nats,node-tools|photos" || got["laptop"] != "node-tools|photos" {
-		t.Errorf("the deploy plan reads %v", got)
-	}
-	text := strings.Join(p.Steps, "\n")
-	// Said before the merge (novox/hq issue 336): merging it holds every send to the bus's machine until a
-	// person runs the bus's step, and the verb that does.
-	for _, want := range []string{"merging this needs a person's bus upgrade", "nothing else is sent to anchor",
-		"mesh_call mesh-controller.bus", "the same as the one running there", "photos waits for a person",
-		"nats provides mesh-bus"} {
-		if !strings.Contains(text, want) {
-			t.Errorf("the steps do not say %q:\n%s", want, text)
-		}
-	}
-
-	p = plan("merge-check.sh")
-	if !strings.HasPrefix(p.Summary, "builds nothing") || len(p.Machines) != 0 || strings.Join(p.Unread, ",") != "merge-check.sh" {
-		t.Errorf("a root file's plan reads %+v", p)
-	}
-	if !strings.Contains(planText(p), "read by no module's build: merge-check.sh") {
-		t.Errorf("the plan's text does not say why nothing is built:\n%s", planText(p))
-	}
-}

cmd/mesh-controller/check.go

@@ -1,287 +0,0 @@
-package main
-
-import (
-	"errors"
-	"fmt"
-	"io"
-	"os"
-	"path/filepath"
-	"sort"
-	"strings"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-)
-
-// moduleCheck judges manifests where they are written, with no mesh (novox/hq ADR 0037, issue 148).
-//
-// **The same functions registration runs, and nothing the command line adds** (ADR 0035): the strict
-// parse with every per-manifest problem, then the rules no single manifest can be judged against,
-// over exactly the manifests given. Somebody describing their own application in their own
-// repository runs this before pushing and finds out there, rather than when a running mesh refuses
-// the registration or, later, when a machine applies something that resolved and should not have.
-//
-// **What it cannot know without a store, it says.** The mesh's own seat set is the store's (ADR
-// 0122); this binary carries a compiled copy that the store overrides when loaded, so a claim on a
-// mesh seat is judged fully only at registration. A seat another module declares is unknown unless
-// that module's manifest is passed too. Both are printed as a note, not as a problem — a check that
-// refused what it could not see would teach people to ignore it.
-//
-// **And every identity against every bound it meets** (novox/hq ADR 0225, issue 263): each module's
-// identity, on a machine whose name is `longestMachine` characters, against the bound of every
-// provision it wants that a manifest given here offers. An overflow is refused in the pull request
-// that introduces it — a new requirement, a lowered bound, a longer slug — instead of on the
-// provider's machine when a real machine's name first meets the module's.
-// SomeManifestsVar, set by the merge gate, says the manifests given are only some of their repository's.
-const SomeManifestsVar = "MESH_MODULE_CHECK_SOME"
-
-func moduleCheck(paths []string, out io.Writer) error {
-	return moduleCheckFor(paths, catalogue.DefaultLongestMachine, out)
-}
-
-func moduleCheckFor(paths []string, longestMachine int, out io.Writer) error {
-	if len(paths) == 0 {
-		return errors.New("module check <manifest.json>... — one file per module; pass every " +
-			"manifest of a repository together so the rules between them are checked too")
-	}
-	shelf := catalogue.Shelf{}
-	faulted := map[string]bool{}
-	failed := 0
-	for _, path := range paths {
-		raw, err := os.ReadFile(path)
-		if err != nil {
-			fmt.Fprintf(out, "%s: %v\n", path, err)
-			failed++
-			continue
-		}
-		m, err := catalogue.ParseManifest(raw)
-		if err != nil {
-			fmt.Fprintf(out, "%s: %v\n", path, err)
-			failed++
-			continue
-		}
-		if first, twice := shelf[m.Module]; twice {
-			_ = first
-			fmt.Fprintf(out, "%s: %s was already given; two manifests name one module\n", path, m.Module)
-			failed++
-			continue
-		}
-		// A definition names no installation (novox/hq ADR 0112, ADR 0155): judged here, in the
-		// catalogue-wide test, and at registration, which refuses in the same words.
-		if wrong := catalogue.TrustProblems(m); len(wrong) > 0 {
-			for _, p := range wrong {
-				fmt.Fprintf(out, "%s: %s\n", path, p)
-			}
-			failed += len(wrong)
-			faulted[m.Module] = true
-		}
-		// A module that declares a setting names the keys of its mergeable files (novox/hq ADR 0326 §3,
-		// issue 574): judged where a definition is written, as at registration, never where a stored
-		// build is read again.
-		if wrong := catalogue.WrittenSettingsProblems(m); len(wrong) > 0 {
-			for _, p := range wrong {
-				fmt.Fprintf(out, "%s: %s\n", path, p)
-			}
-			failed += len(wrong)
-			faulted[m.Module] = true
-		}
-		if named := catalogue.InstallationProblems(m); len(named) > 0 {
-			for _, p := range named {
-				fmt.Fprintf(out, "%s: %s\n", path, p)
-			}
-			failed += len(named)
-			faulted[m.Module] = true
-		}
-		shelf[m.Module] = m
-	}
-
-	// Between the manifests: a seat declared twice, a use of a seat nothing declares, a claim on
-	// a seat that does not exist. Run only over what parsed, because a problem inside one manifest
-	// has already been said and would be said again here in a worse form.
-	//
-	// **Over some of a repository's manifests, a seat none of them declares is a note** (novox/hq issue 364), as
-	// this command's own word says above: the merge gate passes only the manifests a change touches, and says so
-	// with SomeManifestsVar, so a module that uses or claims a seat another module declares (the operator
-	// channel's, a channel bench) was refused there for a manifest it was not given. Given every manifest — the
-	// catalogue's own check, and registration — it stays a refusal.
-	some := os.Getenv(SomeManifestsVar) != ""
-	problems := catalogue.CatalogueProblems(shelf)
-	sort.Strings(problems)
-	for _, p := range problems {
-		if some && catalogue.IsUndeclaredSeat(p) {
-			fmt.Fprintf(out, "note: %s among the manifests given; registration judges it against the whole catalogue, "+
-				"and passing the declaring module's manifest too judges it here\n", p)
-			continue
-		}
-		fmt.Fprintln(out, p)
-		failed++
-	}
-
-	// Between the manifests too: an identity against the bounds of the provisions it wants, which
-	// only the provider's manifest states.
-	identities := catalogue.IdentityProblems(shelf, longestMachine)
-	sort.Strings(identities)
-	for _, p := range identities {
-		fmt.Fprintln(out, p)
-	}
-	failed += len(identities)
-
-	// And the data each module keeps (novox/hq ADR 0233): a provider that grants says what it keeps for
-	// its consumers, a directory a container writes is declared, and no backup line is written by hand.
-	data := catalogue.DataProblems(shelf)
-	sort.Strings(data)
-	for _, p := range data {
-		fmt.Fprintln(out, p)
-	}
-	failed += len(data)
-
-	var names []string
-	for name := range shelf {
-		names = append(names, name)
-	}
-	sort.Strings(names)
-
-	// **Every long-running resource says how it is ready** (novox/hq ADR 0240 rule 8): warned until the
-	// date, refused from it. The count is the catalogue's: its merge check keeps the number and lets a
-	// change lower it, never raise it.
-	undeclared := 0
-	required := !checkNow().Before(catalogue.HealthRequiredFrom)
-	for _, name := range names {
-		missing := catalogue.Undeclared(shelf[name])
-		undeclared += len(missing)
-		if len(missing) == 0 {
-			continue
-		}
-		if required {
-			for _, id := range missing {
-				fmt.Fprintf(out, "%s: %s stays up and does not say how it is ready: a long-running resource declares "+
-					"health since %s (novox/hq ADR 0240 rule 8)\n", name, id, catalogue.HealthRequiredFrom.Format("2006-01-02"))
-			}
-			failed += len(missing)
-			faulted[name] = true
-		}
-	}
-
-	// **A file that asks for a setting and does not say whether it is trusted counts as trusted** (novox/hq issue
-	// 339): listed and counted, never refused, so an author can opt out a file nothing trusts.
-	unsaid := 0
-	for _, name := range names {
-		unsaid += len(catalogue.UnsaidTrust(shelf[name]))
-	}
-
-	for _, name := range names {
-		m := shelf[name]
-		if faulted[name] {
-			continue
-		}
-		fmt.Fprintf(out, "%s: ok", name)
-		if n := len(m.Tools); n > 0 {
-			fmt.Fprintf(out, ", %d tool(s)", n)
-		}
-		if len(m.Invokes) > 0 {
-			fmt.Fprintf(out, ", invokes %s", joinInvokes(m.Invokes))
-		}
-		// The state it keeps and reads (novox/hq ADR 0201), so a reviewer sees what lands on the bus.
-		if len(m.State) > 0 {
-			kept := make([]string, 0, len(m.State))
-			for _, s := range m.State {
-				kept = append(kept, s.Name)
-			}
-			fmt.Fprintf(out, ", keeps state %s", strings.Join(kept, ", "))
-		}
-		// And the logs it keeps, with their caps (novox/hq ADR 0297).
-		if len(m.Logs) > 0 {
-			kept := make([]string, 0, len(m.Logs))
-			for _, l := range m.Logs {
-				kept = append(kept, fmt.Sprintf("%s (%d MiB)", l.Name, l.Cap()))
-			}
-			fmt.Fprintf(out, ", keeps log %s", strings.Join(kept, ", "))
-		}
-		if len(m.Reads) > 0 {
-			fmt.Fprintf(out, ", reads %s", strings.Join(m.Reads, ", "))
-		}
-		// The data it keeps, by class, so a reviewer sees what the mesh will protect and how.
-		if items := m.DataItems(); len(items) > 0 {
-			kept := make([]string, 0, len(items))
-			for _, it := range items {
-				kept = append(kept, it.ID+" ("+it.Class+")")
-			}
-			fmt.Fprintf(out, ", keeps %s", strings.Join(kept, ", "))
-		}
-		// How what it runs is ready (ADR 0240): each declared check, and what is judged by liveness alone.
-		var checks []string
-		for _, r := range m.Resources {
-			if h, has, _ := catalogue.ReadHealth(r); has {
-				checks = append(checks, fmt.Sprintf("%v by %s", r["id"], catalogue.HealthWords(h)))
-			}
-		}
-		if len(checks) > 0 {
-			fmt.Fprintf(out, ", ready: %s", strings.Join(checks, "; "))
-		}
-		if missing := catalogue.UnsaidTrust(m); len(missing) > 0 {
-			fmt.Fprintf(out, "; WARNING: %s ask(s) for a setting and do(es) not say whether it is trusted, so it counts as "+
-				"trusted: set at the terminal alone; say %q false where nothing trusts it (novox/hq issue 339)",
-				strings.Join(missing, ", "), catalogue.TrustedField)
-		}
-		if missing := catalogue.Undeclared(m); len(missing) > 0 {
-			fmt.Fprintf(out, "; WARNING: %s stay(s) up and say(s) not how it is ready — judged by liveness alone, "+
-				"refused from %s (ADR 0240 rule 8)", strings.Join(missing, ", "), catalogue.HealthRequiredFrom.Format("2006-01-02"))
-		}
-		fmt.Fprintln(out)
-	}
-	// The count the catalogue keeps (ADR 0240 rule 8), in a line its merge check reads.
-	fmt.Fprintf(out, "%s %d\n", UndeclaredHealthLine, undeclared)
-	fmt.Fprintf(out, "%s %d\n", UnsaidTrustLine, unsaid)
-	if failed > 0 {
-		return fmt.Errorf("%d problem(s) in %d manifest(s)", failed, len(paths))
-	}
-	fmt.Fprintf(out, "%d manifest(s) checked. Judged against the seats this binary carries; a claim on "+
-		"one of the mesh's own seats is judged fully at registration, and a seat declared by a "+
-		"module not given here reads as unknown. Identities judged on a %d-character machine name, "+
-		"against the bounds of the providers given here\n", len(paths), longestMachine)
-	return nil
-}
-
-// UndeclaredHealthLine starts the line `module check` says the count of long-running resources without
-// `health` in, over the manifests given: the catalogue's merge check compares it with the number it keeps.
-const UndeclaredHealthLine = "long-running resources without health:"
-
-// UnsaidTrustLine starts the line `module check` says the count of files that ask for a setting and do not say
-// whether it is trusted, and so count as trusted (novox/hq issue 339).
-const UnsaidTrustLine = "files asking for a setting without saying whether it is trusted:"
-
-// checkNow is the clock `module check` judges the date by; a test sets it.
-var checkNow = time.Now
-
-func joinInvokes(invokes []string) string {
-	if len(invokes) == 1 && invokes[0] == "*" {
-		return "every tool"
-	}
-	s := ""
-	for i, t := range invokes {
-		if i > 0 {
-			s += ", "
-		}
-		s += t
-	}
-	return s
-}
-
-// manifestsUnder lists every module.json below a directory, for `module check <dir>`.
-func manifestsUnder(dir string) ([]string, error) {
-	var found []string
-	err := filepath.WalkDir(dir, func(path string, d os.DirEntry, err error) error {
-		if err != nil {
-			return err
-		}
-		if d.IsDir() && (d.Name() == "node_modules" || d.Name() == ".git" || d.Name() == "dist") {
-			return filepath.SkipDir
-		}
-		if !d.IsDir() && d.Name() == "module.json" {
-			found = append(found, path)
-		}
-		return nil
-	})
-	sort.Strings(found)
-	return found, err
-}

cmd/mesh-controller/check_builds.go

@@ -1,87 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"os"
-	"strconv"
-
-	"github.com/novox/mesh-controller/internal/builder"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// A pull request's check builds go when it closes (novox/hq ADR 0350 §5): the build seat keeps them in the artifact
-// store's scratch namespace for the walk of its merge to take. **Let go of where the moment is heard**: the
-// controller ends the walk answering a merge — after that walk took what it reuses — and the delivery's owner, which
-// hears the forge say a pull request closed unmerged, asks the `forget-checks` verb; both let go through the store,
-// as the controller's own collection does. The build seat's holders let go of anything a week old on their own,
-// so a word lost here leaves a week's builds, never more.
-
-// checkBuildsIn is the scratch namespace as the controller reaches the artifact store.
-func checkBuildsIn(ctx context.Context, inv *inventory.Inventory) (builder.Scratch, error) {
-	shelf, err := inv.Catalogue(ctx)
-	if err != nil {
-		return nil, err
-	}
-	address, err := artifactStoreAddress(ctx, inv, shelf, "")
-	if err != nil {
-		return nil, err
-	}
-	if address == "" {
-		return nil, errors.New("the artifact store is not on the mesh's network")
-	}
-	return builder.Registry{Address: address}, nil
-}
-
-// forgetChecks lets go of a pull request's check builds and answers what it did.
-var forgetChecks = func(ctx context.Context, inv *inventory.Inventory, pull builder.PullRef) (string, error) {
-	scratch, err := checkBuildsIn(ctx, inv)
-	if err != nil {
-		return "", err
-	}
-	n, err := scratch.Forget(ctx, pull)
-	if err != nil {
-		return "", fmt.Errorf("%s: %d check(s)' builds let go of, and not all: %w", pull, n, err)
-	}
-	return fmt.Sprintf("%s: %d check(s)' builds let go of", pull, n), nil
-}
-
-// forgetChecksOfWalk lets go, on the save that ends a walk, of the check builds of every pull request whose merge
-// it answers: the walk took what it reuses. Said, never fatal.
-func forgetChecksOfWalk(ctx context.Context, inv *inventory.Inventory, p inventory.Plan) {
-	if p.WalkSaid != inventory.WalkEnded || p.Delivery == nil {
-		return
-	}
-	for _, pull := range reuseAskOf(&p).Pulls {
-		said, err := forgetChecks(ctx, inv, builder.PullRef{Owner: pull.Owner, Repo: pull.Repo, Number: pull.Number})
-		if err != nil {
-			fmt.Fprintf(os.Stderr, "%s: its check builds stay until the week's sweep: %v\n", p.ID, err)
-			continue
-		}
-		fmt.Printf("%s: %s\n", p.ID, said)
-	}
-}
-
-// forgetChecksCommand is `forget-checks <owner> <repo> <number>`: the verb the delivery's owner asks when the forge
-// says a pull request closed unmerged (novox/hq ADR 0350 §5).
-func forgetChecksCommand(ctx context.Context, args []string) error {
-	if len(args) != 3 {
-		return errors.New("forget-checks <owner> <repo> <number>")
-	}
-	number, err := strconv.Atoi(args[2])
-	if err != nil || number <= 0 {
-		return fmt.Errorf("%q is not a pull request's number", args[2])
-	}
-	open, err := openStores(ctx)
-	if err != nil {
-		return err
-	}
-	defer open.Close()
-	said, err := forgetChecks(ctx, open.inventory, builder.PullRef{Owner: args[0], Repo: args[1], Number: number})
-	if err != nil {
-		return err
-	}
-	fmt.Println(said)
-	return nil
-}

cmd/mesh-controller/check_builds_test.go

@@ -1,216 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"reflect"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/builder"
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// One build per change (novox/hq ADR 0350), as the controller asks it and takes it in.
-
-// The check of a change is asked to build what a merge of it would move, in the walk's order: a module of the
-// repository checked from the merge, one standing on it from its own repository as the walk builds it, and one
-// that reads the repository through a context not at all. A change that moves no module builds nothing.
-func TestACheckIsAskedToBuildWhatTheMergeWouldMove(t *testing.T) {
-	entries := []inventory.Entry{
-		{Manifest: catalogue.Manifest{Module: "app"}, Source: inventory.Source{Repository: "novox/shop", Seat: "git", Path: "modules/app"}},
-		{Manifest: catalogue.Manifest{Module: "web"}, Source: inventory.Source{Repository: "novox/web", Seat: "git", Ref: "main"}},
-		{Manifest: catalogue.Manifest{Module: "docs"}, Source: inventory.Source{Repository: "novox/docs", Seat: "git"}},
-	}
-	p := link.PullUpdated{Owner: "novox", Repo: "shop", Number: 7, Base: "main", Commit: "abc"}
-	scope := checkScope{Reach: mergeReach{Packaging: entries[2:], Plan: inventory.Plan{Tiers: [][]string{{"app", "docs"}, {"web"}}}}}
-	clone := func(s inventory.Source) (string, error) { return "http://forge.invalid/" + s.Repository + ".git", nil }
-
-	got := checkBuildsOf(p, scope, entries, clone)
-	want := []link.CheckBuild{
-		{Module: "app", Path: "modules/app", Merged: true, Tier: 0},
-		{Module: "docs", Tier: 0, Skip: "its build reads novox/shop through a context, which a check cannot hand the merge"},
-		{Module: "web", Repository: "http://forge.invalid/novox/web.git", Ref: "main", Tier: 1},
-	}
-	if !reflect.DeepEqual(got, want) {
-		t.Fatalf("the check is asked to build\n%+v\nwant\n%+v", got, want)
-	}
-	if got := checkBuildsOf(p, checkScope{}, entries, clone); got != nil {
-		t.Fatalf("a change that moves no module asks for builds: %+v", got)
-	}
-}
-
-// A walk's ask carries its leave to take a check's build, naming the pull requests of the merges it answers; a dry
-// run never does, and neither does an ask that is not a walk's.
-func TestOnlyAWalksAskTakesAChecksBuildAndADryRunNever(t *testing.T) {
-	p := &inventory.Plan{Delivery: &inventory.PlanDelivery{Merges: []inventory.PlanMerge{
-		{Repository: "novox/shop", Number: 7}, {Repository: "http://forge.invalid/novox/web.git", Number: 3},
-		{Repository: "novox/shop", Number: 7}, {Repository: "novox/shop"}}}}
-	asked := reuseAskOf(p)
-	if want := []link.PullRef{{Owner: "novox", Repo: "shop", Number: 7}, {Owner: "novox", Repo: "web", Number: 3}}; !reflect.DeepEqual(asked.Pulls, want) {
-		t.Fatalf("the walk names %+v", asked.Pulls)
-	}
-	walk := withReuse(t.Context(), asked)
-	if reuseAsked(walk, false) != asked {
-		t.Fatal("a walk's ask does not carry its leave")
-	}
-	if reuseAsked(walk, true) != nil {
-		t.Fatal("a dry run carries a leave to take a check's build")
-	}
-	if reuseAsked(t.Context(), false) != nil {
-		t.Fatal("an ask that is not a walk's carries a leave")
-	}
-}
-
-// A walk ended lets go of its merges' check builds — only once it ended, after it took what it reuses.
-func TestAWalkEndedLetsGoOfItsMergesCheckBuilds(t *testing.T) {
-	var forgot []builder.PullRef
-	was := forgetChecks
-	forgetChecks = func(_ context.Context, _ *inventory.Inventory, pull builder.PullRef) (string, error) {
-		forgot = append(forgot, pull)
-		return "", nil
-	}
-	t.Cleanup(func() { forgetChecks = was })
-	p := inventory.Plan{ID: "plan-1", Delivery: &inventory.PlanDelivery{Merges: []inventory.PlanMerge{
-		{Repository: "novox/shop", Number: 7}}}}
-
-	p.WalkSaid = inventory.WalkStarted
-	forgetChecksOfWalk(t.Context(), nil, p)
-	p.WalkSaid = ""
-	forgetChecksOfWalk(t.Context(), nil, p)
-	if len(forgot) != 0 {
-		t.Fatalf("a walk not ended let go of %v, which it may still take", forgot)
-	}
-	p.WalkSaid = inventory.WalkEnded
-	forgetChecksOfWalk(t.Context(), nil, p)
-	if want := []builder.PullRef{{Owner: "novox", Repo: "shop", Number: 7}}; !reflect.DeepEqual(forgot, want) {
-		t.Fatalf("the walk ended let go of %v", forgot)
-	}
-}
-
-// A build in the scratch namespace is never registered: only the walk's copy in the module's own namespace is.
-func TestABuildInTheScratchNamespaceIsNeverRegistered(t *testing.T) {
-	if got := inScratch([]link.MadeArtifact{{Name: "server", Reference: "store.internal:5000/app/server@sha256:aa"}}); got != "" {
-		t.Fatalf("a module's own build reads as a scratch build: %s", got)
-	}
-	scratch := "store.internal:5000/scratch/app/server@sha256:aa"
-	if got := inScratch([]link.MadeArtifact{{Name: "server", Reference: scratch}}); got != scratch {
-		t.Fatalf("a scratch build was not found: %q", got)
-	}
-	if got := inScratch([]link.MadeArtifact{{Name: "look", Reference: "http://store.internal:5000/v2/scratch/app/look/blobs/sha256:bb"}}); got == "" {
-		t.Fatal("a scratch archive was not found")
-	}
-}
-
-// The walk says per module what it did: "reused from …" or "built: <why>" — and a build seat from before says
-// neither, which is said.
-func TestAWalksBuildSaysWhetherItReusedOrBuilt(t *testing.T) {
-	if got := (link.BuildResult{Reused: "reused from the check of novox/shop#7"}).MadeWords(); got != "reused from the check of novox/shop#7" {
-		t.Fatalf("said %q", got)
-	}
-	if got := (link.BuildResult{BuiltWhy: "no check built it"}).MadeWords(); got != "built: no check built it" {
-		t.Fatalf("said %q", got)
-	}
-	if got := (link.BuildResult{}).MadeWords(); !strings.Contains(got, "predates ADR 0350") {
-		t.Fatalf("said %q", got)
-	}
-}
-
-// A walk's module the check's build stood in for is registered by the digest the check built — the copy in the
-// module's namespace — and the walk keeps "reused from …" for it; its first-node gate judges that registered
-// build as it judges one the walk built. A scratch reference is refused. Needs the store (MESH_TEST_POSTGRES), and
-// is named in testdata/store-tests.
-func TestAReusedCheckBuildIsRegisteredByItsDigestAndGatedAsABuiltOne(t *testing.T) {
-	g := aGateMesh(t)
-	ctx := t.Context()
-	inv := g.open.inventory
-	gateEvery = 0
-
-	digest := "sha256:" + strings.Repeat("c", 64)
-	reused := func(id, reference string) link.BuildResult {
-		manifest := mustJSON(t, catalogue.Manifest{Module: "app", Version: "c3", Resources: []map[string]any{
-			{"id": "svc", "type": "container", "name": "app", "image": reference}}})
-		return link.BuildResult{ID: id, Repository: "novox/mesh-catalog", Path: "modules/app", Ref: "main", On: "anchor",
-			Commit: "c3", Manifest: manifest, Trunk: "main", OnTrunk: true, Branches: []string{"main"},
-			Made:   []link.MadeArtifact{{Name: "server", Kind: "image", Reference: reference}},
-			Source: &link.SourceOnSeat{Seat: "git", Repository: "novox/mesh-catalog"},
-			Reused: "reused from the check of novox/mesh-catalog#9 at head abcdefabcdef (merged into trunk 123456123456): server " + digest,
-			ReusedFrom: &link.ReusedFrom{Pull: link.PullRef{Owner: "novox", Repo: "mesh-catalog", Number: 9},
-				Head: "abcdefabcdef", Trunk: "123456123456", Key: "r1:" + strings.Repeat("1", 64)}}
-	}
-	if _, _, err := takeIn(ctx, inv, reused(link.NewBuildID(time.Now()), "store.internal:5000/scratch/app/server@"+digest)); err == nil ||
-		!strings.Contains(err.Error(), "scratch") {
-		t.Fatalf("a build in the scratch namespace was registered: %v", err)
-	}
-	id := link.NewBuildID(time.Now().Add(time.Second))
-	result := reused(id, "store.internal:5000/app/server@"+digest)
-	if _, _, err := takeIn(ctx, inv, result); err != nil {
-		t.Fatal(err)
-	}
-	current, err := inv.CurrentBuilds(ctx)
-	if err != nil || current["app"].Commit != "c3" {
-		t.Fatalf("the reused build is not what app is registered at: %+v %v", current["app"], err)
-	}
-	shelf, err := inv.Catalogue(ctx)
-	if err != nil {
-		t.Fatal(err)
-	}
-	raw, _ := json.Marshal(shelf["app"].Resources)
-	if !strings.Contains(string(raw), "app/server@"+digest) {
-		t.Fatalf("app is registered as %s, not by the check's digest in its own namespace", raw)
-	}
-
-	// The walk asked it: the walk keeps what its build did, and its gate judges the registered build.
-	asked := time.Now().UTC()
-	p := g.plan(t)
-	p.Commit = "c3"
-	p.Modules["app"] = &inventory.PlanModule{State: "asked", AskedAt: &asked, Build: id}
-	if err := inv.SavePlan(ctx, &p); err != nil {
-		t.Fatal(err)
-	}
-	planBuiltSaying(ctx, g.open, "app", "c3", "", asked, id, result.MadeWords())
-	p = g.plan(t)
-	if m := p.Modules["app"]; m.State != "built" || !strings.HasPrefix(m.Made, "reused from the check of novox/mesh-catalog#9") {
-		t.Fatalf("the walk keeps %+v", m)
-	}
-	for i := 0; i < 6; i++ {
-		advancePlans(ctx, g.open)
-	}
-	p = g.plan(t)
-	gate := p.Modules["app"].Gate
-	if gate == nil || gate.To != "c3" || gate.Verdict != inventory.GatePassed {
-		t.Fatalf("the gate judged %+v, not the reused build", gate)
-	}
-	if sent, _, _ := inv.SentBuilds(ctx, "anchor"); sent["app"] != "c3" {
-		t.Fatalf("the first machine was sent %v, not the reused build", sent)
-	}
-}
-
-// A walk's leave names the builds its own pull requests' verdicts made, and none when they cannot be read: the
-// builder takes nothing a verdict does not name (novox/hq ADR 0350 §2).
-func TestAWalksLeaveNamesTheBuildsItsPullRequestsVerdictsMade(t *testing.T) {
-	was := checkedBuildsOf
-	t.Cleanup(func() { checkedBuildsOf = was })
-	var asked []link.PullRef
-	named := []link.CheckedBuild{{Pull: link.PullRef{Owner: "novox", Repo: "shop", Number: 7}, Check: "build-1",
-		Built: link.CheckBuilt{Module: "app", Key: "r1:1"}}}
-	checkedBuildsOf = func(_ context.Context, pulls []link.PullRef) ([]link.CheckedBuild, error) {
-		asked = pulls
-		return named, nil
-	}
-	pulls := []link.PullRef{{Owner: "novox", Repo: "shop", Number: 7}}
-	if got := reuseWithVerdicts(t.Context(), &link.ReuseAsk{Pulls: pulls}); !reflect.DeepEqual(got.Builds, named) ||
-		!reflect.DeepEqual(asked, pulls) {
-		t.Fatalf("the leave names %+v, read for %+v", got.Builds, asked)
-	}
-	checkedBuildsOf = func(context.Context, []link.PullRef) ([]link.CheckedBuild, error) {
-		return nil, errors.New("no bus")
-	}
-	if got := reuseWithVerdicts(t.Context(), &link.ReuseAsk{Pulls: pulls}); got.Builds != nil {
-		t.Fatalf("verdicts that could not be read named %+v", got.Builds)
-	}
-}

cmd/mesh-controller/check_here.go

@@ -1,203 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"flag"
-	"fmt"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/builder"
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// `check-here` is a pull request's merge check run on the machine at hand **exactly as the build seat
-// runs it** (novox/hq issue 286): the same code (builder.Check), the same ask the controller would make of
-// the seat — the gate's modules and judge by the planner's own answer over the facts snapshot, the
-// repositories beside it at the refs the snapshot says the seat clones them at — in the toolchain image
-// the mesh holds, as the user the build seat runs as, against a throwaway store and bus of the versions
-// the mesh runs.
-//
-// **The build seat is the reference.** A merge-check.sh that passed on an agent's machine failed on the
-// seat for three reasons that were each the agent's environment, never the change: a newer Go whose gofmt
-// lays a file out differently, a sibling checkout at the agent's feature branch where the seat had the
-// commit the mesh runs, and a different user. Run here, a check sees what the seat will.
-//
-//	check-here [--tree <checkout>] [--base main] [--registry <artifact store>] [--forge <url of the owner>]
-//	           [--number <n>] [--user uid:gid] [--facts store|<file>] [--keep]
-//
-// The checkout's HEAD is what is checked, and it must be committed: the seat checks a commit, never a
-// working tree.
-func checkHereCommand(ctx context.Context, args []string) error {
-	set := flag.NewFlagSet("check-here", flag.ContinueOnError)
-	tree := set.String("tree", ".", "the change's checkout; its HEAD is checked")
-	base := set.String("base", "main", "the branch the change would merge into")
-	registry := set.String("registry", os.Getenv("MESH_REGISTRY"), "the artifact store holding the facts and the toolchains")
-	forge := set.String("forge", "", "where the repositories beside it are cloned from, as <forge>/<repository>.git; "+
-		"the checkout's origin without its own name when not given")
-	number := set.Int("number", 0, "the pull request's number, when there is one")
-	// The build seat's service runs as root, and its check containers run as the builder does.
-	user := set.String("user", "0:0", "the user the check's containers run as: the build seat's")
-	keep := set.Bool("keep", false, "keep the workspace afterwards")
-	factsFrom := set.String("facts", "store", "the facts snapshot: `store`, the one the artifact store holds — "+
-		"what the seat reads — or a file")
-	if _, err := parseAround(set, args); err != nil {
-		return err
-	}
-	if *registry == "" {
-		return errors.New("check-here reads the facts and the toolchains from the artifact store: --registry <host:port> or MESH_REGISTRY")
-	}
-	dir, err := filepath.Abs(*tree)
-	if err != nil {
-		return err
-	}
-	git := func(args ...string) (string, error) {
-		cmd := exec.CommandContext(ctx, "git", args...)
-		cmd.Dir = dir
-		out, err := cmd.Output()
-		return strings.TrimSpace(string(out)), err
-	}
-	if dirty, err := git("status", "--porcelain", "--untracked-files=no"); err != nil {
-		return fmt.Errorf("%s is not a checkout: %w", dir, err)
-	} else if dirty != "" {
-		return errors.New("the checkout has changes not committed: the build seat checks a commit, so commit first")
-	}
-	head, err := git("rev-parse", "HEAD")
-	if err != nil {
-		return err
-	}
-	origin, err := git("remote", "get-url", "origin")
-	if err != nil {
-		return fmt.Errorf("the checkout has no origin to say which repository it is: %w", err)
-	}
-	owner, repo, prefix := ownerRepoOf(origin)
-	if *forge == "" {
-		*forge = prefix
-	}
-	if _, err := git("fetch", "--quiet", "origin", *base); err != nil {
-		return fmt.Errorf("cannot fetch %s to say what the change touches: %w", *base, err)
-	}
-	// Without rename detection, so a file moved out of a build source is said under its old name as well:
-	// its going is a change to the build that held it (novox/hq ADR 0267).
-	changedText, err := git("diff", "--name-only", "--no-renames", "origin/"+*base+"...HEAD")
-	if err != nil {
-		return err
-	}
-	var paths, removed []string
-	for _, p := range strings.Split(changedText, "\n") {
-		if p = strings.TrimSpace(p); p == "" {
-			continue
-		}
-		paths = append(paths, p)
-		if _, err := os.Stat(filepath.Join(dir, p)); os.IsNotExist(err) {
-			removed = append(removed, p)
-		}
-	}
-
-	_ = os.Setenv("MESH_REGISTRY", *registry)
-	f, err := readFacts(ctx, *factsFrom)
-	if err != nil {
-		return fmt.Errorf("the facts snapshot cannot be read: %w", err)
-	}
-	entries, read, edges, err := graphOfFacts(f)
-	if err != nil {
-		return err
-	}
-	p := link.PullUpdated{Owner: owner, Repo: repo, Number: *number, Base: *base, Commit: head, Paths: paths,
-		Removed: removed, ModuleDirs: moduleDirsIn(dir, paths), ModuleDirsSaid: true}
-	scope := pullScope(p, entries, read, edges)
-	_, scriptErr := os.Stat(filepath.Join(dir, builder.CheckScript))
-	if !scope.gated() && !scope.Mesh {
-		fmt.Printf("%s: %s, and the repository is not the mesh's: the build seat runs nothing for it\n",
-			owner+"/"+repo, noModuleTouched)
-		return nil
-	}
-	if !scope.gated() && scriptErr != nil {
-		fmt.Printf("%s: %s; %s\n", owner+"/"+repo, noModuleTouched, noMergeCheck)
-		return nil
-	}
-
-	toolchains := map[string]string{}
-	for language, reference := range f.Versions.Toolchains {
-		toolchains[language] = catalogue.Rerouted(reference, *registry)
-	}
-	if len(toolchains) == 0 {
-		return errors.New("the facts snapshot names no toolchain: it was taken by a controller from before " +
-			"issue 286, and the seat's toolchain cannot be known here")
-	}
-	beside := map[string]builder.Beside{}
-	for d, ref := range f.Beside {
-		from := d
-		if d == "mesh-controller-main" {
-			from = "mesh-controller"
-		}
-		beside[d] = builder.Beside{Repository: strings.TrimSuffix(*forge, "/") + "/" + from + ".git", Ref: ref}
-	}
-	id := fmt.Sprintf("check-here-%d", time.Now().UnixNano())
-	spec := builder.CheckSpec{ID: id, Repository: dir, Ref: head, Owner: owner, Repo: repo, Number: *number,
-		Paths: paths, Beside: beside, Modules: scope.Modules, New: scope.New, Manifests: scope.Manifests,
-		Base: *base, Judge: scope.Judge, Toolchain: toolchains["go"], Toolchains: toolchains, User: *user}
-
-	workspace, err := os.MkdirTemp("", "mesh-check-here-")
-	if err != nil {
-		return err
-	}
-	if !*keep {
-		defer removeWorkspace(spec.Toolchain, workspace, *user)
-	}
-	fmt.Fprintf(os.Stderr, "checking %s/%s at %.8s as the build seat would, against the facts of %s, in %s\n",
-		owner, repo, head, f.Taken.Format(time.RFC3339), workspace)
-	v, err := builder.Check(ctx, builder.Command, spec, workspace, *registry, builder.GitCredential{},
-		func(step, message string) {
-			if step != "output" {
-				fmt.Fprintf(os.Stderr, "  [%s] %s\n", step, message)
-			}
-		})
-	if err != nil {
-		return fmt.Errorf("the check could not run — on the seat an error, never a pass: %w", err)
-	}
-	fmt.Println(v.Report)
-	fmt.Println()
-	fmt.Printf("mesh/merge-gate: %s — %s\n", strings.ToUpper(v.Gate.Verdict), v.Gate.Summary)
-	if v.Repo != nil {
-		fmt.Printf("mesh/repo-check: %s — %s\n", strings.ToUpper(v.Repo.Verdict), v.Repo.Summary)
-	}
-	for _, l := range []*builder.Layer{v.Gate, v.Repo} {
-		if l != nil && l.Verdict != "pass" && l.Verdict != "warning" {
-			return errors.New("the build seat would not pass this change")
-		}
-	}
-	return nil
-}
-
-// ownerRepoOf reads owner, repository and the owner's URL from a remote: ssh://git@host:222/novox/mesh-host.git
-// → novox, mesh-host, ssh://git@host:222/novox.
-func ownerRepoOf(remote string) (string, string, string) {
-	trimmed := strings.TrimSuffix(strings.TrimSuffix(remote, "/"), ".git")
-	cut := strings.LastIndexAny(trimmed, "/:")
-	if cut < 0 {
-		return "", trimmed, ""
-	}
-	repo, prefix := trimmed[cut+1:], trimmed[:cut]
-	owner := prefix
-	if at := strings.LastIndexAny(prefix, "/:"); at >= 0 {
-		owner = prefix[at+1:]
-	}
-	return owner, repo, prefix
-}
-
-// removeWorkspace removes what the check left, written as the seat's user: by a container of that user
-// when it is not this one.
-func removeWorkspace(image, workspace, user string) {
-	if image != "" && user != fmt.Sprintf("%d:%d", os.Getuid(), os.Getgid()) {
-		// Everything in it — the check's HOME is the workspace, so the toolchain's own files are there too.
-		_ = exec.Command("docker", "run", "--rm", "--user", user, "--volume", workspace+":/workspace", image,
-			"sh", "-c", "rm -rf /workspace/* /workspace/.[!.]*").Run()
-	}
-	_ = os.RemoveAll(workspace)
-}

cmd/mesh-controller/check_test.go

@@ -1,124 +0,0 @@
-package main
-
-import (
-	"bytes"
-	"os"
-	"path/filepath"
-	"strings"
-
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/beside"
-	"github.com/novox/mesh-controller/internal/catalogue"
-)
-
-// The check anybody can run is the check registration runs (novox/hq issue 148, ADR 0037): a manifest
-// with a known fault is named, and one without passes, with no store opened.
-func TestModuleCheckNamesAFaultAndNeedsNoMesh(t *testing.T) {
-	dir := t.TempDir()
-	good := filepath.Join(dir, "good.json")
-	bad := filepath.Join(dir, "bad.json")
-	os.WriteFile(good, []byte(`{"module":"shop","version":"1","tools":["price"],"invokes":["mesh-catalog.catalog_modules"]}`), 0o600)
-	os.WriteFile(bad, []byte(`{"module":"till","version":"1","invokes":["shop"]}`), 0o600)
-
-	var out bytes.Buffer
-	if err := moduleCheck([]string{good}, &out); err != nil {
-		t.Fatalf("a sound manifest was refused: %v\n%s", err, out.String())
-	}
-	if !strings.Contains(out.String(), "shop: ok, 1 tool(s), invokes mesh-catalog.catalog_modules") {
-		t.Fatalf("the report does not say what it checked:\n%s", out.String())
-	}
-
-	out.Reset()
-	err := moduleCheck([]string{good, bad}, &out)
-	if err == nil {
-		t.Fatal("a manifest invoking a module and no tool passed")
-	}
-	if !strings.Contains(out.String(), `till invokes "shop", which does not name a tool`) {
-		t.Fatalf("the fault is not named in the manifest's words:\n%s", out.String())
-	}
-}
-
-// The rules between manifests run over what was given together: a seat two modules declare is
-// refused, which no single-manifest check can see.
-func TestModuleCheckJudgesBetweenTheManifestsGiven(t *testing.T) {
-	dir := t.TempDir()
-	a := filepath.Join(dir, "a.json")
-	b := filepath.Join(dir, "b.json")
-	os.WriteFile(a, []byte(`{"module":"a","version":"1","seats":[{"name":"printer","scope":"mesh"}]}`), 0o600)
-	os.WriteFile(b, []byte(`{"module":"b","version":"1","seats":[{"name":"printer","scope":"mesh"}]}`), 0o600)
-	var out bytes.Buffer
-	if err := moduleCheck([]string{a, b}, &out); err == nil {
-		t.Fatalf("two declarations of one seat passed:\n%s", out.String())
-	}
-	if !strings.Contains(out.String(), "a seat name means one protocol") {
-		t.Fatalf("the cross-manifest rule was not the one named:\n%s", out.String())
-	}
-}
-
-// The real catalogue passes the command, the way it passes the test that used to be the only check.
-func TestModuleCheckPassesTheCatalogue(t *testing.T) {
-	root := beside.Catalogue(t)
-	paths, err := manifestsUnder(root)
-	if err != nil || len(paths) == 0 {
-		t.Fatalf("no manifests under %s: %v", root, err)
-	}
-	var out bytes.Buffer
-	if err := moduleCheck(paths, &out); err != nil {
-		t.Fatalf("the catalogue does not pass its own check: %v\n%s", err, out.String())
-	}
-}
-
-func TestRegistrationRefusesADefinitionNamingAnInstallation(t *testing.T) {
-	// novox/hq ADR 0155: the check moves to registration once the catalogue passes it. Both
-	// ways in — `module add` and a build's result — go through this, and a name declared on
-	// purpose passes with its reason.
-	named := catalogue.Manifest{Module: "idp", Resources: []map[string]any{
-		{"id": "server", "type": "container", "image": "x@sha256:aa",
-			"env": map[string]any{"KC_HOSTNAME": "https://login.mesh-one.be"}},
-	}}
-	err := namesNoInstallation(named)
-	if err == nil || !strings.Contains(err.Error(), "login.mesh-one.be") ||
-		!strings.Contains(err.Error(), catalogue.NamesOnPurpose) {
-		t.Fatalf("a definition naming an installation is refused with the name and the way out; got %v", err)
-	}
-	meant := catalogue.Manifest{Module: "site", Resources: []map[string]any{
-		{"id": "server", "type": "container", "image": "registry.mesh-one.be/org/site@sha256:cc",
-			catalogue.NamesOnPurpose: map[string]any{
-				"registry.mesh-one.be": "built outside the mesh until its repository is a build source here"}},
-	}}
-	if err := namesNoInstallation(meant); err != nil {
-		t.Fatalf("a name declared on purpose passes; got %v", err)
-	}
-}
-
-// **The controller's own manifest names every verb of its seat** (novox/hq ADR 0132): its tools lagged
-// the seat's verbs for weeks, and `module check` — the gate's first step for a change touching it —
-// refused it. Held here, so a verb added to the table without the manifest fails this repository's
-// own suite rather than its next pull request's gate.
-func TestTheControllersManifestServesEveryVerbOfItsSeat(t *testing.T) {
-	var out strings.Builder
-	if err := moduleCheck([]string{"../../module.json"}, &out); err != nil {
-		t.Fatalf("the controller's own module.json fails module check: %v\n%s", err, out.String())
-	}
-}
-
-// A module that uses a seat another module declares (novox/hq issue 364): refused over the whole catalogue when the
-// declarer is missing, a note when the gate says it gives only the manifests a change touches.
-func TestASeatAnotherModuleDeclaresIsANoteOverSomeManifests(t *testing.T) {
-	dir := t.TempDir()
-	user := filepath.Join(dir, "user.json")
-	os.WriteFile(user, []byte(`{"module":"asker","version":"1","uses":["operator-channel"]}`), 0o600)
-	var out bytes.Buffer
-	if err := moduleCheck([]string{user}, &out); err == nil {
-		t.Fatalf("a use of a seat nothing given declares passed the whole-catalogue check:\n%s", out.String())
-	}
-	t.Setenv(SomeManifestsVar, "1")
-	out.Reset()
-	if err := moduleCheck([]string{user}, &out); err != nil {
-		t.Fatalf("over some manifests the use was refused:\n%s", out.String())
-	}
-	if !strings.Contains(out.String(), "note: asker uses the seat \"operator-channel\"") {
-		t.Fatalf("the note was not said:\n%s", out.String())
-	}
-}

cmd/mesh-controller/checks.go

@@ -1,548 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"path"
-	"regexp"
-	"runtime/debug"
-	"slices"
-	"sort"
-	"strings"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// A pull request's merge check (novox/hq to-be 45 §9, ADR 0237 as amended 2026-10-06): the forge
-// announces every pull request's new head, the controller decides what is checked, asks the build seat to
-// check it, and says the verdict as `checked`, which the forge's holder sets as the pull request's
-// statuses. **Before merge, never after**: every check the mesh had ran after a merge, on a machine.
-//
-// **The mesh's module graph decides, not the repository.** The controller holds the graph — every module,
-// the repository and directory it is built from — and maps the pull request's changed paths onto it by
-// the planner's own answer (reachOfMerge, touchedBy — the one place a changed file is mapped onto modules,
-// for the merge handler, the release planner, the merge gate and this check; issue 280): **a changed file
-// touches exactly the modules whose build reads it** — a module's own directory (the whole repository for
-// one built from its root), or a repository its recipe packages. A file no build reads — a script at the
-// root, a README — touches no module. A directory the change adds a module.json in, which the graph does
-// not hold yet (said by the head, issue 278), is a new module and is checked too.
-//
-//   - touches a module: the build seat runs **the gate** — `mesh/merge-gate`, the touched manifests, every
-//     machine composed with the change, the replays — and the repository's own merge-check.sh beside it;
-//   - touches none, in a repository that is the mesh's (it sources a module on some branch, or shares the
-//     core's owner): the gate is a pass that says so — a fact, not a missing check — and the repository's
-//     own merge-check.sh runs as `mesh/repo-check`, a warning when it has none;
-//   - touches none, anywhere else: the gate is a pass that says so, and nothing more is said.
-//
-// What is checked is decided here and run there (internal/builder/check.go).
-
-// checkTimeout is how long one check may run on the build seat. Said here so the ask's watchdog (S6)
-// and the builder agree on what late means.
-const checkTimeout = 45 * time.Minute
-
-// noModuleTouched is the gate's word for a change that touches nothing of the graph.
-const noModuleTouched = "the change touches no module of the mesh's graph"
-
-// noMergeCheck is the repository layer's word for a repository of the mesh with no merge-check.sh.
-const noMergeCheck = "the repository declares no merge-check.sh: none of its own tests run before it merges"
-
-// coreModules are the modules whose repositories are the mesh's core, by the directory a check finds
-// each beside it — and whose owner is the mesh's own.
-var coreModules = map[string]string{"mesh-controller": "mesh-controller", "mesh-host": "mesh-host",
-	"node-tools": "mesh-tools", "nats": "mesh-catalog"}
-
-// checkScope is what a pull request reaches of the mesh's graph, as the planner reckons it.
-type checkScope struct {
-	// Modules are the modules a merge of the change would move itself — built from the repository into
-	// the pull request's base and reading a changed file, or packaging the repository's source — and
-	// Dependents those the plan would build after them; New the directories it adds a module in.
-	Modules    []string
-	Dependents []string
-	New        []string
-	// Manifests are the moved modules' and the new ones' manifests in the change's tree.
-	Manifests []string
-	// Width is how many modules a merge would build, in how many tiers; Unread the changed files no
-	// module's build reads.
-	Width, Tiers int
-	Unread       []string
-	// Mesh says the repository is the mesh's: modules are built from it on some branch, its owner is the
-	// core's, or the change adds a module to it.
-	Mesh bool
-	// Judge is who judges the gate (link.JudgeSelf, link.JudgeValidator, or the running controller).
-	Judge string
-	// From is a module built from the repository, for how the mesh clones it; nil when none is.
-	From *inventory.Entry
-	// Reach is the planner's whole answer, which the change plan is made from.
-	Reach mergeReach
-}
-
-func (s checkScope) gated() bool { return len(s.Modules)+len(s.New) > 0 }
-
-// pullScope is what a pull request reaches: **the planner's own answer** (reachOfMerge), asked as if the
-// head were merged into the base — never a mapping of its own, so a change to what a merge touches
-// changes what is checked with it (novox/hq ADR 0238).
-func pullScope(p link.PullUpdated, entries []inventory.Entry, read map[string][]inventory.ReadRepository,
-	edges []inventory.Edge) checkScope {
-	m := link.SourceMoved{Owner: p.Owner, Repo: p.Repo, Base: p.Base, CloneURL: p.CloneURL, Commit: p.Commit,
-		Paths: p.Paths, PathsTruncated: p.PathsTruncated, Removed: p.Removed, ModuleDirs: p.ModuleDirs,
-		ModuleDirsSaid: p.ModuleDirsSaid}
-	r := reachOfMerge(m, entries, read, edges)
-	s := checkScope{Modules: r.Moved(), Dependents: r.Dependents(), New: r.Added, Unread: r.Unread,
-		Width: len(r.Plan.Modules), Tiers: len(r.Plan.Tiers), Reach: r}
-	for _, e := range append(append([]inventory.Entry{}, r.Touched...), r.Deleted...) {
-		s.Manifests = append(s.Manifests, path.Join(strings.Trim(e.Source.Path, "/"), moduleManifestFile))
-		switch e.Manifest.Module {
-		case "mesh-controller":
-			s.Judge = link.JudgeSelf
-		case "mesh-host":
-			if s.Judge == "" {
-				s.Judge = link.JudgeValidator
-			}
-		}
-	}
-	for _, d := range r.Added {
-		s.Manifests = append(s.Manifests, path.Join(d, moduleManifestFile))
-	}
-	sort.Strings(s.Manifests)
-	s.Manifests = slices.Compact(s.Manifests)
-
-	// Whose repository it is, for how it is cloned and whether its own check is the mesh's to run.
-	owners := map[string]bool{}
-	for i, e := range entries {
-		if e.Provided {
-			continue
-		}
-		if _, core := coreModules[e.Manifest.Module]; core {
-			if owner := sourceOwner(e.Source.Repository); owner != "" {
-				owners[owner] = true
-			}
-		}
-		if sameRepository(e.Source.Repository, m) && s.From == nil {
-			s.From = &entries[i]
-		}
-	}
-	s.Mesh = s.From != nil || owners[strings.ToLower(p.Owner)] || s.gated()
-	return s
-}
-
-// sourceOwner is the owner of a recorded repository, a path on the git seat or a URL: novox/mesh-host → novox.
-func sourceOwner(repository string) string {
-	parts := strings.Split(strings.Trim(strings.TrimSuffix(repository, ".git"), "/"), "/")
-	if len(parts) < 2 {
-		return ""
-	}
-	return strings.ToLower(parts[len(parts)-2])
-}
-
-// PullUpdated decides a pull request's merge check, and asks for it when there is something to run.
-func (f following) PullUpdated(ctx context.Context, p link.PullUpdated) error {
-	inv := f.open.inventory
-	entries, err := inv.Catalogued(ctx)
-	if err != nil {
-		return err
-	}
-	read, err := readForPlanning(ctx, inv)
-	if err != nil {
-		return err
-	}
-	edges, err := inv.Dependencies(ctx)
-	if err != nil {
-		return err
-	}
-	scope := pullScope(p, entries, read, edges)
-	// The change plan of the commit at hand (ADR 0238): what a merge of it would build and send, posted
-	// with the verdict whatever the verdict is.
-	plan := changePlanOf(p.Owner+"/"+p.Repo, p.Base, p.Commit, scope.Reach, entries, func(module string) (inventory.Upgrade, bool) {
-		u, err := inv.UpgradeOf(ctx, module)
-		return u, err == nil
-	})
-	fmt.Print(planText(plan))
-	direct := directVerdict(p, plan)
-	switch {
-	case !scope.gated() && !scope.Mesh:
-		fmt.Printf("%s/%s#%d (%.8s): %s, and the repository is not the mesh's: said, nothing run\n",
-			p.Owner, p.Repo, p.Number, p.Commit, noModuleTouched)
-		sayChecked(ctx, direct)
-		return nil
-	case !scope.gated() && p.MergeCheckSaid && !p.MergeCheck:
-		direct.RepoCheck = &link.CheckLayer{Verdict: "warning", Summary: noMergeCheck}
-		fmt.Printf("%s/%s#%d (%.8s): %s; %s\n", p.Owner, p.Repo, p.Number, p.Commit, noModuleTouched, noMergeCheck)
-		sayChecked(ctx, direct)
-		return nil
-	}
-	request, err := checkRequestFor(ctx, f.open, p, scope, entries)
-	if err != nil {
-		return err
-	}
-	request.Check.Plan = &plan
-	seat := buildSeatHeld(ctx)
-	ask, err := askOverOn(seat)
-	if err != nil {
-		return err
-	}
-	defer ask.Close()
-	if err := ask.Ask(ctx, request); err != nil {
-		return err
-	}
-	what := "its own merge-check.sh alone: " + noModuleTouched
-	if scope.gated() {
-		what = fmt.Sprintf("the gate over %s (a merge would build %d module(s) in %d tier(s))",
-			strings.Join(append(append([]string{}, scope.Modules...), prefixedAll("new:", scope.New)...), ", "),
-			scope.Width, scope.Tiers)
-	}
-	fmt.Printf("%s/%s#%d (%.8s): asked %s to check it before it merges — %s — as %s\n", p.Owner, p.Repo, p.Number,
-		p.Commit, seat, what, request.ID)
-	return nil
-}
-
-// directVerdict is the verdict of a change no build judges — it touches no module, and either the repository is not
-// the mesh's or the head holds no merge-check.sh. **It names the trunk commit it holds for** (novox/hq ADR 0323 §3):
-// the base branch's head the forge announced with the head, so the merge tool can weigh it against the trunk's head
-// and does not refuse it for ever (a verdict naming no trunk is never the trunk's head's). Nothing was built to
-// judge: the trunk commit is the one the forge said the change was announced against.
-func directVerdict(p link.PullUpdated, plan link.ChangePlan) link.Checked {
-	trunk := p.BaseSHA
-	if len(trunk) > 12 {
-		trunk = trunk[:12]
-	}
-	if trunk != "" {
-		plan.Trunk = trunk
-	}
-	return link.Checked{Owner: p.Owner, Repo: p.Repo, Number: p.Number, Commit: p.Commit,
-		ID: link.NewBuildID(time.Now()), Verdict: "pass", Summary: noModuleTouched,
-		Gate: &link.CheckLayer{Verdict: "pass", Summary: noModuleTouched}, Plan: &plan, Trunk: trunk}
-}
-
-// checkRequestFor is the ask for one pull request's head: the repository as the mesh clones it, the head,
-// and what is read beside it.
-func checkRequestFor(ctx context.Context, open *stores, p link.PullUpdated, scope checkScope,
-	entries []inventory.Entry) (link.BuildRequest, error) {
-	shelf := map[string]catalogue.Manifest{}
-	for _, e := range entries {
-		shelf[e.Manifest.Module] = e.Manifest
-	}
-	world, err := theRestOfTheMesh(ctx, open.inventory, shelf, "")
-	if err != nil {
-		return link.BuildRequest{}, err
-	}
-	clone := func(s inventory.Source) (string, error) {
-		if s.Seat == "" {
-			return s.Repository, nil
-		}
-		return clonedFromSeat(world, s.Seat, s.Repository)
-	}
-	// As the mesh clones a module built from it; a repository no module is built from, from the forge.
-	source := inventory.Source{Seat: gitSeat, Repository: p.Owner + "/" + p.Repo}
-	if scope.From != nil {
-		source = scope.From.Source
-	}
-	repository, err := clone(source)
-	if err != nil {
-		return link.BuildRequest{}, err
-	}
-	current, err := open.inventory.CurrentBuilds(ctx)
-	if err != nil {
-		return link.BuildRequest{}, err
-	}
-	// Beside it, at what the mesh runs: each core repository by the module the mesh builds from it.
-	beside := map[string]link.CheckedOut{}
-	for _, e := range entries {
-		dir, core := coreModules[e.Manifest.Module]
-		if !core || e.Provided || e.Source.Repository == "" {
-			continue
-		}
-		url, err := clone(e.Source)
-		if err != nil {
-			return link.BuildRequest{}, err
-		}
-		refs := besideRefs(dir, current[e.Manifest.Module].Commit)
-		beside[dir] = link.CheckedOut{Repository: url, Ref: refs[dir]}
-		if dir == "mesh-controller" {
-			beside["mesh-controller-main"] = link.CheckedOut{Repository: url, Ref: refs["mesh-controller-main"]}
-			if e.Source.Seat != "" {
-				for _, sibling := range []string{"mesh-lab", "mesh-sdk"} {
-					if url, err := clone(inventory.Source{Seat: e.Source.Seat, Repository: siblingOf(e.Source.Repository,
-						sibling)}); err == nil {
-						beside[sibling] = link.CheckedOut{Repository: url, Ref: refs[sibling]}
-					}
-				}
-			}
-		}
-	}
-	return link.BuildRequest{
-		ID:         link.NewBuildID(time.Now()),
-		Repository: repository,
-		Ref:        p.Commit,
-		Held:       heldBy(ctx),
-		Seats:      seatBases(ctx),
-		Source:     sourceOnSeat(source),
-		Check: &link.CheckRequest{Owner: p.Owner, Repo: p.Repo, Number: p.Number, Base: p.Base,
-			Paths: p.Paths, Beside: beside, Modules: scope.Modules, Dependents: scope.Dependents, New: scope.New,
-			Manifests: scope.Manifests, Judge: scope.Judge, Builds: checkBuildsOf(p, scope, entries, clone)},
-	}, nil
-}
-
-// checkBuildsOf are the modules a merge of the change would build, in the walk's order, as the check builds them
-// for the walk to take (novox/hq ADR 0350 §1): a module built from the repository checked, at the branch it merges
-// into, from the merge the check makes; any other — a module standing on one — from its own repository at the
-// branch it follows, as the walk builds it. A module whose build reads the repository checked through a context,
-// or that the merge deletes, cannot be built as the walk would: said, and nothing after it is built. A change that
-// moves no module builds nothing.
-func checkBuildsOf(p link.PullUpdated, scope checkScope, entries []inventory.Entry,
-	clone func(inventory.Source) (string, error)) []link.CheckBuild {
-	if len(scope.Reach.Plan.Tiers) == 0 {
-		return nil
-	}
-	m := link.SourceMoved{Owner: p.Owner, Repo: p.Repo, Base: p.Base, CloneURL: p.CloneURL}
-	byName := map[string]inventory.Entry{}
-	for _, e := range entries {
-		byName[e.Manifest.Module] = e
-	}
-	skip := map[string]string{}
-	for _, e := range scope.Reach.Packaging {
-		skip[e.Manifest.Module] = "its build reads " + p.Owner + "/" + p.Repo + " through a context, which a check " +
-			"cannot hand the merge"
-	}
-	for _, e := range scope.Reach.Deleted {
-		skip[e.Manifest.Module] = "the merge deletes it"
-	}
-	var out []link.CheckBuild
-	for tier, names := range scope.Reach.Plan.Tiers {
-		for _, name := range names {
-			e, known := byName[name]
-			b := link.CheckBuild{Module: name, Tier: tier, Skip: skip[name]}
-			switch {
-			case !known:
-				b.Skip = "the catalogue does not hold it"
-			case b.Skip != "":
-			case sourceIs(e.Source, m):
-				b.Merged, b.Path = true, e.Source.Path
-			default:
-				url, err := clone(e.Source)
-				if err != nil {
-					b.Skip = "its repository cannot be cloned: " + err.Error()
-					break
-				}
-				b.Repository, b.Path, b.Ref = url, e.Source.Path, followedBranch(e.Source.Ref)
-			}
-			out = append(out, b)
-		}
-	}
-	return out
-}
-
-// besideRefs is the ref each repository is cloned at beside a check, by the directory it is found under:
-// a core repository at the commit the mesh runs of the module built from it (`running`) — but the
-// catalogue, whose checkout beside is what tests read its files from, at its main, what the next merge
-// builds from; and beside the controller its main, for a judge the running controller predates, and the
-// lab's main, whose replays every check runs. **One rule, read by the check the controller asks for and by
-// the facts snapshot** (Facts.Beside), so a check run by hand clones what the build seat clones. Beside the
-// controller also the SDK, checked out at the commit the running controller's go.mod pins (sdkPinned), not
-// one a desktop holds (novox/hq issue 449). The checkout only places the clone: the conformance test reads the
-// fixtures at the pin of the tree under check, from the clone's history, so a pull request moving the SDK is
-// judged against the SDK it moves to (internal/link/conformance_test.go).
-func besideRefs(dir, running string) map[string]string {
-	switch dir {
-	case "mesh-catalog":
-		return map[string]string{dir: "main"}
-	case "mesh-controller":
-		return map[string]string{dir: running, "mesh-controller-main": "main", "mesh-lab": "main",
-			"mesh-sdk": sdkPinned()}
-	}
-	return map[string]string{dir: running}
-}
-
-// sdkModule is the Go module of the SDK the controller is built against.
-const sdkModule = "git.novox.be/novox/mesh-sdk/go"
-
-// pseudoCommit is the commit a Go pseudo-version names: v0.1.11-0.20261009143344-f047d0a4a970 → f047d0a4a970.
-var pseudoCommit = regexp.MustCompile(`-([0-9a-f]{12})$`)
-
-// sdkPinned is the ref of the SDK repository this controller was built from, as its go.mod pins it and its
-// build records it: a pseudo-version's commit, or a release's tag (the SDK tags its Go module under go/).
-// "main" only for a binary that records no SDK version — a local replace — which a running controller is
-// not (novox/hq issue 449).
-func sdkPinned() string {
-	info, ok := debug.ReadBuildInfo()
-	if !ok {
-		return "main"
-	}
-	for _, dep := range info.Deps {
-		if dep.Path != sdkModule {
-			continue
-		}
-		if dep.Replace != nil {
-			dep = dep.Replace
-		}
-		if m := pseudoCommit.FindStringSubmatch(dep.Version); m != nil {
-			return m[1]
-		}
-		if strings.HasPrefix(dep.Version, "v") {
-			return "go/" + dep.Version
-		}
-	}
-	return "main"
-}
-
-// siblingOf is another repository of the same owner: novox/mesh-controller → novox/mesh-lab.
-func siblingOf(repository, name string) string {
-	if cut := strings.LastIndex(repository, "/"); cut >= 0 {
-		return repository[:cut+1] + name
-	}
-	return name
-}
-
-// sourceOnSeat is a source's seat form, nil for one on no seat.
-func sourceOnSeat(s inventory.Source) *link.SourceOnSeat {
-	if s.Seat == "" {
-		return nil
-	}
-	return &link.SourceOnSeat{Seat: s.Seat, Repository: s.Repository}
-}
-
-// checkEvents is where the serving controller says a check's verdict; nil in a command.
-var checkEvents link.Bus
-
-// maxCheckReport is how much of a check's report travels in its verdict: enough for the failures and
-// the machines, never a log.
-const maxCheckReport = 60 << 10
-
-// checked says a merge check's verdict as the controller's `checked`. Nothing is recorded or
-// registered: a check builds nothing (issue 240's rule for a dry run, kept for a check).
-func checked(ctx context.Context, result link.BuildResult) {
-	sayChecked(ctx, checkedOf(result))
-}
-
-// checkedOf is what a check's outcome says: each layer, and an error — never a pass — for a check that
-// could not run.
-func checkedOf(result link.BuildResult) link.Checked {
-	c := link.Checked{ID: result.ID, On: result.On, Commit: result.Ref}
-	if result.Checked != nil {
-		c.Owner, c.Repo, c.Number = result.Checked.Owner, result.Checked.Repo, result.Checked.Number
-	}
-	switch {
-	case result.Check != nil:
-		c.Verdict, c.Summary, c.Report = result.Check.Verdict, result.Check.Summary, result.Check.Report
-		c.Gate, c.RepoCheck = result.Check.Gate, result.Check.RepoCheck
-		// What was judged (novox/hq ADR 0323 §3): the head merged into the trunk commit, and the commits of the
-		// repositories read beside it.
-		c.Trunk, c.Beside, c.Took = result.Check.Trunk, result.Check.Beside, result.Check.Took
-		c.Built = result.Check.Built
-		if c.Gate == nil {
-			// A build seat from before the layers: its verdict is the gate's.
-			c.Gate = &link.CheckLayer{Verdict: c.Verdict, Summary: c.Summary}
-		}
-	case result.Failed != "":
-		// The check could not run: an error, never read as a pass — on both layers it was asked for.
-		c.Verdict, c.Summary = "error", "the check could not run: "+firstLine(result.Failed)
-	default:
-		c.Verdict, c.Summary = "error", "the build seat answered the check with no verdict"
-	}
-	if c.Verdict == "" {
-		c.Verdict = "error"
-	}
-	if result.Check == nil {
-		c.Gate = &link.CheckLayer{Verdict: c.Verdict, Summary: c.Summary}
-		c.RepoCheck = &link.CheckLayer{Verdict: c.Verdict, Summary: c.Summary}
-	}
-	if result.Checked != nil && c.Gate != nil && len(c.Gate.Modules) == 0 {
-		c.Gate.Modules = append(append([]string{}, result.Checked.Modules...), prefixedAll("new:", result.Checked.New)...)
-	}
-	if result.Checked != nil && c.Gate != nil && len(c.Gate.Dependents) == 0 {
-		c.Gate.Dependents = result.Checked.Dependents
-	}
-	if result.Checked != nil {
-		c.Plan = result.Checked.Plan
-		if c.Plan != nil && c.Trunk != "" {
-			// The kept delivery plan records the trunk commit with its other inputs (ADR 0323 §3).
-			plan := *c.Plan
-			plan.Trunk = c.Trunk
-			c.Plan = &plan
-		}
-		// A delivery group's composed check (novox/hq ADR 0239): every head it judged, this one first.
-		if g := result.Checked; g.Group != "" {
-			c.Group = g.Group
-			c.Members = append(c.Members, link.CheckedMember{Owner: g.Owner, Repo: g.Repo, Number: g.Number,
-				Commit: result.Ref, Trunk: c.Trunk})
-			for _, m := range g.Members {
-				c.Members = append(c.Members, link.CheckedMember{Owner: m.Owner, Repo: m.Repo, Number: m.Number,
-					Commit: m.Ref, Trunk: memberTrunk(result.Check, m)})
-			}
-		}
-	}
-	for _, l := range []*link.CheckLayer{c.Gate, c.RepoCheck} {
-		if l != nil && l.Verdict == "" {
-			l.Verdict = "error"
-		}
-	}
-	// **A check run again says so** (novox/hq issue 594). The summaries are the lines the pull request
-	// shows, clipped by the forge to a few words, so they get only a short marker after the verdict's own
-	// words; the report gets the whole sentence. Layers copied, so the build's own outcome is left as it came.
-	if mark := link.RunMarker(result.Delivery); mark != "" {
-		c.Summary += " " + mark
-		for _, l := range []**link.CheckLayer{&c.Gate, &c.RepoCheck} {
-			if *l != nil {
-				layer := **l
-				layer.Summary += " " + mark
-				*l = &layer
-			}
-		}
-		c.Report = link.Restarted(result.Delivery) + "\n\n" + c.Report
-	}
-	if len(c.Report) > maxCheckReport {
-		c.Report = "…" + c.Report[len(c.Report)-maxCheckReport:]
-	}
-	return c
-}
-
-// memberTrunk is the trunk commit the build seat merged one of a group's heads into (novox/hq ADR 0323 §6), empty
-// when it said none.
-func memberTrunk(outcome *link.CheckOutcome, m link.GroupMember) string {
-	if outcome == nil {
-		return ""
-	}
-	for _, j := range outcome.Members {
-		if strings.EqualFold(j.Owner, m.Owner) && strings.EqualFold(j.Repo, m.Repo) && strings.HasPrefix(m.Ref, j.Commit) {
-			return j.Trunk
-		}
-	}
-	return ""
-}
-
-func prefixedAll(prefix string, items []string) []string {
-	out := make([]string, 0, len(items))
-	for _, i := range items {
-		out = append(out, prefix+i)
-	}
-	return out
-}
-
-// sayChecked says a merge check's verdict on the bus, where the forge's holder hears it.
-func sayChecked(ctx context.Context, c link.Checked) {
-	repo := "none"
-	if c.RepoCheck != nil {
-		repo = strings.ToUpper(c.RepoCheck.Verdict) + " — " + c.RepoCheck.Summary
-	}
-	judged := ""
-	if c.Trunk != "" {
-		judged = " merged into trunk " + c.Trunk
-	}
-	fmt.Printf("%s: %s/%s#%d at %.8s%s checked on %s: gate %s — %s; repository %s\n", c.ID, c.Owner, c.Repo, c.Number,
-		c.Commit, judged, orSomewhere(c.On), strings.ToUpper(c.Verdict), c.Summary, repo)
-	if checkEvents == nil {
-		return
-	}
-	body, err := json.Marshal(c)
-	if err != nil {
-		return
-	}
-	stating, stop := context.WithTimeout(context.WithoutCancel(ctx), 10*time.Second)
-	defer stop()
-	if err := checkEvents.PublishSeatEvent(stating, link.MeshControllerSeat, link.KeyChecked, body); err != nil {
-		fmt.Printf("%s: the verdict could not be said, so the pull request is not told it: %v\n", c.ID, err)
-	}
-}

cmd/mesh-controller/checks_test.go

@@ -1,290 +0,0 @@
-package main
-
-import (
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// **The mesh's module graph decides what a pull request's check runs**, not the repository (novox/hq
-// ADR 0237 as amended): a change is mapped onto the graph by the rule a merge is (issue 278), the gate
-// runs when it touches a module — a new one included — and a repository that is the mesh's and touches
-// none still has its own merge-check.sh run.
-func TestThePullRequestIsMappedOntoTheModuleGraph(t *testing.T) {
-	const catalogue = "http://forge.internal:20000/novox/mesh-catalog.git"
-	const controller = "http://forge.internal:20000/novox/mesh-controller.git"
-	const host = "http://forge.internal:20000/novox/mesh-host.git"
-	photos := fromRepo("photos", "http://forge.internal:20000/novox/photos.git", "")
-	photos.Source.Ref = "nox-mesh"
-	snake := fromRepo("snake", "jschoubben/snake", "")
-	snake.Source.Seat = "git"
-	entries := []inventory.Entry{
-		fromRepo("gitea", catalogue, "modules/gitea"),
-		fromRepo("keycloak", catalogue, "modules/keycloak"),
-		fromRepo("nats", catalogue, "modules/nats"),
-		fromRepo("mesh-controller", controller, ""),
-		fromRepo("mesh-host", host, ""),
-		photos, snake,
-	}
-	pull := func(owner, repo, base string, paths []string, dirs ...string) link.PullUpdated {
-		return link.PullUpdated{Owner: owner, Repo: repo, Base: base, Commit: "abc", Paths: paths,
-			ModuleDirs: dirs, ModuleDirsSaid: true}
-	}
-	for _, c := range []struct {
-		what                   string
-		p                      link.PullUpdated
-		modules, new, manifest string
-		mesh                   bool
-		judge                  string
-	}{
-		{"one module's own files", pull("novox", "mesh-catalog", "main", []string{"modules/gitea/index.ts"}, "modules/gitea"),
-			"gitea", "", "modules/gitea/module.json", true, ""},
-		{"a file no module's build reads touches no module (issue 280)",
-			pull("novox", "mesh-catalog", "main", []string{"merge-check.sh", "README.md"}), "", "", "", true, ""},
-		{"files the announcer could not list: everything built from it",
-			link.PullUpdated{Owner: "novox", Repo: "mesh-catalog", Base: "main", Commit: "abc", PathsTruncated: true,
-				Paths: []string{"README.md"}}, "gitea,keycloak,nats", "",
-			"modules/gitea/module.json,modules/keycloak/module.json,modules/nats/module.json", true, ""},
-		{"a new module, said by the head", pull("novox", "mesh-catalog", "main",
-			[]string{"modules/newmod/index.ts", "modules/newmod/module.json"}, "modules/newmod"),
-			"", "modules/newmod", "modules/newmod/module.json", true, ""},
-		{"the controller judges itself", pull("novox", "mesh-controller", "main", []string{"cmd/x.go"}),
-			"mesh-controller", "", "module.json", true, "self"},
-		{"the node-engine is judged with its validator", pull("novox", "mesh-host", "main", []string{"validate/v.go"}),
-			"mesh-host", "", "module.json", true, "validator"},
-		{"the core's owner, no module: the mesh's, its own check alone", pull("novox", "hq", "main", []string{"README.md"}),
-			"", "", "", true, ""},
-		{"a branch nothing is built from: the mesh's repository, no module", pull("novox", "photos", "master",
-			[]string{"server/x.js"}), "", "", "", true, ""},
-		{"the branch a module is built from", pull("novox", "photos", "nox-mesh", []string{"server/x.js"}),
-			"photos", "", "module.json", true, ""},
-		{"a repository on the forge's seat", pull("jschoubben", "snake", "main", []string{"index.html"}),
-			"snake", "", "module.json", true, ""},
-		{"a repository of nobody's, touching nothing", pull("someone", "dotfiles", "main", []string{"x"}),
-			"", "", "", false, ""},
-		{"a repository adding a module at its root", pull("someone", "newapp", "main", []string{"module.json", "x.js"}),
-			"", ".", "module.json", true, ""},
-	} {
-		s := pullScope(c.p, entries, nil, nil)
-		got := []string{strings.Join(s.Modules, ","), strings.Join(s.New, ","), strings.Join(s.Manifests, ",")}
-		want := []string{c.modules, c.new, c.manifest}
-		for i, what := range []string{"modules", "new", "manifests"} {
-			if got[i] != want[i] {
-				t.Errorf("%s: %s %q, wanted %q", c.what, what, got[i], want[i])
-			}
-		}
-		if s.Mesh != c.mesh || s.Judge != c.judge {
-			t.Errorf("%s: the mesh's %v judged by %q, wanted %v by %q", c.what, s.Mesh, s.Judge, c.mesh, c.judge)
-		}
-		if s.gated() != (c.modules != "" || c.new != "") {
-			t.Errorf("%s: gated %v", c.what, s.gated())
-		}
-	}
-}
-
-// A module whose build packages another repository's source is touched by a change to it.
-func TestAPullRequestTouchesWhatPackagesItsRepository(t *testing.T) {
-	entries := []inventory.Entry{fromRepo("node-tools", "http://forge.internal:20000/novox/mesh-tools.git", "node-tools")}
-	read := map[string][]inventory.ReadRepository{"node-tools": {{Repository: "http://forge.internal:20000/novox/mesh-sdk.git"}}}
-	s := pullScope(link.PullUpdated{Owner: "novox", Repo: "mesh-sdk", Base: "main", Commit: "abc", Paths: []string{"go/x.go"}}, entries, read, nil)
-	if strings.Join(s.Modules, ",") != "node-tools" || len(s.Manifests) != 0 {
-		t.Fatalf("a change to what node-tools packages touched %v (manifests %v)", s.Modules, s.Manifests)
-	}
-}
-
-// Each layer is said; a check that could not run is an error on both, never a pass; a build seat from
-// before the layers is read as the gate.
-func TestAChecksLayersAreEachSaidAndAnErrorIsNeverAPass(t *testing.T) {
-	asked := &link.CheckRequest{Owner: "novox", Repo: "mesh-catalog", Number: 3, Modules: []string{"gitea"}}
-	c := checkedOf(link.BuildResult{ID: "b", Ref: "abc", Checked: asked, Failed: "the facts snapshot cannot be read"})
-	if c.Verdict != "error" || c.Gate == nil || c.Gate.Verdict != "error" || c.RepoCheck == nil || c.RepoCheck.Verdict != "error" {
-		t.Fatalf("a check that could not run said %+v", c)
-	}
-	if strings.Join(c.Gate.Modules, ",") != "gitea" {
-		t.Errorf("the gate names %v", c.Gate.Modules)
-	}
-	c = checkedOf(link.BuildResult{ID: "b", Ref: "abc", Checked: asked, Check: &link.CheckOutcome{Verdict: "warning", Summary: "wide"}})
-	if c.Gate == nil || c.Gate.Verdict != "warning" || c.RepoCheck != nil {
-		t.Fatalf("an outcome without layers said %+v", c)
-	}
-	c = checkedOf(link.BuildResult{ID: "b", Ref: "abc", Checked: asked, Check: &link.CheckOutcome{Verdict: "pass",
-		Gate: &link.CheckLayer{Verdict: "pass"}, RepoCheck: &link.CheckLayer{Verdict: "fail", Summary: "its merge-check.sh failed"}}})
-	if c.RepoCheck.Verdict != "fail" || c.Gate.Verdict != "pass" {
-		t.Fatalf("the layers said %+v / %+v", c.Gate, c.RepoCheck)
-	}
-}
-
-// **The check asks the planner, never a mapping of its own** (novox/hq ADR 0238): what a pull request
-// reaches is reachOfMerge's answer — the same that plans a merge — so a file at the root touches no
-// module in both, and what stands on a touched module is named as its dependents in both.
-func TestAPullRequestReachesWhatAMergeOfItWouldPlan(t *testing.T) {
-	const catalogue = "http://forge.internal:20000/novox/mesh-catalog.git"
-	nats := fromRepo("nats", catalogue, "modules/nats")
-	nats.Source.BuiltFrom = "old"
-	gitea := fromRepo("gitea", catalogue, "modules/gitea")
-	gitea.Source.BuiltFrom = "old"
-	tools := fromRepo("node-tools", "http://forge.internal:20000/novox/mesh-tools.git", "node-tools")
-	entries := []inventory.Entry{nats, gitea, tools}
-	// node-tools stands on the bus's image; a code edge, so a plan takes it along.
-	edges := []inventory.Edge{{From: "node-tools", To: "nats", Kind: inventory.EdgeStandsOn}}
-	read := map[string][]inventory.ReadRepository{}
-
-	for _, c := range []struct {
-		what              string
-		paths             []string
-		moved, dependents string
-		width             int
-		unread            string
-	}{
-		{"a file at the root, read by no build", []string{"merge-check.sh"}, "", "", 0, "merge-check.sh"},
-		{"the bus's own directory", []string{"modules/nats/Dockerfile"}, "nats", "node-tools", 2, ""},
-		{"both, and a README", []string{"modules/gitea/index.ts", "modules/nats/x", "README.md"}, "gitea,nats", "node-tools", 3, "README.md"},
-	} {
-		p := link.PullUpdated{Owner: "novox", Repo: "mesh-catalog", Base: "main", Commit: "head", Paths: c.paths}
-		s := pullScope(p, entries, read, edges)
-		m := link.SourceMoved{Owner: "novox", Repo: "mesh-catalog", Base: "main", Commit: "head", Paths: c.paths}
-		r := reachOfMerge(m, entries, read, edges)
-		if got := strings.Join(s.Modules, ","); got != c.moved || got != strings.Join(r.Moved(), ",") {
-			t.Errorf("%s: the check reaches %q, the planner %v, wanted %q", c.what, got, r.Moved(), c.moved)
-		}
-		if got := strings.Join(s.Dependents, ","); got != c.dependents {
-			t.Errorf("%s: dependents %q, wanted %q", c.what, got, c.dependents)
-		}
-		if s.Width != c.width || s.Width != len(r.Plan.Modules) {
-			t.Errorf("%s: a merge would build %d, the planner says %d, wanted %d", c.what, s.Width, len(r.Plan.Modules), c.width)
-		}
-		if got := strings.Join(s.Unread, ","); got != c.unread {
-			t.Errorf("%s: unread %q, wanted %q", c.what, got, c.unread)
-		}
-	}
-
-	// A repository whose build another module's recipe packages: that module is reached through the
-	// planner's `read`, and what stands on it after it.
-	read["gitea"] = []inventory.ReadRepository{{Repository: "http://forge.internal:20000/novox/mesh-sdk.git"}}
-	s := pullScope(link.PullUpdated{Owner: "novox", Repo: "mesh-sdk", Base: "main", Commit: "head",
-		Paths: []string{"src/index.ts"}}, entries, read, edges)
-	if strings.Join(s.Modules, ",") != "gitea" || len(s.Manifests) != 0 {
-		t.Fatalf("a change to the source gitea packages reaches %v (manifests %v)", s.Modules, s.Manifests)
-	}
-}
-
-// **Only a commit on the trunk is published** (novox/hq ADR 0238): a build of a commit off its repository's
-// default branch — a pull request's head, a branch built by hand, a rebuild or replay of one — is recorded
-// and never registered, so nothing can send it; a check or a dry run never is either.
-func TestABuildOffTheTrunkIsNeverPublished(t *testing.T) {
-	on := link.BuildResult{ID: "b", Commit: "abc", Trunk: "main", OnTrunk: true}
-	if err := publishable(on, ""); err != nil {
-		t.Errorf("a build on the trunk was refused: %v", err)
-	}
-	off := link.BuildResult{ID: "b", Commit: "abc", Trunk: "main"}
-	if err := publishable(off, ""); !errors.Is(err, errOffTheTrunk) || !strings.Contains(err.Error(), "main") {
-		t.Errorf("a build off the trunk was let through: %v", err)
-	}
-	for _, r := range []link.BuildResult{
-		{ID: "c", Trunk: "main", OnTrunk: true, Check: &link.CheckOutcome{Verdict: "pass"}},
-		{ID: "d", Trunk: "main", OnTrunk: true, Checked: &link.CheckRequest{}},
-		{ID: "e", Trunk: "main", OnTrunk: true, DryRun: true},
-	} {
-		if publishable(r, "") == nil {
-			t.Errorf("%s, a check or a dry run, was publishable", r.ID)
-		}
-	}
-	// A module that follows a branch other than the default: that branch is its trunk, and the default
-	// is not.
-	follows := link.BuildResult{ID: "g", Commit: "abc", Trunk: "master", Branches: []string{"nox-mesh"}}
-	if err := publishable(follows, "nox-mesh"); err != nil {
-		t.Errorf("a commit on the branch a module follows was refused: %v", err)
-	}
-	if err := publishable(link.BuildResult{ID: "h", Commit: "abc", Trunk: "master", OnTrunk: true,
-		Branches: []string{"master"}}, "nox-mesh"); err == nil {
-		t.Error("a commit on the default but not on the branch the module follows was published")
-	}
-	if err := publishable(link.BuildResult{ID: "i", Commit: "abc", Trunk: "main", Branches: []string{"feat/x"}}, ""); err == nil {
-		t.Error("a feature branch's commit was published")
-	}
-	// A build seat older than the rule says nothing: let through and said, so the rule can reach the mesh.
-	if err := publishable(link.BuildResult{ID: "f", Commit: "abc"}, ""); err != nil {
-		t.Errorf("a build seat that said nothing was refused: %v", err)
-	}
-}
-
-// **A verdict names the trunk commit it judged** (novox/hq ADR 0323 §3, issue 341): the controller's `checked`
-// carries the head and the trunk commit the build seat merged it into, the commits of the repositories read beside
-// it, how long it took, and the kept delivery plan records the trunk commit with its other inputs. A group's
-// composed check names, per member, the trunk commit that head was merged into (§6).
-func TestAVerdictNamesTheTrunkCommitItJudged(t *testing.T) {
-	plan := &link.ChangePlan{Repository: "novox/mesh-host", Base: "main", Head: "dfb1415aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-		Summary: "builds mesh-host"}
-	asked := &link.CheckRequest{Owner: "novox", Repo: "mesh-host", Number: 66, Base: "main", Plan: plan}
-	c := checkedOf(link.BuildResult{ID: "b", Ref: "dfb1415aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", Checked: asked,
-		Check: &link.CheckOutcome{Verdict: "pass", Took: "4m12s", Head: "dfb1415aaaaa", Trunk: "d28ca95bbbbb",
-			Gate: &link.CheckLayer{Verdict: "pass"}, RepoCheck: &link.CheckLayer{Verdict: "pass"},
-			Beside: map[string]string{"mesh-catalog": "0123456789ab", "mesh-lab": "ba9876543210"}}})
-	if c.Trunk != "d28ca95bbbbb" || c.Commit != "dfb1415aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" {
-		t.Fatalf("the verdict names head %s and trunk %q", c.Commit, c.Trunk)
-	}
-	if c.Beside["mesh-catalog"] != "0123456789ab" || c.Beside["mesh-lab"] != "ba9876543210" {
-		t.Fatalf("the verdict names the repositories read beside it as %v", c.Beside)
-	}
-	if c.Took != "4m12s" {
-		t.Fatalf("the verdict says it took %q", c.Took)
-	}
-	if c.Plan == nil || c.Plan.Trunk != "d28ca95bbbbb" || c.Plan.Head != plan.Head {
-		t.Fatalf("the kept plan records %+v", c.Plan)
-	}
-	if plan.Trunk != "" {
-		t.Fatal("the plan the controller asked with was changed: the verdict's is a copy")
-	}
-
-	group := &link.CheckRequest{Owner: "novox", Repo: "mesh-controller", Number: 7, Base: "main", Group: "feat/x",
-		Members: []link.GroupMember{{Owner: "novox", Repo: "mesh-host", Number: 8, Ref: "cccccccccccc0000", Base: "main"}}}
-	c = checkedOf(link.BuildResult{ID: "g", Ref: "aaaaaaaaaaaa0000", Checked: group, Check: &link.CheckOutcome{
-		Verdict: "pass", Head: "aaaaaaaaaaaa", Trunk: "111111111111", Gate: &link.CheckLayer{Verdict: "pass"},
-		Members: []link.CheckedMember{{Owner: "novox", Repo: "mesh-host", Commit: "cccccccccccc", Trunk: "222222222222"}}}})
-	if len(c.Members) != 2 || c.Members[0].Trunk != "111111111111" || c.Members[1].Trunk != "222222222222" ||
-		c.Members[1].Commit != "cccccccccccc0000" {
-		t.Fatalf("the composed check names its members %+v", c.Members)
-	}
-}
-
-// **The merge made for a check is never registered** (novox/hq ADR 0323 §2): a build of it — a commit on no branch
-// of the forge — is refused, naming the trunk. The rule of ADR 0238 §1 stands unchanged; this holds it for the
-// merge commit a check makes.
-func TestABuildOfACheckMergeIsRefusedNamingTheTrunk(t *testing.T) {
-	merge := link.BuildResult{ID: "b", Commit: "4b5c6d7e8f90aabbccddeeff0011223344556677", Trunk: "main"}
-	err := publishable(merge, "")
-	if !errors.Is(err, errOffTheTrunk) || !strings.Contains(err.Error(), "not on main") {
-		t.Fatalf("a build of a check's merge was answered %v", err)
-	}
-}
-
-// **A verdict no build judges names its trunk commit too** (novox/hq ADR 0323 §3): a change touching no module of a
-// repository with no merge-check.sh (novox/mesh-tools-go) is answered by the controller itself. Naming no trunk, the
-// merge tool refused it, asked again, got the same verdict, and refused for ever.
-func TestADirectVerdictNamesTheTrunkTheForgeAnnounced(t *testing.T) {
-	p := link.PullUpdated{Owner: "novox", Repo: "mesh-tools-go", Number: 3, Base: "main", Commit: "1a2b3c4d5e6f7a8b9c0d",
-		BaseSHA: "7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b"}
-	c := directVerdict(p, link.ChangePlan{Repository: "novox/mesh-tools-go", Base: "main", Head: p.Commit})
-	if c.Trunk != "7a8b9c0d1e2f" || c.Plan == nil || c.Plan.Trunk != "7a8b9c0d1e2f" {
-		t.Fatalf("the direct verdict names trunk %q, its plan %+v", c.Trunk, c.Plan)
-	}
-	if c.Verdict != "pass" || c.Commit != p.Commit {
-		t.Fatalf("the direct verdict is %+v", c)
-	}
-	if c := directVerdict(link.PullUpdated{Owner: "novox", Repo: "x", Commit: "abc"}, link.ChangePlan{}); c.Trunk != "" {
-		t.Fatalf("a forge that said no base head gave the trunk %q", c.Trunk)
-	}
-}
-
-// A head checked again through mesh-delivery (`delivery check --members`, a recheck) reaches the same direct verdict:
-// it names the base head the forge last announced, kept on the member, or the merge tool would refuse it for ever.
-func TestARecheckedHeadsDirectVerdictNamesItsTrunk(t *testing.T) {
-	m := orderMember{ID: "novox/mesh-tools-go@1a2b3c4d5e6f", Repository: "novox/mesh-tools-go", Base: "main",
-		Head: "1a2b3c4d5e6f7a8b9c0d", Number: 3, BaseSHA: "7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b"}
-	if c := directVerdict(m.pull(), link.ChangePlan{}); c.Trunk != "7a8b9c0d1e2f" {
-		t.Fatalf("a rechecked head's direct verdict names trunk %q", c.Trunk)
-	}
-}

cmd/mesh-controller/collect.go

@@ -1,276 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"os"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/artifacts"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// Letting the artifact store go of what the mesh no longer keeps (novox/hq ADR 0189, issue 108).
-//
-// **Run where the records change.** A build is the moment new bytes landed in the store and the
-// moment the keep set moved, so it is the moment to say what may go — and it needs no timer of
-// its own. Reclaiming the bytes is the store's own nightly step; this only decides.
-//
-// **And run when a person asks** (novox/hq ADR 0251): the `collect` verb is the same sweep, with
-// bounds of its own. One implementation, so what a person runs is exactly what a build runs.
-//
-// Never fatal to a build. The build succeeded, the module is registered, and a store that could
-// not be reached is a thing to say rather than a reason to undo any of that. The next build asks
-// again, and the references it could not collect are still uncollected, so nothing is lost by
-// having failed.
-
-// sweepBounds is how much one sweep may ask of the store.
-type sweepBounds struct {
-	// most is how many artifacts it lets go of at most.
-	most int
-	// budget is the longest it keeps its caller waiting.
-	budget time.Duration
-	// platforms is whether an index is let go of with its own platform manifests (novox/hq ADR 0257).
-	// Only a sweep a person confirmed, after its dry run listed what stays and names a platform: the
-	// records cannot see an unrecorded index, or a copy in progress, naming the same platform, and the
-	// store's tools can.
-	platforms bool
-}
-
-// afterBuild are the bounds of the sweep inside somebody's build.
-//
-// **Bounded, because this runs inside somebody's build.** The first sweep of a mesh that has never
-// collected has the whole history to get through, and a person waiting on `build` should not pay for
-// it. What is left over is simply offered again next time — builds are frequent, and the point is
-// that the store stops growing, not that it empties tonight.
-var afterBuild = sweepBounds{most: mostPerSweep, budget: sweepBudget}
-
-// sweepResult is what one sweep did.
-type sweepResult struct {
-	// HoldersWritten is how many kept archives the store now holds by a manifest it did not before.
-	HoldersWritten int
-	// Missing is how many kept archives the store does not have at all.
-	Missing int
-	// Held is whether every kept archive could be asked to be held; false stops the sweep before it
-	// lets anything go.
-	Held bool
-	// LetGo is what the store let go of, and the record now says collected.
-	LetGo []string
-	// Skipped is how many references the sweep will not address (novox/hq issue 226).
-	Skipped int
-	// Indexes is how many eligible indexes a sweep a person did not confirm left for one that is: an
-	// index goes only with its platform manifests (novox/hq ADR 0257 §4).
-	Indexes int
-	// Left is how many eligible references were not asked about this time.
-	Left int
-	// Bounded is whether it stopped at its bounds rather than at a refusal.
-	Bounded bool
-	// Stopped says why the sweep stopped before the end; empty when it did not.
-	Stopped string
-}
-
-// sweep holds every kept archive, then asks the store to let go of each reference in order, records
-// what it let go of, and says what it did.
-func sweep(ctx context.Context, inv *inventory.Inventory, store artifacts.Store, references, kept []string,
-	bounds sweepBounds) sweepResult {
-	within, stop := context.WithTimeout(ctx, bounds.budget)
-	defer stop()
-	var r sweepResult
-
-	// **Hold before letting go** (novox/hq issue 253). The store's collector keeps only what a
-	// manifest names, and archives were published as bare blobs, so every kept archive is first
-	// held by its manifest — which backfills the ones published before holders, a few at a time
-	// as builds come, and is two HEADs each once done. A kept archive that could not be held stops
-	// the sweep before it deletes anything: "everything kept is held" is the precondition the
-	// collector's safety rests on, and a store refusing a hold would refuse the deletes too.
-	// **An index goes with its platform manifests only when a person confirmed it** (novox/hq ADR
-	// 0257), and a kept index keeps its own: which platform manifests the kept indexes name is read
-	// from the store for every repository the sweep will touch, before the first delete. A single
-	// read that fails stops the sweep before it deletes anything, as a kept archive that cannot be
-	// held does. The sweep after a build leaves an eligible index for such a collect, below.
-	store.Spare = nil
-	if bounds.platforms {
-		if inv == nil {
-			r.Stopped = "no records to read which platform manifests a kept index names, so nothing was let go"
-			r.Left = len(references)
-			return r
-		}
-		images, err := inv.KeptImages(ctx)
-		if err == nil {
-			store.Spare, err = store.SpareKeptIndexes(within, images, references)
-		}
-		if err != nil {
-			r.Stopped = fmt.Sprintf("which platform manifests a kept index names could not be read, so nothing was let go: %v", err)
-			r.Left = len(references)
-			return r
-		}
-	}
-
-	wrote, missing, err := holdKept(within, store, kept)
-	r.HoldersWritten, r.Missing = wrote, missing
-	if err != nil {
-		r.Stopped = fmt.Sprintf("not every kept archive could be held, so nothing was let go: %v", err)
-		r.Left = len(references)
-		return r
-	}
-	r.Held = true
-
-	for i, reference := range references {
-		if i >= bounds.most || within.Err() != nil {
-			r.Left = len(references) - i
-			r.Bounded = true
-			if i >= bounds.most {
-				r.Stopped = fmt.Sprintf("asked about %d, the most one sweep asks", bounds.most)
-			} else {
-				r.Stopped = fmt.Sprintf("ran out of its %s", bounds.budget)
-			}
-			break
-		}
-		if !bounds.platforms {
-			// **An index waits for a confirmed collect** (novox/hq ADR 0257 §4). Let go of alone,
-			// its platform manifests would stay in the store and the record would say collected, so
-			// no later sweep would offer it again and they would stay for ever. Left eligible, the
-			// next collect a person confirms takes it with them.
-			index, err := store.IsIndex(within, reference)
-			if err != nil && !errors.Is(err, artifacts.Gone) && !errors.Is(err, artifacts.ErrNotOurs) {
-				r.Stopped = fmt.Sprintf("the artifact store could not say whether %s is an index, so nothing more was asked of it: %v", reference, err)
-				r.Left = len(references) - i
-				break
-			}
-			if index {
-				r.Indexes++
-				continue
-			}
-		}
-		err := store.LetGo(within, reference)
-		if err == nil || errors.Is(err, artifacts.Gone) {
-			// Gone is the outcome wanted, already true. Recorded so the next sweep does not ask
-			// again for ever.
-			r.LetGo = append(r.LetGo, reference)
-			continue
-		}
-		if errors.Is(err, artifacts.ErrNotOurs) {
-			// **A fact about this record, so this record is skipped** (novox/hq issue 226). Not
-			// marked collected — the mesh did not remove it and should not claim to — and not a
-			// reason to stop, because the store was never asked. One of these at the front of
-			// the oldest-first order ended every sweep until this.
-			r.Skipped++
-			if r.Skipped == 1 {
-				fmt.Fprintf(os.Stderr, "the sweep will not address %s and went on: %v\n", reference, err)
-			}
-			continue
-		}
-		// **Stopped at the first refusal by the STORE, not pushed through.** A store that refuses
-		// one refuses all of them — deletion disabled, the store down, the network gone — so
-		// going on would be a hundred identical failures and a hundred identical log lines in
-		// front of whoever was building something.
-		r.Stopped = fmt.Sprintf("the artifact store kept %s, so nothing more was asked of it: %v", reference, err)
-		r.Left = len(references) - i
-		break
-	}
-
-	if len(r.LetGo) > 0 {
-		// Recorded outside `within`: the deletions happened, and losing the record of them because
-		// the sweep ran out of budget would mean asking about them again for ever.
-		if err := inv.MarkCollected(ctx, r.LetGo); err != nil {
-			r.Stopped = fmt.Sprintf("the store let go of %d artifact(s) and the record of it did not keep: %v",
-				len(r.LetGo), err)
-		}
-	}
-	return r
-}
-
-// collect asks the store to let go of everything the mesh made and no longer keeps, and records
-// what it let go of — after a build. Says what it did and what it could not; returns nothing,
-// because nothing upstream should branch on it.
-func collect(ctx context.Context, inv *inventory.Inventory) {
-	references, err := inv.ToCollect(ctx)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "could not work out what the artifact store may let go of: %v\n", err)
-		return
-	}
-	kept, err := inv.KeptArchives(ctx)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "could not work out which archives the artifact store keeps: %v\n", err)
-		return
-	}
-	if len(references) == 0 && len(kept) == 0 {
-		return
-	}
-	shelf, err := inv.Catalogue(ctx)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "could not read the catalogue to find the artifact store: %v\n", err)
-		return
-	}
-	// As the mesh reaches it from the network. Empty means the store is not on the network — on a
-	// mesh being raised it is not yet, and there the store holds one build of anything and has
-	// nothing to collect.
-	address, err := artifactStoreAddress(ctx, inv, shelf, "")
-	if err != nil || address == "" {
-		if err != nil {
-			fmt.Fprintf(os.Stderr, "could not find the artifact store to collect from: %v\n", err)
-		}
-		return
-	}
-
-	r := sweep(ctx, inv, artifacts.Store{Address: address}, references, kept, afterBuild)
-	if r.HoldersWritten > 0 {
-		fmt.Fprintf(os.Stderr, "the artifact store now holds %d more kept archive(s) by a manifest\n", r.HoldersWritten)
-	}
-	if r.Missing > 0 {
-		fmt.Fprintf(os.Stderr, "%d archive(s) the mesh keeps are not in the artifact store at all; "+
-			"`collection` lists them\n", r.Missing)
-	}
-	if len(r.LetGo) > 0 {
-		fmt.Fprintf(os.Stderr, "the artifact store let go of %d artifact(s) the mesh no longer keeps\n", len(r.LetGo))
-	}
-	if r.Stopped != "" && !r.Bounded {
-		fmt.Fprintln(os.Stderr, r.Stopped)
-	}
-	if r.Held && r.Left > 0 {
-		fmt.Fprintf(os.Stderr, "%d more to collect; the next build asks again\n", r.Left)
-	}
-	if r.Skipped > 0 {
-		fmt.Fprintf(os.Stderr, "%d artifact(s) the sweep will not address were skipped\n", r.Skipped)
-	}
-	if r.Indexes > 0 {
-		fmt.Fprintf(os.Stderr, "%d eligible index(es) wait for a collect a person confirms, which takes their platforms too\n", r.Indexes)
-	}
-}
-
-// holdKept holds every kept archive by its manifest, stopping at the first refusal by the store.
-// Answers how many holders it wrote and how many kept archives the store does not have.
-//
-// A missing archive is counted rather than fatal: there is nothing to hold, and that is a fact
-// for an operator to read (`collection`), not a reason to stop collecting what is not kept. A
-// reference the store cannot be asked about is skipped as the deletion loop skips one
-// (novox/hq issue 226).
-func holdKept(ctx context.Context, store artifacts.Store, kept []string) (wrote, missing int, err error) {
-	for _, reference := range kept {
-		if err := ctx.Err(); err != nil {
-			return wrote, missing, fmt.Errorf("ran out of time before %s: %w", reference, err)
-		}
-		did, err := store.Hold(ctx, reference)
-		switch {
-		case err == nil:
-			if did {
-				wrote++
-			}
-		case errors.Is(err, artifacts.Gone):
-			missing++
-		case errors.Is(err, artifacts.ErrNotOurs):
-		default:
-			return wrote, missing, fmt.Errorf("holding %s: %w", reference, err)
-		}
-	}
-	return wrote, missing, nil
-}
-
-// mostPerSweep is how many artifacts one sweep will ask about. Enough that a mesh building
-// several times a day converges within days of this landing; small enough that no single build
-// waits on the whole backlog.
-const mostPerSweep = 200
-
-// sweepBudget is the longest a sweep will keep a build waiting.
-const sweepBudget = 60 * time.Second

cmd/mesh-controller/collection.go

@@ -1,166 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"flag"
-	"fmt"
-	"os"
-	"strings"
-
-	"github.com/novox/mesh-controller/internal/artifacts"
-)
-
-// What the artifact store keeps, whether each kept archive is held, and what the sweep may let go
-// (novox/hq issue 253, ADR 0189).
-//
-// **The question to answer before the store's collector runs for real.** The collector deletes
-// every blob no manifest names, and archives were published as bare blobs, so the nightly step
-// runs `--dry-run` until every archive the mesh keeps is held by its manifest. The sweep holds
-// them as builds come; this says how far that has got — "0 unheld" is the number that lets the
-// dry run go.
-//
-// Reads and changes nothing: each kept archive is asked about with HEADs only. Reached over the
-// console through the mesh-controller seat's `command` verb (`collection --json`), which needs no
-// new verb in the seat's row.
-
-type collectionReport struct {
-	// Store is the artifact store as this machine reached it; empty when it is not on the network.
-	Store string `json:"store"`
-	// KeptArchives is how many archives the mesh keeps, for either reason.
-	KeptArchives int `json:"kept_archives"`
-	// Held is how many of them the store holds by their manifest.
-	Held int `json:"held"`
-	// Unheld are the kept archives the collector would delete tonight if it ran for real.
-	Unheld []string `json:"unheld"`
-	// Missing are kept archives the store does not have at all.
-	Missing []string `json:"missing"`
-	// Unasked is how many could not be asked about, and why the asking stopped.
-	Unasked int    `json:"unasked"`
-	Stopped string `json:"stopped,omitempty"`
-	// Eligible is what the sweep may let go of: made by the mesh, kept for no reason, not yet
-	// collected — split by kind.
-	Eligible         int `json:"eligible"`
-	EligibleImages   int `json:"eligible_images"`
-	EligibleArchives int `json:"eligible_archives"`
-	// SafeToCollect is whether every kept archive was asked about and every one is held.
-	SafeToCollect bool `json:"safe_to_collect"`
-}
-
-func collectionCommand(ctx context.Context, args []string) error {
-	set := flag.NewFlagSet("collection", flag.ContinueOnError)
-	asJSON := set.Bool("json", false, "answer as JSON")
-	positionals, err := parseAround(set, args)
-	if err != nil {
-		return err
-	}
-	if len(positionals) != 0 {
-		return errors.New("collection [--json]")
-	}
-
-	open, err := openStores(ctx)
-	if err != nil {
-		return err
-	}
-	defer open.Close()
-	inv := open.inventory
-
-	kept, err := inv.KeptArchives(ctx)
-	if err != nil {
-		return err
-	}
-	eligible, err := inv.ToCollect(ctx)
-	if err != nil {
-		return err
-	}
-	report := collectionReport{KeptArchives: len(kept), Eligible: len(eligible), Unheld: []string{}, Missing: []string{}}
-	for _, reference := range eligible {
-		if strings.Contains(reference, "/blobs/") {
-			report.EligibleArchives++
-		} else {
-			report.EligibleImages++
-		}
-	}
-
-	shelf, err := inv.Catalogue(ctx)
-	if err != nil {
-		return err
-	}
-	report.Store, err = artifactStoreAddress(ctx, inv, shelf, "")
-	if err != nil {
-		return err
-	}
-	if report.Store == "" {
-		report.Unasked = len(kept)
-		report.Stopped = "this mesh has no artifact store on its network"
-	} else {
-		report.Unasked, report.Stopped = askHeld(ctx, artifacts.Store{Address: report.Store}, kept, &report)
-	}
-	report.SafeToCollect = report.Unasked == 0 && len(report.Unheld) == 0
-
-	if *asJSON {
-		encoder := json.NewEncoder(os.Stdout)
-		encoder.SetIndent("", "  ")
-		return encoder.Encode(report)
-	}
-	printCollection(report)
-	return nil
-}
-
-// askHeld asks the store about each kept archive, stopping at the first answer that is not about
-// the archive: a store that cannot be reached for one cannot be for the next, and a page of
-// identical failures says less than one line.
-func askHeld(ctx context.Context, store artifacts.Store, kept []string, report *collectionReport) (int, string) {
-	for i, reference := range kept {
-		held, err := store.Held(ctx, reference)
-		switch {
-		case err == nil && held:
-			report.Held++
-		case err == nil:
-			report.Unheld = append(report.Unheld, reference)
-		case errors.Is(err, artifacts.Gone):
-			report.Missing = append(report.Missing, reference)
-		case errors.Is(err, artifacts.ErrNotOurs):
-			// KeptArchives names only the mesh's own; counted as unasked if one ever is not.
-			report.Unasked++
-		default:
-			return report.Unasked + len(kept) - i, fmt.Sprintf("asking about %s: %v", reference, err)
-		}
-	}
-	return report.Unasked, ""
-}
-
-func printCollection(r collectionReport) {
-	store := r.Store
-	if store == "" {
-		store = "(not on the network)"
-	}
-	fmt.Printf("artifact store       %s\n", store)
-	fmt.Printf("kept archives        %d\n", r.KeptArchives)
-	fmt.Printf("  held               %d\n", r.Held)
-	fmt.Printf("  unheld             %d\n", len(r.Unheld))
-	fmt.Printf("  missing            %d\n", len(r.Missing))
-	if r.Unasked > 0 {
-		fmt.Printf("  not asked          %d (%s)\n", r.Unasked, r.Stopped)
-	}
-	fmt.Printf("eligible to let go   %d (%d images, %d archives)\n", r.Eligible, r.EligibleImages, r.EligibleArchives)
-	if len(r.Unheld) > 0 {
-		fmt.Println("\nunheld — the store's collector would delete these; the next build's sweep holds them:")
-		for _, reference := range r.Unheld {
-			fmt.Printf("  %s\n", reference)
-		}
-	}
-	if len(r.Missing) > 0 {
-		fmt.Println("\nmissing — kept by the mesh, not in the store:")
-		for _, reference := range r.Missing {
-			fmt.Printf("  %s\n", reference)
-		}
-	}
-	fmt.Println()
-	if r.SafeToCollect {
-		fmt.Println("every kept archive is held: the store's collector may run for real")
-	} else {
-		fmt.Println("NOT every kept archive is known to be held: keep the store's collector on --dry-run")
-	}
-}

cmd/mesh-controller/condition_looks.go

@@ -1,76 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// The looks of the open conditions — how often each was observed, when last, its newest evidence — are
-// kept in the controller's store, not the conditions bucket (novox/hq issue 420, ADR 0289 §1): the bucket
-// is written when what a condition says changes, never for a look that saw it as it was.
-
-// storeLooks keeps the conditions' looks in the inventory.
-type storeLooks struct{ inv *inventory.Inventory }
-
-func (s storeLooks) KeepLooks(ctx context.Context, key string, l conditions.Looks) error {
-	evidence, err := json.Marshal(l.Evidence)
-	if err != nil {
-		return err
-	}
-	return s.inv.KeepConditionLooks(ctx, inventory.ConditionLooks{Key: key, Observations: l.Observations,
-		LastObserved: l.LastObserved, Evidence: evidence})
-}
-
-func (s storeLooks) Looked(ctx context.Context, key string) (conditions.Looks, bool, error) {
-	row, kept, err := s.inv.ConditionLooksOf(ctx, key)
-	if err != nil || !kept {
-		return conditions.Looks{}, kept, err
-	}
-	l, err := looksOf(row)
-	return l, err == nil, err
-}
-
-func (s storeLooks) AllLooks(ctx context.Context) (map[string]conditions.Looks, error) {
-	rows, err := s.inv.AllConditionLooks(ctx)
-	if err != nil {
-		return nil, err
-	}
-	out := make(map[string]conditions.Looks, len(rows))
-	for key, row := range rows {
-		l, err := looksOf(row)
-		if err != nil {
-			return nil, err
-		}
-		out[key] = l
-	}
-	return out, nil
-}
-
-func (s storeLooks) ForgetLooks(ctx context.Context, key string) error {
-	return s.inv.ForgetConditionLooks(ctx, key)
-}
-
-func looksOf(row inventory.ConditionLooks) (conditions.Looks, error) {
-	l := conditions.Looks{Observations: row.Observations, LastObserved: row.LastObserved.UTC()}
-	if len(row.Evidence) > 0 {
-		if err := json.Unmarshal(row.Evidence, &l.Evidence); err != nil {
-			return conditions.Looks{}, fmt.Errorf("the evidence kept for the condition %s cannot be read: %w", row.Key, err)
-		}
-	}
-	return l, nil
-}
-
-// looksHere is where a process that is not the serving controller reads the conditions' looks: the store,
-// opened for it, closed by the function returned. A store that cannot be opened is said on every condition
-// read through it, never read as none.
-func looksHere(ctx context.Context) (conditions.LookStore, func()) {
-	inv, err := openInventory(ctx)
-	if err != nil {
-		return conditions.NoLooks{Err: err}, func() {}
-	}
-	return storeLooks{inv}, inv.Close
-}

cmd/mesh-controller/condition_looks_test.go

@@ -1,87 +0,0 @@
-package main
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"testing"
-	"time"
-
-	"github.com/nats-io/nats.go/jetstream"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/testbus"
-)
-
-// **Looks at an unchanged condition write the bucket once, and `conditions` still says how often and when
-// it was seen** (novox/hq issue 420): the looks are in the controller's store, and the verb, run as a
-// process of its own, reads them from there. On 2026-10-10 one open condition had rewritten the bucket 7 003
-// times in two days.
-func TestTheConditionsVerbReadsTheLooksTheBucketNoLongerHolds(t *testing.T) {
-	inv := inventory.ForTest(t)
-	bus := testbus.Start(t)
-	serving, err := broker.Dial(bus.ClientURL())
-	if err != nil {
-		t.Fatal(err)
-	}
-	defer serving.Close()
-	if err := serving.EnsureControllerBuckets(); err != nil {
-		t.Fatal(err)
-	}
-	ctx := t.Context()
-	store, history, err := conditions.OnTheBus(ctx, serving.Conn())
-	if err != nil {
-		t.Fatal(err)
-	}
-	k := conditions.NewKeeper(ctx, conditions.Options{Store: store, History: history, Looks: storeLooks{inv}})
-	defer k.Close(context.Background())
-	look := conditions.Observation{Scope: conditions.ScopeMachine, ID: "anchor", Kind: "silent", Machine: "anchor",
-		Severity: conditions.Warning, Summary: "anchor has not been heard from", Source: "S1"}
-	for range 4 {
-		if _, err := k.Observe(ctx, look); err != nil {
-			t.Fatal(err)
-		}
-	}
-
-	api, err := jetstream.New(serving.Conn())
-	if err != nil {
-		t.Fatal(err)
-	}
-	stream, err := api.Stream(ctx, "KV_"+broker.ConditionsBucket)
-	if err != nil {
-		t.Fatal(err)
-	}
-	info, err := stream.Info(ctx)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if info.State.LastSeq != 1 {
-		t.Fatalf("four looks at one unchanged condition wrote the bucket %d times, want 1", info.State.LastSeq)
-	}
-
-	// The verb as a process other than the serving controller: it reads the bucket and the store.
-	keptBefore := conditionsFrom
-	conditionsFrom = nil
-	defer func() { conditionsFrom = keptBefore }()
-	t.Setenv(broker.NATSVar, bus.ClientURL())
-	t.Setenv(broker.CertificateVar, "")
-	var shown bytes.Buffer
-	if err := showCondition(ctx, []string{"machine.anchor.silent", "--json"}, &shown); err != nil {
-		t.Fatal(err)
-	}
-	var c conditions.Condition
-	if err := json.Unmarshal(shown.Bytes(), &c); err != nil {
-		t.Fatalf("%v: %s", err, shown.String())
-	}
-	if c.Observations != 4 || len(c.Evidence) != 4 || c.LastObserved.IsZero() || c.LooksUnread != "" ||
-		time.Since(c.LastObserved) > time.Minute {
-		t.Fatalf("conditions show reads %d observation(s), %d evidence line(s), last %s (%q)", c.Observations,
-			len(c.Evidence), c.LastObserved, c.LooksUnread)
-	}
-	listed, err := openConditions(ctx)
-	if err != nil || len(listed) != 1 || listed[0].Observations != 4 {
-		t.Fatalf("conditions lists %+v: %v", listed, err)
-	}
-}

cmd/mesh-controller/conditions.go

@@ -1,491 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"flag"
-	"fmt"
-	"io"
-	"os"
-	"slices"
-	"strconv"
-	"strings"
-	"time"
-
-	"github.com/nats-io/nats.go"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// What is wrong, kept until observation says it is not (novox/hq to-be 45 §2, ADR 0227).
-//
-// **`status` used to be the only place the mesh said it was wrong, and only to whoever asked.** Every
-// core failure of research 031 was found by a person looking. A condition is the mesh saying it: raised
-// by a watchdog when a signal is late (signals.go), by a probe when an invariant does not hold
-// (doctor.go), or by an event a provider sends (standing.go); kept on the bus with since-when, and its
-// looks — how often, when last, the newest evidence — in the controller's store (condition_looks.go,
-// novox/hq issue 420); said on the bus as it changes, for the operator's channel to carry; and cleared when an
-// observation says it is resolved. Nobody resolves one by hand. A person who knows silences it, for a
-// while, with a reason, and that is recorded as a hand act.
-
-// conditionsFrom is the serving controller's keeper; nil in any other process, which opens its own.
-var conditionsFrom *conditions.Keeper
-
-// keeperOn is a keeper over the store on a connection, saying its transitions on that connection, with
-// the conditions' looks kept in looks (condition_looks.go).
-func keeperOn(ctx context.Context, conn *nats.Conn, looks conditions.LookStore) (*conditions.Keeper, error) {
-	store, history, err := conditions.OnTheBus(ctx, conn)
-	if err != nil {
-		return nil, err
-	}
-	js, err := conn.JetStream()
-	if err != nil {
-		return nil, err
-	}
-	return conditions.NewKeeper(ctx, conditions.Options{Store: store, History: history, Looks: looks,
-		Teller: link.OverNATS{Conn: conn, JS: js},
-		Say:    func(format string, args ...any) { fmt.Fprintf(os.Stderr, format+"\n", args...) },
-		// What status leads with changed: composed again soon (a nudge outside the serving controller
-		// does nothing).
-		Changed: func() { statusFrom.nudge(); askerFrom.nudge() },
-		// Written under the lease, carrying its epoch (novox/hq to-be 45 §6).
-		Epoch: func() (uint64, error) { return theLease.epoch(context.WithoutCancel(ctx)) }}), nil
-}
-
-// withKeeper runs f with the serving controller's keeper, or one of its own that says everything
-// it was given before it returns.
-func withKeeper(ctx context.Context, f func(*conditions.Keeper) error) error {
-	if conditionsFrom != nil {
-		return f(conditionsFrom)
-	}
-	looks, closeLooks := looksHere(ctx)
-	defer closeLooks()
-	return onTheBus(func(conn *nats.Conn) error {
-		k, err := keeperOn(ctx, conn, looks)
-		if err != nil {
-			return err
-		}
-		defer func() {
-			flushing, cancel := context.WithTimeout(context.Background(), 15*time.Second)
-			defer cancel()
-			k.Close(flushing)
-		}()
-		return f(k)
-	})
-}
-
-// openConditions is every open condition, for `status` and `node show`: from the serving keeper, or
-// read from the bus. Where there is no bus to read it from, it says so — never "none open".
-func openConditions(ctx context.Context) ([]conditions.Condition, error) {
-	if conditionsFrom != nil {
-		return conditionsFrom.Open(ctx)
-	}
-	if _, err := broker.BusAddress(); err != nil {
-		return nil, fmt.Errorf("this process has no bus to read the conditions from: %w", err)
-	}
-	var out []conditions.Condition
-	looks, closeLooks := looksHere(ctx)
-	defer closeLooks()
-	err := onTheBus(func(conn *nats.Conn) error {
-		store, _, err := conditions.OnTheBus(ctx, conn)
-		if err != nil {
-			return err
-		}
-		reading, cancel := context.WithTimeout(ctx, 5*time.Second)
-		defer cancel()
-		out, err = conditions.ReadWith(reading, store, looks)
-		return err
-	})
-	return out, err
-}
-
-// conditionsUsage is how the verb is typed.
-const conditionsUsage = "conditions [--scope S] [--severity urgent|warning] [--machine M] [--json] | " +
-	"conditions show <key> | conditions silence <key> --for <duration> --why <text> | " +
-	"conditions history [--days N] [--key K] [--json]"
-
-// conditionsCommand is `conditions`, `conditions show`, `conditions silence` and `conditions history`.
-func conditionsCommand(ctx context.Context, args []string) error {
-	sub := "list"
-	if len(args) > 0 && !strings.HasPrefix(args[0], "-") {
-		sub, args = args[0], args[1:]
-	}
-	switch sub {
-	case "list":
-		return listConditions(ctx, args, os.Stdout)
-	case "show":
-		return showCondition(ctx, args, os.Stdout)
-	case "silence":
-		return silenceCondition(ctx, args)
-	case "history":
-		return conditionHistory(ctx, args, os.Stdout)
-	}
-	return errors.New(conditionsUsage)
-}
-
-func listConditions(ctx context.Context, args []string, w io.Writer) error {
-	set := flag.NewFlagSet("conditions", flag.ContinueOnError)
-	usageTo(set, w)
-	scope := set.String("scope", "", "only this scope: "+strings.Join(conditions.Scopes, ", "))
-	severity := set.String("severity", "", "only urgent, or only warning")
-	machine := set.String("machine", "", "only those about this machine")
-	asJSON := set.Bool("json", false, "as data")
-	if rest, err := parseAround(set, args); err != nil {
-		return err
-	} else if len(rest) > 0 {
-		return errors.New(conditionsUsage)
-	}
-	if *severity != "" && *severity != string(conditions.Urgent) && *severity != string(conditions.Warning) {
-		return fmt.Errorf("a severity is urgent or warning, not %q", *severity)
-	}
-	open, err := openConditions(ctx)
-	if err != nil {
-		return err
-	}
-	var out []conditions.Condition
-	for _, c := range open {
-		if (*scope == "" || c.Subject.Scope == *scope) && (*severity == "" || string(c.Severity) == *severity) &&
-			(*machine == "" || concerns(c, *machine)) {
-			out = append(out, c)
-		}
-	}
-	if *asJSON {
-		return printJSONTo(w, map[string]any{"conditions": inBrief(out), "open": len(open), "counted": counted(out),
-			"note": "urgent first, then oldest first; a condition clears when observation says so, never by hand; " +
-				"each with its newest evidence — `conditions key=<key>` gives one whole"})
-	}
-	if len(out) == 0 {
-		if len(open) == 0 {
-			fmt.Fprintln(w, "no open conditions")
-		} else {
-			fmt.Fprintf(w, "none of the %d open condition(s) is about that\n", len(open))
-		}
-		return nil
-	}
-	for _, line := range conditionLines(out, time.Now()) {
-		fmt.Fprintln(w, line)
-	}
-	return nil
-}
-
-// briefEvidence is how many observations a condition carries in a list of them: its newest. The store
-// keeps ten, and a list of hundreds of conditions with ten each was the larger half of an answer more
-// than the bus carries in one message (novox/hq issue 314). One condition whole is `conditions key=`.
-const briefEvidence = 1
-
-// conditionInBrief is a condition as a list carries it: its newest evidence, with how much more there is
-// and where to read it. Everything else of it, so a reader of the list — the operator's channel among
-// them — reads the same condition it always did.
-type conditionInBrief struct {
-	conditions.Condition
-	// EvidenceKept is how many observations the condition keeps, when the list shows fewer.
-	EvidenceKept int    `json:"evidence-kept,omitempty"`
-	More         string `json:"more,omitempty"`
-}
-
-// inBrief is a list of conditions in brief; never null.
-func inBrief(list []conditions.Condition) []conditionInBrief {
-	out := make([]conditionInBrief, 0, len(list))
-	for _, c := range list {
-		b := conditionInBrief{Condition: c}
-		if len(c.Evidence) > briefEvidence {
-			b.EvidenceKept = len(c.Evidence)
-			b.Evidence = c.Evidence[:briefEvidence:briefEvidence]
-			b.More = c.Show()
-		}
-		out = append(out, b)
-	}
-	return out
-}
-
-// counted is how many of a list each source raised of each kind — `D14 stalled: 689` — so a list of
-// hundreds says its shape before its lines.
-func counted(list []conditions.Condition) map[string]int {
-	out := map[string]int{}
-	for _, c := range list {
-		out[c.Source+" "+c.Kind]++
-	}
-	return out
-}
-
-// concerns says whether a condition is about a machine: it names it, or its key does.
-func concerns(c conditions.Condition, machine string) bool {
-	if c.Subject.Machine == machine || slices.Contains(c.Subject.Also, machine) {
-		return true
-	}
-	for _, part := range strings.Split(c.Key, ".") {
-		if part == machine {
-			return true
-		}
-	}
-	return false
-}
-
-// conditionLines is how a list of conditions reads: one line each, its silence under it.
-func conditionLines(list []conditions.Condition, now time.Time) []string {
-	var out []string
-	for _, c := range list {
-		times := ""
-		if c.Count > 1 {
-			times = fmt.Sprintf(", raised %d times", c.Count)
-		}
-		out = append(out, fmt.Sprintf("  %-7s %s — %s (since %s%s)", strings.ToUpper(string(c.Severity)),
-			c.Key, c.Summary, c.Raised.Local().Format("2006-01-02 15:04"), times))
-		if c.SilencedAt(now) {
-			out = append(out, fmt.Sprintf("          silenced until %s by %s: %s",
-				c.Silenced.Until.Local().Format("2006-01-02 15:04"), c.Silenced.By, c.Silenced.Why))
-		}
-	}
-	return out
-}
-
-func showCondition(ctx context.Context, args []string, w io.Writer) error {
-	set := flag.NewFlagSet("conditions show", flag.ContinueOnError)
-	usageTo(set, w)
-	asJSON := set.Bool("json", false, "as data")
-	rest, err := parseAround(set, args)
-	if err != nil {
-		return err
-	}
-	if len(rest) != 1 {
-		return errors.New("conditions show <key>")
-	}
-	key := rest[0]
-	var c conditions.Condition
-	var found bool
-	if conditionsFrom != nil {
-		c, found, err = conditionsFrom.Get(ctx, key)
-	} else {
-		looks, closeLooks := looksHere(ctx)
-		defer closeLooks()
-		err = onTheBus(func(conn *nats.Conn) error {
-			store, _, err := conditions.OnTheBus(ctx, conn)
-			if err != nil {
-				return err
-			}
-			c, found, err = conditions.ReadOneWith(ctx, store, looks, key)
-			return err
-		})
-	}
-	if err != nil {
-		return err
-	}
-	if !found {
-		return fmt.Errorf("no condition %s is open — `conditions` lists those that are, and `conditions "+
-			"history --key %s` what became of it", key, key)
-	}
-	if *asJSON {
-		return printJSONTo(w, c)
-	}
-	now := time.Now()
-	fmt.Fprintf(w, "%s  %s\n  %s\n\n", strings.ToUpper(string(c.Severity)), c.Key, c.Summary)
-	fmt.Fprintf(w, "  kind       %s\n  about      %s %s", c.Kind, c.Subject.Scope, c.Subject.ID)
-	if c.Subject.Machine != "" {
-		fmt.Fprintf(w, ", on %s", c.Subject.Machine)
-	}
-	fmt.Fprintf(w, "\n  raised by  %s\n  since      %s (%s ago), observed %d time(s), last %s ago\n",
-		c.Source, c.Raised.Local().Format("2006-01-02 15:04:05"), roughly(now.Sub(c.Raised)), c.Observations,
-		now.Sub(c.LastObserved).Round(time.Second))
-	if c.Count > 1 {
-		fmt.Fprintf(w, "  raised     %d times, each within ten minutes of clearing\n", c.Count)
-	}
-	fmt.Fprintf(w, "  resolved   by %s\n", resolverWords(c.Resolver))
-	if c.Silenced != nil {
-		fmt.Fprintf(w, "  silenced   until %s by %s: %s\n", c.Silenced.Until.Local().Format("2006-01-02 15:04"),
-			c.Silenced.By, c.Silenced.Why)
-	}
-	if len(c.Tried) > 0 {
-		fmt.Fprintln(w, "\n  tried:")
-		for _, t := range c.Tried {
-			fmt.Fprintf(w, "    %s  %s — %s: %s\n", t.At.Local().Format("2006-01-02 15:04"), orHealer(t.By), t.What, t.Outcome)
-		}
-	}
-	fmt.Fprintln(w, "\n  evidence, newest first:")
-	for _, e := range c.Evidence {
-		fmt.Fprintf(w, "    %s  %s\n", e.At.Local().Format("2006-01-02 15:04:05"), e.Said)
-	}
-	return nil
-}
-
-func resolverWords(r string) string {
-	switch r {
-	case conditions.ResolverSelf:
-		return "itself: it clears when observation says it is resolved"
-	case conditions.ResolverOperator:
-		return "the operator: nothing in the mesh will repair it"
-	case conditions.ResolverAgent:
-		return "an agent"
-	}
-	return r
-}
-
-// silenceCondition stops a condition's messages for a while (to-be 45 §2). A hand act: recorded with
-// who and why before it is done, its cause the condition's kind unless one is given.
-func silenceCondition(ctx context.Context, args []string) error {
-	set := flag.NewFlagSet("conditions silence", flag.ContinueOnError)
-	forFlag := set.String("for", "", "how long: 30m, 4h, 2d — at most 7d")
-	acts := addHandActFlags(set)
-	rest, err := parseAround(set, args)
-	if err != nil {
-		return err
-	}
-	if len(rest) != 1 {
-		return errors.New("conditions silence <key> --for <duration> --why <text>")
-	}
-	key := rest[0]
-	if err := acts.require("conditions silence"); err != nil {
-		return err
-	}
-	d, err := parseFor(*forFlag)
-	if err != nil {
-		return err
-	}
-	if d > conditions.MaxSilence {
-		return fmt.Errorf("a condition is silenced for at most %s at once; past it, say so again", conditions.MaxSilence)
-	}
-	return withKeeper(ctx, func(k *conditions.Keeper) error {
-		c, found, err := k.Get(ctx, key)
-		if err != nil {
-			return err
-		}
-		if !found {
-			return fmt.Errorf("no condition %s is open — `conditions` lists them. Nothing was silenced", key)
-		}
-		if strings.TrimSpace(*acts.cause) == "" {
-			*acts.cause = c.Kind
-		}
-		*acts.condition = key
-		acts.record(ctx, "conditions silence", []string{key, "--for", *forFlag})
-		held, err := k.Silence(ctx, key, d, link.Caller(), *acts.why)
-		if err != nil {
-			return err
-		}
-		fmt.Printf("%s is silenced until %s: no message is sent for it until then. It is still open, and "+
-			"`status` still says it; it clears when observation says it is resolved\n",
-			held.Key, held.Silenced.Until.Local().Format("2006-01-02 15:04"))
-		return nil
-	})
-}
-
-// parseFor reads a duration, days included.
-func parseFor(s string) (time.Duration, error) {
-	s = strings.TrimSpace(s)
-	if s == "" {
-		return 0, errors.New("say for how long: --for 30m, 4h or 2d")
-	}
-	if days, ok := strings.CutSuffix(s, "d"); ok {
-		n, err := strconv.Atoi(days)
-		if err != nil || n <= 0 {
-			return 0, fmt.Errorf("%q is not a number of days", s)
-		}
-		return time.Duration(n) * 24 * time.Hour, nil
-	}
-	d, err := time.ParseDuration(s)
-	if err != nil || d <= 0 {
-		return 0, fmt.Errorf("%q is not a duration: 30m, 4h or 2d", s)
-	}
-	return d, nil
-}
-
-func conditionHistory(ctx context.Context, args []string, w io.Writer) error {
-	set := flag.NewFlagSet("conditions history", flag.ContinueOnError)
-	usageTo(set, w)
-	days := set.Int("days", 7, "how many days back, at most 90")
-	key := set.String("key", "", "only this condition")
-	asJSON := set.Bool("json", false, "as data")
-	if rest, err := parseAround(set, args); err != nil {
-		return err
-	} else if len(rest) > 0 {
-		return errors.New("conditions history [--days N] [--key K] [--json]")
-	}
-	since := time.Now().Add(-time.Duration(*days) * 24 * time.Hour)
-	var events []conditions.Event
-	read := func(h conditions.History) error {
-		var err error
-		events, err = h.Since(ctx, since)
-		return err
-	}
-	var err error
-	if conditionsFrom != nil {
-		events, err = conditionsFrom.HistorySince(ctx, since)
-	} else {
-		err = onTheBus(func(conn *nats.Conn) error {
-			_, history, err := conditions.OnTheBus(ctx, conn)
-			if err != nil {
-				return err
-			}
-			return read(history)
-		})
-	}
-	if err != nil {
-		return err
-	}
-	var out []conditions.Event
-	for _, e := range events {
-		if *key == "" || e.Key == *key {
-			out = append(out, e)
-		}
-	}
-	if *asJSON {
-		if out == nil {
-			out = []conditions.Event{}
-		}
-		return printJSONTo(w, map[string]any{"history": out, "days": *days})
-	}
-	if len(out) == 0 {
-		fmt.Fprintf(w, "nothing was raised, changed or cleared in the last %d day(s)\n", *days)
-		return nil
-	}
-	for _, e := range out {
-		line := fmt.Sprintf("%s  %-13s %s", e.At.Local().Format("2006-01-02 15:04:05"), e.Change, e.Key)
-		switch e.Change {
-		case conditions.ChangeRaised, conditions.ChangeReopened:
-			line += " — " + e.Summary
-		case conditions.ChangeSeverity:
-			line += fmt.Sprintf(" — %s, was %s", e.Severity, e.Was)
-		case conditions.ChangeResolver:
-			line += fmt.Sprintf(" — %s, was %s", e.Resolver, e.Was)
-		default:
-			if e.Why != "" {
-				line += " — " + e.Why
-			}
-		}
-		fmt.Fprintln(w, line)
-	}
-	return nil
-}
-
-// printConditions is the status section that leads it: every open condition, urgent first, oldest
-// first, silenced ones with their expiry (to-be 45 §2). A store that could not be read is said, and
-// is not "none open".
-func printConditions(list []conditions.Condition, unread string, now time.Time) {
-	if unread != "" {
-		fmt.Printf("the open conditions could NOT be read, so whether anything is wrong is not known: %s\n\n", unread)
-		return
-	}
-	if len(list) == 0 {
-		return
-	}
-	urgent := 0
-	for _, c := range list {
-		if c.Severity == conditions.Urgent {
-			urgent++
-		}
-	}
-	fmt.Printf("%d open condition(s), %d urgent:\n\n", len(list), urgent)
-	for _, line := range conditionLines(list, now) {
-		fmt.Println(line)
-	}
-	fmt.Printf("\n  `conditions show <key>` says more; each clears when observation says it is resolved, " +
-		"never by hand — `conditions silence <key> --for <d> --why <text>` stops its messages\n\n")
-}
-
-// orHealer is who tried, as an attempt names it.
-func orHealer(by string) string {
-	if by == "" {
-		return "a healer"
-	}
-	return by
-}

cmd/mesh-controller/conditions_brief_test.go

@@ -1,108 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"fmt"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-)
-
-// stalledConditions are n open conditions like those of 2026-10-08: one per delivery held past its bound,
-// each keeping all its evidence.
-func stalledConditions(n int) []conditions.Condition {
-	at := time.Date(2026, 10, 8, 9, 0, 0, 0, time.UTC)
-	var out []conditions.Condition
-	for i := 0; i < n; i++ {
-		id := fmt.Sprintf("d-%012x", 0x51a11ed+i)
-		lines := stalledObservations([]stalledLine{{ID: id, State: "checking", For: "13h2m", Bound: "45m",
-			H2: "close: recheck", Says: "the check was asked and nothing has answered"}})
-		o := lines[0]
-		c := conditions.Condition{Key: o.Key(), Kind: o.Kind, Subject: conditions.Subject{Scope: o.Scope, ID: o.ID},
-			Severity: o.Severity, Summary: o.Summary, Source: probeDeliveriesID, Raised: at, LastObserved: at,
-			Observations: 160, Count: 1, Resolver: conditions.ResolverSelf}
-		for e := 0; e < conditions.KeptEvidence; e++ {
-			c.Evidence = append(c.Evidence, conditions.Evidence{At: at.Add(time.Duration(e) * 5 * time.Minute),
-				Said: "checking for " + (13*time.Hour + time.Duration(e)*time.Minute).String()})
-		}
-		out = append(out, c)
-	}
-	return out
-}
-
-// novox/hq issue 314: a list of hundreds of open conditions carries each one's newest evidence, with
-// how much more it keeps and where to read it, and the verb's answer says it once — as data, not again
-// as the text the command printed. On 2026-10-08, 689 stalled deliveries made that answer more than the
-// bus carries in one message; now it is less than half of one.
-func TestAListOfConditionsCarriesEachInBrief(t *testing.T) {
-	list := stalledConditions(689)
-	printed, _ := json.MarshalIndent(map[string]any{"conditions": inBrief(list), "open": len(list),
-		"counted": counted(list)}, "", "  ")
-	var parsed any
-	if err := json.Unmarshal(printed, &parsed); err != nil {
-		t.Fatal(err)
-	}
-	wire, _ := json.Marshal(map[string]any{"result": verbAnswer{OK: true, Answer: parsed,
-		Output: "its answer, as data, is `answer`\n"}})
-	before, _ := json.MarshalIndent(map[string]any{"conditions": list}, "", "  ")
-	t.Logf("689 stalled deliveries: %d bytes on the wire, where the whole list printed was %d and was sent twice",
-		len(wire), len(before))
-	if len(wire) >= 512<<10 {
-		t.Fatalf("the answer of 689 conditions is %d bytes, not under half of one message of the bus", len(wire))
-	}
-	var doc struct {
-		Conditions []conditionInBrief `json:"conditions"`
-		Counted    map[string]int     `json:"counted"`
-	}
-	if err := json.Unmarshal(printed, &doc); err != nil {
-		t.Fatal(err)
-	}
-	c := doc.Conditions[0]
-	if len(doc.Conditions) != 689 || len(c.Evidence) != 1 || c.EvidenceKept != conditions.KeptEvidence ||
-		c.Key != list[0].Key || c.Summary != list[0].Summary || !strings.Contains(c.More, "key="+c.Key) {
-		t.Fatalf("a condition in brief reads %+v", c)
-	}
-	if doc.Counted["D14 stalled"] != 689 {
-		t.Fatalf("counted %v", doc.Counted)
-	}
-	if one := inBrief(list[:1])[0]; len(list[0].Evidence) != conditions.KeptEvidence || one.Evidence[0] != list[0].Evidence[0] {
-		t.Fatal("the brief changed the condition it was made from, or kept other than the newest")
-	}
-}
-
-// The self-check's verdict carries at most overviewFindings of one probe's findings, with their count and
-// how to read them all; `doctor probe=` gives that probe whole (novox/hq issue 314).
-func TestAVerdictCarriesAProbesFindingsInBrief(t *testing.T) {
-	var found []string
-	for i := 0; i < 689; i++ {
-		found = append(found, fmt.Sprintf("delivery d-%012x has been checking for 13h, past its bound of 45m", i))
-	}
-	run := doctorRun{Run: "run-1", Probes: []probeVerdict{{ID: "D14", Verdict: "failed", Found: found},
-		{ID: "D1", Verdict: "passed"}}}
-	answer, err := verdictAnswer(run, time.Now(), "")
-	if err != nil {
-		t.Fatal(err)
-	}
-	brief := answer["run"].(doctorRun).Probes[0]
-	if len(brief.Found) != overviewFindings || brief.FoundCount != 689 || !strings.Contains(brief.More, "probe=D14") {
-		t.Fatalf("the verdict carries %d findings of D14, count %d, more %q", len(brief.Found), brief.FoundCount, brief.More)
-	}
-	if len(run.Probes[0].Found) != 689 {
-		t.Fatal("the overview cut the run it was made from")
-	}
-	whole, err := verdictAnswer(run, time.Now(), "d14")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if p := whole["run"].(doctorRun).Probes; len(p) != 1 || len(p[0].Found) != 689 || p[0].More != "" {
-		t.Fatalf("doctor probe=D14 answered %+v", p)
-	}
-	if _, err := verdictAnswer(run, time.Now(), "D99"); err == nil {
-		t.Fatal("a probe the run does not have was answered")
-	}
-	if !strings.Contains(doctorText(answer), "probe=D14` gives them all") {
-		t.Fatalf("the text does not say how to read them all:\n%s", doctorText(answer))
-	}
-}

cmd/mesh-controller/conditions_test.go

@@ -1,107 +0,0 @@
-package main
-
-import (
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-)
-
-// The verbs of the condition store (novox/hq to-be 45 §2) as the console reaches them, and status led
-// by what is open.
-
-func TestTheConditionsVerbComposesEachShape(t *testing.T) {
-	for _, c := range []struct {
-		args map[string]any
-		want string
-	}{
-		{map[string]any{}, "conditions --json"},
-		{map[string]any{"severity": "urgent", "machine": "ace"}, "conditions --json --severity urgent --machine ace"},
-		{map[string]any{"key": "machine.ace.silent"}, "conditions show machine.ace.silent --json"},
-		{map[string]any{"history": "true", "days": "3", "key": "machine.ace.silent"},
-			"conditions history --json --days 3 --key machine.ace.silent"},
-		{map[string]any{"silence": "machine.ace.silent", "for": "2h", "why": "on the train"},
-			"conditions silence machine.ace.silent --for 2h --why on the train"},
-		{map[string]any{"run": "true"}, "doctor run --json"},
-		{map[string]any{}, "doctor --json"},
-	} {
-		verb := "conditions"
-		if strings.HasPrefix(c.want, "doctor") {
-			verb = "doctor"
-		}
-		argv, err := argvFor(verb, c.args)
-		if err != nil || strings.Join(argv, " ") != c.want {
-			t.Errorf("%s %v composed %q (%v), want %q", verb, c.args, strings.Join(argv, " "), err, c.want)
-		}
-	}
-	for _, c := range []struct {
-		verb string
-		args map[string]any
-	}{
-		{"conditions", map[string]any{"silence": "machine.ace.silent", "why": "x"}},                           // no for
-		{"doctor", map[string]any{"run": "true", "signals": "true"}},                                          // two at once
-		{"conditions", map[string]any{"silence": "machine.ace.silent", "for": "1h", "why": "x", "days": "3"}}, // passed over
-	} {
-		if argv, err := argvFor(c.verb, c.args); err == nil {
-			t.Errorf("%s %v composed %v", c.verb, c.args, argv)
-		}
-	}
-	if repairingCommand([]string{"conditions", "silence", "k"}) != "conditions silence" {
-		t.Error("a silence is not a hand act")
-	}
-}
-
-// **A silence through the verb is recorded and bounded**; the condition stays open.
-func TestASilenceThroughTheVerbHoldsAndTheConditionStaysOpen(t *testing.T) {
-	k, _ := withConditionsInMemory(t)
-	ctx := t.Context()
-	if _, err := k.Observe(ctx, conditions.Observation{Scope: conditions.ScopeMachine, ID: "ace", Kind: "silent",
-		Severity: conditions.Warning, Summary: "ace is silent", Source: "S1"}); err != nil {
-		t.Fatal(err)
-	}
-	if err := conditionsCommand(ctx, []string{"silence", "machine.ace.silent", "--for", "2d"}); err == nil {
-		t.Fatal("silenced without saying why")
-	}
-	if err := conditionsCommand(ctx, []string{"silence", "machine.ace.silent", "--for", "8d", "--why", "x"}); err == nil {
-		t.Fatal("silenced for more than a week")
-	}
-	said := printed(t, func() error {
-		return conditionsCommand(ctx, []string{"silence", "machine.ace.silent", "--for", "2d", "--why", "on the train"})
-	})
-	if !strings.Contains(said, "is silenced until") {
-		t.Fatalf("%s", said)
-	}
-	c, found, _ := k.Get(ctx, "machine.ace.silent")
-	if !found || c.Silenced == nil || c.Silenced.Why != "on the train" {
-		t.Fatalf("%+v", c)
-	}
-	listed := printed(t, func() error { return conditionsCommand(ctx, nil) })
-	if !strings.Contains(listed, "machine.ace.silent") || !strings.Contains(listed, "silenced until") {
-		t.Fatalf("%s", listed)
-	}
-}
-
-// **Conditions that cannot be read are not none open**: status says so, and is not well.
-func TestUnreadableConditionsAreNotAWellMesh(t *testing.T) {
-	open := aMesh(t)
-	_, store := withConditionsInMemory(t)
-	store.SetFail(errors.New("the bus is away"))
-	asked, err := theThreeQuestions(t.Context(), open)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if asked.well() || asked.conditionsUnread == "" {
-		t.Fatalf("well with its conditions unread: %+v", asked.conditionsUnread)
-	}
-	said := printed(t, func() error { return printStatus(asked) })
-	if !strings.HasPrefix(said, "the open conditions could NOT be read") || strings.Contains(said, "no open conditions") {
-		t.Fatalf("%s", said)
-	}
-	store.SetFail(nil)
-	asked, _ = theThreeQuestions(t.Context(), open)
-	said = printed(t, func() error { return printStatus(asked) })
-	if asked.well() && !strings.Contains(said, "no open conditions;") {
-		t.Fatalf("the all-well sentence does not say no conditions are open:\n%s", said)
-	}
-}

cmd/mesh-controller/confirm.go

@@ -1,67 +0,0 @@
-package main
-
-import (
-	"context"
-	"sync"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-)
-
-// **A finding one look can be wrong about is raised on the second look in a row** (novox/hq issue 277).
-//
-// D2 raised its resolver urgent on one unanswered question, asked once, while the resolver's machine
-// was loaded by a push and a build starting; thirty questions right after were answered at once. A
-// single sample of something that is answered over the network, or timed on a machine under load,
-// is not the invariant failing. So a source marks such a finding `Confirm`, and this holds it back:
-//
-//   - raised when the source's previous look saw it too — two runs of the self-check in a row (five
-//     minutes apart), or two ticks of the watchdogs (half a minute) — at the severity the source says;
-//   - kept while it is already open, however it is seen, so a condition the next look still sees is
-//     never cleared and raised again (flapping is not news; a reopening within ReopenWithin still is);
-//   - cleared, as everything is, by the look that no longer sees it.
-//
-// A finding held back is not a pass: the self-check's verdict names it as unconfirmed. A finding that is
-// a definite answer — a resolver that answered wrongly, a stream that is not there — is not marked, and
-// is raised at once.
-type confirming struct {
-	mu sync.Mutex
-	// last is, by source, the keys of the Confirm findings its previous look saw.
-	last map[string]map[string]bool
-}
-
-// pass splits one source's findings into what is raised now and what is held for the next look, and
-// remembers what it saw. An open condition that cannot be read is kept: unknown is not a reason to
-// hold a finding back.
-func (c *confirming) pass(ctx context.Context, keeper *conditions.Keeper, source string,
-	found []conditions.Observation) (raise, held []conditions.Observation) {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	if c.last == nil {
-		c.last = map[string]map[string]bool{}
-	}
-	before, seen := c.last[source], map[string]bool{}
-	for _, o := range found {
-		if !o.Confirm {
-			raise = append(raise, o)
-			continue
-		}
-		key := o.Key()
-		seen[key] = true
-		if before[key] || isOpen(ctx, keeper, key) {
-			raise = append(raise, o)
-			continue
-		}
-		held = append(held, o)
-	}
-	c.last[source] = seen
-	return raise, held
-}
-
-// isOpen says whether a condition is open; one that cannot be read is taken as open.
-func isOpen(ctx context.Context, keeper *conditions.Keeper, key string) bool {
-	if keeper == nil {
-		return false
-	}
-	_, open, err := keeper.Get(ctx, key)
-	return open || err != nil
-}

cmd/mesh-controller/core_downgrade.go

@@ -1,215 +0,0 @@
-package main
-
-import (
-	"context"
-	"fmt"
-	"sort"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/lease"
-)
-
-// **No send but a person's `push <node>` and a gate's own put-back moves the mesh's own core to a build older
-// than the one its machine was last sent** (novox/hq issue 201). Every send made through sendToEach keeps it — a
-// plan's, a release's, a healer's, a rotation's, and the bus step too, which is a person's act but composes under
-// sendKeeps like the rest. On 2026-10-02 two merges a minute apart made two plans;
-// the controller's plan rolled the new controller, which widened its seat's row, and the node-engine's plan then
-// sent the control node the controller build before it. The older binary read the row it could not serve and the
-// mesh lost its voice for ten minutes — the thing that would have corrected it was the thing that was down. ADR
-// 0185 took the outage out of it (a controller behind its row serves what it can); the race is closed here,
-// without needing its trigger: whatever made the mesh's record older, the send keeps the build.
-//
-// **Kept, not refused.** The send composes the controller or the node-engine at the build the machine was last
-// sent, as a recorded module is kept (ADR 0245), and carries everything else: no other module, secret, healer or
-// walk waits on it, and nothing is retried. The kept move is no move for a gate either: ungatedIn and gatedSend
-// leave it out (withoutKept), so a gate judges the other moves of its send. A plan whose own build is the older one finds its gate superseded by
-// the build kept there (issue 352) and ends. The mesh's record stays older, and a warning condition says so until
-// a send carries the record — a person's `push <node>` accepts the older build — or the record moves forward: a
-// newer merge, or `rebuild mesh-controller`.
-//
-// Older is by the builds' registration order — when each was asked (novox/hq issue 219) — never by the commits'
-// dates. So a retry or a rebuild of an old commit, asked anew, counts as newer: it is registered as the module's
-// current build by the same order, and the guard does not stop that move. A build that failed its gate is never
-// ahead: the machine was sent it and the record was put back before it (gateFailed), and if the put-back's own
-// send was refused, the next send completes it rather than keeping the failed build there. A gate's own put-back
-// carries its modules back whatever the order (sendScope.puttingBack); the controller's is held to the store's
-// schema already (issue 352).
-
-// kindCoreDowngrade is a core module kept at the build its machine was last sent, over an older record.
-const kindCoreDowngrade = "core-downgrade-kept"
-
-// coreDowngradeSource is the condition's source: the sends, which raise and clear it.
-const coreDowngradeSource = "sends"
-
-// downgradeGuarded is the core components a send may not move backwards: the controller, which reads the
-// store and its seat's row, and the node-engine, which reads what the controller declares.
-var downgradeGuarded = []string{lease.ComponentController, lease.ComponentEngine}
-
-// askedBuild is what the order needs of one build of a module: when it was asked, and whether it failed its gate.
-type askedBuild struct {
-	asked      time.Time
-	failedGate bool
-}
-
-// buildAsked is the newest build of a module from a commit that worked — when it was asked (or recorded, when
-// the request time is not known), and whether it failed its gate — and false when the records hold none. A
-// variable, so a test reads its own order.
-var buildAsked = func(ctx context.Context, inv *inventory.Inventory, module, commit string) (askedBuild, bool, error) {
-	builds, err := inv.Builds(ctx, module, askedLookBack)
-	if err != nil {
-		return askedBuild{}, false, err
-	}
-	for _, b := range builds {
-		if b.Worked() && sameCommit(b.Commit, commit) {
-			failed, err := inv.GateFailed(ctx, b.ID)
-			if err != nil {
-				return askedBuild{}, false, err
-			}
-			return askedBuild{asked: b.AskedOrAt(), failedGate: failed}, true, nil
-		}
-	}
-	return askedBuild{}, false, nil
-}
-
-// askedLookBack is how many of a module's newest builds are read for when a build was asked.
-const askedLookBack = 50
-
-// coreDowngrade is one core module a machine was last sent a build of that is newer than the mesh's record.
-type coreDowngrade struct {
-	module, node, component string
-	// sent is the build the machine was last sent, record the one the mesh holds.
-	sent, record           string
-	sentAsked, recordAsked time.Time
-}
-
-func (d coreDowngrade) String() string {
-	return fmt.Sprintf("%s was last sent %s %s, and the mesh holds the older %s (asked %s, before %s): a send there "+
-		"keeps %s; `push %s` sends the older build, and a newer merge or `rebuild %s` moves the record forward "+
-		"(novox/hq issue 201)", d.node, d.module, short(d.sent), short(d.record),
-		d.recordAsked.UTC().Format(time.RFC3339), d.sentAsked.UTC().Format(time.RFC3339), short(d.sent), d.node,
-		d.module)
-}
-
-// coreDowngrades is, for one machine, each guarded core module whose record is older than the build the machine
-// was last sent, leaving out what a gate's own put-back puts back and a sent build that failed its gate. A move
-// whose either build the records do not hold is not proved older and is left to the gate that judges it. Pure
-// but for asked.
-func coreDowngrades(node string, sent map[string]string, record map[string]string, scope sendScope,
-	asked func(module, commit string) (askedBuild, bool, error)) ([]coreDowngrade, error) {
-	var out []coreDowngrade
-	for module, was := range sent {
-		component := coreComponent(module)
-		now := record[module]
-		if !guarded(component) || was == "" || now == "" || sameCommit(was, now) {
-			continue
-		}
-		if scope.puttingBack && scope.modules[module] {
-			continue
-		}
-		from, known, err := asked(module, was)
-		if err != nil {
-			return nil, fmt.Errorf("when %s's build %s was asked cannot be read: %w", module, short(was), err)
-		}
-		if !known || from.failedGate {
-			continue
-		}
-		to, known, err := asked(module, now)
-		if err != nil {
-			return nil, fmt.Errorf("when %s's build %s was asked cannot be read: %w", module, short(now), err)
-		}
-		if known && to.asked.Before(from.asked) {
-			out = append(out, coreDowngrade{module: module, node: node, component: component, sent: was, record: now,
-				sentAsked: from.asked, recordAsked: to.asked})
-		}
-	}
-	sort.Slice(out, func(i, j int) bool { return out[i].module < out[j].module })
-	return out, nil
-}
-
-func guarded(component string) bool {
-	for _, c := range downgradeGuarded {
-		if c == component {
-			return true
-		}
-	}
-	return false
-}
-
-// coreKept is, for a send that keeps (sendKeeps), each guarded core module of a machine to keep at the build it
-// was last sent, module → commit, each said and raised as a condition.
-func coreKept(ctx context.Context, inv *inventory.Inventory, node string, sent map[string]string,
-	current map[string]inventory.CurrentBuild) (map[string]string, error) {
-	record := map[string]string{}
-	for m, c := range current {
-		record[m] = c.Commit
-	}
-	found, err := coreDowngrades(node, sent, record, scopeOf(ctx), func(module, commit string) (askedBuild, bool, error) {
-		return buildAsked(ctx, inv, module, commit)
-	})
-	if err != nil || len(found) == 0 {
-		return nil, err
-	}
-	out := map[string]string{}
-	for _, d := range found {
-		out[d.module] = d.sent
-		sayCoreDowngrade(ctx, d)
-	}
-	return out, nil
-}
-
-// coreDowngradeObservation is a kept core build as a condition: `core.<component>.<machine>.<kind>`.
-func coreDowngradeObservation(component, node, summary string) conditions.Observation {
-	return conditions.Observation{Scope: conditions.ScopeCore, ID: component + "." + node, Kind: kindCoreDowngrade,
-		Token: kindCoreDowngrade, Machine: node, Severity: conditions.Warning, Source: coreDowngradeSource,
-		Summary: summary}
-}
-
-func sayCoreDowngrade(ctx context.Context, d coreDowngrade) {
-	fmt.Printf("KEPT: %s\n", d)
-	keeper := conditionsFrom
-	if keeper == nil {
-		return
-	}
-	if _, err := keeper.Observe(ctx, coreDowngradeObservation(d.component, d.node, d.String())); err != nil {
-		fmt.Printf("the condition for %s kept on %s could not be raised: %v\n", d.module, d.node, err)
-	}
-}
-
-// settleCoreDowngrades clears, after a send to a machine is away, the condition of each guarded core module the
-// send carried at the mesh's record — a person's push that accepted the older build, or a send after the record
-// moved forward — or did not carry at all. A send that kept the newer build leaves it open.
-func settleCoreDowngrades(ctx context.Context, inv *inventory.Inventory, node string, carried map[string]string) {
-	keeper := conditionsFrom
-	if keeper == nil || carried == nil {
-		return
-	}
-	var open []string
-	for _, c := range downgradeGuarded {
-		if _, found, err := keeper.Get(ctx, coreDowngradeObservation(c, node, "").Key()); err == nil && found {
-			open = append(open, c)
-		}
-	}
-	if len(open) == 0 {
-		return
-	}
-	current, err := inv.CurrentBuilds(ctx)
-	if err != nil {
-		fmt.Printf("whether %s still keeps a core build over the mesh's record cannot be read: %v\n", node, err)
-		return
-	}
-	for module, now := range current {
-		component := coreComponent(module)
-		if !guarded(component) {
-			continue
-		}
-		if was, has := carried[module]; has && !sameCommit(was, now.Commit) {
-			continue
-		}
-		key := coreDowngradeObservation(component, node, "").Key()
-		if _, err := keeper.Clear(ctx, key, node+" was sent the "+component+" the mesh holds"); err != nil {
-			fmt.Printf("the condition %s could not be cleared: %v\n", key, err)
-		}
-	}
-}

cmd/mesh-controller/credential_on_assign_test.go

@@ -1,90 +0,0 @@
-package main
-
-import (
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// A fresh assignment is pushed before its credential exists (novox/hq issue 203): `assign` recorded
-// the module, `push` sealed a random own secret where the bus credential belongs, and the process
-// crash-looped until a person ran `module issue` and pushed again. Now assigning a module that speaks
-// on the bus issues its credential in the same act — or, when the bus cannot be reached from here,
-// says which verb to run — and a push never seals a placeholder in a credential's place.
-
-func aTalker() catalogue.Manifest {
-	return catalogue.Manifest{Module: "talker", Version: "1",
-		OwnSecrets: catalogue.OwnSecrets{"broker": {Path: "/var/lib/mesh/talker/broker"}},
-		Resources: []map[string]any{
-			{"id": "state", "type": "directory", "path": "/var/lib/mesh/talker", "mode": "0700"},
-		}}
-}
-
-func TestAssigningAModuleThatSpeaksOnTheBusNamesItsCredential(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	register(t, open, aTalker())
-
-	// No bus is known to this process, so the credential cannot be issued here: the assignment
-	// stands and says exactly what must happen before a push — never silently.
-	said, err := assign(ctx, open, "laptop", "talker")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !strings.Contains(said, "module issue talker --node laptop") {
-		t.Fatalf("an assignment whose credential could not be issued does not name the verb:\n%s", said)
-	}
-
-	// And the push refuses to send it, naming the same verb, rather than sealing a placeholder.
-	plan, settings, err := planFor(ctx, open, "laptop")
-	if err != nil {
-		t.Fatal(err)
-	}
-	_, err = declarationFor(ctx, open, "laptop", plan, settings)
-	if err == nil {
-		t.Fatal("a push sealed a placeholder where talker's bus credential belongs")
-	}
-	if !strings.Contains(err.Error(), "module issue talker --node laptop") || !strings.Contains(err.Error(), "issue 203") {
-		t.Fatalf("the refusal does not say what to run: %v", err)
-	}
-
-	// Once the user is minted, the push goes on to the credential the mesh sealed, and re-assigning
-	// does not mint again: a credential rotates on purpose, never by habit.
-	if _, err := open.inventory.MintBusPassword(ctx, inventory.BusUser{
-		Username: "laptop.talker", Kind: inventory.BusModule, Node: "laptop", Module: "talker"}); err != nil {
-		t.Fatal(err)
-	}
-	hash, _, err := open.inventory.BusUserHash(ctx, "laptop.talker")
-	if err != nil {
-		t.Fatal(err)
-	}
-	said, err = assign(ctx, open, "laptop", "talker")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if strings.Contains(said, "module issue") {
-		t.Fatalf("a module with a minted credential was told to issue one:\n%s", said)
-	}
-	again, _, err := open.inventory.BusUserHash(ctx, "laptop.talker")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if again != hash {
-		t.Fatal("re-assigning rotated the credential")
-	}
-}
-
-// A module that declares no broker secret is left alone: nothing to issue, nothing said.
-func TestAssigningAModuleThatDoesNotSpeakSaysNothingOfCredentials(t *testing.T) {
-	open := aMesh(t)
-	register(t, open, helloWeb())
-	said, err := assign(t.Context(), open, "laptop", "hello-web")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if strings.Contains(said, "credential") {
-		t.Fatalf("a module without a broker secret was told about credentials:\n%s", said)
-	}
-}

cmd/mesh-controller/data.go

@@ -1,931 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"flag"
-	"fmt"
-	"log"
-	"sort"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/nats-io/nats.go"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// A module declares the data it holds, and the mesh protects and watches it from that declaration
-// (novox/hq ADR 0233).
-//
-// The self-check's D13 composes what every machine declares, asks each machine's backup holder what
-// it measured of every item — size, newest write, newest good backup, the redundant storage it is on —
-// and keeps both. From that, and from what every provider says it holds for its consumers, it raises,
-// each URGENT for what is irreplaceable and a WARNING for what is valuable (the operator's ranking):
-//
-//   - `data-shrank`: an item holds less than half of its largest size in seven days, and at least
-//     shrinkFloor less; `data-missing`: its path is gone;
-//   - `empty-replacement`: an item, or a consumer's data at a provider, is less than half the size of a
-//     copy of the same thing kept elsewhere — on 2026-10-05 five applications ran for twenty hours on
-//     empty databases while their real ones sat on another machine (issue 273);
-//   - `data-held-twice` (warning): a consumer has active data at two providers and their sizes cannot
-//     be compared;
-//   - `data-quiet`: an item said to be written all the time has not been, within its bound;
-//   - `backup-stale`: an item's newest good backup is older than its bound, or there is none;
-//   - `array-degraded`: the redundant storage an item is on is not healthy, or cannot be read;
-//     `protection-missing`: an item said to be protected by redundancy is on storage that is not;
-//   - `cleanup-waiting` (warning): an item retired more than thirty days, waiting for a person.
-//
-// And it retires: an irreplaceable or valuable item in a module's own directory that its machine no
-// longer declares — its module unassigned — is kept, marked retired with when and why, and listed by
-// `cleanup list` until `cleanup delete` removes it. The node-engine never deletes a directory with
-// anything in it; this is the record of what it kept. An operator's path is never retired or deleted.
-
-// The condition kinds of D13.
-const (
-	kindDataShrank       = "data-shrank"
-	kindEmptyReplacement = "empty-replacement"
-	kindDataHeldTwice    = "data-held-twice"
-	kindDataQuiet        = "data-quiet"
-	kindBackupStale      = "backup-stale"
-	kindDataUnmeasured   = "data-unmeasured"
-	// kindDataMissing is a watched item whose path is gone.
-	kindDataMissing = "data-missing"
-	// kindArrayDegraded is redundant storage watched data is on that is not healthy, or cannot be read.
-	kindArrayDegraded = "array-degraded"
-	// kindProtectionMissing is an item said to be protected by redundancy, on storage that is not.
-	kindProtectionMissing = "protection-missing"
-)
-
-// probeDataID is the self-check's id for this probe.
-const probeDataID = "D13"
-
-// The bounds the findings are read against.
-var (
-	// shrinkWindow is how far back the largest size is looked for.
-	shrinkWindow = 7 * 24 * time.Hour
-	// shrinkFloor is the least loss that is worth saying: two empty databases differ by a few
-	// megabytes, and half of almost nothing is noise.
-	shrinkFloor int64 = 16 << 20
-	// dataAsk is how long one machine's holder, or one provider, is given to answer.
-	dataAsk = 8 * time.Second
-)
-
-// keyOfItem is one item's condition id: its machine, module and item.
-func keyOfItem(machine, module, item string) string { return machine + "." + module + "." + item }
-
-// holderAnswer is what a node-backup holder's `backed-up` says of one module (ADR 0233 adds Data).
-type holderAnswer struct {
-	Module string       `json:"module"`
-	Data   []holderItem `json:"data"`
-}
-
-// holderItem is one item as the holder measured it.
-type holderItem struct {
-	Item       string     `json:"item"`
-	Class      string     `json:"class"`
-	Path       string     `json:"path"`
-	SizeBytes  *int64     `json:"size_bytes"`
-	LastWrite  *time.Time `json:"last_write"`
-	MeasuredAt *time.Time `json:"measured_at"`
-	LastBackup *time.Time `json:"last_backup"`
-	Error      string     `json:"error,omitempty"`
-	// Precision is what the size is: exact, a dataset's, partial, or none (ADR 0233).
-	Precision string `json:"precision,omitempty"`
-	// Redundancy is the redundant storage the item is on, where the holder could tell (ADR 0233).
-	Redundancy *inventory.Redundancy `json:"redundancy,omitempty"`
-}
-
-// readHolder reads a holder's answer into measurements by module and item.
-func readHolder(raw json.RawMessage) (map[string]map[string]inventory.Measurement, error) {
-	var modules []holderAnswer
-	if err := json.Unmarshal(raw, &modules); err != nil {
-		return nil, fmt.Errorf("its answer is not readable: %w", err)
-	}
-	out := map[string]map[string]inventory.Measurement{}
-	for _, m := range modules {
-		for _, it := range m.Data {
-			if out[m.Module] == nil {
-				out[m.Module] = map[string]inventory.Measurement{}
-			}
-			out[m.Module][it.Item] = inventory.Measurement{Path: it.Path, Size: it.SizeBytes, LastWrite: it.LastWrite,
-				MeasuredAt: it.MeasuredAt, LastBackup: it.LastBackup, Error: it.Error, Redundancy: it.Redundancy,
-				Precision: it.Precision}
-		}
-	}
-	return out, nil
-}
-
-// declaredOn is every data item a machine's composition declares, and the module there that holds
-// node-backup to measure them — empty for none.
-func declaredOn(plan catalogue.Resolution) ([]inventory.DeclaredData, string) {
-	var out []inventory.DeclaredData
-	held := ""
-	for _, m := range plan.Modules {
-		for _, c := range m.Claims {
-			if s, known := catalogue.SeatNamed(c.Name); known && s.Name == catalogue.BackupSeat {
-				held = m.Module
-			}
-		}
-		for _, it := range m.DataItems() {
-			out = append(out, inventory.DeclaredData{Module: m.Module, Item: it.ID, Class: it.Class,
-				Owned: it.OwnedByModule(), Protection: it.Protection()})
-		}
-	}
-	return out, held
-}
-
-// consumerCopy is one provider's account of one consumer: where, how big, and whether still active.
-type consumerCopy struct {
-	Node, Module, Consumer string
-	Size                   *int64
-	Retired                bool
-	// Class is how precious the consumer's data is: the stricter of what the provider keeps for its
-	// consumers and what the consumer says it keeps there (`kept-by`).
-	Class string
-}
-
-// probeData is D13.
-func probeData(ctx context.Context, d *doctor) ([]conditions.Observation, error) {
-	if d.js == nil {
-		return nil, errors.New("no bus to ask the machines over")
-	}
-	open := d.open
-	shelf, err := open.inventory.Catalogue(ctx)
-	if err != nil {
-		return nil, err
-	}
-	nodes, err := open.inventory.Nodes(ctx)
-	if err != nil {
-		return nil, err
-	}
-	heard := heardMachines(d)
-	now := time.Now()
-	delivered, err := readDeliveries(ctx, open.inventory)
-	if err != nil {
-		return nil, err
-	}
-
-	type machine struct {
-		name     string
-		declared []inventory.DeclaredData
-		held     bool
-		measured map[string]map[string]inventory.Measurement
-		askErr   error
-	}
-	var machines []*machine
-	for _, n := range nodes {
-		plan, _, err := planFor(ctx, open, n.Name)
-		if err != nil {
-			if ctx.Err() != nil {
-				return nil, ctx.Err()
-			}
-			// A machine that cannot be worked out declares nothing this run — which is not the same as
-			// declaring nothing: retiring its data on that would be acting on an unreadable result.
-			continue
-		}
-		declared, holder := declaredOn(plan)
-		// **A holder is asked only once its machine has been sent it and had time to report** (novox/hq
-		// issue 275): assigned and not pushed yet, it is not there to answer, and "did not say what it
-		// measured" about it was a warning for a push nobody had made yet.
-		held := holder != "" && delivered[n.Name].settled(holder, now)
-		machines = append(machines, &machine{name: n.Name, declared: declared, held: held})
-	}
-	// Every holder asked at once, as D8 asks every ban list.
-	var wg sync.WaitGroup
-	for _, m := range machines {
-		if !m.held || !heard[m.name] {
-			continue
-		}
-		wg.Add(1)
-		go func(m *machine) {
-			defer wg.Done()
-			asking, cancel := context.WithTimeout(ctx, dataAsk)
-			defer cancel()
-			raw, err := askSeatTool(asking, d.js.Conn(), catalogue.BackupSeat, "backed-up", m.name)
-			if err == nil {
-				m.measured, err = readHolder(raw)
-			}
-			m.askErr = err
-		}(m)
-	}
-	wg.Wait()
-
-	var out []conditions.Observation
-	for _, m := range machines {
-		if m.askErr != nil {
-			out = append(out, conditions.Observation{Scope: conditions.ScopeMachine, ID: m.name, Token: kindDataUnmeasured,
-				Kind: kindDataUnmeasured, Machine: m.name, Severity: conditions.Warning, Confirm: true,
-				Summary: fmt.Sprintf("%s's backup holder did not say what it measured of the data declared there, so "+
-					"nothing about that data is known", m.name),
-				Said: firstLine(m.askErr.Error())})
-		}
-		why := fmt.Sprintf("no longer declared on %s: its module was unassigned there, or is no longer pulled in", m.name)
-		change, err := open.inventory.RecordData(ctx, m.name, m.declared, m.measured, why, now)
-		if err != nil {
-			return nil, fmt.Errorf("what %s holds could not be kept: %w", m.name, err)
-		}
-		for _, r := range change.Retired {
-			log.Printf("data: %s of %s on %s RETIRED, kept at %s: %s — `cleanup list` shows it, and only `cleanup "+
-				"delete` removes it (novox/hq ADR 0233)", r.Item, r.Module, r.Machine, orUnknownPath(r.Path), why)
-		}
-		for _, r := range change.Reenabled {
-			log.Printf("data: %s of %s on %s is declared again, no longer retired", r.Item, r.Module, r.Machine)
-		}
-	}
-
-	records, err := open.inventory.Data(ctx)
-	if err != nil {
-		return nil, err
-	}
-	peaks, err := open.inventory.DataPeaks(ctx, now.Add(-shrinkWindow))
-	if err != nil {
-		return nil, err
-	}
-	bindings, err := open.inventory.Bindings(ctx)
-	if err != nil {
-		return nil, err
-	}
-	upgraded, keptBy := keptByClasses(bindings, shelf)
-	copies, err := consumerCopies(ctx, d.js.Conn(), open.inventory, shelf, keptBy)
-	if err != nil {
-		return nil, err
-	}
-	out = append(out, dataFindings(records, peaks, shelf, copies, upgraded, now)...)
-	return out, nil
-}
-
-func orUnknownPath(p string) string {
-	if p == "" {
-		return "a path its backup holder never named"
-	}
-	return p
-}
-
-// consumerCopies asks every provider of a provision whose consumers' data is kept what it holds, at
-// once. One that cannot answer is passed over: it says nothing about any copy, which is not a finding.
-func consumerCopies(ctx context.Context, conn *nats.Conn, inv *inventory.Inventory,
-	shelf map[string]catalogue.Manifest, keptBy map[string]string) ([]consumerCopy, error) {
-	instances, err := providerInstances(ctx, inv)
-	if err != nil {
-		return nil, err
-	}
-	var asked []providerInstance
-	for _, p := range instances {
-		m := shelf[p.Module]
-		keeps := false
-		for provision := range m.Grants {
-			keeps = keeps || m.KeepsConsumerData(provision)
-		}
-		if keeps {
-			asked = append(asked, p)
-		}
-	}
-	states := make([]*link.RetirementState, len(asked))
-	var wg sync.WaitGroup
-	for i, p := range asked {
-		wg.Add(1)
-		go func(i int, p providerInstance) {
-			defer wg.Done()
-			asking, cancel := context.WithTimeout(ctx, dataAsk)
-			defer cancel()
-			if s, err := askRetirement(asking, conn, p); err == nil {
-				states[i] = &s
-			}
-		}(i, p)
-	}
-	wg.Wait()
-	var out []consumerCopy
-	for i, p := range asked {
-		s := states[i]
-		if s == nil {
-			continue
-		}
-		class := consumersClass(shelf[p.Module])
-		for _, c := range s.Held {
-			cp := consumerCopy{Node: p.Node, Module: p.Module, Consumer: c,
-				Class: catalogue.StricterClass(class, keptBy[p.Module+"/"+c])}
-			if size, ok := s.HeldSizes[c]; ok && size >= 0 {
-				size := size
-				cp.Size = &size
-			}
-			out = append(out, cp)
-		}
-		for _, r := range s.Retired {
-			if r.Kind != "" && r.Kind != "consumer" {
-				continue
-			}
-			cp := consumerCopy{Node: p.Node, Module: p.Module, Consumer: r.Consumer, Retired: true,
-				Class: catalogue.StricterClass(class, keptBy[p.Module+"/"+r.Consumer])}
-			if r.SizeBytes != nil && *r.SizeBytes >= 0 {
-				cp.Size = r.SizeBytes
-			}
-			out = append(out, cp)
-		}
-	}
-	return out, nil
-}
-
-// severityOf is how loud a finding about data of a class is: urgent for what is irreplaceable, a warning
-// for anything else watched (the operator's ranking, ADR 0233).
-func severityOf(class string) conditions.Severity {
-	if class == catalogue.ClassIrreplaceable {
-		return conditions.Urgent
-	}
-	return conditions.Warning
-}
-
-// consumersClass is the most precious class a provider keeps any of its consumers' data as.
-func consumersClass(m catalogue.Manifest) string {
-	class := catalogue.ClassNone
-	for provision := range m.Grants {
-		if c, ok := m.ConsumerDataOf(provision); ok {
-			class = catalogue.StricterClass(class, c.Class)
-		} else if m.KeepsConsumerData(provision) {
-			class = catalogue.StricterClass(class, catalogue.ClassValuable)
-		}
-	}
-	return class
-}
-
-// keptByClasses is what consumers say of the data they keep with their providers (`kept-by`), read
-// through where each is bound: by provider module and consumer identity, the class of that consumer's
-// data there; and by provider item key (machine/module/item), the class the item holding it is held to.
-func keptByClasses(bindings []inventory.Binding, shelf map[string]catalogue.Manifest) (map[string]string, map[string]string) {
-	upgraded, keptBy := map[string]string{}, map[string]string{}
-	for _, b := range bindings {
-		m, ok := shelf[b.Consumer]
-		if !ok {
-			continue
-		}
-		k, said := m.KeptByOf(b.Provision)
-		if !said {
-			continue
-		}
-		identity := catalogue.ConsumerIdentity(b.Machine, catalogue.IdentitySource(m.Slug, m.Module))
-		key := b.Provider.Module + "/" + identity
-		keptBy[key] = catalogue.StricterClass(keptBy[key], k.Class)
-		if pc, ok := shelf[b.Provider.Module].ConsumerDataOf(b.Provision); ok && pc.In != "" {
-			if _, own := shelf[b.Provider.Module].DataItem(pc.In); own {
-				item := b.Provider.Node + "/" + b.Provider.Module + "/" + pc.In
-				upgraded[item] = catalogue.StricterClass(upgraded[item], k.Class)
-			}
-		}
-	}
-	return upgraded, keptBy
-}
-
-// dataFindings is every condition the data on record raises now. A function of what is known, so the
-// incident's shape is tested without a mesh. upgraded is the class an item is held to where a consumer
-// of its module keeps data in it more precious than its own class says (`kept-by`), by its key.
-func dataFindings(records []inventory.DataRecord, peaks map[string]int64, shelf map[string]catalogue.Manifest,
-	copies []consumerCopy, upgraded map[string]string, now time.Time) []conditions.Observation {
-	var out []conditions.Observation
-	byItem := map[string][]inventory.DataRecord{}
-	arrays := map[string][]inventory.DataRecord{}
-	type shrunk struct {
-		machine, dataset, class string
-		size, peak              int64
-		items                   []string
-	}
-	shrunkDatasets := map[string]shrunk{}
-	for _, r := range records {
-		if r.DeletedAt != nil {
-			continue
-		}
-		class := catalogue.StricterClass(r.Class, upgraded[r.Key()])
-		r.Class = class
-		byItem[r.Module+"/"+r.Item] = append(byItem[r.Module+"/"+r.Item], r)
-		item, declared := shelf[r.Module].DataItem(r.Item)
-		id := keyOfItem(r.Machine, r.Module, r.Item)
-		if r.Retired() {
-			if now.Sub(*r.RetiredAt) > cleanupAfter {
-				out = append(out, conditions.Observation{Scope: conditions.ScopeMachine, ID: id, Token: "cleanup",
-					Kind: kindCleanupWaiting, Machine: r.Machine, Severity: conditions.Warning, Resolver: conditions.ResolverOperator,
-					Summary: fmt.Sprintf("%s of %s on %s (%s, %s) has been retired %d days — kept where it was since %s; "+
-						"`cleanup delete %s %s %s --why …` once a person has decided, or assign %s there again",
-						r.Item, r.Module, r.Machine, r.Class, sizeWords(r.Size), int(now.Sub(*r.RetiredAt).Hours()/24),
-						r.RetiredWhy, r.Machine, r.Module, r.Item, r.Module),
-					Said: "kept at " + orUnknownPath(r.Path)})
-			}
-			continue
-		}
-		if !catalogue.Watched(class) {
-			continue
-		}
-		severity := severityOf(class)
-		if r.Redundancy != nil {
-			where := r.Machine + "/" + r.Redundancy.Kind + ":" + r.Redundancy.Where
-			arrays[where] = append(arrays[where], r)
-		} else if declared && item.Redundancy != "" && r.MeasuredAt != nil && r.MeasureError == "" {
-			out = append(out, conditions.Observation{Scope: conditions.ScopeMachine, ID: id, Token: kindProtectionMissing,
-				Kind: kindProtectionMissing, Machine: r.Machine, Severity: severity, Resolver: conditions.ResolverOperator,
-				Summary: fmt.Sprintf("%s of %s on %s (%s) is said to be protected by the redundancy of the storage it is on, "+
-					"and it is on nothing the backup holder can read as redundant: it has no protection the mesh can see",
-					r.Item, r.Module, r.Machine, class),
-				Said: orUnknownPath(r.Path) + " is on no redundant storage the backup holder can read"})
-		}
-		if r.MeasureError != "" && strings.Contains(r.MeasureError, "does not exist") {
-			out = append(out, conditions.Observation{Scope: conditions.ScopeMachine, ID: id, Token: kindDataMissing,
-				Kind: kindDataMissing, Machine: r.Machine, Severity: severity, Resolver: conditions.ResolverOperator,
-				Summary: fmt.Sprintf("%s of %s on %s (%s) is gone: where it was declared, nothing exists any more", r.Item,
-					r.Module, r.Machine, class),
-				Said: orUnknownPath(r.Path) + " does not exist: " + firstLine(r.MeasureError)})
-		} else if peak, ok := peaks[r.Key()]; ok && r.Size != nil && inventory.Comparable(r.Precision) &&
-			*r.Size*2 < peak && peak-*r.Size >= shrinkFloor && inventory.Dataset(r.Precision) != "" {
-			// Several items on one dataset share its size: one condition for the dataset, as loud as the
-			// most precious item on it.
-			k := r.Machine + "/" + inventory.Dataset(r.Precision)
-			ds := shrunkDatasets[k]
-			ds.machine, ds.dataset, ds.size, ds.peak = r.Machine, inventory.Dataset(r.Precision), *r.Size, peak
-			ds.class = catalogue.StricterClass(ds.class, class)
-			ds.items = append(ds.items, r.Module+"/"+r.Item)
-			shrunkDatasets[k] = ds
-		} else if peak, ok := peaks[r.Key()]; ok && r.Size != nil && inventory.Comparable(r.Precision) &&
-			*r.Size*2 < peak && peak-*r.Size >= shrinkFloor {
-			out = append(out, conditions.Observation{Scope: conditions.ScopeMachine, ID: id, Token: kindDataShrank,
-				Kind: kindDataShrank, Machine: r.Machine, Severity: severity, Resolver: conditions.ResolverOperator,
-				Summary: fmt.Sprintf("%s of %s on %s (%s) shrank to %s from %s within %d days — more than half of what it "+
-					"held is gone. If that was meant, silence this with why; if not, `node-backup.restore` puts the last "+
-					"good copy beside it", r.Item, r.Module, r.Machine, class, sizeWords(r.Size), sizeWords(&peak),
-					int(shrinkWindow.Hours()/24))})
-		}
-		if !declared {
-			continue
-		}
-		if within := item.ActiveWithin(); within > 0 && r.LastWrite != nil && now.Sub(*r.LastWrite) > within {
-			out = append(out, conditions.Observation{Scope: conditions.ScopeMachine, ID: id, Token: kindDataQuiet,
-				Kind: kindDataQuiet, Machine: r.Machine, Severity: severity,
-				Summary: fmt.Sprintf("%s of %s on %s is written all the time, and has not been since %s (its bound is %s): "+
-					"whatever writes it has stopped", r.Item, r.Module, r.Machine, r.LastWrite.UTC().Format(time.RFC3339),
-					within)})
-		}
-		// A backup is required of what is irreplaceable and copied; of what is valuable it is the standard
-		// plan, said only where the machine was measured — where a holder is there to take it.
-		if item.BackedUp() && (class == catalogue.ClassIrreplaceable || r.MeasuredAt != nil) {
-			within := item.BackupWithin()
-			switch {
-			case r.LastBackup == nil && now.Sub(r.FirstSeen) > within:
-				out = append(out, conditions.Observation{Scope: conditions.ScopeMachine, ID: id, Token: kindBackupStale,
-					Kind: kindBackupStale, Machine: r.Machine, Severity: severity,
-					Summary: fmt.Sprintf("%s of %s on %s is %s and has no good backup on record, %s after it was first "+
-						"declared — is node-backup held there, and do its nights succeed? (`node-backup.backed-up`)",
-						r.Item, r.Module, r.Machine, class, now.Sub(r.FirstSeen).Round(time.Hour))})
-			case r.LastBackup != nil && now.Sub(*r.LastBackup) > within:
-				out = append(out, conditions.Observation{Scope: conditions.ScopeMachine, ID: id, Token: kindBackupStale,
-					Kind: kindBackupStale, Machine: r.Machine, Severity: severity,
-					Summary: fmt.Sprintf("%s of %s on %s is %s and its newest good backup is from %s, older than its bound "+
-						"of %s", r.Item, r.Module, r.Machine, class, r.LastBackup.UTC().Format(time.RFC3339), within)})
-			}
-		}
-	}
-	for _, k := range keysSorted(shrunkDatasets) {
-		ds := shrunkDatasets[k]
-		out = append(out, conditions.Observation{Scope: conditions.ScopeMachine,
-			ID: ds.machine + ".dataset." + strings.ReplaceAll(ds.dataset, "/", "-"), Token: kindDataShrank,
-			Kind: kindDataShrank, Machine: ds.machine, Severity: severityOf(ds.class), Resolver: conditions.ResolverOperator,
-			Summary: fmt.Sprintf("the dataset on %s that holds %s shrank to %s from %s within %d days — more than half of "+
-				"what it held is gone", ds.machine, strings.Join(ds.items, ", "), sizeWords(&ds.size), sizeWords(&ds.peak),
-				int(shrinkWindow.Hours()/24)),
-			Said: "the dataset " + ds.dataset})
-	}
-	// The redundant storage watched data is on: one condition per array, as loud as the most precious
-	// item on it — the array, not each item, is what degrades.
-	for _, where := range keysSorted(arrays) {
-		rs := arrays[where]
-		red := rs[0].Redundancy
-		if red.Healthy != nil && *red.Healthy {
-			continue
-		}
-		class, machine := catalogue.ClassValuable, rs[0].Machine
-		var names []string
-		for _, r := range rs {
-			class = catalogue.StricterClass(class, r.Class)
-			names = append(names, r.Module+"/"+r.Item)
-		}
-		state := "could not be read"
-		if red.Healthy != nil {
-			state = "is NOT healthy"
-		}
-		out = append(out, conditions.Observation{Scope: conditions.ScopeMachine,
-			ID:    machine + ".array." + strings.NewReplacer("/", "-", ":", "-").Replace(red.Kind+"-"+red.Where),
-			Token: kindArrayDegraded, Kind: kindArrayDegraded, Machine: machine, Severity: severityOf(class),
-			Resolver: conditions.ResolverOperator,
-			Summary: fmt.Sprintf("the %s storage on %s that protects %s %s", red.Kind, machine, strings.Join(names, ", "),
-				state),
-			Said: fmt.Sprintf("the %s storage %s %s: %s", red.Kind, red.Where, state, firstLine(red.Said))})
-	}
-	// The same item on several machines: a copy that is in use and far smaller than one kept elsewhere is
-	// an empty replacement. Only against a retired copy — a module running on two machines on purpose
-	// keeps two different sets of data.
-	for _, key := range keysSorted(byItem) {
-		rs := byItem[key]
-		for _, a := range rs {
-			if a.Retired() || a.Size == nil || !catalogue.Watched(a.Class) || !inventory.Comparable(a.Precision) {
-				continue
-			}
-			for _, o := range rs {
-				if o.Machine == a.Machine || !o.Retired() || o.Size == nil || !inventory.Comparable(o.Precision) ||
-					!replacedByLess(*a.Size, *o.Size) {
-					continue
-				}
-				out = append(out, conditions.Observation{Scope: conditions.ScopeMachine,
-					ID: keyOfItem(a.Machine, a.Module, a.Item), Token: kindEmptyReplacement, Kind: kindEmptyReplacement,
-					Machine: a.Machine, Also: []string{o.Machine}, Severity: severityOf(a.Class), Resolver: conditions.ResolverOperator,
-					Summary: fmt.Sprintf("%s of %s on %s holds %s, and the copy %s kept on %s holds %s: %s is running on "+
-						"an empty replacement of its data. Move the data, or assign it back where its data is",
-						a.Item, a.Module, a.Machine, sizeWords(a.Size), o.Module, o.Machine, sizeWords(o.Size), a.Module)})
-				break
-			}
-		}
-	}
-	out = append(out, consumerFindings(copies)...)
-	return out
-}
-
-// replacedByLess is whether a copy in use is an empty replacement of a copy kept elsewhere: less than
-// half of it, and at least shrinkFloor less.
-func replacedByLess(inUse, kept int64) bool {
-	return inUse*2 < kept && kept-inUse >= shrinkFloor
-}
-
-// consumerFindings is the same question of consumers' data at providers: one consumer, the same
-// provider module on two machines.
-func consumerFindings(copies []consumerCopy) []conditions.Observation {
-	by := map[string][]consumerCopy{}
-	for _, c := range copies {
-		k := c.Module + "/" + c.Consumer
-		by[k] = append(by[k], c)
-	}
-	var out []conditions.Observation
-	for _, k := range keysSorted(by) {
-		cs := by[k]
-		if len(cs) < 2 {
-			continue
-		}
-		found := false
-		for _, a := range cs {
-			if a.Retired || a.Size == nil {
-				continue
-			}
-			for _, o := range cs {
-				if o.Node == a.Node || o.Size == nil || !replacedByLess(*a.Size, *o.Size) {
-					continue
-				}
-				state := "active"
-				if o.Retired {
-					state = "retired"
-				}
-				out = append(out, conditions.Observation{Scope: conditions.ScopeProvider,
-					ID: a.Module + "." + a.Node + "." + a.Consumer, Token: kindEmptyReplacement, Kind: kindEmptyReplacement,
-					Machine: a.Node, Also: []string{o.Node}, Severity: severityOf(catalogue.StricterClass(a.Class, o.Class)),
-					Resolver: conditions.ResolverOperator,
-					Summary: fmt.Sprintf("%s's data at %s on %s holds %s, and its %s copy at %s on %s holds %s: the "+
-						"consumer is using an empty replacement of its data (issue 273's shape). Pin it back to %s, or move "+
-						"the data first", a.Consumer, a.Module, a.Node, sizeWords(a.Size), state, o.Module, o.Node,
-						sizeWords(o.Size), o.Node)})
-				found = true
-				break
-			}
-			if found {
-				break
-			}
-		}
-		if found {
-			continue
-		}
-		var active []consumerCopy
-		for _, c := range cs {
-			if !c.Retired {
-				active = append(active, c)
-			}
-		}
-		if len(active) >= 2 {
-			var where []string
-			var also []string
-			for _, c := range active {
-				where = append(where, c.Node+" ("+sizeWords(c.Size)+")")
-				also = append(also, c.Node)
-			}
-			out = append(out, conditions.Observation{Scope: conditions.ScopeProvider,
-				ID: active[0].Module + "." + active[0].Consumer, Token: kindDataHeldTwice, Kind: kindDataHeldTwice,
-				Machine: active[0].Node, Also: also[1:], Severity: conditions.Warning, Resolver: conditions.ResolverOperator,
-				Summary: fmt.Sprintf("%s has active data at %s on %d machines — %s — and only one is the one it uses",
-					active[0].Consumer, active[0].Module, len(active), strings.Join(where, ", "))})
-		}
-	}
-	return out
-}
-
-func keysSorted[V any](m map[string]V) []string {
-	out := make([]string, 0, len(m))
-	for k := range m {
-		out = append(out, k)
-	}
-	sort.Strings(out)
-	return out
-}
-
-// ---- the `data` verb ---------------------------------------------------------------------------
-
-const dataUsage = "data [--json] [--machine <name>] [--retired]"
-
-// dataRow is one item as `data` lists it.
-type dataRow struct {
-	Machine    string `json:"machine"`
-	Module     string `json:"module"`
-	Item       string `json:"item"`
-	Class      string `json:"class"`
-	Path       string `json:"path,omitempty"`
-	Protection string `json:"protection,omitempty"`
-	// Array is the redundant storage it is on and its state, where its holder could tell.
-	Array      string `json:"array,omitempty"`
-	Unmeasured string `json:"unmeasured,omitempty"`
-	// Precision says what the size is: exact, a dataset's whole size, partial, or none.
-	Precision  string `json:"precision,omitempty"`
-	SizeBytes  *int64 `json:"size-bytes,omitempty"`
-	LastWrite  string `json:"last-write,omitempty"`
-	MeasuredAt string `json:"measured-at,omitempty"`
-	LastBackup string `json:"last-backup,omitempty"`
-	BackupDue  string `json:"backup-within,omitempty"`
-	Retired    string `json:"retired,omitempty"`
-	RetiredWhy string `json:"retired-why,omitempty"`
-	Deleted    string `json:"deleted,omitempty"`
-}
-
-// dataCommand is `data`: every item every machine declares, or held retired, as the self-check last
-// found it.
-func dataCommand(ctx context.Context, args []string) error {
-	set := flag.NewFlagSet("data", flag.ContinueOnError)
-	asJSON := set.Bool("json", false, "as data")
-	only := set.String("machine", "", "one machine")
-	retiredOnly := set.Bool("retired", false, "only what is retired")
-	if rest, err := parseAround(set, args); err != nil {
-		return err
-	} else if len(rest) > 0 {
-		return errors.New(dataUsage)
-	}
-	open, err := openStores(ctx)
-	if err != nil {
-		return err
-	}
-	defer open.Close()
-	records, err := open.inventory.Data(ctx)
-	if err != nil {
-		return err
-	}
-	shelf, err := open.inventory.Catalogue(ctx)
-	if err != nil {
-		return err
-	}
-	rows := dataRows(records, shelf, *only, *retiredOnly)
-	if *asJSON {
-		return printJSON(map[string]any{"data": rows})
-	}
-	if len(rows) == 0 {
-		fmt.Println("no data on record: the self-check (D13) records what each machine declares on its next run")
-		return nil
-	}
-	for _, r := range rows {
-		state := ""
-		switch {
-		case r.Deleted != "":
-			state = "  DELETED " + r.Deleted
-		case r.Retired != "":
-			state = "  RETIRED " + r.Retired + " — " + r.RetiredWhy
-		}
-		fmt.Printf("%s %s/%s  %s  %s  %s  protected by %s%s\n", r.Machine, r.Module, r.Item, r.Class,
-			sizeWords(r.SizeBytes), orUnknownPath(r.Path), orNothingWord(r.Protection), state)
-		if r.Array != "" {
-			fmt.Printf("    on %s\n", r.Array)
-		}
-		if r.Precision != "" && r.Precision != "exact" {
-			fmt.Printf("    size: %s\n", r.Precision)
-		}
-		if r.Unmeasured != "" {
-			fmt.Printf("    not measured: %s\n", r.Unmeasured)
-		}
-		if r.Class == catalogue.ClassCache {
-			continue
-		}
-		fmt.Printf("    last write %s, measured %s, last backup %s%s\n", orNever(r.LastWrite), orNever(r.MeasuredAt),
-			orNever(r.LastBackup), within(r.BackupDue))
-	}
-	return nil
-}
-
-func dataRows(records []inventory.DataRecord, shelf map[string]catalogue.Manifest, only string, retiredOnly bool) []dataRow {
-	rows := []dataRow{}
-	stamp := func(t *time.Time) string {
-		if t == nil {
-			return ""
-		}
-		return t.UTC().Format(time.RFC3339)
-	}
-	for _, r := range records {
-		if only != "" && r.Machine != only {
-			continue
-		}
-		if retiredOnly && !r.Retired() {
-			continue
-		}
-		row := dataRow{Machine: r.Machine, Module: r.Module, Item: r.Item, Class: r.Class, Path: r.Path,
-			Protection: r.Protection, Unmeasured: r.MeasureError, Precision: r.Precision, SizeBytes: r.Size, LastWrite: stamp(r.LastWrite), MeasuredAt: stamp(r.MeasuredAt),
-			LastBackup: stamp(r.LastBackup), Retired: stamp(r.RetiredAt), RetiredWhy: r.RetiredWhy,
-			Deleted: stamp(r.DeletedAt)}
-		if it, ok := shelf[r.Module].DataItem(r.Item); ok && it.BackedUp() {
-			row.BackupDue = it.BackupWithin().String()
-		}
-		if red := r.Redundancy; red != nil {
-			state := "state unread"
-			if red.Healthy != nil && *red.Healthy {
-				state = "healthy"
-			} else if red.Healthy != nil {
-				state = "NOT HEALTHY"
-			}
-			row.Array = red.Kind + " " + red.Where + ", " + state
-		}
-		rows = append(rows, row)
-	}
-	return rows
-}
-
-func orNothingWord(s string) string {
-	if s == "" || s == "none" {
-		return "nothing"
-	}
-	return s
-}
-
-func orNever(s string) string {
-	if s == "" {
-		return "never"
-	}
-	return s
-}
-
-func within(s string) string {
-	if s == "" {
-		return " (not backed up)"
-	}
-	return " (bound " + s + ")"
-}
-
-// ---- cleanup of retired own data ---------------------------------------------------------------
-
-// The tools a node-backup holder serves to delete one retired item (novox/hq ADR 0233): the first
-// takes a last restore point of it, tagged as retired, and only then removes it — in the background,
-// because a large item outlasts any call — and the second says how that went. Module tools, not seat
-// verbs: only the controller's `cleanup delete` calls them, as it calls a provider's provisioner_delete.
-const (
-	ToolDeleteRetired  = "backup_delete_retired"
-	ToolDeletedOutcome = "backup_deleted"
-)
-
-// deletionWait is how long `cleanup delete` follows a deletion before handing it back to the person.
-var deletionWait = 8 * time.Minute
-
-// deletionPoll is how often it asks.
-var deletionPoll = 5 * time.Second
-
-// deletion is a holder's account of one deletion.
-type deletion struct {
-	Started  bool   `json:"started"`
-	Running  bool   `json:"running"`
-	Done     bool   `json:"done"`
-	OK       bool   `json:"ok"`
-	Snapshot string `json:"snapshot"`
-	Error    string `json:"error"`
-}
-
-// retiredData is every retired item on record, as `cleanup list` shows them.
-func retiredData(records []inventory.DataRecord, now time.Time) []retiredRow {
-	var out []retiredRow
-	for _, r := range records {
-		if !r.Retired() {
-			continue
-		}
-		out = append(out, retiredRow{Node: r.Machine, Module: r.Module, Consumer: r.Item, Kind: retiredDataKind,
-			RetiredAt: r.RetiredAt.UTC().Format(time.RFC3339), AgeDays: int(now.Sub(*r.RetiredAt).Hours() / 24),
-			SizeBytes: r.Size, Why: r.RetiredWhy, Path: r.Path, Class: r.Class})
-	}
-	return out
-}
-
-// retiredDataKind is what `cleanup list` calls a module's own retired data, beside a provider's consumer.
-const retiredDataKind = "own-data"
-
-// holderOn is the module holding node-backup on a machine.
-func holderOn(ctx context.Context, inv *inventory.Inventory, machine string) (string, error) {
-	held, err := inv.Holdings(ctx)
-	if err != nil {
-		return "", err
-	}
-	for _, h := range held {
-		if s, known := catalogue.SeatNamed(h.Claim); known && s.Name == catalogue.BackupSeat && h.Node == machine {
-			return h.Module, nil
-		}
-	}
-	return "", fmt.Errorf("nothing holds %s on %s, and it is the backup holder that deletes retired data there "+
-		"(after a last restore point)", catalogue.BackupSeat, machine)
-}
-
-// deleteRetiredData has a machine's backup holder delete one retired item: never one declared now, and
-// never one not retired. The holder takes a last restore point of it first, so the deletion can be
-// undone until a person forgets that restore point; the record says deleted only once the holder says
-// it is.
-func deleteRetiredData(ctx context.Context, conn *nats.Conn, open *stores, r inventory.DataRecord, f handActFlags) error {
-	inv := open.inventory
-	if !r.Retired() {
-		return fmt.Errorf("%s of %s on %s is not retired — only retired data is deleted. Nothing was done",
-			r.Item, r.Module, r.Machine)
-	}
-	if r.Path == "" {
-		return fmt.Errorf("%s of %s on %s was never measured, so where it is was never said; nothing was deleted",
-			r.Item, r.Module, r.Machine)
-	}
-	if plan, _, err := planFor(ctx, open, r.Machine); err == nil {
-		for _, m := range plan.Modules {
-			if _, still := m.DataItem(r.Item); still && m.Module == r.Module {
-				return fmt.Errorf("%s runs on %s again and declares %s: it is not retired any more. Nothing was done",
-					r.Module, r.Machine, r.Item)
-			}
-		}
-	}
-	holder, err := holderOn(ctx, inv, r.Machine)
-	if err != nil {
-		return err
-	}
-	f.record(ctx, "cleanup delete", []string{r.Machine, r.Module, r.Item})
-	args := map[string]any{"module": r.Module, "item": r.Item, "path": r.Path, "confirm": r.Item,
-		"why": strings.TrimSpace(*f.why), "by": link.Caller(), "via": link.ViaController}
-	ask := func(tool string) (deletion, error) {
-		var d deletion
-		answer, err := link.AskModuleToolOn(ctx, conn, holder, tool, r.Machine, args, 25*time.Second)
-		if err != nil {
-			return d, err
-		}
-		if answer.Error != "" {
-			return d, fmt.Errorf("%s on %s refused: %s", holder, r.Machine, answer.Error)
-		}
-		return d, unmarshalAnswer(answer, &d)
-	}
-	d, err := ask(ToolDeleteRetired)
-	if err != nil {
-		return err
-	}
-	for waited := time.Duration(0); !d.Done && waited < deletionWait; waited += deletionPoll {
-		select {
-		case <-ctx.Done():
-			return ctx.Err()
-		case <-time.After(deletionPoll):
-		}
-		if d, err = ask(ToolDeletedOutcome); err != nil {
-			return err
-		}
-	}
-	switch {
-	case !d.Done:
-		fmt.Printf("%s on %s is still taking the last restore point of %s and deleting it; `cleanup list` keeps "+
-			"showing it until the holder says it is done — the same `cleanup delete` again reads how it went\n",
-			holder, r.Machine, r.Path)
-		return nil
-	case !d.OK:
-		return fmt.Errorf("%s on %s did NOT delete %s: %s", holder, r.Machine, r.Path, d.Error)
-	}
-	if err := inv.MarkDataDeleted(ctx, r.Machine, r.Module, r.Item, link.Caller(), strings.TrimSpace(*f.why), time.Now()); err != nil {
-		return fmt.Errorf("%s deleted %s on %s, and it could not be recorded: %w", holder, r.Path, r.Machine, err)
-	}
-	fmt.Printf("%s on %s deleted %s of %s (%s, %s); its last restore point is %s, kept until a person forgets it\n",
-		holder, r.Machine, r.Item, r.Module, r.Path, sizeWords(r.Size), orNever(d.Snapshot))
-	return nil
-}
-
-// keptOnUnassign says, for an unassignment, the irreplaceable and valuable data each module leaves in its
-// own directories on the machine:
-// kept, and retired at the self-check's next run.
-func keptOnUnassign(ctx context.Context, inv *inventory.Inventory, machine string, modules []string) []string {
-	records, err := inv.Data(ctx)
-	if err != nil {
-		return []string{"what it leaves behind could not be read from the mesh's record: " + err.Error()}
-	}
-	var out []string
-	for _, r := range records {
-		if r.Machine != machine || r.DeletedAt != nil || !catalogue.Retires(r.Class) || !r.Owned {
-			continue
-		}
-		for _, m := range modules {
-			if r.Module == m {
-				out = append(out, fmt.Sprintf("%s's %s (%s, %s) stays where it is: it is %s, so it is retired, "+
-					"never removed — `cleanup list` shows it, `cleanup delete` alone removes it (novox/hq ADR 0233)",
-					r.Module, r.Item, orUnknownPath(r.Path), sizeWords(r.Size), r.Class))
-			}
-		}
-	}
-	return out
-}

cmd/mesh-controller/data_test.go

@@ -1,503 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"strings"
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/nats-io/nats.go"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/link"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-
-	"github.com/novox/mesh-controller/internal/testbus"
-)
-
-func bytesOf(n int64) *int64 { return &n }
-
-func when(t time.Time) *time.Time { return &t }
-
-func shelfFor(t *testing.T, manifests ...string) map[string]catalogue.Manifest {
-	t.Helper()
-	out := map[string]catalogue.Manifest{}
-	for _, raw := range manifests {
-		m, err := catalogue.ParseManifest([]byte(raw))
-		if err != nil {
-			t.Fatal(err)
-		}
-		out[m.Module] = m
-	}
-	return out
-}
-
-const houseManifest = `{"module":"house","version":"1",
-	"data":{"own":[{"id":"config","path":"${dir:config}","class":"irreplaceable","active":"1d"}]},
-	"resources":[{"id":"config","type":"directory","mode":"0700"}]}`
-
-func findingsByKind(obs []conditions.Observation) map[string]conditions.Observation {
-	out := map[string]conditions.Observation{}
-	for _, o := range linted(obs) {
-		out[o.Kind] = o
-	}
-	return out
-}
-
-// THE INCIDENT (issue 273), replayed against what D13 reads: five applications on the home server bound,
-// by one changed rule, to the store on the control node, which made each an empty database — while
-// their real databases, hundreds of megabytes each, sat on the home server's own store, by then retired
-// because the mesh no longer asked for them there. Each is an empty replacement, naming both machines
-// and the pin back: a warning for the store's consumers, whose data is valuable; urgent for one that says
-// its data there is irreplaceable (`kept-by`).
-func TestAnEmptyReplacementOfAConsumersDataIsSaid(t *testing.T) {
-	var copies []consumerCopy
-	for _, app := range []string{"mesh_home_board", "mesh_home_flows", "mesh_home_agents", "mesh_home_game", "mesh_home_cars"} {
-		copies = append(copies,
-			consumerCopy{Node: "home", Module: "postgres", Consumer: app, Size: bytesOf(400 << 20), Retired: true, Class: "valuable"},
-			consumerCopy{Node: "anchor", Module: "postgres", Consumer: app, Size: bytesOf(9 << 20), Class: "valuable"})
-	}
-	copies[1].Class = "irreplaceable" // the photo site's own database says so
-	got := linted(dataFindings(nil, nil, nil, copies, nil, time.Now()))
-	if len(got) != 5 {
-		t.Fatalf("%d findings for five empty replacements: %+v", len(got), got)
-	}
-	for i, o := range got {
-		want := conditions.Warning
-		if strings.Contains(o.ID, "mesh_home_board") {
-			want = conditions.Urgent
-		}
-		_ = i
-		if o.Kind != kindEmptyReplacement || o.Severity != want || o.Machine != "anchor" ||
-			len(o.Also) != 1 || o.Also[0] != "home" || !strings.Contains(o.Summary, "Pin it back to home") {
-			t.Errorf("%+v", o)
-		}
-	}
-
-	// While the old copy is still active (the first ten minutes), it is the same finding.
-	copies[0].Retired = false
-	copies[1].Class = "valuable"
-	if got := dataFindings(nil, nil, nil, copies[:2], nil, time.Now()); len(got) != 1 || got[0].Kind != kindEmptyReplacement {
-		t.Fatalf("with the old copy still active: %+v", got)
-	}
-}
-
-// A move a person made — the data moved first, then pinned — leaves a full copy at the new provider and
-// a retired one at the old: nothing to say here; `cleanup` covers the old one.
-func TestADeliberateMoveIsNoEmptyReplacement(t *testing.T) {
-	copies := []consumerCopy{
-		{Node: "home", Module: "postgres", Consumer: "mesh_home_board", Size: bytesOf(400 << 20), Retired: true},
-		{Node: "anchor", Module: "postgres", Consumer: "mesh_home_board", Size: bytesOf(402 << 20)},
-	}
-	if got := dataFindings(nil, nil, nil, copies, nil, time.Now()); len(got) != 0 {
-		t.Fatalf("a deliberate move raised %+v", got)
-	}
-	// Two small databases differing by less than the floor are not a finding either.
-	copies[0].Size, copies[1].Size = bytesOf(12<<20), bytesOf(8<<20)
-	if got := dataFindings(nil, nil, nil, copies, nil, time.Now()); len(got) != 0 {
-		t.Fatalf("noise between two empty databases raised %+v", got)
-	}
-}
-
-// Where a provider cannot say sizes, a consumer active at two providers is still said — as a warning,
-// since which one is empty cannot be told.
-func TestConsumerDataActiveTwiceWithoutSizesIsAWarning(t *testing.T) {
-	copies := []consumerCopy{
-		{Node: "home", Module: "minio", Consumer: "mesh_home_photos"},
-		{Node: "anchor", Module: "minio", Consumer: "mesh_home_photos"},
-	}
-	got := linted(dataFindings(nil, nil, nil, copies, nil, time.Now()))
-	if len(got) != 1 || got[0].Kind != kindDataHeldTwice || got[0].Severity != conditions.Warning {
-		t.Fatalf("%+v", got)
-	}
-}
-
-// The same incident for a module's own data: a module unassigned from one machine and assigned on
-// another starts over in an empty directory while its full one is kept, retired, where it was.
-func TestAnEmptyReplacementOfAModulesOwnDataIsUrgent(t *testing.T) {
-	now := time.Now()
-	retired := now.Add(-time.Hour)
-	records := []inventory.DataRecord{
-		{Machine: "home", Module: "house", Item: "config", Class: "irreplaceable", Path: "/var/lib/house/config",
-			Size: bytesOf(2 << 30), RetiredAt: &retired, FirstSeen: now.Add(-90 * 24 * time.Hour)},
-		{Machine: "anchor", Module: "house", Item: "config", Class: "irreplaceable", Path: "/var/lib/house/config",
-			Size: bytesOf(1 << 20), FirstSeen: now.Add(-time.Hour), LastWrite: when(now)},
-	}
-	got := findingsByKind(dataFindings(records, nil, shelfFor(t, houseManifest), nil, nil, now))
-	o, ok := got[kindEmptyReplacement]
-	if !ok || o.Severity != conditions.Urgent || o.Machine != "anchor" || o.Also[0] != "home" {
-		t.Fatalf("%+v", got)
-	}
-	// The same of a valuable item is a warning.
-	records[0].Class, records[1].Class = "valuable", "valuable"
-	if o := findingsByKind(dataFindings(records, nil, shelfFor(t, houseManifest), nil, nil, now))[kindEmptyReplacement]; o.Severity != conditions.Warning {
-		t.Fatalf("a valuable empty replacement: %+v", o)
-	}
-	records[0].Class, records[1].Class = "irreplaceable", "irreplaceable"
-	// Two machines running a module on purpose, both active, keep two sets of data: nothing to say.
-	records[0].RetiredAt = nil
-	if got := findingsByKind(dataFindings(records, nil, shelfFor(t, houseManifest), nil, nil, now)); got[kindEmptyReplacement].Kind != "" {
-		t.Fatalf("two active copies were read as a replacement: %+v", got)
-	}
-}
-
-// An irreplaceable item that lost more than half of its largest size in a week is urgent; a smaller loss,
-// or a loss under the floor, is not a finding.
-func TestAShrinkOfMoreThanHalfIsUrgent(t *testing.T) {
-	now := time.Now()
-	r := inventory.DataRecord{Machine: "home", Module: "house", Item: "config", Class: "irreplaceable",
-		Size: bytesOf(300 << 20), FirstSeen: now.Add(-30 * 24 * time.Hour), LastWrite: when(now), LastBackup: when(now)}
-	shelf := shelfFor(t, houseManifest)
-	o := findingsByKind(dataFindings([]inventory.DataRecord{r}, map[string]int64{r.Key(): 1 << 30}, shelf, nil, nil, now))[kindDataShrank]
-	if o.Severity != conditions.Urgent || !strings.Contains(o.Summary, "shrank") {
-		t.Fatalf("%+v", o)
-	}
-	for _, peak := range []int64{500 << 20, 20 << 20} {
-		if got := findingsByKind(dataFindings([]inventory.DataRecord{r}, map[string]int64{r.Key(): peak}, shelf, nil, nil, now)); got[kindDataShrank].Kind != "" {
-			t.Errorf("a peak of %d raised a shrink", peak)
-		}
-	}
-	small := r
-	small.Size = bytesOf(1 << 20)
-	if got := findingsByKind(dataFindings([]inventory.DataRecord{small}, map[string]int64{r.Key(): 10 << 20}, shelf, nil, nil, now)); got[kindDataShrank].Kind != "" {
-		t.Error("a loss under the floor raised a shrink")
-	}
-}
-
-// THE FALSE ALARM (issue 368), replayed through the store D13 reads: an agent's home moved from the
-// operator's own home (94.7 MB) to the agent account's fresh one (490 B), and `data-shrank` was raised
-// for data that was never lost. A moved item is read against its new path only, so nothing is raised —
-// and a genuine shrink at the new path, a week of history later, still is.
-func TestAMovedPathIsNoShrinkAndAShrinkThereStillIs(t *testing.T) {
-	inv := inventory.ForTest(t)
-	ctx := t.Context()
-	shelf := shelfFor(t, houseManifest)
-	declared := []inventory.DeclaredData{{Module: "house", Item: "config", Class: "irreplaceable", Owned: true}}
-	start := time.Now().Add(-6 * time.Hour)
-	measure := func(at time.Time, path string, size int64) []conditions.Observation {
-		t.Helper()
-		if _, err := inv.RecordData(ctx, "home", declared, map[string]map[string]inventory.Measurement{"house": {
-			"config": {Path: path, Size: bytesOf(size), MeasuredAt: when(at), LastWrite: when(at),
-				LastBackup: when(at)}}}, "", at); err != nil {
-			t.Fatal(err)
-		}
-		records, err := inv.Data(ctx)
-		if err != nil {
-			t.Fatal(err)
-		}
-		peaks, err := inv.DataPeaks(ctx, at.Add(-shrinkWindow))
-		if err != nil {
-			t.Fatal(err)
-		}
-		return dataFindings(records, peaks, shelf, nil, nil, at)
-	}
-	measure(start, "/home/operator/.claude", 94_700_000)
-	if got := findingsByKind(measure(start.Add(10*time.Minute), "/home/agent/.claude", 490)); got[kindDataShrank].Kind != "" {
-		t.Fatalf("a moved path raised a shrink: %+v", got[kindDataShrank])
-	}
-	measure(start.Add(2*time.Hour), "/home/agent/.claude", 300<<20)
-	got := findingsByKind(measure(start.Add(4*time.Hour), "/home/agent/.claude", 1<<20))[kindDataShrank]
-	if got.Severity != conditions.Urgent || !strings.Contains(got.Summary, "shrank") {
-		t.Fatalf("a genuine shrink at the new path was not raised: %+v", got)
-	}
-}
-
-// Data said to be written all the time and not written; data with no backup or an old one — urgent when
-// irreplaceable, a warning when valuable; and a new item given its bound before it is said.
-func TestQuietDataAndMissingBackupsAreSaidByClass(t *testing.T) {
-	now := time.Now()
-	shelf := shelfFor(t, houseManifest)
-	r := inventory.DataRecord{Machine: "home", Module: "house", Item: "config", Class: "irreplaceable",
-		Size: bytesOf(1 << 30), FirstSeen: now.Add(-10 * 24 * time.Hour), LastWrite: when(now.Add(-3 * 24 * time.Hour)),
-		LastBackup: when(now.Add(-72 * time.Hour))}
-	got := findingsByKind(dataFindings([]inventory.DataRecord{r}, nil, shelf, nil, nil, now))
-	if got[kindDataQuiet].Severity != conditions.Urgent || got[kindBackupStale].Severity != conditions.Urgent {
-		t.Fatalf("irreplaceable: %+v", got)
-	}
-	valuable := r
-	valuable.Class, valuable.MeasuredAt = "valuable", when(now) // measured: a holder is there to take its backup
-	if got := findingsByKind(dataFindings([]inventory.DataRecord{valuable}, nil, shelf, nil, nil, now)); got[kindDataQuiet].Severity != conditions.Warning ||
-		got[kindBackupStale].Severity != conditions.Warning {
-		t.Fatalf("valuable: %+v", got)
-	}
-	never := r
-	never.LastBackup = nil
-	if o := findingsByKind(dataFindings([]inventory.DataRecord{never}, nil, shelf, nil, nil, now))[kindBackupStale]; !strings.Contains(o.Summary, "no good backup") {
-		t.Fatalf("never backed up: %+v", o)
-	}
-	fresh := never
-	fresh.FirstSeen, fresh.LastWrite = now.Add(-time.Hour), when(now)
-	if got := dataFindings([]inventory.DataRecord{fresh}, nil, shelf, nil, nil, now); len(got) != 0 {
-		t.Fatalf("an item declared an hour ago, before its first night, raised %+v", got)
-	}
-}
-
-// An item retired more than thirty days waits for a person; less, it is only listed.
-func TestRetiredDataWaitingThirtyDaysIsSaid(t *testing.T) {
-	now := time.Now()
-	old, recent := now.Add(-31*24*time.Hour), now.Add(-2*24*time.Hour)
-	records := []inventory.DataRecord{
-		{Machine: "home", Module: "house", Item: "config", Class: "irreplaceable", Size: bytesOf(1 << 30), RetiredAt: &old},
-		{Machine: "home", Module: "attic", Item: "boxes", Class: "irreplaceable", Size: bytesOf(1 << 30), RetiredAt: &recent},
-	}
-	got := linted(dataFindings(records, nil, shelfFor(t, houseManifest), nil, nil, now))
-	if len(got) != 1 || got[0].Kind != kindCleanupWaiting || !strings.Contains(got[0].Summary, "cleanup delete home house config") {
-		t.Fatalf("%+v", got)
-	}
-	if rows := retiredData(records, now); len(rows) != 2 || rows[0].Kind != retiredDataKind {
-		t.Fatalf("cleanup list: %+v", rows)
-	}
-}
-
-// The holder's answer reads into measurements, by module and item.
-func TestTheHoldersAnswerIsRead(t *testing.T) {
-	raw := []byte(`[{"module":"postgres","runs":1,"paths":["/var/lib/mesh-store/dumps"],"lastNight":null,"restorePoints":3,
-		"data":[{"item":"store","class":"irreplaceable","path":"/var/lib/mesh-store","covered_by":"/var/lib/mesh-store/dumps",
-		"size_bytes":1073741824,"last_write":"2026-10-06T10:00:00Z","measured_at":"2026-10-06T10:05:00Z","last_backup":"2026-10-06T03:10:00Z"}]}]`)
-	got, err := readHolder(raw)
-	if err != nil {
-		t.Fatal(err)
-	}
-	m := got["postgres"]["store"]
-	if m.Path != "/var/lib/mesh-store" || m.Size == nil || *m.Size != 1<<30 || m.LastBackup == nil || m.MeasuredAt == nil {
-		t.Fatalf("%+v", m)
-	}
-	// An older holder, which says no data, reads as nothing measured rather than a failure.
-	if got, err := readHolder([]byte(`[{"module":"postgres","runs":1,"paths":[]}]`)); err != nil || len(got) != 0 {
-		t.Fatalf("%v, %v", got, err)
-	}
-}
-
-// fakeHolder answers node-backup's `backed-up` on one machine over a real bus, with what it is told it
-// measured.
-type fakeHolder struct {
-	mu      sync.Mutex
-	modules []map[string]any
-}
-
-func (f *fakeHolder) set(modules ...map[string]any) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.modules = modules
-}
-
-func (f *fakeHolder) serve(t *testing.T, conn *nats.Conn, node string) {
-	t.Helper()
-	sub, err := conn.Subscribe(link.NodeSeatToolSubject(catalogue.BackupSeat, "backed-up", node), func(m *nats.Msg) {
-		f.mu.Lock()
-		defer f.mu.Unlock()
-		body, _ := json.Marshal(map[string]any{"result": f.modules, "error": "", "node": node})
-		_ = m.Respond(body)
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(func() { _ = sub.Unsubscribe() })
-	if err := conn.Flush(); err != nil {
-		t.Fatal(err)
-	}
-}
-
-func measuredHouse(path string, size int64, at time.Time) map[string]any {
-	return map[string]any{"module": "house", "runs": 0, "paths": []string{path}, "data": []map[string]any{{
-		"item": "config", "class": "irreplaceable", "path": path, "covered_by": path, "size_bytes": size,
-		"last_write": at, "measured_at": at, "last_backup": at}}}
-}
-
-// UNASSIGNING A MODULE WITH IRREPLACEABLE DATA KEEPS THE DATA, and assigning it elsewhere onto an empty
-// directory is an empty replacement — through the real stores and a real bus. The unassignment says the
-// data stays; the self-check's next run retires it (kept, listed by cleanup), and when the module comes
-// up on another machine with an empty directory while the full one waits retired, that is urgent.
-func TestNatsUnassigningIrreplaceableDataRetiresItAndAnEmptyReplacementIsUrgent(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	inv := open.inventory
-	if _, err := inv.SeedSeats(ctx, catalogue.DefaultSeats()); err != nil {
-		t.Fatal(err)
-	}
-	register(t, open, catalogue.Manifest{Module: "keeper", Version: "1",
-		Claims: []catalogue.Claim{{Name: catalogue.BackupSeat, Scope: catalogue.ScopeNode, Serves: []string{"backed-up", "now", "restore"}}}})
-	house, err := catalogue.ParseManifest([]byte(houseManifest))
-	if err != nil {
-		t.Fatal(err)
-	}
-	register(t, open, house)
-	if _, err := assign(ctx, open, "laptop", "house"); err == nil {
-		t.Fatal("irreplaceable data was assigned to a machine with nothing to back it up")
-	}
-	for _, node := range []string{"laptop", "anchor"} {
-		if _, err := assign(ctx, open, node, "keeper"); err != nil {
-			t.Fatal(err)
-		}
-	}
-	if _, err := assign(ctx, open, "laptop", "house"); err != nil {
-		t.Fatal(err)
-	}
-	// Sent, and applied: a holder is asked only once it has been (novox/hq issue 275).
-	for _, node := range []string{"laptop", "anchor"} {
-		pushedAndApplied(t, open, node)
-	}
-
-	conn := onATestBus(t)
-	js, err := broker.Dial(testbus.URL(t))
-	if err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(js.Close)
-	laptop, anchor := &fakeHolder{}, &fakeHolder{}
-	laptop.serve(t, conn, "laptop")
-	anchor.serve(t, conn, "anchor")
-	now := time.Now()
-	heard := &watchdogs{last: &signalFacts{now: now, machines: []machineFacts{
-		{name: "laptop", lastHeard: now}, {name: "anchor", lastHeard: now}}}}
-	d := &doctor{open: open, js: js, watchdogs: heard}
-	var d13 probe
-	for _, p := range probeRegistry {
-		if p.ID == probeDataID {
-			d13 = p
-		}
-	}
-	run := func() []conditions.Observation {
-		t.Helper()
-		probing := context.WithValue(ctx, probeAsksKey{}, d13)
-		obs, err := probeData(probing, d)
-		if err != nil {
-			t.Fatal(err)
-		}
-		return obs
-	}
-
-	laptop.set(measuredHouse("/var/lib/house/config", 2<<30, now))
-	if obs := run(); len(obs) != 0 {
-		t.Fatalf("a measured, backed-up item raised %+v", obs)
-	}
-	r, err := inv.DataOf(ctx, "laptop", "house", "config")
-	if err != nil || r.Path != "/var/lib/house/config" || r.Size == nil || *r.Size != 2<<30 || r.LastBackup == nil {
-		t.Fatalf("what the holder measured was not kept: %+v, %v", r, err)
-	}
-
-	said, err := unassign(ctx, open, "laptop", "house")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !strings.Contains(said, "house's config (/var/lib/house/config, 2.0 GB) stays where it is") {
-		t.Fatalf("the unassignment does not say the data stays:\n%s", said)
-	}
-	laptop.set()
-	run()
-	r, err = inv.DataOf(ctx, "laptop", "house", "config")
-	if err != nil || !r.Retired() || r.Path != "/var/lib/house/config" {
-		t.Fatalf("unassigned, the irreplaceable item is not kept retired: %+v, %v", r, err)
-	}
-	records, _ := inv.Data(ctx)
-	if rows := retiredData(records, time.Now()); len(rows) != 1 || rows[0].Path != "/var/lib/house/config" {
-		t.Fatalf("cleanup list: %+v", rows)
-	}
-
-	// Assigned on the anchor, onto an empty directory.
-	if _, err := assign(ctx, open, "anchor", "house"); err != nil {
-		t.Fatal(err)
-	}
-	anchor.set(measuredHouse("/var/lib/house/config", 300<<10, time.Now()))
-	obs := findingsByKind(run())
-	o, ok := obs[kindEmptyReplacement]
-	if !ok || o.Severity != conditions.Urgent || o.Machine != "anchor" || o.Also[0] != "laptop" {
-		t.Fatalf("an empty replacement of a module's data was not urgent: %+v", obs)
-	}
-}
-
-// Data on redundant storage: the array it is on is watched, one condition per array as loud as the most
-// precious item on it; an item said to be on redundancy and found on plain storage is said; an item
-// whose path is gone is said.
-func TestTheArrayUnderDataIsWatched(t *testing.T) {
-	now := time.Now()
-	media := `{"module":"media","version":"1","accesses":[{"id":"films","mode":"read"},{"id":"shows","mode":"read"}],
-		"data":{"own":[{"id":"films","path":"${access:films}","class":"irreplaceable","redundancy":"an array, no room to copy"},
-			{"id":"shows","path":"${access:shows}","class":"irreplaceable","redundancy":"an array, no room to copy"}]}}`
-	shelf := shelfFor(t, media)
-	sick := false
-	on := func(item string, healthy *bool) inventory.DataRecord {
-		return inventory.DataRecord{Machine: "home", Module: "media", Item: item, Class: "irreplaceable", Owned: false,
-			Path: "/tank/" + item, Size: bytesOf(40 << 40), FirstSeen: now.Add(-24 * time.Hour), MeasuredAt: when(now),
-			Redundancy: &inventory.Redundancy{Kind: "zfs", Where: "tank", Healthy: healthy, Said: "pool 'tank' is DEGRADED"}}
-	}
-	got := linted(dataFindings([]inventory.DataRecord{on("films", &sick), on("shows", &sick)}, nil, shelf, nil, nil, now))
-	if len(got) != 1 || got[0].Kind != kindArrayDegraded || got[0].Severity != conditions.Urgent ||
-		!strings.Contains(got[0].Summary, "media/films, media/shows") {
-		t.Fatalf("%+v", got)
-	}
-	well := true
-	if got := dataFindings([]inventory.DataRecord{on("films", &well)}, nil, shelf, nil, nil, now); len(got) != 0 {
-		t.Fatalf("a healthy array raised %+v", got)
-	}
-	plain := on("films", nil)
-	plain.Redundancy = nil
-	if o := findingsByKind(dataFindings([]inventory.DataRecord{plain}, nil, shelf, nil, nil, now))[kindProtectionMissing]; o.Severity != conditions.Urgent {
-		t.Fatalf("redundancy said and not found: %+v", o)
-	}
-	gone := on("films", &well)
-	gone.MeasureError, gone.Size = "/tank/films does not exist", bytesOf(0)
-	if o := findingsByKind(dataFindings([]inventory.DataRecord{gone}, map[string]int64{gone.Key(): 40 << 40}, shelf, nil, nil, now))[kindDataMissing]; o.Severity != conditions.Urgent {
-		t.Fatalf("a vanished library: %+v", o)
-	}
-}
-
-// What a consumer keeps with its provider as irreplaceable holds the provider's item to that class:
-// the photo site's objects make the object store's data an urgent matter.
-func TestKeptByHoldsTheProvidersItemToTheConsumersClass(t *testing.T) {
-	objects := `{"module":"objects","version":"1","provides":[{"name":"s3-bucket","scope":"mesh"}],"grants":{"s3-bucket":"${dir:g}"},
-		"data":{"own":[{"id":"data","path":"${dir:data}","class":"valuable"}],"consumers":{"s3-bucket":{"class":"valuable","in":"data"}}},
-		"resources":[{"id":"g","type":"directory","mode":"0700"},{"id":"data","type":"directory","mode":"0700"}]}`
-	photos := `{"module":"photos","version":"1","requires":["s3-bucket"],"data":{"kept-by":{"s3-bucket":{"class":"irreplaceable"}}}}`
-	shelf := shelfFor(t, objects, photos)
-	bindings := []inventory.Binding{{Machine: "anchor", Consumer: "photos", Provision: "s3-bucket",
-		Provider: catalogue.Chosen{Node: "anchor", Module: "objects"}}}
-	upgraded, keptBy := keptByClasses(bindings, shelf)
-	if upgraded["anchor/objects/data"] != "irreplaceable" || keptBy["objects/mesh_anchor_photos"] != "irreplaceable" {
-		t.Fatalf("upgraded %v, kept by %v", upgraded, keptBy)
-	}
-	now := time.Now()
-	r := inventory.DataRecord{Machine: "anchor", Module: "objects", Item: "data", Class: "valuable", Owned: true,
-		Size: bytesOf(10 << 30), FirstSeen: now.Add(-10 * 24 * time.Hour), MeasuredAt: when(now), LastBackup: when(now.Add(-72 * time.Hour))}
-	if o := findingsByKind(dataFindings([]inventory.DataRecord{r}, nil, shelf, nil, upgraded, now))[kindBackupStale]; o.Severity != conditions.Urgent {
-		t.Fatalf("the photos' store without a backup: %+v", o)
-	}
-	if o := findingsByKind(dataFindings([]inventory.DataRecord{r}, nil, shelf, nil, nil, now))[kindBackupStale]; o.Severity != conditions.Warning {
-		t.Fatalf("a valuable store without a backup: %+v", o)
-	}
-}
-
-// Items measured from one dataset's counters share its size: a shrink of the dataset is one condition
-// naming every item on it, not one per item; and a partial walk's lower bound is never compared.
-func TestADatasetShrinksOnceAndAPartialSizeIsNeverCompared(t *testing.T) {
-	now := time.Now()
-	media := `{"module":"media","version":"1","accesses":[{"id":"films","mode":"read"},{"id":"shows","mode":"read"}],
-		"data":{"own":[{"id":"films","path":"${access:films}","class":"irreplaceable","redundancy":"an array","measure":"dataset"},
-			{"id":"shows","path":"${access:shows}","class":"irreplaceable","redundancy":"an array","measure":"dataset"}]}}`
-	shelf := shelfFor(t, media, houseManifest)
-	well := true
-	on := func(item string, size int64) inventory.DataRecord {
-		return inventory.DataRecord{Machine: "home", Module: "media", Item: item, Class: "irreplaceable",
-			Size: bytesOf(size), FirstSeen: now.Add(-24 * time.Hour), MeasuredAt: when(now),
-			Precision:  "dataset tank/media: its whole size",
-			Redundancy: &inventory.Redundancy{Kind: "zfs", Where: "tank", Healthy: &well}}
-	}
-	films, shows := on("films", 30<<40), on("shows", 30<<40)
-	peaks := map[string]int64{films.Key(): 90 << 40, shows.Key(): 90 << 40}
-	got := linted(dataFindings([]inventory.DataRecord{films, shows}, peaks, shelf, nil, nil, now))
-	if len(got) != 1 || got[0].Kind != kindDataShrank || got[0].Severity != conditions.Urgent ||
-		!strings.Contains(got[0].Summary, "media/films, media/shows") {
-		t.Fatalf("%+v", got)
-	}
-	partial := inventory.DataRecord{Machine: "home", Module: "house", Item: "config", Class: "irreplaceable",
-		Size: bytesOf(1 << 20), FirstSeen: now.Add(-24 * time.Hour), MeasuredAt: when(now), LastWrite: when(now),
-		LastBackup: when(now), Precision: "partial: measured partially"}
-	if got := dataFindings([]inventory.DataRecord{partial}, map[string]int64{partial.Key(): 1 << 30}, shelf, nil, nil, now); len(got) != 0 {
-		t.Fatalf("a partial size was compared: %+v", got)
-	}
-}

cmd/mesh-controller/deadletters.go

@@ -1,166 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"strconv"
-	"strings"
-
-	"github.com/nats-io/nats.go"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// What a consumer gave up on, answered by the serving controller (novox/hq issue 330).
-//
-// **In this process, on its own connection**: DEAD_LETTERS is read and changed on the bus, and the
-// serving controller is already on it. A verb run as a fresh process would open a connection of its own
-// for each call (novox/hq issue 327).
-
-// busHandles are the serving controller's connection and JetStream handle.
-type busHandles struct {
-	conn *nats.Conn
-	js   nats.JetStreamContext
-}
-
-// defaultDeadLetters is how many the list says when not asked for more.
-const defaultDeadLetters = 50
-
-// causeDeadLetter is the cause a delivery or drop gives when the caller gives none.
-const causeDeadLetter = "dead-letter"
-
-// deadLettersAnswer is what `dead-letters` answers: the list, one whole, or what came of delivering one
-// again or dropping it.
-func deadLettersAnswer(ctx context.Context, a *verbArguments) (any, error) {
-	serving := servingBus.Load()
-	if serving == nil {
-		return nil, errors.New("this controller is not serving, so it does not read DEAD_LETTERS: ask again, " +
-			"and the serving controller answers")
-	}
-	on := &busHandles{conn: serving.Conn(), js: serving.Context()}
-	// The shape first, and every argument it reads; one given beside it is refused before anything is
-	// done, as every verb refuses what it would pass over (novox/hq issue 244).
-	var deliver, drop, why, cause, idText, consumer, limit string
-	switch {
-	case a.given["deliver"] != "" || a.given["drop"] != "":
-		deliver, drop, why, cause = a.str("deliver"), a.str("drop"), a.str("why"), a.str("cause")
-	case a.given["id"] != "":
-		idText = a.str("id")
-	default:
-		consumer, limit = a.str("consumer"), a.str("limit")
-	}
-	if unused := a.unused(); len(unused) > 0 {
-		return nil, fmt.Errorf("dead-letters did not use %s together with %s, and an argument a verb would pass "+
-			"over is refused: nothing was done", quoteAll(unused), quoteAll(a.usedGiven()))
-	}
-	switch {
-	case deliver != "" && drop != "":
-		return nil, errors.New("dead-letters delivers one again or drops one, not both. Nothing was done")
-	case deliver != "" || drop != "":
-		act, text := "deliver", deliver
-		if drop != "" {
-			act, text = "drop", drop
-		}
-		if strings.TrimSpace(why) == "" {
-			return nil, fmt.Errorf("dead-letters %s is a hand act, and says why: why is required and recorded in "+
-				"the hand-act log (novox/hq to-be 45 §7). Nothing was done", act)
-		}
-		id, err := deadLetterID(text)
-		if err != nil {
-			return nil, err
-		}
-		return actOnDeadLetter(ctx, on, act, id, why, cause)
-	case idText != "":
-		id, err := deadLetterID(idText)
-		if err != nil {
-			return nil, err
-		}
-		return link.DeadLetterNamed(on.js, id)
-	}
-	most := defaultDeadLetters
-	if limit != "" {
-		n, err := strconv.Atoi(limit)
-		if err != nil || n <= 0 {
-			return nil, fmt.Errorf("limit is a number of dead letters, not %q", limit)
-		}
-		most = n
-	}
-	held, total, err := link.DeadLetters(on.js, consumer, most)
-	if err != nil {
-		return nil, err
-	}
-	answer := map[string]any{"dead_letters": held, "held": total,
-		"note": "newest first; with id, one whole; deliver or drop one with why"}
-	if total == 0 {
-		answer["note"] = "no consumer gave up on a message that is still kept"
-	}
-	return answer, nil
-}
-
-// deadLetterID is a dead letter's id as a caller wrote it.
-func deadLetterID(text string) (uint64, error) {
-	id, err := strconv.ParseUint(strings.TrimSpace(text), 10, 64)
-	if err != nil || id == 0 {
-		return 0, fmt.Errorf("a dead letter's id is its number in %s, as dead-letters lists it, not %q",
-			broker.DeadLettersStream, text)
-	}
-	return id, nil
-}
-
-// actOnDeadLetter delivers one again or drops it, recorded in the hand-act log before it is done. A log
-// that cannot be written is said, and the act still happens: the log is never the reason a person's act
-// is refused (handacts.go).
-func actOnDeadLetter(ctx context.Context, on *busHandles, act string, id uint64, why, cause string) (any, error) {
-	d, err := link.DeadLetterNamed(on.js, id)
-	if err != nil {
-		return nil, err
-	}
-	if act == "deliver" {
-		// Refused before it is recorded: an act that cannot be done is not an act.
-		if _, err := link.AgainTo(on.js, d); err != nil {
-			return nil, err
-		}
-	}
-	if cause == "" {
-		cause = causeDeadLetter
-	}
-	by := link.CallerIn(ctx)
-	if by == "" {
-		by = "a seat call whose caller the bus did not name"
-	}
-	answer := map[string]any{"dead_letter": d.ID, "consumer": d.Who, "subject": d.Subject}
-	recorded, logErr := link.RecordHandAct(ctx, on.conn, link.HandAct{Verb: "dead-letters " + act,
-		Args: []string{strconv.FormatUint(id, 10), d.Stream + "." + d.Consumer}, Why: why, Cause: cause,
-		Condition: conditions.Key(conditions.ScopeBus, d.Stream+"."+d.Consumer, link.AdvisoryMaxDeliveries),
-		By:        by + ", through the " + catalogue.ControllerSeatName + " seat"})
-	if logErr != nil {
-		answer["unrecorded"] = "the hand-act log could not be written, and the act was done all the same: " + logErr.Error()
-	} else {
-		answer["recorded"] = recorded.ID
-	}
-	switch act {
-	case "deliver":
-		delivered, to, err := link.DeliverAgain(on.js, id)
-		if err != nil {
-			return nil, err
-		}
-		answer["delivered_on"] = to
-		if delivered.Original != "" {
-			// What became of the ask in its seat's queue (novox/hq issue 334): removed, or left, and why.
-			answer["original"] = delivered.Original
-		}
-		answer["done"] = fmt.Sprintf("dead letter %d was delivered again to %s, and nobody else; it is no longer kept",
-			id, consumerWho(d.Stream, d.Consumer))
-	case "drop":
-		if _, err := link.DropDeadLetter(on.js, id); err != nil {
-			return nil, err
-		}
-		answer["done"] = fmt.Sprintf("dead letter %d, which %s gave up on, was dropped for good", id,
-			consumerWho(d.Stream, d.Consumer))
-	}
-	return answer, nil
-}

cmd/mesh-controller/deadletters_test.go

@@ -1,132 +0,0 @@
-package main
-
-import (
-	"context"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/link"
-	"github.com/novox/mesh-controller/internal/testbus"
-)
-
-// The serving controller's bus, with the mesh's streams, for the verb to read and act on.
-func servingDeadLetters(t *testing.T) *broker.JetStream {
-	t.Helper()
-	js, err := broker.Dial(testbus.URL(t))
-	if err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(js.Close)
-	if err := broker.AssertMeshStreams(js); err != nil {
-		t.Fatal(err)
-	}
-	if err := js.EnsureControllerBuckets(); err != nil {
-		t.Fatal(err)
-	}
-	before := servingBus.Load()
-	servingBus.Store(js)
-	t.Cleanup(func() { servingBus.Store(before) })
-	return js
-}
-
-func askDeadLetters(t *testing.T, args map[string]any) (any, error) {
-	t.Helper()
-	a, err := readArguments("dead-letters", args)
-	if err != nil {
-		return nil, err
-	}
-	return deadLettersAnswer(context.Background(), a)
-}
-
-func TestDeadLettersListsDropsAndRecordsWhy(t *testing.T) {
-	js := servingDeadLetters(t)
-	if _, err := js.Context().Publish("mesh.mod.gitea.event.pull.merged", []byte(`{"n":1}`)); err != nil {
-		t.Fatal(err)
-	}
-	d, err := link.KeepDeadLetter(js.Context(), []byte(`{"stream":"EVENTS","consumer":"media_sonarr","stream_seq":1,"deliveries":5}`))
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	answer, err := askDeadLetters(t, map[string]any{})
-	if err != nil {
-		t.Fatal(err)
-	}
-	listed := answer.(map[string]any)
-	if listed["held"] != 1 || len(listed["dead_letters"].([]link.DeadLetter)) != 1 {
-		t.Fatalf("listed %v", listed)
-	}
-
-	// Refused before anything is done: an act without why, an argument the shape passes over, both acts.
-	for _, args := range []map[string]any{
-		{"drop": "1"},
-		{"drop": "1", "why": "x", "limit": "3"},
-		{"drop": "1", "deliver": "1", "why": "x"},
-		{"why": "x"},
-		{"id": "nought"},
-	} {
-		if _, err := askDeadLetters(t, args); err == nil {
-			t.Errorf("%v was done", args)
-		}
-	}
-	if _, total, _ := link.DeadLetters(js.Context(), "", 0); total != 1 {
-		t.Fatalf("a refused call changed what is kept: %d left", total)
-	}
-
-	done, err := askDeadLetters(t, map[string]any{"drop": "1", "why": "the media server took the download in by hand"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if said := done.(map[string]any); said["recorded"] == nil || !strings.Contains(said["done"].(string), "dropped") {
-		t.Fatalf("answered %v", said)
-	}
-	acts, err := link.HandActs(context.Background(), js.Conn(), time.Now().Add(-time.Minute))
-	if err != nil || len(acts) != 1 || acts[0].Verb != "dead-letters drop" || acts[0].Cause != causeDeadLetter ||
-		!strings.Contains(acts[0].Condition, "media_sonarr") {
-		t.Fatalf("recorded %+v (%v)", acts, err)
-	}
-	if !personsDecision(acts[0]) {
-		t.Error("dropping a dead letter is counted as a repair, so S15 would want a healer for it")
-	}
-	if _, err := askDeadLetters(t, map[string]any{"id": "1"}); err == nil {
-		t.Errorf("dead letter %d is still answered after it was dropped", d.ID)
-	}
-}
-
-// Open while DEAD_LETTERS holds a message for the consumer, in words the operator reads in one pass:
-// what is held, and where to act.
-func TestAConsumersDeadLettersAreSaidUntilActedOn(t *testing.T) {
-	f := &signalFacts{now: time.Now(), deadLetters: map[string]int{"EVENTS.media_sonarr": 4, "EVENTS.controller": 1}}
-	found := watchDeadLetters(f)
-	if len(found) != 2 {
-		t.Fatalf("said %d conditions", len(found))
-	}
-	for _, o := range found {
-		if o.Kind != "max-deliveries" || o.Severity != conditions.Warning || o.Needs == "" {
-			t.Errorf("%+v", o)
-		}
-		if why, ok := conditions.PlainWords(conditions.Words{Headline: o.Headline, Needs: o.Needs,
-			Explanation: o.Explanation, Resolved: o.Resolved}, "media"); !ok {
-			t.Errorf("%q is not plain: %s", o.Headline, why)
-		}
-		if !strings.Contains(o.Needs, "mesh MCP server") {
-			t.Errorf("does not say where to act: %q", o.Needs)
-		}
-	}
-	sonarr := found[1]
-	if sonarr.ID != "EVENTS.media_sonarr" || sonarr.Machine != "media" ||
-		sonarr.Headline != "Sonarr on media could not handle 4 messages" ||
-		!strings.Contains(sonarr.Summary, "DEAD_LETTERS") {
-		t.Errorf("%+v", sonarr)
-	}
-	if found[0].Headline != "The controller could not handle a message" {
-		t.Errorf("%q", found[0].Headline)
-	}
-	// None held, none said: it clears when they are delivered again or dropped.
-	if left := watchDeadLetters(&signalFacts{now: time.Now()}); len(left) != 0 {
-		t.Fatalf("%v", left)
-	}
-}

cmd/mesh-controller/delivery_conditions.go

@@ -1,242 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"strings"
-	"time"
-
-	"github.com/nats-io/nats.go"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// A delivery held past its bound, said by the controller and healed by H2 from mesh-delivery's own table
-// (novox/hq ADR 0239 decision 9, to-be 47 Phase B). The conditions are the controller's, one owner: the
-// self-check reads the delivery owner's `stalled` (probe D14) and raises `delivery.<id>.stalled`; healer
-// H2 calls the owner's `close`, which takes only the transition the table names for that state, and only
-// the next observation says whether it worked (ADR 0231).
-
-// probeDeliveriesID is the probe that reads the delivery's owner.
-const probeDeliveriesID = "D14"
-
-// kindDeliveryStalled is what a delivery held past its bound raises: H2's kind, in the delivery scope.
-const kindDeliveryStalled = "stalled"
-
-// deliveryOwnerWithin is how long the owner is given to answer.
-var deliveryOwnerWithin = 10 * time.Second
-
-// stalledLine is one delivery past its bound, as mesh-delivery's `stalled` says it.
-type stalledLine struct {
-	ID string `json:"id"`
-	// Number is the pull request's, for a line of a head the forge never announced (novox/hq issue 347).
-	Number int    `json:"number,omitempty"`
-	State  string `json:"state"`
-	// Walk is the walk a line is about: a waiting walk no live delivery holds, or, asked with `walks`, each walk
-	// waiting for the owner's word and what holds it (novox/hq issues 362, 529).
-	Walk string `json:"walk,omitempty"`
-	// Waiting are the merge checks a line of the state `unanswered` waits on, as mesh-delivery says each:
-	// "mesh/merge-gate pending since <UTC time>", "mesh/repo-check never set" (novox/hq issue 438).
-	Waiting []string `json:"waiting,omitempty"`
-	// Checks are the same merge checks as data, which the controller words in the operator's own time (novox/hq
-	// issue 443): a time inside a finished sentence cannot be said again in another zone. A mesh-delivery from before
-	// says none, and Waiting is said as it reads.
-	Checks []waitingCheck `json:"checks,omitempty"`
-	// Held is the state of the delivery of a line of the state `unanswered`, ready or rejected, when one is held
-	// (novox/hq issues 441, 451): its check answered once, so a recheck is the step. Empty for a head with no
-	// delivery, and from a mesh-delivery that does not say it yet; the words are never read for it.
-	Held  string `json:"held,omitempty"`
-	For   string `json:"for"`
-	Bound string `json:"bound"`
-	H2    string `json:"h2"`
-	Says  string `json:"says"`
-}
-
-// waitingCheck is one merge check a stalled line waits on, as mesh-delivery gives it: its context, its state —
-// "pending", or "never-set" — and, for a pending one, since when in RFC 3339, empty when the forge did not say.
-type waitingCheck struct {
-	Context string `json:"context"`
-	State   string `json:"state"`
-	Since   string `json:"since,omitempty"`
-}
-
-// wordsNow is the time the words are said at, which says whether a time needs its day; a seam a test replaces.
-var wordsNow = time.Now
-
-// wordsZone is the zone a stalled line's times are said in: the controller's local zone, as every other time in its
-// messages. A seam a test replaces, so that no test writes time.Local, which every goroutine of the package reads.
-var wordsZone = func() *time.Location { return time.Local }
-
-// operatorsOnly is whether the table leaves H2 nothing to do for the line: the state is the operator's.
-func (l stalledLine) operatorsOnly() bool { return l.H2 == "" || strings.HasPrefix(l.H2, "none") }
-
-// askDeliveryOwner asks the holder of the mesh-delivery seat one of the verbs the controller is granted;
-// a seam a test replaces. The holder's own refusal is an error naming it.
-var askDeliveryOwner = func(ctx context.Context, conn *nats.Conn, verb string, args map[string]any) (json.RawMessage, error) {
-	granted := false
-	for _, v := range broker.VerbsTheControllerAsksTheDeliveryOwner {
-		granted = granted || v.Verb == verb
-	}
-	if !granted {
-		return nil, fmt.Errorf("the controller asks %s.%s, which its grant does not name", catalogue.DeliverySeat, verb)
-	}
-	if conn == nil {
-		return nil, errors.New("this controller is not on the bus")
-	}
-	answer, err := link.AskMeshSeatTool(ctx, conn, catalogue.DeliverySeat, verb, args, deliveryOwnerWithin)
-	if err != nil {
-		return nil, err
-	}
-	if answer.Error != "" {
-		return nil, fmt.Errorf("%s.%s refused: %s", catalogue.DeliverySeat, verb, answer.Error)
-	}
-	return unwrapToolResult(answer.Result), nil
-}
-
-// unwrapToolResult is a tool's answer whatever the runtime wrapped it in: the JSON itself, or the
-// protocol's content list holding it as text.
-func unwrapToolResult(raw json.RawMessage) json.RawMessage {
-	var wrapped struct {
-		Content []struct {
-			Text string `json:"text"`
-		} `json:"content"`
-	}
-	if json.Unmarshal(raw, &wrapped) == nil && len(wrapped.Content) > 0 && json.Valid([]byte(wrapped.Content[0].Text)) {
-		return json.RawMessage(wrapped.Content[0].Text)
-	}
-	return raw
-}
-
-// deliveriesStalled is what the owner says is held past its bound; nothing when no holder is on record,
-// or none answers (D3 says that one).
-func deliveriesStalled(ctx context.Context, conn *nats.Conn, held bool) ([]stalledLine, error) {
-	if !held {
-		return nil, nil
-	}
-	raw, err := askDeliveryOwner(ctx, conn, "stalled", map[string]any{})
-	if errors.Is(err, link.ErrNothingServes) {
-		return nil, nil // the holder not running is D3's holder-silent, said once there
-	}
-	if err != nil {
-		return nil, err
-	}
-	var lines []stalledLine
-	if err := json.Unmarshal(raw, &lines); err != nil {
-		return nil, fmt.Errorf("%s.stalled answered something unreadable: %w", catalogue.DeliverySeat, err)
-	}
-	return lines, nil
-}
-
-// walkWaits are, by walk, the lines mesh-delivery says of a walk waiting for its word: what holds it.
-type walkWaits map[string][]stalledLine
-
-// walksWaiting asks the delivery's owner what holds each walk waiting for its word (novox/hq issue 529): its
-// `stalled` asked with `walks`, so a line of `plans` names a held delivery, its reason and the verb that releases
-// it, instead of pointing at a hand start. Nil when no holder is on record or none answers: the line then reads as
-// before. An owner from before this answers its stalled lines, of which only those naming a walk are kept.
-func walksWaiting(ctx context.Context, conn *nats.Conn, held bool) walkWaits {
-	if !held {
-		return nil
-	}
-	raw, err := askDeliveryOwner(ctx, conn, "stalled", map[string]any{"walks": true})
-	if err != nil {
-		return nil
-	}
-	var lines []stalledLine
-	if json.Unmarshal(raw, &lines) != nil {
-		return nil
-	}
-	out := walkWaits{}
-	for _, l := range lines {
-		if l.Walk != "" {
-			out[l.Walk] = append(out[l.Walk], l)
-		}
-	}
-	return out
-}
-
-// stalledObservations are the conditions of what is stalled.
-func stalledObservations(lines []stalledLine) []conditions.Observation {
-	out := make([]conditions.Observation, 0, len(lines))
-	for _, l := range lines {
-		o := conditions.Observation{Scope: conditions.ScopeDelivery, ID: l.ID, Kind: kindDeliveryStalled,
-			Severity: conditions.Warning,
-			Summary: fmt.Sprintf("the delivery %s has been %s for %s, past its bound of %s (%s): healer H2 may %s — "+
-				"`mesh-delivery.show %s`", l.ID, l.State, l.For, l.Bound, l.Says, l.H2, l.ID),
-			Said: fmt.Sprintf("%s for %s", l.State, l.For)}
-		if l.operatorsOnly() {
-			o.Resolver = conditions.ResolverOperator
-		}
-		o.Headline, o.Explanation, o.Resolved, o.Needs, o.Actions = stalledWords(l, o)
-		out = append(out, o)
-	}
-	return out
-}
-
-// probeDeliveries is D14: every delivery held past its state's bound is said.
-func probeDeliveries(ctx context.Context, d *doctor) ([]conditions.Observation, error) {
-	entries, err := d.open.inventory.Catalogued(ctx)
-	if err != nil {
-		return nil, err
-	}
-	var conn *nats.Conn
-	if d.js != nil {
-		conn = d.js.Conn()
-	}
-	lines, err := deliveriesStalled(ctx, conn, deliverySeatHeld(entries))
-	if err != nil {
-		return nil, err
-	}
-	return stalledObservations(lines), nil
-}
-
-// --- H2, for a delivery ---------------------------------------------------------------------------------
-
-// connOf is the bus a healer asks over.
-func (h *healing) connOf() *nats.Conn {
-	if h.js == nil {
-		return nil
-	}
-	return h.js.Conn()
-}
-
-// appliesToAStalledDelivery is H2's for a delivery: the owner still lists it, with a transition the table
-// lets H2 take; never one whose state is the operator's.
-func appliesToAStalledDelivery(ctx context.Context, h *healing, c conditions.Condition) (string, bool, string, error) {
-	lines, err := deliveriesStalled(ctx, h.connOf(), true)
-	if err != nil {
-		return "", false, "", err
-	}
-	for _, l := range lines {
-		if l.ID != c.Subject.ID {
-			continue
-		}
-		if l.operatorsOnly() {
-			return "", false, "the delivery is " + l.State + ", a state the table leaves to the operator", nil
-		}
-		return c.Key, true, "", nil
-	}
-	return "", false, "the delivery's owner no longer lists it as stalled: its condition clears on the next look", nil
-}
-
-// repairDelivery is H2 for a delivery: the owner's `close`, which reads the walk again and takes only the
-// transition its table names. A refusal is no repair, said; the next observation says whether it worked.
-func repairDelivery(ctx context.Context, h *healing, c conditions.Condition) (string, string, error) {
-	raw, err := askDeliveryOwner(ctx, h.connOf(), "close", map[string]any{"id": c.Subject.ID, "why": c.Key})
-	if err != nil {
-		if errors.Is(err, link.ErrNothingServes) {
-			return "", "", err
-		}
-		return "closed nothing", oneLine(err.Error()), nil
-	}
-	var said string
-	if json.Unmarshal(raw, &said) != nil {
-		said = string(raw)
-	}
-	return "asked " + catalogue.DeliverySeat + " to close " + c.Subject.ID, said, nil
-}

cmd/mesh-controller/delivery_conditions_test.go

@@ -1,172 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"slices"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/nats-io/nats.go"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-	"github.com/novox/mesh-controller/internal/testbus"
-)
-
-// novox/hq ADR 0239 decision 9, to-be 47 Phase B: a delivery held past its bound is the controller's
-// condition, read from mesh-delivery's `stalled`; H2 takes the table's transition through its `close`.
-
-// ownerAnswers replaces the delivery owner with one that answers stalled with these lines and records
-// what close was asked.
-func ownerAnswers(t *testing.T, lines []stalledLine, closeErr error) *[]string {
-	t.Helper()
-	var closed []string
-	was := askDeliveryOwner
-	askDeliveryOwner = func(_ context.Context, _ *nats.Conn, verb string, args map[string]any) (json.RawMessage, error) {
-		switch verb {
-		case "stalled":
-			raw, _ := json.Marshal(lines)
-			return raw, nil
-		case "close":
-			closed = append(closed, args["id"].(string))
-			if closeErr != nil {
-				return nil, closeErr
-			}
-			return json.RawMessage(`"` + args["id"].(string) + `: delivering → delivered, as its walk's record says"`), nil
-		}
-		t.Fatalf("asked the owner %s", verb)
-		return nil, nil
-	}
-	t.Cleanup(func() { askDeliveryOwner = was })
-	return &closed
-}
-
-func holdTheDeliverySeat(t *testing.T, open *stores) {
-	t.Helper()
-	m := catalogue.Manifest{Module: "mesh-delivery", Version: "1",
-		Claims: []catalogue.Claim{{Name: catalogue.DeliverySeat, Scope: catalogue.ScopeMesh}}}
-	if err := open.inventory.RegisterModule(t.Context(), m, inventory.Source{Repository: "novox/mesh-catalog",
-		Path: "modules/mesh-delivery", BuiltFrom: "c0"}); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := open.inventory.Assign(t.Context(), "anchor", "mesh-delivery"); err != nil {
-		t.Fatal(err)
-	}
-}
-
-var twoStalled = []stalledLine{
-	{ID: "novox/app@aaaaaaaaaaaa", State: "delivering", For: "3h0m0s", Bound: "2h0m0s",
-		H2: "close, by done or superseded or failed, when the walk's record says so", Says: "its walk runs"},
-	{ID: "novox/lab@bbbbbbbbbbbb", State: "held", For: "49h0m0s", Bound: "24h0m0s",
-		H2: "none: the state is the operator's", Says: "it waits for the operator"},
-}
-
-func TestD14SaysEveryDeliveryHeldPastItsBound(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	ownerAnswers(t, twoStalled, nil)
-	d := &doctor{open: open}
-	got, err := probeDeliveries(ctx, d)
-	if err != nil || len(got) != 0 {
-		t.Fatalf("with no holder on record D14 said %+v %v", got, err)
-	}
-	holdTheDeliverySeat(t, open)
-	got, err = probeDeliveries(ctx, d)
-	if err != nil || len(got) != 2 {
-		t.Fatalf("D14 said %+v %v", got, err)
-	}
-	if got[0].Key() != "delivery.novox/app_aaaaaaaaaaaa.stalled" || got[0].Severity != conditions.Warning ||
-		got[0].Resolver != "" || !strings.Contains(got[0].Summary, "mesh-delivery.show novox/app@aaaaaaaaaaaa") {
-		t.Fatalf("the first is %+v", got[0])
-	}
-	if got[1].Resolver != conditions.ResolverOperator {
-		t.Fatalf("a held delivery is not the operator's: %+v", got[1])
-	}
-	// The holder not running is D3's to say, not D14's.
-	was := askDeliveryOwner
-	askDeliveryOwner = func(context.Context, *nats.Conn, string, map[string]any) (json.RawMessage, error) {
-		return nil, link.ErrNothingServes
-	}
-	defer func() { askDeliveryOwner = was }()
-	if got, err := probeDeliveries(ctx, d); err != nil || len(got) != 0 {
-		t.Fatalf("an owner that is down was said by D14: %+v %v", got, err)
-	}
-}
-
-// H2 for a delivery: close asked for the one whose state the table gives H2, never for the operator's; a
-// refusal is no repair.
-func TestH2ClosesAStalledDeliveryThroughItsOwnerOnly(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	h, told, _ := healingOn(t, open)
-	closed := ownerAnswers(t, twoStalled, nil)
-	for _, o := range stalledObservations(twoStalled) {
-		o.Source = probeDeliveriesID
-		if _, err := conditionsFrom.Observe(ctx, o); err != nil {
-			t.Fatal(err)
-		}
-	}
-	h.tick(ctx)
-	if !slices.Equal(*closed, []string{"novox/app@aaaaaaaaaaaa"}) {
-		t.Fatalf("close was asked for %v", *closed)
-	}
-	acts := told.said()
-	if len(acts) != 1 || acts[0].Healer != "H2" || acts[0].Condition != "delivery.novox/app_aaaaaaaaaaaa.stalled" {
-		t.Fatalf("said %+v", acts)
-	}
-	// A refusal: closed nothing, said so.
-	c, _, _ := conditionsFrom.Get(ctx, "delivery.novox/app_aaaaaaaaaaaa.stalled")
-	ownerAnswers(t, twoStalled, errors.New("mesh-delivery.close refused: still delivering"))
-	act, said, err := repairDelivery(ctx, h, c)
-	if err != nil || act != "closed nothing" || !strings.Contains(said, "still delivering") {
-		t.Fatalf("a refused close reads %q %q %v", act, said, err)
-	}
-}
-
-// The controller may ask the delivery's owner what D14 and H2 ask, on its flat subjects, and nothing else
-// of it; and over a real bus the answer — wrapped as the runtime wraps it — is read.
-func TestTheDeliveryOwnerIsAskedOverTheBus(t *testing.T) {
-	granted, err := broker.PermissionsFor(broker.Principal{Kind: broker.KindController, PasswordHash: "x"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	// And release and stop, which the operator's warrant chooses (novox/hq ADR 0259).
-	for _, verb := range []string{"stalled", "close", "release", "stop"} {
-		if !slices.Contains(granted.Publish, link.SeatToolSubject(catalogue.DeliverySeat, verb)) {
-			t.Errorf("the controller may not ask %s.%s", catalogue.DeliverySeat, verb)
-		}
-	}
-	if _, err := askDeliveryOwner(t.Context(), nil, "retire-history", nil); err == nil || !strings.Contains(err.Error(), "grant") {
-		t.Fatalf("a verb the grant does not name was asked: %v", err)
-	}
-	conn, err := nats.Connect(testbus.URL(t))
-	if err != nil {
-		t.Fatal(err)
-	}
-	defer conn.Close()
-	if _, err := deliveriesStalled(t.Context(), conn, true); err != nil {
-		t.Fatalf("an owner not running is D3's, not an error: %v", err)
-	}
-	lines, _ := json.Marshal(twoStalled)
-	wrapped, _ := json.Marshal(map[string]any{"content": []map[string]any{{"type": "text", "text": string(lines)}}})
-	sub, err := conn.Subscribe(link.SeatToolSubject(catalogue.DeliverySeat, "stalled"), func(m *nats.Msg) {
-		body, _ := json.Marshal(link.Answer{Result: wrapped})
-		_ = m.Respond(body)
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	defer func() { _ = sub.Unsubscribe() }()
-	ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
-	defer cancel()
-	got, err := deliveriesStalled(ctx, conn, true)
-	if err != nil || len(got) != 2 || got[0].ID != "novox/app@aaaaaaaaaaaa" {
-		t.Fatalf("over the bus: %+v %v", got, err)
-	}
-}

cmd/mesh-controller/delivery_order_test.go

@@ -1,152 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// recordingDelivery is a delivery that writes down what was done, in order, and fails where told.
-type recordingDelivery struct {
-	did        []string
-	grantErr   error
-	declareErr error
-}
-
-func (r *recordingDelivery) grant(_ context.Context, sending []readyNode) error {
-	for _, s := range sending {
-		r.did = append(r.did, "grant "+s.node)
-	}
-	return r.grantErr
-}
-
-func (r *recordingDelivery) declare(_ context.Context, s readyNode, _ []byte) (string, error) {
-	if r.declareErr != nil {
-		return "", r.declareErr
-	}
-	r.did = append(r.did, "declare "+s.node)
-	return "digest-" + s.node, nil
-}
-
-func ready(names ...string) []readyNode {
-	var out []readyNode
-	for _, n := range names {
-		out = append(out, readyNode{node: n, declared: sendable{Resources: []map[string]any{{"id": "x"}}}})
-	}
-	return out
-}
-
-// novox/hq issue 249: the grants that come with a module's new declarations are issued before any
-// machine is sent the code that uses them — except the machine holding the bus, whose declaration
-// carries the controller's own right to issue them, and goes first.
-func TestGrantsAreIssuedBeforeTheDeclarations(t *testing.T) {
-	d := &recordingDelivery{}
-	digests, err := deliver(t.Context(), d, "", ready("anchor", "laptop"))
-	if err != nil {
-		t.Fatal(err)
-	}
-	want := []string{"grant anchor", "grant laptop", "declare anchor", "declare laptop"}
-	if !reflect.DeepEqual(d.did, want) {
-		t.Fatalf("delivered in the order %v, wanted %v", d.did, want)
-	}
-	if digests["anchor"] != "digest-anchor" || digests["laptop"] != "digest-laptop" {
-		t.Fatalf("the digests sent were not answered: %v", digests)
-	}
-
-	held := &recordingDelivery{}
-	if _, err := deliver(t.Context(), held, "broker", ready("broker", "anchor")); err != nil {
-		t.Fatal(err)
-	}
-	want = []string{"declare broker", "grant broker", "grant anchor", "declare anchor"}
-	if !reflect.DeepEqual(held.did, want) {
-		t.Fatalf("with the bus's machine in the send: %v, wanted %v", held.did, want)
-	}
-}
-
-// A grant that cannot be issued holds back the machines it concerns and is an error the caller
-// retries on — never "until the next push" — and the bus's own machine is sent regardless, so the
-// grant that would let the controller issue memberships is never held behind them.
-func TestAGrantThatFailsHoldsBackWhatItConcerns(t *testing.T) {
-	// A failure naming no machine (the buckets): everything but the bus's machine.
-	d := &recordingDelivery{grantErr: errors.New("the bus refused the bucket")}
-	_, err := deliver(t.Context(), d, "broker", ready("broker", "anchor", "laptop"))
-	if err == nil || !errors.Is(err, errGrants) || !strings.Contains(err.Error(), "the bus refused the bucket") ||
-		!strings.Contains(err.Error(), "anchor, laptop not sent") {
-		t.Fatalf("a failed grant was not said as the send's failure: %v", err)
-	}
-	if want := []string{"declare broker", "grant broker", "grant anchor", "grant laptop"}; !reflect.DeepEqual(d.did, want) {
-		t.Fatalf("delivered %v, wanted the bus's machine alone", d.did)
-	}
-
-	// A membership that failed for one machine: that machine alone.
-	one := &recordingDelivery{grantErr: &grantsRefused{nodes: map[string]error{"laptop": errors.New("no")}}}
-	_, err = deliver(t.Context(), one, "", ready("anchor", "laptop"))
-	if !errors.Is(err, errGrants) || !strings.Contains(err.Error(), "laptop not sent") {
-		t.Fatalf("one machine's refused membership was not said: %v", err)
-	}
-	if want := []string{"grant anchor", "grant laptop", "declare anchor"}; !reflect.DeepEqual(one.did, want) {
-		t.Fatalf("delivered %v, wanted anchor sent and laptop held back", one.did)
-	}
-
-	// The announced upgrade that hit it is asked again.
-	if !errors.Is(askAgainOnGrants(err), link.ErrTryAgain) {
-		t.Fatal("an announcement whose send stopped at its grants is not asked again")
-	}
-	if other := errors.New("laptop could not be resolved"); errors.Is(askAgainOnGrants(other), link.ErrTryAgain) {
-		t.Fatal("any failure is asked again, not only a grant's")
-	}
-
-	// Nothing to send is nothing granted either.
-	none := &recordingDelivery{grantErr: errors.New("never asked")}
-	if _, err := deliver(t.Context(), none, "", nil); err != nil || len(none.did) != 0 {
-		t.Fatalf("an empty send granted or failed: %v %v", none.did, err)
-	}
-}
-
-// Whether the bus's machine goes first is read from the user list alone, by its digest.
-func TestTheBusMachineIsBehindByItsUserListAlone(t *testing.T) {
-	list := "users: [a, b]"
-	if userListBehind(list, digestOf([]byte(list))) {
-		t.Fatal("the list it was sent reads as behind")
-	}
-	if !userListBehind(list, digestOf([]byte("users: [a]"))) || !userListBehind(list, "") {
-		t.Fatal("a changed or never-sent list reads as current")
-	}
-	if userListBehind("", "") {
-		t.Fatal("a machine sent no list reads as behind")
-	}
-	// A list that could not be composed is behind: not known is never "not behind" (the review of hq issue 353).
-	if !listBehind("", errors.New("the plan cannot be worked out"), digestOf([]byte(list))) {
-		t.Fatal("a list nobody could compose reads as current")
-	}
-	if listBehind(list, nil, digestOf([]byte(list))) || !listBehind(list, nil, "") {
-		t.Fatal("listBehind does not read the digest as userListBehind does")
-	}
-}
-
-// The machine holding the bus goes first: its declaration carries the user list the new grants are
-// checked against. Among the machines it is moved to the front; not among them it is added only
-// when it is behind.
-func TestTheMachineHoldingTheBusIsSentFirst(t *testing.T) {
-	for _, c := range []struct {
-		what   string
-		names  []string
-		holder string
-		behind bool
-		want   []string
-	}{
-		{"among them", []string{"ace", "g14", "novox"}, "novox", false, []string{"novox", "ace", "g14"}},
-		{"not among them, behind", []string{"ace", "g14"}, "novox", true, []string{"novox", "ace", "g14"}},
-		{"not among them, current", []string{"ace", "g14"}, "novox", false, []string{"ace", "g14"}},
-		{"nothing holds the bus", []string{"ace", "g14"}, "", true, []string{"ace", "g14"}},
-		{"only it", []string{"novox"}, "novox", false, []string{"novox"}},
-	} {
-		if got := brokerFirst(c.names, c.holder, c.behind); !reflect.DeepEqual(got, c.want) {
-			t.Errorf("%s: sent in the order %v, wanted %v", c.what, got, c.want)
-		}
-	}
-}

cmd/mesh-controller/delivery_test.go

@@ -1,393 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"reflect"
-	"slices"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/nats-io/nats.go"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-	"github.com/novox/mesh-controller/internal/testbus"
-)
-
-// novox/hq ADR 0239 decision 4: a group's order, from the graph and the pull requests, the same on every
-// reading — the build agent before what it builds, the controller before a manifest that needs it, the
-// node-engine before the controller, a declared `after:` — and a contradiction named, never ordered.
-func TestAGroupIsOrderedByTheGraphAndWhatItsPullRequestsSay(t *testing.T) {
-	members := []orderMember{
-		{ID: "cat", Repository: "novox/mesh-catalog"},
-		{ID: "ctl", Repository: "novox/mesh-controller"},
-		{ID: "host", Repository: "novox/mesh-host"},
-		{ID: "agent", Repository: "novox/build-agent"},
-		{ID: "app", Repository: "novox/app", After: []string{"lab"}},
-		{ID: "lab", Repository: "novox/lab"},
-	}
-	reach := map[string]orderReach{
-		"cat":   {Moved: []string{"gitea"}, Manifests: []string{"modules/gitea/module.json"}},
-		"ctl":   {Moved: []string{"mesh-controller"}, Manifests: []string{"module.json"}},
-		"host":  {Moved: []string{"mesh-host"}, Manifests: []string{"module.json"}},
-		"agent": {Moved: []string{"build-agent"}},
-		"app":   {Moved: []string{"app"}},
-		"lab":   {Moved: []string{"lab"}},
-	}
-	edges := []inventory.Edge{{From: "app", To: "build-agent", Kind: inventory.EdgeBuiltBy},
-		{From: "gitea", To: "postgres", Kind: inventory.EdgeDeclared}}
-	got := orderOf(members, reach, edges)
-	if len(got.Cycle) > 0 {
-		t.Fatalf("a cycle where there is none: %v", got.Cycle)
-	}
-	// By repository among those with nothing before them: the build agent, the lab, then what waited on both.
-	want := []string{"agent", "lab", "app", "host", "ctl", "cat"}
-	if !reflect.DeepEqual(got.Order, want) {
-		t.Fatalf("ordered %v, wanted %v; pairs %+v", got.Order, want, got.Pairs)
-	}
-	why := map[string]string{}
-	for _, p := range got.Pairs {
-		why[p.Before+">"+p.After] = p.Why
-	}
-	for pair, reason := range map[string]string{"host>ctl": orderEngineFirst, "ctl>cat": orderVersionSkew,
-		"ctl>host": "", "agent>app": orderBuiltBy, "lab>app": orderDeclared} {
-		if why[pair] != reason {
-			t.Errorf("%s is ordered %q, wanted %q", pair, why[pair], reason)
-		}
-	}
-	// The same members in another order read the same.
-	shuffled := []orderMember{members[5], members[3], members[0], members[4], members[2], members[1]}
-	if again := orderOf(shuffled, reach, edges); !reflect.DeepEqual(again.Order, want) {
-		t.Fatalf("another reading ordered %v", again.Order)
-	}
-
-	// A declared order against an inferred one wins (novox/hq ADR 0249), and the pair says what it won over.
-	members[1].After = []string{"mesh-catalog"}
-	got = orderOf(members, reach, edges)
-	if len(got.Cycle) > 0 || len(got.Contradictions) > 0 {
-		t.Fatalf("a declared order did not win: cycle %v, %+v", got.Cycle, got.Contradictions)
-	}
-	if want := []string{"agent", "lab", "app", "cat", "host", "ctl"}; !reflect.DeepEqual(got.Order, want) {
-		t.Fatalf("ordered %v, wanted %v", got.Order, want)
-	}
-	if !slices.ContainsFunc(got.Pairs, func(p orderPair) bool {
-		return p.Before == "cat" && p.After == "ctl" && p.Why == orderDeclared && reflect.DeepEqual(p.Over, []string{orderVersionSkew})
-	}) || slices.ContainsFunc(got.Pairs, func(p orderPair) bool { return p.Before == "ctl" && p.After == "cat" }) {
-		t.Fatalf("the declared pair does not say it won over version skew: %+v", got.Pairs)
-	}
-
-	// Declared both ways is a contradiction no precedence resolves: a cycle, and how to end it.
-	members[0].After = []string{"novox/mesh-controller"}
-	got = orderOf(members, reach, edges)
-	if !reflect.DeepEqual(got.Cycle, []string{"cat", "ctl"}) || len(got.Contradictions) != 1 {
-		t.Fatalf("the cycle is %v, ordered %v, contradictions %+v", got.Cycle, got.Order, got.Contradictions)
-	}
-	if c := got.Contradictions[0]; !reflect.DeepEqual(c.Members, []string{"cat", "ctl"}) ||
-		!strings.Contains(c.Said, "remove one of the `after:` lines") {
-		t.Fatalf("the contradiction is said %+v", c)
-	}
-}
-
-// novox/hq ADR 0249: when two rules order one pair both ways, the rule of higher precedence wins and the
-// pair says what it overruled; rules of one rank both ways are refused, naming both and how to declare.
-func TestAnOrderRuleYieldsToAStrongerOne(t *testing.T) {
-	members := []orderMember{
-		{ID: "ctl", Repository: "novox/mesh-controller", Number: 7},
-		{ID: "host", Repository: "novox/mesh-host", Number: 9},
-	}
-	reach := map[string]orderReach{
-		"ctl":  {Moved: []string{"mesh-controller", "build-agent"}},
-		"host": {Moved: []string{"mesh-host"}},
-	}
-	builtBy := []inventory.Edge{{From: "mesh-host", To: "build-agent", Kind: inventory.EdgeBuiltBy}}
-
-	// Built by outranks engine before controller.
-	got := orderOf(members, reach, builtBy)
-	if !reflect.DeepEqual(got.Order, []string{"ctl", "host"}) || len(got.Cycle) > 0 {
-		t.Fatalf("ordered %v, cycle %v", got.Order, got.Cycle)
-	}
-	if want := []orderPair{{Before: "ctl", After: "host", Why: orderBuiltBy, Over: []string{orderEngineFirst}}}; !reflect.DeepEqual(got.Pairs, want) {
-		t.Fatalf("pairs %+v, wanted %+v", got.Pairs, want)
-	}
-
-	// A declared line outranks both.
-	members[0].After = []string{"mesh-host"}
-	got = orderOf(members, reach, builtBy)
-	if !reflect.DeepEqual(got.Order, []string{"host", "ctl"}) || len(got.Cycle) > 0 ||
-		!reflect.DeepEqual(got.Pairs[0].Over, []string{orderBuiltBy}) || got.Pairs[0].Why != orderDeclared {
-		t.Fatalf("a declared order did not win: %v %+v", got.Order, got.Pairs)
-	}
-
-	// Without the build agent, engine before controller stands alone.
-	members[0].After = nil
-	got = orderOf(members, map[string]orderReach{"ctl": {Moved: []string{"mesh-controller"}}, "host": reach["host"]}, builtBy)
-	if !reflect.DeepEqual(got.Order, []string{"host", "ctl"}) || got.Pairs[0].Why != orderEngineFirst || len(got.Pairs[0].Over) > 0 {
-		t.Fatalf("engine before controller alone: %v %+v", got.Order, got.Pairs)
-	}
-
-	// Built by both ways is one rank against itself: refused, both rules named, and how to declare.
-	both := append(builtBy, inventory.Edge{From: "build-agent", To: "mesh-host", Kind: inventory.EdgeStandsOn})
-	got = orderOf(members, reach, both)
-	if !reflect.DeepEqual(got.Cycle, []string{"ctl", "host"}) || len(got.Order) > 0 || len(got.Contradictions) != 1 {
-		t.Fatalf("a contradiction was ordered: %v, cycle %v, %+v", got.Order, got.Cycle, got.Contradictions)
-	}
-	said := got.Contradictions[0].Said
-	for _, w := range []string{"built by puts ctl first", "built by puts host first",
-		"`after: novox/mesh-controller` in novox/mesh-host#9's description", "`after: novox/mesh-host` in novox/mesh-controller#7's"} {
-		if !strings.Contains(said, w) {
-			t.Errorf("the contradiction does not say %q: %s", w, said)
-		}
-	}
-}
-
-// novox/hq ADR 0239 decision 8: a walk waits for the delivery's owner only while the seat has a holder on
-// record, and never one that moves a module on the controller's own path.
-func TestAWalkWaitsOnlyWhileTheDeliverySeatIsHeldAndNeverForTheCore(t *testing.T) {
-	holder := inventory.Entry{Manifest: catalogue.Manifest{Module: "mesh-delivery",
-		Claims: []catalogue.Claim{{Name: catalogue.DeliverySeat, Scope: catalogue.ScopeMesh}}}, On: []string{"anchor"}}
-	unassigned := holder
-	unassigned.On = nil
-	for _, c := range []struct {
-		entries []inventory.Entry
-		moved   []string
-		waits   bool
-	}{
-		{nil, []string{"gitea"}, false},
-		{[]inventory.Entry{unassigned}, []string{"gitea"}, false},
-		{[]inventory.Entry{holder}, []string{"gitea", "plex"}, true},
-		{[]inventory.Entry{holder}, []string{"gitea", "mesh-controller"}, false},
-		{[]inventory.Entry{holder}, []string{"mesh-host"}, false},
-		{[]inventory.Entry{holder}, []string{"node-tools"}, false},
-		{[]inventory.Entry{holder}, []string{"nats"}, false},
-		{[]inventory.Entry{holder}, []string{"mesh-delivery", "gitea"}, false},
-	} {
-		d := awaitsFor(c.entries, c.moved)
-		if (d != nil) != c.waits {
-			t.Errorf("held %v, moving %v: waits %v, wanted %v", len(c.entries) > 0 && len(c.entries[0].On) > 0,
-				c.moved, d != nil, c.waits)
-		}
-		if d != nil && d.Awaits != catalogue.DeliverySeat {
-			t.Errorf("waits for %q", d.Awaits)
-		}
-	}
-}
-
-// novox/hq ADR 0239: with mesh-delivery on record, a merge opens its walk and asks nothing until the
-// delivery's word; the word starts it; the core's own merge never waits; a person starts a waiting walk by
-// hand when the owner is down, and the owner's stop ends one as stopped.
-func TestAMergeWaitsForItsDeliverysWordAndThePersonsWordWorksWithoutIt(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	inv := open.inventory
-	asked := asksRecorded(t)
-	withConditionsInMemory(t)
-	for _, name := range []string{"app", "mesh-delivery"} {
-		m := catalogue.Manifest{Module: name, Version: "1"}
-		if name == "mesh-delivery" {
-			m.Claims = []catalogue.Claim{{Name: catalogue.DeliverySeat, Scope: catalogue.ScopeMesh}}
-		}
-		if err := inv.RegisterModule(ctx, m, inventory.Source{Repository: "novox/mesh-catalog", Seat: "git",
-			Path: "modules/" + name, Ref: "main", BuiltFrom: "c0", Head: "c0"}); err != nil {
-			t.Fatal(err)
-		}
-	}
-	merge := func(commit string, paths ...string) inventory.Plan {
-		t.Helper()
-		m := link.SourceMoved{Owner: "novox", Repo: "mesh-catalog", Base: "main", Commit: commit, Paths: paths,
-			ModuleDirs: []string{"modules/app", "modules/mesh-delivery"}, ModuleDirsSaid: true}
-		if err := (following{open: open}).SourceMoved(ctx, m); err != nil {
-			t.Fatal(err)
-		}
-		recent, err := inv.RecentPlans(ctx, 1)
-		if err != nil || len(recent) != 1 || recent[0].Commit != commit {
-			t.Fatalf("no plan for %s: %v %v", commit, recent, err)
-		}
-		return recent[0]
-	}
-
-	// finish ends a walk as done, so the next merge has nothing of it to take over.
-	finish := func(id string) {
-		t.Helper()
-		w, err := inv.PlanByID(ctx, id)
-		if err != nil {
-			t.Fatal(err)
-		}
-		w.State = inventory.PlanDone
-		if err := inv.SavePlan(ctx, &w); err != nil {
-			t.Fatal(err)
-		}
-	}
-
-	// No holder on record: the merge starts its walk, as before.
-	p := merge("c1aaaaaaaa", "modules/app/index.ts")
-	if p.Waiting() || len(*asked) != 1 {
-		t.Fatalf("with no holder on record the walk waited (%v) or asked %v", p.Waiting(), *asked)
-	}
-
-	// The holder on record: the next merge waits, asking nothing, and an advance asks nothing either. One walk
-	// is open at a time (novox/hq ADR 0276): the first ends before the next merge's batch is cut.
-	finish(p.ID)
-	if _, err := inv.Assign(ctx, "anchor", "mesh-delivery"); err != nil {
-		t.Fatal(err)
-	}
-	p = merge("c2bbbbbbbb", "modules/app/index.ts")
-	if !p.Waiting() || len(*asked) != 1 || !strings.Contains(p.Note, "plans go "+p.ID) {
-		t.Fatalf("the walk did not wait for its word: waiting %v, asked %v, note %q", p.Waiting(), *asked, p.Note)
-	}
-	advanceHeld(ctx, open)
-	if len(*asked) != 1 {
-		t.Fatalf("a waiting walk was advanced into asking: %v", *asked)
-	}
-	if line := planLine(p, p.Created); strings.Contains(line, "LATE") || !strings.Contains(line, "waits for") {
-		t.Errorf("a waiting walk reads %q", line)
-	}
-
-	// The delivery's word starts it.
-	if err := deliveryCommand(ctx, []string{"go", p.ID, "--by", catalogue.DeliverySeat, "--why", "its turn"}); err != nil {
-		t.Fatal(err)
-	}
-	if err := deliveryCommand(ctx, []string{"go", p.ID}); err == nil {
-		t.Fatal("a walk was let go twice")
-	}
-	advanceHeld(ctx, open)
-	if len(*asked) != 2 {
-		t.Fatalf("the word did not start the walk: %v", *asked)
-	}
-	got, err := inv.PlanByID(ctx, p.ID)
-	if err != nil || got.Delivery == nil || got.Delivery.By != catalogue.DeliverySeat || got.Delivery.Why != "its turn" {
-		t.Fatalf("the word was not kept: %+v %v", got.Delivery, err)
-	}
-
-	// The delivery's owner's own merge never waits for it. A walk that started is never taken over (novox/hq
-	// ADR 0276): the merge's batch is cut once it ended.
-	finish(p.ID)
-	p = merge("c3cccccccc", "modules/mesh-delivery/main.go")
-	if p.Waiting() || len(*asked) != 3 {
-		t.Fatalf("mesh-delivery's own walk waited for mesh-delivery: %v %v", p.Waiting(), *asked)
-	}
-
-	// The owner down: a person starts a waiting walk, with why.
-	finish(p.ID)
-	p = merge("c4dddddddd", "modules/app/index.ts")
-	if !p.Waiting() {
-		t.Fatal("the walk did not wait")
-	}
-	if err := plansCommand(ctx, []string{"go", p.ID}); err == nil || !strings.Contains(err.Error(), "--why") {
-		t.Fatalf("a walk was started by hand without why: %v", err)
-	}
-	if err := plansCommand(ctx, []string{"go", p.ID, "--why", "mesh-delivery is down"}); err != nil {
-		t.Fatal(err)
-	}
-	advanceHeld(ctx, open)
-	got, _ = inv.PlanByID(ctx, p.ID)
-	if got.Waiting() || !strings.HasPrefix(got.Delivery.By, "a person") || len(*asked) < 4 {
-		t.Fatalf("a person's word did not start the walk: %+v, asked %v", got.Delivery, *asked)
-	}
-
-	// The owner's stop: failed, said as stopped by it.
-	finish(p.ID)
-	p = merge("c5eeeeeeee", "modules/app/index.ts")
-	if err := deliveryCommand(ctx, []string{"stop", p.ID, "--why", "the operator stopped it", "--by",
-		"mesh-delivery for jochen"}); err != nil {
-		t.Fatal(err)
-	}
-	got, _ = inv.PlanByID(ctx, p.ID)
-	if got.State != inventory.PlanFailed || got.Delivery.Stopped != "mesh-delivery for jochen" ||
-		!strings.Contains(got.Note, "the operator stopped it") {
-		t.Fatalf("the stop was kept as %s %+v %q", got.State, got.Delivery, got.Note)
-	}
-
-	// Unassigned: the mesh is back on the controller's own path.
-	if err := inv.Unassign(ctx, "anchor", "mesh-delivery"); err != nil {
-		t.Fatal(err)
-	}
-	asks := len(*asked)
-	if p = merge("c6ffffffff", "modules/app/index.ts"); p.Waiting() || len(*asked) != asks+1 {
-		t.Fatalf("with the holder gone the walk waited: %v", p.Waiting())
-	}
-}
-
-// The verbs mesh-delivery asks with become the commands they name, and nothing a caller sends is passed over.
-func TestTheDeliveryVerbsComposeTheirCommands(t *testing.T) {
-	for _, c := range []struct {
-		verb string
-		args map[string]any
-		want []string
-	}{
-		{"deliver", map[string]any{"plan": "plan-1", "why": "its turn"},
-			[]string{"delivery", "go", "plan-1", "--by", "mesh-delivery", "--why", "its turn"}},
-		{"delivery-stop", map[string]any{"plan": "plan-1", "why": "w", "by": "jochen"},
-			[]string{"delivery", "stop", "plan-1", "--why", "w", "--by", "mesh-delivery for jochen"}},
-		{"delivery-walks", map[string]any{}, []string{"delivery", "walks"}},
-		{"delivery-walks", map[string]any{"plan": "plan-1"}, []string{"delivery", "walks", "--plan", "plan-1"}},
-		{"delivery-order", map[string]any{"members": "[]"}, []string{"delivery", "order", "--members", "[]"}},
-		{"delivery-check", map[string]any{"group": "feat/x", "members": "[]"},
-			[]string{"delivery", "check", "--group", "feat/x", "--members", "[]"}},
-		{"delivery-plan", map[string]any{"repository": "novox/a", "paths": "x", "head": "c0"},
-			[]string{"delivery", "plan", "--repository", "novox/a", "--paths", "x", "--head", "c0"}},
-		{"plans", map[string]any{"go": "plan-1", "why": "down"}, []string{"plans", "go", "plan-1", "--why", "down"}},
-	} {
-		got, err := argvFor(c.verb, c.args)
-		if err != nil || !reflect.DeepEqual(got, c.want) {
-			t.Errorf("%s %v → %v %v, wanted %v", c.verb, c.args, got, err, c.want)
-		}
-	}
-	if _, err := argvFor("deliver", map[string]any{}); err == nil {
-		t.Error("deliver without a walk was composed")
-	}
-	if _, err := argvFor("delivery-stop", map[string]any{"plan": "p"}); err == nil {
-		t.Error("a stop without why was composed")
-	}
-}
-
-// A verb runs as a command of its own: what it keeps of a walk is still said as plan-moved, on a bus of the
-// command's own, so the delivery's owner hears it at once and not only when it reads the walks back.
-func TestAWalkLetGoByAVerbIsSaidAsPlanMoved(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	url := testbus.URL(t)
-	js, err := broker.Dial(url)
-	if err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(js.Close)
-	if err := broker.AssertMeshStreams(js); err != nil {
-		t.Fatal(err)
-	}
-	before := handActConn
-	handActConn = js.Conn()
-	t.Cleanup(func() { handActConn = before })
-	heard := make(chan *nats.Msg, 4)
-	sub, err := js.Conn().ChanSubscribe(link.SeatEventSubject(link.MeshControllerSeat, link.KeyPlanMoved), heard)
-	if err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(func() { _ = sub.Unsubscribe() })
-
-	waiting := inventory.Plan{ID: "plan-waits", Repository: "novox/mesh-catalog", Branch: "main", Commit: "c7c7c7c7",
-		Created: time.Now().UTC(), State: inventory.PlanBuilding, Tiers: [][]string{{"app"}},
-		Modules:  map[string]*inventory.PlanModule{"app": {}},
-		Delivery: &inventory.PlanDelivery{Awaits: catalogue.DeliverySeat}}
-	if err := open.inventory.SavePlan(ctx, &waiting); err != nil {
-		t.Fatal(err)
-	}
-	if err := deliveryCommand(ctx, []string{"go", waiting.ID, "--why", "its turn"}); err != nil {
-		t.Fatal(err)
-	}
-	select {
-	case m := <-heard:
-		var said inventory.Plan
-		if err := json.Unmarshal(m.Data, &said); err != nil || said.ID != waiting.ID || said.Delivery == nil ||
-			said.Delivery.Go == nil {
-			t.Fatalf("plan-moved said %s (%v)", m.Data, err)
-		}
-	case <-time.After(5 * time.Second):
-		t.Fatal("a walk let go by a verb was not said")
-	}
-	if checkEvents != nil || inventory.PlanSaved != nil {
-		t.Fatal("the command's own bus was left in place")
-	}
-}

cmd/mesh-controller/dependents_test.go

@@ -1,52 +0,0 @@
-package main
-
-import (
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// A merge that rebuilds a base rebuilds what stands on it, through every layer, and nothing else
-// (novox/hq issue 186): the runtime image moving means every module built on it moves too, and a
-// module built on one of those moves as well.
-func TestAMergeOfABaseTakesWhatStandsOnItAlong(t *testing.T) {
-	entry := func(name string) inventory.Entry {
-		return inventory.Entry{Manifest: catalogue.Manifest{Module: name}}
-	}
-	entries := []inventory.Entry{entry("mesh-tools"), entry("shop"), entry("shop-plugin"), entry("postgres"), entry("unrelated")}
-	against := map[string][]string{
-		"shop":        {catalogue.ArtifactStoreScheme + "mesh-tools/runtime@sha256:a"},
-		"shop-plugin": {catalogue.ArtifactStoreScheme + "shop/runtime@sha256:b"},
-		"postgres":    {catalogue.ArtifactStoreScheme + "mesh-tools/runtime@sha256:a"},
-		"unrelated":   {catalogue.ArtifactStoreScheme + "alpine/base@sha256:c"},
-	}
-	got := dependentsOf([]inventory.Entry{entry("mesh-tools")}, entries, against)
-	var names []string
-	for _, e := range got {
-		names = append(names, e.Manifest.Module)
-	}
-	want := map[string]bool{"shop": true, "shop-plugin": true, "postgres": true}
-	if len(names) != len(want) {
-		t.Fatalf("rebuilt %v; wanted exactly the three that stand on the runtime, directly or through shop", names)
-	}
-	for _, n := range names {
-		if !want[n] {
-			t.Fatalf("%s was rebuilt and stands on nothing that moved (%v)", n, names)
-		}
-	}
-	// The dependents come in base order when the merge orders them: the runtime, then shop, then
-	// the plugin that stands on shop.
-	ordered := orderByBases(append([]inventory.Entry{entry("mesh-tools")}, got...), against)
-	pos := map[string]int{}
-	for i, e := range ordered {
-		pos[e.Manifest.Module] = i
-	}
-	if !(pos["mesh-tools"] < pos["shop"] && pos["shop"] < pos["shop-plugin"]) {
-		t.Fatalf("not in base order: %v", ordered)
-	}
-	// Nothing moved: nothing follows.
-	if more := dependentsOf(nil, entries, against); len(more) != 0 {
-		t.Fatalf("with nothing moved, %d module(s) were rebuilt", len(more))
-	}
-}

cmd/mesh-controller/desk_secret.go

@@ -1,333 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"strings"
-	"time"
-
-	"github.com/nats-io/nats.go"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/link"
-	"github.com/novox/mesh-controller/internal/secrets"
-)
-
-// A module's own secret given at the operator's desk (novox/hq ADR 0259 §10, ADR 0277).
-//
-//	mesh-controller secret ask <node> <module> <name> [--at <desk>]
-//
-// **The value never passes through whoever asked for it.** An agent, or the operator at the mesh MCP
-// server, calls `secret-ask` (or `give`) with the machine, the module, the secret's name and the desk — never
-// a value. The controller makes a sealing keypair for this one call, asks the desk's `node-launcher.secret` to
-// prompt the operator without showing what is typed, and is answered with what was typed **sealed to that
-// key**: no plaintext on the bus, in a runtime's log or in any call's record. It opens it here, seals it to the
-// module's machine exactly as `secret accept` does, and forgets it. What it answers says only that the
-// value was taken, or why not.
-//
-// **Bounded, and the prompt says who asked** (ADR 0277): one open prompt per secret and few an hour, read from
-// the store before the prompt opens (inventory.OpenSecretAsk), so an agent cannot keep a prompt in front of the
-// operator until they type. The prompt names the module, the secret, the machine and who asked — the caller as
-// the bus named it, never a word the caller chose — written by the desk's launcher from those names alone.
-//
-// **What remains** (ADR 0234's accepted residual risk): on an X11 desk any program of the operator's
-// account can read the keys as they are typed. And a program that calls the desk's prompt itself, with a
-// key of its own, is answered with what the operator typed into a prompt they did not ask for — as it could
-// draw a window of its own. The prompt says who asks and for what, so the operator types only into a
-// prompt they started.
-
-// deskPromptWithin is how long the prompt waits for the operator: below the runtime's thirty seconds for
-// one call, as the launcher's menu is.
-const deskPromptWithin = 25
-
-// deskGive is the desk path, its four reaches given so a test needs no store and no bus.
-type deskGive struct {
-	// declares refuses a module or a secret the mesh would refuse, before anybody is asked to type.
-	declares func(module, name string) error
-	// known refuses a machine the mesh does not know, before anybody is asked to type; nil knows every one
-	// (a test that does not look).
-	known func(machine string) error
-	// trusted says a module runs as an account of its own: its secret is never taken at a desk (below). Nil is
-	// never (a test that does not look).
-	trusted func(module string) (bool, error)
-	// ask asks one machine's node-launcher.secret and answers its result, or the holder's refusal.
-	ask func(machine string, args map[string]any) (json.RawMessage, error)
-	// accept seals the value as `secret accept` does, and says whether it lives until the module's start.
-	accept func(value string) (untilStart bool, err error)
-	// record writes the act in the hand-act log.
-	record func(link.HandAct) error
-	// announce raises the condition that says a module's own secret was given (secretGivenObservation), on
-	// every channel; nil announces nothing (a test that does not look).
-	announce func(node, module, name, how string) error
-	// askedBy is who asked, as the bus named the caller: said in the prompt and recorded.
-	askedBy string
-	// open records the ask and holds the bounds (one open per secret, few an hour), answering the record's id;
-	// nil keeps no record (a test that does not look). end closes it with how it ended.
-	open func(node, module, name, desk string) (int64, error)
-	end  func(id int64, outcome string) error
-}
-
-// askedByName is the caller as the prompt names it: the first clause of what the bus said, in the characters
-// a name has, at most 80 of them. The desk's launcher refuses anything else, so no words of the caller's own
-// reach the prompt.
-func askedByName(caller string) string {
-	first, _, _ := strings.Cut(caller, ",")
-	var b strings.Builder
-	for _, r := range strings.TrimSpace(first) {
-		switch {
-		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9', r == '.', r == '_', r == '/', r == '@',
-			r == '-', r == ' ':
-			b.WriteRune(r)
-		default:
-			b.WriteRune('-')
-		}
-		if b.Len() >= 80 {
-			break
-		}
-	}
-	name := strings.TrimSpace(b.String())
-	if name == "" || strings.HasPrefix(name, "-") {
-		return "an unnamed caller"
-	}
-	return name
-}
-
-// errNothingGiven is a prompt dismissed, or not answered in time: nothing changes.
-var errNothingGiven = errors.New("nothing was given")
-
-// give asks the desk for the value and seals it; it answers the words said to the caller.
-func (d deskGive) give(node, module, name, desk string) (string, error) {
-	for what, v := range map[string]string{"the machine": node, "the module": module, "the secret": name, "the desk": desk} {
-		if strings.TrimSpace(v) == "" {
-			return "", fmt.Errorf("%s is not named", what)
-		}
-	}
-	if d.known != nil {
-		for what, machine := range map[string]string{"the machine the secret is for": node, "the desk": desk} {
-			if err := d.known(machine); err != nil {
-				return "", fmt.Errorf("nobody was asked to type anything: %s, %s, is not a machine this mesh knows: %w",
-					what, machine, err)
-			}
-		}
-	}
-	if err := d.declares(module, name); err != nil {
-		return "", fmt.Errorf("nobody was asked to type anything: %w", err)
-	}
-	// **A trusted party's secret is not taken at a desk** (the confirmation review of 2026-10-09, N1-give). The
-	// prompt's answer comes back over the desk machine's bus, on a subject that machine's runtime answers — and
-	// on a desk machine agents run as the operator, who holds that runtime's credential. An agent could answer
-	// first, with a bot token of its own sealed to this call's key, and the channel the operator's answers are
-	// proven on would be the agent's. So the value of a module running as its own account is typed at the
-	// controller's terminal, where no bus carries it.
-	if d.trusted != nil {
-		trusted, err := d.trusted(module)
-		if err != nil {
-			return "", fmt.Errorf("nobody was asked to type anything: whether %s is a trusted party could not be read: %w", module, err)
-		}
-		if trusted {
-			return "", fmt.Errorf("nobody was asked to type anything: %s runs as an account of its own and proves the "+
-				"operator's answers, so its %s is given at the controller's terminal alone — there, run `mesh-controller "+
-				"secret accept %s %s %s` and type it at its prompt. A desk's prompt is answered over the desk machine's "+
-				"bus, where an agent may answer first (novox/hq ADR 0259 §10)", module, name, node, module, name)
-		}
-	}
-	// The bounds, read and kept before anybody is asked to type (novox/hq ADR 0277): one open prompt per secret,
-	// few an hour. How the ask ends is recorded whatever happens below.
-	outcome := "failed"
-	if d.open != nil {
-		id, err := d.open(node, module, name, desk)
-		if err != nil {
-			return "", fmt.Errorf("nobody was asked to type anything: %w", err)
-		}
-		defer func() {
-			if d.end != nil {
-				_ = d.end(id, outcome)
-			}
-		}()
-	}
-	public, private, err := secrets.Keypair()
-	if err != nil {
-		return "", fmt.Errorf("no key could be made to take the value: %w", err)
-	}
-	// By name, never by words: the holder writes the prompt from these, and says the controller asks, which
-	// the bus alone makes true (broker.ControllerOnly). Who asked is the bus's word on the caller, cut to a
-	// name's characters — never an argument of the call.
-	raw, err := d.ask(desk, map[string]any{
-		"module":          module,
-		"secret":          name,
-		"node":            node,
-		"asked_by":        askedByName(d.askedBy),
-		"seal_to":         public,
-		"timeout_seconds": deskPromptWithin,
-	})
-	if err != nil {
-		outcome = "refused"
-		return "", fmt.Errorf("the desk on %s could not be asked: %w", desk, err)
-	}
-	var answer struct {
-		Sealed    string `json:"sealed"`
-		Cancelled bool   `json:"cancelled"`
-		TimedOut  bool   `json:"timed_out"`
-	}
-	if err := json.Unmarshal(raw, &answer); err != nil {
-		return "", fmt.Errorf("the desk on %s answered something that is not the prompt's answer", desk)
-	}
-	switch {
-	case answer.TimedOut:
-		outcome = "timed-out"
-		return "", fmt.Errorf("%w: the prompt on %s was not answered within %d seconds", errNothingGiven, desk, deskPromptWithin)
-	case answer.Cancelled:
-		outcome = "dismissed"
-		return "", fmt.Errorf("%w: the prompt on %s was dismissed", errNothingGiven, desk)
-	case answer.Sealed == "":
-		return "", fmt.Errorf("the desk on %s answered no sealed value", desk)
-	}
-	opened, err := secrets.Open(private, answer.Sealed)
-	if err != nil {
-		// Never the value, never what failed to open: only that it was not sealed to this call.
-		return "", fmt.Errorf("the desk on %s answered a value not sealed to this call; nothing was taken", desk)
-	}
-	value := asSupplied(string(opened))
-	for i := range opened {
-		opened[i] = 0
-	}
-	if strings.TrimSpace(value) == "" {
-		outcome = "empty"
-		return "", fmt.Errorf("%w: the prompt on %s was answered empty", errNothingGiven, desk)
-	}
-	untilStart, err := d.accept(value)
-	value = ""
-	if err != nil {
-		return "", err
-	}
-	outcome = "given"
-	act := link.HandAct{Verb: "secret accept", Args: []string{node, module, name, "--at-desk", desk},
-		Why: fmt.Sprintf("the operator gave %s for %s on %s at the desk on %s, asked by %s", name, module, node, desk,
-			askedByName(d.askedBy)),
-		Cause: "given-at-the-desk"}
-	recorded := ""
-	if err := d.record(act); err != nil {
-		recorded = fmt.Sprintf("\n  this act could NOT be recorded in the hand-act log, and is done anyway: %v", err)
-	}
-	if d.announce != nil {
-		if err := d.announce(node, module, name, "at the desk on "+desk); err != nil {
-			recorded += fmt.Sprintf("\n  this change could NOT be announced on the operator's channels: %v", err)
-		}
-	}
-	words := fmt.Sprintf("%s on %s now holds %q, given at the desk on %s and sealed to %s; the mesh cannot read it "+
-		"back.\n  run `push %s` to send it", module, node, name, desk, node, node)
-	if untilStart {
-		words += fmt.Sprintf("\n  it lives until %s next starts well under the mesh, and is then replaced with a value "+
-			"the mesh makes (ADR 0228)", module)
-	}
-	return words + recorded, nil
-}
-
-// askAtDesk is `secret ask <node> <module> <name> [--at <machine>]`, and the terminal's `secret accept … --at-desk
-// <machine>`: the desk path, on this controller's stores and bus. The desk is the module's machine unless named.
-func askAtDesk(ctx context.Context, node, module, name, desk string) error {
-	if desk == "" {
-		desk = node
-	}
-	open, err := openStores(ctx)
-	if err != nil {
-		return err
-	}
-	defer open.Close()
-	d := deskGive{
-		askedBy: link.Caller(),
-		open: func(node, module, name, desk string) (int64, error) {
-			return open.inventory.OpenSecretAsk(ctx, node, module, name, askedByName(link.Caller()), desk)
-		},
-		end:      func(id int64, outcome string) error { return open.inventory.EndSecretAsk(ctx, id, outcome) },
-		declares: func(module, name string) error { return open.inventory.DeclaresOwnSecret(ctx, module, name) },
-		known: func(machine string) error {
-			_, err := open.inventory.NodeByName(ctx, machine)
-			return err
-		},
-		trusted: func(module string) (bool, error) { return open.inventory.RunsAsItsOwnAccount(ctx, module) },
-		ask: func(machine string, args map[string]any) (json.RawMessage, error) {
-			var result json.RawMessage
-			err := onTheBus(func(conn *nats.Conn) error {
-				answer, err := link.AskSeatTool(ctx, conn, "node-launcher", "secret", machine, args,
-					time.Duration(deskPromptWithin+5)*time.Second)
-				if err != nil {
-					return err
-				}
-				if answer.Error != "" {
-					return errors.New(answer.Error)
-				}
-				result = answer.Result
-				return nil
-			})
-			return result, err
-		},
-		accept: func(value string) (bool, error) {
-			return open.inventory.AcceptGivenSecret(ctx, node, module, name, value)
-		},
-		record: func(act link.HandAct) error {
-			return onTheBus(func(conn *nats.Conn) error {
-				_, err := link.RecordHandAct(ctx, conn, act)
-				return err
-			})
-		},
-		announce: func(node, module, name, how string) error { return announceSecretGiven(ctx, node, module, name, how) },
-	}
-	words, err := d.give(node, module, name, desk)
-	if err != nil {
-		return err
-	}
-	fmt.Println(words)
-	return nil
-}
-
-// kindSecretGiven is the condition every value given for a module's own secret raises (the review of 2026-10-09,
-// M4): on every channel, so a bot token changed by somebody else — a channel that now answers for them — is
-// heard of. It stays until the operator silences or clears it.
-const kindSecretGiven = "secret-given"
-
-// secretGivenObservation is that condition: which secret, of which module on which machine, how and when.
-// The summary, for whoever looks closer, names the secret and the time. The words the operator reads are
-// held to the plain rule (conditions.PlainWords): no clock time — the channel says when, in the operator's
-// time — and the secret's name said as words. Words that broke the rule were replaced by the keeper with
-// "needs a look … a problem it calls secret given" (hq issue 359), which told the operator nothing.
-func secretGivenObservation(node, module, name, how string, at time.Time) conditions.Observation {
-	key := node + "." + module + "." + name
-	where := module + " on " + node
-	// Within the bounds whatever the names' length: the module and machine, else the module, else the machine.
-	headline := "New secret given for " + where
-	for _, h := range []string{"New secret given for " + module, "New secret given on " + node} {
-		if len(headline) > conditions.HeadlineMax {
-			headline = h
-		}
-	}
-	resolved := "You saw that " + module + " was given a new secret"
-	if len(resolved) > conditions.HeadlineMax+20 {
-		resolved = "You saw that a new secret was given on " + node
-	}
-	return conditions.Observation{Scope: conditions.ScopeMachine, ID: key, Token: kindSecretGiven, Kind: kindSecretGiven,
-		Machine: node, Severity: conditions.Urgent, Source: kindSecretGiven,
-		Summary: fmt.Sprintf("%s of %s on %s was given %s at %s", name, module, node, how,
-			at.Local().Format("2006-01-02 15:04")),
-		Headline: headline,
-		Explanation: fmt.Sprintf("The secret %s of %s was given %s. If you gave it, nothing else is needed. If you "+
-			"did not, somebody else now holds what %s acts with.", secretNameWords(name), where, how, module),
-		Needs:    "silence this if you just gave it; if you did not, give it again yourself so that only you hold it.",
-		Resolved: resolved,
-		Actions:  []conditions.Action{conditions.SilenceAction(conditions.Key(conditions.ScopeMachine, key, kindSecretGiven))}}
-}
-
-// secretNameWords is a secret's name as the operator reads it: "telegram-token" is "telegram token".
-func secretNameWords(name string) string {
-	return strings.Join(strings.FieldsFunc(name, func(r rune) bool { return r == '-' || r == '_' || r == '.' }), " ")
-}
-
-// announceSecretGiven raises it on this controller's keeper.
-func announceSecretGiven(ctx context.Context, node, module, name, how string) error {
-	return withKeeper(ctx, func(k *conditions.Keeper) error {
-		_, err := k.Observe(ctx, secretGivenObservation(node, module, name, how, time.Now()))
-		return err
-	})
-}

cmd/mesh-controller/desk_secret_test.go

@@ -1,512 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/link"
-	"github.com/novox/mesh-controller/internal/secrets"
-)
-
-const typed = "123456789:AAEhBP0av28P4XFQnIuR-o-7Xnz1kkUzW3g"
-
-// aDesk is the desk path with a prompt the test answers as the operator would, and what it was asked kept.
-func aDesk(t *testing.T, answer func(args map[string]any) (json.RawMessage, error)) (deskGive, *[]string, *[]link.HandAct, *[]map[string]any) {
-	t.Helper()
-	var accepted []string
-	var acts []link.HandAct
-	var asked []map[string]any
-	return deskGive{
-		declares: func(module, name string) error {
-			if module != "telegram" || name != "telegram-token" {
-				return errors.New(module + " does not declare " + name + " as an own secret")
-			}
-			return nil
-		},
-		ask: func(machine string, args map[string]any) (json.RawMessage, error) {
-			asked = append(asked, args)
-			return answer(args)
-		},
-		accept: func(value string) (bool, error) { accepted = append(accepted, value); return false, nil },
-		record: func(a link.HandAct) error { acts = append(acts, a); return nil },
-	}, &accepted, &acts, &asked
-}
-
-func sealedTo(t *testing.T, value string) func(args map[string]any) (json.RawMessage, error) {
-	return func(args map[string]any) (json.RawMessage, error) {
-		sealed, err := secrets.Seal(args["seal_to"].(string), []byte(value+"\n"))
-		if err != nil {
-			t.Fatal(err)
-		}
-		raw, _ := json.Marshal(map[string]any{"sealed": sealed})
-		return raw, nil
-	}
-}
-
-// novox/hq ADR 0259 §10: the value typed at the desk is sealed as `secret accept` seals it, and is in no
-// answer, no prompt argument and no act recorded.
-func TestASecretGivenAtTheDeskIsSealedAndSaidNowhere(t *testing.T) {
-	d, accepted, acts, asked := aDesk(t, sealedTo(t, typed))
-	words, err := d.give("anchor", "telegram", "telegram-token", "laptop")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(*accepted) != 1 || (*accepted)[0] != typed {
-		t.Fatalf("the value sealed is not what was typed, its line ending taken off")
-	}
-	if len(*acts) != 1 || (*acts)[0].Verb != "secret accept" || (*acts)[0].Cause != "given-at-the-desk" ||
-		!strings.Contains((*acts)[0].Why, "at the desk on laptop") {
-		t.Errorf("the act: %+v", *acts)
-	}
-	raw, _ := json.Marshal(struct {
-		Words string
-		Acts  []link.HandAct
-		Asked []map[string]any
-	}{words, *acts, *asked})
-	if strings.Contains(string(raw), typed) || strings.Contains(string(raw), "AAEhBP0") {
-		t.Fatal("the value appears in what was said, asked or recorded")
-	}
-	if !strings.Contains(words, "push anchor") || !strings.Contains(words, "given at the desk on laptop") {
-		t.Errorf("%q", words)
-	}
-	if p := (*asked)[0]; p["seal_to"] == "" || p["timeout_seconds"] != deskPromptWithin {
-		t.Errorf("the prompt was asked %v", p)
-	}
-}
-
-func TestNothingIsAskedForASecretTheMeshWouldRefuse(t *testing.T) {
-	for _, c := range [][2]string{{"telegram", "chat-id"}, {"nobody", "telegram-token"}} {
-		d, accepted, _, asked := aDesk(t, sealedTo(t, typed))
-		if _, err := d.give("anchor", c[0], c[1], "laptop"); err == nil || !strings.Contains(err.Error(), "nobody was asked") {
-			t.Errorf("%v: %v", c, err)
-		}
-		if len(*asked) != 0 || len(*accepted) != 0 {
-			t.Errorf("%v: the operator was asked anyway", c)
-		}
-	}
-	d, _, _, _ := aDesk(t, sealedTo(t, typed))
-	if _, err := d.give("anchor", "telegram", "telegram-token", ""); err == nil {
-		t.Error("no desk was refused nowhere")
-	}
-}
-
-func TestADismissedEmptyLateOrForeignAnswerTakesNothing(t *testing.T) {
-	for want, answer := range map[string]func(map[string]any) (json.RawMessage, error){
-		"not answered within 25 seconds": func(map[string]any) (json.RawMessage, error) {
-			return json.RawMessage(`{"cancelled":true,"timed_out":true}`), nil
-		},
-		"was dismissed":  func(map[string]any) (json.RawMessage, error) { return json.RawMessage(`{"cancelled":true}`), nil },
-		"answered empty": sealedTo(t, "  "),
-		"not sealed to this call": func(map[string]any) (json.RawMessage, error) {
-			other, _, _ := secrets.Keypair()
-			sealed, _ := secrets.Seal(other, []byte(typed))
-			raw, _ := json.Marshal(map[string]any{"sealed": sealed})
-			return raw, nil
-		},
-		"could not be asked": func(map[string]any) (json.RawMessage, error) { return nil, errors.New("no session answers") },
-	} {
-		d, accepted, acts, _ := aDesk(t, answer)
-		_, err := d.give("anchor", "telegram", "telegram-token", "laptop")
-		if err == nil || !strings.Contains(err.Error(), want) || strings.Contains(err.Error(), typed) {
-			t.Errorf("want %q, got %v", want, err)
-		}
-		if len(*accepted) != 0 || len(*acts) != 0 {
-			t.Errorf("%s: something was taken or recorded", want)
-		}
-	}
-}
-
-func TestTheGiveVerbRunsTheDeskPathAndTheControllerMayAskTheDesk(t *testing.T) {
-	argv, err := argvFor("give", map[string]any{"node": "anchor", "module": "telegram", "secret": "telegram-token", "at": "laptop"})
-	if err != nil || strings.Join(argv, " ") != "secret ask anchor telegram telegram-token --at laptop" {
-		t.Fatalf("%v %v", argv, err)
-	}
-	if _, err := argvFor("give", map[string]any{"node": "anchor", "module": "telegram", "secret": "telegram-token"}); err == nil {
-		t.Error("give without a desk was taken")
-	}
-	// secret-ask is the same line, with the desk the module's machine unless named (novox/hq ADR 0277).
-	argv, err = argvFor("secret-ask", map[string]any{"node": "anchor", "module": "telegram", "secret": "telegram-token"})
-	if err != nil || strings.Join(argv, " ") != "secret ask anchor telegram telegram-token" {
-		t.Fatalf("%v %v", argv, err)
-	}
-	argv, err = argvFor("secret-ask", map[string]any{"node": "anchor", "module": "telegram", "secret": "telegram-token", "at": "laptop"})
-	if err != nil || strings.Join(argv, " ") != "secret ask anchor telegram telegram-token --at laptop" {
-		t.Fatalf("%v %v", argv, err)
-	}
-	perms, err := broker.PermissionsFor(broker.Principal{Kind: broker.KindController})
-	if err != nil {
-		t.Fatal(err)
-	}
-	found := false
-	for _, p := range perms.Publish {
-		found = found || p == "mesh.seat.node-launcher.tool.secret.*"
-	}
-	if !found {
-		t.Error("the controller may not ask the desk's prompt")
-	}
-}
-
-// The review of 2026-10-09 (M4): the desk's prompt says who asks in words the caller does not choose — the
-// controller, which the bus alone lets ask it — and what for, from names the controller checked; the prompt
-// carries no free text of the caller's.
-func TestThePromptIsAskedByNameNeverByWordsTheCallerChose(t *testing.T) {
-	d, _, _, asked := aDesk(t, sealedTo(t, typed))
-	if _, err := d.give("anchor", "telegram", "telegram-token", "laptop"); err != nil {
-		t.Fatal(err)
-	}
-	p := (*asked)[0]
-	if p["module"] != "telegram" || p["secret"] != "telegram-token" || p["node"] != "anchor" {
-		t.Errorf("the prompt was not asked by name: %v", p)
-	}
-	for _, free := range []string{"prompt", "message"} {
-		if _, there := p[free]; there {
-			t.Errorf("the prompt carries the caller's %s: %v", free, p)
-		}
-	}
-}
-
-// Every value given for a module's own secret is announced as a condition, on every channel (the review of
-// 2026-10-09, M4): a bot token changed by somebody else is a channel that now answers for them.
-func TestAValueGivenAtTheDeskIsAnnounced(t *testing.T) {
-	d, _, _, _ := aDesk(t, sealedTo(t, typed))
-	var said []string
-	d.announce = func(node, module, name, how string) error {
-		said = append(said, node+" "+module+" "+name+" "+how)
-		return nil
-	}
-	if _, err := d.give("anchor", "telegram", "telegram-token", "laptop"); err != nil {
-		t.Fatal(err)
-	}
-	if len(said) != 1 || !strings.Contains(said[0], "anchor telegram telegram-token") || !strings.Contains(said[0], "laptop") {
-		t.Fatalf("announced %v", said)
-	}
-	o := secretGivenObservation("anchor", "telegram", "telegram-token", "at the desk on laptop", time.Date(2026, 10, 9, 12, 3, 0, 0, time.UTC))
-	if o.Severity != conditions.Urgent || !strings.Contains(o.Explanation, "telegram token") ||
-		len(o.Actions) == 0 || o.Key() == "" {
-		t.Errorf("the announcement %+v", o)
-	}
-	if strings.Contains(o.Summary+o.Explanation+o.Said, typed) {
-		t.Error("the announcement carries the value")
-	}
-}
-
-// **The secret-given condition says itself in its own plain words** (hq issue 359): the words it carries pass
-// the plain rule, from the controller's terminal and from a desk, so the keeper keeps them — they once held a
-// clock time, and the operator read "Novox needs a look … a problem it calls secret given" instead. Its
-// severity and its answer stay: it is heard on every channel, and silenced by the operator.
-func TestTheSecretGivenConditionSaysItselfInPlainWords(t *testing.T) {
-	at := time.Date(2026, 10, 9, 23, 32, 0, 0, time.Local)
-	for _, how := range []string{"at the controller's terminal", "at the desk on laptop"} {
-		o := secretGivenObservation("anchor", "telegram", "telegram-token", how, at)
-		w := conditions.Words{Headline: o.Headline, Explanation: o.Explanation, Resolved: o.Resolved, Needs: o.Needs,
-			Actions: o.Actions}
-		if why, ok := conditions.PlainWords(w, o.Machine); !ok {
-			t.Fatalf("given %s, the words are not plain: %s", how, why)
-		}
-		k, _ := withConditionsInMemory(t)
-		c, err := k.Observe(t.Context(), o)
-		if err != nil {
-			t.Fatal(err)
-		}
-		if c.Headline != "New secret given for telegram on anchor" || c.Severity != conditions.Urgent ||
-			!strings.HasPrefix(c.Explanation, conditions.NeedsYou+" silence this") ||
-			!strings.Contains(c.Explanation, "telegram token of telegram on anchor was given "+how) ||
-			len(c.Actions) != 1 || c.Actions[0].Label != "Silence for a week" {
-			t.Errorf("given %s, the keeper said %q / %q (%s, %v)", how, c.Headline, c.Explanation, c.Severity, c.Actions)
-		}
-		if strings.Contains(c.Headline+c.Explanation+c.Resolved+c.Needs, typed) {
-			t.Error("the words carry the value")
-		}
-	}
-	// A long module name keeps the headline and the resolved line within their bounds.
-	for _, module := range []string{"a-module-with-a-rather-long-name-indeed",
-		"a-module-with-a-name-so-long-that-no-headline-could-ever-hold-it"} {
-		o := secretGivenObservation("anchor", module, "api-key", "at the controller's terminal", at)
-		if why, ok := conditions.PlainWords(conditions.Words{Headline: o.Headline, Explanation: o.Explanation,
-			Resolved: o.Resolved, Needs: o.Needs, Actions: o.Actions}, o.Machine); !ok {
-			t.Errorf("the module %s: %s", module, why)
-		}
-	}
-}
-
-// The bus lets the controller alone ask the desk's prompt (the review of 2026-10-09, M4): the runtime, which
-// carries every agent's calls, and a person granted every tool are denied it, however wide their grant.
-func TestOnlyTheControllerMayAskTheDesksPrompt(t *testing.T) {
-	for _, p := range []broker.Principal{
-		{Kind: broker.KindNodeTools, Node: "laptop"},
-		{Kind: broker.KindPerson, Module: "operator", Invokes: []string{"*"}},
-		{Kind: broker.KindModule, Node: "laptop", Module: "lab", Invokes: []string{"seat:node-launcher.secret"}},
-	} {
-		perms, err := broker.PermissionsFor(p)
-		if err != nil {
-			t.Fatal(err)
-		}
-		for _, subject := range []string{"mesh.seat.node-launcher.tool.secret.laptop", "mesh.seat.node-launcher.tool.secret",
-			"mesh.mod.rofi.tool.node-launcher.secret", "mesh.mod.rofi.tool.node-launcher.secret.laptop"} {
-			if broker.MayPublish(perms, subject) {
-				t.Errorf("%s may publish %s", p.Username(), subject)
-			}
-		}
-	}
-	perms, _ := broker.PermissionsFor(broker.Principal{Kind: broker.KindController})
-	if !broker.MayPublish(perms, "mesh.seat.node-launcher.tool.secret.laptop") {
-		t.Error("the controller may not ask the desk's prompt")
-	}
-}
-
-// A value for a secret comes from the terminal or the desk, never through a verb (the review of 2026-10-09,
-// M4): `secret accept` with a value, run for a verb, is refused before anything is read.
-func TestASecretValueIsNeverAcceptedThroughAVerb(t *testing.T) {
-	t.Setenv(verbVar, "mesh-controller.command")
-	for _, args := range [][]string{
-		{"accept", "anchor", "telegram", "telegram-token", "--from", "/dev/null"},
-		{"accept", "anchor", "app", "db", "--from", "/dev/null", "--provider", "store"},
-	} {
-		err := secretCommand(context.Background(), args)
-		if err == nil || !strings.Contains(err.Error(), "never through a verb") {
-			t.Errorf("%v: %v", args, err)
-		}
-	}
-}
-
-// The `give` and `secret-ask` verbs' own line passes the terminal-only rule of ADR 0266, and no `secret accept`
-// does: a value, a file, a provider or an extra word is still the terminal's alone (novox/hq ADR 0277).
-func TestOnlyTheGiveLinePassesTheTerminalRuleForSecrets(t *testing.T) {
-	for _, argv := range [][]string{
-		{"secret", "ask", "anchor", "telegram", "telegram-token", "--at", "laptop"},
-		{"secret", "ask", "anchor", "telegram", "telegram-token"},
-	} {
-		if err := terminalOnly(argv); err != nil {
-			t.Errorf("%v refused: %v", argv, err)
-		}
-	}
-	for _, argv := range [][]string{
-		{"secret", "accept", "anchor", "telegram", "telegram-token", "--at-desk", "laptop"},
-		{"secret", "ask", "anchor", "telegram", "telegram-token", "--from", "/tmp/x"},
-		{"secret", "ask", "anchor", "telegram", "telegram-token", "--at", "laptop", "--local"},
-		{"secret", "ask", "anchor", "telegram", "--at", "laptop"},
-		{"secret", "accept", "anchor", "telegram", "telegram-token"},
-		{"secret", "accept", "anchor", "telegram", "telegram-token", "--from", "/tmp/x"},
-		{"secret", "accept", "anchor", "telegram", "telegram-token", "--at-desk", "laptop", "--local"},
-		{"secret", "accept", "anchor", "telegram", "--provider", "--at-desk", "laptop"},
-		{"secret", "export", "anchor", "telegram", "telegram-token", "--at-desk", "laptop"},
-	} {
-		if err := terminalOnly(argv); err == nil {
-			t.Errorf("%v passed the terminal rule", argv)
-		}
-	}
-}
-
-// The confirmation review of 2026-10-09, N1-give: a desk's prompt is answered over the desk machine's bus, and
-// on a desk machine agents run as the operator, who holds its runtime's credential — so a trusted party's
-// secret (a module running as an account of its own: the Telegram bot's token) is never taken at a desk.
-// Refused before anybody is asked to type, whoever called, naming the terminal's line.
-func TestATrustedPartysSecretIsNeverTakenAtADesk(t *testing.T) {
-	d, accepted, acts, asked := aDesk(t, sealedTo(t, typed))
-	d.trusted = func(module string) (bool, error) { return module == "telegram", nil }
-	_, err := d.give("anchor", "telegram", "telegram-token", "laptop")
-	if err == nil || !strings.Contains(err.Error(), "controller's terminal alone") ||
-		!strings.Contains(err.Error(), "secret accept anchor telegram telegram-token") {
-		t.Fatalf("a trusted party's secret was taken at the desk, or refused without the line: %v", err)
-	}
-	if len(*asked)+len(*accepted)+len(*acts) != 0 {
-		t.Errorf("asked %v, accepted %d, recorded %v", *asked, len(*accepted), *acts)
-	}
-	d.trusted = func(string) (bool, error) { return false, errors.New("the store did not answer") }
-	if _, err := d.give("anchor", "telegram", "telegram-token", "laptop"); err == nil || len(*asked) != 0 {
-		t.Errorf("a module not known to be untrusted was asked at the desk: %v", err)
-	}
-}
-
-// And who may answer the desk's prompt at all: only the runtime of the machine it is asked on, carrying the
-// launcher that holds the seat there — never the controller, another machine's runtime, or a module's own
-// account (the confirmation review of 2026-10-09, N1-give).
-func TestOnlyTheDeskMachinesLauncherMayAnswerItsPrompt(t *testing.T) {
-	launcher := broker.Declared{Module: "rofi", Holds: []broker.Seat{{Name: "node-launcher", Scope: "node",
-		Serves: []string{"run", "secret"}}}}
-	subject := "mesh.seat.node-launcher.tool.secret.laptop"
-	for _, c := range []struct {
-		p       broker.Principal
-		answers bool
-	}{
-		{broker.Principal{Kind: broker.KindNodeTools, Node: "laptop", Module: broker.RuntimeModule, Carries: []broker.Declared{launcher}}, true},
-		{broker.Principal{Kind: broker.KindNodeTools, Node: "anchor", Module: broker.RuntimeModule, Carries: []broker.Declared{launcher}}, false},
-		{broker.Principal{Kind: broker.KindController}, false},
-		{broker.Principal{Kind: broker.KindModule, Node: "laptop", Module: "lab"}, false},
-		{broker.Principal{Kind: broker.KindNode, Node: "laptop"}, false},
-	} {
-		perms, err := broker.PermissionsFor(c.p)
-		if err != nil {
-			t.Fatal(err)
-		}
-		if got := broker.MaySubscribe(perms, subject); got != c.answers {
-			t.Errorf("%s may answer %s: %v, want %v", c.p.Username(), subject, got, c.answers)
-		}
-	}
-}
-
-// N1-give at the controller's terminal (the confirmation review of 2026-10-09): a trusted party's secret is
-// announced before it is kept, and not kept when the announcement fails; another module's is kept first and
-// a failed announcement is said, not undone.
-func TestATrustedPartysSecretGivenAtTheTerminalIsAnnouncedBeforeItIsKept(t *testing.T) {
-	var order []string
-	announce := func(fail bool) func() error {
-		return func() error {
-			order = append(order, "announce")
-			if fail {
-				return errors.New("no channel")
-			}
-			return nil
-		}
-	}
-	keep := func() (bool, error) { order = append(order, "keep"); return false, nil }
-
-	order = nil
-	if _, unannounced, err := keepGiven(true, announce(false), keep); err != nil || unannounced != nil ||
-		strings.Join(order, ",") != "announce,keep" {
-		t.Errorf("trusted: %v %v, order %v; want announced, then kept", unannounced, err, order)
-	}
-	order = nil
-	if _, _, err := keepGiven(true, announce(true), keep); err == nil || strings.Join(order, ",") != "announce" {
-		t.Errorf("trusted, announcement failed: %v, order %v; want refused and nothing kept", err, order)
-	}
-	order = nil
-	if _, unannounced, err := keepGiven(false, announce(true), keep); err != nil || unannounced == nil ||
-		strings.Join(order, ",") != "keep,announce" {
-		t.Errorf("not trusted: %v %v, order %v; want kept, then the failed announcement said", unannounced, err, order)
-	}
-	order = nil
-	failing := func() (bool, error) { order = append(order, "keep"); return false, errors.New("store away") }
-	if _, _, err := keepGiven(false, announce(false), failing); err == nil || strings.Join(order, ",") != "keep" {
-		t.Errorf("not trusted, keep failed: %v, order %v; want refused and nothing announced", err, order)
-	}
-}
-
-// A machine the mesh does not know, as the secret's or as the desk, is refused before anybody is asked to type.
-func TestAGiveNamingAMachineTheMeshDoesNotKnowAsksNobody(t *testing.T) {
-	for _, unknown := range []string{"elsewhere", "nodesk"} {
-		d, accepted, acts, asked := aDesk(t, func(map[string]any) (json.RawMessage, error) {
-			t.Fatal("the desk was asked")
-			return nil, nil
-		})
-		d.known = func(machine string) error {
-			if machine == unknown {
-				return errors.New("no node " + machine)
-			}
-			return nil
-		}
-		node, desk := "anchor", "laptop"
-		if unknown == "elsewhere" {
-			node = unknown
-		} else {
-			desk = unknown
-		}
-		_, err := d.give(node, "telegram", "telegram-token", desk)
-		if err == nil || !strings.Contains(err.Error(), "nobody was asked") || !strings.Contains(err.Error(), unknown) {
-			t.Errorf("%s: %v", unknown, err)
-		}
-		if len(*accepted)+len(*acts)+len(*asked) != 0 {
-			t.Errorf("%s: something happened: %v %v %v", unknown, *accepted, *acts, *asked)
-		}
-	}
-}
-
-// novox/hq ADR 0277: the prompt names who asked — the controller's word on the bus's caller, cut to a name's
-// characters — and never a word the caller chose: there is no argument for it.
-func TestThePromptNamesWhoAskedFromTheBussWordAlone(t *testing.T) {
-	d, _, acts, asked := aDesk(t, sealedTo(t, typed))
-	d.askedBy = "g14/claude-code, through the mesh-controller seat"
-	if _, err := d.give("anchor", "telegram", "telegram-token", "laptop"); err != nil {
-		t.Fatal(err)
-	}
-	if got := (*asked)[0]["asked_by"]; got != "g14/claude-code" {
-		t.Errorf("asked_by %q", got)
-	}
-	if len(*acts) != 1 || !strings.Contains((*acts)[0].Why, "asked by g14/claude-code") {
-		t.Errorf("the record: %+v", *acts)
-	}
-	for in, want := range map[string]string{
-		"jochen at a shell on novox":         "jochen at a shell on novox",
-		"laptop/agent":                       "laptop/agent",
-		"Your bank asks\nType your PIN, now": "Your bank asks-Type your PIN",
-		"":                                   "an unnamed caller",
-		"<b>x</b>":                           "an unnamed caller",
-		strings.Repeat("a", 100):             strings.Repeat("a", 80),
-		"--prompt, something else":           "an unnamed caller",
-	} {
-		if got := askedByName(in); got != want {
-			t.Errorf("askedByName(%q) = %q, want %q", in, got, want)
-		}
-	}
-	// The verb's schema has no argument that reaches the prompt's words.
-	for _, verb := range []string{"give", "secret-ask"} {
-		for _, free := range []string{"asked_by", "prompt", "message", "value", "from"} {
-			if _, err := argvFor(verb, map[string]any{"node": "anchor", "module": "telegram", "secret": "telegram-token",
-				"at": "laptop", free: "x"}); err == nil {
-				t.Errorf("%s takes %s", verb, free)
-			}
-		}
-	}
-}
-
-// An ask for a secret is bounded before anybody is asked to type (ADR 0277): the record refuses it, nothing is
-// asked; and how every ask ends is recorded.
-func TestASecretAskIsBoundedAndItsEndRecorded(t *testing.T) {
-	d, accepted, _, asked := aDesk(t, sealedTo(t, typed))
-	var ended []string
-	d.open = func(node, module, name, desk string) (int64, error) { return 7, nil }
-	d.end = func(id int64, outcome string) error {
-		ended = append(ended, fmt.Sprintf("%d %s", id, outcome))
-		return nil
-	}
-	if _, err := d.give("anchor", "telegram", "telegram-token", "laptop"); err != nil {
-		t.Fatal(err)
-	}
-	d.open = func(node, module, name, desk string) (int64, error) {
-		return 0, errors.New("an ask for telegram-token of telegram on anchor is still open")
-	}
-	_, err := d.give("anchor", "telegram", "telegram-token", "laptop")
-	if err == nil || !strings.Contains(err.Error(), "nobody was asked to type anything") || !strings.Contains(err.Error(), "still open") {
-		t.Errorf("a second ask: %v", err)
-	}
-	if len(*asked) != 1 || len(*accepted) != 1 {
-		t.Errorf("asked %d, accepted %d", len(*asked), len(*accepted))
-	}
-	d.open = func(node, module, name, desk string) (int64, error) { return 8, nil }
-	d.ask = func(string, map[string]any) (json.RawMessage, error) {
-		return json.RawMessage(`{"cancelled":true}`), nil
-	}
-	if _, err := d.give("anchor", "telegram", "telegram-token", "laptop"); !errors.Is(err, errNothingGiven) {
-		t.Errorf("a dismissed prompt: %v", err)
-	}
-	if strings.Join(ended, "; ") != "7 given; 8 dismissed" {
-		t.Errorf("ended: %v", ended)
-	}
-}
-
-// A secret ask cannot be turned into a secret read: the line carries no value, the answer carries none, and every
-// other `secret` line is the terminal's.
-func TestASecretAskIsNeverASecretRead(t *testing.T) {
-	t.Setenv(verbVar, "mesh-controller.secret-ask")
-	for _, args := range [][]string{
-		{"ask", "anchor", "telegram", "telegram-token", "the-value"},
-		{"ask", "anchor", "telegram"},
-		{"ask", "anchor", "telegram", "telegram-token", "--from", "/dev/null"},
-	} {
-		if err := secretCommand(context.Background(), args); err == nil {
-			t.Errorf("secret %v was taken", args)
-		}
-	}
-	for _, args := range [][]string{{"recover", "anchor", "telegram", "telegram-token"}, {"export"}} {
-		if err := terminalOnly(append([]string{"secret"}, args...)); err == nil {
-			t.Errorf("secret %v passed the terminal rule", args)
-		}
-	}
-}

cmd/mesh-controller/doctor.go

@@ -1,693 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"flag"
-	"fmt"
-	"sort"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/nats-io/nats.go"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// The self-check: `doctor` (novox/hq to-be 45 §4, ADR 0227 rule 6).
-//
-// **The design's invariants, run against the running mesh.** A probe is one live invariant of a
-// design — every machine's declaration composes and validates, every resolver answers, every seat's
-// holder answers, every stream and consumer is there as defined — with an id, a bound, and the
-// condition it raises when the invariant does not hold. The serving controller runs the registry every
-// five minutes, each probe given thirty seconds; a probe that errors or does not finish raises
-// `probe-failed` for itself, because an unanswered probe is never a pass. Every run ends with a
-// heartbeat on the bus (`doctor-heartbeat`, S10), which mesh-watcher listens for from a second
-// machine: a controller that stops checking is itself said, through a channel that does not pass
-// through it.
-//
-// `doctor` answers the last run's verdict at once; `doctor run` runs now; `doctor probes` lists the
-// registry; `doctor signals` says, for every row of the signals table, the age of its newest signal.
-
-// The self-check's clocks.
-var (
-	// doctorEvery is how often the registry runs; doctorFirstAfter how long after the controller
-	// starts the first run waits, so what the controller hears at its start has arrived.
-	doctorEvery      = 5 * time.Minute
-	doctorFirstAfter = time.Minute
-	// probeWithin is each probe's bound.
-	probeWithin = 30 * time.Second
-)
-
-// The verdicts a probe can have.
-const (
-	verdictPass        = "pass"
-	verdictFail        = "fail"
-	verdictFailedToRun = "failed-to-run"
-	verdictDeferred    = "deferred"
-)
-
-// probe is one live invariant.
-type probe struct {
-	ID      string
-	Asserts string
-	From    string
-	// Kind is the condition kind raised when the invariant does not hold.
-	Kind string
-	// Raises are the other kinds its findings carry, each its own (a consumer missing, one far behind):
-	// what a healer may be registered against (healers.go).
-	Raises []string
-	Phase  int
-	// Deferred says why it is not run yet; empty for one that is.
-	Deferred string
-	// Asks are the seat verbs it calls. A probe may call no other (askSeatTool refuses), and the
-	// controller's grant names every one (a test over this registry): a probe whose question the bus
-	// refuses checks nothing (D8, 2026-10-06).
-	Asks []broker.SeatVerb
-	run  func(ctx context.Context, d *doctor) ([]conditions.Observation, error)
-}
-
-// probeRegistry is the registry, in to-be 45's order. **The registry is the design's live form**: a
-// probe added to a design is a row added here.
-var probeRegistry = []probe{
-	// D1 also says every module assigned and left out of a machine's declaration (novox/hq issue 380), from the
-	// resolution it already makes: needs-operator for a setting nobody gave, left-out for any other cause.
-	{ID: "D1", Asserts: "every machine's declaration composes, and passes the node-engine's validation; no module " +
-		"assigned to a machine is left out of its declaration unsaid",
-		From: "issues 236, 263, 275, 380", Kind: "declaration-refused",
-		Raises: []string{kindAwaitingPush, kindLeftOut, kindNeedsOperator}, Phase: 1,
-		run: probeDeclarations},
-	{ID: "D2", Asserts: "every holder of the mesh's resolver answers a machine name for IPv4, and NODATA for IPv6",
-		From: "issue 262", Kind: "resolver-wrong", Phase: 1, run: probeResolvers},
-	{ID: "D3", Asserts: "every seat on record that serves verbs has a live holder that answers, on every " +
-		"machine that is heard from", From: "issues 208, 218", Kind: "holder-silent", Phase: 1, run: probeHolders},
-	{ID: "D4", Asserts: "every kept archive is held by a manifest", From: "issue 253",
-		Kind: "archives-unheld", Phase: 1, run: probeArchives},
-	{ID: "D5", Asserts: "exactly one lease holder — the key names this controller at its epoch, and the record " +
-		"holds no other epoch open; no message from a stale epoch refused in the last interval",
-		From: "issue 204", Kind: "lease-split", Phase: 2, run: probeLease},
-	{ID: "D6", Asserts: "every durable consumer the mesh expects exists with its definition, and is near its " +
-		"stream's head", From: "issues 248, 266", Kind: "consumer-wrong", Raises: []string{"consumer-lost", kindConsumerBehind},
-		Phase: 1, run: probeConsumers},
-	{ID: "D7", Asserts: "every stream the controller defines exists with its definition, and its own buckets",
-		From: "issue 208", Kind: "stream-wrong", Phase: 1, run: probeStreams},
-	{ID: "D8", Asserts: "no address the mesh owns — a machine's private address or its endpoint — is in a ban list",
-		From: "issue 238", Kind: "own-address-banned", Phase: 1, run: probeBans,
-		Asks: []broker.SeatVerb{{Seat: "node-intrusion-prevention", Verb: "banned"}}},
-	{ID: "D9", Asserts: "status answers in full within ten seconds, from a summary composed lately",
-		From: "issue 265", Kind: "status-slow", Phase: 1, run: probeStatus},
-	{ID: "D10", Asserts: "every machine runs the node-engine and node tools builds the mesh holds, or is inside " +
-		"a plan's window", From: "the version split", Kind: "core-behind", Phase: 1, run: probeCoreBuilds},
-	{ID: "D11", Asserts: "no provider holds a consumer retired more than thirty days without a person deciding " +
-		"its cleanup", From: "ADR 0230", Kind: kindCleanupWaiting, Phase: 2, run: probeRetired},
-	{ID: probeBindingsID, Asserts: "every consumer of a provision that keeps its data is bound where it was last " +
-		"sent, or moves by a pin", From: "issue 273, ADR 0232", Kind: kindBindingMoved,
-		Raises: []string{kindBindingKept, kindBindingMoving}, Phase: 2, run: probeBindings},
-	{ID: probeDataID, Asserts: "every item of data a machine declares is measured, is there, holds what it held, is " +
-		"written where it should be, is backed up within its bound or sits on healthy redundant storage, and is no " +
-		"empty replacement of a copy kept elsewhere; what a machine no longer declares that is irreplaceable or " +
-		"valuable is retired, not forgotten", From: "issue 273, ADR 0233",
-		Kind: kindDataShrank, Raises: []string{kindEmptyReplacement, kindDataHeldTwice, kindDataQuiet, kindBackupStale,
-			kindDataUnmeasured, kindDataMissing, kindArrayDegraded, kindProtectionMissing, kindCleanupWaiting},
-		Phase: 2, run: probeData,
-		Asks: []broker.SeatVerb{{Seat: "node-backup", Verb: "backed-up"}}},
-	// The delivery's owner (novox/hq ADR 0239): what it holds past a bound of its own table is said here, by
-	// the controller, and H2 works it through the owner's `close`.
-	{ID: probeDeliveriesID, Asserts: "no delivery is held past its state's bound unsaid: mesh-delivery's " +
-		"`stalled`, each with the transition its table lets healer H2 take", From: "ADR 0239",
-		Kind: kindDeliveryStalled, Phase: 3, run: probeDeliveries},
-	// The delivery budgets (novox/hq ADR 0282 decision 7): the newest delivery of each class within its budget,
-	// read from mesh-delivery's `times`; a measurement said, never a delivery held.
-	{ID: probeBudgetsID, Asserts: "the newest delivery of a leaf module ran on every machine within three minutes of " +
-		"its merge, and of a core module within ten: mesh-delivery's `times`", From: "ADR 0282, ADR 0304",
-		Kind: kindOverBudget, Phase: 3, run: probeBudgets},
-	// A client of the bus reconnecting in a loop (novox/hq issue 327), from the server's record of closed
-	// connections, which the bus's own module reads.
-	{ID: probeReconnectsID, Asserts: "no user of the bus had its connection dropped more than twelve times in the " +
-		"last hour: the bus module's nats_closed_connections", From: "issue 327", Kind: kindBusReconnects,
-		Phase: 1, run: probeReconnects},
-	// The account agents run as (novox/hq ADR 0266): where a machine names one, its node-engine has judged it
-	// unable to become root without a person — what ADR 0259 §8 rests an authorised answer on.
-	{ID: agentAccountProbe, Asserts: "every machine that names an agent account has it judged, on its node-engine's " +
-		"newest statement, unable to become root without a person", From: "ADR 0266, ADR 0259 §8",
-		Kind: kindAgentCanBecomeRoot, Phase: 1, run: probeAgentAccounts},
-	// Root where the trusted parties run (novox/hq ADR 0259 §8): while an agent can become root there without a
-	// person, an answer proven there proves nothing.
-	{ID: "D-root", Asserts: "no agent can become root without a person on a machine where the router or a channel " +
-		"proving its sender runs: not by its own account, and not through a tool that runs its command as an account " +
-		"that can", From: "ADR 0259 §8", Kind: kindRootNotFree, Phase: 2, run: probeAgentRoot},
-	// A module's bucket or log filling toward its cap (novox/hq ADR 0297 §6): said at three quarters, cleared
-	// below seven tenths, so one at its threshold is not raised and cleared on every run. One that cannot be
-	// read is said on its own, and every other is still judged.
-	{ID: probeFillID, Asserts: "every module's bucket and log holds less than three quarters of its cap; one " +
-		"said filling is cleared once it holds less than seven tenths", From: "ADR 0297, issue 501",
-		Kind: kindBucketOrLogFilling, Raises: []string{kindBucketOrLogUnread}, Phase: 1, run: probeFill},
-	{ID: "DW", Asserts: "the watchdogs of the signals table ran within three of their intervals",
-		From: "ADR 0227 rule 6: the watchers are watched", Kind: "watchdogs-silent", Phase: 1, run: probeWatchdogs},
-	// The core's health definitions (novox/hq to-be 45 §8, ADR 0236): what a core component's new build is
-	// judged by on its first machine, run against every machine between upgrades too.
-	{ID: "H-controller", Asserts: "the controller lease is held, renewed in time, by a controller that says it is " +
-		"ready: its self-check ran and status answered in full within ten seconds", From: "ADR 0236, to-be 45 §8",
-		Kind: kindCoreUnhealthy, Phase: 4, run: probeControllerHealth},
-	{ID: "H-engine", Asserts: "every machine heard from has reported its current declaration, under a node-engine " +
-		"build it names", From: "ADR 0236, to-be 45 §8", Kind: kindCoreUnhealthy, Phase: 4, run: probeEngineHealth},
-	{ID: "H-tools", Asserts: "every machine heard from that runs the node tools has them answering the bus",
-		From: "ADR 0236, to-be 45 §8", Kind: kindCoreUnhealthy, Phase: 4, run: probeToolsHealth},
-	{ID: "H-bus", Asserts: "every stream and durable consumer the mesh defines is on the bus, and a request crosses " +
-		"it to the machines' node tools and back", From: "ADR 0236, to-be 45 §8", Kind: kindCoreUnhealthy, Phase: 4,
-		run: probeBusHealth},
-	// The gate's verdicts and the witnesses' rollbacks (ADR 0236): each build that failed its gate keeps its
-	// condition until a newer build passes; each rollback a witness stands by is said.
-	{ID: gateProbe, Asserts: "no build that failed its gate, and no core component a witness put back, goes unsaid; " +
-		"a newer build that passes its gate clears it", From: "ADR 0236, to-be 45 §8", Kind: kindRolledBack,
-		Raises: []string{kindRollbackFailed}, Phase: 4, run: probeGates},
-	// The bus's planned step (ADR 0236): open while a person's bus upgrade runs, then checked by H-bus.
-	{ID: busStepProbe, Asserts: "a bus upgrade a person started is said while it runs, and is followed by the bus's " +
-		"health within its bound — or is said failed, with its snapshot as the way back", From: "ADR 0236, to-be 45 §8",
-		Kind: kindBusMaintenance, Raises: []string{kindBusUpgradeFailed}, Phase: 4, run: probeBusStep},
-}
-
-// probeVerdict is one probe's outcome in a run.
-type probeVerdict struct {
-	ID      string   `json:"id"`
-	Verdict string   `json:"verdict"`
-	Found   []string `json:"found,omitempty"`
-	// Unconfirmed are findings one look can be wrong about, seen by this run and not the one before:
-	// raised if the next run sees them too (confirm.go). Not a pass, and not yet a condition.
-	Unconfirmed []string `json:"unconfirmed,omitempty"`
-	Error       string   `json:"error,omitempty"`
-	Took        string   `json:"took,omitempty"`
-	// FoundCount and More are an overview's: how many findings the probe had when the overview shows
-	// fewer, and how to read them all (novox/hq issue 314). Never in a heartbeat.
-	FoundCount int    `json:"found-count,omitempty"`
-	More       string `json:"more,omitempty"`
-}
-
-// overviewFindings is how many findings of one probe an overview carries. On 2026-10-08 D14 found 689
-// stalled deliveries, and an overview carrying every one of them, beside the conditions they raised,
-// was more than the bus carries in one message (novox/hq issue 314); one probe's verdict whole is
-// `doctor probe=<id>`.
-const overviewFindings = 20
-
-// inOverview is a run as an overview carries it: each probe's findings at most overviewFindings, with
-// their count and how to read them all. The run itself is not changed.
-func inOverview(run doctorRun) doctorRun {
-	probes := make([]probeVerdict, len(run.Probes))
-	for i, p := range run.Probes {
-		total := len(p.Found) + len(p.Unconfirmed)
-		if total > overviewFindings {
-			p.FoundCount = len(p.Found)
-			if len(p.Found) > overviewFindings {
-				p.Found = p.Found[:overviewFindings:overviewFindings]
-			}
-			if room := overviewFindings - len(p.Found); len(p.Unconfirmed) > room {
-				p.Unconfirmed = p.Unconfirmed[:room:room]
-			}
-			p.More = fmt.Sprintf("%d found and %d unconfirmed, %d of them shown — `doctor probe=%s` gives them all",
-				p.FoundCount, total-p.FoundCount, len(p.Found)+len(p.Unconfirmed), p.ID)
-		}
-		probes[i] = p
-	}
-	run.Probes = probes
-	return run
-}
-
-// oneProbe is a run with only one probe's verdict, whole.
-func oneProbe(run doctorRun, id string) (doctorRun, error) {
-	for _, p := range run.Probes {
-		if strings.EqualFold(p.ID, id) {
-			run.Probes = []probeVerdict{p}
-			return run, nil
-		}
-	}
-	return doctorRun{}, fmt.Errorf("the run %s has no probe %q — `doctor probes=true` lists them", run.Run, id)
-}
-
-// doctorCounts are a run's verdicts, counted.
-type doctorCounts struct {
-	Passed      int `json:"passed"`
-	Failed      int `json:"failed"`
-	FailedToRun int `json:"failed-to-run"`
-	Deferred    int `json:"deferred"`
-}
-
-// doctorRun is one run of the registry, and the body of its heartbeat.
-type doctorRun struct {
-	Run             string         `json:"run"`
-	At              time.Time      `json:"at"`
-	Started         time.Time      `json:"started"`
-	Took            string         `json:"took"`
-	IntervalSeconds int            `json:"interval-seconds"`
-	Counts          doctorCounts   `json:"counts"`
-	Probes          []probeVerdict `json:"probes"`
-	// Controller is the machine that ran it, and Why what started it: the schedule, or a person.
-	Controller string `json:"controller"`
-	Why        string `json:"why"`
-	// Unsaid is how many condition transitions this controller could not say, since it started.
-	Unsaid int `json:"unsaid,omitempty"`
-}
-
-// doctor is the registry and what its probes need.
-type doctor struct {
-	open      *stores
-	js        *broker.JetStream
-	keeper    *conditions.Keeper
-	teller    conditions.Teller
-	watchdogs *watchdogs
-	host      string
-	// confirm holds back what one run alone saw of a finding a single look can be wrong about.
-	confirm confirming
-
-	running sync.Mutex
-	mu      sync.Mutex
-	last    *doctorRun
-	ended   time.Time
-}
-
-// lastRunEnded is when the last run ended; zero before the first.
-func (d *doctor) lastRunEnded() time.Time {
-	d.mu.Lock()
-	defer d.mu.Unlock()
-	return d.ended
-}
-
-// lastRun is the last run's verdict; nil before the first.
-func (d *doctor) lastRun() *doctorRun {
-	d.mu.Lock()
-	defer d.mu.Unlock()
-	return d.last
-}
-
-// keep runs the registry on its schedule until ctx ends.
-func (d *doctor) keep(ctx context.Context) {
-	select {
-	case <-ctx.Done():
-		return
-	case <-time.After(doctorFirstAfter):
-	}
-	tick := time.NewTicker(doctorEvery)
-	defer tick.Stop()
-	for {
-		// Only the controller acting checks the mesh on a schedule: one standing by would say a
-		// heartbeat for a self-check that is not the mesh's.
-		if d.watchdogs == nil || d.watchdogs.acting == nil || d.watchdogs.acting() {
-			d.runOnce(ctx, "the schedule")
-		}
-		select {
-		case <-ctx.Done():
-			return
-		case <-tick.C:
-		}
-	}
-}
-
-var doctorRuns struct {
-	sync.Mutex
-	n uint64
-}
-
-// runOnce runs every probe the registry runs, keeps what each found, and says the heartbeat. One run
-// at a time: a person's `doctor run` during a scheduled one waits for it.
-func (d *doctor) runOnce(ctx context.Context, why string) doctorRun {
-	d.running.Lock()
-	defer d.running.Unlock()
-	doctorRuns.Lock()
-	doctorRuns.n++
-	n := doctorRuns.n
-	doctorRuns.Unlock()
-	started := time.Now()
-	run := doctorRun{Run: fmt.Sprintf("doctor-%d-%d", started.Unix(), n), Started: started.UTC(),
-		IntervalSeconds: int(doctorEvery / time.Second), Controller: d.host, Why: why}
-
-	type result struct {
-		obs  []conditions.Observation
-		err  error
-		took time.Duration
-	}
-	results := make([]result, len(probeRegistry))
-	var wg sync.WaitGroup
-	for i, p := range probeRegistry {
-		if p.run == nil {
-			continue
-		}
-		wg.Add(1)
-		go func(i int, p probe) {
-			defer wg.Done()
-			probing, cancel := context.WithTimeout(context.WithValue(ctx, probeAsksKey{}, p), probeWithin)
-			defer cancel()
-			began := time.Now()
-			done := make(chan result, 1)
-			go func() {
-				defer func() {
-					if r := recover(); r != nil {
-						done <- result{err: fmt.Errorf("the probe panicked: %v", r)}
-					}
-				}()
-				obs, err := p.run(probing, d)
-				done <- result{obs: obs, err: err}
-			}()
-			select {
-			case r := <-done:
-				r.took = time.Since(began)
-				results[i] = r
-			case <-probing.Done():
-				results[i] = result{err: fmt.Errorf("it did not finish within %s", probeWithin), took: time.Since(began)}
-			}
-		}(i, p)
-	}
-	wg.Wait()
-
-	var blind []conditions.Observation
-	for i, p := range probeRegistry {
-		v := probeVerdict{ID: p.ID}
-		r := results[i]
-		switch {
-		case p.run == nil:
-			v.Verdict = verdictDeferred
-			run.Counts.Deferred++
-		case r.err != nil:
-			v.Verdict, v.Error = verdictFailedToRun, r.err.Error()
-			run.Counts.FailedToRun++
-			// A probe that could not run once — a question timed out on a loaded machine — is said in
-			// the verdict at once, and raised as a condition when the next run cannot run it either.
-			blind = append(blind, conditions.Observation{Scope: conditions.ScopeProbe, ID: p.ID, Kind: "probe-failed",
-				Token: "failed", Severity: conditions.Warning, Confirm: true,
-				Summary: fmt.Sprintf("the probe %s (%s) could not run: what it checks is not known — never a pass", p.ID, p.Asserts),
-				Said:    firstLine(r.err.Error())})
-		default:
-			raise, held := d.confirm.pass(ctx, d.keeper, p.ID, kindedAs(r.obs, p.Kind))
-			if err := d.keeper.Reconcile(ctx, p.ID, raise); err != nil {
-				v.Error = "what it found could not be kept: " + err.Error()
-			}
-			for _, o := range held {
-				v.Unconfirmed = append(v.Unconfirmed, o.Summary)
-			}
-			if len(raise) == 0 {
-				v.Verdict = verdictPass
-				run.Counts.Passed++
-			} else {
-				v.Verdict = verdictFail
-				run.Counts.Failed++
-				for _, o := range raise {
-					v.Found = append(v.Found, o.Summary)
-				}
-			}
-		}
-		if p.run != nil {
-			v.Took = r.took.Round(time.Millisecond).String()
-		}
-		run.Probes = append(run.Probes, v)
-	}
-	blind, _ = d.confirm.pass(ctx, d.keeper, sourceDoctor, blind)
-	if err := d.keeper.Reconcile(ctx, sourceDoctor, blind); err != nil {
-		fmt.Printf("the self-check's own failures could not be kept: %v\n", err)
-	}
-	ended := time.Now()
-	run.At, run.Took, run.Unsaid = ended.UTC(), ended.Sub(started).Round(time.Millisecond).String(), d.keeper.Unsaid()
-	d.mu.Lock()
-	d.last, d.ended = &run, ended
-	d.mu.Unlock()
-	d.sayHeartbeat(ctx, run)
-	return run
-}
-
-// sourceDoctor is what raises a probe's own failure to run.
-const sourceDoctor = "doctor"
-
-// kindedAs gives each observation of a probe the probe's kind where it named none.
-func kindedAs(obs []conditions.Observation, kind string) []conditions.Observation {
-	out := make([]conditions.Observation, 0, len(obs))
-	for _, o := range obs {
-		if o.Kind == "" {
-			o.Kind = kind
-		}
-		out = append(out, o)
-	}
-	return out
-}
-
-// sayHeartbeat publishes the run's heartbeat. Not said is said here, and S10 on the second machine
-// says it outward: the watcher hears nothing.
-func (d *doctor) sayHeartbeat(ctx context.Context, run doctorRun) {
-	if d.teller == nil {
-		return
-	}
-	body, err := json.Marshal(run)
-	if err != nil {
-		fmt.Printf("the self-check's heartbeat could not be written: %v\n", err)
-		return
-	}
-	saying, cancel := context.WithTimeout(ctx, 10*time.Second)
-	defer cancel()
-	if err := d.teller.PublishSeatEvent(saying, conditions.Seat, conditions.HeartbeatEvent, body); err != nil {
-		fmt.Printf("the self-check's heartbeat (%s) could NOT be said, so the watcher on the second machine "+
-			"will say the self-check is silent: %v\n", run.Run, err)
-	}
-}
-
-// doctorFrom is the serving controller's self-check; nil in any other process.
-var doctorFrom *doctor
-
-// doctorCommand is `doctor`, `doctor run`, `doctor probes` and `doctor signals`.
-func doctorCommand(ctx context.Context, args []string) error {
-	sub := ""
-	if len(args) > 0 && !strings.HasPrefix(args[0], "-") {
-		sub, args = args[0], args[1:]
-	}
-	set := flag.NewFlagSet("doctor", flag.ContinueOnError)
-	asJSON := set.Bool("json", false, "as data")
-	probe := set.String("probe", "", "one probe's verdict, with every finding")
-	if rest, err := parseAround(set, args); err != nil {
-		return err
-	} else if len(rest) > 0 {
-		return errors.New("doctor [run|probes|signals] [--probe <id>] [--json]")
-	}
-	answer, err := doctorAnswer(ctx, sub, *probe)
-	if err != nil {
-		return err
-	}
-	if *asJSON {
-		return printJSON(answer)
-	}
-	fmt.Print(doctorText(answer))
-	return nil
-}
-
-// doctorAnswer is what the verb answers, as data.
-//
-// A verdict is an overview — each probe's findings at most overviewFindings — unless probe names one,
-// which is then answered alone and whole (novox/hq issue 314).
-func doctorAnswer(ctx context.Context, sub, probe string) (any, error) {
-	if probe != "" && sub != "" && sub != "run" {
-		return nil, fmt.Errorf("probe names one probe of a verdict; %s has none", sub)
-	}
-	switch sub {
-	case "":
-		if doctorFrom != nil {
-			if run := doctorFrom.lastRun(); run != nil {
-				return verdictAnswer(*run, time.Now(), probe)
-			}
-			return nil, fmt.Errorf("the self-check has not finished its first run yet: it runs %s after the "+
-				"controller starts, then every %s — `doctor run` runs it now", doctorFirstAfter, doctorEvery)
-		}
-		run, err := lastHeartbeat(ctx)
-		if err != nil {
-			return nil, err
-		}
-		return verdictAnswer(run, time.Now(), probe)
-	case "run":
-		d := doctorFrom
-		if d == nil {
-			local, closeIt, err := localDoctor(ctx)
-			if err != nil {
-				return nil, err
-			}
-			defer closeIt()
-			d = local
-		}
-		return verdictAnswer(d.runOnce(ctx, "asked by "+link.Caller()), time.Now(), probe)
-	case "probes":
-		return probesAnswer(), nil
-	case "signals":
-		if doctorFrom == nil || doctorFrom.watchdogs == nil {
-			return nil, errors.New("the age of each signal is known to the serving controller alone, which " +
-				"hears them: ask it through the mesh-controller seat's doctor verb")
-		}
-		return signalsAnswer(doctorFrom.watchdogs.lastFacts(), doctorFrom.watchdogs.lastTick()), nil
-	}
-	return nil, fmt.Errorf("doctor answers the last run, or `run`, `probes` or `signals` — not %q", sub)
-}
-
-// verdictAnswer is a run as the verb answers it, with its age.
-func verdictAnswer(run doctorRun, now time.Time, probe string) (map[string]any, error) {
-	if probe != "" {
-		one, err := oneProbe(run, probe)
-		if err != nil {
-			return nil, err
-		}
-		run = one
-	} else {
-		run = inOverview(run)
-	}
-	return map[string]any{"run": run, "age": now.Sub(run.At).Round(time.Second).String(),
-		"note": "a probe that could not run is never a pass; each failure is an open condition until a run passes it, " +
-			"and one a single look can be wrong about — an unanswered question, a slow answer — is raised when two " +
-			"runs in a row see it"}, nil
-}
-
-// probesAnswer is the registry.
-func probesAnswer() map[string]any {
-	var out []map[string]any
-	for _, p := range probeRegistry {
-		row := map[string]any{"id": p.ID, "asserts": p.Asserts, "from": p.From, "kind": p.Kind, "phase": p.Phase}
-		if len(p.Raises) > 0 {
-			row["raises"] = p.Raises
-		}
-		if p.Deferred != "" {
-			row["deferred"] = p.Deferred
-		}
-		out = append(out, row)
-	}
-	return map[string]any{"probes": out, "every": doctorEvery.String(), "each within": probeWithin.String()}
-}
-
-// signalsAnswer is every row of the signals table with the age of its newest signal.
-func signalsAnswer(f *signalFacts, ticked time.Time) map[string]any {
-	var rows []map[string]any
-	for _, r := range signalsTable {
-		row := map[string]any{"row": r.Row, "signal": r.Signal, "emitter": r.Emitter, "bound": r.Bound,
-			"kind": r.Kind, "severity": r.Severity, "phase": r.Phase}
-		switch {
-		case r.Deferred != "":
-			row["deferred"] = r.Deferred
-		case f == nil:
-			row["newest"] = "not yet looked at"
-		default:
-			if err := r.needs(f); err != nil {
-				row["blind"] = err.Error()
-			} else if newest := r.newest(f); newest.IsZero() {
-				row["newest"] = "none heard"
-			} else {
-				row["newest"] = newest.UTC().Format(time.RFC3339)
-				row["age"] = f.now.Sub(newest).Round(time.Second).String()
-			}
-		}
-		rows = append(rows, row)
-	}
-	out := map[string]any{"signals": rows, "every": watchEvery.String()}
-	if !ticked.IsZero() {
-		out["looked"] = ticked.UTC().Format(time.RFC3339)
-	}
-	return out
-}
-
-// doctorText is an answer as a person reads it.
-func doctorText(answer any) string {
-	body, _ := json.Marshal(answer)
-	var b strings.Builder
-	var verdict struct {
-		Run doctorRun `json:"run"`
-		Age string    `json:"age"`
-	}
-	if json.Unmarshal(body, &verdict) == nil && verdict.Run.Run != "" {
-		r := verdict.Run
-		fmt.Fprintf(&b, "%s, %s ago (took %s, %s): %d passed, %d failed, %d could not run, %d not built yet\n\n",
-			r.Run, verdict.Age, r.Took, r.Why, r.Counts.Passed, r.Counts.Failed, r.Counts.FailedToRun, r.Counts.Deferred)
-		for _, p := range r.Probes {
-			fmt.Fprintf(&b, "  %-4s %-14s %s\n", p.ID, p.Verdict, p.Took)
-			for _, f := range p.Found {
-				fmt.Fprintf(&b, "         %s\n", f)
-			}
-			for _, f := range p.Unconfirmed {
-				fmt.Fprintf(&b, "         unconfirmed, raised if the next run sees it too: %s\n", f)
-			}
-			if p.More != "" {
-				fmt.Fprintf(&b, "         … %s\n", p.More)
-			}
-			if p.Error != "" {
-				fmt.Fprintf(&b, "         %s\n", p.Error)
-			}
-		}
-		return b.String()
-	}
-	pretty, _ := json.MarshalIndent(answer, "", "  ")
-	return string(pretty) + "\n"
-}
-
-// lastHeartbeat is the newest run's heartbeat, read from the events stream: what a process other than
-// the serving controller answers `doctor` from.
-func lastHeartbeat(ctx context.Context) (doctorRun, error) {
-	var run doctorRun
-	err := onTheBus(func(conn *nats.Conn) error {
-		js, err := conn.JetStream(nats.Context(ctx))
-		if err != nil {
-			return err
-		}
-		msg, err := js.GetLastMsg(broker.EventsStream, link.SeatEventSubject(conditions.Seat, conditions.HeartbeatEvent))
-		if errors.Is(err, nats.ErrMsgNotFound) {
-			return errors.New("the self-check has said no heartbeat on the bus in the last week: it is not running")
-		}
-		if err != nil {
-			return fmt.Errorf("the self-check's last heartbeat cannot be read: %w", err)
-		}
-		return json.Unmarshal(msg.Data, &run)
-	})
-	return run, err
-}
-
-// localDoctor is a self-check run by a process other than the serving controller: its own stores,
-// its own connection, and its own keeper, closed after.
-func localDoctor(ctx context.Context) (*doctor, func(), error) {
-	open, err := openStores(ctx)
-	if err != nil {
-		return nil, nil, err
-	}
-	js, err := dialTheBus()
-	if err != nil {
-		open.Close()
-		return nil, nil, err
-	}
-	k, err := keeperOn(ctx, js.Conn(), storeLooks{open.inventory})
-	if err != nil {
-		js.Close()
-		open.Close()
-		return nil, nil, err
-	}
-	jsCtx := js.Context()
-	d := &doctor{open: open, js: js, keeper: k, teller: link.OverNATS{Conn: js.Conn(), JS: jsCtx},
-		host: controlHost(ctx, open.inventory)}
-	return d, func() {
-		flushing, cancel := context.WithTimeout(context.Background(), 15*time.Second)
-		defer cancel()
-		k.Close(flushing)
-		js.Close()
-		open.Close()
-	}, nil
-}
-
-// sortedFound is a probe's findings in a stated order, so two runs over one mesh say the same.
-func sortedFound(obs []conditions.Observation) []conditions.Observation {
-	sort.Slice(obs, func(i, j int) bool { return obs[i].Key() < obs[j].Key() })
-	return obs
-}
-
-// probeAsksKey carries the running probe, so a seat verb it calls is checked against what it declares.
-type probeAsksKey struct{}
-
-// declaredBy says whether the probe running in ctx declared a seat verb; outside a probe, false.
-func declaredBy(ctx context.Context, seat, verb string) (string, bool) {
-	p, ok := ctx.Value(probeAsksKey{}).(probe)
-	if !ok {
-		return "a caller outside the self-check", false
-	}
-	for _, v := range p.Asks {
-		if v.Seat == seat && v.Verb == verb {
-			return p.ID, true
-		}
-	}
-	return p.ID, false
-}

cmd/mesh-controller/doctor_test.go

@@ -1,430 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"net"
-	"slices"
-	"strings"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"github.com/nats-io/nats.go"
-	"github.com/nats-io/nats.go/jetstream"
-	"golang.org/x/net/dns/dnsmessage"
-
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/link"
-
-	"github.com/novox/mesh-controller/internal/testbus"
-)
-
-// The self-check (novox/hq to-be 45 §4): a probe that fails raises its condition, one that cannot run
-// raises probe-failed for itself and is never a pass, and every run ends with its heartbeat.
-
-// withProbes runs the test with a registry of its own.
-func withProbes(t *testing.T, probes ...probe) {
-	t.Helper()
-	before := probeRegistry
-	probeRegistry = probes
-	t.Cleanup(func() { probeRegistry = before })
-}
-
-func TestARunKeepsWhatEachProbeFoundAndSaysItsHeartbeat(t *testing.T) {
-	failing := conditions.Observation{Scope: conditions.ScopeMachine, ID: "anchor", Token: "refused",
-		Severity: conditions.Urgent, Summary: "anchor's node-engine would refuse its declaration"}
-	var broken atomic.Bool
-	broken.Store(true)
-	withProbes(t,
-		probe{ID: "P1", Asserts: "passes", Kind: "never", Phase: 1,
-			run: func(context.Context, *doctor) ([]conditions.Observation, error) { return nil, nil }},
-		probe{ID: "P2", Asserts: "finds a fault", Kind: "declaration-refused", Phase: 1,
-			run: func(context.Context, *doctor) ([]conditions.Observation, error) {
-				if broken.Load() {
-					return []conditions.Observation{failing}, nil
-				}
-				return nil, nil
-			}},
-		probe{ID: "P3", Asserts: "cannot run", Kind: "x", Phase: 1,
-			run: func(context.Context, *doctor) ([]conditions.Observation, error) {
-				if broken.Load() {
-					return nil, errors.New("the store is away")
-				}
-				return nil, nil
-			}},
-		probe{ID: "P4", Asserts: "hangs", Kind: "x", Phase: 1,
-			run: func(ctx context.Context, _ *doctor) ([]conditions.Observation, error) {
-				if broken.Load() {
-					<-ctx.Done()
-					time.Sleep(50 * time.Millisecond)
-				}
-				return nil, nil
-			}},
-		probe{ID: "P5", Asserts: "later", Kind: "x", Phase: 2, Deferred: "not yet"},
-	)
-	before := probeWithin
-	probeWithin = 200 * time.Millisecond
-	t.Cleanup(func() { probeWithin = before })
-
-	store := conditions.NewInMemory()
-	told := &conditions.Told{}
-	k := conditions.NewKeeper(t.Context(), conditions.Options{Store: store, History: store})
-	defer k.Close(context.Background())
-	d := &doctor{keeper: k, teller: told, host: "anchor"}
-	// A probe that cannot run is said in the verdict at once, and as a condition when the next run cannot
-	// run it either (novox/hq issue 277): one timed-out question is not a probe gone blind.
-	first := d.runOnce(t.Context(), "a test")
-	if first.Counts != (doctorCounts{Passed: 1, Failed: 1, FailedToRun: 2, Deferred: 1}) {
-		t.Fatalf("counted %+v", first.Counts)
-	}
-	if open, _ := k.Open(t.Context()); len(open) != 1 || open[0].Key != "machine.anchor.refused" {
-		t.Fatalf("after one run, open: %+v", open)
-	}
-	run := d.runOnce(t.Context(), "a test")
-	if run.Counts != (doctorCounts{Passed: 1, Failed: 1, FailedToRun: 2, Deferred: 1}) {
-		t.Fatalf("counted %+v", run.Counts)
-	}
-	open, err := k.Open(t.Context())
-	if err != nil {
-		t.Fatal(err)
-	}
-	var keys []string
-	for _, c := range open {
-		keys = append(keys, c.Key+"="+c.Kind)
-	}
-	for _, want := range []string{"machine.anchor.refused=declaration-refused", "probe.P3.failed=probe-failed",
-		"probe.P4.failed=probe-failed"} {
-		if !slices.Contains(keys, want) {
-			t.Errorf("%s is not open: %v", want, keys)
-		}
-	}
-	// The heartbeat, in the shape mesh-watcher reads (the contract with the operator's channel).
-	if len(told.Names) != 2 || told.Names[1] != conditions.HeartbeatEvent {
-		t.Fatalf("said %v", told.Names)
-	}
-	if d.lastRunEnded().IsZero() || d.lastRun().Run != run.Run {
-		t.Fatal("the run is not the last verdict")
-	}
-	body, _ := json.Marshal(run)
-	var shape map[string]any
-	_ = json.Unmarshal(body, &shape)
-	for _, field := range []string{"run", "at", "interval-seconds", "counts", "probes", "controller"} {
-		if _, ok := shape[field]; !ok {
-			t.Errorf("the heartbeat carries no %q: %s", field, body)
-		}
-	}
-
-	// Mended: the next run clears every one of them.
-	broken.Store(false)
-	d.runOnce(t.Context(), "a test")
-	if open, _ := k.Open(t.Context()); len(open) != 0 {
-		t.Fatalf("a passing run left open %+v", open)
-	}
-}
-
-// **The registry says what each probe asserts**, and a probe not built says why and when.
-func TestTheRegistryIsTheDesignsLiveForm(t *testing.T) {
-	seen := map[string]bool{}
-	for _, p := range probeRegistry {
-		if seen[p.ID] {
-			t.Errorf("%s twice", p.ID)
-		}
-		seen[p.ID] = true
-		if p.Asserts == "" || p.From == "" || p.Kind == "" {
-			t.Errorf("%s does not say what it asserts, where from, or what it raises", p.ID)
-		}
-		if (p.run == nil) != (p.Deferred != "") || (p.Deferred != "" && p.Phase <= 1) {
-			t.Errorf("%s is run and deferred, or neither, or deferred out of Phase 1: %+v", p.ID, p)
-		}
-	}
-	for _, id := range []string{"D1", "D2", "D3", "D4", "D5", "D6", "D7", "D8", "D9", "D10"} {
-		if !seen[id] {
-			t.Errorf("to-be 45 §4 has %s and the registry does not", id)
-		}
-	}
-}
-
-// **The doctor and the watchdogs watch each other**: watchdogs that stopped are DW; a self-check that
-// stopped is S10 (signals_test.go).
-func TestWatchdogsThatStoppedAreSaid(t *testing.T) {
-	w := &watchdogs{started: time.Now().Add(-time.Hour)}
-	d := &doctor{watchdogs: w, host: "anchor"}
-	got, err := probeWatchdogs(t.Context(), d)
-	if err != nil || len(got) != 1 || got[0].Severity != conditions.Urgent {
-		t.Fatalf("%+v %v", got, err)
-	}
-	w.ticked = time.Now()
-	if got, _ := probeWatchdogs(t.Context(), d); len(got) != 0 {
-		t.Fatalf("%+v", got)
-	}
-}
-
-// **D1 composes every machine of a healthy mesh and the host's own validator takes each.**
-func TestEveryMachineOfAHealthyMeshComposesAndValidates(t *testing.T) {
-	open := aMesh(t)
-	got, err := probeDeclarations(t.Context(), &doctor{open: open})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(got) != 0 {
-		t.Fatalf("a healthy mesh failed D1: %+v", got)
-	}
-}
-
-// **D1 names a machine nothing can be sent to**, and the network that cannot be computed for it.
-func TestAMachineWhoseDeclarationDoesNotComposeIsSaid(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	one, two := rivals()
-	register(t, open, one)
-	register(t, open, two)
-	for _, m := range []string{"rival-one", "rival-two"} {
-		if _, err := assign(ctx, open, "laptop", m); err != nil && m == "rival-one" {
-			t.Fatal(err)
-		}
-	}
-	got, err := probeDeclarations(ctx, &doctor{open: open})
-	linted(got)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(got) != 1 || got[0].Key() != "machine.laptop.uncomposable" || !strings.Contains(got[0].Summary, "the-seat") {
-		t.Fatalf("%+v", got)
-	}
-}
-
-// **D2: a resolver answering NXDOMAIN for IPv6 is wrong** — musl takes it as no such name (issue 262).
-func TestAResolverAnsweringNoSuchNameForIPv6IsWrong(t *testing.T) {
-	answerAs := func(rcode dnsmessage.RCode) string {
-		conn, err := net.ListenPacket("udp", "127.0.0.1:0")
-		if err != nil {
-			t.Fatal(err)
-		}
-		t.Cleanup(func() { _ = conn.Close() })
-		go func() {
-			buf := make([]byte, 1500)
-			for {
-				n, from, err := conn.ReadFrom(buf)
-				if err != nil {
-					return
-				}
-				var q dnsmessage.Message
-				if q.Unpack(buf[:n]) != nil {
-					continue
-				}
-				reply := dnsmessage.Message{Header: dnsmessage.Header{ID: q.ID, Response: true}, Questions: q.Questions}
-				if q.Questions[0].Type == dnsmessage.TypeA {
-					reply.Answers = []dnsmessage.Resource{{Header: dnsmessage.ResourceHeader{Name: q.Questions[0].Name,
-						Type: dnsmessage.TypeA, Class: dnsmessage.ClassINET}, Body: &dnsmessage.AResource{A: [4]byte{10, 77, 0, 1}}}}
-				} else {
-					reply.RCode = rcode
-				}
-				packed, _ := reply.Pack()
-				_, _ = conn.WriteTo(packed, from)
-			}
-		}()
-		_, port, _ := net.SplitHostPort(conn.LocalAddr().String())
-		return port
-	}
-	before := resolverPort
-	t.Cleanup(func() { resolverPort = before })
-
-	resolverPort = answerAs(dnsmessage.RCodeSuccess)
-	v4, rcode, err := askResolver(t.Context(), "127.0.0.1", "anchor.internal", dnsmessage.TypeA)
-	if err != nil || rcode != dnsmessage.RCodeSuccess || !slices.Equal(v4, []string{"10.77.0.1"}) {
-		t.Fatalf("%v %v %v", v4, rcode, err)
-	}
-	v6, rcode, err := askResolver(t.Context(), "127.0.0.1", "anchor.internal", dnsmessage.TypeAAAA)
-	if err != nil || rcode != dnsmessage.RCodeSuccess || len(v6) != 0 {
-		t.Fatalf("NODATA read as %v %v %v", v6, rcode, err)
-	}
-	resolverPort = answerAs(dnsmessage.RCodeNameError)
-	if _, rcode, _ := askResolver(t.Context(), "127.0.0.1", "anchor.internal", dnsmessage.TypeAAAA); rcode != dnsmessage.RCodeNameError {
-		t.Fatalf("NXDOMAIN read as %v", rcode)
-	}
-}
-
-// **D6, D7: what the controller defines is what it finds**, and a consumer deleted or a stream
-// redefined is said — against a real bus, raised by the same derivation the controller starts with.
-func TestNatsTheBusIsWhatTheControllerDefines(t *testing.T) {
-	url := testbus.URL(t)
-	open := aMesh(t)
-	js, err := broker.Dial(url)
-	if err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(js.Close)
-	for _, s := range []string{"CONTROL", "NODES", "ASSIGNMENTS", "EVENTS"} {
-		_ = js.Context().DeleteStream(s)
-	}
-	if _, err := assertBusObjects(t.Context(), open.inventory, js); err != nil {
-		t.Fatal(err)
-	}
-	if err := js.EnsureControllerBuckets(); err != nil {
-		t.Fatal(err)
-	}
-	d := &doctor{open: open, js: js}
-	for _, p := range []func(context.Context, *doctor) ([]conditions.Observation, error){probeConsumers, probeStreams} {
-		got, err := p(t.Context(), d)
-		if err != nil || len(got) != 0 {
-			t.Fatalf("a bus just raised fails: %+v %v", got, err)
-		}
-	}
-	if err := js.Context().DeleteConsumer("NODES", "laptop"); err != nil {
-		t.Fatal(err)
-	}
-	info, err := js.Context().StreamInfo("EVENTS")
-	if err != nil {
-		t.Fatal(err)
-	}
-	cfg := info.Config
-	cfg.MaxMsgsPerSubject = 3
-	if _, err := js.Context().UpdateStream(&cfg); err != nil {
-		t.Fatal(err)
-	}
-	consumers, err := probeConsumers(t.Context(), d)
-	if err != nil || len(consumers) != 1 || consumers[0].Key() != "bus.NODES.laptop.missing" {
-		t.Fatalf("the deleted consumer: %+v %v", consumers, err)
-	}
-	streams, err := probeStreams(t.Context(), d)
-	if err != nil || len(streams) != 1 || !strings.Contains(streams[0].Summary, "per subject") {
-		t.Fatalf("the redefined stream: %+v %v", streams, err)
-	}
-}
-
-// **S9 hears the bus**: a consumer that gives up on a message, and one deleted, as the server says.
-func TestNatsTheBusSaysAConsumerGaveUpAndOneWasDeleted(t *testing.T) {
-	url := testbus.URL(t)
-	conn, err := nats.Connect(url)
-	if err != nil {
-		t.Fatal(err)
-	}
-	defer conn.Close()
-	heard := make(chan *nats.Msg, 16)
-	for _, subject := range broker.BusAdvisories {
-		if _, err := conn.ChanSubscribe(subject, heard); err != nil {
-			t.Fatal(err)
-		}
-	}
-	api, _ := jetstream.New(conn)
-	_ = api.DeleteStream(t.Context(), "SEAT_ADVISED")
-	stream, err := api.CreateStream(t.Context(), jetstream.StreamConfig{Name: "SEAT_ADVISED", Subjects: []string{"advised.>"}})
-	if err != nil {
-		t.Fatal(err)
-	}
-	defer func() { _ = api.DeleteStream(context.Background(), "SEAT_ADVISED") }()
-	consumer, err := stream.CreateConsumer(t.Context(), jetstream.ConsumerConfig{Durable: "SEAT_ADVISED_worker",
-		AckPolicy: jetstream.AckExplicitPolicy, MaxDeliver: 1, AckWait: 100 * time.Millisecond})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if _, err := api.Publish(t.Context(), "advised.x", []byte("x")); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := consumer.Fetch(1, jetstream.FetchMaxWait(time.Second)); err != nil {
-		t.Fatal(err)
-	}
-	// A seat's worker, so the deletion is of a consumer the mesh names (link.MeshNamed).
-	// Not acknowledged: after its one delivery the consumer gives up on it — on the next fetch.
-	time.Sleep(300 * time.Millisecond)
-	_, _ = consumer.Fetch(1, jetstream.FetchMaxWait(300*time.Millisecond))
-	if err := stream.DeleteConsumer(t.Context(), "SEAT_ADVISED_worker"); err != nil {
-		t.Fatal(err)
-	}
-	kinds := map[string]string{}
-	deadline := time.After(5 * time.Second)
-	for len(kinds) < 2 {
-		select {
-		case m := <-heard:
-			if a, ok := link.ReadAdvisory(m.Subject, m.Data); ok {
-				kinds[a.Kind] = a.Said
-			}
-		case <-deadline:
-			t.Fatalf("the bus said only %v", kinds)
-		}
-	}
-	if !strings.Contains(kinds["max-deliveries"], "gave up") || !strings.Contains(kinds["consumer-lost"], "was deleted") {
-		t.Fatalf("%v", kinds)
-	}
-}
-
-// **D10 compares a node-engine with what it is delivered as, not with its commit** (2026-10-06: every
-// machine read as behind right after a push sent it the current build — it says the digest-named
-// directory it runs from, and the mesh holds a commit).
-func TestANodeEngineIsJudgedByTheVersionItIsDeliveredAs(t *testing.T) {
-	m := catalogue.Manifest{Module: "mesh-host", Resources: []map[string]any{
-		{"id": "launcher", "type": "file", "path": "/usr/lib/nox-mesh-host/launch"},
-		{"id": "host", "type": "archive", "path": "/usr/lib/nox-mesh-host/versions/31045596c83a"},
-		{"id": "unfilled", "type": "archive", "path": "/usr/lib/x/versions/${version}"},
-	}}
-	delivered := deliveredVersions(m)
-	if !slices.Equal(delivered, []string{"31045596c83a"}) {
-		t.Fatalf("%v", delivered)
-	}
-	commit := "1545b00a9f0c"
-	for _, c := range []struct {
-		reported string
-		behind   bool
-	}{
-		{"31045596c83a", false}, // the live case: current, and was called behind
-		{"0123456789ab", true},  // another delivery
-		{"1545b00a", false},     // placed by hand, stamped with the commit
-		{"", false},             // not said
-	} {
-		if got := engineBehind(c.reported, delivered, commit); got != c.behind {
-			t.Errorf("%q behind = %v, want %v", c.reported, got, c.behind)
-		}
-	}
-	if engineBehind("31045596c83a", nil, commit) {
-		t.Error("behind a mesh that holds no delivered build")
-	}
-}
-
-// **Every seat verb a probe calls is one it declares, and one the controller is granted** — derived
-// from the registry, so a probe added with a question the bus would refuse fails here, not live.
-func TestEverySeatVerbAProbeAsksIsGranted(t *testing.T) {
-	granted, err := broker.PermissionsFor(broker.Principal{Kind: broker.KindController, PasswordHash: "x"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	asked := 0
-	for _, p := range probeRegistry {
-		for _, v := range p.Asks {
-			asked++
-			subject := link.NodeSeatToolSubject(v.Seat, v.Verb, "anchor")
-			if !slices.ContainsFunc(granted.Publish, func(pattern string) bool { return subjectMatches(pattern, subject) }) {
-				t.Errorf("%s asks %s.%s and the controller may not publish %s", p.ID, v.Seat, v.Verb, subject)
-			}
-			if !slices.Contains(broker.VerbsTheSelfCheckAsks, v) {
-				t.Errorf("%s asks %s.%s, which broker.VerbsTheSelfCheckAsks does not name", p.ID, v.Seat, v.Verb)
-			}
-		}
-	}
-	if asked == 0 {
-		t.Fatal("no probe asks a seat verb: D8 lost its declaration")
-	}
-	// And a probe asking what it did not declare is refused before anything is sent.
-	ctx := context.WithValue(t.Context(), probeAsksKey{}, probe{ID: "DX"})
-	if _, err := askSeatTool(ctx, nil, "node-intrusion-prevention", "banned", "anchor"); err == nil ||
-		!strings.Contains(err.Error(), "does not declare") {
-		t.Fatalf("an undeclared question was asked: %v", err)
-	}
-}
-
-// subjectMatches is the bus's matching of a permission pattern against a subject.
-func subjectMatches(pattern, subject string) bool {
-	p, s := strings.Split(pattern, "."), strings.Split(subject, ".")
-	for i, tok := range p {
-		if tok == ">" {
-			return len(s) > i
-		}
-		if i >= len(s) || (tok != "*" && tok != s[i]) {
-			return false
-		}
-	}
-	return len(p) == len(s)
-}

cmd/mesh-controller/dry_run_test.go

@@ -1,38 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// A dry run's outcome is looked at, never taken in (novox/hq issue 240). The daemon here holds no
-// store at all, so anything that tried to record or register would fail rather than pass quietly.
-func TestADryRunsOutcomeIsTakenInByNothing(t *testing.T) {
-	err := builds{}.Built(t.Context(), link.BuildResult{
-		ID: "build-1", Repository: "ssh://forge/app.git", Ref: "unreviewed", Module: "app", DryRun: true,
-		Manifest: json.RawMessage(`{"module":"app","version":"1"}`),
-	})
-	if err != nil {
-		t.Fatalf("a dry run's outcome was not simply set aside: %v", err)
-	}
-}
-
-// The mark survives the wire both ways: asked as a dry run, answered as one.
-func TestTheDryRunMarkTravelsWithTheBuild(t *testing.T) {
-	raw, _ := json.Marshal(link.BuildRequest{ID: "build-1", Repository: "r", DryRun: true})
-	var asked link.BuildRequest
-	if err := json.Unmarshal(raw, &asked); err != nil || !asked.DryRun {
-		t.Fatalf("the request lost its dry-run mark: %s", raw)
-	}
-	raw, _ = json.Marshal(link.BuildResult{ID: "build-1", DryRun: true})
-	var answered link.BuildResult
-	if err := json.Unmarshal(raw, &answered); err != nil || !answered.DryRun {
-		t.Fatalf("the outcome lost its dry-run mark: %s", raw)
-	}
-	raw, _ = json.Marshal(link.BuildResult{ID: "build-2"})
-	if string(raw) != `{"id":"build-2","repository":"","on":""}` {
-		t.Fatalf("an ordinary outcome carries a dry-run mark: %s", raw)
-	}
-}

cmd/mesh-controller/durations.go

@@ -1,170 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"flag"
-	"fmt"
-	"os"
-	"slices"
-	"sort"
-	"strings"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// What the core's bounds are set from (novox/hq to-be 45 Phase 0).
-//
-// **A bound is set from what was measured, not from what seemed reasonable.** Phase 1 puts a watchdog
-// on each row of the signals table, and each has a bound: S1 three heartbeat intervals, S2 three times
-// a machine's last apply, S3 a tier's build and apply time, S6 a build's timeout. Marked provisional
-// in the design until a fortnight of these says what the mesh actually takes. Recorded by the serving
-// controller as it hears each — a send's first report, a machine's next word, a plan leaving a tier, a
-// build's outcome — and summarised here per machine, repository or module.
-
-// recordBuildDuration measures one build from its ask to its outcome heard.
-func recordBuildDuration(ctx context.Context, inv *inventory.Inventory, result link.BuildResult, asked time.Time) {
-	if asked.IsZero() || result.ID == "" {
-		return
-	}
-	subject := result.Module
-	if subject == "" {
-		subject = result.Repository
-	}
-	detail := "built"
-	if result.Failed != "" {
-		detail = "failed: " + firstLine(result.Failed)
-	}
-	if err := inv.RecordDuration(ctx, inventory.Duration{Kind: inventory.DurationBuild, Subject: subject,
-		Node: result.On, Ref: result.ID, Started: asked, Took: time.Since(asked), Detail: detail}); err != nil {
-		fmt.Fprintf(os.Stderr, "%s: how long it took could not be recorded: %v\n", result.ID, err)
-	}
-}
-
-// durationSummary is one subject's measurements of one kind.
-type durationSummary struct {
-	Kind    string `json:"kind"`
-	Subject string `json:"subject"`
-	Count   int    `json:"count"`
-	Median  string `json:"median"`
-	P90     string `json:"p90"`
-	Max     string `json:"max"`
-	// Bound is what to-be 45's rule would make of these, where the rule is a multiple of a measured
-	// time: three times the slowest apply (S2), three times the median word interval (S1).
-	Suggests string `json:"suggests,omitempty"`
-}
-
-func summarise(ds []inventory.Duration) []durationSummary {
-	type key struct{ kind, subject string }
-	by := map[key][]time.Duration{}
-	for _, d := range ds {
-		k := key{d.Kind, d.Subject}
-		by[k] = append(by[k], d.Took)
-	}
-	var out []durationSummary
-	for k, took := range by {
-		slices.Sort(took)
-		at := func(q float64) time.Duration { return took[int(q*float64(len(took)-1))] }
-		s := durationSummary{Kind: k.kind, Subject: k.subject, Count: len(took),
-			Median: round(at(0.5)), P90: round(at(0.9)), Max: round(took[len(took)-1])}
-		switch k.kind {
-		case inventory.DurationApply:
-			s.Suggests = "S2 bound max(2m, 3×last apply) ≈ " + round(max(2*time.Minute, 3*at(0.9))) + " at the p90"
-		case inventory.DurationHeartbeatGap:
-			s.Suggests = "S1 bound 3×interval ≈ " + round(3*at(0.5))
-		}
-		out = append(out, s)
-	}
-	sort.Slice(out, func(i, j int) bool {
-		ki, kj := slices.Index(inventory.DurationKinds, out[i].Kind), slices.Index(inventory.DurationKinds, out[j].Kind)
-		if ki != kj {
-			return ki < kj
-		}
-		return out[i].Subject < out[j].Subject
-	})
-	return out
-}
-
-func round(d time.Duration) string {
-	switch {
-	case d < time.Second:
-		return d.Round(time.Millisecond).String()
-	case d < time.Minute:
-		return d.Round(100 * time.Millisecond).String()
-	default:
-		return d.Round(time.Second).String()
-	}
-}
-
-// durationsCommand is `durations`: the summary per kind and subject, or every measurement as data.
-func durationsCommand(ctx context.Context, args []string) error {
-	set := flag.NewFlagSet("durations", flag.ContinueOnError)
-	kind := set.String("kind", "", "one kind: "+strings.Join(inventory.DurationKinds, ", "))
-	days := set.Int("days", 14, "how many days back")
-	asJSON := set.Bool("json", false, "the summary as data")
-	all := set.Bool("all", false, "every measurement rather than the summary")
-	if _, err := parseAround(set, args); err != nil {
-		return err
-	}
-	if *kind != "" && !slices.Contains(inventory.DurationKinds, *kind) {
-		return fmt.Errorf("%q is not a kind of duration: %s", *kind, strings.Join(inventory.DurationKinds, ", "))
-	}
-	open, err := openStores(ctx)
-	if err != nil {
-		return err
-	}
-	defer open.Close()
-	ds, err := open.inventory.Durations(ctx, *kind, time.Now().Add(-time.Duration(*days)*24*time.Hour))
-	if err != nil {
-		return err
-	}
-	if *all {
-		body, err := json.MarshalIndent(ds, "", "  ")
-		if err != nil {
-			return err
-		}
-		fmt.Println(string(body))
-		return nil
-	}
-	summary := summarise(ds)
-	if *asJSON {
-		body, err := json.MarshalIndent(map[string]any{"days": *days, "durations": summary}, "", "  ")
-		if err != nil {
-			return err
-		}
-		fmt.Println(string(body))
-		return nil
-	}
-	if len(summary) == 0 {
-		fmt.Printf("nothing measured in the last %d day(s): the serving controller records apply, heartbeat-gap, "+
-			"plan-tier and build durations as it hears them\n", *days)
-		return nil
-	}
-	fmt.Printf("durations over the last %d day(s) — what the core's bounds are set from (to-be 45 Phase 0)\n\n", *days)
-	fmt.Printf("  %-14s %-28s %6s %10s %10s %10s\n", "kind", "of", "count", "median", "p90", "max")
-	for _, s := range summary {
-		fmt.Printf("  %-14s %-28s %6d %10s %10s %10s\n", s.Kind, s.Subject, s.Count, s.Median, s.P90, s.Max)
-		if s.Suggests != "" {
-			fmt.Printf("  %-14s %-28s %s\n", "", "", s.Suggests)
-		}
-	}
-	return nil
-}
-
-// forgettingOldDurations removes what is older than a month, at start and daily after.
-func forgettingOldDurations(ctx context.Context, inv *inventory.Inventory) {
-	for {
-		if n, err := inv.ForgetOldDurations(ctx); err != nil {
-			fmt.Fprintf(os.Stderr, "durations older than %s could not be removed: %v\n", inventory.DurationsKeptFor, err)
-		} else if n > 0 {
-			fmt.Printf("removed %d duration(s) older than %s\n", n, inventory.DurationsKeptFor)
-		}
-		select {
-		case <-ctx.Done():
-			return
-		case <-time.After(24 * time.Hour):
-		}
-	}
-}

cmd/mesh-controller/epoch_send_test.go

@@ -1,115 +0,0 @@
-package main
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// A declaration carries the lease's epoch (novox/hq to-be 45 §6) — to a machine whose node-engine said
-// it reads one, and to no other: an older node-engine refuses a key it does not know, whole.
-
-// bodiesDelivery records each send as the mesh does, and keeps the bodies.
-type bodiesDelivery struct {
-	recordedDelivery
-	bodies map[string][]byte
-}
-
-func (b *bodiesDelivery) declare(ctx context.Context, s readyNode, body []byte) (string, error) {
-	b.bodies[s.node] = body
-	return b.recordedDelivery.declare(ctx, s, body)
-}
-
-func TestAMachineIsSentTheEpochOnlyOnceItSaysItReadsOne(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	inv := open.inventory
-	epoch := uint64(57)
-	was := epochForActs
-	epochForActs = func(context.Context) (uint64, error) { return epoch, nil }
-	t.Cleanup(func() { epochForActs = was })
-
-	anchor, err := inv.NodeByName(ctx, "anchor")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := inv.RecordReadsEpoch(ctx, anchor.ID, true); err != nil {
-		t.Fatal(err)
-	}
-	gens, err := generators(ctx, open)
-	if err != nil {
-		t.Fatal(err)
-	}
-	d := &bodiesDelivery{recordedDelivery: recordedDelivery{inv: inv}, bodies: map[string][]byte{}}
-	if _, err := sendRound(ctx, open, []string{"anchor", "laptop"}, composeForPush(open, gens), d, "", nil); err != nil {
-		t.Fatal(err)
-	}
-	carried := func(node string) (epoch float64, has bool) {
-		var envelope map[string]any
-		if err := json.Unmarshal(d.bodies[node], &envelope); err != nil {
-			t.Fatal(err)
-		}
-		epoch, has = envelope["epoch"].(float64)
-		return epoch, has
-	}
-	if e, has := carried("anchor"); !has || e != 57 {
-		t.Fatalf("the machine that reads an epoch was sent %v: %s", e, d.bodies["anchor"])
-	}
-	if _, has := carried("laptop"); has {
-		t.Fatalf("a machine that never said it reads an epoch was sent one: %s", d.bodies["laptop"])
-	}
-
-	// A new holder of the lease is not a change of the machine: neither reads as behind.
-	epoch = 58
-	would, err := wouldSend(ctx, open, mustNodes(t, open))
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, node := range []string{"anchor", "laptop"} {
-		sent, err := inv.Outstanding(ctx, node)
-		if err != nil {
-			t.Fatal(err)
-		}
-		if would[node] != sent {
-			t.Fatalf("%s reads as behind after the lease changed hands, with nothing else changed", node)
-		}
-	}
-}
-
-// A process that may not act composes nothing and sends nothing: its number is not taken.
-func TestNothingIsComposedOrSentWithoutTheLease(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	was := epochForActs
-	epochForActs = func(context.Context) (uint64, error) { return 0, errors.New("this controller lost the lease") }
-	t.Cleanup(func() { epochForActs = was })
-	gens, err := generators(ctx, open)
-	if err != nil {
-		t.Fatal(err)
-	}
-	d := &bodiesDelivery{recordedDelivery: recordedDelivery{inv: open.inventory}, bodies: map[string][]byte{}}
-	refused, err := sendRound(ctx, open, []string{"anchor"}, composeForPush(open, gens), d, "", nil)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(d.bodies) != 0 || len(refused) != 1 || !strings.Contains(refused[0], "lost the lease") {
-		t.Fatalf("a controller without the lease composed %d and refused %v", len(d.bodies), refused)
-	}
-	anchor, _ := open.inventory.NodeByName(ctx, "anchor")
-	if seq, _ := open.inventory.Sequence(ctx, anchor.ID); seq != 0 {
-		t.Fatalf("a controller without the lease took sequence %d", seq)
-	}
-
-	// And at the send itself: the gate every declaration passes.
-	gate := link.ActingGate
-	link.ActingGate = func(context.Context) error { return errors.New("this controller lost the lease") }
-	t.Cleanup(func() { link.ActingGate = gate })
-	if err := link.Declare(ctx, nil, nil, "anchor", []byte(`{"declaration":1}`), 0); err == nil ||
-		!strings.Contains(err.Error(), "lost the lease") {
-		t.Fatalf("a declaration was let through the gate: %v", err)
-	}
-}

cmd/mesh-controller/facts.go

@@ -1,662 +0,0 @@
-package main
-
-import (
-	"context"
-	"crypto/sha256"
-	"encoding/json"
-	"errors"
-	"flag"
-	"fmt"
-	"os"
-	"slices"
-	"sort"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/novox/mesh-host/validate"
-
-	"github.com/novox/mesh-controller/internal/artifacts"
-	"github.com/novox/mesh-controller/internal/broker"
-	"github.com/novox/mesh-controller/internal/builder"
-	"github.com/novox/mesh-controller/internal/catalogue"
-	snapshot "github.com/novox/mesh-controller/internal/facts"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// The facts snapshot (novox/hq to-be 45 §9, ADR 0227 rule 9): what a merge check needs to judge a change
-// against the mesh that runs, written by the controller to the artifact store, where the build seat reads
-// it. internal/facts says what it holds and what it never holds; this composes it from the store and
-// keeps it current.
-
-// factsEvery is how often the snapshot is composed. It is kept when it moved — a machine, an
-// assignment, a seat, a setting, a build — or once a day when nothing did, so its age says the
-// controller is still writing it (S14).
-var factsEvery = 10 * time.Minute
-
-// factsDaily is how old a snapshot of an unchanged mesh may grow before it is written again.
-const factsDaily = 24 * time.Hour
-
-// factsStaleAfter is S14's bound: a snapshot older than this is one no check should be fed.
-const factsStaleAfter = 48 * time.Hour
-
-// factsExport is what this controller knows of the snapshot it keeps: when the newest was taken, its
-// content, and the last attempt's error.
-type factsExport struct {
-	mu      sync.Mutex
-	taken   time.Time
-	content string
-	digest  string
-	err     error
-	began   time.Time
-}
-
-// exportedFacts is this process's export, read by S14.
-var exportedFacts = &factsExport{}
-
-func (e *factsExport) last() (taken time.Time, digest string, began time.Time, err error) {
-	e.mu.Lock()
-	defer e.mu.Unlock()
-	return e.taken, e.digest, e.began, e.err
-}
-
-func (e *factsExport) kept(f snapshot.Facts, content, digest string) {
-	e.mu.Lock()
-	defer e.mu.Unlock()
-	e.taken, e.content, e.digest, e.err = f.Taken, content, digest, nil
-}
-
-func (e *factsExport) failed(err error) {
-	e.mu.Lock()
-	defer e.mu.Unlock()
-	e.err = err
-}
-
-// exportingFacts keeps the snapshot current for as long as this controller holds the lease: ctx ends
-// when it stops acting.
-func exportingFacts(ctx context.Context, open *stores, busVersion func() string) {
-	exportedFacts.mu.Lock()
-	exportedFacts.began = time.Now()
-	exportedFacts.mu.Unlock()
-	// What the store holds already, so a restarted controller neither writes an unchanged snapshot again
-	// nor reads its age as zero.
-	if address, err := factsStore(ctx, open); err == nil {
-		if body, digest, err := (artifacts.Store{Address: address}).GetTagged(ctx, snapshot.Repository, snapshot.Tag); err == nil {
-			if f, err := snapshot.Decode(body); err == nil {
-				content, _ := f.Content()
-				exportedFacts.kept(f, content, digest)
-			}
-		}
-	}
-	failing := ""
-	first := time.NewTimer(time.Minute)
-	defer first.Stop()
-	tick := time.NewTicker(factsEvery)
-	defer tick.Stop()
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-first.C:
-		case <-tick.C:
-		}
-		wrote, err := exportFacts(ctx, open, busVersion(), false)
-		why := ""
-		if err != nil {
-			why = err.Error()
-			exportedFacts.failed(err)
-		}
-		if why != failing {
-			if why != "" {
-				fmt.Printf("the facts snapshot cannot be kept: %s\n", why)
-			} else {
-				fmt.Println("the facts snapshot is kept again")
-			}
-			failing = why
-		}
-		if wrote != "" {
-			fmt.Printf("the facts snapshot moved and is kept as %s\n", short(strings.TrimPrefix(wrote, "sha256:")))
-		}
-	}
-}
-
-// exportFacts composes the snapshot and keeps it when it moved, or when the one kept is a day old, or
-// when told to. Answers the digest it kept, empty when it kept nothing.
-func exportFacts(ctx context.Context, open *stores, busVersion string, force bool) (string, error) {
-	f, err := gatherFacts(ctx, open, busVersion)
-	if err != nil {
-		return "", err
-	}
-	content, err := f.Content()
-	if err != nil {
-		return "", err
-	}
-	exportedFacts.mu.Lock()
-	unchanged := content == exportedFacts.content && time.Since(exportedFacts.taken) < factsDaily
-	exportedFacts.mu.Unlock()
-	if unchanged && !force {
-		return "", nil
-	}
-	body, err := f.Encode()
-	if err != nil {
-		return "", err
-	}
-	address, err := factsStore(ctx, open)
-	if err != nil {
-		return "", err
-	}
-	digest, err := (artifacts.Store{Address: address}).PutTagged(ctx, snapshot.Repository, snapshot.Tag, snapshot.MediaType, body)
-	if err != nil && digest == "" {
-		return "", err
-	}
-	exportedFacts.kept(f, content, digest)
-	return digest, err
-}
-
-// factsStore is the artifact store as this controller reaches it.
-func factsStore(ctx context.Context, open *stores) (string, error) {
-	shelf, err := open.inventory.Catalogue(ctx)
-	if err != nil {
-		return "", err
-	}
-	address, err := artifactStoreAddress(ctx, open.inventory, shelf, "")
-	if err != nil {
-		return "", err
-	}
-	if address == "" {
-		return "", errors.New("the artifact store is not on the private network, so there is nowhere to keep the facts")
-	}
-	return address, nil
-}
-
-// gatherFacts composes one snapshot from the store: read only, nothing made, nothing sent.
-func gatherFacts(ctx context.Context, open *stores, busVersion string) (snapshot.Facts, error) {
-	inv := open.inventory
-	f := snapshot.Facts{Format: snapshot.Format, Taken: time.Now().UTC(), Controller: snapshot.Build{Version: version}}
-	f.Versions.Bus = busVersion
-	storeVersion, err := inv.ServerVersion(ctx)
-	if err != nil {
-		return snapshot.Facts{}, fmt.Errorf("the store will not say its version: %w", err)
-	}
-	f.Versions.Store = storeVersion
-
-	nodes, err := inv.Nodes(ctx)
-	if err != nil {
-		return snapshot.Facts{}, err
-	}
-	overlays, err := inv.Overlays(ctx)
-	if err != nil {
-		return snapshot.Facts{}, err
-	}
-	place := map[string]inventory.Overlay{}
-	for _, o := range overlays {
-		place[o.Name] = o
-	}
-	entries, err := inv.Catalogued(ctx)
-	if err != nil {
-		return snapshot.Facts{}, err
-	}
-	shelf := map[string]catalogue.Manifest{}
-	for _, e := range entries {
-		shelf[e.Manifest.Module] = e.Manifest
-	}
-	current, err := inv.CurrentBuilds(ctx)
-	if err != nil {
-		return snapshot.Facts{}, err
-	}
-	read, err := readForPlanning(ctx, inv)
-	if err != nil {
-		return snapshot.Facts{}, err
-	}
-	edges, err := inv.Dependencies(ctx)
-	if err != nil {
-		return snapshot.Facts{}, err
-	}
-	holdings, err := inv.Holdings(ctx)
-	if err != nil {
-		return snapshot.Facts{}, err
-	}
-
-	// **Every name first**, so text read afterwards — a setting naming a machine, a problem naming a
-	// site — has it replaced wherever it appears.
-	scrub := snapshot.NewScrubber()
-	domains := map[string]string{}
-	for _, n := range nodes {
-		scrub.Machine(n.Name)
-		if n.Account != "" && n.Account != "root" {
-			scrub.Account(n.Account)
-		}
-		d, err := inv.PublicDomainOf(ctx, n.Name)
-		if err != nil {
-			return snapshot.Facts{}, err
-		}
-		domains[n.Name] = scrub.Domain(d)
-	}
-	for _, o := range overlays {
-		scrub.Site(o.Site)
-	}
-
-	// What a merge check runs in and reads beside it, as the build seat would be asked for it.
-	if held, err := inv.Held(ctx); err == nil {
-		for language, reference := range builder.ToolchainsOf(held) {
-			if f.Versions.Toolchains == nil {
-				f.Versions.Toolchains = map[string]string{}
-			}
-			f.Versions.Toolchains[language] = catalogue.Recorded(reference)
-		}
-	} else {
-		return snapshot.Facts{}, err
-	}
-	for _, e := range entries {
-		if dir, core := coreModules[e.Manifest.Module]; core && !e.Provided && e.Source.Repository != "" {
-			for d, ref := range besideRefs(dir, current[e.Manifest.Module].Commit) {
-				if f.Beside == nil {
-					f.Beside = map[string]string{}
-				}
-				f.Beside[d] = ref
-			}
-		}
-	}
-
-	if c, ok := current["mesh-controller"]; ok {
-		f.Controller.Commit = c.Commit
-	}
-
-	gens, gensErr := generators(ctx, open)
-	hostShelf := shelf[hostModule]
-	meshWide := map[string]bool{}
-	engines := map[string]bool{}
-	for _, n := range nodes {
-		m := snapshot.Machine{Name: scrub.Machine(n.Name), Length: len(n.Name), Adopted: n.Adopted,
-			AccountHome: scrub.Text(n.AccountHome), NodeEngine: n.HostVersion, PublicDomain: domains[n.Name],
-			AgentAccount: scrub.Account(n.AgentAccount), AgentAccountHome: scrub.Text(n.AgentAccountHome)}
-		switch n.Account {
-		case "", "root":
-			m.Account = n.Account
-		default:
-			m.Account = scrub.Account(n.Account)
-		}
-		if n.HostVersion != "" {
-			engines[n.HostVersion] = true
-		}
-		m.System = systemOf(hostShelf, n.HostVersion)
-		m.Libc = libcOf(m.System)
-		reported, err := inv.DescribedOf(ctx, n.Name)
-		if err != nil {
-			return snapshot.Facts{}, err
-		}
-		m.Architecture, m.Kernel = reported.Architecture, reported.Kernel
-		outward, err := inv.OutwardLinksOf(ctx, n.Name)
-		if err != nil {
-			return snapshot.Facts{}, err
-		}
-		for _, l := range outward {
-			m.OutwardLinks = append(m.OutwardLinks, scrub.Text(l))
-		}
-		capabilities, err := inv.Profile(ctx, n.Name)
-		if err != nil {
-			return snapshot.Facts{}, err
-		}
-		for _, c := range capabilities {
-			kept := snapshot.Capability{Name: c.Name, Present: c.Present}
-			// The detail only where it is a version: everything else a detector says — a ruleset, a
-			// device, a path — is the machine's own business and no check reads it.
-			if c.Present && (c.Name == "container-runtime" || c.Name == "package-manager") {
-				kept.Detail = scrub.Text(c.Detail)
-			}
-			m.Capabilities = append(m.Capabilities, kept)
-		}
-		if o, ok := place[n.Name]; ok {
-			m.Site, m.Hub, m.Public, m.OnNetwork = scrub.Site(o.Site), o.Hub, o.Endpoint != "", o.Address != ""
-		}
-		assigned, err := inv.Assigned(ctx, n.Name)
-		if err != nil {
-			return snapshot.Facts{}, err
-		}
-		m.Assigned = assigned
-		sent, known, err := inv.SentBuilds(ctx, n.Name)
-		if err != nil {
-			return snapshot.Facts{}, err
-		}
-		if known && slices.Contains(assigned, broker.RuntimeModule) {
-			m.NodeTools = sent[broker.RuntimeModule]
-		}
-		pins, err := inv.PinsFor(ctx, n.Name)
-		if err != nil {
-			return snapshot.Facts{}, err
-		}
-		for provision, c := range pins {
-			m.Pins = append(m.Pins, snapshot.Pin{Provision: provision, Machine: scrub.Machine(c.Node), Module: c.Module})
-		}
-		for _, module := range assigned {
-			held, err := inv.SecretsOf(ctx, n.Name, module)
-			if err != nil {
-				return snapshot.Facts{}, err
-			}
-			for _, h := range held {
-				if h.Origin == inventory.OriginAccepted {
-					m.Accepted = append(m.Accepted, snapshot.Accepted{Module: module, Name: h.Name,
-						Provider: scrub.Machine(h.Provider), Local: h.Local})
-				}
-			}
-			layers, err := inv.SettingsFor(ctx, n.Name, module)
-			if err != nil {
-				return snapshot.Facts{}, err
-			}
-			for _, layer := range layers {
-				if layer.From == catalogue.MeshWideLayer {
-					if !meshWide[module] {
-						meshWide[module] = true
-						f.Settings = append(f.Settings, snapshot.Settings{Module: module, Values: scrub.Values(layer.Values)})
-					}
-					continue
-				}
-				m.Settings = append(m.Settings, snapshot.Settings{Module: module, Values: scrub.Values(layer.Values)})
-			}
-		}
-		m.Declaration = declarationFacts(ctx, open, n.Name, gens, gensErr, scrub)
-		if ctx.Err() != nil {
-			return snapshot.Facts{}, ctx.Err()
-		}
-		f.Machines = append(f.Machines, m)
-	}
-	for e := range engines {
-		f.Versions.NodeEngines = append(f.Versions.NodeEngines, e)
-	}
-
-	// Seats and their holders, and from them the roles a machine is named by.
-	roles := map[string][]string{}
-	seats := map[string]*snapshot.Seat{}
-	for _, h := range holdings {
-		key := h.Claim + "\x00" + h.Scope
-		s, ok := seats[key]
-		if !ok {
-			s = &snapshot.Seat{Name: h.Claim, Scope: h.Scope}
-			seats[key] = s
-		}
-		s.Holders = append(s.Holders, snapshot.Holder{Machine: scrub.Machine(h.Node), Module: h.Module})
-		if h.Scope == catalogue.ScopeMesh {
-			role := "holds " + h.Claim
-			if h.Claim == catalogue.ControllerSeatName {
-				role = "the control node"
-			}
-			roles[h.Node] = append(roles[h.Node], role)
-		}
-	}
-	for _, s := range seats {
-		f.Seats = append(f.Seats, *s)
-	}
-	for i := range f.Machines {
-		for _, n := range nodes {
-			if scrub.Machine(n.Name) != f.Machines[i].Name {
-				continue
-			}
-			f.Machines[i].Roles = roles[n.Name]
-			if f.Machines[i].Hub {
-				f.Machines[i].Roles = append(f.Machines[i].Roles, "the hub")
-			}
-		}
-	}
-
-	// Every module, as the mesh holds it, and where it is built from.
-	newest := map[string]inventory.Source{}
-	count := map[string]int{}
-	for _, e := range entries {
-		raw, err := json.Marshal(e.Manifest)
-		if err != nil {
-			return snapshot.Facts{}, err
-		}
-		mod := snapshot.Module{Name: e.Manifest.Module, Repository: snapshot.RepositoryName(e.Source.Repository), Path: e.Source.Path,
-			Commit: e.Source.BuiltFrom, Provided: e.Provided, RollOut: current[e.Manifest.Module].RollOut,
-			Manifest: raw}
-		for _, r := range read[e.Manifest.Module] {
-			// The module's own build source is said apart: a gate that predates it would read an own
-			// entry among Reads as a context of its own repository.
-			if r.Own {
-				if len(r.Paths) > 0 {
-					mod.Sources = append(mod.Sources, snapshot.BuildSource{Own: true, Paths: r.Paths})
-				}
-				continue
-			}
-			mod.Reads = append(mod.Reads, snapshot.RepositoryName(r.Repository))
-			if len(r.Paths) > 0 {
-				mod.Sources = append(mod.Sources, snapshot.BuildSource{Repository: snapshot.RepositoryName(r.Repository), Paths: r.Paths})
-			}
-		}
-		f.Modules = append(f.Modules, mod)
-		if e.Provided || e.Source.Repository == "" {
-			continue
-		}
-		count[e.Source.Repository]++
-		if was, ok := newest[e.Source.Repository]; !ok || e.Source.Seen.After(was.Seen) {
-			newest[e.Source.Repository] = e.Source
-		}
-	}
-	for repository, s := range newest {
-		commit := s.Head
-		if commit == "" {
-			commit = s.BuiltFrom
-		}
-		f.Sources = append(f.Sources, snapshot.Source{Repository: snapshot.RepositoryName(repository), Commit: commit,
-			Modules: count[repository]})
-	}
-	for _, e := range edges {
-		f.Edges = append(f.Edges, snapshot.Edge{From: e.From, To: e.To, Kind: e.Kind})
-	}
-	f.Sorted()
-	return f, nil
-}
-
-// declarationFacts is how one machine's declaration composes now, as the next push would compose it and
-// without making anything (D1's composition), and whether the node-engine's validator takes it.
-func declarationFacts(ctx context.Context, open *stores, node string, gens map[string]catalogue.Generator,
-	gensErr error, scrub *snapshot.Scrubber) snapshot.Declaration {
-	var d snapshot.Declaration
-	if gensErr != nil {
-		d.Problems = []string{scrub.Text("the private network cannot be computed: " + oneLine(gensErr.Error()))}
-		return d
-	}
-	declared, problems, err := composedAndValidated(ctx, open, node, gens, Foreseeing)
-	if err != nil {
-		d.Problems = []string{scrub.Text(oneLine(err.Error()))}
-		return d
-	}
-	for _, p := range problems {
-		d.Problems = append(d.Problems, scrub.Text(p))
-	}
-	d.Composes = len(problems) == 0
-	if body, err := declared.Body(); err == nil {
-		d.Digest = fmt.Sprintf("sha256:%x", sha256.Sum256(body))
-	}
-	// Scrubbed like every other word: a resource is named after the machine a grant is for.
-	for _, r := range resourceNames(declared.Resources) {
-		d.Resources = append(d.Resources, scrub.Text(r))
-	}
-	for module, why := range declared.leftOutWhy {
-		if d.LeftOut == nil {
-			d.LeftOut = map[string]string{}
-		}
-		d.LeftOut[module] = scrub.Text(why)
-	}
-	for _, o := range declared.withheld {
-		d.Withheld = append(d.Withheld, scrub.Text(o.String()))
-	}
-	for _, u := range declared.unbound {
-		d.Unbound = append(d.Unbound, scrub.Text(u.String()))
-	}
-	sort.Strings(d.Withheld)
-	sort.Strings(d.Unbound)
-	return d
-}
-
-// composedAndValidated composes one machine's declaration — as a push would (Allocating) or as the next
-// push will without making anything (Foreseeing) — with the order it was last sent, and runs the
-// node-engine's own validator over the body. An error is that it did not compose; problems are what the
-// validator refuses.
-func composedAndValidated(ctx context.Context, open *stores, node string, gens map[string]catalogue.Generator,
-	choosing Choosing) (sendable, []string, error) {
-	plan, settings, err := planFor(ctx, open, node)
-	if err != nil {
-		return sendable{}, nil, err
-	}
-	declared, err := declarationWith(ctx, open, node, plan, settings, gens, choosing)
-	if err != nil {
-		return sendable{}, nil, err
-	}
-	record, err := open.inventory.NodeByName(ctx, node)
-	if err != nil {
-		return sendable{}, nil, err
-	}
-	if declared.Sequence, err = open.inventory.Sequence(ctx, record.ID); err != nil {
-		return sendable{}, nil, err
-	}
-	if declared.Epoch, err = open.inventory.SentEpoch(ctx, record.ID); err != nil {
-		return sendable{}, nil, err
-	}
-	// And the generation it was last sent, as the would-send is (novox/hq issue 234).
-	if declared.Generation, err = open.inventory.SentGeneration(ctx, record.ID); err != nil {
-		return sendable{}, nil, err
-	}
-	body, err := declared.Body()
-	if err != nil {
-		return sendable{}, nil, err
-	}
-	return declared, validate.Declaration(body), nil
-}
-
-// resourceNames are a declaration's resources as `type:id`, sorted.
-func resourceNames(resources []map[string]any) []string {
-	out := make([]string, 0, len(resources))
-	for _, r := range resources {
-		kind, _ := r["type"].(string)
-		id, _ := r["id"].(string)
-		out = append(out, kind+":"+id)
-	}
-	sort.Strings(out)
-	return out
-}
-
-// systemOf is the system a node-engine of that version was built for, read from the build the mesh
-// holds: the artifact a resource delivered into `versions/<version>` came from is named for its system
-// (`host-arch`). Empty when the version is not a delivered one — an engine placed by hand.
-func systemOf(host catalogue.Manifest, version string) string {
-	if version == "" {
-		return ""
-	}
-	for _, r := range host.Resources {
-		path, _ := r["path"].(string)
-		if !strings.HasSuffix(path, "/versions/"+version) {
-			continue
-		}
-		source, _ := r["source"].(string)
-		for _, part := range strings.Split(source, "/") {
-			if system, ok := strings.CutPrefix(part, "host-"); ok && system != "" {
-				return system
-			}
-		}
-	}
-	return ""
-}
-
-// libcOf is the C library of a system the node-engine is built for.
-func libcOf(system string) string {
-	switch system {
-	case "arch":
-		return "glibc"
-	case "alpine":
-		return "musl"
-	case "android":
-		return "bionic"
-	}
-	return ""
-}
-
-// factsCommand is `facts`: what the controller keeps, and keeping it now.
-//
-//	facts                 the snapshot the artifact store holds: when, which, how many machines
-//	facts show            the same, whole, as JSON
-//	facts export          compose and keep one now
-//	facts compose         compose one and print it, keeping nothing
-func factsCommand(ctx context.Context, args []string) error {
-	set := flag.NewFlagSet("facts", flag.ContinueOnError)
-	rest, err := parseAround(set, args)
-	if err != nil {
-		return err
-	}
-	what := ""
-	if len(rest) > 0 {
-		what = rest[0]
-	}
-	open, err := openStores(ctx)
-	if err != nil {
-		return err
-	}
-	defer open.Close()
-	switch what {
-	case "", "show":
-		address, err := factsStore(ctx, open)
-		if err != nil {
-			return err
-		}
-		body, digest, err := (artifacts.Store{Address: address}).GetTagged(ctx, snapshot.Repository, snapshot.Tag)
-		if err != nil {
-			return err
-		}
-		if what == "show" {
-			_, err := os.Stdout.Write(body)
-			return err
-		}
-		f, err := snapshot.Decode(body)
-		if err != nil {
-			return err
-		}
-		fmt.Printf("the facts snapshot kept as %s:%s is %s, taken %s (%s ago) by controller %s\n",
-			snapshot.Repository, snapshot.Tag, short(strings.TrimPrefix(digest, "sha256:")),
-			f.Taken.Format(time.RFC3339), ago(time.Since(f.Taken)), orNone(f.Controller.Commit))
-		fmt.Printf("  %d machine(s), %d module(s), %d seat(s); the longest machine name is %d characters\n",
-			len(f.Machines), len(f.Modules), len(f.Seats), f.Longest())
-		fmt.Printf("  the bus runs %s, the store %s\n", orNone(f.Versions.Bus), orNone(f.Versions.Store))
-		for _, m := range f.Machines {
-			state := "composes"
-			if !m.Declaration.Composes {
-				state = "does NOT compose: " + strings.Join(m.Declaration.Problems, "; ")
-			}
-			fmt.Printf("  %-12s %s; %d module(s); %s\n", m.Name, m.Described(), len(m.Assigned), state)
-		}
-		return nil
-	case "export", "compose":
-		busVersion := ""
-		if server, err := connectLink(ctx, nil, nil, nil); err == nil {
-			busVersion = busVersionOf(server)
-			server.Close()
-		}
-		if what == "compose" {
-			f, err := gatherFacts(ctx, open, busVersion)
-			if err != nil {
-				return err
-			}
-			body, err := f.Encode()
-			if err != nil {
-				return err
-			}
-			_, err = os.Stdout.Write(append(body, '\n'))
-			return err
-		}
-		digest, err := exportFacts(ctx, open, busVersion, true)
-		if err != nil {
-			return err
-		}
-		fmt.Printf("the facts snapshot is kept as %s:%s, %s\n", snapshot.Repository, snapshot.Tag, digest)
-		return nil
-	}
-	return fmt.Errorf("facts [show|export|compose], not %q", what)
-}
-
-// busVersionOf is the bus server's release, as it told this connection.
-func busVersionOf(server *link.Server) string {
-	if bus, ok := server.Bus().(link.OverNATS); ok && bus.Conn != nil {
-		return bus.Conn.ConnectedServerVersion()
-	}
-	return ""
-}

cmd/mesh-controller/facts_test.go

@@ -1,137 +0,0 @@
-package main
-
-import (
-	"regexp"
-	"strings"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	snapshot "github.com/novox/mesh-controller/internal/facts"
-)
-
-// The facts snapshot (novox/hq to-be 45 §9): composed from the store, every machine under a pseudonym
-// of its name's length, and nothing of the installation in it — no secret, no address, no name.
-
-// aMeshWithSecrets is aMesh with a provider and its consumers, a value given by hand, settings carrying
-// a password, an address and a machine's name, and a push's worth of credentials made.
-func aMeshWithSecrets(t *testing.T) (*stores, []string) {
-	t.Helper()
-	open := aMesh(t)
-	ctx := t.Context()
-	register(t, open, catalogue.Manifest{Module: "objects", Version: "1",
-		Provides: []catalogue.Offer{{Name: "s3-bucket", Scope: catalogue.ScopeMesh,
-			Identity: &catalogue.OfferIdentity{Max: 20, In: "an S3 access key"}}},
-		Receives: map[string]string{"s3-bucket": "/var/lib/mesh/objects/mesh.json"}})
-	register(t, open, catalogue.Manifest{Module: "files", Version: "1", Requires: []string{"s3-bucket"},
-		Resources: []map[string]any{{"id": "config", "type": "file", "path": "/etc/files/config.json",
-			"mode": "0600", "content": "{}", "merge": "json"}}})
-	for _, a := range [][2]string{{"anchor", "objects"}, {"laptop", "files"}} {
-		if _, err := assign(ctx, open, a[0], a[1]); err != nil {
-			t.Fatalf("assign %s %s: %v", a[0], a[1], err)
-		}
-	}
-	secrets := []string{"Hunter2-Is-Not-A-Password-9f8e7d", "0123456789abcdefABCDEF0123456789zz"}
-	if err := open.inventory.SetSettings(ctx, "", "files", map[string]any{
-		"admin_password": secrets[0], "upstream": "10.77.0.9", "hub": "anchor"}); err != nil {
-		t.Fatal(err)
-	}
-	if err := open.inventory.SetSettings(ctx, "laptop", "files", map[string]any{
-		"note": "reach me at 192.168.1.135, token " + secrets[1]}); err != nil {
-		t.Fatal(err)
-	}
-	// A push's worth of composition, which makes the pair credential the consumer is sent.
-	gens, err := generators(ctx, open)
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, node := range []string{"laptop", "anchor"} {
-		if _, _, err := composedAndValidated(ctx, open, node, gens, Allocating); err != nil {
-			t.Fatalf("%s does not compose: %v", node, err)
-		}
-	}
-	issued, err := open.inventory.SecretsFrom(ctx, "anchor")
-	if err != nil || len(issued) == 0 {
-		t.Fatalf("no credential was made for the consumer: %v", err)
-	}
-	for _, s := range issued {
-		// Sealed, never kept plain (ADR 0004): the sealed blobs are what the store holds, and none may leave.
-		secrets = append(secrets, s.ForConsumer, s.ForProvider)
-	}
-	return open, secrets
-}
-
-func TestTheFactsCarryNoSecretNoAddressAndNoName(t *testing.T) {
-	open, secrets := aMeshWithSecrets(t)
-	f, err := gatherFacts(t.Context(), open, "2.11.17")
-	if err != nil {
-		t.Fatal(err)
-	}
-	body, err := f.Encode()
-	if err != nil {
-		t.Fatal(err)
-	}
-	text := string(body)
-	for _, s := range secrets {
-		if s != "" && strings.Contains(text, s) {
-			t.Errorf("a secret is in the snapshot: %q", s)
-		}
-	}
-	for _, leaked := range []string{"anchor", "laptop", "10.77.0.", "192.168.1.135", ".example:51820"} {
-		if strings.Contains(text, leaked) {
-			t.Errorf("%q is in the snapshot", leaked)
-		}
-	}
-	// Every address it carries is a documentation address.
-	for _, a := range regexp.MustCompile(`\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b`).FindAllString(text, -1) {
-		if !strings.HasPrefix(a, "192.0.2.") && !strings.HasPrefix(a, "198.51.100.") && !strings.HasPrefix(a, "203.0.113.") {
-			t.Errorf("%s is an address outside the documentation ranges", a)
-		}
-	}
-
-	// What a check needs is there: every machine, its length, its modules, its declaration composing.
-	if len(f.Machines) != 2 || f.Longest() != len("laptop") {
-		t.Fatalf("machines %+v, longest %d", f.Machines, f.Longest())
-	}
-	anchor := snapshot.Pseudonym("machine", "anchor")
-	m, ok := f.Machine(anchor)
-	if !ok || !m.Hub || !strings.Contains(m.Described(), "the hub") || len(m.Name) != len("anchor") {
-		t.Fatalf("the anchor reads as %+v", m)
-	}
-	if !m.Declaration.Composes || m.Declaration.Digest == "" || len(m.Declaration.Resources) == 0 {
-		t.Errorf("the anchor's declaration reads as %+v", m.Declaration)
-	}
-	laptop, _ := f.Machine(snapshot.Pseudonym("machine", "laptop"))
-	if strings.Join(laptop.Assigned, ",") != "files,mesh-wireguard" && !strings.Contains(strings.Join(laptop.Assigned, ","), "files") {
-		t.Errorf("the laptop's assignments read as %v", laptop.Assigned)
-	}
-	var meshWide map[string]any
-	for _, s := range f.Settings {
-		if s.Module == "files" {
-			meshWide = s.Values
-		}
-	}
-	if meshWide["admin_password"] != snapshot.Withheld || meshWide["hub"] != anchor {
-		t.Errorf("the mesh-wide settings read as %v", meshWide)
-	}
-	if f.Versions.Bus != "2.11.17" || f.Versions.Store == "" {
-		t.Errorf("versions read as %+v", f.Versions)
-	}
-	var objects bool
-	for _, mod := range f.Modules {
-		objects = objects || mod.Name == "objects" && len(mod.Manifest) > 0
-	}
-	if !objects {
-		t.Error("the modules the mesh holds are not in the snapshot")
-	}
-
-	// And an unchanged mesh is the same content a moment later.
-	again, err := gatherFacts(t.Context(), open, "2.11.17")
-	if err != nil {
-		t.Fatal(err)
-	}
-	a, _ := f.Content()
-	b, _ := again.Content()
-	if a != b {
-		t.Error("two snapshots of an unchanged mesh differ, so it would be written again every ten minutes")
-	}
-}

cmd/mesh-controller/failed_wait_provider_test.go

@@ -1,66 +0,0 @@
-package main
-
-import (
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// A provider whose wait fails the controller's check lists who waits on it (novox/hq issue 450).
-//
-// A wait that does not check out is judged unhealthy (ADR 0283 decision 3), so the provider raises its unhealthy
-// condition and its consumers are held under it (ADR 0240 rule 5). What is stored is what the machine said, the
-// wait unchecked: read as said, the provider seems to wait for the operator, and the held consumers were never
-// listed on the condition that is open.
-
-// refusedWait is a wait for a secret the database's manifest does not declare: it fails the check.
-var refusedWait = inventory.Wait{Part: "postgres-database", Secret: "certificate", What: "the database's certificate"}
-
-// judgedRefused is the provider's resource as the controller judges it: unhealthy, saying why.
-func judgedRefused() inventory.ResourceHealth {
-	r := waitingDatabaseFor(refusedWait)
-	r.State, r.Waits = link.StateUnhealthy, nil
-	r.Reason = "says it waits for the secret certificate, which db does not declare"
-	return r
-}
-
-// The consumer's statement arrives after the provider's, so it is the consumer's judging (sayWaiters) that must list
-// it at the provider's unhealthy condition, made urgent by who waits on it.
-func TestAProviderWhoseWaitFailedItsCheckListsWhoWaitsOnIt(t *testing.T) {
-	k, _ := withConditionsInMemory(t)
-	stored := waitingDatabaseFor(refusedWait)
-	open := judgeBoth(t, k, []inventory.ResourceHealth{judgedRefused()},
-		map[string]inventory.NodeHealth{"anchor": {Node: "anchor", Resources: []inventory.ResourceHealth{stored}}},
-		shopFailingBeside(stored))
-	provider := conditionOf(open, moduleUnhealthyKey("db", "anchor"))
-	if len(open) != 1 || provider == nil {
-		t.Fatalf("a provider whose wait failed its check and a consumer of it raised %v; want the provider's "+
-			"unhealthy alone", openKeysOf(open))
-	}
-	if said := provider.Evidence[0].Said; !strings.Contains(said, "shop on laptop") {
-		t.Fatalf("the provider's unhealthy condition does not list shop on laptop as waiting on it: %s", said)
-	}
-	if provider.Severity != conditions.Urgent {
-		t.Fatalf("the provider's unhealthy condition is %s with a consumer waiting on it; want urgent", provider.Severity)
-	}
-}
-
-// A provider that waits for a secret already given is unhealthy to its consumers too, before its own condition opens:
-// they are held under it as under any unhealthy provider, never as waiting for the operator, and its condition, when
-// open, is said as unhealthy with who waits on it.
-func TestAProviderWaitingForASecretAlreadyGivenIsUnhealthyToItsConsumers(t *testing.T) {
-	given := holdingOf(nil, shopFailingBeside(waitingDatabase()), shopOnTheDatabase)
-	given.waits.given["db@anchor"] = map[string]time.Time{"licence": time.Now().Add(-time.Hour)}
-	by, held := given.heldWith("laptop", "shop", []inventory.ResourceHealth{failingConsumer("shop")})
-	if !held || by.provider != theDatabase || len(by.waits) > 0 {
-		t.Fatalf("shop under a database waiting for a licence already given: held %v under %v with waits %v; want "+
-			"held under db on anchor as unhealthy, no waits", held, by.provider, by.waits)
-	}
-	if _, uncovered := given.waitingUncovered("laptop", "shop", []inventory.ResourceHealth{failingConsumer("shop")}); uncovered {
-		t.Fatalf("a provider whose wait failed its check is said as waiting for another part")
-	}
-}

cmd/mesh-controller/fixclass_test.go

@@ -1,54 +0,0 @@
-package main
-
-import (
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// **A change plan says its class** (novox/hq ADR 0313 §2): the issue tracker holds a fix to the budget of the
-// slowest-budgeted module the fix moves, and a fix that moves no module has no fix budget. The plan says core,
-// leaf or none, so mesh-delivery can pass it on with the fix's delivery.
-func TestAChangePlanSaysTheClassOfWhatItMoves(t *testing.T) {
-	const repo = "http://forge.internal:20000/novox/mesh-catalog.git"
-	entry := func(name, path string) inventory.Entry {
-		e := fromRepo(name, repo, path)
-		e.Source.BuiltFrom = "old"
-		e.On = []string{"anchor"}
-		return e
-	}
-	gitea := entry("gitea", "modules/gitea")
-	resolver := entry("dnsmasq", "modules/dnsmasq")
-	resolver.Manifest.Claims = []catalogue.Claim{{Name: resolverSeat}}
-	delivery := entry(catalogue.DeliverySeat, "modules/mesh-delivery")
-	webApp := entry("photos", "modules/photos")
-	entries := []inventory.Entry{gitea, resolver, delivery, webApp}
-	// photos stands on gitea: a change to gitea moves photos as its dependent.
-	edges := []inventory.Edge{{From: "photos", To: "gitea", Kind: inventory.EdgeStandsOn}}
-	policy := func(string) (inventory.Upgrade, bool) { return inventory.Upgrade{RollOut: true}, true }
-	plan := func(paths ...string) link.ChangePlan {
-		m := link.SourceMoved{Owner: "novox", Repo: "mesh-catalog", Base: "main", Commit: "head", Paths: paths}
-		return changePlanOf("novox/mesh-catalog", "main", "head", reachOfMerge(m, entries, nil, edges), entries, policy)
-	}
-
-	for _, c := range []struct {
-		why   string
-		paths []string
-		want  string
-	}{
-		{"a leaf module and its dependent", []string{"modules/gitea/index.ts"}, inventory.ClassLeaf},
-		{"the delivery's owner, on the controller's own path", []string{"modules/mesh-delivery/cmd/x.go"}, inventory.ClassCore},
-		{"the mesh's resolver", []string{"modules/dnsmasq/module.json"}, inventory.ClassCore},
-		{"a leaf and a core module together: the slowest-budgeted", []string{"modules/gitea/index.ts", "modules/dnsmasq/module.json"}, inventory.ClassCore},
-		{"nothing any module's build reads", []string{"README.md"}, "none"},
-		{"a new leaf module alone", []string{"modules/weather/module.json"}, inventory.ClassLeaf},
-		{"a new module on the controller's own path, by its own class", []string{"next/mesh-delivery/module.json"}, inventory.ClassCore},
-		{"a new leaf module beside a core one moved", []string{"modules/weather/module.json", "modules/dnsmasq/module.json"}, inventory.ClassCore},
-	} {
-		if got := plan(c.paths...).Class; got != c.want {
-			t.Errorf("%s: class %q, want %q", c.why, got, c.want)
-		}
-	}
-}

cmd/mesh-controller/forge_wait_test.go

@@ -1,148 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// A wait on a clock of its own: each pause moves it on, and nothing waits in real time.
-func aFakeWait(bound time.Duration) (waitOut, *[]time.Duration) {
-	clock := time.Date(2026, 10, 11, 11, 52, 2, 0, time.UTC)
-	var paused []time.Duration
-	return waitOut{bound: bound, first: time.Second, most: 10 * time.Second,
-		now: func() time.Time { return clock },
-		sleep: func(_ context.Context, d time.Duration) error {
-			paused = append(paused, d)
-			clock = clock.Add(d)
-			return nil
-		}}, &paused
-}
-
-// notServed is what the bus says while node-tools re-serves, in the words seen on 2026-10-11.
-func notServed() error {
-	return fmt.Errorf("cannot ask gitea.gitea_api: %w", link.ErrNothingServes)
-}
-
-// A registration's forge question that lands while the tool runner re-serves is asked again, and the forge's
-// answer, seconds later, is the registration's (novox/hq issue 486).
-func TestTheForgeNotServedForAMomentIsWaitedOut(t *testing.T) {
-	w, paused := aFakeWait(60 * time.Second)
-	asked := 0
-	facts, err := forgeWaitedOut(t.Context(), w, "novox/mesh-catalog", func(context.Context) (forgeFacts, error) {
-		asked++
-		if asked <= 2 {
-			return forgeFacts{}, notServed()
-		}
-		return forgeFacts{ID: 42, Guarded: true}, nil
-	})
-	if err != nil {
-		t.Fatalf("a forge not served for two asks failed the registration: %v", err)
-	}
-	if facts.ID != 42 || !facts.Guarded || asked != 3 {
-		t.Fatalf("the forge's answer was %+v after %d asks, want its answer on the third", facts, asked)
-	}
-	if want := []time.Duration{time.Second, 2 * time.Second}; fmt.Sprint(*paused) != fmt.Sprint(want) {
-		t.Fatalf("paused %v, want %v", *paused, want)
-	}
-}
-
-// A tool that did not answer within its wait has held the receive loop that long already: not asked again.
-func TestTheForgeNotAnsweringInTimeIsNotAskedAgain(t *testing.T) {
-	w, paused := aFakeWait(60 * time.Second)
-	asked := 0
-	_, err := forgeWaitedOut(t.Context(), w, "novox/x", func(context.Context) (forgeFacts, error) {
-		asked++
-		return forgeFacts{}, fmt.Errorf("gitea did not answer: %w", link.ErrNoAnswer)
-	})
-	if !errors.Is(err, link.ErrNoAnswer) || asked != 1 || len(*paused) != 0 {
-		t.Fatalf("a forge that did not answer in time was asked %d times, paused %v: %v", asked, *paused, err)
-	}
-}
-
-// An ask that hangs past the bound is cut off at the bound, not at its own wait, and the failure still says it
-// waited: the receive loop is held no longer than the bound (novox/hq issue 486).
-func TestAnAskHangingPastTheBoundIsCutOffAtIt(t *testing.T) {
-	w := waitOut{bound: 200 * time.Millisecond, first: 10 * time.Millisecond, most: 50 * time.Millisecond,
-		now: time.Now, sleep: sleepOrDone}
-	asked := 0
-	began := time.Now()
-	_, err := forgeWaitedOut(t.Context(), w, "novox/mesh-catalog", func(ctx context.Context) (forgeFacts, error) {
-		asked++
-		if asked == 1 {
-			return forgeFacts{}, notServed()
-		}
-		select { // link.Ask's own wait is 30 s; the bound must end it first
-		case <-ctx.Done():
-			return forgeFacts{}, fmt.Errorf("gitea did not answer: %w", link.ErrNoAnswer)
-		case <-time.After(30 * time.Second):
-			return forgeFacts{ID: 1, Guarded: true}, nil
-		}
-	})
-	if took := time.Since(began); took > 2*time.Second {
-		t.Fatalf("the wait took %s, past its bound of %s", took, w.bound)
-	}
-	if err == nil || !strings.Contains(err.Error(), "waited") || !strings.Contains(err.Error(), "asking 2 times") ||
-		!strings.Contains(err.Error(), "issue 486") {
-		t.Fatalf("the bound's end does not say it waited: %v", err)
-	}
-}
-
-// Past the bound the registration fails, saying it waited, for how long, and what the forge last said.
-func TestTheForgeNotServedPastTheBoundFailsSayingItWaited(t *testing.T) {
-	w, paused := aFakeWait(60 * time.Second)
-	_, err := forgeWaitedOut(t.Context(), w, "novox/mesh-catalog", func(context.Context) (forgeFacts, error) {
-		return forgeFacts{}, notServed()
-	})
-	if err == nil {
-		t.Fatal("a forge never served was read as an answer")
-	}
-	var waited time.Duration
-	for _, p := range *paused {
-		waited += p
-	}
-	if waited > 60*time.Second || waited < 40*time.Second {
-		t.Fatalf("waited %s in all, want close to and within the bound of 60s", waited)
-	}
-	for _, want := range []string{"waited " + waited.String(), "novox/mesh-catalog", "nothing serves", "issue 486"} {
-		if !strings.Contains(err.Error(), want) {
-			t.Errorf("the failure does not say %q: %v", want, err)
-		}
-	}
-	if !errors.Is(err, link.ErrNothingServes) {
-		t.Errorf("the failure lost what the forge last said: %v", err)
-	}
-}
-
-// A refusal is the forge's word: never asked again.
-func TestARefusalFromTheForgeIsNeverAskedAgain(t *testing.T) {
-	w, paused := aFakeWait(60 * time.Second)
-	asked := 0
-	_, err := forgeWaitedOut(t.Context(), w, "novox/x", func(context.Context) (forgeFacts, error) {
-		asked++
-		return forgeFacts{}, errors.New("gitea.gitea_api: 404 Not Found")
-	})
-	if err == nil || asked != 1 || len(*paused) != 0 {
-		t.Fatalf("a refusal was asked %d times, paused %v: %v", asked, *paused, err)
-	}
-}
-
-// A registration whose own context ends stops waiting at once.
-func TestAWaitForTheForgeEndsWithItsContext(t *testing.T) {
-	w, _ := aFakeWait(60 * time.Second)
-	ctx, cancel := context.WithCancel(t.Context())
-	w.sleep = func(ctx context.Context, d time.Duration) error { cancel(); return sleepOrDone(ctx, d) }
-	asked := 0
-	_, err := forgeWaitedOut(ctx, w, "novox/x", func(context.Context) (forgeFacts, error) {
-		asked++
-		return forgeFacts{}, notServed()
-	})
-	if !errors.Is(err, context.Canceled) || asked != 1 {
-		t.Fatalf("asked %d times after the context ended: %v", asked, err)
-	}
-}

cmd/mesh-controller/found_wait_test.go

@@ -1,160 +0,0 @@
-package main
-
-import (
-	"context"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// A directory the node-engine uses as found (novox/hq issue 339) waits for a person to hand it over at the
-// machine. Found before this send, it is no fault of the build: the gate passes with the wait carried, so an
-// urgent fix of that module still goes through. Found by this send, the send brought it, and the gate holds.
-func foundDirectory(module string, since time.Time) inventory.ResourceHealth {
-	return inventory.ResourceHealth{Module: module, Resource: module + ".data", Kind: link.KindDirectory,
-		Target: "/srv/" + module, State: link.StateUnhealthy, Since: since,
-		Reason: link.ReasonUsedAsFound + " owned by 1000:1000, mode 700, as found; root, mode 755 was declared and " +
-			"not given it — `nox node hand-over laptop <directory>` on the control-node, with its path, hands it to the mesh"}
-}
-
-func TestADirectoryFoundBeforeTheSendIsAWaitForAPerson(t *testing.T) {
-	now := time.Now()
-	sent := now.Add(-time.Minute)
-	f := gateFacts{now: now, health: map[string]inventory.NodeHealth{"laptop": {Node: "laptop", HeardAt: now,
-		Resources: []inventory.ResourceHealth{foundDirectory("notes", sent.Add(-24*time.Hour))}}}}
-	h, why := moduleHealthWord("notes", "laptop", sent, f)
-	if h != healthPerson || !strings.Contains(why, "notes.data") || !strings.Contains(why, "hand-over") {
-		t.Fatalf("a directory found before the send reads %v %q; want a wait for a person", h, why)
-	}
-	// Found by this very send: the send brought it, and it is not passed.
-	f.health["laptop"] = inventory.NodeHealth{Node: "laptop", HeardAt: now,
-		Resources: []inventory.ResourceHealth{foundDirectory("notes", sent.Add(time.Second))}}
-	if h, why := moduleHealthWord("notes", "laptop", sent, f); h != healthNotYet {
-		t.Fatalf("a directory this send found reads %v %q; want not yet", h, why)
-	}
-	// A container down beside the old wait is a fault, as before.
-	f.health["laptop"] = inventory.NodeHealth{Node: "laptop", HeardAt: now, Resources: []inventory.ResourceHealth{
-		foundDirectory("notes", sent.Add(-time.Hour)),
-		{Module: "notes", Resource: "notes.web", Kind: "container", Target: "notes", State: link.StateUnhealthy, Reason: "down"}}}
-	if h, why := moduleHealthWord("notes", "laptop", sent, f); h != healthNotYet {
-		t.Fatalf("a container down beside the wait reads %v %q; want not yet", h, why)
-	}
-}
-
-// The whole walk: a module whose directory was used as found long before still gets its fix to every machine,
-// its pass kept and the wait said; a directory this very send found holds it and puts it back.
-func TestAFixGoesThroughPastADirectoryFoundBefore(t *testing.T) {
-	for _, c := range []struct {
-		name   string
-		found  time.Duration // when the directory was found, against now
-		passes bool
-	}{
-		{"found a day before the send", -24 * time.Hour, true},
-		{"found by this send", time.Hour, false},
-	} {
-		t.Run(c.name, func(t *testing.T) {
-			b := aBacklog(t)
-			ctx := t.Context()
-			inv := b.open.inventory
-			releaseHeard = func(context.Context, *stores) (map[string]bool, error) {
-				return map[string]bool{"anchor": true, "laptop": true}, nil
-			}
-			backlogFacts := gatherGateFacts
-			gatherGateFacts = func(ctx context.Context, open *stores, component string) (gateFacts, error) {
-				f, err := backlogFacts(ctx, open, component)
-				// The used-as-found condition, raised after the send (its second statement): its own kind, never a
-				// fault the gate reads as the build's.
-				f.judged, f.openErr = true, nil
-				f.open = append(f.open, conditions.Condition{Key: usedAsFoundKey("app", "anchor"), Kind: kindUsedAsFound,
-					Subject: conditions.Subject{Scope: conditions.ScopeModule, ID: "app.anchor", Machine: "anchor"},
-					Raised:  time.Now()})
-				f.health = map[string]inventory.NodeHealth{}
-				for _, n := range []string{"anchor", "laptop"} {
-					f.health[n] = inventory.NodeHealth{Node: n, HeardAt: time.Now(), Resources: []inventory.ResourceHealth{
-						{Module: "app", Resource: "app.web", Kind: "container", Target: "app", State: link.StateHealthy},
-						foundDirectory("app", time.Now().Add(c.found)),
-						{Module: "late", Resource: "late.web", Kind: "container", Target: "late", State: link.StateHealthy}}}
-				}
-				return f, err
-			}
-			wasWithin, wasEvery, wasBound := gateWithin, gateEvery, gateBound
-			// The witness window is the node-engine's, from a start no test makes (novox/hq ADR 0351).
-			wasWindow := gateWitnessWindow
-			gateWitnessWindow = 0
-			t.Cleanup(func() { gateWitnessWindow = wasWindow })
-			t.Cleanup(func() { gateWithin, gateEvery, gateBound = wasWithin, wasEvery, wasBound })
-			gateWithin, gateEvery, gateBound = time.Hour, 0, 300*time.Millisecond
-			deadline := time.Now().Add(5 * time.Second)
-			for time.Now().Before(deadline) {
-				advancePlans(ctx, b.open)
-				if p := b.release(t); p.State != inventory.PlanRolling {
-					break
-				}
-				time.Sleep(20 * time.Millisecond)
-			}
-			p := b.release(t)
-			v, found, err := inv.GateOf(ctx, "build-app-c2")
-			if c.passes {
-				if p.State != inventory.PlanDone || err != nil || !found || v.Verdict != inventory.GatePassed {
-					t.Fatalf("the walk is %s (%s); app's verdict %+v: want the fix through", p.State, p.Note, v)
-				}
-				if !strings.Contains(v.Why+p.Note, "hand it over") {
-					t.Errorf("the wait is not carried: verdict %q, walk %q", v.Why, p.Note)
-				}
-				return
-			}
-			if p.State == inventory.PlanDone {
-				t.Fatalf("a directory this send found let the walk through: %s", p.Note)
-			}
-		})
-	}
-}
-
-// The condition says the wait in its own kind: the operator's, never urgent, and cleared once handed over.
-func TestADirectoryUsedAsFoundIsItsOwnCondition(t *testing.T) {
-	k, _ := withConditionsInMemory(t)
-	ctx := t.Context()
-	rs := map[string][]inventory.ResourceHealth{"notes": {foundDirectory("notes", time.Now().Add(-time.Hour))}}
-	for i := 0; i < 2; i++ {
-		if err := judgeModuleHealth(ctx, nil, k, "laptop", rs, map[string]int{"notes": i + 1}, time.Now()); err != nil {
-			t.Fatal(err)
-		}
-	}
-	open, _ := k.Open(ctx)
-	var got *conditions.Condition
-	for i, c := range open {
-		if c.Key == usedAsFoundKey("notes", "laptop") {
-			got = &open[i]
-		}
-		if c.Kind == kindModuleUnhealthy {
-			t.Fatalf("raised as a fault: %+v", c)
-		}
-	}
-	if got == nil || got.Resolver != conditions.ResolverOperator || got.Severity == conditions.Urgent ||
-		!strings.Contains(got.Summary, "notes.data") {
-		t.Fatalf("the condition: %+v", got)
-	}
-	// Long open is still not urgent: only a person can hand it over, and nothing is broken by the wait.
-	if err := judgeModuleHealth(ctx, nil, k, "laptop", rs, map[string]int{"notes": 3}, time.Now().Add(48*time.Hour)); err != nil {
-		t.Fatal(err)
-	}
-	open, _ = k.Open(ctx)
-	for _, c := range open {
-		if c.Key == usedAsFoundKey("notes", "laptop") && c.Severity == conditions.Urgent {
-			t.Fatal("a directory used as found became urgent")
-		}
-	}
-	if err := judgeModuleHealth(ctx, nil, k, "laptop", map[string][]inventory.ResourceHealth{}, nil, time.Now()); err != nil {
-		t.Fatal(err)
-	}
-	open, _ = k.Open(ctx)
-	for _, c := range open {
-		if c.Key == usedAsFoundKey("notes", "laptop") {
-			t.Fatal("not cleared once handed over")
-		}
-	}
-}