Take mesh-sdk at bd7731f: a machine that does not resolve keeps its name and its address in the mesh as well as its tunnel (issue 1833)

One machine whose modules could not be resolved left the private network uncomposable when it was the hub, and every
send to every machine was held. The SDK now keeps a refused machine at the place the controller already holds for it.

Makefile

@@ -90,15 +90,6 @@ redis-provisioner-image:
 	@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 modules/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
@@ -117,7 +108,7 @@ proxy-image:
 # 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
+	@sh merge-check.sh ; status=$$? ; docker rm -f -v $(PG_CONTAINER) >/dev/null 2>&1 || true ; exit $$status
 
 # The unit level alone (untagged: no bus, no store, no other process), which a developer runs continuously. The tests
 # that need a bus or the store carry `//go:build integration` and run in `check`, not here; without a database the
@@ -135,7 +126,7 @@ fmt:
 	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 rm -f -v $(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'
@@ -147,7 +138,7 @@ postgres:
 	echo ' — never came up' ; docker logs $(PG_CONTAINER) | tail -20 ; exit 1
 
 postgres-stop:
-	@docker rm -f $(PG_CONTAINER) >/dev/null 2>&1 || true
+	@docker rm -f -v $(PG_CONTAINER) >/dev/null 2>&1 || true
 
 clean:
 	rm -rf build/

cmd/mesh-builder/busy.go

@@ -6,7 +6,11 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+	"sync"
+	"sync/atomic"
 	"time"
+
+	"github.com/novox/mesh-controller/internal/builder"
 )
 
 // **The build agent says whether it is busy, and being asked drains it** (novox/hq ADR 0335 §1, §5). Its
@@ -73,14 +77,77 @@ func drainedTooLong(now time.Time) error {
 		"within %s (novox/hq ADR 0335)", began.UTC().Format(time.RFC3339), drainTooLong)
 }
 
+// inHand is true while this process has claimed a build and not yet released it. The mark in the temporary directory
+// is only believed while it is: a mark with no build of this process behind it is stale (a crash, a fault in an
+// earlier path) and is removed, because left alone it hands back every ask for ever (issue 1768).
+var inHand atomic.Bool
+
+// markRetry is how long an agent that cannot mark a build in hand takes no work, and markFault when it last failed to.
+// Taking nothing is the point: an ask fetched and handed back at once, many times a second, spends all its deliveries.
+const markRetry = 30 * time.Second
+
+var (
+	markMu    sync.Mutex
+	markFault time.Time
+	markSaid  string
+)
+
+// markFaulty says the agent could not mark a build in hand and has not yet been able to since: it takes no work. Once
+// markRetry has passed it tries the mark itself, with no ask in hand, so that an ask is fetched only when marking works.
+func markFaulty(now time.Time) bool {
+	markMu.Lock()
+	failed := markFault
+	markMu.Unlock()
+	if failed.IsZero() {
+		return false
+	}
+	if now.Sub(failed) < markRetry {
+		return true
+	}
+	f, err := os.OpenFile(inHandMark(), os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
+	if err != nil && errors.Is(err, os.ErrExist) && !inHand.Load() {
+		_ = os.Remove(inHandMark())
+		f, err = os.OpenFile(inHandMark(), os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
+	}
+	if err != nil {
+		markFailed(err)
+		return true
+	}
+	_ = f.Close()
+	_ = os.Remove(inHandMark())
+	markMu.Lock()
+	markFault, markSaid = time.Time{}, ""
+	markMu.Unlock()
+	fmt.Fprintf(os.Stderr, "the mark of a build in hand can be made again (%s): taking builds\n", inHandMark())
+	return false
+}
+
+// markFailed notes that a build could not be marked in hand, and says it when it is a new reason.
+func markFailed(err error) {
+	markMu.Lock()
+	defer markMu.Unlock()
+	markFault = time.Now()
+	if said := err.Error(); said != markSaid {
+		markSaid = said
+		fmt.Fprintf(os.Stderr, "cannot mark a build in hand (%s), so this agent takes no build for %s and tries again: %v\n",
+			inHandMark(), markRetry, err)
+	}
+}
+
 // claim marks a request in hand, unless the agent is drained: then nothing is in hand, and the request goes
 // back to the queue.
 func claim() bool {
+	if !inHand.Load() {
+		// Nothing of this process is in hand, so a mark already there is stale.
+		if err := os.Remove(inHandMark()); err == nil {
+			fmt.Fprintf(os.Stderr, "removed the mark of a build in hand (%s): no build of this agent is in hand\n", inHandMark())
+		}
+	}
 	// Made, never written over: one build at a time, and a mark already there is a build in hand.
 	f, err := os.OpenFile(inHandMark(), os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
 	if err != nil {
 		// Unmarked, an ask would say idle while this build runs: the build is not taken.
-		fmt.Fprintf(os.Stderr, "cannot mark a build in hand (%s), so it is handed back: %v\n", inHandMark(), err)
+		markFailed(err)
 		return false
 	}
 	_, err = f.WriteString(time.Now().UTC().Format(time.RFC3339) + "\n")
@@ -89,7 +156,7 @@ func claim() bool {
 	}
 	if err != nil {
 		_ = os.Remove(inHandMark())
-		fmt.Fprintf(os.Stderr, "cannot mark a build in hand (%s), so it is handed back: %v\n", inHandMark(), err)
+		markFailed(err)
 		return false
 	}
 	if drained() {
@@ -97,6 +164,7 @@ func claim() bool {
 		fmt.Fprintln(os.Stderr, "asked whether busy, so this agent takes no new build: handed back")
 		return false
 	}
+	inHand.Store(true)
 	return true
 }
 
@@ -107,6 +175,7 @@ func holding(what string) {
 
 // released ends the build in hand.
 func released() {
+	inHand.Store(false)
 	if err := os.Remove(inHandMark()); err != nil && !errors.Is(err, os.ErrNotExist) {
 		fmt.Fprintf(os.Stderr, "cannot remove the mark of the build in hand (%s): %v\n", inHandMark(), err)
 	}
@@ -144,3 +213,23 @@ func busy() (string, error) {
 	}
 	return fmt.Sprintf("busy: %s, in hand since %s; taking no new build", what, since), nil
 }
+
+var (
+	roomMu   sync.Mutex
+	roomSaid bool
+)
+
+// noRoom says this node is under the floor of free space (novox/hq issue 1834): it takes no work, so another build node
+// takes the ask instead of this one taking it and ending it in an error. Said once when it starts and again when it ends.
+func noRoom(workspace string) bool {
+	err := builder.RoomToWork("/", workspace)
+	roomMu.Lock()
+	defer roomMu.Unlock()
+	if err != nil && !roomSaid {
+		fmt.Fprintf(os.Stderr, "taking no builds: %v\n", err)
+	} else if err == nil && roomSaid {
+		fmt.Fprintf(os.Stderr, "there is room again: taking builds\n")
+	}
+	roomSaid = err != nil
+	return err != nil
+}

cmd/mesh-builder/busy_test.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"github.com/novox/mesh-controller/internal/builder"
 	"os"
 	"strings"
 	"sync"
@@ -160,3 +161,79 @@ func TestAnUnknownCommandFails(t *testing.T) {
 		t.Fatalf("help failed: %v", err)
 	}
 }
+
+// 1768/AC2: a mark naming no build of this agent (left by a crash or a fault) is stale: the next ask removes it and is
+// run, never fetched and handed back in a loop.
+func TestAStaleInHandMarkIsRemovedAndTheAskRuns(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	inHand.Store(false)
+	if err := undrained(); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(inHandMark(), []byte("2026-10-21T18:45:06Z\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if !claim() {
+		t.Fatal("a stale in-hand mark made the agent hand back an ask")
+	}
+	// A live one — this agent's own build in hand — is never taken over.
+	if claim() {
+		t.Fatal("a second build was taken while one is in hand")
+	}
+	if _, err := busy(); err != nil {
+		t.Fatalf("the build in hand was lost: %v", err)
+	}
+	released()
+}
+
+// 1768/AC3: an agent that cannot mark a build in hand for another reason takes no work, instead of fetching asks and
+// handing them back; it takes work again once marking works.
+func TestAnAgentThatCannotMarkABuildTakesNoWorkUntilItCan(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("TMPDIR", dir)
+	inHand.Store(false)
+	markFault, markSaid = time.Time{}, ""
+	t.Cleanup(func() { markFault, markSaid = time.Time{}, "" })
+	if err := undrained(); err != nil {
+		t.Fatal(err)
+	}
+	// The mark's place is a directory that cannot be removed or made over: a directory named as the mark.
+	if err := os.MkdirAll(inHandMark()+"/x", 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if claim() {
+		t.Fatal("an agent that cannot mark a build took it")
+	}
+	if !markFaulty(time.Now()) {
+		t.Fatal("an agent that cannot mark a build still takes work")
+	}
+	// Still failing after the retry time: still takes nothing, and no ask was needed to find out.
+	if !markFaulty(time.Now().Add(2 * markRetry)) {
+		t.Fatal("an agent whose mark still cannot be made takes work")
+	}
+	if err := os.RemoveAll(inHandMark()); err != nil {
+		t.Fatal(err)
+	}
+	if markFaulty(time.Now().Add(4 * markRetry)) {
+		t.Fatal("an agent whose mark can be made again takes no work")
+	}
+	if !claim() {
+		t.Fatal("an agent that can mark takes no build")
+	}
+	released()
+}
+
+// 1834/AC4: given a node under the floor of free space, when the taking loop asks, then it takes nothing, and takes again
+// once there is room.
+func TestANodeUnderTheFloorOfFreeSpaceTakesNoWork(t *testing.T) {
+	was := builder.FreeBytes
+	t.Cleanup(func() { builder.FreeBytes = was })
+	builder.FreeBytes = func(string) (uint64, error) { return 2 << 30, nil }
+	if !noRoom(t.TempDir()) {
+		t.Error("a node with 2 GiB free took work")
+	}
+	builder.FreeBytes = func(string) (uint64, error) { return 200 << 30, nil }
+	if noRoom(t.TempDir()) {
+		t.Error("a node with 200 GiB free refused work")
+	}
+}

cmd/mesh-builder/check_spec_test.go

@@ -36,3 +36,17 @@ func TestTheSiblingsAnAskNamesReachTheSpecAndTheOutcome(t *testing.T) {
 		t.Fatalf("a request that names none has siblings %+v", plain.Siblings)
 	}
 }
+
+// 1826/AC2: the held values a check request carries reach the spec; a request that carries none leaves it empty.
+func TestTheHeldValuesAnAskCarriesReachTheSpec(t *testing.T) {
+	spec := checkSpecOf(link.BuildRequest{Check: &link.CheckRequest{Owner: "novox", Repo: "mesh-catalog",
+		HeldConfig: []link.HeldConfig{{Pull: "novox/mesh-catalog#434", Head: "a", Node: "ace", Module: "n8n", Key: "media-gid",
+			Value: []byte("2000"), Approved: "the operator"}}}})
+	if len(spec.Held) != 1 || spec.Held[0].Node != "ace" || spec.Held[0].Key != "media-gid" || string(spec.Held[0].Value) != "2000" ||
+		spec.Held[0].Approved != "the operator" {
+		t.Fatalf("the spec reads %+v", spec.Held)
+	}
+	if plain := checkSpecOf(link.BuildRequest{Check: &link.CheckRequest{Owner: "o", Repo: "r"}}); plain.Held != nil {
+		t.Fatalf("a request that carries none has %+v", plain.Held)
+	}
+}

cmd/mesh-builder/holder_test.go

@@ -91,7 +91,7 @@ func TestKillEndsTheBuildRunningHereAndNoOther(t *testing.T) {
 		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") {
+	if len(removed) != 6 || !strings.Contains(removed[0], "label=mesh.build=build-1") || !strings.Contains(removed[3], "label=mesh.build=build-1") {
 		t.Errorf("removed %v", removed)
 	}
 	if c := h.current(); c.Running != nil {
@@ -160,7 +160,7 @@ func TestAHolderStartingRemovesWhatEarlierBuildsLeftHere(t *testing.T) {
 		}
 		return "", nil
 	}
-	if n := h.removeLeftBehind(); n != 2 || len(removed) != 2 || removed[1] != "docker rm -f c1 c2" {
+	if n := h.removeLeftBehind(); n != 2 || len(removed) != 3 || removed[2] != "docker rm -f -v c1 c2" {
 		t.Fatalf("removed %d: %v", n, removed)
 	}
 	h.remove = func(context.Context, string, string, ...string) (string, error) {

cmd/mesh-builder/main.go

@@ -64,6 +64,8 @@ is dialled except the broker.
   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)
+  MESH_BUILD_CGROUP_PARENT  the slice every container a build or check starts joins, which carries the
+                     machine's limits on builds (novox/hq issue 1798; default: the runtime's own)
 
 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:
@@ -137,6 +139,10 @@ func run() error {
 	if err != nil {
 		return err
 	}
+	// A build and a check run below the machine's own work (novox/hq issue 1798): the agent itself at the
+	// lowest priority, which its git and go children inherit, and every container in the build slice.
+	_ = syscall.Setpriority(syscall.PRIO_PROCESS, 0, 19)
+	builder.CgroupParent = strings.TrimSpace(os.Getenv("MESH_BUILD_CGROUP_PARENT"))
 	workspace := os.Getenv("MESH_WORKSPACE")
 	if workspace == "" {
 		workspace = os.TempDir() + "/mesh-builder"
@@ -184,7 +190,7 @@ func run() error {
 	// Paused or drained, it takes nothing new (novox/hq ADR 0219, ADR 0335): a drained agent finishes the build
 	// in hand and then says idle, and its container is replaced between builds.
 	machine := link.MachineOverNATSWith(js, on, seat, link.MachineOptions{
-		Paused: func() bool { return h.Paused() || drained() },
+		Paused: func() bool { return h.Paused() || drained() || markFaulty(time.Now()) || noRoom(workspace) },
 		Taking: func() { taking(seat) },
 		Claim:  claim,
 	})
@@ -499,6 +505,10 @@ func checkSpecOf(request link.BuildRequest) builder.CheckSpec {
 		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),
 		Tests: c.Tests, StoreOnly: c.StoreOnly, SiblingsUnknown: c.SiblingsUnknown}
+	for _, h := range c.HeldConfig {
+		spec.Held = append(spec.Held, builder.HeldValue{Pull: h.Pull, Head: h.Head, Node: h.Node, Module: h.Module, Key: h.Key,
+			Value: h.Value, Approved: h.Approved, By: h.By, At: h.At})
+	}
 	for _, s := range c.Siblings {
 		spec.Siblings = append(spec.Siblings, builder.Sibling{Repository: s.Repository, Number: s.Number, Head: s.Head,
 			Base: s.Base, Dir: s.Dir})

cmd/mesh-controller/checks.go

@@ -191,6 +191,16 @@ func (f following) pullUpdated(ctx context.Context, p link.PullUpdated, w io.Wri
 		scope.Modules, scope.Dependents, scope.New, scope.Manifests = nil, nil, nil, nil
 		composedGate(&direct)
 	}
+	// **Mesh-config is told what the head declares at every announced head of a pull request in a repository that holds
+	// modules** (novox/hq ADR 0502 clauses 2 and 6, issue 1826), also when the head touches no module: a head that reverts
+	// the change must drop the value held for it. Asked of nothing else here.
+	this := pullAtOf(p)
+	if this.Truncated {
+		this.Paths, this.Truncated = truncatedPaths(entries, p.Owner, p.Repo, scope.Modules), false
+	}
+	if scope.gated() || holdsModules(entries, p.Owner, p.Repo) {
+		tellPullDeclares(ctx, w, []pullAt{this})
+	}
 	switch {
 	case !scope.gated() && !scope.Mesh:
 		fmt.Fprintf(w, "%s/%s#%d (%.8s): %s, and the repository is not the mesh's: said, nothing run\n",
@@ -209,6 +219,9 @@ func (f following) pullUpdated(ctx context.Context, p link.PullUpdated, w io.Wri
 	}
 	request.Check.Plan = &plan
 	request.Check.Composed = composed
+	if !composed {
+		carryHeld(ctx, w, &request, []pullAt{this})
+	}
 	// **The group's other open pull requests are read beside it** (novox/hq ADR 0382 §1).
 	siblingsFrom(&request, p, entries, lines, groupsErr)
 	seat := buildSeatHeld(ctx)
@@ -594,11 +607,13 @@ func checkedOf(result link.BuildResult) link.Checked {
 		// 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
+			// Every member is named with its trunk commit (novox/hq issue 1106): the seat's word, else the one the forge
+			// announced with the head, so the forge's merge tool never meets a member whose verdict names none.
 			c.Members = append(c.Members, link.CheckedMember{Owner: g.Owner, Repo: g.Repo, Number: g.Number,
-				Commit: result.Ref, Trunk: c.Trunk})
+				Commit: result.Ref, Trunk: firstTrunk(c.Trunk, g.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)})
+					Commit: m.Ref, Trunk: firstTrunk(memberTrunk(result.Check, m), m.Trunk)})
 			}
 		}
 	}
@@ -627,6 +642,16 @@ func checkedOf(result link.BuildResult) link.Checked {
 	return c
 }
 
+// firstTrunk is the first trunk commit named, as twelve characters; empty when none is.
+func firstTrunk(named ...string) string {
+	for _, n := range named {
+		if n != "" {
+			return twelve(n)
+		}
+	}
+	return ""
+}
+
 // 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 {

cmd/mesh-controller/checks_test.go

@@ -250,6 +250,31 @@ func TestAVerdictNamesTheTrunkCommitItJudged(t *testing.T) {
 	}
 }
 
+// **A group's composed verdict names every member's trunk commit** (novox/hq issue 1106): a member the build seat named no
+// trunk for (an SDK member whose base the seat did not merge, or a seat from before the rule) is named by the trunk the forge
+// announced with its head, and the primary the same, so the merge tool never reads "names no trunk commit" on a member
+// whose trunk did not move.
+func TestAGroupVerdictNamesEveryMembersTrunkTheSDKMemberToo(t *testing.T) {
+	group := &link.CheckRequest{Owner: "novox", Repo: "mesh-catalog", Number: 7, Base: "main", Group: "feat/x",
+		Trunk: "dddddddddddd0000",
+		Members: []link.GroupMember{
+			{Owner: "novox", Repo: "mesh-sdk", Number: 8, Ref: "cccccccccccc0000", Base: "main", Trunk: "eeeeeeeeeeee0000"},
+			{Owner: "novox", Repo: "mesh-host", Number: 9, Ref: "bbbbbbbbbbbb0000", Base: "main", Trunk: "ffffffffffff0000"}}}
+	c := checkedOf(link.BuildResult{ID: "g", Ref: "aaaaaaaaaaaa0000", Checked: group, Check: &link.CheckOutcome{
+		Verdict: "pass", Head: "aaaaaaaaaaaa", Gate: &link.CheckLayer{Verdict: "pass"},
+		Members: []link.CheckedMember{{Owner: "novox", Repo: "mesh-host", Commit: "bbbbbbbbbbbb", Trunk: "222222222222"}}}})
+	want := []string{"dddddddddddd", "eeeeeeeeeeee", "222222222222"}
+	if len(c.Members) != 3 {
+		t.Fatalf("the composed check names its members %+v", c.Members)
+	}
+	for i, m := range c.Members {
+		if m.Trunk != want[i] {
+			t.Fatalf("member %d (%s/%s) is named with trunk %q, want %q (the seat's word first, else the announced one): %+v",
+				i, m.Owner, m.Repo, m.Trunk, want[i], 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.

cmd/mesh-controller/delivery.go

@@ -1177,6 +1177,12 @@ func askGroupCheck(ctx context.Context, open *stores, group string, members []or
 		return "", err
 	}
 	request.Check.Group = group
+	// **The values held for the keys the members introduce are told and carried** (novox/hq ADR 0502, issue 1826).
+	var pulls []pullAt
+	for i, s := range changeSourcesOf(members, entries, reach) {
+		pulls = append(pulls, pullAt{changeSource: s, Number: members[i].pull().Number})
+	}
+	withHeldConfig(ctx, os.Stderr, &request, pulls, true)
 	// A group's check is queued as ready when any member's pull request is marked ready.
 	request.Check.Ready = slices.ContainsFunc(members, func(m orderMember) bool { return m.Ready })
 	world, err := restOfTheMesh(ctx, open, shelfOf(entries), "")
@@ -1204,7 +1210,7 @@ func askGroupCheck(ctx context.Context, open *stores, group string, members []or
 			return "", fmt.Errorf("%s cannot be cloned for the group's check: %w", m.ID, err)
 		}
 		request.Check.Members = append(request.Check.Members, link.GroupMember{Owner: mp.Owner, Repo: mp.Repo,
-			Number: mp.Number, Repository: url, Ref: mp.Commit, Paths: mp.Paths, Base: mp.Base})
+			Number: mp.Number, Repository: url, Ref: mp.Commit, Paths: mp.Paths, Base: mp.Base, Trunk: mp.BaseSHA})
 	}
 	seat := buildSeatHeld(ctx)
 	ask, err := askOverOn(seat)

cmd/mesh-controller/issue611_test.go

@@ -35,7 +35,7 @@ func TestAMergeSaysTheModulesWhoseBuildSourceItLeftUnchanged(t *testing.T) {
 			{Own: true, Paths: []string{"modules/build-agent/Dockerfile", "modules/build-agent/module.json"}},
 		},
 		"route-proxy": {
-			{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"go.mod", "examples/route-proxy/"}},
+			{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"go.mod", "modules/route-proxy/cmd/route-proxy/"}},
 			{Own: true, Paths: []string{"modules/route-proxy/Dockerfile", "modules/route-proxy/module.json"}},
 		},
 	}

cmd/mesh-controller/merge_gate.go

@@ -65,6 +65,9 @@ type mergeCheckInput struct {
 	// group are the other heads of a delivery group composed with this one (novox/hq ADR 0239), each laid
 	// over the mesh after the one before: the group judged as one future state.
 	group []groupChange
+	// held are the approved config values held for the keys the pull requests introduce (novox/hq ADR 0502 clause 4),
+	// laid over the composition with the change only.
+	held []heldValue
 	// admin is a PostgreSQL the gate may create and drop databases in.
 	admin string
 	// beside is the directory holding the core clones beside the check (MESH_CHECK_BESIDE), for finding moves.
@@ -189,6 +192,8 @@ func mergeGateCommand(ctx context.Context, args []string) error {
 		"--changed, for a list too long for an argument (novox/hq issue 1247)")
 	group := set.String("group", "", "a delivery group's other heads, as JSON [{repository, tree, changed}], composed "+
 		"with this one as one future state (novox/hq ADR 0239)")
+	heldFile := set.String("held", "", "a file of the config values approved for keys the change's pull requests introduce, as JSON "+
+		"[{pull, node, module, key, value, approved_by}], laid over the composition with the change (novox/hq ADR 0502)")
 	asJSON := set.Bool("json", false, "print the verdict as JSON")
 	if _, err := parseAround(set, args); err != nil {
 		return err
@@ -208,6 +213,10 @@ func mergeGateCommand(ctx context.Context, args []string) error {
 	if err != nil {
 		return err
 	}
+	held, err := readHeld(*heldFile)
+	if err != nil {
+		return err
+	}
 	out := io.Writer(os.Stdout)
 	stdout := os.Stdout
 	if *asJSON {
@@ -223,7 +232,7 @@ func mergeGateCommand(ctx context.Context, args []string) error {
 		return err
 	}
 	v, err := judgeChange(ctx, mergeCheckInput{facts: f, repository: *repository, tree: *tree, changed: changedList,
-		group: others, admin: *admin, say: out, beside: os.Getenv("MESH_CHECK_BESIDE")})
+		group: others, held: held, admin: *admin, say: out, beside: os.Getenv("MESH_CHECK_BESIDE")})
 	os.Stdout = stdout
 	if err != nil {
 		return err
@@ -387,7 +396,16 @@ func judgeChange(ctx context.Context, in mergeCheckInput) (mergeVerdict, error)
 		}
 	}
 	sort.Strings(added)
-	after, tried, notes, err := composeEveryMachine(ctx, in, change, changeSources, added)
+	// **The held values are laid in this composition only** (novox/hq ADR 0502 clause 4): the mesh as it is does not
+	// declare their keys, so the base composition would refuse them.
+	withHeld := in
+	var heldNotes []string
+	withHeld.facts, heldNotes = layHeld(in.facts, in.held, change)
+	for _, n := range heldNotes {
+		say("%s", n)
+	}
+	v.Notes = append(v.Notes, heldNotes...)
+	after, tried, notes, err := composeEveryMachine(ctx, withHeld, change, changeSources, added)
 	if err != nil {
 		return v, fmt.Errorf("the mesh with the change could not be raised: %w", err)
 	}

cmd/mesh-controller/merge_gate_held.go

@@ -0,0 +1,135 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"sort"
+	"strings"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
+	snapshot "git.novox.be/novox/mesh-sdk/go/facts"
+)
+
+// Config values held for the keys an open pull request introduces (novox/hq ADR 0502 clause 4, issue 1826): the gate
+// lays each approved one over its module's values on its node in the composition with the change, and in that one
+// only. In the mesh as it is the key is not declared, so the value would be refused there.
+
+// heldValue is one approved held value as the build agent writes it (--held): the value of Key for Module on Node,
+// a machine's real name, which the snapshot holds only as a pseudonym.
+type heldValue struct {
+	Pull     string          `json:"pull"`
+	Head     string          `json:"head,omitempty"`
+	Node     string          `json:"node"`
+	Module   string          `json:"module"`
+	Key      string          `json:"key"`
+	Value    json.RawMessage `json:"value"`
+	Approved string          `json:"approved,omitempty"`
+	By       string          `json:"by,omitempty"`
+	At       string          `json:"at,omitempty"`
+}
+
+// readHeld reads the file --held names; none named, none held.
+func readHeld(path string) ([]heldValue, error) {
+	if path == "" {
+		return nil, nil
+	}
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var held []heldValue
+	if err := json.Unmarshal(raw, &held); err != nil {
+		return nil, fmt.Errorf("the held values are not readable: %w", err)
+	}
+	for _, h := range held {
+		if h.Node == "" || h.Module == "" || h.Key == "" || len(h.Value) == 0 {
+			return nil, fmt.Errorf("a held value of %s names no node, module, key or value", h.Pull)
+		}
+	}
+	return held, nil
+}
+
+// layHeld is the snapshot with each held value laid as the value of its key in its node's layer of its module, and what
+// it said of them. The snapshot given is not changed. **A held value for a machine the snapshot does not hold, or a
+// module the change does not define, is said and not laid**, never dropped silently; one for a module not assigned to
+// its machine is laid and said. The notes name machines as the snapshot does (roles and pseudonym), not by their names.
+func layHeld(f snapshot.Facts, held []heldValue, shelf map[string]catalogue.Manifest) (snapshot.Facts, []string) {
+	if len(held) == 0 {
+		return f, nil
+	}
+	out := f
+	out.Machines = make([]snapshot.Machine, len(f.Machines))
+	copy(out.Machines, f.Machines)
+	var notes, laid []string
+	pulls := map[string]bool{}
+	for _, h := range held {
+		at := -1
+		pseudonym := snapshot.Pseudonym("machine", h.Node)
+		for i, m := range out.Machines {
+			if m.Name == pseudonym {
+				at = i
+			}
+		}
+		if at < 0 {
+			notes = append(notes, fmt.Sprintf("the value held for %s of %s (%s=%s) is not composed: the snapshot holds no machine %s",
+				h.Module, h.Pull, h.Key, h.Value, pseudonym))
+			continue
+		}
+		if _, defined := shelf[h.Module]; !defined {
+			notes = append(notes, fmt.Sprintf("the value held for %s of %s (%s=%s) is not composed: the change defines no module %s",
+				h.Module, h.Pull, h.Key, h.Value, h.Module))
+			continue
+		}
+		var value any
+		if err := json.Unmarshal(h.Value, &value); err != nil {
+			notes = append(notes, fmt.Sprintf("the value held for %s of %s (%s) is not composed: it is not a value: %v",
+				h.Module, h.Pull, h.Key, err))
+			continue
+		}
+		m := &out.Machines[at]
+		layers := make([]snapshot.Settings, len(m.Settings))
+		copy(layers, m.Settings)
+		found := false
+		for i := range layers {
+			if layers[i].Module == h.Module {
+				values := make(map[string]any, len(layers[i].Values)+1)
+				for k, v := range layers[i].Values {
+					values[k] = v
+				}
+				values[h.Key] = value
+				layers[i].Values = values
+				found = true
+			}
+		}
+		if !found {
+			layers = append(layers, snapshot.Settings{Module: h.Module, Values: map[string]any{h.Key: value}})
+			sort.Slice(layers, func(a, b int) bool { return layers[a].Module < layers[b].Module })
+		}
+		m.Settings = layers
+		assigned := false
+		for _, a := range m.Assigned {
+			assigned = assigned || a == h.Module
+		}
+		by := ""
+		if h.Approved != "" {
+			by = ", approved by " + h.Approved
+		}
+		line := fmt.Sprintf("%s on %s %s=%s%s", h.Module, m.Described(), h.Key, h.Value, by)
+		if !assigned {
+			line += " (not assigned there in the snapshot)"
+		}
+		laid = append(laid, line)
+		pulls[h.Pull] = true
+	}
+	if len(laid) > 0 {
+		var names []string
+		for p := range pulls {
+			names = append(names, p)
+		}
+		sort.Strings(names)
+		notes = append([]string{fmt.Sprintf("composed with %d value(s) held for %s: %s", len(laid), strings.Join(names, ", "),
+			strings.Join(laid, "; "))}, notes...)
+	}
+	return out, notes
+}

cmd/mesh-controller/merge_gate_held_test.go

@@ -0,0 +1,85 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
+	snapshot "git.novox.be/novox/mesh-sdk/go/facts"
+)
+
+func heldGateFacts() snapshot.Facts {
+	return snapshot.Facts{Machines: []snapshot.Machine{
+		{Name: snapshot.Pseudonym("machine", "ace"), Roles: []string{"the build node"}, Assigned: []string{"n8n"},
+			Settings: []snapshot.Settings{{Module: "n8n", Values: map[string]any{"port": 5678.0}}}},
+		{Name: snapshot.Pseudonym("machine", "g14")},
+	}}
+}
+
+var heldShelf = map[string]catalogue.Manifest{"n8n": {Module: "n8n"}}
+
+// 1826/AC3: a held value is laid in its node's layer of its module, beside what the layer holds, and said.
+func TestAHeldValueIsLaidOverItsNodesLayerAndSaid(t *testing.T) {
+	f := heldGateFacts()
+	got, notes := layHeld(f, []heldValue{{Pull: "novox/mesh-catalog#434", Node: "ace", Module: "n8n", Key: "media-gid",
+		Value: []byte("2000"), Approved: "the operator"}}, heldShelf)
+	layer := got.Machines[0].Settings[0].Values
+	if layer["media-gid"] != 2000.0 || layer["port"] != 5678.0 {
+		t.Fatalf("the layer holds %v", layer)
+	}
+	if _, has := f.Machines[0].Settings[0].Values["media-gid"]; has {
+		t.Fatal("the snapshot given was changed")
+	}
+	if len(notes) != 1 || !strings.Contains(notes[0], "composed with 1 value(s) held for novox/mesh-catalog#434") ||
+		!strings.Contains(notes[0], "media-gid=2000") || !strings.Contains(notes[0], "approved by the operator") ||
+		strings.Contains(notes[0], "ace") {
+		t.Fatalf("said %q", notes)
+	}
+}
+
+// 1826/AC3: a machine with no layer of the module gets one.
+func TestAHeldValueMakesTheLayerAMachineLacks(t *testing.T) {
+	got, _ := layHeld(heldGateFacts(), []heldValue{{Pull: "p", Node: "g14", Module: "n8n", Key: "k", Value: []byte(`"x"`)}}, heldShelf)
+	s := got.Machines[1].Settings
+	if len(s) != 1 || s[0].Module != "n8n" || s[0].Values["k"] != "x" {
+		t.Fatalf("layers %+v", s)
+	}
+}
+
+// 1826/AC3: a held value for a machine or a module the snapshot or the change does not hold is said, never laid.
+func TestAHeldValueForWhatIsNotHeldIsSaidNotLaid(t *testing.T) {
+	f := heldGateFacts()
+	got, notes := layHeld(f, []heldValue{
+		{Pull: "p", Node: "nowhere", Module: "n8n", Key: "k", Value: []byte("1")},
+		{Pull: "p", Node: "ace", Module: "ghost", Key: "k", Value: []byte("1")},
+	}, heldShelf)
+	if len(notes) != 2 || !strings.Contains(notes[0], "holds no machine") || !strings.Contains(notes[1], "defines no module ghost") {
+		t.Fatalf("said %q", notes)
+	}
+	if _, has := got.Machines[0].Settings[0].Values["k"]; has {
+		t.Fatal("laid")
+	}
+}
+
+// 1826/AC3: none held lays nothing and says nothing; the file is read and refuses a value without a node.
+func TestNoHeldValuesLayNothingAndTheFileIsRead(t *testing.T) {
+	if got, notes := layHeld(heldGateFacts(), nil, heldShelf); len(notes) != 0 || len(got.Machines) != 2 {
+		t.Fatalf("%v %v", got, notes)
+	}
+	dir := t.TempDir()
+	good := filepath.Join(dir, "good.json")
+	os.WriteFile(good, []byte(`[{"pull":"p","node":"ace","module":"n8n","key":"k","value":1}]`), 0o644)
+	if h, err := readHeld(good); err != nil || len(h) != 1 || h[0].Key != "k" {
+		t.Fatalf("%v %v", h, err)
+	}
+	bad := filepath.Join(dir, "bad.json")
+	os.WriteFile(bad, []byte(`[{"pull":"p","module":"n8n","key":"k","value":1}]`), 0o644)
+	if _, err := readHeld(bad); err == nil {
+		t.Fatal("a value without a node was read")
+	}
+	if h, err := readHeld(""); h != nil || err != nil {
+		t.Fatalf("%v %v", h, err)
+	}
+}

cmd/mesh-controller/merge_gate_integration_test.go

@@ -526,3 +526,57 @@ func TestAMemberJudgedAloneSeesAMoveThroughTheClonesBeside(t *testing.T) {
 		t.Errorf("nothing beside, yet moves %v", got)
 	}
 }
+
+// 1826/AC3 (integration level, a throwaway store): a change whose container says ${config:media-gid} fails the gate for
+// want of the value, passes it with the value the operator approved held for its pull request, and the mesh as it is
+// composes the same either way.
+func TestAChangeNeedingAHeldValueFailsWithoutItAndPassesWithIt(t *testing.T) {
+	open := aMesh(t)
+	ctx := t.Context()
+	trunk := `{"module":"n8n","version":"1","resources":[{"id":"server","type":"container","name":"n8n",
+		"image":"n8nio/n8n@sha256:4846eb2f4b874ab04cde7fc1e249d2ddaec66e9aea64439beb2972cfea88e3c0"}]}`
+	m, err := catalogue.ParseManifest([]byte(trunk))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := open.inventory.RegisterModule(ctx, m, inventory.Source{Repository: "novox/mesh-catalog",
+		Path: "modules/n8n", BuiltFrom: "c0ffee"}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := assign(ctx, open, "laptop", "n8n"); err != nil {
+		t.Fatal(err)
+	}
+	f, err := gatherFacts(ctx, open, "2.11.17")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for i := range f.Machines {
+		f.Machines[i].Capabilities = append(f.Machines[i].Capabilities, snapshot.Capability{Name: "container-groups", Present: true})
+	}
+	tree := aTree(t, map[string]string{"n8n": n8nWithAGroup})
+	judge := func(held []heldValue) mergeVerdict {
+		v, err := judgeChange(t.Context(), mergeCheckInput{facts: f, admin: os.Getenv("MESH_TEST_POSTGRES"),
+			repository: "novox/mesh-catalog", tree: tree, changed: []string{"modules/n8n/module.json"}, held: held})
+		if err != nil {
+			t.Fatal(err)
+		}
+		return v
+	}
+	without := judge(nil)
+	if without.Verdict != "fail" || !strings.Contains(without.Report(), "media-gid") {
+		t.Fatalf("a required value nothing sets passed, or failed for another reason:\n%s", without.Report())
+	}
+	with := judge([]heldValue{{Pull: "novox/mesh-catalog#434", Node: "laptop", Module: "n8n", Key: "media-gid",
+		Value: []byte("2000"), Approved: "the operator"}})
+	if with.Verdict == "fail" || with.Verdict == "error" {
+		t.Fatalf("the held value did not make it compose:\n%s", with.Report())
+	}
+	if !strings.Contains(with.Report(), "composed with 1 value(s) held for novox/mesh-catalog#434") {
+		t.Fatalf("the value laid is not said:\n%s", with.Report())
+	}
+	for i := range with.Machines {
+		if with.Machines[i].Base.Composes != without.Machines[i].Base.Composes {
+			t.Fatalf("the mesh as it is composes differently with a held value: %+v / %+v", with.Machines[i].Base, without.Machines[i].Base)
+		}
+	}
+}

cmd/mesh-controller/plan_looks.go

@@ -206,6 +206,7 @@ func servingPlanSaved(ctx context.Context, bus link.Bus, open *stores) func(*inv
 	return func(_ *inventory.Inventory, p inventory.Plan) {
 		sayPlanMoved(ctx, bus, open.inventory, p)
 		planKept(p)
+		keepBuildingKey(ctx, p)
 		if p.WalkSaid == inventory.WalkEnded {
 			go forgetChecksOfWalk(context.WithoutCancel(ctx), open.inventory, p)
 		}

cmd/mesh-controller/planner_records_test.go

@@ -52,7 +52,7 @@ func TestASharedRepositoryIsPlannedFromTheRecordedBuildSources(t *testing.T) {
 		{Repository: "novox/mesh-controller", Ref: "main", Paths: append([]string{"cmd/mesh-builder/", "internal/broker/"}, gomod...)}}
 	sourcesOf["route-proxy"] = []inventory.BuildSource{
 		{Paths: []string{"modules/route-proxy/Dockerfile", "modules/route-proxy/module.json"}},
-		{Repository: "novox/mesh-controller", Ref: "main", Paths: append([]string{"examples/route-proxy/", "internal/broker/"}, gomod...)}}
+		{Repository: "novox/mesh-controller", Ref: "main", Paths: append([]string{"modules/route-proxy/cmd/route-proxy/", "internal/broker/"}, gomod...)}}
 	register(catalogue.Manifest{Module: "mesh-controller", Version: "1"}, "novox/mesh-controller", "", nil, nil)
 	register(agent, "novox/mesh-catalog", "modules/build-agent", nil, controllerRead)
 	register(catalogue.Manifest{Module: "route-proxy", Version: "1"}, "novox/mesh-catalog", "modules/route-proxy", nil, controllerRead)
@@ -133,7 +133,7 @@ func TestASharedRepositoryIsPlannedFromTheRecordedBuildSources(t *testing.T) {
 		{"a package only the controller builds from: the controller alone", "mesh-controller",
 			[]string{"internal/conditions/condition.go"}, "mesh-controller", true},
 		{"the route proxy's program: the route proxy alone", "mesh-controller",
-			[]string{"examples/route-proxy/main.go"}, "route-proxy", true},
+			[]string{"modules/route-proxy/cmd/route-proxy/main.go"}, "route-proxy", true},
 		{"a package all three build from: all three", "mesh-controller",
 			[]string{"internal/broker/broker.go"}, "mesh-controller,route-proxy | build-agent", false},
 		{"the route proxy's directory in the catalogue: it alone", "mesh-catalog",

cmd/mesh-controller/planner_rules_test.go

@@ -259,7 +259,7 @@ func TestASharedRepositoryMovesOnlyWhatItsBuildSourceHolds(t *testing.T) {
 			{Own: true, Paths: []string{"modules/build-agent/Dockerfile", "modules/build-agent/module.json"}},
 		},
 		"route-proxy": {
-			{Repository: "novox/mesh-controller", Ref: "main", Paths: with("examples/route-proxy/", "internal/broker/",
+			{Repository: "novox/mesh-controller", Ref: "main", Paths: with("modules/route-proxy/cmd/route-proxy/", "internal/broker/",
 				"vendor/github.com/nats-io/nats.go/")},
 			{Own: true, Paths: []string{"modules/route-proxy/Dockerfile", "modules/route-proxy/module.json"}},
 		},
@@ -288,7 +288,7 @@ func TestASharedRepositoryMovesOnlyWhatItsBuildSourceHolds(t *testing.T) {
 		{"a README of the controller's repository: no module (338)", "mesh-controller",
 			[]string{"README.md"}, read, "", "README.md"},
 		{"the route proxy's program alone: the route proxy alone (338)", "mesh-controller",
-			[]string{"examples/route-proxy/main.go"}, read, "route-proxy", ""},
+			[]string{"modules/route-proxy/cmd/route-proxy/main.go"}, read, "route-proxy", ""},
 		{"the build seat's program alone: its holder alone", "mesh-controller",
 			[]string{"cmd/mesh-builder/main.go"}, read, "build-agent", ""},
 		{"a package the build seat's program and the controller build from: both", "mesh-controller",
@@ -305,7 +305,7 @@ func TestASharedRepositoryMovesOnlyWhatItsBuildSourceHolds(t *testing.T) {
 		{"go.sum: all three", "mesh-controller",
 			[]string{"go.sum"}, read, "mesh-controller,route-proxy | build-agent", ""},
 		{"a file added to the proxy's package: the proxy", "mesh-controller",
-			[]string{"examples/route-proxy/new.go"}, read, "route-proxy", ""},
+			[]string{"modules/route-proxy/cmd/route-proxy/new.go"}, read, "route-proxy", ""},
 		// Before any build source is said: as before.
 		{"no build source said: a README moves all three, as before", "mesh-controller",
 			[]string{"README.md"}, unsaid, "mesh-controller,route-proxy | build-agent", ""},
@@ -345,7 +345,7 @@ func TestAModuleAPlanOvertookIsReadWhole(t *testing.T) {
 	built := time.Date(2026, 10, 10, 1, 0, 0, 0, time.UTC)
 	read := map[string][]inventory.ReadRepository{
 		"route-proxy": {
-			{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"examples/route-proxy/", "go.mod"}, Built: built},
+			{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"modules/route-proxy/cmd/route-proxy/", "go.mod"}, Built: built},
 			{Own: true, Paths: []string{"modules/route-proxy/module.json"}, Built: built},
 		},
 		"mesh-controller": {{Own: true, Paths: []string{"module.json", "cmd/mesh-controller/"}, Built: built}},
@@ -396,11 +396,11 @@ func TestAMissedMergeMovingOnlyAPackagingModuleIsActedOnOnce(t *testing.T) {
 	}
 	read := map[string][]inventory.ReadRepository{
 		"mesh-controller": {{Own: true, Paths: []string{"module.json", "cmd/mesh-controller/"}, Built: merged.Add(-time.Hour)}},
-		"route-proxy": {{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"examples/route-proxy/"},
+		"route-proxy": {{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"modules/route-proxy/cmd/route-proxy/"},
 			Built: merged.Add(-time.Hour), Looked: merged.Add(-time.Hour)}},
 	}
 	m := link.SourceMoved{Owner: "novox", Repo: "mesh-controller", Base: "main", Commit: "c1",
-		MergedAt: merged.Format(time.RFC3339), Paths: []string{"examples/route-proxy/main.go"}}
+		MergedAt: merged.Format(time.RFC3339), Paths: []string{"modules/route-proxy/cmd/route-proxy/main.go"}}
 	if got := wouldMove(m, entries, planningView(read, nil)); len(got) != 1 || got[0].Manifest.Module != "route-proxy" {
 		t.Fatalf("a missed merge of the proxy's program would move %v", got)
 	}
@@ -599,14 +599,14 @@ func TestTheGatePlansFromTheBuildSourcesTheSnapshotCarries(t *testing.T) {
 			Sources: []snapshot.BuildSource{{Own: true, Paths: []string{"module.json", "cmd/mesh-controller/", "internal/broker/"}}}},
 		{Name: "route-proxy", Repository: "novox/mesh-catalog", Path: "modules/route-proxy", Manifest: manifest("route-proxy"),
 			Reads: []string{"novox/mesh-controller"},
-			Sources: []snapshot.BuildSource{{Repository: "novox/mesh-controller", Paths: []string{"examples/route-proxy/", "internal/broker/"}},
+			Sources: []snapshot.BuildSource{{Repository: "novox/mesh-controller", Paths: []string{"modules/route-proxy/cmd/route-proxy/", "internal/broker/"}},
 				{Own: true, Paths: []string{"modules/route-proxy/module.json"}}}},
 	}}
 	for paths, want := range map[string]string{
-		"cmd/mesh-controller/main.go":  "mesh-controller",
-		"examples/route-proxy/main.go": "route-proxy",
-		"internal/broker/broker.go":    "mesh-controller,route-proxy",
-		"README.md":                    "",
+		"cmd/mesh-controller/main.go":                 "mesh-controller",
+		"modules/route-proxy/cmd/route-proxy/main.go": "route-proxy",
+		"internal/broker/broker.go":                   "mesh-controller,route-proxy",
+		"README.md":                                   "",
 	} {
 		r, err := reachOfChange(facts, "novox/mesh-controller", []string{paths}, "")
 		if err != nil {

cmd/mesh-controller/plans_building.go

@@ -0,0 +1,238 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"sync"
+	"sync/atomic"
+	"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/link"
+)
+
+// The plans building (novox/hq ADR 0483 clause 2, issue 1687).
+//
+// **A key per delivery plan in its build phase, so that the build seat takes no new check while a delivery builds.** The phase
+// runs from the ask of the plan's first build until every build of its last tier is built, or the plan fails, stops or waits
+// on the operator. It is derived from the plan alone (buildPhaseOf), so a controller that restarts finds the same answer. The
+// key is put when the first build is asked (sayBuilding), kept current at every save of the plan (keepBuildingKey) and by a
+// look every link.PlansBuildingRefresh while this controller holds the lease (keepingPlansBuilding), and deleted at the phase's
+// end; the bucket's age removes the key of a controller that stopped, so checks are held at most that long.
+//
+// The layout is documented in internal/link/holds.go.
+
+// buildPhaseOf says whether a plan is in its build phase: open, not waiting for the operator's word, with a build asked and a
+// build of its tiers still to be built. A tier built and sent leaves the plan rolling while later tiers are still to be asked;
+// it is in the phase still, which is what keeps a check from taking a place between two tiers.
+func buildPhaseOf(p inventory.Plan) bool {
+	if !p.Open() || p.Waiting() || p.Release != nil {
+		return false
+	}
+	asked, unbuilt := false, false
+	for _, tier := range p.Tiers {
+		for _, m := range tier {
+			st := p.Modules[m]
+			if st != nil && st.State != "" {
+				asked = true
+			}
+			if st == nil || (st.State != "built" && st.State != planDeleted) {
+				unbuilt = true
+			}
+		}
+	}
+	return asked && unbuilt
+}
+
+// buildingSince is when the plan's first build was asked, or fallback when no module says.
+func buildingSince(p inventory.Plan, fallback time.Time) time.Time {
+	since := time.Time{}
+	for _, st := range p.Modules {
+		if st != nil && st.AskedAt != nil && (since.IsZero() || st.AskedAt.Before(since)) {
+			since = *st.AskedAt
+		}
+	}
+	if since.IsZero() {
+		return fallback
+	}
+	return since
+}
+
+// buildingStore is the bucket of the plans building.
+type buildingStore interface {
+	Put(ctx context.Context, plan string, value []byte) error
+	Delete(ctx context.Context, plan string) error
+	Keys(ctx context.Context) ([]string, error)
+}
+
+// syncBuilding makes the bucket say what the plans say: a key for each plan in its build phase, put again, and none for any
+// other plan, deleted. It returns the faults, each once.
+func syncBuilding(ctx context.Context, store buildingStore, plans []inventory.Plan, now time.Time) []error {
+	var faults []error
+	live := map[string]bool{}
+	for _, p := range plans {
+		if !buildPhaseOf(p) {
+			continue
+		}
+		live[p.ID] = true
+		if err := putBuilding(ctx, store, p.ID, buildingSince(p, now), now); err != nil {
+			faults = append(faults, err)
+		}
+	}
+	keys, err := store.Keys(ctx)
+	if err != nil {
+		return append(faults, err)
+	}
+	for _, key := range keys {
+		if live[key] {
+			continue
+		}
+		if err := store.Delete(ctx, key); err != nil {
+			faults = append(faults, fmt.Errorf("the key of %s could not be taken away: %w", key, err))
+		}
+	}
+	return faults
+}
+
+func putBuilding(ctx context.Context, store buildingStore, plan string, since, now time.Time) error {
+	body, _ := json.Marshal(link.PlanBuilding{Plan: plan, Since: since.UTC(), Seen: now.UTC()})
+	if err := store.Put(ctx, plan, body); err != nil {
+		return fmt.Errorf("the key of %s could not be put: %w", plan, err)
+	}
+	return nil
+}
+
+// busBuilding is the store on the controller's bucket.
+type busBuilding struct {
+	conn *nats.Conn
+	mu   sync.Mutex
+	kv   jetstream.KeyValue
+}
+
+func (b *busBuilding) bucket(ctx context.Context) (jetstream.KeyValue, error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	if b.kv != nil {
+		return b.kv, nil
+	}
+	api, err := jetstream.New(b.conn)
+	if err != nil {
+		return nil, err
+	}
+	kv, err := api.KeyValue(ctx, broker.PlansBuildingBucket)
+	if err != nil {
+		return nil, fmt.Errorf("the plans building: %w", err)
+	}
+	b.kv = kv
+	return kv, nil
+}
+
+func (b *busBuilding) Put(ctx context.Context, plan string, value []byte) error {
+	kv, err := b.bucket(ctx)
+	if err != nil {
+		return err
+	}
+	_, err = kv.Put(ctx, plan, value)
+	return err
+}
+
+func (b *busBuilding) Delete(ctx context.Context, plan string) error {
+	kv, err := b.bucket(ctx)
+	if err != nil {
+		return err
+	}
+	if err := kv.Delete(ctx, plan); err != nil && !errors.Is(err, jetstream.ErrKeyNotFound) {
+		return err
+	}
+	return nil
+}
+
+func (b *busBuilding) Keys(ctx context.Context) ([]string, error) {
+	kv, err := b.bucket(ctx)
+	if err != nil {
+		return nil, err
+	}
+	keys, err := kv.Keys(ctx)
+	if errors.Is(err, jetstream.ErrNoKeysFound) {
+		return nil, nil
+	}
+	return keys, err
+}
+
+// buildingKeys is the store of the serving controller; nil in a process that is not it, which says nothing.
+var buildingKeys atomic.Pointer[buildingStore]
+
+func setBuildingStore(s buildingStore) {
+	if s == nil {
+		buildingKeys.Store(nil)
+		return
+	}
+	buildingKeys.Store(&s)
+}
+
+// sayBuilding puts a plan's key: its first build is being asked (or another of its builds). A key that could not be put is
+// said; the look that follows puts it again.
+func sayBuilding(ctx context.Context, plan string, since time.Time) {
+	s := buildingKeys.Load()
+	if s == nil {
+		return
+	}
+	if err := putBuilding(ctx, *s, plan, since, time.Now()); err != nil {
+		fmt.Printf("plans: %v; checks may take a place of %s until the next look\n", err, plan)
+	}
+}
+
+// keepBuildingKey is told each plan this controller keeps: its key put again while it builds and taken away once it does not.
+func keepBuildingKey(ctx context.Context, p inventory.Plan) {
+	s := buildingKeys.Load()
+	if s == nil {
+		return
+	}
+	if buildPhaseOf(p) {
+		sayBuilding(ctx, p.ID, buildingSince(p, time.Now()))
+		return
+	}
+	if err := (*s).Delete(ctx, p.ID); err != nil {
+		fmt.Printf("plans: the key of %s could not be taken away; it ages out: %v\n", p.ID, err)
+	}
+}
+
+// keepingPlansBuilding looks at the plans every link.PlansBuildingRefresh for as long as this controller serves and holds the
+// lease, so a key is put again before its age and the key of a plan that left the phase unseen is taken away.
+func keepingPlansBuilding(ctx context.Context, inv *inventory.Inventory, conn *nats.Conn) {
+	store := &busBuilding{conn: conn}
+	setBuildingStore(store)
+	defer setBuildingStore(nil)
+	tick := time.NewTicker(broker.PlansBuildingRefresh)
+	defer tick.Stop()
+	failing := ""
+	for {
+		if epoch, err := theLease.epoch(ctx); err == nil && epoch != 0 {
+			why := ""
+			if plans, err := inv.OpenPlans(ctx); err != nil {
+				why = fmt.Sprintf("the plans cannot be read: %v", err)
+			} else if faults := syncBuilding(ctx, store, plans, time.Now()); len(faults) > 0 {
+				why = fmt.Sprint(faults)
+			}
+			if why != failing {
+				if why != "" {
+					fmt.Printf("plans: the keys of the plans building cannot be kept: %s\n", why)
+				} else {
+					fmt.Printf("plans: the keys of the plans building are kept again\n")
+				}
+				failing = why
+			}
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-tick.C:
+		}
+	}
+}

cmd/mesh-controller/plans_building_test.go

@@ -0,0 +1,175 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"sort"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/inventory"
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// Issue 1687 (ADR 0483 clause 2): a delivery plan's key lives from the ask of its first build until every build of its last
+// tier is built, or the plan fails, stops or waits on the operator.
+
+type fakeBuildingStore struct {
+	mu   sync.Mutex
+	keys map[string]link.PlanBuilding
+	puts map[string]int
+}
+
+func newFakeBuildingStore() *fakeBuildingStore {
+	return &fakeBuildingStore{keys: map[string]link.PlanBuilding{}, puts: map[string]int{}}
+}
+
+func (f *fakeBuildingStore) Put(_ context.Context, plan string, value []byte) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	var v link.PlanBuilding
+	if err := json.Unmarshal(value, &v); err != nil {
+		return err
+	}
+	f.keys[plan] = v
+	f.puts[plan]++
+	return nil
+}
+
+func (f *fakeBuildingStore) Delete(_ context.Context, plan string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	delete(f.keys, plan)
+	return nil
+}
+
+func (f *fakeBuildingStore) Keys(context.Context) ([]string, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	var out []string
+	for k := range f.keys {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out, nil
+}
+
+func aPlan(id, state string, tiers [][]string, states map[string]string) inventory.Plan {
+	p := inventory.Plan{ID: id, State: state, Tiers: tiers, Modules: map[string]*inventory.PlanModule{}}
+	now := time.Now().Add(-time.Minute)
+	for m, st := range states {
+		pm := &inventory.PlanModule{State: st}
+		if st != "" {
+			pm.AskedAt = &now
+		}
+		p.Modules[m] = pm
+	}
+	return p
+}
+
+func TestAPlanIsInItsBuildPhaseFromTheFirstAskToTheLastBuild(t *testing.T) {
+	tiers := [][]string{{"a", "b"}, {"c"}}
+	cases := []struct {
+		name string
+		plan inventory.Plan
+		want bool
+	}{
+		{"no build asked yet", aPlan("p", inventory.PlanBuilding, tiers, nil), false},
+		{"the first tier asked", aPlan("p", inventory.PlanBuilding, tiers, map[string]string{"a": "asked", "b": "asked"}), true},
+		// Between two tiers: the first built and sent (rolling), the second not asked yet.
+		{"between two tiers", aPlan("p", inventory.PlanRolling, tiers, map[string]string{"a": "built", "b": "built"}), true},
+		{"the last tier asked", aPlan("p", inventory.PlanBuilding, tiers, map[string]string{"a": "built", "b": "built", "c": "asked"}), true},
+		{"every build built", aPlan("p", inventory.PlanRolling, tiers, map[string]string{"a": "built", "b": "built", "c": "built"}), false},
+		// A module the plan deletes is done as far as its tiers go (release_plan.go), so it holds no key through the rollout.
+		{"a deleted module is done", aPlan("p", inventory.PlanRolling, tiers, map[string]string{"a": "built", "b": "built", "c": planDeleted}), false},
+		{"failed", aPlan("p", inventory.PlanFailed, tiers, map[string]string{"a": "failed", "b": "asked"}), false},
+		{"superseded", aPlan("p", inventory.PlanSuperseded, tiers, map[string]string{"a": "asked"}), false},
+		{"a batch whose window is open", aPlan("p", inventory.PlanAssembling, tiers, map[string]string{"a": "asked"}), false},
+	}
+	for _, c := range cases {
+		if got := buildPhaseOf(c.plan); got != c.want {
+			t.Errorf("%s: in the build phase = %v, want %v", c.name, got, c.want)
+		}
+	}
+	waiting := aPlan("p", inventory.PlanBuilding, tiers, map[string]string{"a": "asked"})
+	waiting.Delivery = &inventory.PlanDelivery{Awaits: "the operator's word"}
+	if buildPhaseOf(waiting) {
+		t.Error("a plan that waits on the operator is in its build phase")
+	}
+}
+
+// The key's life: put, refreshed, deleted at the phase's end; a plan that left the phase unseen loses its key at the next look.
+func TestAPlanKeyIsPutRefreshedAndDeletedAtThePhasesEnd(t *testing.T) {
+	ctx := context.Background()
+	store := newFakeBuildingStore()
+	tiers := [][]string{{"a"}, {"b"}}
+	building := aPlan("plan-1", inventory.PlanBuilding, tiers, map[string]string{"a": "asked"})
+
+	if faults := syncBuilding(ctx, store, []inventory.Plan{building}, time.Now()); len(faults) > 0 {
+		t.Fatal(faults)
+	}
+	if _, ok := store.keys["plan-1"]; !ok {
+		t.Fatal("no key while the first build is asked")
+	}
+	first := store.keys["plan-1"]
+	// Refreshed: put again, the phase's start kept.
+	time.Sleep(2 * time.Millisecond)
+	syncBuilding(ctx, store, []inventory.Plan{building}, time.Now())
+	if store.puts["plan-1"] != 2 || !store.keys["plan-1"].Seen.After(first.Seen) || !store.keys["plan-1"].Since.Equal(first.Since) {
+		t.Errorf("the key was not refreshed with its start kept: %d puts, %+v then %+v", store.puts["plan-1"], first, store.keys["plan-1"])
+	}
+	// Between the tiers: still there.
+	between := aPlan("plan-1", inventory.PlanRolling, tiers, map[string]string{"a": "built"})
+	syncBuilding(ctx, store, []inventory.Plan{between}, time.Now())
+	if _, ok := store.keys["plan-1"]; !ok {
+		t.Error("the key was gone between two tiers")
+	}
+	// A key of another plan that is no longer in the phase.
+	store.keys["plan-0"] = link.PlanBuilding{Plan: "plan-0"}
+	done := aPlan("plan-1", inventory.PlanRolling, tiers, map[string]string{"a": "built", "b": "built"})
+	syncBuilding(ctx, store, []inventory.Plan{done}, time.Now())
+	if len(store.keys) != 0 {
+		t.Errorf("keys remain after the last build was built: %v", store.keys)
+	}
+}
+
+// keepBuildingKey, told of each save, puts the key while the plan builds and deletes it when the plan fails.
+func TestASavedPlanPutsOrDeletesItsKey(t *testing.T) {
+	ctx := context.Background()
+	store := newFakeBuildingStore()
+	var s buildingStore = store
+	buildingKeys.Store(&s)
+	defer buildingKeys.Store(nil)
+
+	p := aPlan("plan-7", inventory.PlanBuilding, [][]string{{"a"}}, map[string]string{"a": "asked"})
+	keepBuildingKey(ctx, p)
+	if _, ok := store.keys["plan-7"]; !ok {
+		t.Fatal("the key was not put when the plan was saved building")
+	}
+	p.State = inventory.PlanFailed
+	keepBuildingKey(ctx, p)
+	if _, ok := store.keys["plan-7"]; ok {
+		t.Fatal("the key stayed after the plan failed")
+	}
+}
+
+// The plan's key is there before its first build is asked, so a check cannot take a place between the ask and the plan's save.
+func TestThePlansKeyIsPutBeforeItsFirstBuildIsAsked(t *testing.T) {
+	store := newFakeBuildingStore()
+	var s buildingStore = store
+	buildingKeys.Store(&s)
+	defer buildingKeys.Store(nil)
+	p, byName := aTierOfThree()
+	keyThere := false
+	was := askABuild
+	askABuild = func(context.Context, buildSource, string, string) (string, error) {
+		_, keyThere = store.keys["plan-1"]
+		return "build-x", nil
+	}
+	t.Cleanup(func() { askABuild = was })
+	askModule(t.Context(), p, "a", byName)
+	if !keyThere {
+		t.Fatal("the plan's key was not there when its first build was asked")
+	}
+}

cmd/mesh-controller/pull_declares.go

@@ -0,0 +1,211 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"path"
+	"reflect"
+	"slices"
+	"time"
+
+	"github.com/nats-io/nats.go"
+
+	"github.com/novox/mesh-controller/internal/broker"
+	"github.com/novox/mesh-controller/internal/inventory"
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// What the controller tells mesh-config of an open pull request, and asks it back (novox/hq ADR 0502 clauses 2 and 4,
+// issue 1826): a config key a pull request introduces is not declared on the trunk, so a value for it can be judged
+// only against the pull request's own declaration, which the core reads from the forge and mesh-config never does
+// (ADR 0495 §1). The call is mesh-config's `config` verb in the controller's own name, actions `pull-declares` and
+// `held`; the shapes are those of the interface the two sides agreed.
+
+// meshConfigWait is how long the controller waits for mesh-config before it goes on without: a check is never held up
+// by a module that does not answer.
+const meshConfigWait = 10 * time.Second
+
+// meshConfigAsk is one call of mesh-config's `config` verb in the controller's own name, answering its result. A
+// variable so a test needs no bus.
+var meshConfigAsk = func(ctx context.Context, args map[string]any) ([]byte, error) {
+	var result []byte
+	err := onTheBus(func(conn *nats.Conn) error {
+		answer, err := link.AskMeshSeatToolAs(ctx, conn, broker.ControllerName, "mesh-config", "config", args, meshConfigWait)
+		if err != nil {
+			return err
+		}
+		if answer.Error != "" {
+			return fmt.Errorf("%s", answer.Error)
+		}
+		result = answer.Result
+		return nil
+	})
+	return result, err
+}
+
+// pullAt is an open pull request at a head: the change to read, and its number.
+type pullAt struct {
+	changeSource
+	Number int
+}
+
+// pullAtOf is a pull request announced, as the change it makes over what it merges into.
+func pullAtOf(p link.PullUpdated) pullAt {
+	old := p.BaseSHA
+	if old == "" {
+		old = p.Base
+	}
+	return pullAt{Number: p.Number, changeSource: changeSource{Owner: p.Owner, Repo: p.Repo, New: p.Commit, Old: old,
+		Paths: p.Paths, Truncated: p.PathsTruncated, Removed: p.Removed}}
+}
+
+func pullKey(owner, repo string, number int) string {
+	return fmt.Sprintf("%s/%s#%d", owner, repo, number)
+}
+
+func (p pullAt) key() string { return pullKey(p.Owner, p.Repo, p.Number) }
+
+// pullDeclarations are the config declarations a pull request's head adds or changes over what it merges into, by
+// module, in the shape of the declared-config mirror. The bool says the head could be read: false for a pull request whose
+// paths are cut (the caller cuts them to the manifests of the modules it moves) or whose base is unknown, which is then
+// told nothing, never an empty set.
+func pullDeclarations(ctx context.Context, p pullAt) ([]inventory.DeclaredConfigMirrored, bool, error) {
+	var out []inventory.DeclaredConfigMirrored
+	if p.Truncated || p.Old == "" {
+		return nil, false, nil
+	}
+	for _, file := range p.Paths {
+		if path.Base(file) != moduleManifestFile || slices.Contains(p.Removed, file) {
+			continue
+		}
+		now, exists, err := manifestCached(ctx, p.Owner, p.Repo, file, p.New)
+		if err != nil {
+			return nil, false, err
+		}
+		if !exists || now.Module == "" {
+			continue
+		}
+		was, _, err := manifestCached(ctx, p.Owner, p.Repo, file, p.Old)
+		if err != nil {
+			return nil, false, err
+		}
+		have, err := inventory.DeclaredOf(now.Settings)
+		if err != nil {
+			return nil, false, fmt.Errorf("%s at %.8s: %w", file, p.New, err)
+		}
+		had, err := inventory.DeclaredOf(was.Settings)
+		if err != nil {
+			return nil, false, fmt.Errorf("%s at %.8s: %w", file, p.Old, err)
+		}
+		changed := map[string]inventory.DeclaredMirrored{}
+		for key, d := range have {
+			if before, there := had[key]; !there || !reflect.DeepEqual(before, d) {
+				changed[key] = d
+			}
+		}
+		if len(changed) > 0 {
+			out = append(out, inventory.DeclaredConfigMirrored{Module: now.Module, Settings: changed})
+		}
+	}
+	return out, true, nil
+}
+
+// tellPullDeclares tells mesh-config, for each pull request at every announced head, what the head declares, an empty set
+// when it declares nothing new: mesh-config re-judges the values held at every head, so a head that reverts the change
+// drops them (ADR 0502 clause 6). A
+// failure is said to w and the check goes on: the held values are then none (ADR 0502 clause 2).
+func tellPullDeclares(ctx context.Context, w io.Writer, pulls []pullAt) {
+	for _, p := range pulls {
+		mods, readable, err := pullDeclarations(ctx, p)
+		if err != nil {
+			fmt.Fprintf(w, "%s: what its head declares cannot be read, so mesh-config is told nothing: %v\n", p.key(), err)
+			continue
+		}
+		if !readable {
+			continue
+		}
+		declares := map[string]map[string]inventory.DeclaredMirrored{}
+		for _, m := range mods {
+			declares[m.Module] = m.Settings
+		}
+		if _, err := meshConfigAsk(ctx, map[string]any{"action": "pull-declares", "pull": p.key(), "head": p.New,
+			"declares": declares}); err != nil {
+			fmt.Fprintf(w, "%s: mesh-config cannot be told what its head declares (%v); the check goes on without held values\n",
+				p.key(), err)
+		}
+	}
+}
+
+// heldFor asks mesh-config for the approved held values of these pull requests at their heads (ADR 0502 clause 4). Only
+// those of the pull requests asked about are carried. A failure is said to w and answers none.
+func heldFor(ctx context.Context, w io.Writer, pulls []pullAt) []link.HeldConfig {
+	if len(pulls) == 0 {
+		return nil
+	}
+	type pullHead struct {
+		Pull string `json:"pull"`
+		Head string `json:"head"`
+	}
+	asked := make([]pullHead, 0, len(pulls))
+	for _, p := range pulls {
+		asked = append(asked, pullHead{p.key(), p.New})
+	}
+	raw, err := meshConfigAsk(ctx, map[string]any{"action": "held", "pulls": asked})
+	if err != nil {
+		fmt.Fprintf(w, "mesh-config cannot say what it holds for these pull requests (%v); the check goes on without held values\n", err)
+		return nil // empty-on-error: said above; a check without held values fails for want of the value and says so, it never passes on a guess
+	}
+	var answer struct {
+		Held    []link.HeldConfig `json:"held"`
+		Skipped []struct {
+			Pull string `json:"pull"`
+			Why  string `json:"why"`
+		} `json:"skipped"`
+	}
+	if len(raw) == 0 {
+		return nil
+	}
+	if err := json.Unmarshal(raw, &answer); err != nil {
+		fmt.Fprintf(w, "mesh-config's held values cannot be read (%v); the check goes on without them\n", err)
+		return nil // empty-on-error: said above; a check without held values fails for want of the value and says so, it never passes on a guess
+	}
+	for _, s := range answer.Skipped {
+		fmt.Fprintf(w, "%s: mesh-config holds a value it does not carry: %s\n", s.Pull, s.Why)
+	}
+	var out []link.HeldConfig
+	for _, h := range answer.Held {
+		for _, p := range pulls {
+			if h.Pull == p.key() {
+				out = append(out, h)
+				break
+			}
+		}
+	}
+	return out
+}
+
+// withHeldConfig tells mesh-config what these pull requests declare and puts the approved held values of them on the
+// check request (ADR 0502 clause 4). With carry false, a member of a group whose composed check composes, only the
+// declarations are told.
+func withHeldConfig(ctx context.Context, w io.Writer, request *link.BuildRequest, pulls []pullAt, carry bool) {
+	tellPullDeclares(ctx, w, pulls)
+	if carry {
+		carryHeld(ctx, w, request, pulls)
+	}
+}
+
+// carryHeld puts the approved held values of these pull requests on the check request.
+func carryHeld(ctx context.Context, w io.Writer, request *link.BuildRequest, pulls []pullAt) {
+	if request.Check != nil {
+		request.Check.HeldConfig = heldFor(ctx, w, pulls)
+	}
+}
+
+// holdsModules is whether a module of the mesh is built from this repository.
+func holdsModules(entries []inventory.Entry, owner, repo string) bool {
+	return slices.ContainsFunc(entries, func(e inventory.Entry) bool {
+		return sameRepository(e.Source.Repository, link.SourceMoved{Owner: owner, Repo: repo})
+	})
+}

cmd/mesh-controller/pull_declares_test.go

@@ -0,0 +1,209 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
+	"github.com/novox/mesh-controller/internal/inventory"
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+const (
+	headSHA = "2222222222222222222222222222222222222222"
+	baseSHA = "1111111111111111111111111111111111111111"
+)
+
+// fakeManifests serves manifests by ref, and counts what the forge was asked. Issue 1826/AC1 (unit level).
+func fakeManifests(t *testing.T, at map[string]*catalogue.Manifest) {
+	t.Helper()
+	was := manifestAt
+	t.Cleanup(func() { manifestAt = was })
+	manifestsReadMu.Lock()
+	clear(manifestsRead)
+	manifestsReadMu.Unlock()
+	manifestAt = func(_ context.Context, _, _, _, ref string) (catalogue.Manifest, bool, error) {
+		if m := at[ref]; m != nil {
+			return *m, true, nil
+		}
+		return catalogue.Manifest{}, false, nil
+	}
+}
+
+// fakeConfig records the calls to mesh-config and answers each action from answers.
+func fakeConfig(t *testing.T, answers map[string]string) *[]map[string]any {
+	t.Helper()
+	var calls []map[string]any
+	was := meshConfigAsk
+	t.Cleanup(func() { meshConfigAsk = was })
+	meshConfigAsk = func(_ context.Context, args map[string]any) ([]byte, error) {
+		calls = append(calls, args)
+		return []byte(answers[args["action"].(string)]), nil
+	}
+	return &calls
+}
+
+func manifest(module string, keys map[string]catalogue.SettingDeclaration) *catalogue.Manifest {
+	return &catalogue.Manifest{Module: module, Settings: keys}
+}
+
+func thePull() pullAt {
+	return pullAt{Number: 434, changeSource: changeSource{Owner: "novox", Repo: "mesh-catalog", New: headSHA, Old: baseSHA,
+		Paths: []string{"modules/n8n/module.json", "modules/n8n/README.md"}}}
+}
+
+// 1826/AC1: a key the head adds is sent with its declaration, under the pull request and the head.
+func TestAKeyThePullRequestAddsIsToldToMeshConfig(t *testing.T) {
+	fakeManifests(t, map[string]*catalogue.Manifest{
+		baseSHA: manifest("n8n", map[string]catalogue.SettingDeclaration{"port": {Type: "number"}}),
+		headSHA: manifest("n8n", map[string]catalogue.SettingDeclaration{"port": {Type: "number"},
+			"media-gid": {Type: "number", Required: true}}),
+	})
+	calls := fakeConfig(t, map[string]string{"pull-declares": `{"kept":1}`})
+	tellPullDeclares(context.Background(), io.Discard, []pullAt{thePull()})
+	if len(*calls) != 1 {
+		t.Fatalf("mesh-config was asked %d times: %v", len(*calls), *calls)
+	}
+	c := (*calls)[0]
+	if c["action"] != "pull-declares" || c["pull"] != "novox/mesh-catalog#434" || c["head"] != headSHA {
+		t.Fatalf("the call is %v", c)
+	}
+	body, _ := json.Marshal(c["declares"])
+	var declares map[string]map[string]inventory.DeclaredMirrored
+	if err := json.Unmarshal(body, &declares); err != nil || len(declares) != 1 || declares["n8n"] == nil {
+		t.Fatalf("declares %s: %v", body, err)
+	}
+	mods := []inventory.DeclaredConfigMirrored{{Module: "n8n", Settings: declares["n8n"]}}
+	if _, has := mods[0].Settings["port"]; has || len(mods[0].Settings) != 1 {
+		t.Fatalf("only the added key is told, got %v", mods[0].Settings)
+	}
+	d := mods[0].Settings["media-gid"]
+	if d.Type != "number" || !d.Required {
+		t.Fatalf("the declaration is %+v", d)
+	}
+}
+
+// 1826/AC1: a key whose declaration the head changes is sent; one it leaves as it was is not.
+func TestAnUnchangedKeyIsNotToldAndAChangedOneIs(t *testing.T) {
+	fakeManifests(t, map[string]*catalogue.Manifest{
+		baseSHA: manifest("n8n", map[string]catalogue.SettingDeclaration{"port": {Type: "number"}, "x": {Type: "string"}}),
+		headSHA: manifest("n8n", map[string]catalogue.SettingDeclaration{"port": {Type: "number"}, "x": {Type: "string", Pattern: "a+"}}),
+	})
+	mods, touched, err := pullDeclarations(context.Background(), thePull())
+	if err != nil || !touched || len(mods) != 1 || len(mods[0].Settings) != 1 || mods[0].Settings["x"].Pattern != "a+" {
+		t.Fatalf("%+v %v %v", mods, touched, err)
+	}
+}
+
+// 1826/AC1: a head that changes no module.json, or removes it, is still told, with declares {}: mesh-config re-judges at every
+// head, so a head that reverts the change drops the value held for it (review round 1, finding 1).
+func TestAHeadThatDeclaresNothingIsToldAsEmpty(t *testing.T) {
+	fakeManifests(t, map[string]*catalogue.Manifest{baseSHA: manifest("n8n", nil), headSHA: manifest("n8n", nil)})
+	calls := fakeConfig(t, nil)
+	p := thePull()
+	p.Paths = []string{"modules/n8n/README.md"}
+	tellPullDeclares(context.Background(), io.Discard, []pullAt{p})
+	p = thePull()
+	p.Removed = p.Paths
+	tellPullDeclares(context.Background(), io.Discard, []pullAt{p})
+	if len(*calls) != 2 {
+		t.Fatalf("mesh-config was told %v", *calls)
+	}
+	for _, c := range *calls {
+		if d, _ := json.Marshal(c["declares"]); string(d) != "{}" || c["head"] != headSHA {
+			t.Fatalf("told %v", c)
+		}
+	}
+}
+
+// 1826/AC1: a head whose paths are cut, or whose base is unknown, cannot be read: nothing is told, never an empty set.
+func TestAHeadThatCannotBeReadIsNotToldAsEmpty(t *testing.T) {
+	calls := fakeConfig(t, nil)
+	p := thePull()
+	p.Truncated = true
+	tellPullDeclares(context.Background(), io.Discard, []pullAt{p})
+	if len(*calls) != 0 {
+		t.Fatalf("told %v", *calls)
+	}
+}
+
+// 1826/AC1: a module.json changed without a declaration changing is told as an empty set, so mesh-config re-judges what it holds.
+func TestAChangedManifestWithNoNewDeclarationIsToldAsEmpty(t *testing.T) {
+	m := manifest("n8n", map[string]catalogue.SettingDeclaration{"port": {Type: "number"}})
+	fakeManifests(t, map[string]*catalogue.Manifest{baseSHA: m, headSHA: m})
+	calls := fakeConfig(t, nil)
+	tellPullDeclares(context.Background(), io.Discard, []pullAt{thePull()})
+	if len(*calls) != 1 {
+		t.Fatalf("calls %v", *calls)
+	}
+	if d, _ := json.Marshal((*calls)[0]["declares"]); string(d) != "{}" {
+		t.Fatalf("declares %s", d)
+	}
+}
+
+// 1826/AC1: mesh-config not answering is said and goes on; the check is not stopped.
+func TestMeshConfigNotAnsweringIsSaidAndGoneOn(t *testing.T) {
+	fakeManifests(t, map[string]*catalogue.Manifest{baseSHA: manifest("n8n", nil),
+		headSHA: manifest("n8n", map[string]catalogue.SettingDeclaration{"k": {Type: "string"}})})
+	was := meshConfigAsk
+	t.Cleanup(func() { meshConfigAsk = was })
+	meshConfigAsk = func(context.Context, map[string]any) ([]byte, error) { return nil, io.ErrUnexpectedEOF }
+	var said strings.Builder
+	tellPullDeclares(context.Background(), &said, []pullAt{thePull()})
+	got := heldFor(context.Background(), &said, []pullAt{thePull()})
+	if len(got) != 0 || !strings.Contains(said.String(), "mesh-config") {
+		t.Fatalf("held %v, said %q", got, said.String())
+	}
+}
+
+// 1826/AC2: the held values mesh-config answers for the check's pull requests are what the check request carries.
+func TestTheHeldValuesOfTheChecksPullRequestsAreAsked(t *testing.T) {
+	calls := fakeConfig(t, map[string]string{"held": `{"held":[{"pull":"novox/mesh-catalog#434","head":"` + headSHA +
+		`","node":"ace","module":"n8n","key":"media-gid","value":2000,"approved":"the operator"}]}`})
+	other := pullAt{Number: 7, changeSource: changeSource{Owner: "novox", Repo: "mesh-controller", New: baseSHA}}
+	got := heldFor(context.Background(), io.Discard, []pullAt{thePull(), other})
+	if len(got) != 1 || got[0].Node != "ace" || got[0].Key != "media-gid" || string(got[0].Value) != "2000" {
+		t.Fatalf("got %+v", got)
+	}
+	c := (*calls)[0]
+	pulls, _ := json.Marshal(c["pulls"])
+	if c["action"] != "held" || string(pulls) != `[{"pull":"novox/mesh-catalog#434","head":"`+headSHA+
+		`"},{"pull":"novox/mesh-controller#7","head":"`+baseSHA+`"}]` {
+		t.Fatalf("asked %v %s", c, pulls)
+	}
+}
+
+// 1826/AC2: a value held for a pull request the check is not of is never carried.
+func TestAHeldValueOfAnotherPullRequestIsNotCarried(t *testing.T) {
+	fakeConfig(t, map[string]string{"held": `{"held":[{"pull":"novox/mesh-catalog#999","head":"x","node":"ace","module":"n8n","key":"k","value":1}]}`})
+	if got := heldFor(context.Background(), io.Discard, []pullAt{thePull()}); len(got) != 0 {
+		t.Fatalf("carried %+v", got)
+	}
+}
+
+// 1826/AC2: the check request carries what mesh-config answered; a member of a composed group asks none.
+func TestTheCheckRequestCarriesTheHeldValues(t *testing.T) {
+	fakeManifests(t, map[string]*catalogue.Manifest{baseSHA: manifest("n8n", nil), headSHA: manifest("n8n", nil)})
+	fakeConfig(t, map[string]string{"held": `{"held":[{"pull":"novox/mesh-catalog#434","node":"ace","module":"n8n","key":"media-gid","value":2000}]}`})
+	request := link.BuildRequest{Check: &link.CheckRequest{}}
+	withHeldConfig(context.Background(), io.Discard, &request, []pullAt{thePull()}, true)
+	if len(request.Check.HeldConfig) != 1 || request.Check.HeldConfig[0].Key != "media-gid" {
+		t.Fatalf("the request carries %+v", request.Check.HeldConfig)
+	}
+	request = link.BuildRequest{Check: &link.CheckRequest{}}
+	withHeldConfig(context.Background(), io.Discard, &request, []pullAt{thePull()}, false)
+	if len(request.Check.HeldConfig) != 0 {
+		t.Fatalf("a composed member carries %+v", request.Check.HeldConfig)
+	}
+}
+
+// 1826/AC1: a repository that builds a module of the mesh holds modules; another does not.
+func TestARepositoryThatBuildsAModuleHoldsModules(t *testing.T) {
+	entries := []inventory.Entry{{Manifest: catalogue.Manifest{Module: "a"}, Source: inventory.Source{Repository: "novox/mesh-catalog", Path: "modules/a"}}}
+	if !holdsModules(entries, "novox", "mesh-catalog") || holdsModules(entries, "novox", "hq") {
+		t.Fatal("wrong")
+	}
+}

cmd/mesh-controller/push.go

@@ -284,6 +284,8 @@ func serve(ctx context.Context) (err error) {
 	go mirroringRecords(ctx, inv, bus.Conn, bus)
 	// And the bucket of the files that travel by digest, judged against what each machine's latest declaration names (ADR 0486 §3).
 	go sweepingDeclarationFiles(ctx, inv, bus.Conn)
+	// And the key of each plan in its build phase, which holds the build seat's checks while a delivery builds (ADR 0483 clause 2).
+	go keepingPlansBuilding(ctx, inv, bus.Conn)
 	// Every call carries the lease's epoch, and its record is written only under the lease (novox/hq
 	// to-be 45 §6).
 	link.Calls.UnderLease(func() (uint64, error) { return theLease.epoch(ctx) })

cmd/mesh-controller/queue.go

@@ -91,7 +91,9 @@ type queueAnswer struct {
 	Dead       int            `json:"dead"`
 	MaxDeliver int            `json:"max-deliver"`
 	Asks       []queuedAnswer `json:"asks"`
-	Text       string         `json:"text"`
+	// HeldFor are the delivery plans building, while which the waiting checks are held (ADR 0483 clause 5); empty when none.
+	HeldFor []string `json:"held-for,omitempty"`
+	Text    string   `json:"text"`
 }
 
 // queuedAnswer is one ask as data. Never what the request carries beyond its source — not `held`, every
@@ -120,6 +122,9 @@ type queuedAnswer struct {
 	// Delivery is the how-manyth time an ask in flight was handed out; more than 1 is a restart
 	// (novox/hq issue 594).
 	Delivery int `json:"delivery,omitempty"`
+	// LetThrough is a check that waited past 30 minutes and is let through while a delivery builds: the next one, or the one
+	// that runs (ADR 0483 clause 5).
+	LetThrough bool `json:"let-through,omitempty"`
 }
 
 // aCommitRef is a ref that names a commit by its full hash (SHA-1 or SHA-256).
@@ -130,7 +135,8 @@ var aCommitRef = regexp.MustCompile(`^(?:[0-9a-f]{40}|[0-9a-f]{64})$`)
 func queueAnswerOf(q link.Queue, now time.Time) queueAnswer {
 	waiting, running, dead := q.Of(link.AskWaiting), q.Of(link.AskInFlight), q.Of(link.AskDead)
 	out := queueAnswer{Seat: q.Seat, Waiting: len(waiting), InFlight: len(running), Dead: len(dead),
-		MaxDeliver: q.MaxDeliver, Asks: []queuedAnswer{}, Text: queueText(q, now)}
+		MaxDeliver: q.MaxDeliver, Asks: []queuedAnswer{}, HeldFor: q.Hold.Plans, Text: queueText(q, now)}
+	letNext, letRunning := q.LetThroughOf(now)
 	one := func(a link.QueuedAsk, position int) queuedAnswer {
 		kind := link.KindOf(a.Request)
 		since := a.AskedAt
@@ -143,7 +149,7 @@ func queueAnswerOf(q link.Queue, now time.Time) queueAnswer {
 		}
 		return queuedAnswer{ID: a.ID, State: a.State, Kind: kind, Repository: link.WithoutPassword(a.Repository), Path: a.Path,
 			Ref: a.Ref, Commit: commit, Machine: a.On, WasOn: a.Was, AskedAt: a.AskedAt, Since: since,
-			Position: position, Seq: a.Seq, Delivery: a.Delivery}
+			Position: position, Seq: a.Seq, Delivery: a.Delivery, LetThrough: a.ID != "" && (a.ID == letNext || a.ID == letRunning)}
 	}
 	for _, a := range running {
 		out.Asks = append(out.Asks, one(a, 0))
@@ -179,6 +185,11 @@ func queueText(q link.Queue, now time.Time) string {
 		}
 		return s
 	}
+	letNext, letRunning := q.LetThroughOf(now)
+	const passed = "waited past 30 minutes, let through"
+	if q.HoldFault != "" {
+		fmt.Fprintf(&b, "why checks wait cannot be read, so none is said held: %s\n", q.HoldFault)
+	}
 	if len(running) > 0 {
 		fmt.Fprintln(&b, "\nin flight:")
 		for _, a := range running {
@@ -193,14 +204,27 @@ func queueText(q link.Queue, now time.Time) string {
 			case a.Was != "":
 				where = fmt.Sprintf("handed back by %s, to be handed out again", a.Was)
 			}
-			fmt.Fprintf(&b, "  %-26s %-8s %s — %s, %s (seq %d)\n", a.ID, link.KindOf(a.Request), what(a), where,
-				ago(a.AskedAt), a.Seq)
+			note := ""
+			if a.ID != "" && a.ID == letRunning {
+				note = " — " + passed
+			}
+			fmt.Fprintf(&b, "  %-26s %-8s %s — %s, %s (seq %d)%s\n", a.ID, link.KindOf(a.Request), what(a), where,
+				ago(a.AskedAt), a.Seq, note)
 		}
 	}
 	if len(waiting) > 0 {
 		fmt.Fprintln(&b, "\nwaiting, in the order they are handed out:")
+		// **Why the checks wait** (ADR 0483 clause 5): above them, the plans they are held for.
+		if len(q.Hold.Plans) > 0 && hasCheck(waiting) {
+			fmt.Fprintf(&b, "  checks are held while delivery %s builds; the oldest check that waited 30 minutes goes first, one at a time\n",
+				strings.Join(q.Hold.Plans, ", "))
+		}
 		for _, a := range waiting {
-			fmt.Fprintf(&b, "  %-26s %-8s %s — %s (seq %d)\n", a.ID, link.KindOf(a.Request), what(a), ago(a.AskedAt), a.Seq)
+			note := ""
+			if a.ID != "" && a.ID == letNext {
+				note = " — " + passed + " next"
+			}
+			fmt.Fprintf(&b, "  %-26s %-8s %s — %s (seq %d)%s\n", a.ID, link.KindOf(a.Request), what(a), ago(a.AskedAt), a.Seq, note)
 		}
 	}
 	if len(dead) > 0 {
@@ -218,6 +242,16 @@ func queueText(q link.Queue, now time.Time) string {
 	return b.String()
 }
 
+// hasCheck says a check is among the asks.
+func hasCheck(asks []link.QueuedAsk) bool {
+	for _, a := range asks {
+		if a.Request.Check != nil {
+			return true
+		}
+	}
+	return false
+}
+
 // cancelCommand drops one waiting or dead ask.
 func cancelCommand(ctx context.Context, args []string) error {
 	if len(args) != 1 {

cmd/mesh-controller/queue_held_test.go

@@ -0,0 +1,77 @@
+package main
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// Issue 1688 / 1652 AC5 (ADR 0483 clause 5): the queue names, above the waiting checks, the plan they are held for, and says of a
+// check let through that it waited past 30 minutes.
+
+func aHeldQueue(now time.Time) link.Queue {
+	check := func(id string, ago time.Duration, n int) link.QueuedAsk {
+		return link.QueuedAsk{Seq: uint64(n), ID: id, Repository: "ssh://forge/novox/r", AskedAt: now.Add(-ago), State: link.AskWaiting,
+			Request: link.BuildRequest{ID: id, Check: &link.CheckRequest{Owner: "novox", Repo: "r", Number: n}}}
+	}
+	return link.Queue{Seat: link.TheBuildMachine, Asks: []link.QueuedAsk{
+		check("build-young", 5*time.Minute, 1),
+		check("build-old", 45*time.Minute, 2),
+		check("build-older", 50*time.Minute, 3),
+	}, Hold: link.CheckHold{Plans: []string{"plan-42"}}}
+}
+
+func TestTheQueueNamesThePlanTheChecksAreHeldFor(t *testing.T) {
+	now := time.Date(2026, 10, 21, 12, 0, 0, 0, time.UTC)
+	text := queueText(aHeldQueue(now), now)
+	heldAt := strings.Index(text, "held while delivery plan-42 builds")
+	firstAt := strings.Index(text, "build-young")
+	if heldAt < 0 || firstAt < 0 || heldAt > firstAt {
+		t.Fatalf("the plan the checks are held for is not named above the waiting checks:\n%s", text)
+	}
+	// Nothing building: nothing held.
+	q := aHeldQueue(now)
+	q.Hold = link.CheckHold{}
+	if strings.Contains(queueText(q, now), "held while") {
+		t.Fatal("checks are said held with no delivery building")
+	}
+}
+
+func TestACheckLetThroughIsSaidToHaveWaitedPastThirtyMinutes(t *testing.T) {
+	now := time.Date(2026, 10, 21, 12, 0, 0, 0, time.UTC)
+	q := aHeldQueue(now)
+	text := queueText(q, now)
+	var saidOf []string
+	for _, l := range strings.Split(text, "\n") {
+		if strings.Contains(l, "waited past 30 minutes, let through") {
+			saidOf = append(saidOf, strings.Fields(l)[0])
+		}
+	}
+	if len(saidOf) != 1 || saidOf[0] != "build-older" {
+		t.Fatalf("the check let through next (the oldest) is not the one said: %v\n%s", saidOf, text)
+	}
+	answer := queueAnswerOf(q, now)
+	if len(answer.HeldFor) != 1 || answer.HeldFor[0] != "plan-42" {
+		t.Errorf("held-for = %v", answer.HeldFor)
+	}
+	for _, a := range answer.Asks {
+		if a.LetThrough != (a.ID == "build-older") {
+			t.Errorf("%s let-through = %v", a.ID, a.LetThrough)
+		}
+	}
+	// A check in flight under the let-through key is said too.
+	q.Asks = append(q.Asks, link.QueuedAsk{Seq: 9, ID: "build-running", State: link.AskInFlight, On: "ace", AskedAt: now.Add(-time.Hour),
+		Started: now.Add(-time.Minute), Request: link.BuildRequest{ID: "build-running", Check: &link.CheckRequest{Owner: "novox", Repo: "r", Number: 9}}})
+	q.Hold.LetThrough = &link.LetThrough{Builder: "ace"}
+	if !strings.Contains(queueText(q, now), "build-running") || !strings.Contains(queueText(q, now), "waited past 30 minutes, let through\n") {
+		t.Errorf("the check in flight let through is not said:\n%s", queueText(q, now))
+	}
+	// Younger than the bound: none is said.
+	young := aHeldQueue(now)
+	young.Asks = young.Asks[:1]
+	if strings.Contains(queueText(young, now), "waited past") {
+		t.Error("a check of 5 minutes is said to have waited past 30")
+	}
+}

cmd/mesh-controller/release_plan.go

@@ -577,6 +577,9 @@ func askModule(ctx context.Context, p *inventory.Plan, name string, byName map[s
 	}
 	// **The walk takes the check's build of the same key** (novox/hq ADR 0350 §2): its ask says so, with the pull
 	// requests it answers, whose checks name the part of a differing key.
+	// **The plan's key is there before its first build is** (ADR 0483 clause 2): a check taken between the ask and the plan's save
+	// would hold a place for its whole run.
+	sayBuilding(ctx, p.ID, now)
 	id, err := askABuild(withReuse(ctx, reuseWithVerdicts(ctx, p.ID, reuseAskOf(p), mergedHeadsOf(p))), source,
 		e.Source.Path, ref)
 	if err != nil {

go.mod

@@ -3,7 +3,7 @@ module github.com/novox/mesh-controller
 go 1.26.0
 
 require (
-	git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021173436-07a65927c362
+	git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261022132648-bd7731f3588c
 	github.com/jackc/pgx/v5 v5.10.0
 	github.com/nats-io/nats-server/v2 v2.11.17
 	github.com/nats-io/nats.go v1.54.0

go.sum

@@ -1,7 +1,7 @@
 git.novox.be/novox/mesh-host v0.0.0-20261018171808-9d9e3a46c4f5 h1:E5stfIeCN6uYgA9TCv+4K8JgaURg3zQppvUgJLaDMP4=
 git.novox.be/novox/mesh-host v0.0.0-20261018171808-9d9e3a46c4f5/go.mod h1:4wyoCr6IIIIarEUuROThWDj7DAvJvIidqMjWcpSnOwE=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021173436-07a65927c362 h1:Ud/YHmhlm0qdB45LyDvxq7l4x6Bg2Ye0siHK5JFE+kk=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021173436-07a65927c362/go.mod h1:ouERNpZizzwZ0HLEtAypsY9FR20FyUgUYRni6J7kVCY=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261022132648-bd7731f3588c h1:UKlwMw6fmesDqe0aL0lfI/ivhorsGjAvh9XefFjhNI4=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261022132648-bd7731f3588c/go.mod h1:ouERNpZizzwZ0HLEtAypsY9FR20FyUgUYRni6J7kVCY=
 github.com/antithesishq/antithesis-sdk-go v0.7.0-default-no-op h1:Z/MZK75wC/NSrkgqeNIa7jexam9uWzhLmFTSCPI/kn0=
 github.com/antithesishq/antithesis-sdk-go v0.7.0-default-no-op/go.mod h1:FQyySiasQQM8735Ddel3MRojmy4dA1IqCeyJ5jmPMbI=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=

internal/broker/checks.go

@@ -46,6 +46,7 @@ func CheckStreams() []Stream {
 			Retention:         RetentionWorkQueue,
 			MaxAge:            7 * 24 * 60 * 60,
 			MaxMsgsPerSubject: 1,
+			Direct:            true,
 			Why: "the checks of pull requests marked ready, taken after a delivery build and before any other check " +
 				"(novox/hq ADR 0406 §3); one subject a pull request, the newest request kept, so a newer one replaces a " +
 				"request still waiting",
@@ -56,6 +57,7 @@ func CheckStreams() []Stream {
 			Retention:         RetentionWorkQueue,
 			MaxAge:            7 * 24 * 60 * 60,
 			MaxMsgsPerSubject: 1,
+			Direct:            true,
 			Why: "every other check, taken last and in the order asked (novox/hq ADR 0406 §3); one subject a pull " +
 				"request, the newest request kept; one left behind for a head already judged is dropped when taken",
 		},
@@ -98,6 +100,13 @@ func holderCheckGrants() []string {
 		"$KV."+CheckRunningBucket+".>",
 		"$JS.API.STREAM.INFO.KV_"+CheckRunningBucket,
 		"$JS.API.DIRECT.GET.KV_"+CheckRunningBucket+".>")
+	// And, to hold checks while a delivery builds (ADR 0483, issues 1687 and 1688): the bucket of the plans building, **read and
+	// never written** (the controller's alone, so no `$KV.` subject of it is granted), and the oldest waiting ask of each check
+	// queue, read by a direct get that takes nothing from the queue and so counts against no delivery of the ask.
+	pub = append(pub, readGrants(PlansBuildingBucket, "")...)
+	for _, w := range CheckWorkers() {
+		pub = append(pub, "$JS.API.DIRECT.GET."+w.Stream, "$JS.API.DIRECT.GET."+w.Stream+".>")
+	}
 	return pub
 }
 

internal/broker/checks_test.go

@@ -40,3 +40,37 @@ func TestTheBuildAgentReadsAndWatchesThePullRequestsKeys(t *testing.T) {
 		}
 	}
 }
+
+// Issue 1687 (ADR 0483 clause 2): a holder of the build seat reads the bucket of the plans building and writes none of it, and
+// reads the oldest waiting ask of each check queue by a direct get, which takes nothing from the queue.
+func TestTheBuildSeatsHoldersReadThePlansBuildingAndWriteNone(t *testing.T) {
+	seat := Seat{Name: TheBuildSeat, Scope: "node", Accepts: []string{"build"}, Emits: []string{"built", "started"}}
+	p := Principal{Kind: KindModule, Node: "one", Module: "build-agent", Holds: []Seat{seat}, PasswordHash: "x"}
+	perms, err := PermissionsFor(p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	stream := "KV_" + PlansBuildingBucket
+	for _, s := range []string{
+		"$JS.API.STREAM.INFO." + stream,
+		"$JS.API.DIRECT.GET." + stream + ".>",
+		"$JS.API.CONSUMER.CREATE." + stream + ".>",
+		"$JS.API.DIRECT.GET.CHECKS_READY",
+		"$JS.API.DIRECT.GET.CHECKS_OTHER",
+	} {
+		has(t, perms.Publish, s)
+	}
+	for _, s := range perms.Publish {
+		if SubjectsOverlap(s, "$KV."+PlansBuildingBucket+".plan-1") {
+			t.Errorf("a holder of the build seat may write %s through %q", PlansBuildingBucket, s)
+		}
+	}
+	// And the controller alone writes it, as the writers table says.
+	for _, row := range WritersTable {
+		for _, s := range row.Subjects {
+			if s == "$KV."+PlansBuildingBucket+".>" && row.Writes(p, "$KV."+PlansBuildingBucket+".plan-1") {
+				t.Errorf("%q lets the build seat's holder write the plans building", row.State)
+			}
+		}
+	}
+}

internal/broker/controller_buckets.go

@@ -63,6 +63,26 @@ var (
 	// repository: the controller reads the ask's warrant from the router and accepts only the operator's Approve of
 	// those heads. Written by the controller alone, from the announcement, when it holds the lease.
 	DeliveryMergesBucket = BucketName(ControllerSeat, "delivery-merges")
+	// PlansBuildingBucket holds one key per delivery plan in its build phase (novox/hq ADR 0483 clause 2, issue 1687): the key
+	// is `<plan id>` (`plan-<digits>`), its value the plan, the time its build phase began and the time of the last refresh.
+	// The controller (lease holder) puts it when the plan's first build is asked, puts it again about every thirty seconds
+	// while the plan builds, and deletes it when the phase ends (every build of the last tier built, or the plan fails, stops
+	// or waits on the operator); the bucket's age, PlansBuildingKeptFor, is how long a key outlives a controller that
+	// stopped. **Read by the build seat's holders and the checker, written by the controller alone**: a holder takes no new
+	// check while any key is there, but for one that waited past ADR 0483's bound. A reader lists the keys and reads none of
+	// their values to decide that (`link.BuildingPlans`).
+	PlansBuildingBucket = BucketName(ControllerSeat, PlansBuilding)
+)
+
+// PlansBuilding is the local name of the bucket of the plans building, as a reader names it in `reads`
+// (`mesh-controller.plans-building`).
+const PlansBuilding = "plans-building"
+
+// PlansBuildingKeptFor is the age of a plan-building key: the controller puts it again at PlansBuildingRefresh, so a
+// controller that stopped leaves checks held at most this long (ADR 0483 clause 2).
+const (
+	PlansBuildingKeptFor = 2 * time.Minute
+	PlansBuildingRefresh = 30 * time.Second
 )
 
 // DeliveryMergesKeptFor is how long a merge mesh-delivery announced is kept: a week, as the events are.
@@ -133,7 +153,7 @@ func ChainBuckets() []string { return []string{BuildsBucket, RolloutsBucket, Ass
 // ControllerMirrors are the local names of the controller's buckets a module may read: the record mirrors and the
 // chain's buckets.
 func ControllerMirrors() []string {
-	return []string{MirrorAssignments, MirrorDeclaredConfig, MirrorPredefined, ChainBuilds, ChainRollouts, ChecksRunning}
+	return []string{MirrorAssignments, MirrorDeclaredConfig, MirrorPredefined, ChainBuilds, ChainRollouts, ChecksRunning, PlansBuilding}
 }
 
 // MirrorsWrittenByAnother are the controller's mirrors whose writer is not the controller, each with its reason: the rule
@@ -204,14 +224,14 @@ func IsControllerBucket(bucket string) bool {
 		bucket == AssignmentsBucket || bucket == DeclaredConfigBucket || bucket == PredefinedBucket ||
 		bucket == MergeWindowBucket || bucket == RolloutSilentBucket || bucket == CheckRunningBucket ||
 		bucket == DeliveryMergesBucket || bucket == BuildsBucket || bucket == RolloutsBucket ||
-		bucket == delivery.HaveBucket
+		bucket == PlansBuildingBucket || bucket == delivery.HaveBucket
 }
 
 // ControllerBuckets are the controller's own buckets, in the order they are asserted.
 func ControllerBuckets() []string {
 	return []string{LeaseBucket, CallsBucket, HandActsBucket, ConditionsBucket, ConditionHistoryBucket, AskedBucket,
 		AssignmentsBucket, DeclaredConfigBucket, PredefinedBucket, MergeWindowBucket, RolloutSilentBucket, CheckRunningBucket,
-		DeliveryMergesBucket, BuildsBucket, RolloutsBucket, delivery.HaveBucket}
+		DeliveryMergesBucket, PlansBuildingBucket, BuildsBucket, RolloutsBucket, delivery.HaveBucket}
 }
 
 // ControllerBucketsAsserter is what raising the controller's buckets needs of a connection.
@@ -354,6 +374,22 @@ func (j *JetStream) EnsureControllerBuckets() error {
 	}); err != nil {
 		return fmt.Errorf("asserting bucket %s: %w", CheckRunningBucket, err)
 	}
+	// **The plans building: keys that age** (ADR 0483 clause 2, issue 1687). One message a key, each refresh a new one, so the
+	// age of the bucket is how long a key outlives a controller that stopped refreshing it.
+	if _, err := js.CreateOrUpdateKeyValue(ctx, jetstream.KeyValueConfig{
+		Bucket: PlansBuildingBucket,
+		Description: "the delivery plans in their build phase (novox/hq ADR 0483): `<plan id>` holds the plan and when its " +
+			"build phase began; put when the plan's first build is asked and about every thirty seconds, deleted when the " +
+			"phase ends, gone within two minutes of a controller that stopped; read by the build seat's holders, which " +
+			"take no new check while a key is there; written by the controller alone",
+		History:      1,
+		TTL:          PlansBuildingKeptFor,
+		MaxValueSize: 4 << 10,
+		MaxBytes:     8 << 20,
+		Storage:      jetstream.FileStorage,
+	}); err != nil {
+		return fmt.Errorf("asserting bucket %s: %w", PlansBuildingBucket, err)
+	}
 	// **The merges mesh-delivery announced: keys that age** (ADR 0420 §7, issue 1025). One message a key; a week.
 	if _, err := js.CreateOrUpdateKeyValue(ctx, jetstream.KeyValueConfig{
 		Bucket: DeliveryMergesBucket,

internal/broker/jetstream.go

@@ -2,10 +2,7 @@ package broker
 
 import (
 	"context"
-	"crypto/sha256"
 	"crypto/tls"
-	"crypto/x509"
-	"encoding/hex"
 	"errors"
 	"fmt"
 	"os"
@@ -112,25 +109,6 @@ func DialPinned(url, fingerprint string, opts ...nats.Option) (*JetStream, error
 	return Dial(url, opts...)
 }
 
-// PinnedToFingerprint accepts exactly the certificate with this SHA-256 and no other.
-func PinnedToFingerprint(want string) *tls.Config {
-	return &tls.Config{
-		InsecureSkipVerify: true, //nolint:gosec // replaced by the pin below, which is stricter
-		MinVersion:         tls.VersionTLS12,
-		VerifyPeerCertificate: func(rawCerts [][]byte, _ [][]*x509.Certificate) error {
-			if len(rawCerts) == 0 {
-				return errors.New("the bus presented no certificate")
-			}
-			sum := sha256.Sum256(rawCerts[0])
-			got := "sha256:" + hex.EncodeToString(sum[:])
-			if got != want {
-				return fmt.Errorf("the bus presented a certificate this mesh does not know (%s…), expected %s…", got[:23], want[:23])
-			}
-			return nil
-		},
-	}
-}
-
 // Conn is the connection itself, for what the mesh keeps off JetStream on purpose — a heartbeat,
 // a tool call — where a lost message is answered by the next one or by a timeout the caller
 // already handles (design 25 §3).

internal/broker/log.go

@@ -98,17 +98,6 @@ func (l Log) Config() jetstream.StreamConfig {
 	}
 }
 
-// LogIssued is one log an assignment may reach, by the name its module uses for it (novox/hq ADR
-// 0297): its stream, the subject its entries go under, and whether it may append. Only the owner's
-// instances are issued a log, so Writes is always true today; it is said so the runtime need not
-// assume it.
-type LogIssued struct {
-	Name    string `json:"name"`
-	Stream  string `json:"stream"`
-	Subject string `json:"subject"`
-	Writes  bool   `json:"writes"`
-}
-
 // logsIssuedFor is every log a module's code may reach, as its membership lists them: its own.
 func logsIssuedFor(d Declared) []LogIssued {
 	var out []LogIssued

internal/broker/membership.go

@@ -1,7 +1,6 @@
 package broker
 
 import (
-	"encoding/json"
 	"slices"
 	"sort"
 	"strings"
@@ -16,81 +15,6 @@ import (
 // grant is the same composition read the other way. The shape issued today is the shape the mesh
 // already had, so nothing moves when a membership first arrives; only who decides it moves.
 
-// Membership is one assignment's subjects: what this instance of a module on this machine serves,
-// and what it may reach.
-type Membership struct {
-	Node   string `json:"node"`
-	Module string `json:"module"`
-	// Serves is every address a tool of this instance answers on. `{tool}` stands for the tool's
-	// own name, which the module knows and the mesh does not need to: the mesh issues the address,
-	// the runtime fills the name. An address with a queue is shared with the module's other
-	// instances, and the bus hands each call to one of them; an address without is this instance's.
-	Serves []Served `json:"serves"`
-	// Seats is every verb of a seat this instance holds, at the subject the seat's callers use.
-	Seats []SeatServed `json:"seats,omitempty"`
-	// Emits is where an event of this module lands; `{event}` stands for the event's name.
-	Emits string `json:"emits"`
-	// Reaches is each tool this module may call, `<module>.<tool>`, to the subjects that reach it:
-	// the first is whichever instance answers, when the mesh issued one; the rest name a machine.
-	Reaches map[string][]string `json:"reaches,omitempty"`
-	// Tools is where this instance answers what it serves — the runtime's one verb of its own.
-	Tools string `json:"tools"`
-	// Receives is what this assignment is given for each requirement it receives, by requirement:
-	// the contributions of every module that asked for it, as the catalogue composed them (novox/hq
-	// ADR 0167). The same list its received file is written from, so the two cannot disagree; a
-	// requirement nobody contributed to is an empty list, never absent. Kept as JSON because the
-	// catalogue owns the shape of a contribution and the bus only carries it.
-	Receives map[string]json.RawMessage `json:"receives,omitempty"`
-	// Mesh is every machine's address on the private network — what a rule saying "from the mesh"
-	// resolves to in the packet filter, issued here from the same list (novox/hq ADR 0167). A
-	// module that must tell the mesh from the world, the route proxy serving an internal name, reads
-	// it here rather than keeping a definition of its own.
-	Mesh []string `json:"mesh,omitempty"`
-	// State is every bucket this module's code may reach, by the name it uses for each, and whether
-	// it may write it (novox/hq ADR 0201): the runtime answers a bundle's state verbs from this list
-	// and refuses, with the reason, what is not on it — the bus enforces only the union over every
-	// module on the machine.
-	State []StateIssued `json:"state,omitempty"`
-	// Logs is every log this module's code may reach, by the name it uses for each (novox/hq ADR 0297):
-	// its own and no other's, since a log is its owner's alone. The runtime answers a bundle's log verbs
-	// from this list and refuses, with the reason, a log not on it.
-	Logs []LogIssued `json:"logs,omitempty"`
-	// SeatTraffic is what this module's code may submit, say, hear, take, ask, answer and read on seats
-	// that name their caller or their kind (novox/hq ADR 0259 §3). The runtime carrying the module
-	// publishes, takes and answers for it only what is listed here: the bus enforces only the union
-	// over every module on the machine, so one module's code reaching another's name or kind through
-	// the runtime is the runtime's to refuse.
-	SeatTraffic *SeatTraffic `json:"seat-traffic,omitempty"`
-	// Streams are this module's own streams (novox/hq ADR 0363 §2): an event one of them carries is published
-	// on that stream's subject, never on Emits. Hears are the module streams it hears, each through a durable
-	// consumer on that stream the runtime binds beside the one on EVENTS (§8).
-	Streams []StreamIssued `json:"streams,omitempty"`
-	Hears   []HeardIssued  `json:"hears,omitempty"`
-	// Waits are the event families a session may wait on through the mesh MCP server, the tool runner's
-	// alone (novox/hq ADR 0367 §2): the subjects its account is granted, under the names a session asks for.
-	// The tool runner refuses any family not listed here.
-	Waits []WaitIssued `json:"waits,omitempty"`
-}
-
-// Served is one address a tool is answered on.
-type Served struct {
-	Subject string `json:"subject"`
-	Queue   string `json:"queue,omitempty"`
-}
-
-// SeatServed is one verb of a held seat, where its callers ask.
-type SeatServed struct {
-	Seat    string `json:"seat"`
-	Verb    string `json:"verb"`
-	Subject string `json:"subject"`
-}
-
-// MembershipSubject is the one address a runtime derives for itself: where its own membership is
-// published, from the two names its credential carries. Everything else is in the membership.
-func MembershipSubject(node, module string) string {
-	return "mesh.assignment." + node + "." + module
-}
-
 // Placements is where every module runs, for deciding which instance answers for the module.
 type Placements struct {
 	// Nodes is each module's machines.

internal/broker/modstreams.go

@@ -260,21 +260,6 @@ func ownStreamGrants(module string, streams []ModuleStream) []string {
 	return out
 }
 
-// StreamIssued is one of a module's own streams as its membership names it (ADR 0363 §2): the events it
-// carries, as the bus spells them, and the subject an event of them is published on, `{event}` the event.
-type StreamIssued struct {
-	Stream  string   `json:"stream"`
-	Events  []string `json:"events"`
-	Subject string   `json:"subject"`
-}
-
-// HeardIssued is one module stream an assignment hears, as its membership names it (ADR 0363 §8): the
-// stream and the durable consumer on it the runtime binds.
-type HeardIssued struct {
-	Stream   string `json:"stream"`
-	Consumer string `json:"consumer"`
-}
-
 // streamsIssuedFor is every stream of its own a module's membership names.
 func streamsIssuedFor(d Declared) []StreamIssued {
 	var out []StreamIssued

internal/broker/nats.go

@@ -424,6 +424,11 @@ var DegradableGrants = []DegradableGrant{
 		Reason: "refused: the controller asserts this bucket through the API and writes none of its keys — the build seat's " +
 			"holders do (ADR 0406 §3, issue 974)",
 	},
+	{
+		Subject: "$KV." + PlansBuildingBucket + ".>",
+		Reason: "refused: the controller then says no plan builds, and no check is held while a delivery builds — a check run " +
+			"wrongly costs a delivery a place, a check held wrongly costs a pull request its turn (ADR 0483 clause 2, issue 1687)",
+	},
 	{
 		Subject: "mesh.seat." + ControllerSeat + ".event.sent",
 		Reason: "refused: the controller says a tier sent to a machine only for outsiders, and a send that could not " +
@@ -709,7 +714,7 @@ func PermissionsFor(p Principal) (Permissions, error) {
 		// And asking the operator (novox/hq ADR 0259): an ask and its cancel under its own name, its warrants
 		// heard under its own name, the record of its asks read under its own name — as any user of the seat,
 		// derived the same way, from the seat its holder declares.
-		tp, ts := SeatTrafficOf(ControllerSeat, nil, p.Uses, nil).grants()
+		tp, ts := seatTrafficGrants(SeatTrafficOf(ControllerSeat, nil, p.Uses, nil))
 		pub = append(pub, tp...)
 		sub = append(sub, ts...)
 		// And asks who answers (novox/hq to-be 45 §4, D3): the self-check finds every seat's holder by
@@ -1042,7 +1047,7 @@ func PermissionsFor(p Principal) (Permissions, error) {
 
 		// 6. Its traffic on seats that name their caller or their kind, ask proofs or keep records
 		//    (novox/hq ADR 0259 §3).
-		tp, ts := SeatTrafficOf(p.Module, p.Holds, p.Uses, p.Watches).grants()
+		tp, ts := seatTrafficGrants(SeatTrafficOf(p.Module, p.Holds, p.Uses, p.Watches))
 		pub = append(pub, tp...)
 		sub = append(sub, ts...)
 
@@ -1166,7 +1171,7 @@ func PermissionsFor(p Principal) (Permissions, error) {
 		// not publish under another's name or kind through it is the runtime's to keep, from the seat
 		// traffic each module's membership lists.
 		for _, d := range p.Carries {
-			tp, ts := SeatTrafficOf(d.Module, d.Holds, d.Uses, d.Watches).grants()
+			tp, ts := seatTrafficGrants(SeatTrafficOf(d.Module, d.Holds, d.Uses, d.Watches))
 			pub = append(pub, tp...)
 			sub = append(sub, ts...)
 		}

internal/broker/onnats.go

@@ -35,39 +35,6 @@ func OnNATS() (address string, on bool, err error) {
 	return address, true, nil
 }
 
-// CredentialIn reads the user and password out of a bus address, and the address without them.
-//
-// The controller's own credential arrives in its address, the way the old bus's does. Split out so the
-// controller can record a hash of what it is actually using: its user is created by the installer at a
-// bootstrap password, before the controller exists to mint one, and a composition that left itself out
-// would produce a bus the writer cannot connect to.
-func CredentialIn(address string) (user, password, bare string) {
-	at := strings.LastIndex(address, "@")
-	if at < 0 {
-		return "", "", address
-	}
-	scheme := ""
-	rest := address[:at]
-	if i := strings.Index(rest, "://"); i >= 0 {
-		scheme, rest = rest[:i+3], rest[i+3:]
-	}
-	user, password, _ = strings.Cut(rest, ":")
-	return user, password, scheme + address[at+1:]
-}
-
-// BareAddress is a bus address with any credential stripped, for something that only needs to know
-// whether a server is answering there.
-func BareAddress(address string) string {
-	_, _, bare := CredentialIn(address)
-	if bare == "" {
-		return address
-	}
-	if strings.Contains(bare, "://") {
-		return bare
-	}
-	return "nats://" + bare
-}
-
 // BusAddress is where the mesh's bus is, with this process's credential, and refuses to be empty:
 // there is one bus, and a control plane without it can hold records and answer nothing (novox/hq
 // ADR 0131, design 28 task 5.5).

internal/broker/onnats_test.go

@@ -1,28 +0,0 @@
-package broker
-
-import (
-	"testing"
-)
-
-// Which bus the mesh is on is one fact, and being told about both is refused.
-//
-
-// The controller's own credential arrives in its address, and has to be readable out of it — its user
-// is created by the installer at a bootstrap password, before the controller exists to mint one.
-func TestACredentialIsReadOutOfABusAddress(t *testing.T) {
-	for _, c := range []struct{ in, user, password, bare string }{
-		{"nats://controller:secret@127.0.0.1:4222", "controller", "secret", "nats://127.0.0.1:4222"},
-		{"controller:secret@127.0.0.1:4222", "controller", "secret", "127.0.0.1:4222"},
-		{"nats://127.0.0.1:4222", "", "", "nats://127.0.0.1:4222"},
-		{"127.0.0.1:4222", "", "", "127.0.0.1:4222"},
-		// A password containing an at-sign: split on the last one, or the address becomes part of the
-		// credential and the connection goes somewhere nobody named.
-		{"nats://controller:a@b@127.0.0.1:4222", "controller", "a@b", "nats://127.0.0.1:4222"},
-	} {
-		user, password, bare := CredentialIn(c.in)
-		if user != c.user || password != c.password || bare != c.bare {
-			t.Errorf("%q read as %q/%q at %q; wanted %q/%q at %q",
-				c.in, user, password, bare, c.user, c.password, c.bare)
-		}
-	}
-}

internal/broker/plans_building_live_test.go

@@ -0,0 +1,134 @@
+//go:build integration
+
+package broker
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/nats-io/nats-server/v2/server"
+	"github.com/nats-io/nats.go"
+	"github.com/nats-io/nats.go/jetstream"
+	"golang.org/x/crypto/bcrypt"
+)
+
+// **A holder of the build seat reads the plans building and the server refuses its write** (novox/hq ADR 0483 clause 2, issue
+// 1687): on a real server whose users are composed as the controller composes them, the controller makes the bucket and puts a
+// plan's key; the build agent's credential lists the keys and gets one, and its put of a key is refused with a permissions
+// violation. It also reads the first waiting ask of a check queue by a direct get, which takes nothing from the queue.
+func TestNatsTheBuildSeatsHoldersReadThePlansBuildingAndTheServerRefusesTheirWrite(t *testing.T) { // 1687
+	hash, err := bcrypt.GenerateFromPassword([]byte("pw"), bcrypt.MinCost)
+	if err != nil {
+		t.Fatal(err)
+	}
+	seat := Seat{Name: TheBuildSeat, Scope: "node", Accepts: []string{"build"}, Emits: []string{"built", "started"}}
+	users, err := Users(Records{Nodes: []string{"alpha"}, Assigned: map[string][]Declared{
+		"alpha": {{Module: RuntimeModule}, {Module: "build-agent", Holds: []Seat{seat}}},
+	}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for i := range users {
+		users[i].PasswordHash = string(hash)
+	}
+	accounts, err := ComposeAccounts(users)
+	if err != nil {
+		t.Fatal(err)
+	}
+	conf := filepath.Join(t.TempDir(), "bus.conf")
+	if err := os.WriteFile(conf, []byte("listen: 127.0.0.1:-1\njetstream { store_dir: "+
+		`"`+t.TempDir()+`"`+" }\n"+accounts), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	opts, err := server.ProcessConfigFile(conf)
+	if err != nil {
+		t.Fatalf("the composed accounts do not parse: %v", err)
+	}
+	opts.NoLog, opts.NoSigs = true, true
+	s, err := server.NewServer(opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	go s.Start()
+	if !s.ReadyForConnections(10 * time.Second) {
+		t.Fatal("the bus did not come up")
+	}
+	t.Cleanup(s.Shutdown)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	connect := func(user string) (*nats.Conn, chan error) {
+		t.Helper()
+		refused := make(chan error, 8)
+		nc, err := nats.Connect(s.ClientURL(), nats.UserInfo(user, "pw"), nats.CustomInboxPrefix("_INBOX."+user),
+			nats.ErrorHandler(func(_ *nats.Conn, _ *nats.Subscription, err error) { refused <- err }))
+		if err != nil {
+			t.Fatalf("%s cannot connect: %v", user, err)
+		}
+		t.Cleanup(nc.Close)
+		return nc, refused
+	}
+	controller, _ := connect(ControllerName)
+	cj := OnConn(controller)
+	if err := AssertMeshStreams(cj); err != nil {
+		t.Fatalf("the controller cannot make the streams: %v", err)
+	}
+	if err := cj.EnsureControllerBuckets(); err != nil {
+		t.Fatalf("the controller cannot make its buckets: %v", err)
+	}
+	cjs, _ := jetstream.New(controller)
+	ckv, err := cjs.KeyValue(ctx, PlansBuildingBucket)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := ckv.Put(ctx, "plan-1", []byte(`{"plan":"plan-1"}`)); err != nil {
+		t.Fatalf("the controller cannot put a plan's key: %v", err)
+	}
+
+	holder, refused := connect("alpha.build-agent")
+	hjs, err := jetstream.New(holder)
+	if err != nil {
+		t.Fatal(err)
+	}
+	kv, err := hjs.KeyValue(ctx, PlansBuildingBucket)
+	if err != nil {
+		t.Fatalf("a holder of the build seat cannot bind %s: %v", PlansBuildingBucket, err)
+	}
+	keys, err := kv.Keys(ctx)
+	if err != nil || len(keys) != 1 || keys[0] != "plan-1" {
+		t.Fatalf("the holder lists %v (%v), want plan-1", keys, err)
+	}
+	if e, err := kv.Get(ctx, "plan-1"); err != nil || e == nil {
+		t.Fatalf("the holder cannot get the key: %v", err)
+	}
+	// Its write is refused by the server.
+	if err := holder.Publish("$KV."+PlansBuildingBucket+".plan-2", []byte(`{}`)); err != nil {
+		t.Fatal(err)
+	}
+	_ = holder.Flush()
+	select {
+	case err := <-refused:
+		if !errors.Is(err, nats.ErrPermissionViolation) {
+			t.Errorf("the server said %v, want a permissions violation", err)
+		}
+	case <-time.After(3 * time.Second):
+		t.Error("the server did not refuse the holder's put of a plan's key")
+	}
+	if _, err := ckv.Get(ctx, "plan-2"); !errors.Is(err, jetstream.ErrKeyNotFound) {
+		t.Errorf("the refused put left a key: %v", err)
+	}
+
+	// And the direct get of a check queue's first waiting ask, which is granted.
+	reply, err := holder.RequestWithContext(ctx, "$JS.API.DIRECT.GET."+ChecksOtherStream, []byte(`{"seq":1,"next_by_subj":"`+
+		CheckSubjectPrefix(TheBuildSeat, false)+`>"}`))
+	if err != nil {
+		t.Fatalf("the holder's direct get of %s was not answered: %v", ChecksOtherStream, err)
+	}
+	if reply.Header.Get("Status") != "404" {
+		t.Errorf("an empty queue answered %q, want 404", reply.Header.Get("Status"))
+	}
+}

internal/broker/plans_building_mirror_test.go

@@ -0,0 +1,30 @@
+package broker
+
+import (
+	"slices"
+	"testing"
+)
+
+// Issue 1687 (ADR 0483 clause 2): a module whose manifest reads mesh-controller.plans-building may name it in `reads`, and
+// reads the bucket and writes none; the controller writes it, so it is no mirror written by another.
+func TestAModuleReadingPlansBuildingReadsAndWritesNone(t *testing.T) {
+	if !slices.Contains(ControllerMirrors(), "plans-building") || BucketName(ControllerSeat, PlansBuilding) != PlansBuildingBucket {
+		t.Fatalf("a module cannot name %s in `reads`: %v", PlansBuildingBucket, ControllerMirrors())
+	}
+	if _, other := MirrorsWrittenByAnother[PlansBuilding]; other {
+		t.Error("the controller writes the plans building itself")
+	}
+	perms, err := PermissionsFor(Principal{Kind: KindModule, Node: "one", Module: "mesh-delivery-checker", PasswordHash: "x",
+		Reads: []string{"mesh-controller.plans-building"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	stream := "KV_" + PlansBuildingBucket
+	has(t, perms.Publish, "$JS.API.STREAM.INFO."+stream)
+	has(t, perms.Publish, "$JS.API.DIRECT.GET."+stream+".>")
+	for _, p := range perms.Publish {
+		if SubjectsOverlap(p, "$KV."+PlansBuildingBucket+".plan-1") {
+			t.Errorf("the reading module may write %s through %q", PlansBuildingBucket, p)
+		}
+	}
+}

internal/broker/sdk_membership.go

@@ -0,0 +1,38 @@
+package broker
+
+import (
+	"git.novox.be/novox/mesh-sdk/go/membership"
+	"git.novox.be/novox/mesh-sdk/go/process"
+)
+
+// The membership the mesh issues an assignment (novox/hq ADR 0160), its subject, its stream, the bare address and the
+// pin are mesh-sdk's, public so that a module's program outside this Go module, the route proxy, reads them too
+// (novox/hq ADR 0480 clause 4, issue 1633). This package keeps no second copy: what follows only names them where the
+// controller already did.
+type (
+	Membership   = membership.Membership
+	Served       = membership.Served
+	SeatServed   = membership.SeatServed
+	StateIssued  = membership.StateIssued
+	LogIssued    = membership.LogIssued
+	Worker       = membership.Worker
+	SeatTraffic  = membership.SeatTraffic
+	KindHeld     = membership.KindHeld
+	StreamIssued = membership.StreamIssued
+	HeardIssued  = membership.HeardIssued
+	WaitIssued   = membership.WaitIssued
+)
+
+// AssignmentsStream holds every assignment's membership, the newest per subject.
+const AssignmentsStream = membership.AssignmentsStream
+
+var (
+	// MembershipSubject is where an assignment's own membership is published.
+	MembershipSubject = membership.Subject
+	// CredentialIn reads the user and password out of a bus address, and the address without them.
+	CredentialIn = membership.CredentialIn
+	// BareAddress is a bus address with any credential stripped.
+	BareAddress = membership.BareAddress
+	// PinnedToFingerprint accepts exactly the certificate with this SHA-256 and no other.
+	PinnedToFingerprint = process.PinnedToFingerprint
+)

internal/broker/seattraffic.go

@@ -24,44 +24,6 @@ import "sort"
 // And one read: **a holder's records**, a bucket the seat names, read by each user under its own name only
 // (`$KV.<bucket>.<module>.>`), so an asker reads the state of its own asks and no other asker's.
 
-// Worker is one durable consumer a holder pulls a seat's work from.
-type Worker struct {
-	Stream   string
-	Consumer string
-	Filter   string
-}
-
-// SeatTraffic is one module's seat traffic beyond tools. Publish and Subscribe are subject patterns, in the
-// server's wildcards; the runtime that carries the module checks a bundle's request against them, since
-// the runtime's own principal holds the union of every module it carries.
-type SeatTraffic struct {
-	// Publish is what it submits (accepts of seats it uses), says (events of seats it holds) and asks
-	// (proofs of seats it holds a kind of).
-	Publish []string `json:"publish,omitempty"`
-	// Subscribe is what it hears: events of seats it uses that are named by caller, events of seats it
-	// watches, and accepts of seats it holds.
-	Subscribe []string `json:"subscribe,omitempty"`
-	// Answers is the proof subjects it answers, as a watcher of a kinded seat.
-	Answers []string `json:"answers,omitempty"`
-	// Workers are the work queues it takes from, as a holder.
-	Workers []Worker `json:"workers,omitempty"`
-	// Records is the direct-get subjects of the records it reads under its own name.
-	Records []string `json:"records,omitempty"`
-	// Kinds are the holders of every kinded bench it uses or watches, with what each promises: the one
-	// account of which channel is which, and what it can carry, that the router judges an answer by. The
-	// controller's, from the claims, never a channel's word (novox/hq ADR 0259 §5).
-	Kinds []KindHeld `json:"kinds,omitempty"`
-}
-
-// KindHeld is one kind of a kinded bench and who holds it.
-type KindHeld struct {
-	Seat         string   `json:"seat"`
-	Kind         string   `json:"kind"`
-	Module       string   `json:"module"`
-	Node         string   `json:"node"`
-	Capabilities []string `json:"capabilities,omitempty"`
-}
-
 // KindedBenches are the seats that may be kinded (ADR 0234 §2): making another is a decision, recorded.
 var KindedBenches = map[string]bool{"channel": true, "intake": true}
 
@@ -175,9 +137,9 @@ func SeatTrafficOf(module string, holds, uses, watches []Seat) SeatTraffic {
 	return t
 }
 
-// grants is the bus permissions seat traffic needs: the subjects themselves, and the JetStream API a
+// seatTrafficGrants is the bus permissions seat traffic needs: the subjects themselves, and the JetStream API a
 // worker is pulled and acknowledged through and a record is read through.
-func (t SeatTraffic) grants() (pub, sub []string) {
+func seatTrafficGrants(t SeatTraffic) (pub, sub []string) {
 	pub = append(pub, t.Publish...)
 	sub = append(sub, t.Subscribe...)
 	sub = append(sub, t.Answers...)

internal/broker/state.go

@@ -186,16 +186,6 @@ func perMachineNames(buckets []Bucket) []string {
 	return out
 }
 
-// StateIssued is one bucket an assignment may reach, by the name its module uses for it: its own
-// state by the local name, another's as `<module>.<name>` (novox/hq ADR 0201). Key, when set, is the
-// one key it may reach (novox/hq ADR 0260): this machine's.
-type StateIssued struct {
-	Name   string `json:"name"`
-	Bucket string `json:"bucket"`
-	Writes bool   `json:"writes,omitempty"`
-	Key    string `json:"key,omitempty"`
-}
-
 // stateIssuedFor is every bucket a module's code may reach on a machine, as its membership lists them.
 func stateIssuedFor(d Declared, node string) []StateIssued {
 	var out []StateIssued

internal/broker/streams.go

@@ -80,9 +80,6 @@ const RestrictedMetadata = "mesh-restricted"
 // it under: never set by a mesh-internal work-queue stream (a seat's, a check's), only by Stream.WorkQueue.
 const WorkQueueMetadata = "mesh-work-queue"
 
-// AssignmentsStream holds every assignment's membership, the newest per subject.
-const AssignmentsStream = "ASSIGNMENTS"
-
 // What a durable consumer gave up on is kept (novox/hq issue 330, design 25 §3).
 //
 // **The server says it and keeps it; the controller copies it.** A consumer that handed a message over

internal/broker/testdata/composed.conf

@@ -29,7 +29,7 @@ accounts {
     ]
     users = [
       { user: "controller", password: "$2a$11$cccccccccccccccccccccc", permissions: {
-        publish: { allow: ["$JS.ACK.CONTROL.controller.>", "$JS.ACK.DEAD_LETTER_NOTICES.controller.>", "$JS.ACK.EVENTS.controller-merges.>", "$JS.ACK.EVENTS.controller.>", "$JS.API.>", "$KV.SEAT_MESH_BUILD_MACHINE_cancelled.>", "$KV.SEAT_NODE_BUILD_AGENT_cancelled.>", "$KV.mesh-controller_asked.>", "$KV.mesh-controller_assignments.>", "$KV.mesh-controller_builds.>", "$KV.mesh-controller_calls.>", "$KV.mesh-controller_checks-running.>", "$KV.mesh-controller_condition-history.>", "$KV.mesh-controller_conditions.>", "$KV.mesh-controller_declared-config.>", "$KV.mesh-controller_delivery-merges.>", "$KV.mesh-controller_hand-acts.>", "$KV.mesh-controller_lease.>", "$KV.mesh-controller_merge-window.>", "$KV.mesh-controller_predefined.>", "$KV.mesh-controller_rollout-silent.>", "$KV.mesh-controller_rollouts.>", "$SRV.INFO", "_INBOX.enrol.>", "mesh.again.>", "mesh.assignment.>", "mesh.events.dead.>", "mesh.mod.*.tool.>", "mesh.node.>", "mesh.seat.mesh-build-machine.accept.>", "mesh.seat.mesh-build-machine.tool.>", "mesh.seat.mesh-controller.event.applied", "mesh.seat.mesh-controller.event.assignment-changed", "mesh.seat.mesh-controller.event.built-before", "mesh.seat.mesh-controller.event.checked", "mesh.seat.mesh-controller.event.condition-changed", "mesh.seat.mesh-controller.event.condition-cleared", "mesh.seat.mesh-controller.event.condition-raised", "mesh.seat.mesh-controller.event.declared-config-changed", "mesh.seat.mesh-controller.event.doctor-heartbeat", "mesh.seat.mesh-controller.event.healer-acted", "mesh.seat.mesh-controller.event.plan-moved", "mesh.seat.mesh-controller.event.predefined-changed", "mesh.seat.mesh-controller.event.refused", "mesh.seat.mesh-controller.event.rolled-back", "mesh.seat.mesh-controller.event.secret-replaced", "mesh.seat.mesh-controller.event.sent", "mesh.seat.mesh-controller.tool.plans", "mesh.seat.mesh-controller.tool.push", "mesh.seat.mesh-controller.tool.upgrade", "mesh.seat.mesh-delivery.tool.close", "mesh.seat.mesh-delivery.tool.groups", "mesh.seat.mesh-delivery.tool.release", "mesh.seat.mesh-delivery.tool.stalled", "mesh.seat.mesh-delivery.tool.stop", "mesh.seat.mesh-delivery.tool.times", "mesh.seat.node-backup.tool.backed-up.*", "mesh.seat.node-backup.tool.now.*", "mesh.seat.node-build-agent.accept.>", "mesh.seat.node-build-agent.check.>", "mesh.seat.node-build-agent.tool.>", "mesh.seat.node-intrusion-prevention.tool.banned.*", "mesh.seat.node-launcher.tool.secret.*", "mesh.seat.node-service-manager.tool.restart.*", "mesh.seat.operator-channel.tool.tell"] }
+        publish: { allow: ["$JS.ACK.CONTROL.controller.>", "$JS.ACK.DEAD_LETTER_NOTICES.controller.>", "$JS.ACK.EVENTS.controller-merges.>", "$JS.ACK.EVENTS.controller.>", "$JS.API.>", "$KV.SEAT_MESH_BUILD_MACHINE_cancelled.>", "$KV.SEAT_NODE_BUILD_AGENT_cancelled.>", "$KV.mesh-controller_asked.>", "$KV.mesh-controller_assignments.>", "$KV.mesh-controller_builds.>", "$KV.mesh-controller_calls.>", "$KV.mesh-controller_checks-running.>", "$KV.mesh-controller_condition-history.>", "$KV.mesh-controller_conditions.>", "$KV.mesh-controller_declared-config.>", "$KV.mesh-controller_delivery-merges.>", "$KV.mesh-controller_hand-acts.>", "$KV.mesh-controller_lease.>", "$KV.mesh-controller_merge-window.>", "$KV.mesh-controller_plans-building.>", "$KV.mesh-controller_predefined.>", "$KV.mesh-controller_rollout-silent.>", "$KV.mesh-controller_rollouts.>", "$SRV.INFO", "_INBOX.enrol.>", "mesh.again.>", "mesh.assignment.>", "mesh.events.dead.>", "mesh.mod.*.tool.>", "mesh.node.>", "mesh.seat.mesh-build-machine.accept.>", "mesh.seat.mesh-build-machine.tool.>", "mesh.seat.mesh-controller.event.applied", "mesh.seat.mesh-controller.event.assignment-changed", "mesh.seat.mesh-controller.event.built-before", "mesh.seat.mesh-controller.event.checked", "mesh.seat.mesh-controller.event.condition-changed", "mesh.seat.mesh-controller.event.condition-cleared", "mesh.seat.mesh-controller.event.condition-raised", "mesh.seat.mesh-controller.event.declared-config-changed", "mesh.seat.mesh-controller.event.doctor-heartbeat", "mesh.seat.mesh-controller.event.healer-acted", "mesh.seat.mesh-controller.event.plan-moved", "mesh.seat.mesh-controller.event.predefined-changed", "mesh.seat.mesh-controller.event.refused", "mesh.seat.mesh-controller.event.rolled-back", "mesh.seat.mesh-controller.event.secret-replaced", "mesh.seat.mesh-controller.event.sent", "mesh.seat.mesh-controller.tool.plans", "mesh.seat.mesh-controller.tool.push", "mesh.seat.mesh-controller.tool.upgrade", "mesh.seat.mesh-delivery.tool.close", "mesh.seat.mesh-delivery.tool.groups", "mesh.seat.mesh-delivery.tool.release", "mesh.seat.mesh-delivery.tool.stalled", "mesh.seat.mesh-delivery.tool.stop", "mesh.seat.mesh-delivery.tool.times", "mesh.seat.node-backup.tool.backed-up.*", "mesh.seat.node-backup.tool.now.*", "mesh.seat.node-build-agent.accept.>", "mesh.seat.node-build-agent.check.>", "mesh.seat.node-build-agent.tool.>", "mesh.seat.node-intrusion-prevention.tool.banned.*", "mesh.seat.node-launcher.tool.secret.*", "mesh.seat.node-service-manager.tool.restart.*", "mesh.seat.operator-channel.tool.tell"] }
         subscribe: { allow: ["$JS.API.>", "$JS.EVENT.ADVISORY.CONSUMER.DELETED.>", "$JS.EVENT.ADVISORY.CONSUMER.MAX_DELIVERIES.>", "$SRV.INFO", "$SRV.INFO.mesh-controller", "$SRV.INFO.mesh-controller.>", "$SRV.PING", "$SRV.PING.mesh-controller", "$SRV.PING.mesh-controller.>", "$SRV.STATS", "$SRV.STATS.mesh-controller", "$SRV.STATS.mesh-controller.>", "_DELIVER.controller", "_DELIVER.controller.>", "_INBOX.controller.>", "mesh.control.>", "mesh.mod.*.event.provisioner.failing", "mesh.mod.*.event.provisioner.recovered", "mesh.mod.*.event.provisioner.retirement", "mesh.mod.gitea.event.pull.merged", "mesh.mod.gitea.event.pull.updated", "mesh.mod.mesh-catalog.event.catching-up", "mesh.mod.mesh-catalog.event.upgraded", "mesh.seat.mesh-build-machine.event.built", "mesh.seat.mesh-controller.tool.>", "mesh.seat.node-build-agent.event.built", "mesh.seat.operator-channel.event.decided.mesh-controller"] }
         allow_responses: { max: 1, ttl: "1m" }
       } }

internal/broker/waits.go

@@ -31,12 +31,6 @@ type Wait struct {
 	Last string
 }
 
-// WaitIssued is one family as a membership issues it: the name a session asks for, and its subject.
-type WaitIssued struct {
-	Event   string `json:"event"`
-	Subject string `json:"subject"`
-}
-
 // WaitSubject is where a family's events land. Each token is checked before it becomes a subject: a
 // wildcard, a dot inside a name or an empty token would widen the grant.
 func WaitSubject(w Wait) (string, error) {

internal/broker/writers.go

@@ -177,6 +177,10 @@ var WritersTable = []WriterRow{
 		KeptIn: "key-value " + CheckRunningBucket + ", aged out when not renewed", Others: "the build seat's holders read it to drop a duplicate request",
 		Subjects: kvOf(CheckRunningBucket), Writes: holdsTheBuildSeat,
 		Shared: "every machine holding the build seat puts the key of the check it runs and deletes it when the check ends"},
+	{State: "the plans-building mirror", Writer: "controller (lease holder), at the first build's ask and at each refresh",
+		KeptIn:   "key-value " + PlansBuildingBucket + ", aged out when not refreshed",
+		Others:   "the build seat's holders read it and take no new check while a key is there (ADR 0483)",
+		Subjects: kvOf(PlansBuildingBucket), Writes: isController},
 	{State: "a merge announced", Writer: "one announcer per forge (the hook, or the poll when the hook is absent — never both)",
 		KeptIn: "the bus", Others: "—", Subjects: []string{"mesh.mod.*.event.pull.merged"}, Writes: ownModule},
 	// A pull request's head, before it merges (novox/hq to-be 45 §9): the same one announcer.

internal/broker/writers_test.go

@@ -29,6 +29,8 @@ var designRows = []string{
 	"builds and their outcomes",
 	"a pull request's check asked",
 	"a pull request's check running",
+	// The plans in their build phase, a bucket the build seat's holders read (ADR 0483 clause 2, issue 1687).
+	"the plans-building mirror",
 	"a merge announced",
 	"a pull request's head announced",
 	"a pull request's merge check",

internal/builder/build_source_test.go

@@ -86,11 +86,14 @@ func TestAnImageCompilingGoIsHandedItsBuildSourceAndSaysIt(t *testing.T) {
 	}
 	for file, want := range map[string]bool{"proxy/main.go": true, "internal/shared/s.go": true, "go.mod": true,
 		"cmd/ctl/main.go": false, "internal/only/o.go": false, "README.md": false} {
-		_, err := os.Stat(filepath.Join(workspace, "narrow-server", filepath.FromSlash(file)))
-		if (err == nil) != want {
-			t.Errorf("%s handed to the recipe: %v, wanted %v", file, err == nil, want)
+		held := slices.Contains(r.builtFrom, file)
+		if held != want {
+			t.Errorf("%s handed to the recipe: %v, wanted %v", file, held, want)
 		}
 	}
+	if _, err := os.Stat(filepath.Join(workspace, "narrow-server")); err == nil {
+		t.Error("the narrowed build source was left in the workspace")
+	}
 
 	// Said per repository: its own, the manifest and the recipe; the context's, the closure.
 	if len(got.Sources) != 2 {

internal/builder/builder.go

@@ -219,6 +219,11 @@ func build(ctx context.Context, run Runner, publish Publisher,
 	if err := os.MkdirAll(workspace, 0o755); err != nil {
 		return Result{}, err
 	}
+	// **A node with no room takes no build** (novox/hq issue 1834).
+	if err := RoomToWork("/", workspace); err != nil {
+		say("clone", "refused: %v", err)
+		return Result{}, err
+	}
 	// The credential is a file git reads, never an argument: a URL carrying a password in argv
 	// would be readable by anything that can list processes for as long as a clone runs.
 	credentials, forget, err := storeCredential(workspace, forge)
@@ -738,11 +743,41 @@ func logging(log Log) func(step, format string, args ...any) {
 	}
 }
 
+// keepsImageLocally says the publisher leaves the image in the machine's runtime as the artifact itself.
+func keepsImageLocally(publish Publisher) bool {
+	switch publish.(type) {
+	case Local, *Local:
+		return true
+	}
+	return false
+}
+
+// PushedNames is implemented by a publisher that tags the image under other names to push it: the names it leaves in the
+// machine's runtime for a repository, which go with the build's own tag (novox/hq issue 1834).
+type PushedNames interface {
+	PushedNames(repository string) []string
+}
+
+// releaseImage removes the names an image was given on the node, in one command: its layers go only with the last. It runs
+// with a context of its own, the build's may be cancelled. A name never made (the build failed before it) is no fault;
+// one that cannot be removed is said, and removal is said only when the image is gone.
+func releaseImage(ctx context.Context, run Runner, names []string, say func(step, format string, args ...any)) {
+	removing, done := context.WithTimeout(context.WithoutCancel(ctx), time.Minute)
+	defer done()
+	if _, err := run(removing, "", "docker", append([]string{"rmi"}, names...)...); err != nil {
+		if !strings.Contains(err.Error(), "No such image") {
+			say("image", "the local image %s could not be removed, and goes with the week's sweep: %v", strings.Join(names, ", "), err)
+		}
+		return
+	}
+	say("image", "the local image %s is removed: the registry holds it", strings.Join(names, ", "))
+}
+
 // contextFrom clones an image artifact's own build context, when it names one apart from this
 // module's own repository — a fresh tree, the same way the module's own is, keyed by artifact
 // name so two artifacts of one module naming different contexts do not collide.
 func contextFrom(ctx context.Context, run Runner, workspace, artifact, credentials string,
-	from catalogue.ArtifactContext, seats map[string]string, say func(step, format string, args ...any)) (string, error) {
+	from catalogue.ArtifactContext, seats map[string]string, say func(step, format string, args ...any)) (_ string, err error) {
 	url, err := contextURL(from, seats)
 	if err != nil {
 		return "", err
@@ -752,6 +787,12 @@ func contextFrom(ctx context.Context, run Runner, workspace, artifact, credentia
 	if err := os.RemoveAll(dir); err != nil {
 		return "", err
 	}
+	// A clone that failed half-way is no context to leave behind (novox/hq issue 1834).
+	defer func() {
+		if err != nil {
+			os.RemoveAll(dir)
+		}
+	}()
 	if _, err := run(ctx, workspace, "git", cloneWith(credentials, "clone", "--quiet", url, dir)...); err != nil {
 		return "", fmt.Errorf("cannot clone %s: %w", url, err)
 	}
@@ -1143,6 +1184,8 @@ func one(ctx context.Context, run Runner, publish Publisher,
 				src.contexts[a.Name] = t
 			}
 			buildDir = cloned
+			// Let go of when the image is built, whatever became of it (novox/hq issue 1834).
+			defer os.RemoveAll(cloned)
 			if t, _ := trunkOf(ctx, run, cloned, "HEAD"); t == "" || !atTrunkHead(ctx, run, cloned, "HEAD", t) {
 				src.contextOffHead()
 			}
@@ -1180,6 +1223,7 @@ func one(ctx context.Context, run Runner, publish Publisher,
 				src.ownHas(paths...)
 			}
 			buildDir = narrowed
+			defer os.RemoveAll(narrowed)
 		} else if a.Context != nil {
 			src.readWhole(*a.Context)
 		}
@@ -1205,6 +1249,16 @@ func one(ctx context.Context, run Runner, publish Publisher,
 		}
 		invocation = append(invocation, ".")
 		say("image", "docker build -f %s", recipePath)
+		// **The local tag goes with the build** (novox/hq issue 1834): an image published to a registry is held there, and
+		// a tag per module and commit left on the node was the 96 GB of a full disk. Only a node publishing nowhere (a
+		// mesh being raised) keeps it, since the local image is then the artifact.
+		if !keepsImageLocally(publish) {
+			names := []string{local}
+			if p, ok := publish.(PushedNames); ok {
+				names = append(names, p.PushedNames(module+"/"+a.Name)...)
+			}
+			defer releaseImage(ctx, run, names, say)
+		}
 		if _, err := run(ctx, buildDir, "docker", invocation...); err != nil {
 			return catalogue.Built{}, fmt.Errorf("%s: building %s failed: %w", module, a.Name, err)
 		}

internal/builder/builder_test.go

@@ -38,6 +38,9 @@ type recorded struct {
 	stamped time.Time
 	// tree is what git names as the tree of the module's directory; empty answers as for a commit.
 	tree string
+	// builtFrom is the files (slash-separated, relative) of the folder the last `docker build` ran in, read as it ran:
+	// the build removes that folder when it ends (novox/hq issue 1834).
+	builtFrom []string
 }
 
 func (r *recorded) run(_ context.Context, dir, name string, args ...string) (string, error) {
@@ -53,6 +56,16 @@ func (r *recorded) run(_ context.Context, dir, name string, args ...string) (str
 			break
 		}
 	}
+	if name == "docker" && len(args) > 0 && args[0] == "build" {
+		r.builtFrom = nil
+		_ = filepath.WalkDir(dir, func(p string, d os.DirEntry, err error) error {
+			if err == nil && !d.IsDir() {
+				rel, _ := filepath.Rel(dir, p)
+				r.builtFrom = append(r.builtFrom, filepath.ToSlash(rel))
+			}
+			return nil
+		})
+	}
 	switch {
 	case name == "git" && isClone:
 		repository := args[len(args)-2]

internal/builder/check.go

@@ -123,8 +123,41 @@ type CheckSpec struct {
 	// controller could not learn them, and the verdict says so.
 	Siblings        []Sibling
 	SiblingsUnknown string
+	// Held are the approved held values of the check's pull requests (novox/hq ADR 0502 clause 4): written to a file and
+	// handed to the gate, which lays them over the change's composition only. None: no flag, no file.
+	Held []HeldValue
 }
 
+// HeldValue is one approved config value held for a key an open pull request introduces: the value of Key for Module on
+// Node (a machine's real name; the gate finds it in the snapshot by its pseudonym). The gate reads this document.
+type HeldValue struct {
+	Pull     string          `json:"pull"`
+	Head     string          `json:"head,omitempty"`
+	Node     string          `json:"node"`
+	Module   string          `json:"module"`
+	Key      string          `json:"key"`
+	Value    json.RawMessage `json:"value"`
+	Approved string          `json:"approved,omitempty"`
+	By       string          `json:"by,omitempty"`
+	At       string          `json:"at,omitempty"`
+}
+
+// writeHeld writes the held values to held.json under root and answers its path; empty, and nothing written, for none.
+func writeHeld(root string, held []HeldValue) (string, error) {
+	if len(held) == 0 {
+		return "", nil
+	}
+	raw, err := json.Marshal(held)
+	if err != nil {
+		return "", err
+	}
+	file := filepath.Join(root, "held.json")
+	return file, os.WriteFile(file, raw, 0o644)
+}
+
+// heldFlag is how the gate is given the held values: only when there are some, so a judge from before --held still runs.
+const heldFlag = `${MESH_CHECK_HELD:+--held "$MESH_CHECK_HELD"}`
+
 // Sibling is one other open pull request of a delivery group (novox/hq ADR 0382): the repository it is in as
 // owner/repo, its number, its whole head, the branch it merges into, and Dir, the directory the check finds that
 // repository under beside it (an entry of Beside).
@@ -272,6 +305,8 @@ const (
 	// EnvGroup is a delivery group's other heads, as JSON, for the gate (novox/hq ADR 0239); empty for a
 	// pull request checked alone.
 	EnvGroup = "MESH_CHECK_GROUP"
+	// EnvHeld is the file of the approved held values of the check's pull requests (novox/hq ADR 0502); empty for none.
+	EnvHeld = "MESH_CHECK_HELD"
 	// EnvTests is a `go test -run` pattern and EnvStoreOnly is 1 when a branch tried before its pull request
 	// asks for only those tests, or only the store tests (novox/hq issue 686). Never set for a pull request's
 	// check. A script that reads neither runs whole.
@@ -357,6 +392,12 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 	ctx, stop := context.WithTimeout(ctx, CheckTimeout)
 	defer stop()
 
+	// **A node with no room takes no check** (novox/hq issue 1834): said as the check's verdict, never a throwaway store
+	// that dies at once on a full disk.
+	if err := RoomToWork("/", workspace); err != nil {
+		say("check", "refused: %v", err)
+		return CheckVerdict{}, err
+	}
 	root := filepath.Join(workspace, "check")
 	if err := os.RemoveAll(root); err != nil {
 		return CheckVerdict{}, err
@@ -572,6 +613,15 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 		}
 	}
 
+	// The approved held values of the check's pull requests, for the gate (novox/hq ADR 0502 clause 4).
+	heldFile, err := writeHeld(root, spec.Held)
+	if err != nil {
+		return CheckVerdict{}, err
+	}
+	if heldFile != "" {
+		say("check", "with %d config value(s) held for its pull request(s)", len(spec.Held))
+	}
+
 	// Every clone is made: the credential is gone before anything of the check runs (novox/hq issue 462).
 	forget()
 
@@ -733,7 +783,7 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 		EnvTestStore + "=" + storeURL, EnvTestBus + "=nats://" + bus, EnvRepository + "=" + spec.Owner + "/" + spec.Repo,
 		EnvBeside + "=" + root,
 		EnvModules + "=" + strings.Join(append(append([]string{}, spec.Modules...), spec.New...), ","),
-		EnvGroup + "=" + groupFile,
+		EnvGroup + "=" + groupFile, EnvHeld + "=" + heldFile,
 		"GOCACHE=" + filepath.Join(workspace, "go-cache"), "GOMODCACHE=" + filepath.Join(workspace, "go-modules")}
 	env = append(env, changedEnv...)
 	env = append(env, selection(spec)...)
@@ -1100,7 +1150,7 @@ func gateLayer(ctx context.Context, spec CheckSpec, tree, root, gate, verdictFil
 	if err := running(inToolchain(tree, append(env, EnvVerdict+"="+verdictFile), "sh", "-c",
 		`"$MESH_GATE" merge-gate --facts "$MESH_FACTS" --store "$MESH_GATE_POSTGRES" `+
 			`--repository "$MESH_CHECK_REPOSITORY" --tree . `+gateChangedFlag(env)+` `+
-			`${MESH_CHECK_GROUP:+--group "$MESH_CHECK_GROUP"} --json > "$MESH_CHECK_VERDICT"`)); err != nil {
+			`${MESH_CHECK_GROUP:+--group "$MESH_CHECK_GROUP"} `+heldFlag+` --json > "$MESH_CHECK_VERDICT"`)); err != nil {
 		if ctx.Err() != nil {
 			return "error", "the check was ended during the merge gate"
 		}
@@ -1587,7 +1637,9 @@ func BusImage(version string) string {
 
 // throwaway starts a container publishing one port on loopback, and answers where it is reached.
 func throwaway(ctx context.Context, run, plain Runner, name, image string, port int, opts, args []string) (string, error) {
-	invocation := []string{"run", "-d", "--rm", "--name", name, "-p", fmt.Sprintf("127.0.0.1::%d", port)}
+	// Never with --rm (novox/hq issue 1834): a store that dies at once took its log with it. The check removes what it
+	// raised, with its volumes, after it has read why one stopped (RemoveContainersOf).
+	invocation := []string{"run", "-d", "--name", name, "-p", fmt.Sprintf("127.0.0.1::%d", port)}
 	invocation = append(invocation, opts...)
 	invocation = append(invocation, image)
 	invocation = append(invocation, args...)
@@ -1608,17 +1660,45 @@ func throwaway(ctx context.Context, run, plain Runner, name, image string, port
 
 // waitFor runs a readiness command in a container until it answers, for a minute.
 func waitFor(ctx context.Context, run Runner, name string, ready []string) error {
-	for i := 0; i < 60; i++ {
+	return waitReady(ctx, run, name, ready, 60)
+}
+
+// waitReady is waitFor for a number of tries, a second apart. A container that never answers is not left a mystery
+// (novox/hq issue 1834): its state and exit code and the last 20 lines of its log are in the error, read before the
+// check removes it.
+func waitReady(ctx context.Context, run Runner, name string, ready []string, attempts int) error {
+	for i := 0; i < attempts; i++ {
 		if _, err := run(ctx, "", "docker", append([]string{"exec", name}, ready...)...); err == nil {
 			return nil
 		}
+		if i == attempts-1 {
+			break
+		}
 		select {
 		case <-ctx.Done():
 			return ctx.Err()
 		case <-time.After(time.Second):
 		}
 	}
-	return fmt.Errorf("%s never became ready", name)
+	return fmt.Errorf("%s never became ready%s", name, whyItStopped(ctx, run, name))
+}
+
+// whyItStopped is ": <state>, exit code N; its last log lines: …" for a container, or "" when docker says nothing.
+func whyItStopped(ctx context.Context, run Runner, name string) string {
+	reading, done := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
+	defer done()
+	var said []string
+	if out, err := run(reading, "", "docker", "inspect", "--format",
+		"{{.State.Status}}, exit code {{.State.ExitCode}}", name); err == nil && strings.TrimSpace(out) != "" {
+		said = append(said, strings.TrimSpace(out))
+	}
+	if out, err := run(reading, "", "docker", "logs", "--tail", "20", name); err == nil && strings.TrimSpace(out) != "" {
+		said = append(said, "its last log lines: "+strings.TrimSpace(out))
+	}
+	if len(said) == 0 {
+		return ""
+	}
+	return ": " + strings.Join(said, "; ")
 }
 
 // dialable waits for an address to take a connection, for a minute.

internal/builder/check_held_test.go

@@ -0,0 +1,33 @@
+package builder
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// 1826/AC2: the held values are written whole to held.json, and the gate is given the flag only when there are some.
+func TestHeldValuesAreWrittenForTheGateAndNoneWriteNothing(t *testing.T) {
+	root := t.TempDir()
+	if file, err := writeHeld(root, nil); err != nil || file != "" {
+		t.Fatalf("none wrote %q %v", file, err)
+	}
+	if _, err := os.Stat(filepath.Join(root, "held.json")); err == nil {
+		t.Fatal("none wrote a file")
+	}
+	file, err := writeHeld(root, []HeldValue{{Pull: "novox/mesh-catalog#434", Node: "ace", Module: "n8n", Key: "media-gid",
+		Value: []byte("2000"), Approved: "the operator"}})
+	if err != nil || file != filepath.Join(root, "held.json") {
+		t.Fatalf("wrote %q %v", file, err)
+	}
+	raw, _ := os.ReadFile(file)
+	for _, want := range []string{`"node":"ace"`, `"module":"n8n"`, `"key":"media-gid"`, `"value":2000`} {
+		if !strings.Contains(string(raw), want) {
+			t.Fatalf("%s lacks %s", raw, want)
+		}
+	}
+	if !strings.Contains(heldFlag, `--held "$MESH_CHECK_HELD"`) || !strings.HasPrefix(heldFlag, "${MESH_CHECK_HELD:+") {
+		t.Fatalf("the flag is %s", heldFlag)
+	}
+}

internal/builder/disk_1834_test.go

@@ -0,0 +1,216 @@
+package builder
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// Issue 1834: a build node's root disk filled and every check there ended "the store never became ready". A node
+// frees what each build and check leaves, refuses to take work under a floor of free space, and a store that does
+// not come up says why.
+
+func init() {
+	// The disk the tests run on is none of their business; the tests of the floor say their own.
+	FreeBytes = func(string) (uint64, error) { return 500 << 30, nil }
+}
+
+func withFree(t *testing.T, bytes uint64) {
+	t.Helper()
+	was := FreeBytes
+	FreeBytes = func(string) (uint64, error) { return bytes, nil }
+	t.Cleanup(func() { FreeBytes = was })
+}
+
+// 1834/AC2: given 3 GiB free, when a check or a build is asked, then it refuses at once, saying so, running nothing.
+func TestACheckUnderTheFloorOfFreeSpaceRefusesSayingSo(t *testing.T) {
+	withFree(t, 3<<30)
+	var ran []string
+	run := func(_ context.Context, _ string, name string, args ...string) (string, error) {
+		ran = append(ran, name+" "+strings.Join(args, " "))
+		return "", nil
+	}
+	_, err := Check(context.Background(), run, CheckSpec{ID: "build-1"}, t.TempDir(), "registry.invalid", GitCredential{}, nil)
+	if err == nil || !strings.Contains(err.Error(), "the build node has 3 GiB free on /, under the floor of 20 GiB") {
+		t.Fatalf("a check on a full disk said %v", err)
+	}
+	if len(ran) != 0 {
+		t.Errorf("a refused check ran %v", ran)
+	}
+}
+
+func TestABuildUnderTheFloorOfFreeSpaceRefusesSayingSo(t *testing.T) {
+	withFree(t, 3<<30)
+	r := &recorded{}
+	_, err := Build(context.Background(), r.run, r, "https://forge.invalid/x.git", "", "", t.TempDir(), nil, Npmrc{}, GitCredential{}, nil)
+	if err == nil || !strings.Contains(err.Error(), "under the floor of 20 GiB") {
+		t.Fatalf("a build on a full disk said %v", err)
+	}
+	if len(r.ran) != 0 {
+		t.Errorf("a refused build ran %v", r.ran)
+	}
+}
+
+// The workspace's filesystem is read too, and a workspace not made yet is read at its nearest folder.
+func TestTheWorkspacesFilesystemIsReadToo(t *testing.T) {
+	was := FreeBytes
+	t.Cleanup(func() { FreeBytes = was })
+	missing := filepath.Join(t.TempDir(), "not", "yet")
+	FreeBytes = func(p string) (uint64, error) {
+		if p == "/" {
+			return 100 << 30, nil
+		}
+		if _, err := os.Stat(p); err != nil {
+			t.Errorf("read the free space of %s, which is not there", p)
+		}
+		return 1 << 30, nil
+	}
+	err := RoomToWork("/", missing)
+	if err == nil || !strings.Contains(err.Error(), "1 GiB free on "+missing) {
+		t.Errorf("the workspace's disk, under the floor, said %v", err)
+	}
+	FreeBytes = func(string) (uint64, error) { return 0, errors.New("no") }
+	if RoomToWork("/") == nil {
+		t.Error("a disk that cannot be read was taken as having room")
+	}
+}
+
+// 1834/AC3: given a store that stops at once, when the check waits for it, then its exit code and last log lines are
+// in the error and the container is removed afterwards, not by --rm before anyone could read it.
+func TestAStoreThatDiesSaysWhyItDied(t *testing.T) {
+	var ran []string
+	run := func(_ context.Context, _ string, name string, args ...string) (string, error) {
+		line := name + " " + strings.Join(args, " ")
+		ran = append(ran, line)
+		switch {
+		case args[0] == "exec":
+			return "", errors.New("Error response from daemon: container is not running")
+		case args[0] == "inspect":
+			return "exited exit code 1\n", nil
+		case args[0] == "logs":
+			return "initdb: error: could not create directory: No space left on device\n", nil
+		}
+		return "", nil
+	}
+	err := waitReady(context.Background(), run, "build-1-store", []string{"pg_isready"}, 1)
+	for _, want := range []string{"build-1-store never became ready", "exit code 1", "No space left on device"} {
+		if err == nil || !strings.Contains(err.Error(), want) {
+			t.Errorf("the verdict %q lacks %q", err, want)
+		}
+	}
+	logs := ""
+	for _, l := range ran {
+		if strings.HasPrefix(l, "docker logs") {
+			logs = l
+		}
+	}
+	if logs != "docker logs --tail 20 build-1-store" {
+		t.Errorf("the log was read as %q", logs)
+	}
+}
+
+func TestTheThrowawayStoreIsNotStartedWithRm(t *testing.T) {
+	var started []string
+	run := func(_ context.Context, _ string, name string, args ...string) (string, error) {
+		if args[0] == "run" {
+			started = args
+		}
+		return "127.0.0.1:40000\n", nil
+	}
+	if _, err := throwaway(context.Background(), run, run, "build-1-store", "postgres:17-alpine", 5432, nil, nil); err != nil {
+		t.Fatal(err)
+	}
+	for _, a := range started {
+		if a == "--rm" {
+			t.Errorf("started with --rm, which erases why it died: %v", started)
+		}
+	}
+}
+
+// 1834/AC1: given an image built for a check or a walk and published to the registry, when the build ends, then the
+// local image tag, the narrowed source and the context clone it left are gone; an image published nowhere (a mesh
+// being raised) is kept, since it is the artifact.
+// pushedNamed is a publisher that tags the image as <registry>/<repository> to push it, as the registry one does.
+type pushedNamed struct{ *recorded }
+
+func (pushedNamed) PushedNames(repository string) []string {
+	return []string{"registry.invalid/" + repository}
+}
+
+func TestABuildRemovesWhatItLeftOnTheNode(t *testing.T) {
+	r := &recorded{
+		contents:  map[string]string{"modules/m/" + ManifestName: anImageWithAContext, "modules/m/Dockerfile": "FROM scratch\n"},
+		secondary: map[string]map[string]string{"https://forge.invalid/ctl.git": {"go.mod": "module x\n"}},
+	}
+	workspace := t.TempDir()
+	if _, err := Build(context.Background(), r.run, pushedNamed{r}, "https://forge.invalid/c.git", "modules/m", "", workspace, nil, Npmrc{},
+		GitCredential{}, nil); err != nil {
+		t.Fatal(err)
+	}
+	// Both names go in one rmi: the layers stay while either is left (the push tagged the image with the registry's).
+	if !strings.Contains(strings.Join(r.ran, "\n"), "docker rmi m-server:c0ffeec0 registry.invalid/m/server") {
+		t.Errorf("the image built for it and its pushed name were not removed: %v", r.ran)
+	}
+	left, _ := filepath.Glob(filepath.Join(workspace, "*"))
+	if len(left) != 0 {
+		t.Errorf("the build left %v in its workspace", left)
+	}
+}
+
+const anImageWithAContext = `{"module":"m","version":"1",
+  "build":{"artifacts":[{"name":"server","kind":"image","from":"Dockerfile",
+    "context":{"repository":"https://forge.invalid/ctl.git","ref":"main"}}]}}`
+
+func TestAnImageKeptLocallyIsNotRemoved(t *testing.T) {
+	r := &recorded{contents: map[string]string{"modules/m/" + ManifestName: anImageWithAContext, "modules/m/Dockerfile": "FROM scratch\n"}}
+	local := Local{Run: func(ctx context.Context, dir, name string, args ...string) (string, error) {
+		if args[0] == "image" {
+			return "sha256:" + strings.Repeat("a", 64) + "\n", nil
+		}
+		return r.run(ctx, dir, name, args...)
+	}}
+	if _, err := Build(context.Background(), local.Run, local, "https://forge.invalid/c.git", "modules/m", "", t.TempDir(), nil, Npmrc{},
+		GitCredential{}, nil); err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(strings.Join(r.ran, "\n"), "docker rmi") {
+		t.Errorf("the artifact of a mesh being raised was removed: %v", r.ran)
+	}
+}
+
+// The held image the comparison pulls to read is let go of once read.
+func TestTheHeldImageAComparisonPullsIsRemovedAfterReading(t *testing.T) {
+	var ran []string
+	run := func(_ context.Context, _ string, name string, args ...string) (string, error) {
+		ran = append(ran, name+" "+strings.Join(args, " "))
+		if args[0] == "create" {
+			return "abcdef0123456789\n", nil
+		}
+		if args[0] == "image" {
+			return "", errors.New("stop here")
+		}
+		return "", nil
+	}
+	_, _ = imageContent(context.Background(), run, t.TempDir(), "reg.invalid/m/server@sha256:"+strings.Repeat("a", 64))
+	if got := ran[len(ran)-1]; !strings.HasPrefix(got, "docker rmi reg.invalid/m/server@sha256:") {
+		t.Errorf("the last command was %q, not the removal of the pulled image: %v", got, ran)
+	}
+}
+
+func TestAnImageThatCannotBeRemovedIsNotSaidRemoved(t *testing.T) {
+	var said []string
+	run := func(context.Context, string, string, ...string) (string, error) {
+		return "", errors.New("image is being used")
+	}
+	releaseImage(context.Background(), run, []string{"a:1"}, func(step, format string, args ...any) {
+		said = append(said, format)
+	})
+	for _, s := range said {
+		if strings.Contains(s, "is removed") {
+			t.Errorf("said removed: %q", s)
+		}
+	}
+}

internal/builder/floor.go

@@ -0,0 +1,46 @@
+package builder
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"syscall"
+)
+
+// FreeSpaceFloor is the free space a build node must have, on / and on its workspace's filesystem, before it takes
+// a build or a check (novox/hq issue 1834): under it, a throwaway store cannot initialise its data directory and
+// dies at once, and the check ended "never became ready" instead of saying the disk was full.
+const FreeSpaceFloor = 20 << 30
+
+// FreeBytes reads the bytes an unprivileged writer can still use on the filesystem holding path. A variable so a
+// test answers for a disk it does not have.
+var FreeBytes = func(path string) (uint64, error) {
+	var s syscall.Statfs_t
+	if err := syscall.Statfs(path, &s); err != nil {
+		return 0, err
+	}
+	return s.Bavail * uint64(s.Bsize), nil
+}
+
+// RoomToWork refuses, saying how much is free, when any of the paths' filesystems is under FreeSpaceFloor. A path
+// that does not exist yet (a workspace not made) is read at its nearest folder that does.
+func RoomToWork(paths ...string) error {
+	for _, p := range paths {
+		at := p
+		for {
+			if _, err := os.Stat(at); err == nil || filepath.Dir(at) == at {
+				break
+			}
+			at = filepath.Dir(at)
+		}
+		free, err := FreeBytes(at)
+		if err != nil {
+			return fmt.Errorf("the free space on %s cannot be read: %w", p, err)
+		}
+		if free < FreeSpaceFloor {
+			return fmt.Errorf("the build node has %d GiB free on %s, under the floor of %d GiB",
+				free>>30, p, FreeSpaceFloor>>30)
+		}
+	}
+	return nil
+}

internal/builder/gosource_test.go

@@ -172,11 +172,11 @@ func TestANarrowedTreeHoldsTheBuildSourceAndNothingElse(t *testing.T) {
 	}
 }
 
-// This repository's own programs: the route proxy's build source is not the controller's, and neither
-// holds the other's command.
+// This repository's own programs: the route proxy lives in its module's own Go module, so its build source is
+// not the controller's, and neither holds the other's command.
 func TestThisRepositorysProgramsHaveBuildSourcesOfTheirOwn(t *testing.T) {
 	root := filepath.Join("..", "..")
-	proxy, err := GoBuildSource(root, "examples/route-proxy")
+	proxy, err := GoBuildSource(filepath.Join(root, "modules", "route-proxy"), "cmd/route-proxy")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -194,15 +194,15 @@ func TestThisRepositorysProgramsHaveBuildSourcesOfTheirOwn(t *testing.T) {
 		file    string
 		held    bool
 	}{
-		{proxy, "the route proxy", "examples/route-proxy/main.go", true},
-		{proxy, "the route proxy", "internal/broker/broker.go", true},
-		{proxy, "the route proxy", "cmd/mesh-controller/main.go", false},
-		{proxy, "the route proxy", "internal/conditions/condition.go", false},
+		{proxy, "the route proxy", "cmd/route-proxy/main.go", true},
+		{proxy, "the route proxy", "cmd/route-proxy/bus.go", true},
+		{proxy, "the route proxy", "go.mod", true},
+		{proxy, "the route proxy", "cmd/route-provider/main.go", false},
 		{proxy, "the route proxy", "README.md", false},
 		{controller, "the controller", "cmd/mesh-controller/main.go", true},
 		{controller, "the controller", "internal/conditions/condition.go", true},
 		{controller, "the controller", "internal/inventory/migrations/0001-nodes.sql", true},
-		{controller, "the controller", "examples/route-proxy/main.go", false},
+		{controller, "the controller", "modules/route-proxy/cmd/route-proxy/main.go", false},
 		{controller, "the controller", "cmd/mesh-builder/main.go", false},
 		{controller, "the controller", "README.md", false},
 		{builder, "the build seat's program", "cmd/mesh-builder/main.go", true},

internal/builder/kill.go

@@ -3,6 +3,7 @@ package builder
 import (
 	"context"
 	"os/exec"
+	"regexp"
 	"strings"
 	"syscall"
 	"time"
@@ -41,6 +42,11 @@ func inItsOwnGroup(cmd *exec.Cmd) {
 	cmd.WaitDelay = KillWait
 }
 
+// CgroupParent is the slice every container a build or check starts joins (novox/hq issue 1798), so the node's own
+// weights and cap bind it: the build-agent module declares the slice with the machine's CPU weight, IO weight and
+// memory limits, and names it in MESH_BUILD_CGROUP_PARENT. Empty, a container joins the runtime's default.
+var CgroupParent string
+
 // Labelled is a Runner that marks every container a build starts with the build's id, so a kill
 // finds what outlived the docker client (novox/hq ADR 0219). Applied at the one place every command
 // passes rather than at each `docker run` the builder composes: a run added later is labelled too.
@@ -55,8 +61,11 @@ func LabelledArgs(name string, args []string, id string) []string {
 	if name != "docker" || len(args) == 0 || args[0] != "run" || id == "" {
 		return args
 	}
-	out := make([]string, 0, len(args)+2)
+	out := make([]string, 0, len(args)+4)
 	out = append(out, "run", "--label", BuildLabel+"="+id)
+	if CgroupParent != "" {
+		out = append(out, "--cgroup-parent", CgroupParent)
+	}
 	return append(out, args[1:]...)
 }
 
@@ -71,12 +80,45 @@ func RemoveContainersOf(ctx context.Context, run Runner, id string) (int, error)
 	if len(ids) == 0 {
 		return 0, nil
 	}
-	if _, err := run(ctx, "", "docker", append([]string{"rm", "-f"}, ids...)...); err != nil {
+	if err := removeWithVolumes(ctx, run, ids); err != nil {
 		return 0, err
 	}
 	return len(ids), nil
 }
 
+// MountedVolumes is the template `docker inspect --format` reads the names of a container's volumes with.
+const MountedVolumes = `{{range .Mounts}}{{if eq .Type "volume"}}{{println .Name}}{{end}}{{end}}`
+
+// anonymousVolume is the name docker gives a volume it makes for an image's VOLUME line: 64 hex digits.
+var anonymousVolume = regexp.MustCompile(`^[0-9a-f]{64}$`)
+
+// removeWithVolumes removes containers together with their anonymous volumes (novox/hq issue 1772). A throwaway
+// store declares its data directory a VOLUME, docker makes an anonymous volume for it, and `docker rm -f`
+// without -v leaves that volume for ever: 1,629 of them, 107 GB, on one build node. So the volumes the
+// containers mount are read first, the containers are removed with -v, and an anonymous volume still there
+// afterwards is removed by name. Only a volume one of these containers mounted, and only one with an anonymous
+// volume's name, is touched: a named volume — an operator's own data — never is. A volume already gone is
+// no failure.
+func removeWithVolumes(ctx context.Context, run Runner, ids []string) error {
+	var volumes []string
+	if out, err := run(ctx, "", "docker", append([]string{"inspect", "--format", MountedVolumes}, ids...)...); err == nil {
+		seen := map[string]bool{}
+		for _, name := range strings.Fields(out) {
+			if anonymousVolume.MatchString(name) && !seen[name] {
+				seen[name] = true
+				volumes = append(volumes, name)
+			}
+		}
+	}
+	if _, err := run(ctx, "", "docker", append([]string{"rm", "-f", "-v"}, ids...)...); err != nil {
+		return err
+	}
+	if len(volumes) > 0 {
+		_, _ = run(ctx, "", "docker", append([]string{"volume", "rm"}, volumes...)...)
+	}
+	return nil
+}
+
 // A holder that stops mid-build leaves its containers running (novox/hq issue 306).
 //
 // A build's containers are removed by the build itself, by a kill, or by the next delivery of the same
@@ -106,7 +148,7 @@ func RemoveLeftBehind(ctx context.Context, run Runner) (int, error) {
 	if len(ids) == 0 {
 		return 0, nil
 	}
-	if _, err := run(ctx, "", "docker", append([]string{"rm", "-f"}, ids...)...); err != nil {
+	if err := removeWithVolumes(ctx, run, ids); err != nil {
 		return 0, err
 	}
 	return len(ids), nil

internal/builder/kill_test.go

@@ -2,6 +2,7 @@ package builder
 
 import (
 	"context"
+	"errors"
 	"reflect"
 	"strings"
 	"testing"
@@ -49,7 +50,8 @@ func TestAKillRemovesTheContainersLabelledWithTheBuild(t *testing.T) {
 	if err != nil || n != 2 {
 		t.Fatalf("%d %v", n, err)
 	}
-	if want := []string{"docker ps -aq --filter label=mesh.build=build-3", "docker rm -f c1 c2"}; !reflect.DeepEqual(ran, want) {
+	if want := []string{"docker ps -aq --filter label=mesh.build=build-3", "docker inspect --format " + MountedVolumes + " c1 c2",
+		"docker rm -f -v c1 c2"}; !reflect.DeepEqual(ran, want) {
 		t.Errorf("ran %v", ran)
 	}
 }
@@ -73,7 +75,7 @@ func TestAStartingHolderRemovesWhatEarlierHoldersLeftAndNothingElse(t *testing.T
 	if n != 3 {
 		t.Errorf("removed %d", n)
 	}
-	if len(ran) != 2 || !reflect.DeepEqual(ran[1], []string{"docker", "rm", "-f", "c1", "c2", "c7"}) {
+	if len(ran) != 3 || !reflect.DeepEqual(ran[2], []string{"docker", "rm", "-f", "-v", "c1", "c2", "c7"}) {
 		t.Fatalf("ran %v", ran)
 	}
 	if !strings.Contains(strings.Join(ran[0], " "), "--filter label=mesh.build") {
@@ -90,3 +92,75 @@ func TestAStartingHolderRemovesWhatEarlierHoldersLeftAndNothingElse(t *testing.T
 		t.Errorf("with nothing of the seat's: %d %v %v", n, err, ran)
 	}
 }
+
+// **Issue 1772**: a throwaway store declares its data directory a VOLUME, so docker makes an anonymous volume for
+// it, and `docker rm -f` without -v leaves that volume behind (1,629 of them, 107 GB, on one build node). Every
+// container a build or check removes is removed with its anonymous volumes (-v), and any volume the container
+// mounted that is still there afterwards is removed by name — those, and only those, never a named volume.
+func TestARemovedContainerTakesItsAnonymousVolumesWithIt(t *testing.T) {
+	anon := strings.Repeat("a", 64)
+	other := strings.Repeat("b", 64)
+	var ran []string
+	run := func(_ context.Context, _ string, name string, args ...string) (string, error) {
+		ran = append(ran, name+" "+strings.Join(args, " "))
+		switch args[0] {
+		case "ps":
+			return "c1\n", nil
+		case "inspect":
+			return anon + "\n" + "compose_data\n" + other + "\n", nil
+		}
+		return "", nil
+	}
+	if n, err := RemoveContainersOf(context.Background(), run, "build-4"); err != nil || n != 1 {
+		t.Fatalf("%d %v", n, err)
+	}
+	last := ran[len(ran)-1]
+	if want := "docker volume rm " + anon + " " + other; last != want {
+		t.Errorf("last command %q, want %q", last, want)
+	}
+	if !strings.Contains(strings.Join(ran, "\n"), "docker rm -f -v c1") {
+		t.Errorf("ran %v", ran)
+	}
+	if strings.Contains(last, "compose_data") {
+		t.Errorf("a named volume was removed: %q", last)
+	}
+}
+
+// A volume already gone when the sweep looks (rm -v took it) is no failure.
+func TestAVolumeAlreadyGoneIsNoFailure(t *testing.T) {
+	run := func(_ context.Context, _ string, name string, args ...string) (string, error) {
+		switch args[0] {
+		case "ps":
+			return "c1\n", nil
+		case "inspect":
+			return strings.Repeat("c", 64) + "\n", nil
+		case "volume":
+			return "", errors.New("no such volume")
+		}
+		return "", nil
+	}
+	if n, err := RemoveContainersOf(context.Background(), run, "build-5"); err != nil || n != 1 {
+		t.Fatalf("%d %v", n, err)
+	}
+}
+
+// A node's build slice limits everything a build or check starts (novox/hq issue 1798): with a parent
+// set, every `docker run` joins it, so the node's CPU and IO weights and memory cap bind the container;
+// with none set the arguments are as they always were.
+func TestEveryContainerJoinsTheNodesBuildSlice(t *testing.T) {
+	was := CgroupParent
+	defer func() { CgroupParent = was }()
+	CgroupParent = "meshbuild.slice"
+	got := LabelledArgs("docker", []string{"run", "--rm", "img", "sh"}, "build-1")
+	want := []string{"run", "--label", "mesh.build=build-1", "--cgroup-parent", "meshbuild.slice", "--rm", "img", "sh"}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("1798/AC1: docker run became %v", got)
+	}
+	if got := LabelledArgs("docker", []string{"build", "."}, "build-1"); !reflect.DeepEqual(got, []string{"build", "."}) {
+		t.Errorf("a docker build became %v", got)
+	}
+	CgroupParent = ""
+	if got := LabelledArgs("docker", []string{"run", "img"}, "build-1"); !reflect.DeepEqual(got, []string{"run", "--label", "mesh.build=build-1", "img"}) {
+		t.Errorf("1798/AC1: with no slice, docker run became %v", got)
+	}
+}

internal/builder/registry.go

@@ -43,6 +43,11 @@ type Registry struct {
 	HTTP *http.Client
 }
 
+// PushedNames are the names PublishImage leaves the image under on the node.
+func (r Registry) PushedNames(repository string) []string {
+	return []string{r.Address + "/" + repository}
+}
+
 // PublishImage pushes a locally built image and returns a reference pinned by digest.
 //
 // The digest is read back from the registry's own answer rather than computed here. What matters

internal/builder/reuse.go

@@ -253,6 +253,13 @@ func (s scratchPublisher) PublishImage(ctx context.Context, localTag, repository
 	return s.to.PublishImage(ctx, localTag, ScratchPrefix+repository)
 }
 
+func (s scratchPublisher) PushedNames(repository string) []string {
+	if p, ok := s.to.(PushedNames); ok {
+		return p.PushedNames(ScratchPrefix + repository)
+	}
+	return nil
+}
+
 func (s scratchPublisher) PublishArchive(ctx context.Context, repository string, body []byte, digest string) (string, error) {
 	return s.to.PublishArchive(ctx, ScratchPrefix+repository, body, digest)
 }

internal/builder/same_program.go

@@ -88,6 +88,9 @@ func imageContent(ctx context.Context, run Runner, dir, ref string) (string, err
 	if _, err := run(ctx, dir, "docker", "pull", "--quiet", ref); err != nil {
 		return "", fmt.Errorf("pulling %s: %w", ref, err)
 	}
+	// The image is on the node only for the reading (novox/hq issue 1834); one a container still runs is refused by
+	// docker and stays.
+	defer func() { _, _ = run(context.WithoutCancel(ctx), dir, "docker", "rmi", ref) }()
 	config, err := run(ctx, dir, "docker", "image", "inspect", "--format",
 		"{{.Os}}/{{.Architecture}}/{{.Variant}} {{json .Config}}", ref)
 	if err != nil {
@@ -105,7 +108,7 @@ func imageContent(ctx context.Context, run Runner, dir, ref string) (string, err
 	if id == "" {
 		return "", errors.New("the container engine named no container for " + ref)
 	}
-	defer func() { _, _ = run(context.WithoutCancel(ctx), dir, "docker", "rm", "--force", id) }()
+	defer func() { _, _ = run(context.WithoutCancel(ctx), dir, "docker", "rm", "--force", "--volumes", id) }()
 	if err := os.MkdirAll(dir, 0o700); err != nil {
 		return "", err
 	}

internal/inventory/builds_test.go

@@ -185,7 +185,7 @@ func TestABuildsBuildSourceComesBackOverWhatItRead(t *testing.T) {
 	said.Read = []ReadRepository{{Repository: "novox/mesh-controller", Ref: "main"}, {Repository: "novox/other"}}
 	said.Sources = []BuildSource{
 		{Paths: []string{"modules/route-proxy/Dockerfile", "modules/route-proxy/module.json"}},
-		{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"examples/route-proxy/", "go.mod"}},
+		{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"modules/route-proxy/cmd/route-proxy/", "go.mod"}},
 		{Repository: "novox/unread", Paths: []string{"x"}},
 	}
 	unsaid := aBuild("unsaid", "build-agent", "")
@@ -200,7 +200,7 @@ func TestABuildsBuildSourceComesBackOverWhatItRead(t *testing.T) {
 		t.Fatal(err)
 	}
 	want := []ReadRepository{
-		{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"examples/route-proxy/", "go.mod"}},
+		{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"modules/route-proxy/cmd/route-proxy/", "go.mod"}},
 		{Repository: "novox/other"},
 		{Paths: []string{"modules/route-proxy/Dockerfile", "modules/route-proxy/module.json"}, Own: true},
 	}
@@ -238,7 +238,7 @@ func TestAFailedNewerBuildLeavesTheBuildSourceStale(t *testing.T) {
 	worked.Asked = time.Now().Add(-time.Hour)
 	worked.Read = []ReadRepository{{Repository: "novox/mesh-controller", Ref: "main"}}
 	worked.Sources = []BuildSource{{Paths: []string{"modules/route-proxy/module.json"}},
-		{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"examples/route-proxy/"}}}
+		{Repository: "novox/mesh-controller", Ref: "main", Paths: []string{"modules/route-proxy/cmd/route-proxy/"}}}
 	failed := aBuild("failed", "route-proxy", "compile error")
 	failed.Asked = time.Now()
 	for _, b := range []Build{worked, failed} {

internal/inventory/mirrors.go

@@ -6,6 +6,8 @@ import (
 	"encoding/json"
 	"fmt"
 	"time"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
 )
 
 // The values of the controller's record mirrors, built from the store (novox/hq ADR 0289, design 54 §1,
@@ -179,3 +181,13 @@ func (i *Inventory) PredefinedMirror(ctx context.Context) (map[string][]byte, er
 	}
 	return map[string][]byte{PredefinedMirrorKey: value}, nil
 }
+
+// DeclaredOf is a manifest's config declarations as the mirror holds them (DeclaredMirrored), so a pull request's
+// declarations are told to mesh-config in the one shape it reads the trunk's in (novox/hq ADR 0502 clause 2).
+func DeclaredOf(settings map[string]catalogue.SettingDeclaration) (map[string]DeclaredMirrored, error) {
+	raw, err := json.Marshal(settings)
+	if err != nil {
+		return nil, err
+	}
+	return declaredMirrored(raw)
+}

internal/link/admit_test.go

@@ -0,0 +1,28 @@
+package link
+
+import (
+	"context"
+	"testing"
+
+	"github.com/nats-io/nats.go"
+)
+
+// 1768/AC1: a request dropped as a duplicate of one another builder runs marks nothing in hand: the claim is not made,
+// so no mark is left behind to fail every later claim.
+func TestADuplicateDropIsJudgedBeforeTheClaimSoLeavesNoMark(t *testing.T) {
+	claims := 0
+	m := &natsMachine{
+		opts:      MachineOptions{Claim: func() bool { claims++; return true }},
+		duplicate: func(context.Context, BuildRequest) string { return "ace is running it" },
+	}
+	if m.admit(context.Background(), &nats.Msg{}, BuildRequest{ID: "build-1"}) {
+		t.Fatal("a duplicate was admitted")
+	}
+	if claims != 0 {
+		t.Fatalf("a dropped duplicate was claimed %d times, which leaves the in-hand mark behind", claims)
+	}
+	m.duplicate = func(context.Context, BuildRequest) string { return "" }
+	if !m.admit(context.Background(), &nats.Msg{}, BuildRequest{ID: "build-2"}) || claims != 1 {
+		t.Fatalf("a request that is no duplicate was not claimed once: claims=%d", claims)
+	}
+}

internal/link/build.go

@@ -218,6 +218,25 @@ type CheckRequest struct {
 	Try       bool   `json:"try,omitempty"`
 	Tests     string `json:"tests,omitempty"`
 	StoreOnly bool   `json:"store-only,omitempty"`
+	// HeldConfig are the approved held values of the pull requests this check is of (novox/hq ADR 0502 clause 4): each
+	// a config value the operator approved for a key an open pull request introduces. The merge gate lays them over
+	// their module's values on their node in the composition with the change only, never in the mesh as it is. Empty
+	// from a controller from before it, or when mesh-config held none or did not answer.
+	HeldConfig []HeldConfig `json:"held_config,omitempty"`
+}
+
+// HeldConfig is one approved held value (novox/hq ADR 0502), as mesh-config's `held` action answers it.
+type HeldConfig struct {
+	Pull   string          `json:"pull"`
+	Head   string          `json:"head,omitempty"`
+	Node   string          `json:"node"`
+	Module string          `json:"module"`
+	Key    string          `json:"key"`
+	Value  json.RawMessage `json:"value"`
+	// Approved says who approved it, in words, as mesh-config states it; By and At are who held it and when.
+	Approved string `json:"approved,omitempty"`
+	By       string `json:"by,omitempty"`
+	At       string `json:"at,omitempty"`
 }
 
 // StepTried is the step a build seat says a try's outcome under, in the build's log: one line, a Tried as JSON
@@ -292,6 +311,10 @@ type GroupMember struct {
 	// Base is the branch it merges into: the build seat merges the head into that trunk's head before the
 	// group is composed (novox/hq ADR 0323 §6). A build seat from before it composes the head alone.
 	Base string `json:"base,omitempty"`
+	// Trunk is the base branch's head the forge announced with the head (novox/hq issue 1106): the trunk commit the
+	// composed verdict names for this member when the build seat named none, so a member whose trunk did not move is
+	// never merged-refused for a verdict that names no trunk.
+	Trunk string `json:"trunk,omitempty"`
 }
 
 // Who judges a merge check's gate.

internal/link/builds_nats.go

@@ -6,6 +6,7 @@ import (
 	"errors"
 	"fmt"
 	"os"
+	"sync"
 	"time"
 
 	"github.com/nats-io/nats.go"
@@ -162,11 +163,23 @@ type natsMachine struct {
 	// build waits, then the checks of pull requests marked ready, then every other check (novox/hq ADR 0406 §3).
 	subs []*takeQueue
 	opts MachineOptions
+	// duplicate stands in for runningElsewhere in tests; nil is the real one.
+	duplicate func(context.Context, BuildRequest) string
+	// gate is what the loop asks of the bus to hold checks while a delivery builds; nil is the bus's (a test sets a fake).
+	gate checkGate
+	// said is the faults of the hold already said, letKey whether this holder created the let-through key for the check it
+	// took last (ADR 0483 clause 3).
+	said   map[string]bool
+	letKey bool
+	// mu guards the subscriptions of subs, bound and let go of by the taking loop and closed by Close.
+	mu sync.Mutex
 }
 
 // takeQueue is one queue a machine pulls from.
 type takeQueue struct {
 	sub *nats.Subscription
+	// pull is what the queue is fetched through: the subscription once bound (a test sets a fake).
+	pull puller
 	// kind is what its asks are: a build, a ready check, or another check.
 	kind string
 	// worker is the consumer bound; bound is false until a bind succeeded, for a queue the mesh may not have made yet.
@@ -174,6 +187,11 @@ type takeQueue struct {
 	bound  bool
 }
 
+// puller is the fetch of a queue.
+type puller interface {
+	Fetch(batch int, opts ...nats.PullOpt) ([]*nats.Msg, error)
+}
+
 // The kinds of queue a machine takes from, in the order it takes from them.
 const (
 	queueBuilds = "builds"
@@ -195,6 +213,9 @@ type MachineOptions struct {
 	// the request in hand first and reads its drain after, so an ask of `busy` racing the fetch sees one or
 	// the other, never neither. Nil claims every one.
 	Claim func() bool
+	// LetThroughAfter is how long a check waits while a delivery builds before it is let through; zero is ADR 0483's thirty
+	// minutes. Set by a test.
+	LetThroughAfter time.Duration
 }
 
 // MachineOverNATS takes build work from the current build role.
@@ -222,6 +243,8 @@ const (
 )
 
 func (m *natsMachine) Close() {
+	m.mu.Lock()
+	defer m.mu.Unlock()
 	for _, q := range m.subs {
 		if q.sub != nil {
 			_ = q.sub.Unsubscribe()
@@ -244,6 +267,9 @@ func (m *natsMachine) Close() {
 // **In this order** (novox/hq ADR 0406 §3): a delivery build, then a check of a pull request marked ready, then any
 // other check, each queue tried without waiting; when all three are empty the first is waited on for a second at most
 // and the three are tried again, so a delivery build is never much more than a second behind and nothing spins.
+//
+// **Unless a delivery builds** (novox/hq ADR 0483): while the controller's bucket of the plans building holds a key, no check queue
+// is fetched from, but for the one check that waited LetThroughAfter, which goes first (see next).
 func (m *natsMachine) Take(ctx context.Context, do func(context.Context, Build)) error {
 	worker, found := broker.HolderConsumerFor(m.on, "build-agent",
 		broker.DeclaredSeat{Name: m.seat, Accepts: []string{"build"}})
@@ -288,6 +314,19 @@ func (m *natsMachine) Take(ctx context.Context, do func(context.Context, Build))
 			}
 			continue
 		}
+		// The seat's own queue is bound again when a running ask made the machine let go of it (quiesce): a machine that cannot
+		// is not taking, which is said and tried again.
+		if !m.subs[0].bound {
+			if err := m.bind(m.subs[0]); err != nil {
+				fmt.Fprintf(os.Stderr, "this machine cannot bind %s again after a build, and tries again: %v\n", m.seat, err)
+				select {
+				case <-ctx.Done():
+					return nil
+				case <-time.After(pausedPoll):
+				}
+				continue
+			}
+		}
 		if time.Now().After(bindAgain) {
 			for _, q := range m.subs[1:] {
 				if !q.bound {
@@ -312,7 +351,7 @@ func (m *natsMachine) Take(ctx context.Context, do func(context.Context, Build))
 			// say why (2026-10-03, the first build agents). Asked again.
 			continue
 		default:
-			if m.subs[0].sub.IsValid() {
+			if m.subs[0].sub != nil && m.subs[0].sub.IsValid() {
 				// A transient fault in asking — a reconnect, a slow server — is asked past rather
 				// than ending the machine; one that outlasts the ack wait redelivers nothing lost.
 				time.Sleep(time.Second)
@@ -320,70 +359,125 @@ func (m *natsMachine) Take(ctx context.Context, do func(context.Context, Build))
 			}
 			return fmt.Errorf("the bus stopped delivering build work: %w", err)
 		}
-		// **Paused while the pull was answered** (ADR 0219): "takes no new build" holds even for
-		// the one that arrived in that moment. Handed back at once for another holder — counted as
-		// a delivery, which a pause landing exactly then costs and nothing else does.
-		if m.opts.Paused != nil && m.opts.Paused() {
-			_ = msg.Nak()
-			continue
-		}
-		var request BuildRequest
-		if err := json.Unmarshal(msg.Data, &request); err != nil {
-			// Unreadable: terminated rather than retried, because the next attempt reads the same
-			// bytes. Nobody waiting hears an answer, which is right — there was no request.
-			_ = msg.Term()
-			continue
-		}
-		// **Cancelled in the moment it was fetched** (novox/hq ADR 0219): the controller wrote the
-		// id into the seat's cancelled set before deleting the ask, so one taken in between is
-		// ended here, terminated rather than redelivered, and its outcome said as failed — never
-		// built. A set that cannot be read is said and the ask built: a cancel is a person's
-		// exception, and a holder that refused every build while its grant was missing would
-		// stop the mesh building for it.
-		build := &natsBuild{request: request, msg: msg, on: m.on, js: m.js, seat: m.seat, delivery: deliveryOf(msg)}
-		if cancelled, err := IsCancelled(m.js.Conn(), m.seat, request.ID); err != nil {
-			fmt.Fprintf(os.Stderr, "could not read whether %s was cancelled, so it is built: %v\n", request.ID, err)
-		} else if cancelled {
-			endCancelled(ctx, build)
-			continue
-		}
-		// **A check left behind is dropped when it is taken** (novox/hq ADR 0406 §3): a request on the third queue for a
-		// head and a trunk commit its pull request's key already says were judged is acknowledged and not run.
-		if q.kind == queueOther {
-			if why := m.judgedAlready(ctx, request); why != "" {
-				fmt.Fprintf(os.Stderr, "%s was left behind in the check queue and is dropped: %s\n", request.ID, why)
-				_ = msg.Ack()
-				continue
-			}
-		}
-		// **Drained in the moment it was fetched** (novox/hq ADR 0335): handed back at once, as a pause
-		// landing then is.
-		if m.opts.Claim != nil && !m.opts.Claim() {
-			_ = msg.Nak()
-			continue
-		}
-		// **A duplicate of a check another builder is running is dropped** (issue 1649): an ask redelivered to this machine
-		// because its first holder did not say, in time, that it had it. The running key names that builder and this same
-		// ask; running it a second time would spend a second place on one check.
-		if why := m.runningElsewhere(ctx, request); why != "" {
-			fmt.Fprintf(os.Stderr, "%s is handed out again while another builder runs it and is dropped: %s\n", request.ID, why)
-			_ = msg.Ack()
-			continue
-		}
-		// A build outlives the acknowledgement window many times over; said while it runs,
-		// as the controller says it for its own long handlers, so the server neither hands
-		// the ask to a second machine nor counts the wait against its deliveries.
-		working := make(chan struct{})
-		go stillWorking(msg, working, heartbeatWhileWorking)
-		// And a check says it is running, to the other builders (ADR 0406 §3): its key put now and at each heartbeat,
-		// deleted when it ends, whatever the outcome.
-		stopRunning := keepRunning(ctx, m.js.Conn(), request, m.on, heartbeatWhileWorking)
-		do(ctx, build)
-		stopRunning()
-		close(working)
+		m.handOver(ctx, msg, q, do)
+		// And the queues it let go of are bound again at once, not after the half minute.
+		bindAgain = time.Time{}
 	}
 }
 
+// handOver settles one fetched ask: dropped, handed back or built. **A check let through keeps its key for as long as it
+// stays here** (ADR 0483 clause 3): refreshed while it runs and deleted when it ends, however it ends.
+func (m *natsMachine) handOver(ctx context.Context, msg *nats.Msg, q *takeQueue, do func(context.Context, Build)) {
+	if m.letKey {
+		defer m.keepLetThrough(ctx, heartbeatWhileWorking)()
+	}
+	// **Paused while the pull was answered** (ADR 0219): "takes no new build" holds even for
+	// the one that arrived in that moment. Handed back at once for another holder — counted as
+	// a delivery, which a pause landing exactly then costs and nothing else does.
+	if m.opts.Paused != nil && m.opts.Paused() {
+		_ = msg.Nak()
+		return
+	}
+	var request BuildRequest
+	if err := json.Unmarshal(msg.Data, &request); err != nil {
+		// Unreadable: terminated rather than retried, because the next attempt reads the same
+		// bytes. Nobody waiting hears an answer, which is right — there was no request.
+		_ = msg.Term()
+		return
+	}
+	// **Cancelled in the moment it was fetched** (novox/hq ADR 0219): the controller wrote the
+	// id into the seat's cancelled set before deleting the ask, so one taken in between is
+	// ended here, terminated rather than redelivered, and its outcome said as failed — never
+	// built. A set that cannot be read is said and the ask built: a cancel is a person's
+	// exception, and a holder that refused every build while its grant was missing would
+	// stop the mesh building for it.
+	build := &natsBuild{request: request, msg: msg, on: m.on, js: m.js, seat: m.seat, delivery: deliveryOf(msg)}
+	if cancelled, err := IsCancelled(m.js.Conn(), m.seat, request.ID); err != nil {
+		fmt.Fprintf(os.Stderr, "could not read whether %s was cancelled, so it is built: %v\n", request.ID, err)
+	} else if cancelled {
+		endCancelled(ctx, build)
+		return
+	}
+	// **A check left behind is dropped when it is taken** (novox/hq ADR 0406 §3): a request on the third queue for a
+	// head and a trunk commit its pull request's key already says were judged is acknowledged and not run.
+	if q.kind == queueOther {
+		if why := m.judgedAlready(ctx, request); why != "" {
+			fmt.Fprintf(os.Stderr, "%s was left behind in the check queue and is dropped: %s\n", request.ID, why)
+			_ = msg.Ack()
+			return
+		}
+	}
+	if !m.admit(ctx, msg, request) {
+		return
+	}
+	// A build outlives the acknowledgement window many times over; said while it runs,
+	// as the controller says it for its own long handlers, so the server neither hands
+	// the ask to a second machine nor counts the wait against its deliveries.
+	working := make(chan struct{})
+	go stillWorking(msg, working, heartbeatWhileWorking)
+	// And a check says it is running, to the other builders (ADR 0406 §3): its key put now and at each heartbeat,
+	// deleted when it ends, whatever the outcome.
+	stopRunning := keepRunning(ctx, m.js.Conn(), request, m.on, heartbeatWhileWorking)
+	// **And holds nothing else while it runs** (issue 1747): see quiesce.
+	m.quiesce(q)
+	do(ctx, build)
+	stopRunning()
+	close(working)
+	// **The queue it came from too, once the ask is settled**: a fetch that returned a late message leaves its pull request
+	// open, and the server can deliver one more into the subscription (issue 1747). Take binds every queue again first.
+	m.quiesce(nil)
+}
+
+// quiesce lets go of every queue but the one the running ask came from, for as long as it runs. **A builder never holds a
+// message it does not start** (issue 1747). A message the server sends after a fetch gave up, within the few milliseconds its
+// pull request still lived, lands in that queue's subscription and stays there until the next fetch of it: held, never
+// acknowledged as in progress, for as long as the builder runs its current ask, five or ten minutes for a check, while the
+// holders that could build it are all busy and a delivery waits behind it. The legacy pull subscription cannot be read
+// without sending a new pull request, which could take one more, so it cannot be searched for such a message. It is dropped
+// instead: the subscription is closed, a message in it or on its way is lost to this builder and the server hands it out again
+// when its worker's wait for an acknowledgement ends (a minute), to any holder that is free, and the queue is bound again
+// before the next fetch (Take). The queue the running ask came from keeps its subscription, which its acknowledgements use.
+func (m *natsMachine) quiesce(keep *takeQueue) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	for _, q := range m.subs {
+		if q == keep || !q.bound {
+			continue
+		}
+		if q.sub != nil {
+			_ = q.sub.Unsubscribe()
+		}
+		q.sub, q.pull, q.bound = nil, nil, false
+	}
+}
+
+// admit decides whether a fetched request is run here, and answers the message when it is not.
+//
+// **The duplicate is judged before the request is claimed** (issue 1768): a claim marks the build in hand, and a request
+// dropped after it left the mark behind, so every later claim failed and every ask was handed back at once until all
+// had spent their deliveries. A request dropped here has marked nothing.
+//
+// **Drained in the moment it was fetched** (novox/hq ADR 0335): handed back at once, as a pause landing then is.
+func (m *natsMachine) admit(ctx context.Context, msg *nats.Msg, request BuildRequest) bool {
+	// **A duplicate of a check another builder is running is dropped** (issue 1649): an ask redelivered to this machine
+	// because its first holder did not say, in time, that it had it. The running key names that builder and this same
+	// ask; running it a second time would spend a second place on one check.
+	elsewhere := m.runningElsewhere
+	if m.duplicate != nil {
+		elsewhere = m.duplicate
+	}
+	if why := elsewhere(ctx, request); why != "" {
+		fmt.Fprintf(os.Stderr, "%s is handed out again while another builder runs it and is dropped: %s\n", request.ID, why)
+		_ = msg.Ack()
+		return false
+	}
+	if m.opts.Claim != nil && !m.opts.Claim() {
+		_ = msg.Nak()
+		return false
+	}
+	return true
+}
+
 // runningElsewhere says why an ask need not run here, or nothing: the bucket of the checks running says another builder
 // runs this very ask (its id, its head and its trunk commit). A key that cannot be read runs the check.
 func (m *natsMachine) runningElsewhere(ctx context.Context, r BuildRequest) string {
@@ -420,25 +514,39 @@ func duplicateOf(running CheckRunning, found bool, r BuildRequest, me string) st
 // subscribing `…accept.build` against a consumer filtered on `…accept.>` is rejected even though it is narrower. Learned
 // twice now, on two different consumers, which is why it is written down here.
 func (m *natsMachine) bind(q *takeQueue) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
 	sub, err := m.js.Context().PullSubscribe(q.worker.Filters[0], q.worker.Name,
 		nats.Bind(q.worker.Stream, q.worker.Name), nats.ManualAck())
 	if err != nil {
 		return err
 	}
-	q.sub, q.bound = sub, true
+	q.sub, q.pull, q.bound = sub, sub, true
 	return nil
 }
 
 // next takes the next request in the order of the queues: each tried for a moment, and when all are empty the first waited
 // on for a second. Nothing, with no error, when there was nothing.
 func (m *natsMachine) next(ctx context.Context) (*nats.Msg, *takeQueue, error) {
+	// **While a delivery builds, only delivery builds are taken, but for one check that waited** (novox/hq ADR 0483): the
+	// bucket of the plans building is read before either check queue is fetched from, and a key there holds both. The check
+	// that waited LetThroughAfter goes first, ahead of the builds that wait; the rest of the holders take builds only.
+	if m.seat == broker.TheBuildSeat && len(m.subs) > 1 {
+		if plans := m.building(ctx); len(plans) > 0 {
+			if msg, q := m.letOneThrough(ctx); msg != nil {
+				fmt.Fprintf(os.Stderr, "a check that waited %s is let through while %s builds\n", m.letThroughAfter(), whyHeld(plans))
+				return msg, q, nil
+			}
+			return m.nextBuild(ctx)
+		}
+	}
 	var last error
 	for _, q := range m.subs {
 		if !q.bound {
 			continue
 		}
 		trying, end := context.WithTimeout(ctx, checkTakeWait)
-		fetched, err := q.sub.Fetch(1, nats.Context(trying))
+		fetched, err := q.pull.Fetch(1, nats.Context(trying))
 		end()
 		if len(fetched) > 0 {
 			return fetched[0], q, nil
@@ -454,9 +562,18 @@ func (m *natsMachine) next(ctx context.Context) (*nats.Msg, *takeQueue, error) {
 	if last != nil {
 		return nil, nil, last
 	}
+	return m.nextBuild(ctx)
+}
+
+// nextBuild waits for a second at most for a delivery build, the seat's own queue.
+func (m *natsMachine) nextBuild(ctx context.Context) (*nats.Msg, *takeQueue, error) {
+	if !m.subs[0].bound {
+		// Let go of while an ask ran and not bound again yet (Take binds it before it asks): nothing to take from.
+		return nil, nil, nil
+	}
 	waiting, end := context.WithTimeout(ctx, takeIdleWait)
 	defer end()
-	fetched, err := m.subs[0].sub.Fetch(1, nats.Context(waiting))
+	fetched, err := m.subs[0].pull.Fetch(1, nats.Context(waiting))
 	if len(fetched) > 0 {
 		return fetched[0], m.subs[0], nil
 	}
@@ -619,3 +736,16 @@ func endCancelled(ctx context.Context, b *natsBuild) {
 	}
 	_ = b.msg.Term()
 }
+
+// boundKinds are the kinds of queue this machine holds a subscription to now.
+func (m *natsMachine) boundKinds() []string {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	var out []string
+	for _, q := range m.subs {
+		if q.bound {
+			out = append(out, q.kind)
+		}
+	}
+	return out
+}

internal/link/checks_nats.go

@@ -287,12 +287,16 @@ type CheckRunning struct {
 }
 
 // RunningKeyOf is the key a check is said running under: its pull request's tokens, or `group.<name>` for a group's
-// composed check; none for a try, which no other request replaces.
+// composed check; `try.<id>` for a try, which no other request replaces.
 func RunningKeyOf(r BuildRequest) (string, bool) {
 	c := r.Check
 	switch {
-	case c == nil, c.Try:
+	case c == nil:
 		return "", false
+	case c.Try:
+		// A try says it runs under its own id, which no other request shares: so a reader of the bucket can tell a try that runs
+		// from a check left waiting for a redelivery (ADR 0483 clause 3).
+		return "try." + tokenOf(r.ID), true
 	case c.Group != "":
 		return "group." + tokenOf(c.Group), true
 	case c.Number <= 0:

internal/link/checks_nats_integration_test.go

@@ -6,7 +6,6 @@ import (
 	"context"
 	"encoding/json"
 	"reflect"
-	"strings"
 	"testing"
 	"time"
 
@@ -595,21 +594,12 @@ func TestABusyMachineTakesNoWaitingAskWhateverItsPullsHold(t *testing.T) {
 	case <-time.After(10 * time.Second):
 		t.Fatal("builder a took nothing")
 	}
-	var other *takeQueue
-	for _, q := range a.subs {
-		if q.kind == queueOther && q.bound {
-			other = q
-		}
-	}
-	if other == nil {
-		t.Fatal("builder a has no pull on the other checks")
-	}
-	// The queue is empty, so this request is answered at its expiry with a status message that lands in the pull.
-	reply := strings.TrimSuffix(other.sub.Subject, "*") + "late"
-	if err := js.Conn().PublishRequest("$JS.API.CONSUMER.MSG.NEXT."+other.worker.Stream+"."+other.worker.Name, reply,
-		[]byte(`{"batch":1,"expires":1000000}`)); err != nil {
-		t.Fatal(err)
+	// **A busy machine holds no pull at all** (issues 1649 and 1747): the queues the running ask did not come from are let go of,
+	// so no message, a status message or a late delivery, can sit in one while it runs.
+	if kinds := a.boundKinds(); len(kinds) != 1 || kinds[0] != queueBuilds {
+		t.Fatalf("builder a holds %v while it builds; want only the queue its build came from", kinds)
 	}
+	other := &takeQueue{kind: queueOther, worker: broker.CheckWorkers()[1]}
 	time.Sleep(500 * time.Millisecond)
 	for i, id := range []string{"wait-1", "wait-2"} {
 		if err := asks.Ask(ctx, aPullCheck(id, 20+i, "head-x-000000000", "trunk-1-000000", false)); err != nil {

internal/link/checks_wait_integration_test.go

@@ -0,0 +1,479 @@
+//go:build integration
+
+package link
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"github.com/nats-io/nats.go"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nats-io/nats.go/jetstream"
+
+	"github.com/novox/mesh-controller/internal/broker"
+)
+
+// Checks wait while a delivery builds (novox/hq ADR 0483, issues 1652, 1687, 1688), against a real bus.
+
+// aBusWithTheBuckets is the bus with the build role and the controller's buckets, the bucket of the checks running with an age
+// of two seconds so a key a holder stopped refreshing is seen to expire.
+func aBusWithTheBuckets(t *testing.T) (*broker.JetStream, jetstream.KeyValue) {
+	t.Helper()
+	js := aBusWithTheBuildRole(t)
+	api, err := jetstream.New(js.Conn())
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx := t.Context()
+	if _, err := api.CreateKeyValue(ctx, jetstream.KeyValueConfig{Bucket: broker.CheckRunningBucket, History: 1, TTL: 2 * time.Second}); err != nil {
+		t.Fatal(err)
+	}
+	plans, err := api.CreateKeyValue(ctx, jetstream.KeyValueConfig{Bucket: broker.PlansBuildingBucket, History: 1, TTL: broker.PlansBuildingKeptFor})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return js, plans
+}
+
+func aCheckAskedAgo(ago time.Duration, number int, ready bool) BuildRequest {
+	r := aPullCheck(fmt.Sprintf("build-%d", time.Now().Add(-ago).UnixNano()), number, fmt.Sprintf("head-%d-0000000", number), "trunk-0-000000", ready)
+	return r
+}
+
+// 1652/AC6: a plan's builds asked in two tiers with a check waiting, the check is handed out only after the last tier's builds,
+// and not in the gap between the tiers.
+func TestNatsACheckIsHandedOutOnlyAfterTheLastTierOfAPlan(t *testing.T) {
+	js, plans := aBusWithTheBuckets(t)
+	ctx, stop := context.WithCancel(t.Context())
+	defer stop()
+	asks := BuildsOn(js, TheBuildMachine)
+
+	if _, err := plans.Put(ctx, "plan-1", []byte(`{"plan":"plan-1"}`)); err != nil {
+		t.Fatal(err)
+	}
+	if err := asks.Ask(ctx, aCheckAskedAgo(time.Minute, 7, true)); err != nil {
+		t.Fatal(err)
+	}
+	if err := asks.Ask(ctx, BuildRequest{ID: "tier-1-a", Repository: "/a"}); err != nil {
+		t.Fatal(err)
+	}
+	took := make(chan string, 16)
+	machine := MachineOverNATS(js, "anchor")
+	defer machine.Close()
+	go func() {
+		_ = machine.Take(ctx, func(ctx context.Context, work Build) {
+			took <- work.Request().ID
+			_ = work.Announce(ctx, BuildResult{ID: work.Request().ID, On: "anchor", Failed: "no"})
+			_ = work.Done()
+		})
+	}()
+	expect := func(want string) {
+		t.Helper()
+		select {
+		case got := <-took:
+			if got != want {
+				t.Fatalf("taken %s, want %s", got, want)
+			}
+		case <-time.After(15 * time.Second):
+			t.Fatalf("%s was not taken", want)
+		}
+	}
+	expect("tier-1-a")
+	// The gap between two tiers: the delivery's queue is empty, the plan's key is there, and the check is not taken.
+	select {
+	case got := <-took:
+		t.Fatalf("%s was taken in the gap between two tiers", got)
+	case <-time.After(3 * time.Second):
+	}
+	if err := asks.Ask(ctx, BuildRequest{ID: "tier-2-a", Repository: "/b"}); err != nil {
+		t.Fatal(err)
+	}
+	expect("tier-2-a")
+	select {
+	case got := <-took:
+		t.Fatalf("%s was taken before the plan's last build was built and its key deleted", got)
+	case <-time.After(2 * time.Second):
+	}
+	// The phase ends: the key is deleted, and the check is handed out.
+	if err := plans.Delete(ctx, "plan-1"); err != nil {
+		t.Fatal(err)
+	}
+	select {
+	case got := <-took:
+		if got == "tier-1-a" || got == "tier-2-a" {
+			t.Fatalf("a build was taken twice: %s", got)
+		}
+	case <-time.After(15 * time.Second):
+		t.Fatal("the check was not handed out once the plan's key was deleted")
+	}
+}
+
+// 1688: two holders racing for checks that waited past the bound: exactly one is let through at a time, by a create that fails
+// while the key is there, and the key is deleted when its check ends, after which the next oldest goes.
+func TestNatsTwoHoldersRacingForOldChecksLetExactlyOneThrough(t *testing.T) {
+	js, plans := aBusWithTheBuckets(t)
+	ctx, stop := context.WithCancel(t.Context())
+	defer stop()
+	// The buckets' age is two seconds here, so the keys are refreshed well within it.
+	was := heartbeatWhileWorking
+	heartbeatWhileWorking = 400 * time.Millisecond
+	t.Cleanup(func() { heartbeatWhileWorking = was })
+	asks := BuildsOn(js, TheBuildMachine)
+	if _, err := plans.Put(ctx, "plan-1", []byte(`{"plan":"plan-1"}`)); err != nil {
+		t.Fatal(err)
+	}
+	for i, ago := range []time.Duration{50 * time.Minute, 40 * time.Minute, 35 * time.Minute} {
+		if err := asks.Ask(ctx, aCheckAskedAgo(ago, i+1, false)); err != nil {
+			t.Fatal(err)
+		}
+	}
+	var mu sync.Mutex
+	running, most := 0, 0
+	started := make(chan string, 8)
+	release := make(chan struct{})
+	do := func(ctx context.Context, work Build) {
+		mu.Lock()
+		running++
+		most = max(most, running)
+		mu.Unlock()
+		started <- work.Request().Check.Repo + fmt.Sprint(work.Request().Check.Number)
+		<-release
+		mu.Lock()
+		running--
+		mu.Unlock()
+		_ = work.Announce(ctx, BuildResult{ID: work.Request().ID, On: "x", Failed: "no"})
+		_ = work.Done()
+	}
+	for _, on := range []string{"ace", "shanks"} {
+		machine := MachineOverNATS(js, on)
+		defer machine.Close()
+		go func() { _ = machine.Take(ctx, do) }()
+	}
+	var order []string
+	for range 3 {
+		select {
+		case id := <-started:
+			order = append(order, id)
+		case <-time.After(20 * time.Second):
+			t.Fatalf("started so far: %v", order)
+		}
+		// While it runs, no second check starts and the key is there.
+		select {
+		case id := <-started:
+			t.Fatalf("%s started beside a check let through", id)
+		case <-time.After(2500 * time.Millisecond):
+		}
+		kv := runningKV(t, js)
+		if _, err := kv.Get(ctx, LetThroughKey); err != nil {
+			t.Fatalf("the let-through key is not there while the check runs: %v", err)
+		}
+		release <- struct{}{}
+		// It is deleted when the check ends: the next check let through creates the key again at once, and a create fails
+		// while the key is there, so its start (the next round) is the proof; after the last one the key stays gone.
+		if len(order) == 3 {
+			deadline := time.Now().Add(10 * time.Second)
+			for {
+				if _, err := kv.Get(ctx, LetThroughKey); err != nil {
+					break
+				}
+				if time.Now().After(deadline) {
+					t.Fatal("the let-through key was not deleted when the last check ended")
+				}
+				time.Sleep(50 * time.Millisecond)
+			}
+		}
+	}
+	if want := []string{"a1", "a2", "a3"}; !reflect.DeepEqual(order, want) {
+		t.Fatalf("checks went %v, want the oldest first %v", order, want)
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if most != 1 {
+		t.Fatalf("%d checks ran at once while a delivery built", most)
+	}
+}
+
+func runningKV(t *testing.T, js *broker.JetStream) jetstream.KeyValue {
+	t.Helper()
+	api, err := jetstream.New(js.Conn())
+	if err != nil {
+		t.Fatal(err)
+	}
+	kv, err := api.KeyValue(t.Context(), broker.CheckRunningBucket)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return kv
+}
+
+// 1688: the create of the let-through key succeeds for exactly one of holders asking at once, and a key its holder stopped
+// refreshing expires, after which the next create succeeds.
+func TestNatsOneCreateOfTheLetThroughKeySucceedsAndAStoppedHoldersKeyExpires(t *testing.T) {
+	js, _ := aBusWithTheBuckets(t)
+	gate := busGate{conn: js.Conn()}
+	ctx := t.Context()
+	var wg sync.WaitGroup
+	var mu sync.Mutex
+	won := 0
+	for i := range 8 {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			ok, err := gate.TakeLetThrough(ctx, fmt.Sprint("holder-", i))
+			if err != nil {
+				t.Error(err)
+				return
+			}
+			if ok {
+				mu.Lock()
+				won++
+				mu.Unlock()
+			}
+		}()
+	}
+	wg.Wait()
+	if won != 1 {
+		t.Fatalf("%d of 8 holders created the let-through key, want exactly one", won)
+	}
+	// The holder stopped: nothing refreshes the key, and the bucket's age (two seconds here) removes it.
+	deadline := time.Now().Add(15 * time.Second)
+	for {
+		ok, err := gate.TakeLetThrough(ctx, "next")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if ok {
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatal("the key of a stopped holder did not expire")
+		}
+		time.Sleep(250 * time.Millisecond)
+	}
+	// And a refreshed key does not expire.
+	for range 6 {
+		if err := gate.KeepLetThrough(ctx, "next"); err != nil {
+			t.Fatal(err)
+		}
+		time.Sleep(700 * time.Millisecond)
+	}
+	if ok, _ := gate.TakeLetThrough(ctx, "other"); ok {
+		t.Fatal("a refreshed key expired")
+	}
+	var v LetThrough
+	e, err := runningKV(t, js).Get(ctx, LetThroughKey)
+	if err != nil || json.Unmarshal(e.Value(), &v) != nil || v.Builder != "next" {
+		t.Fatalf("the key says %+v (%v)", v, err)
+	}
+}
+
+// 1687: the oldest waiting ask is read without being taken: no delivery is counted against it.
+func TestNatsTheOldestWaitingAskIsReadWithoutTakingIt(t *testing.T) {
+	js, _ := aBusWithTheBuckets(t)
+	ctx := t.Context()
+	asks := BuildsOn(js, TheBuildMachine)
+	old := aCheckAskedAgo(45*time.Minute, 1, false)
+	if err := asks.Ask(ctx, old); err != nil {
+		t.Fatal(err)
+	}
+	gate := busGate{conn: js.Conn()}
+	q := &takeQueue{kind: queueOther, worker: broker.CheckWorkers()[1]}
+	at, found, err := gate.OldestWaiting(ctx, q)
+	if err != nil || !found {
+		t.Fatalf("the first waiting ask was not read: %v %v", found, err)
+	}
+	if want, _ := BuildAskedAt(old.ID); !at.Equal(want) {
+		t.Fatalf("read %v, asked %v", at, want)
+	}
+	for range 3 {
+		if _, _, err := gate.OldestWaiting(ctx, q); err != nil {
+			t.Fatal(err)
+		}
+	}
+	info, err := js.Context().ConsumerInfo(q.worker.Stream, q.worker.Name)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.Delivered.Consumer != 0 || info.NumAckPending != 0 || info.NumPending != 1 {
+		t.Fatalf("reading the age took the ask: delivered %d, pending acks %d, waiting %d", info.Delivered.Consumer, info.NumAckPending, info.NumPending)
+	}
+	// And an empty queue reads as none.
+	if _, found, err := gate.OldestWaiting(ctx, &takeQueue{kind: queueReady, worker: broker.CheckWorkers()[0]}); err != nil || found {
+		t.Fatalf("an empty queue read as %v (%v)", found, err)
+	}
+}
+
+// Issue 1747: a message that reaches a builder's subscription outside a fetch is not held while the builder runs another ask. A
+// stray check lands in the other queue's subscription of builder A, which then runs a long check; the server hands the stray
+// out again when its wait for an acknowledgement ends (two seconds here), builder B runs it, and A, finished, does not run it a
+// second time from the subscription it held.
+func TestNatsAMessageDeliveredOutsideAFetchIsNotHeldWhileTheBuilderRunsAnotherAsk(t *testing.T) { // 1747
+	js := aBusWithTheBuildRole(t)
+	ctx, stop := context.WithCancel(t.Context())
+	defer stop()
+	for _, w := range broker.CheckWorkers() {
+		w.AckWaitSeconds = 2
+		if err := js.EnsureConsumer(w); err != nil {
+			t.Fatal(err)
+		}
+	}
+	// The long check says it is alive well within the ack wait of two seconds.
+	was := heartbeatWhileWorking
+	heartbeatWhileWorking = 400 * time.Millisecond
+	t.Cleanup(func() { heartbeatWhileWorking = was })
+	asks := BuildsOn(js, TheBuildMachine)
+	long := aPullCheck("build-"+fmt.Sprint(time.Now().UnixNano()), 1, "head-1-0000000", "trunk-0-000000", true)
+	stray := aPullCheck("build-"+fmt.Sprint(time.Now().UnixNano()+1), 2, "head-2-0000000", "trunk-0-000000", false)
+	for _, r := range []BuildRequest{long, stray} {
+		if err := asks.Ask(ctx, r); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	var mu sync.Mutex
+	runs := map[string][]string{} // ask id -> the machines that ran it
+	release := make(chan struct{})
+	started := make(chan string, 8)
+	do := func(on string) func(context.Context, Build) {
+		return func(ctx context.Context, work Build) {
+			id := work.Request().ID
+			mu.Lock()
+			runs[id] = append(runs[id], on)
+			mu.Unlock()
+			started <- on + ":" + id
+			if id == long.ID {
+				<-release
+			}
+			_ = work.Announce(ctx, BuildResult{ID: id, On: on, Failed: "no"})
+			_ = work.Done()
+		}
+	}
+
+	var a *natsMachine
+	strayLanded := make(chan error, 1)
+	a = MachineOverNATSWith(js, "ace", TheBuildMachine, MachineOptions{Claim: func() bool {
+		// The moment the long check is claimed: the server hands the other queue's waiting check to A's subscription there, as
+		// one that arrives after a fetch gave up does. Done once.
+		select {
+		case <-strayLanded:
+			return true
+		default:
+		}
+		other := a.subs[2]
+		inbox := strings.TrimSuffix(other.sub.Subject, "*") + "stray"
+		body, _ := json.Marshal(map[string]any{"batch": 1, "expires": int64(30 * time.Second)})
+		if err := js.Conn().PublishRequest("$JS.API.CONSUMER.MSG.NEXT."+other.worker.Stream+"."+other.worker.Name, inbox, body); err != nil {
+			strayLanded <- err
+			return true
+		}
+		_ = js.Conn().Flush()
+		for deadline := time.Now().Add(5 * time.Second); time.Now().Before(deadline); time.Sleep(10 * time.Millisecond) {
+			if n, _, _ := other.sub.Pending(); n > 0 {
+				break
+			}
+		}
+		strayLanded <- nil
+		return true
+	}}).(*natsMachine)
+	defer a.Close()
+	go func() { _ = a.Take(ctx, do("ace")) }()
+
+	select {
+	case got := <-started:
+		if got != "ace:"+long.ID {
+			t.Fatalf("started %s, want the long check on ace first", got)
+		}
+	case <-time.After(15 * time.Second):
+		t.Fatal("the long check did not start")
+	}
+	if err := <-strayLanded; err != nil {
+		t.Fatal(err)
+	}
+
+	// B, free, runs the stray once the server hands it out again.
+	b := MachineOverNATS(js, "shanks")
+	defer b.Close()
+	go func() { _ = b.Take(ctx, do("shanks")) }()
+	select {
+	case got := <-started:
+		if got != "shanks:"+stray.ID {
+			t.Fatalf("started %s, want the stray on shanks", got)
+		}
+	case <-time.After(20 * time.Second):
+		t.Fatal("the stray was held by the builder that ran the long check and nobody ran it")
+	}
+	// A finishes, and does not run the stray from the subscription it held.
+	release <- struct{}{}
+	select {
+	case got := <-started:
+		t.Fatalf("%s started after the long check: the stray ran twice", got)
+	case <-time.After(6 * time.Second):
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if len(runs[stray.ID]) != 1 {
+		t.Fatalf("the stray ran on %v, want once", runs[stray.ID])
+	}
+}
+
+// Review of 1688: a young check pending redelivery (handed back by a Nak) stands ahead of a check older than 30 minutes in the
+// same queue while a plan builds. The let-through fetch would return the young one first, so nothing is fetched: the young
+// check's delivery count stays 1, it is not handed back every second until it is dead-lettered, and it is not run.
+func TestNatsAYoungRedeliveryAheadOfAnOldCheckIsNeverFetchedByTheLetThrough(t *testing.T) {
+	js, plans := aBusWithTheBuckets(t)
+	ctx, stop := context.WithCancel(t.Context())
+	defer stop()
+	asks := BuildsOn(js, TheBuildMachine)
+	young := aCheckAskedAgo(time.Minute, 1, false)
+	if err := asks.Ask(ctx, young); err != nil {
+		t.Fatal(err)
+	}
+	// Someone took it and handed it back: it is pending redelivery.
+	worker := broker.CheckWorkers()[1]
+	sub, err := js.Context().PullSubscribe(worker.Filters[0], worker.Name, nats.Bind(worker.Stream, worker.Name), nats.ManualAck())
+	if err != nil {
+		t.Fatal(err)
+	}
+	got, err := sub.Fetch(1, nats.MaxWait(5*time.Second))
+	if err != nil || len(got) != 1 {
+		t.Fatalf("the young check was not fetched to be handed back: %v", err)
+	}
+	if err := got[0].Nak(); err != nil {
+		t.Fatal(err)
+	}
+	_ = sub.Unsubscribe()
+	old := aCheckAskedAgo(45*time.Minute, 2, false)
+	if err := asks.Ask(ctx, old); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := plans.Put(ctx, "plan-1", []byte(`{"plan":"plan-1"}`)); err != nil {
+		t.Fatal(err)
+	}
+	started := make(chan string, 4)
+	machine := MachineOverNATS(js, "ace")
+	defer machine.Close()
+	go func() {
+		_ = machine.Take(ctx, func(ctx context.Context, work Build) {
+			started <- work.Request().ID
+			_ = work.Announce(ctx, BuildResult{ID: work.Request().ID, On: "ace", Failed: "no"})
+			_ = work.Done()
+		})
+	}()
+	select {
+	case id := <-started:
+		t.Fatalf("%s was run while the young redelivery stood ahead of it", id)
+	case <-time.After(6 * time.Second):
+	}
+	info, err := js.Context().ConsumerInfo(worker.Stream, worker.Name)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if info.Delivered.Consumer != 1 || info.NumRedelivered != 0 {
+		t.Fatalf("the young check was handed out %d time(s), %d redelivered: the let-through fetched it", info.Delivered.Consumer, info.NumRedelivered)
+	}
+}

internal/link/holds.go

@@ -0,0 +1,384 @@
+package link
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/nats-io/nats.go"
+	"github.com/nats-io/nats.go/jetstream"
+
+	"github.com/novox/mesh-controller/internal/broker"
+)
+
+// Checks wait while a delivery builds (novox/hq ADR 0483, issues 1652, 1687 and 1688).
+//
+// **The layout other parts read** (ADR 0484 clause 12 has the checker read the same key; a layout shared between modules
+// belongs in mesh-sdk, and this one is not there yet):
+//
+//   - bucket `mesh-controller_plans-building` (broker.PlansBuildingBucket): one key per delivery plan in its build phase, named
+//     by the plan's id (`plan-<digits>`), value a PlanBuilding as JSON. Written by the controller (lease holder) alone: put when
+//     the plan's first build is asked, put again about every thirty seconds, deleted when the phase ends; the bucket's age
+//     (two minutes) removes the key of a controller that stopped. A reader lists the keys and needs no value to decide.
+//   - key `let-through` in bucket `mesh-controller_checks-running` (broker.CheckRunningBucket), value a LetThrough as JSON:
+//     created by the holder that takes a check which waited LetThroughAfter, refreshed at each heartbeat of that check, deleted
+//     when it ends. At most one such check runs at a time on the build seat, because the create fails while the key is there.
+
+// LetThroughAfter is how long a check waits, while a delivery builds, before it is let through (ADR 0483 clause 3).
+const LetThroughAfter = 30 * time.Minute
+
+// LetThroughKey is the key of the one check let through, in the bucket of the checks running. It has no dot, so it is no
+// pull request's key (`<owner>.<repo>.<number>`) and no group's (`group.<name>`).
+const LetThroughKey = "let-through"
+
+// PlanBuilding is the value of a plan's key in the bucket of the plans building.
+type PlanBuilding struct {
+	Plan  string    `json:"plan"`
+	Since time.Time `json:"since"`
+	Seen  time.Time `json:"seen"`
+}
+
+// LetThrough is the value of the let-through key: the builder that runs the check and when it took it.
+type LetThrough struct {
+	Builder string    `json:"builder"`
+	Since   time.Time `json:"since"`
+}
+
+// checkGate is what a taking loop asks of the bus to hold checks while a delivery builds; a variable of the machine so a test
+// hands out against fakes.
+type checkGate interface {
+	// Building is the ids of the plans in their build phase: the keys of the bucket. An error is a bucket that cannot be read.
+	Building(ctx context.Context) ([]string, error)
+	// OldestWaiting is when the first waiting ask of a check queue was asked, read without taking it.
+	OldestWaiting(ctx context.Context, q *takeQueue) (time.Time, bool, error)
+	// TakeLetThrough creates the let-through key for a builder: false when it is there (another builder runs a check let through).
+	TakeLetThrough(ctx context.Context, builder string) (bool, error)
+	// KeepLetThrough puts the key again, and DropLetThrough deletes it.
+	KeepLetThrough(ctx context.Context, builder string) error
+	DropLetThrough(ctx context.Context) error
+}
+
+// busGate is the gate over a connection.
+type busGate struct{ conn *nats.Conn }
+
+func (g busGate) Building(ctx context.Context) ([]string, error) {
+	return BuildingPlans(ctx, g.conn)
+}
+
+// BuildingPlans is the ids of the delivery plans in their build phase, from the controller's bucket. A reader that is not the
+// build seat's (the checker, ADR 0484 clause 12) calls this. A bucket that cannot be read is an error; none is none building.
+func BuildingPlans(ctx context.Context, conn *nats.Conn) ([]string, error) {
+	api, err := jetstream.New(conn)
+	if err != nil {
+		return nil, err
+	}
+	kv, err := api.KeyValue(ctx, broker.PlansBuildingBucket)
+	if err != nil {
+		return nil, fmt.Errorf("the plans building: %w", err)
+	}
+	keys, err := kv.Keys(ctx)
+	if errors.Is(err, jetstream.ErrNoKeysFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("the plans building: %w", err)
+	}
+	return keys, nil
+}
+
+// OldestWaiting is when the check a fetch of this queue would return was asked, read without taking anything.
+//
+// **It sees redeliveries** (review of issue 1688). A work queue keeps only what is not acknowledged: what the worker handed out
+// (sequence up to its delivered mark) is running or waiting to be handed out again, and a fetch returns those before anything
+// new. An ask there that is not said running (a key of the checks running names its build) is such a redelivery. If one is
+// younger than the bound, the queue's next fetch would return it, and a young check is never let through: the queue is not a
+// candidate, and nothing is fetched, so nothing is handed back and no delivery is spent. Otherwise the candidate is the oldest
+// of the redeliveries and the first ask after the delivered mark.
+func (g busGate) OldestWaiting(ctx context.Context, q *takeQueue) (time.Time, bool, error) {
+	info, err := jsOf(g.conn).ConsumerInfo(q.worker.Stream, q.worker.Name, nats.Context(ctx))
+	if err != nil {
+		return time.Time{}, false, fmt.Errorf("the %s worker: %w", q.kind, err)
+	}
+	var oldest time.Time
+	note := func(at time.Time) {
+		if oldest.IsZero() || at.Before(oldest) {
+			oldest = at
+		}
+	}
+	for seq := uint64(1); seq <= info.Delivered.Stream; {
+		data, stored, got, err := g.directGet(ctx, q, seq)
+		if err != nil {
+			return time.Time{}, false, err
+		}
+		if got == 0 || got > info.Delivered.Stream {
+			break
+		}
+		seq = got + 1
+		var r BuildRequest
+		if json.Unmarshal(data, &r) != nil {
+			continue
+		}
+		running, ok, err := ReadRunning(ctx, g.conn, r)
+		if err != nil {
+			return time.Time{}, false, fmt.Errorf("the checks running: %w", err)
+		}
+		if ok && running.Build == r.ID {
+			continue // running now
+		}
+		at := askedAtOf(data, stored)
+		if time.Since(at) < LetThroughAfter {
+			return time.Time{}, false, nil // a young redelivery is next in line
+		}
+		note(at)
+	}
+	data, stored, got, err := g.directGet(ctx, q, info.Delivered.Stream+1)
+	if err != nil {
+		return time.Time{}, false, err
+	}
+	if got != 0 {
+		note(askedAtOf(data, stored))
+	}
+	return oldest, !oldest.IsZero(), nil
+}
+
+// directGet reads the first ask at or after a sequence of a check queue's stream, without taking it: its body, the time the
+// stream stored it, and its sequence (0 when there is none).
+func (g busGate) directGet(ctx context.Context, q *takeQueue, seq uint64) ([]byte, string, uint64, error) {
+	body, _ := json.Marshal(map[string]any{"seq": seq, "next_by_subj": q.worker.Filters[0]})
+	reply, err := g.conn.RequestWithContext(ctx, "$JS.API.DIRECT.GET."+q.worker.Stream, body)
+	if err != nil {
+		return nil, "", 0, fmt.Errorf("the asks of the %s queue: %w", q.kind, err)
+	}
+	if st := reply.Header.Get("Status"); st == "404" || st == "408" {
+		return nil, "", 0, nil
+	}
+	got, _ := strconv.ParseUint(reply.Header.Get("Nats-Sequence"), 10, 64)
+	return reply.Data, reply.Header.Get("Nats-Time-Stamp"), got, nil
+}
+
+// askedAtOf is when a request was asked: its id says (NewBuildID), the stream's own time otherwise, and a request that says
+// neither is taken as asked now, so it is never let through on a guess.
+func askedAtOf(data []byte, stored string) time.Time {
+	var r BuildRequest
+	if json.Unmarshal(data, &r) == nil {
+		if at, ok := BuildAskedAt(r.ID); ok {
+			return at
+		}
+	}
+	if at, err := time.Parse(time.RFC3339Nano, stored); err == nil {
+		return at
+	}
+	return time.Now()
+}
+
+func jsOf(conn *nats.Conn) nats.JetStreamContext {
+	js, _ := conn.JetStream()
+	return js
+}
+
+func (g busGate) TakeLetThrough(ctx context.Context, builder string) (bool, error) {
+	kv, err := runningBucket(ctx, g.conn)
+	if err != nil {
+		return false, err
+	}
+	body, _ := json.Marshal(LetThrough{Builder: builder, Since: time.Now().UTC()})
+	if _, err := kv.Create(ctx, LetThroughKey, body); err != nil {
+		if errors.Is(err, jetstream.ErrKeyExists) {
+			return false, nil
+		}
+		return false, err
+	}
+	return true, nil
+}
+
+func (g busGate) KeepLetThrough(ctx context.Context, builder string) error {
+	kv, err := runningBucket(ctx, g.conn)
+	if err != nil {
+		return err
+	}
+	body, _ := json.Marshal(LetThrough{Builder: builder, Since: time.Now().UTC()})
+	_, err = kv.Put(ctx, LetThroughKey, body)
+	return err
+}
+
+func (g busGate) DropLetThrough(ctx context.Context) error {
+	kv, err := runningBucket(ctx, g.conn)
+	if err != nil {
+		return err
+	}
+	if err := kv.Delete(ctx, LetThroughKey); err != nil && !errors.Is(err, jetstream.ErrKeyNotFound) {
+		return err
+	}
+	return nil
+}
+
+// CheckHold is what a reader of the queue (the controller's own verb) says of why checks wait: the plans building and the check
+// let through now, if one.
+type CheckHold struct {
+	Plans      []string
+	LetThrough *LetThrough
+}
+
+// ReadCheckHold reads the plans building and the let-through key. A bucket that cannot be read is an error the caller says.
+func ReadCheckHold(ctx context.Context, conn *nats.Conn) (CheckHold, error) {
+	var h CheckHold
+	plans, err := BuildingPlans(ctx, conn)
+	if err != nil {
+		return h, err
+	}
+	h.Plans = plans
+	kv, err := runningBucket(ctx, conn)
+	if err != nil {
+		return h, err
+	}
+	e, err := kv.Get(ctx, LetThroughKey)
+	if errors.Is(err, jetstream.ErrKeyNotFound) {
+		return h, nil
+	}
+	if err != nil {
+		return h, err
+	}
+	var l LetThrough
+	if json.Unmarshal(e.Value(), &l) == nil {
+		h.LetThrough = &l
+	}
+	return h, nil
+}
+
+// gateOf is the machine's gate: the one a test set, or the bus's.
+func (m *natsMachine) gateOf() checkGate {
+	if m.gate != nil {
+		return m.gate
+	}
+	return busGate{conn: m.js.Conn()}
+}
+
+// sayOnce says a fault of the hold the first time it happens and again once it has recovered and happened anew, so a bucket
+// that cannot be read is in the log once and not every second.
+func (m *natsMachine) sayOnce(kind string, err error) {
+	if m.said == nil {
+		m.said = map[string]bool{}
+	}
+	if err == nil {
+		delete(m.said, kind)
+		return
+	}
+	if !m.said[kind] {
+		m.said[kind] = true
+		fmt.Fprintf(os.Stderr, "%s; read as empty, so no check is held for it: %v\n", kind, err)
+	}
+}
+
+// building says whether a delivery builds: any key in the bucket of the plans building. **A bucket that cannot be read is said
+// and read as empty** (ADR 0483 clause 2): a check wrongly held costs a pull request its turn, a fault that held every check
+// would stop the mesh checking.
+func (m *natsMachine) building(ctx context.Context) []string {
+	plans, err := m.gateOf().Building(ctx)
+	m.sayOnce("the bucket of the plans building cannot be read", err)
+	if err != nil {
+		// empty-on-error: ADR 0483 clause 2 — a bucket that cannot be read is said (sayOnce) and read as empty, because a check wrongly held costs a pull request its turn and a fault that held every check would stop the mesh checking.
+		return nil
+	}
+	return plans
+}
+
+// letOneThrough takes the oldest waiting check of the two check queues once it waited LetThroughAfter, by the one let-through
+// key: nil when none waited that long, when another holder runs the check let through, or when the check was taken by
+// another holder in the moment. The caller owns the key while it returns a message and releases it with dropLetThrough.
+func (m *natsMachine) letOneThrough(ctx context.Context) (*nats.Msg, *takeQueue) {
+	gate := m.gateOf()
+	var oldest *takeQueue
+	var oldestAt time.Time
+	for _, q := range m.subs[1:] {
+		if !q.bound {
+			continue
+		}
+		at, found, err := gate.OldestWaiting(ctx, q)
+		m.sayOnce("the first waiting check of the "+q.kind+" queue cannot be read", err)
+		if err != nil || !found {
+			continue
+		}
+		if oldest == nil || at.Before(oldestAt) {
+			oldest, oldestAt = q, at
+		}
+	}
+	if oldest == nil || time.Since(oldestAt) < m.letThroughAfter() {
+		return nil, nil
+	}
+	created, err := gate.TakeLetThrough(ctx, m.on)
+	m.sayOnce("the let-through key cannot be taken", err)
+	if err != nil || !created {
+		return nil, nil
+	}
+	trying, end := context.WithTimeout(ctx, checkTakeWait)
+	defer end()
+	fetched, err := oldest.pull.Fetch(1, nats.Context(trying))
+	if len(fetched) == 0 {
+		if err != nil && !errors.Is(err, context.DeadlineExceeded) && !errors.Is(err, nats.ErrTimeout) && !errors.Is(err, context.Canceled) {
+			m.sayOnce("the "+oldest.kind+" check queue cannot be taken from", err)
+		}
+		m.dropLetThrough(ctx)
+		return nil, nil
+	}
+	// Another holder took the one that was oldest in the moment between the read and the fetch: what came is a younger check,
+	// handed back and the key released, never run during a delivery.
+	if askedAtOf(fetched[0].Data, "").Add(m.letThroughAfter()).After(time.Now()) {
+		_ = fetched[0].NakWithDelay(time.Minute) // a delay keeps it off the queue of redeliveries a fetch reads first
+		m.dropLetThrough(ctx)
+		return nil, nil
+	}
+	m.letKey = true
+	return fetched[0], oldest
+}
+
+func (m *natsMachine) letThroughAfter() time.Duration {
+	if m.opts.LetThroughAfter > 0 {
+		return m.opts.LetThroughAfter
+	}
+	return LetThroughAfter
+}
+
+// dropLetThrough deletes the let-through key this holder created.
+func (m *natsMachine) dropLetThrough(ctx context.Context) {
+	m.letKey = false
+	if err := m.gateOf().DropLetThrough(context.WithoutCancel(ctx)); err != nil {
+		fmt.Fprintf(os.Stderr, "could not take the let-through key away; it ages out: %v\n", err)
+	}
+}
+
+// keepLetThrough refreshes the key at every heartbeat while the check it was created for runs, and returns the end of that: it
+// stops the refreshing and deletes the key.
+func (m *natsMachine) keepLetThrough(ctx context.Context, every time.Duration) (end func()) {
+	done := make(chan struct{})
+	finished := make(chan struct{})
+	go func() {
+		defer close(finished)
+		tick := time.NewTicker(every)
+		defer tick.Stop()
+		for {
+			select {
+			case <-done:
+				return
+			case <-tick.C:
+				putting, stop := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
+				if err := m.gateOf().KeepLetThrough(putting, m.on); err != nil {
+					fmt.Fprintf(os.Stderr, "could not keep the let-through key: %v\n", err)
+				}
+				stop()
+			}
+		}
+	}()
+	return func() {
+		close(done)
+		<-finished
+		m.dropLetThrough(ctx)
+	}
+}
+
+// whyHeld words the plans a check is held for, for the log.
+func whyHeld(plans []string) string { return strings.Join(plans, ", ") }

internal/link/holds_test.go

@@ -0,0 +1,307 @@
+package link
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nats-io/nats.go"
+
+	"github.com/novox/mesh-controller/internal/broker"
+)
+
+// Checks wait while a delivery builds (novox/hq ADR 0483, issues 1687 and 1688): the order the taking loop hands out in, against
+// fake queues and a fake bus.
+
+// fakeQueue is a queue the loop fetches from: the asks waiting, handed out in order, and how often it was fetched from.
+type fakeQueue struct {
+	mu      sync.Mutex
+	waiting []*nats.Msg
+	fetched int
+}
+
+func (f *fakeQueue) Fetch(int, ...nats.PullOpt) ([]*nats.Msg, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.fetched++
+	if len(f.waiting) == 0 {
+		return nil, nats.ErrTimeout
+	}
+	m := f.waiting[0]
+	f.waiting = f.waiting[1:]
+	return []*nats.Msg{m}, nil
+}
+
+func (f *fakeQueue) fetches() int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.fetched
+}
+
+// askedAgo is a request asked this long ago, as the id says, for a check of this pull request.
+func askedAgo(ago time.Duration, number int, ready bool) *nats.Msg {
+	id := fmt.Sprintf("build-%d", time.Now().Add(-ago).UnixNano())
+	body, _ := json.Marshal(BuildRequest{ID: id, Repository: "r", Check: &CheckRequest{Owner: "o", Repo: "r", Number: number, Ready: ready}})
+	return &nats.Msg{Data: body}
+}
+
+func buildAsk() *nats.Msg {
+	body, _ := json.Marshal(BuildRequest{ID: fmt.Sprintf("build-%d", time.Now().UnixNano()), Repository: "r"})
+	return &nats.Msg{Data: body}
+}
+
+// fakeGate is the bus as the loop sees it for the hold.
+type fakeGate struct {
+	mu         sync.Mutex
+	plans      []string
+	plansErr   error
+	letKey     bool
+	taken      int
+	kept       int
+	dropped    int
+	oldestFrom map[*takeQueue]*fakeQueue
+}
+
+func (g *fakeGate) Building(context.Context) ([]string, error) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	return g.plans, g.plansErr
+}
+
+// OldestWaiting reads the first waiting ask of the fake queue without taking it.
+func (g *fakeGate) OldestWaiting(_ context.Context, q *takeQueue) (time.Time, bool, error) {
+	f := g.oldestFrom[q]
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if len(f.waiting) == 0 {
+		return time.Time{}, false, nil
+	}
+	return askedAtOf(f.waiting[0].Data, ""), true, nil
+}
+
+func (g *fakeGate) TakeLetThrough(context.Context, string) (bool, error) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if g.letKey {
+		return false, nil
+	}
+	g.letKey = true
+	g.taken++
+	return true, nil
+}
+
+func (g *fakeGate) KeepLetThrough(context.Context, string) error {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	g.kept++
+	return nil
+}
+
+func (g *fakeGate) DropLetThrough(context.Context) error {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	g.letKey = false
+	g.dropped++
+	return nil
+}
+
+func (g *fakeGate) setPlans(plans ...string) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	g.plans = plans
+}
+
+// aMachine is a loop on the build seat with a delivery queue and the two check queues, all fake.
+func aMachine() (m *natsMachine, builds, ready, other *fakeQueue, gate *fakeGate) {
+	builds, ready, other = &fakeQueue{}, &fakeQueue{}, &fakeQueue{}
+	subs := []*takeQueue{
+		{kind: queueBuilds, pull: builds, bound: true},
+		{kind: queueReady, pull: ready, bound: true},
+		{kind: queueOther, pull: other, bound: true},
+	}
+	gate = &fakeGate{oldestFrom: map[*takeQueue]*fakeQueue{subs[1]: ready, subs[2]: other}}
+	m = &natsMachine{on: "ace", seat: broker.TheBuildSeat, subs: subs, gate: gate}
+	return m, builds, ready, other, gate
+}
+
+func nextAsk(t *testing.T, m *natsMachine) (*nats.Msg, *takeQueue) {
+	t.Helper()
+	msg, q, err := m.next(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	return msg, q
+}
+
+// 1652/AC6, 1687: a waiting check is not taken while a plan key is there, also when the delivery's queue is empty for the moment
+// (between two tiers).
+func TestNoCheckIsTakenWhileAPlanBuilds(t *testing.T) {
+	m, builds, ready, other, gate := aMachine()
+	gate.setPlans("plan-1")
+	ready.waiting = []*nats.Msg{askedAgo(2*time.Minute, 1, true)}
+	other.waiting = []*nats.Msg{askedAgo(5*time.Minute, 2, false)}
+	// The delivery's queue is empty: between two tiers.
+	if msg, _ := nextAsk(t, m); msg != nil {
+		t.Fatalf("a check was taken while plan-1 builds: %s", msg.Data)
+	}
+	if ready.fetches() != 0 || other.fetches() != 0 {
+		t.Fatalf("the check queues were fetched from while plan-1 builds: ready %d, other %d", ready.fetches(), other.fetches())
+	}
+	if builds.fetches() == 0 {
+		t.Fatal("the delivery's queue was not looked at")
+	}
+}
+
+// A delivery build is still taken first, and the check waits behind it.
+func TestADeliveryBuildIsTakenWhileAPlanBuilds(t *testing.T) {
+	m, builds, ready, _, gate := aMachine()
+	gate.setPlans("plan-1")
+	builds.waiting = []*nats.Msg{buildAsk()}
+	ready.waiting = []*nats.Msg{askedAgo(2*time.Minute, 1, true)}
+	msg, q := nextAsk(t, m)
+	if msg == nil || q.kind != queueBuilds {
+		t.Fatalf("the delivery build was not taken first: %v %v", msg, q)
+	}
+	if ready.fetches() != 0 {
+		t.Fatal("a check queue was fetched from")
+	}
+}
+
+// It is taken once the key is gone (deleted at the phase's end, or expired).
+func TestACheckIsTakenOnceTheKeyIsGone(t *testing.T) {
+	m, _, ready, _, gate := aMachine()
+	gate.setPlans("plan-1")
+	ready.waiting = []*nats.Msg{askedAgo(2*time.Minute, 1, true)}
+	if msg, _ := nextAsk(t, m); msg != nil {
+		t.Fatal("taken while the key is there")
+	}
+	gate.setPlans()
+	msg, q := nextAsk(t, m)
+	if msg == nil || q.kind != queueReady {
+		t.Fatalf("the check was not taken once the key was gone: %v", q)
+	}
+	if m.letKey {
+		t.Fatal("a check taken without a delivery building took the let-through key")
+	}
+}
+
+// 1687: a bucket that cannot be read is said and read as empty, so the checks are taken.
+func TestAnUnreadableBucketHoldsNoCheck(t *testing.T) {
+	m, _, ready, _, gate := aMachine()
+	gate.plansErr = errors.New("permissions violation")
+	gate.plans = []string{"plan-1"}
+	ready.waiting = []*nats.Msg{askedAgo(2*time.Minute, 1, true)}
+	msg, q := nextAsk(t, m)
+	if msg == nil || q.kind != queueReady {
+		t.Fatal("a check was held because the bucket could not be read")
+	}
+	if !m.said["the bucket of the plans building cannot be read"] {
+		t.Fatalf("the fault was not said: %v", m.said)
+	}
+}
+
+// 1688: a check asked 30 minutes ago is let through while a key is there; the oldest across both queues by ask time, ahead of a
+// waiting delivery build; a younger one is never taken before it.
+func TestTheOldestCheckPastTheBoundGoesFirstAcrossBothQueues(t *testing.T) {
+	m, builds, ready, other, gate := aMachine()
+	gate.setPlans("plan-1")
+	builds.waiting = []*nats.Msg{buildAsk()}
+	ready.waiting = []*nats.Msg{askedAgo(31*time.Minute, 1, true)}
+	other.waiting = []*nats.Msg{askedAgo(50*time.Minute, 2, false)}
+	msg, q := nextAsk(t, m)
+	if msg == nil || q.kind != queueOther || !strings.Contains(string(msg.Data), `"number":2`) {
+		t.Fatalf("the oldest check (50 minutes, other queue) was not let through first: %v", q)
+	}
+	if !m.letKey || gate.taken != 1 {
+		t.Fatalf("the let-through key was not created for it: held %v, created %d", m.letKey, gate.taken)
+	}
+}
+
+// 1688: several checks past the bound go one at a time, oldest first: while the key is there every other holder takes builds.
+func TestChecksPastTheBoundGoOneAtATimeOldestFirst(t *testing.T) {
+	m, builds, ready, other, gate := aMachine()
+	gate.setPlans("plan-1")
+	ready.waiting = []*nats.Msg{askedAgo(33*time.Minute, 1, true), askedAgo(31*time.Minute, 3, true)}
+	other.waiting = []*nats.Msg{askedAgo(40*time.Minute, 2, false)}
+	var order []string
+	for range 3 {
+		msg, q := nextAsk(t, m)
+		if msg == nil {
+			t.Fatalf("no check let through after %v", order)
+		}
+		var r BuildRequest
+		_ = json.Unmarshal(msg.Data, &r)
+		order = append(order, fmt.Sprint(r.Check.Number, q.kind))
+		// While it runs another holder (the same fake gate, key held) takes builds only.
+		builds.waiting = []*nats.Msg{buildAsk()}
+		other2 := &natsMachine{on: "shanks", seat: broker.TheBuildSeat, subs: m.subs, gate: gate}
+		if next, nq := nextAsk(t, other2); next == nil || nq.kind != queueBuilds {
+			t.Fatalf("a second holder did not take a delivery build while the let-through key is held: %v", nq)
+		}
+		m.dropLetThrough(context.Background())
+	}
+	if want := []string{"2other", "1ready", "3ready"}; strings.Join(order, " ") != strings.Join(want, " ") {
+		t.Fatalf("checks went %v, want %v (oldest first, one at a time)", order, want)
+	}
+}
+
+// 1688: a check younger than the bound is never let through, and no key is created for it.
+func TestACheckYoungerThanTheBoundIsHeld(t *testing.T) {
+	m, _, ready, _, gate := aMachine()
+	gate.setPlans("plan-1")
+	ready.waiting = []*nats.Msg{askedAgo(29*time.Minute, 1, true)}
+	if msg, _ := nextAsk(t, m); msg != nil {
+		t.Fatal("a check of 29 minutes was let through")
+	}
+	if gate.taken != 0 {
+		t.Fatal("a let-through key was created for a young check")
+	}
+	if ready.fetches() != 0 {
+		t.Fatal("the age was read by a fetch; it must be read without taking")
+	}
+}
+
+// 1688: the holder that lost the race for the key, or the check, takes builds only; and a younger check that arrives in the
+// moment between the read and the fetch is handed back with the key released.
+func TestAYoungerCheckFetchedInTheRaceIsHandedBackAndTheKeyReleased(t *testing.T) {
+	m, _, ready, _, gate := aMachine()
+	gate.setPlans("plan-1")
+	// The read sees the old check; before the fetch another holder takes it and a young one is first.
+	gate.oldestFrom[m.subs[1]] = &fakeQueue{waiting: []*nats.Msg{askedAgo(40*time.Minute, 1, true)}}
+	ready.waiting = []*nats.Msg{askedAgo(time.Minute, 2, true)}
+	if msg, _ := nextAsk(t, m); msg != nil {
+		t.Fatalf("a young check was run during a delivery: %s", msg.Data)
+	}
+	if gate.letKey || m.letKey {
+		t.Fatal("the let-through key was left held")
+	}
+}
+
+// The key of a check let through is refreshed while it runs and deleted when it ends.
+func TestTheLetThroughKeyLivesAsLongAsTheCheckRuns(t *testing.T) {
+	m, _, ready, _, gate := aMachine()
+	gate.setPlans("plan-1")
+	ready.waiting = []*nats.Msg{askedAgo(40*time.Minute, 1, true)}
+	if msg, _ := nextAsk(t, m); msg == nil {
+		t.Fatal("not let through")
+	}
+	end := m.keepLetThrough(context.Background(), 20*time.Millisecond)
+	time.Sleep(120 * time.Millisecond)
+	gate.mu.Lock()
+	held, kept := gate.letKey, gate.kept
+	gate.mu.Unlock()
+	if !held || kept == 0 {
+		t.Errorf("while the check ran the key was held %v and refreshed %d times", held, kept)
+	}
+	end()
+	gate.mu.Lock()
+	defer gate.mu.Unlock()
+	if gate.letKey || m.letKey {
+		t.Error("the key was not deleted when the check ended")
+	}
+}

internal/link/queue.go

@@ -88,6 +88,40 @@ type Queue struct {
 	AckPending int         `json:"ack-pending"`
 	MaxDeliver int         `json:"max-deliver"`
 	Asks       []QueuedAsk `json:"asks"`
+	// Hold is why the checks wait: the delivery plans building and the check let through now (ADR 0483, issues 1687 and 1688);
+	// HoldFault says the bucket could not be read, in which case Hold is empty.
+	Hold      CheckHold `json:"hold"`
+	HoldFault string    `json:"hold-fault,omitempty"`
+}
+
+// LetThroughOf says which ask is let through under ADR 0483 clause 3: the check that waited LetThroughAfter or longer and is next
+// (the oldest waiting check across the two check queues, while a delivery builds), and the check in flight that was let through
+// (the let-through key names the machine that runs it). Empty when none.
+func (q Queue) LetThroughOf(now time.Time) (next, running string) {
+	if len(q.Hold.Plans) == 0 && q.Hold.LetThrough == nil {
+		return "", ""
+	}
+	var oldest *QueuedAsk
+	for i := range q.Asks {
+		a := &q.Asks[i]
+		if a.State != AskWaiting || a.Request.Check == nil || a.AskedAt.IsZero() {
+			continue
+		}
+		if oldest == nil || a.AskedAt.Before(oldest.AskedAt) {
+			oldest = a
+		}
+	}
+	if oldest != nil && len(q.Hold.Plans) > 0 && now.Sub(oldest.AskedAt) >= LetThroughAfter {
+		next = oldest.ID
+	}
+	if q.Hold.LetThrough != nil {
+		for _, a := range q.Asks {
+			if a.State == AskInFlight && a.Request.Check != nil && a.On == q.Hold.LetThrough.Builder {
+				running = a.ID
+			}
+		}
+	}
+	return next, running
 }
 
 // Of is the asks in one state, in queue order.
@@ -319,6 +353,16 @@ func ReadQueue(ctx context.Context, js *broker.JetStream, seat string) (Queue, e
 	for _, r := range reads {
 		q.Asks = append(q.Asks, ClassifyQueue(r.asks, r.delivered, r.ackPending, heard)...)
 	}
+	// And why the checks wait, for the build seat that has them (ADR 0483 clause 5). A bucket that cannot be read is said by the
+	// queue, which then names no plan.
+	if seat == broker.TheBuildSeat {
+		hold, err := ReadCheckHold(ctx, js.Conn())
+		if err != nil {
+			q.HoldFault = err.Error()
+		} else {
+			q.Hold = hold
+		}
+	}
 	return q, nil
 }
 

internal/link/stray_test.go

@@ -0,0 +1,54 @@
+package link
+
+import (
+	"testing"
+	"time"
+
+	"github.com/nats-io/nats.go"
+)
+
+// Issue 1747: a builder never holds a message it does not start. A message the server sends after a fetch gave up lands in that
+// queue's subscription; while an ask runs, the queues it does not come from are let go of, so such a message is not held
+// unheartbeated for the whole run, and the queues are bound again before the next fetch.
+
+func TestARunningAskLetsGoOfTheQueuesItDidNotComeFrom(t *testing.T) {
+	m, builds, _, other, _ := aMachine()
+	// A delivery build reached the builds queue's subscription after its fetch gave up: it sits in the buffer.
+	builds.waiting = []*nats.Msg{buildAsk()}
+	took := m.subs[1] // the running ask came from the ready queue
+
+	m.quiesce(took)
+
+	if !took.bound || took.pull == nil {
+		t.Error("the queue the running ask came from was let go of; its acknowledgements need it")
+	}
+	for _, q := range []*takeQueue{m.subs[0], m.subs[2]} {
+		if q.bound || q.pull != nil || q.sub != nil {
+			t.Errorf("the %s queue is still held while an ask runs", q.kind)
+		}
+	}
+	// Nothing is fetched from a queue that was let go of: a message in it cannot be taken unheartbeated.
+	if msg, _, _ := m.next(t.Context()); msg != nil {
+		t.Fatalf("a message was taken from a queue that was let go of: %s", msg.Data)
+	}
+	if builds.fetches() != 0 || other.fetches() != 0 {
+		t.Errorf("fetched from a queue that was let go of: builds %d, other %d", builds.fetches(), other.fetches())
+	}
+}
+
+// Once the ask is settled the queue it came from is let go of too: a second message the server delivered into its subscription
+// on a pull request still open is not run after the ask ends (review of 1747).
+func TestTheQueueTheAskCameFromIsLetGoOfWhenTheAskEnds(t *testing.T) {
+	m, _, ready, _, _ := aMachine()
+	ready.waiting = []*nats.Msg{askedAgo(time.Minute, 2, true)}
+	m.quiesce(nil)
+	for _, q := range m.subs {
+		if q.bound || q.pull != nil {
+			t.Errorf("the %s queue is still held after the ask ended", q.kind)
+		}
+	}
+	m.subs[0].bound, m.subs[0].pull = true, &fakeQueue{}
+	if msg, _, _ := m.next(t.Context()); msg != nil || ready.fetches() != 0 {
+		t.Fatal("a message held in the kept queue's subscription was taken after the ask ended")
+	}
+}

internal/ownmanifest/image_place_test.go

@@ -0,0 +1,92 @@
+package ownmanifest
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// imagesOutOfPlace lists the image artifacts among manifests (module name to its manifest's text) whose Dockerfile
+// is not a file inside that module's own directory, root/<module> (novox/hq ADR 0487 clause 13, which replaced the
+// refusal of the image kind of ADR 0480 clause 11). The image builder builds a module from its directory alone.
+// It reads the manifest as plain JSON, since the catalogue parser refuses some of these itself. It mirrors mesh-catalog's checks/imageplace: an empty from, an absolute one, one leaving the directory with ..,
+// or a name that is no file there, is refused.
+func imagesOutOfPlace(t *testing.T, root string, manifests map[string][]byte) []string {
+	t.Helper()
+	var out []string
+	for module, raw := range manifests {
+		var m struct {
+			Build struct {
+				Artifacts []struct{ Name, Kind, From string } `json:"artifacts"`
+			} `json:"build"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			t.Fatalf("%s does not parse: %v", module, err)
+		}
+		for _, a := range m.Build.Artifacts {
+			if a.Kind != "image" {
+				continue
+			}
+			clean := filepath.Clean(a.From)
+			bad := a.From == "" || filepath.IsAbs(clean) || clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator))
+			if !bad {
+				info, err := os.Stat(filepath.Join(root, module, clean))
+				bad = err != nil || info.IsDir()
+			}
+			if bad {
+				out = append(out, module+" ("+a.Name+" from "+a.From+")")
+			}
+		}
+	}
+	return out
+}
+
+// Every image a module of this repository declares is built from a Dockerfile in the module's own directory
+// (novox/hq ADR 0487 clause 13). The catalogue's own modules are held to the same by checks/imageplace in mesh-catalog.
+func TestEveryImageArtifactBuildsFromADockerfileInItsOwnModuleDirectory(t *testing.T) {
+	root := filepath.Join("..", "..", "modules")
+	paths, err := filepath.Glob(filepath.Join(root, "*", "module.json"))
+	if err != nil || len(paths) == 0 {
+		t.Fatalf("no module manifests found in this repository's modules: %v", err)
+	}
+	manifests := map[string][]byte{}
+	for _, p := range paths {
+		raw, err := os.ReadFile(p)
+		if err != nil {
+			t.Fatal(err)
+		}
+		manifests[filepath.Base(filepath.Dir(p))] = raw
+	}
+	if got := imagesOutOfPlace(t, root, manifests); len(got) != 0 {
+		t.Errorf("these image artifacts do not build from a Dockerfile in their own module's directory "+
+			"(ADR 0487 clause 13): %v", got)
+	}
+}
+
+// The check fails on each bad case and passes on a good one, so it holds something.
+func TestAnImageWhoseDockerfileIsOutOfPlaceIsFoundAndOneInPlaceIsNot(t *testing.T) {
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, "x", "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for _, f := range []string{"x/Dockerfile", "x/sub/Dockerfile", "outside"} {
+		if err := os.WriteFile(filepath.Join(root, f), nil, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	manifest := func(from string) map[string][]byte {
+		return map[string][]byte{"x": []byte(`{"module":"x","version":"1","build":{"artifacts":[{"name":"server","kind":"image","from":"` + from + `"}]}}`)}
+	}
+	for _, from := range []string{"Dockerfile", "sub/Dockerfile", "./Dockerfile"} {
+		if got := imagesOutOfPlace(t, root, manifest(from)); len(got) != 0 {
+			t.Errorf("from %q: found %v, want none", from, got)
+		}
+	}
+	for _, from := range []string{"", "/etc/Dockerfile", "../outside", "..", "sub/../../outside", "Missing", "sub"} {
+		if got := imagesOutOfPlace(t, root, manifest(from)); len(got) != 1 {
+			t.Errorf("from %q: found %v, want it refused", from, got)
+		}
+	}
+}

internal/ownmanifest/public_issuer_test.go

@@ -11,7 +11,7 @@ import (
 //
 // route-proxy keeps each ACME authority's account and certificates in a directory named after a
 // digest of the directory URL and of the root bundle its `trust` container copies in
-// (examples/route-proxy, forThisAuthority). Until ADR 0226 the URL was rendered from a binding to
+// (modules/route-proxy/cmd/route-proxy, forThisAuthority). Until ADR 0226 the URL was rendered from a binding to
 // `public-acme`'s `acme-ca`, spelled with the port. A URL spelled any other way — even the same
 // authority without `:443` — or a root bundle from another image is a new authority to the proxy:
 // a new account, and every routed name ordered again, on two machines at once, against Let's
@@ -36,8 +36,11 @@ func TestRouteProxyKeepsItsPublicAccountDirectory(t *testing.T) {
 	}
 
 	// As a build would leave it: each artifact a container names resolved to an image. Which image
-	// does not matter to the file checked here.
+	// does not matter to the file checked here. An archive resource carries no image: it unpacks a bundle.
 	for _, res := range m.Resources {
+		if res["type"] == "archive" {
+			continue
+		}
 		if artifact, ok := res["artifact"].(string); ok {
 			delete(res, "artifact")
 			res["image"] = "registry.invalid/route-proxy/" + artifact +
@@ -86,3 +89,57 @@ func TestRouteProxyKeepsItsPublicAccountDirectory(t *testing.T) {
 			"plan for the account (ADR 0226)", trust, trustImage)
 	}
 }
+
+// The proxy's program is mounted into the pinned trust image, not baked into an image (novox/hq ADR 0480 clauses 1,
+// 2 and 4): a Go bundle of the module's own Go module stamped for alpine, unpacked by an archive resource, mounted
+// read-only at /opt/mesh, called through args, and named under restart-on so a new program never leaves the old
+// one running. The container's name, network and logging are what the jail and the routes rely on.
+func TestRouteProxyRunsItsMountedProgramOnTheTrustImage(t *testing.T) {
+	m := catalogueManifest(t, "route-proxy")
+	var bundle *Artifact
+	for i, a := range m.Build.Artifacts {
+		if a.Name == "server" {
+			bundle = &m.Build.Artifacts[i]
+		}
+		if a.Kind == "image" {
+			t.Errorf("artifact %s is an image built from a Dockerfile (ADR 0452 §1)", a.Name)
+		}
+	}
+	if bundle == nil || bundle.Kind != "bundle" || bundle.Language != "go" || bundle.System != "alpine" ||
+		bundle.From != "cmd/route-proxy" || bundle.Binary != "route-proxy" {
+		t.Fatalf("the server artifact is not a Go bundle of cmd/route-proxy stamped for alpine: %+v", bundle)
+	}
+	var archive, server map[string]any
+	for _, r := range m.Resources {
+		switch {
+		case r["type"] == "archive" && r["artifact"] == "server":
+			archive = r
+		case r["id"] == "server":
+			server = r
+		}
+	}
+	if archive == nil || server == nil {
+		t.Fatalf("archive %v or server container %v is missing", archive, server)
+	}
+	if server["artifact"] != "trust" || server["name"] != "route-proxy" || server["network"] != "host" || server["logging"] != "journald" {
+		t.Errorf("the server container moved: %v", server)
+	}
+	mount := archive["path"].(string) + ":/opt/mesh:ro"
+	mounted := false
+	for _, v := range server["volumes"].([]any) {
+		mounted = mounted || v == mount
+	}
+	if !mounted {
+		t.Errorf("the archive is not mounted read-only at /opt/mesh (%s): %v", mount, server["volumes"])
+	}
+	if args, _ := server["args"].([]any); len(args) != 1 || args[0] != "/opt/mesh/route-proxy" {
+		t.Errorf("args are %v, want the mounted program", server["args"])
+	}
+	restarts := false
+	for _, v := range server["restart-on"].([]any) {
+		restarts = restarts || v == archive["id"]
+	}
+	if !restarts {
+		t.Errorf("restart-on %v does not name the archive %v", server["restart-on"], archive["id"])
+	}
+}

internal/testbus/testbus_test.go

@@ -19,18 +19,10 @@ import (
 // bus upgrade moves the catalogue's pin; this then fails in the merge check until the tests' pin moves
 // with it, so the controller is never tested against a bus the mesh no longer runs, or not yet.
 func TestTheBusTheTestsRunIsTheBusTheMeshRuns(t *testing.T) {
-	dockerfile := filepath.Join(beside.Catalogue(t), "nats", "Dockerfile")
-	raw, err := os.ReadFile(dockerfile)
-	if err != nil {
-		t.Fatal(err)
-	}
-	pinned := regexp.MustCompile(`upstream: nats ([0-9.]+)-alpine`).FindSubmatch(raw)
-	if pinned == nil {
-		t.Fatalf("%s says no release its digest is", dockerfile)
-	}
-	if string(pinned[1]) != Version {
-		t.Errorf("the tests run bus %s and the catalogue's bus image is %s: move go.mod's nats-server pin "+
-			"(and `go mod vendor`) with the image", Version, pinned[1])
+	release, from := catalogueBusRelease(t, filepath.Join(beside.Catalogue(t), "nats"))
+	if release != Version {
+		t.Errorf("the tests run bus %s and the catalogue's bus image is %s (%s): move go.mod's nats-server pin "+
+			"(and `go mod vendor`) with the image", Version, release, from)
 	}
 	path := os.Getenv("MESH_FACTS")
 	if path == "" {
@@ -57,3 +49,51 @@ func TestTheBusTheTestsRunIsTheBusTheMeshRuns(t *testing.T) {
 }
 
 // A test's bus is its own: what one test makes, the next never sees.
+
+// catalogueBusRelease is the server release the catalogue's nats module runs, and where it was read. Since
+// ADR 0497 the server is an upstream artifact in the module's manifest (`nats:<release>-alpine@sha256:…`);
+// before it, an image built from the module's Dockerfile, whose `upstream: nats <release>-alpine` line said
+// the release its digest is. The manifest is read first; the Dockerfile only where the manifest names no
+// upstream nats image (a catalogue from before that move, such as the captured copy). Neither is a failure.
+func catalogueBusRelease(t *testing.T, module string) (release, from string) {
+	t.Helper()
+	manifest := filepath.Join(module, "module.json")
+	raw, err := os.ReadFile(manifest)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Build struct {
+			Artifacts []struct {
+				Name string `json:"name"`
+				Kind string `json:"kind"`
+				From string `json:"from"`
+			} `json:"artifacts"`
+		} `json:"build"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatalf("%s: %v", manifest, err)
+	}
+	upstream := regexp.MustCompile(`^(?:[^/]+/)*nats:([0-9]+\.[0-9]+\.[0-9]+)-alpine(?:@sha256:[0-9a-f]{64})?$`)
+	for _, a := range m.Build.Artifacts {
+		if a.Kind != "upstream" || !strings.HasPrefix(a.From[strings.LastIndex(a.From, "/")+1:], "nats:") {
+			continue
+		}
+		pinned := upstream.FindStringSubmatch(a.From)
+		if pinned == nil {
+			t.Fatalf("%s: the upstream artifact %q is %q, which says no release in the form nats:<x.y.z>-alpine",
+				manifest, a.Name, a.From)
+		}
+		return pinned[1], manifest
+	}
+	dockerfile := filepath.Join(module, "Dockerfile")
+	raw, err = os.ReadFile(dockerfile)
+	if err != nil {
+		t.Fatalf("%s names no upstream nats image, and the image built before it is not there either: %v", manifest, err)
+	}
+	pinned := regexp.MustCompile(`upstream: nats ([0-9.]+)-alpine`).FindSubmatch(raw)
+	if pinned == nil {
+		t.Fatalf("%s says no release its digest is", dockerfile)
+	}
+	return string(pinned[1]), dockerfile
+}

modules/build-agent/files/build-agent.env

@@ -6,3 +6,4 @@ MESH_NPM_TOKEN_FILE=/run/mesh/package-registry.secret
 MESH_GENESIS_PACKAGE_REGISTRY=/run/mesh/genesis-package-registry.json
 MESH_WORKSPACE=${dir:workspace}
 MESH_JUDGE_CACHE=${dir:judge-cache}
+MESH_BUILD_CGROUP_PARENT=meshbuild.slice

modules/build-agent/files/meshbuild.slice

@@ -0,0 +1,10 @@
+# Managed by the mesh (module build-agent). Replaced on every push; edit the module's settings instead.
+#
+# Everything a build or check starts on this machine runs in this slice (novox/hq issue 1798): the build
+# agent starts every container with --cgroup-parent=meshbuild.slice. The weights only bind while the machine
+# is busy, so an idle machine still builds at full speed; the memory limits are the part that always binds.
+[Slice]
+CPUWeight=${setting:cpu-weight}
+IOWeight=${setting:io-weight}
+MemoryHigh=${setting:memory-high}
+MemoryMax=${setting:memory-max}

modules/build-agent/manifest_test.go

@@ -187,3 +187,61 @@ func TestTheAgentReadsTheGatesPullKeysAndTodaysBoth(t *testing.T) {
 		}
 	}
 }
+
+// Builds and checks run below the machine's own work (novox/hq issue 1798): the module declares the slice
+// every build container joins with its limits as settings that have defaults, and tells the agent its name.
+func TestTheBuildSliceCarriesTheMachinesLimits(t *testing.T) {
+	raw, err := os.ReadFile("module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Config map[string]struct {
+			Default any `json:"default"`
+		} `json:"config"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	slice, err := os.ReadFile("files/meshbuild.slice")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for key, property := range map[string]string{"cpu-weight": "CPUWeight", "io-weight": "IOWeight", "memory-high": "MemoryHigh", "memory-max": "MemoryMax"} {
+		if c, ok := m.Config[key]; !ok || c.Default == nil {
+			t.Errorf("1798/AC2: setting %s is missing or has no default", key)
+		}
+		if !strings.Contains(string(slice), property+"=${setting:"+key+"}") {
+			t.Errorf("1798/AC2: the slice does not set %s from %s", property, key)
+		}
+	}
+	var placed, running bool
+	for _, r := range read(t).Resources {
+		placed = placed || (r["type"] == "file" && r["path"] == "/etc/systemd/system/meshbuild.slice")
+		running = running || (r["type"] == "service" && r["unit"] == "meshbuild.slice" && r["state"] == "running")
+	}
+	if !placed || !running {
+		t.Errorf("1798/AC2: the slice must be placed (%v) and running (%v)", placed, running)
+	}
+	// 1798/AC3: a dash in a slice's name nests it in the slice named before the dash, and cgroup v2 weights only
+	// compare siblings, so the name has none and the slice sits at the top level beside user.slice.
+	for _, r := range read(t).Resources {
+		if r["type"] == "service" && r["unit"] == "meshbuild.slice" {
+			if strings.Contains(strings.TrimSuffix(r["unit"].(string), ".slice"), "-") {
+				t.Errorf("1798/AC3: slice name %v nests", r["unit"])
+			}
+			// 1798/AC4: a changed limit reaches systemd only if the unit restarts when its file changes.
+			restart, _ := r["restart-on"].([]any)
+			if len(restart) != 1 || restart[0] != "build-slice" {
+				t.Errorf("1798/AC4: the slice unit does not restart on its file: %v", restart)
+			}
+		}
+	}
+	env, err := os.ReadFile("files/build-agent.env")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(env), "MESH_BUILD_CGROUP_PARENT=meshbuild.slice") {
+		t.Error("1798/AC1: the agent is not told the slice's name")
+	}
+}

modules/build-agent/module.json

@@ -2,6 +2,34 @@
   "module": "build-agent",
   "version": "1",
   "slug": "agent",
+  "config": {
+    "cpu-weight": {
+      "type": "number",
+      "description": "The CPU weight of everything a build or check starts on this machine, from 1 to 10000 against 100 for an ordinary service or a login session: under load the builds get their share of that, on an idle machine they take what is free (novox/hq issue 1798). The default 20 is about a sixth of the CPU against one competing workload; a desktop may take 10. Changing it restarts the build slice, which stops every build and check running on that machine at that moment; they fail and must be retried.",
+      "minimum": 1,
+      "maximum": 10000,
+      "default": 20
+    },
+    "io-weight": {
+      "type": "number",
+      "description": "The disk IO weight of everything a build or check starts, from 1 to 10000 against 100 for an ordinary service: the default 10 lets the machine's own work go first (novox/hq issue 1798). Changing it restarts the build slice, which stops every build and check running on that machine at that moment; they fail and must be retried.",
+      "minimum": 1,
+      "maximum": 10000,
+      "default": 10
+    },
+    "memory-high": {
+      "type": "string",
+      "description": "The memory above which builds and checks are slowed and made to give memory back, a percentage of the machine's memory or a size (systemd's MemoryHigh): the default 50% leaves half the machine to what it runs (novox/hq issue 1798). Changing it restarts the build slice, which stops every build and check running on that machine at that moment; they fail and must be retried.",
+      "pattern": "([1-9][0-9]?|100)%|[1-9][0-9]*[KMGT]",
+      "default": "50%"
+    },
+    "memory-max": {
+      "type": "string",
+      "description": "The memory builds and checks together may never exceed, a percentage or a size (systemd's MemoryMax); a build past it is killed by the kernel and fails, so keep it above memory-high: the default 70% (novox/hq issue 1798). Changing it restarts the build slice, which stops every build and check running on that machine at that moment; they fail and must be retried.",
+      "pattern": "([1-9][0-9]?|100)%|[1-9][0-9]*[KMGT]",
+      "default": "70%"
+    }
+  },
   "capabilities": [
     "container-runtime"
   ],
@@ -9,7 +37,12 @@
     {
       "name": "node-build-agent",
       "scope": "node",
-      "serves": ["current", "kill", "pause", "resume"]
+      "serves": [
+        "current",
+        "kill",
+        "pause",
+        "resume"
+      ]
     }
   ],
   "reads": [
@@ -48,7 +81,7 @@
         "id": "judge-cache",
         "path": "${dir:judge-cache}",
         "class": "cache",
-        "why": "the Go cache every merge check's judge is built with and the group judges kept per head; mounted into judge builds only, never into a check's containers (novox/hq ADR 0358 §6)"
+        "why": "the Go cache every merge check's judge is built with and the group judges kept per head; mounted into judge builds only, never into a check's containers (novox/hq ADR 0358 \u00a76)"
       }
     ]
   },
@@ -69,6 +102,23 @@
       "type": "directory",
       "mode": "0700"
     },
+    {
+      "id": "build-slice",
+      "type": "file",
+      "path": "/etc/systemd/system/meshbuild.slice",
+      "mode": "0644",
+      "trusted": false,
+      "template": "files/meshbuild.slice"
+    },
+    {
+      "id": "build-slice-unit",
+      "type": "service",
+      "unit": "meshbuild.slice",
+      "state": "running",
+      "restart-on": [
+        "build-slice"
+      ]
+    },
     {
       "id": "agent-env",
       "type": "file",

modules/route-proxy/Dockerfile

@@ -1,29 +0,0 @@
-ARG ALPINE_BASE=alpine:3.20
-ARG GO_BASE=golang:1.25
-# The route-proxy module's runtime image: the reference reverse proxy compiled into a container.
-#
-# **The proxy source sits beside this module.** The canonical proxy, the contract written as something
-# that runs, lives in this same repository, mesh-controller, at examples/route-proxy (novox/hq 08-connectivity
-# §3), and the repository is the build context (a module lives whole in one repository, novox/hq ADR 0420),
-# so this Dockerfile compiles ./examples/route-proxy from the repository root. The build seat hands it only
-# that program's build source, its import closure, go.mod, go.sum and the vendored packages it uses
-# (novox/hq ADR 0267, the artifact's `compiles`), so a merge elsewhere in the repository does not
-# move this image, and a COPY of anything outside it fails by name.
-#
-#   docker build -f modules/route-proxy/Dockerfile -t mesh-route-proxy:development .
-#
-# The mesh pins the digest of what this produces; the committed module.json carries the placeholder
-# digest every mesh-built image does, replaced at publish.
-FROM ${GO_BASE} AS build
-WORKDIR /src
-COPY go.mod go.sum ./
-RUN go mod download
-COPY . .
-RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -buildvcs=false -ldflags=-buildid= -o /mesh-route-proxy ./examples/route-proxy
-
-# A small runtime with the public CA roots the ACME client needs to reach a real authority, and run
-# as root so it can bind :80 and :443 — the two privileged ports a public front door listens on.
-FROM ${ALPINE_BASE}
-RUN apk add --no-cache ca-certificates
-COPY --from=build /mesh-route-proxy /usr/local/bin/mesh-route-proxy
-ENTRYPOINT ["/usr/local/bin/mesh-route-proxy"]

modules/route-proxy/README.md

@@ -45,15 +45,15 @@ pinned image is not moved without a decision; mesh-controller's
 
 ## How it ships the Go proxy
 
-The proxy is a Go program, unlike the TypeScript tool-runtime modules. Its source sits in this same
-repository, mesh-controller, at `examples/route-proxy`, the contract written as something that runs. This
-module ships the packaging: a multi-stage [`Dockerfile`](Dockerfile) whose build context is the repository
-root and which compiles `./examples/route-proxy` into `mesh-route-proxy`. The committed `module.json` carries the
-placeholder digest every mesh-built image does (`@sha256:0000…`); the mesh pins the real digest at
-publish.
+The proxy is a Go program, unlike the TypeScript tool-runtime modules. Its source sits in this module, at
+`cmd/route-proxy`, in the module's own Go module (`go.mod`, with a `vendor/` directory), the contract written as
+something that runs. No image is built for it (novox/hq ADR 0480): the `server` artifact is a Go bundle compiled
+for alpine, an `archive` resource unpacks it onto the machine, and the `route-proxy` container runs the pinned
+`trust` image (the same alpine digest whose system roots the public account directory is named after) with the
+archive mounted read-only at `/opt/mesh` and `/opt/mesh/route-proxy` as its program. A new build of the program
+restarts the container, because the archive is in its `restart-on`.
 
-In the lab, `mesh-lab/scripts/build-route-proxy-image.sh` builds this into the local daemon as
-`mesh-route-proxy:development`, and a scenario stocks it and serves it by digest.
+In the lab, a scenario stocks the same alpine image and serves it by digest.
 
 ## Certificates, and the endpoint (resolves 04-ISSUES/004)
 

modules/route-proxy/cmd/route-provider/provider_test.go

@@ -77,7 +77,8 @@ func TestAConsumerOfARouteIsToldItsNamesFromItsPlanEntry(t *testing.T) {
 // route-proxy's own files and resources stay as they were (issue 792): the module answers its route through the
 // helper but is not marked moved, so its acme.env, its broker secret and its containers are composed as today and
 // the public ingress does not change. Everything of the manifest but its build, what it provides and the state it
-// keeps is pinned by this digest; changing the ingress means changing it here, on purpose.
+// keeps is pinned by this digest; changing the ingress means changing it here, on purpose. Re-pinned in R4d (novox/hq
+// ADR 0480): the program is an archive mounted into the trust image, the container and its files are otherwise as before.
 func TestRouteProxyIsNotMovedAndKeepsItsOwnFiles(t *testing.T) {
 	raw, err := os.ReadFile("../../module.json")
 	if err != nil {
@@ -102,7 +103,7 @@ func TestRouteProxyIsNotMovedAndKeepsItsOwnFiles(t *testing.T) {
 		t.Fatal(err)
 	}
 	sum := sha256.Sum256(pinned)
-	if got := hex.EncodeToString(sum[:]); got != "57a39de0943d8b33b9db6cb998ce97f8793602cca6cdfa5849c1c392390454a3" {
+	if got := hex.EncodeToString(sum[:]); got != "85cb955e5a4b2d8826f50aa76433064a576e8b15b71537032eb93c7388c0ee28" {
 		t.Fatalf("route-proxy's own manifest changed: digest %s", got)
 	}
 	// The two acme templates are pinned the same way (issue 849): they are what the proxy's certificates are asked

modules/route-proxy/cmd/route-proxy/bus.go

@@ -4,14 +4,14 @@ import (
 	"encoding/json"
 	"fmt"
 	"log"
-	"os"
 	"strings"
 	"sync/atomic"
 	"time"
 
 	"github.com/nats-io/nats.go"
 
-	"github.com/novox/mesh-controller/internal/broker"
+	"git.novox.be/novox/mesh-sdk/go/membership"
+	"git.novox.be/novox/mesh-sdk/go/process"
 )
 
 // What the mesh issued this proxy, read on the bus (novox/hq ADR 0160, ADR 0167).
@@ -21,16 +21,6 @@ import (
 // network, which is who may be served an internal name. Read once at connect and followed, so a
 // route added or a machine joining reaches a running proxy without a restart.
 
-// credential is the bus account the mesh delivered as this module's own secret named broker.
-type credential struct {
-	URL         string `json:"url"`
-	Fingerprint string `json:"fingerprint"`
-	Node        string `json:"node"`
-	Module      string `json:"module"`
-	User        string `json:"user"`
-	Password    string `json:"password"`
-}
-
 // followMembership connects with the credential in path and applies every membership the mesh
 // issues this proxy. It retries the first connection for as long as it takes: a proxy that started
 // before the bus keeps serving the file, and takes the bus when it answers.
@@ -46,60 +36,23 @@ func followMembership(path string, held *table, fromBus *atomic.Bool) {
 }
 
 func followOnce(path string, held *table, fromBus *atomic.Bool) error {
-	raw, err := os.ReadFile(path)
+	account, err := process.ReadAccount(path)
 	if err != nil {
 		return err
 	}
-	var cred credential
-	if err := json.Unmarshal(raw, &cred); err != nil {
-		return fmt.Errorf("the broker credential is not one: %w", err)
-	}
-	if cred.Node == "" || cred.Module == "" {
-		return fmt.Errorf("the broker credential names no node or module, so it has no membership")
-	}
-
-	opts := []nats.Option{
-		nats.Name(cred.Node + "." + cred.Module),
-		nats.UserInfo(cred.User, cred.Password),
-		// Its own inbox, and nothing wider: every principal is granted `_INBOX.<its user>.>` alone.
-		nats.CustomInboxPrefix("_INBOX." + cred.User),
-		// The bus being restarted is an upgrade, not a reason to stop following.
-		nats.MaxReconnects(-1),
-	}
-	if strings.TrimSpace(cred.Fingerprint) != "" {
-		opts = append(opts, nats.Secure(broker.PinnedToFingerprint(cred.Fingerprint)))
-	}
-	conn, err := nats.Connect(cred.URL, opts...)
+	conn, err := process.Connect(account, nats.Name(account.Node+"."+account.Module))
 	if err != nil {
-		return fmt.Errorf("connecting to the bus at %s: %w", broker.BareAddress(cred.URL), err)
+		return fmt.Errorf("connecting to the bus at %s: %w", membership.BareAddress(account.URL), err)
 	}
-
-	subject := broker.MembershipSubject(cred.Node, cred.Module)
-	apply := func(body []byte) {
-		var issued broker.Membership
-		if err := json.Unmarshal(body, &issued); err != nil {
-			log.Printf("a membership arrived that is not one: %v", err)
-			return
-		}
+	subject := membership.Subject(account.Node, account.Module)
+	err = conn.FollowMembership(func(issued membership.Membership) {
 		if took := applyMembership(issued, held); took && !fromBus.Swap(true) {
 			log.Printf("routes now come from this proxy's membership on %s", subject)
 		}
-	}
-
-	// Followed first, read second: an issue landing between the two is applied, not missed.
-	if _, err := conn.Subscribe(subject, func(m *nats.Msg) { apply(m.Data) }); err != nil {
+	}, func(err error) { log.Print(err) })
+	if err != nil {
 		conn.Close()
-		return fmt.Errorf("cannot follow %s: %w", subject, err)
-	}
-	// The subject-addressed direct get: the one request this account may make of the stream.
-	got, err := conn.Request("$JS.API.DIRECT.GET."+broker.AssignmentsStream+"."+subject, nil, 5*time.Second)
-	switch {
-	case err != nil:
-		log.Printf("cannot read the membership issued on %s yet (%v); following it", subject, err)
-	case got.Header.Get("Status") != "" || len(got.Data) == 0:
-		log.Printf("no membership issued on %s yet; serving the file until one is", subject)
-	default:
-		apply(got.Data)
+		return err
 	}
 	return nil
 }
@@ -108,7 +61,7 @@ func followOnce(path string, held *table, fromBus *atomic.Bool) error {
 //
 // A membership with no routes in it is one from a controller older than ADR 0167, and the file stays
 // the source rather than every route being withdrawn because a field was absent.
-func applyMembership(issued broker.Membership, held *table) bool {
+func applyMembership(issued membership.Membership, held *table) bool {
 	raw, carries := issued.Receives["route"]
 	if !carries {
 		return false

modules/route-proxy/cmd/route-proxy/reach_test.go

@@ -12,7 +12,7 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/novox/mesh-controller/internal/broker"
+	"git.novox.be/novox/mesh-sdk/go/membership"
 )
 
 // behind is a workload the proxy can send to, and a table routing one public name and one
@@ -169,7 +169,7 @@ func TestTheMeshIsReadAsAddressesAndRanges(t *testing.T) {
 // machines it names (novox/hq ADR 0167).
 func TestAMembershipIsServedAsIssued(t *testing.T) {
 	held := newTable()
-	took := applyMembership(broker.Membership{
+	took := applyMembership(membership.Membership{
 		Receives: map[string]json.RawMessage{"route": json.RawMessage(`[
 		  {"from":"admin","node":"anchor","at":"anchor.internal",
 		   "values":{"internal-name":"admin.anchor.internal","port":8080}}]`)},
@@ -191,13 +191,13 @@ func TestAMembershipIsServedAsIssued(t *testing.T) {
 func TestAMembershipWithoutRoutesLeavesTheFileServing(t *testing.T) {
 	held := behind(t, "10.10.0.7")
 	before := held.names()
-	if applyMembership(broker.Membership{Mesh: []string{"10.10.0.7"}}, held) {
+	if applyMembership(membership.Membership{Mesh: []string{"10.10.0.7"}}, held) {
 		t.Error("a membership without routes was taken as the source of routes")
 	}
 	if got := held.names(); strings.Join(got, ",") != strings.Join(before, ",") {
 		t.Errorf("a membership without routes changed what is served: %v, was %v", got, before)
 	}
-	if applyMembership(broker.Membership{
+	if applyMembership(membership.Membership{
 		Receives: map[string]json.RawMessage{"route": json.RawMessage(`[]`)},
 		Mesh:     []string{"not-an-address"},
 	}, held) {

modules/route-proxy/go.mod

@@ -2,4 +2,17 @@ module route-proxy
 
 go 1.26.0
 
-require git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021114014-66e8fdaa62e2
+require (
+	git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261022075101-c61212eba77c
+	github.com/nats-io/nats.go v1.54.0
+	golang.org/x/crypto v0.57.0
+)
+
+require (
+	github.com/klauspost/compress v1.20.0 // indirect
+	github.com/nats-io/nkeys v0.4.16 // indirect
+	github.com/nats-io/nuid v1.0.1 // indirect
+	golang.org/x/net v0.58.0 // indirect
+	golang.org/x/sys v0.48.0 // indirect
+	golang.org/x/text v0.42.0 // indirect
+)

modules/route-proxy/go.sum

@@ -1,2 +1,30 @@
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021114014-66e8fdaa62e2 h1:Cdl5N56QPfmFBoLHrDfvvyc5Q+PUnTjf3fgYD7imcco=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021114014-66e8fdaa62e2/go.mod h1:ouERNpZizzwZ0HLEtAypsY9FR20FyUgUYRni6J7kVCY=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261022075101-c61212eba77c h1:YdSbkI42rlVmClybH8BS717ut0vouKIMavO691fpdps=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261022075101-c61212eba77c/go.mod h1:ouERNpZizzwZ0HLEtAypsY9FR20FyUgUYRni6J7kVCY=
+github.com/antithesishq/antithesis-sdk-go v0.7.0-default-no-op h1:Z/MZK75wC/NSrkgqeNIa7jexam9uWzhLmFTSCPI/kn0=
+github.com/antithesishq/antithesis-sdk-go v0.7.0-default-no-op/go.mod h1:FQyySiasQQM8735Ddel3MRojmy4dA1IqCeyJ5jmPMbI=
+github.com/google/go-tpm v0.9.8 h1:slArAR9Ft+1ybZu0lBwpSmpwhRXaa85hWtMinMyRAWo=
+github.com/google/go-tpm v0.9.8/go.mod h1:h9jEsEECg7gtLis0upRBQU+GhYVH6jMjrFxI8u6bVUY=
+github.com/klauspost/compress v1.20.0 h1:a3C1ke2ohxFymNlb2HWAHjDeKCI90scRskErZkR0ezA=
+github.com/klauspost/compress v1.20.0/go.mod h1:LUdAzn7YLVvxLpc7y3V1m40wESHTgc1422pwwBSKYuI=
+github.com/minio/highwayhash v1.0.4 h1:asJizugGgchQod2ja9NJlGOWq4s7KsAWr5XUc9Clgl4=
+github.com/minio/highwayhash v1.0.4/go.mod h1:GGYsuwP/fPD6Y9hMiXuapVvlIUEhFhMTh0rxU3ik1LQ=
+github.com/nats-io/jwt/v2 v2.8.1 h1:V0xpGuD/N8Mi+fQNDynXohVvp7ZztevW5io8CUWlPmU=
+github.com/nats-io/jwt/v2 v2.8.1/go.mod h1:nWnOEEiVMiKHQpnAy4eXlizVEtSfzacZ1Q43LIRavZg=
+github.com/nats-io/nats-server/v2 v2.11.17 h1:GKEghcFK6A+aFx11Yf1LjgLC3txAwvyhnYzhBIQZA8I=
+github.com/nats-io/nats-server/v2 v2.11.17/go.mod h1:B1sFVz4StNosQ903ak4N1G01Fl/9f8e06mXpFIE2K24=
+github.com/nats-io/nats.go v1.54.0 h1:vsXoOxjHp/GmPUN+EcI7uOf/uB+iAP+kEsAFNQN0yzA=
+github.com/nats-io/nats.go v1.54.0/go.mod h1:y+DZoD1oBOYfZTU681eTUiUjI0vbqYGixNVFHcjHJ0k=
+github.com/nats-io/nkeys v0.4.16 h1:rd5oAuLOb8mnAycB0xleuEBNS1pVVnN0fv/FF34Eypg=
+github.com/nats-io/nkeys v0.4.16/go.mod h1:llLgWoI0o4z/Q57q2R1kHfmocyhGV6VG/U18Glg1Afs=
+github.com/nats-io/nuid v1.0.1 h1:5iA8DT8V7q8WK2EScv2padNa/rTESc1KdnPw4TC2paw=
+github.com/nats-io/nuid v1.0.1/go.mod h1:19wcPz3Ph3q0Jbyiqsd0kePYG7A95tJPxeL+1OSON2c=
+golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
+golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
+golang.org/x/net v0.58.0 h1:ynWG7rqYi4ccpTEuPZ2QGWHktVEM9DMCj9yzDE0Q7To=
+golang.org/x/net v0.58.0/go.mod h1:YwCddHnFlT7eLQqVprV19OnhLGtc5xOKgE0RyqgfWAU=
+golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
+golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
+golang.org/x/text v0.42.0 h1:JbOZXgfeCPU9gacVtYliJqOhD+zhrEqK4LfdpmlUZqI=
+golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E=
+golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
+golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=

modules/route-proxy/module.json

@@ -149,11 +149,18 @@
         "internal-acme-env"
       ]
     },
+    {
+      "id": "program-route-proxy",
+      "type": "archive",
+      "path": "${dir:state}/route-proxy",
+      "artifact": "server",
+      "unknown": "program"
+    },
     {
       "id": "server",
       "type": "container",
       "name": "route-proxy",
-      "artifact": "server",
+      "artifact": "trust",
       "network": "host",
       "env-file": [
         "${dir:state}/acme.env",
@@ -163,7 +170,8 @@
         "${dir:routes-dir}:/routes:ro",
         "${dir:acme-cache}:/acme",
         "${dir:ca-dir}:/ca:ro",
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro"
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:state}/route-proxy:/opt/mesh:ro"
       ],
       "env": {
         "ROUTES": "/routes/mesh.json",
@@ -174,11 +182,15 @@
         "INTERNAL_ACME_CA_BUNDLE": "/ca/internal-root.crt",
         "MESH_BROKER_FILE": "/run/secrets/broker"
       },
+      "args": [
+        "/opt/mesh/route-proxy"
+      ],
       "restart-on": [
         "trust",
         "acme-env",
         "internal-trust",
-        "internal-acme-env"
+        "internal-acme-env",
+        "program-route-proxy"
       ],
       "logging": "journald",
       "health": {
@@ -195,14 +207,11 @@
     "artifacts": [
       {
         "name": "server",
-        "kind": "image",
-        "from": "Dockerfile",
-        "compiles": "examples/route-proxy",
-        "context": {
-          "seat": "git",
-          "repository": "novox/mesh-controller",
-          "ref": "main"
-        }
+        "kind": "bundle",
+        "language": "go",
+        "system": "alpine",
+        "from": "cmd/route-proxy",
+        "binary": "route-proxy"
       },
       {
         "name": "trust",
@@ -225,16 +234,6 @@
         "kind": "archive",
         "from": "files"
       }
-    ],
-    "on": [
-      {
-        "arg": "GO_BASE",
-        "image": "golang@sha256:6c2a5538f964f1c82f97ad14988bf05de100d922d159d0e398b54c7b0ca0c6c9"
-      },
-      {
-        "arg": "ALPINE_BASE",
-        "image": "alpine@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc"
-      }
     ]
   },
   "jails": [

modules/route-proxy/vendor/git.novox.be/novox/mesh-sdk/go/membership/membership.go

@@ -0,0 +1,165 @@
+// Package membership is what the mesh issues an assignment to serve and to reach (novox/hq ADR 0160), as a
+// process reads it from the bus: the Membership shape, the one subject it is published on, the stream that
+// holds it, and the bus address helpers a reader needs. The controller composes it and the route proxy reads
+// it; both use this one definition, so there is no second copy to drift (novox/hq issue 1633).
+package membership
+
+import (
+	"encoding/json"
+	"strings"
+)
+
+// AssignmentsStream holds every assignment's membership, the newest per subject.
+const AssignmentsStream = "ASSIGNMENTS"
+
+// Subject is the one address a runtime derives for itself: where its own membership is published, from
+// the two names its credential carries. Everything else is in the membership.
+func Subject(node, module string) string {
+	return "mesh.assignment." + node + "." + module
+}
+
+// DirectGetSubject is the subject-addressed direct get of a membership from its stream: the one request an
+// account may make of the stream.
+func DirectGetSubject(node, module string) string {
+	return "$JS.API.DIRECT.GET." + AssignmentsStream + "." + Subject(node, module)
+}
+
+// Membership is one assignment's subjects: what this instance of a module on this machine serves,
+// and what it may reach.
+type Membership struct {
+	Node   string `json:"node"`
+	Module string `json:"module"`
+	// Serves is every address a tool of this instance answers on. `{tool}` stands for the tool's
+	// own name. An address with a queue is shared with the module's other instances.
+	Serves []Served `json:"serves"`
+	// Seats is every verb of a seat this instance holds, at the subject the seat's callers use.
+	Seats []SeatServed `json:"seats,omitempty"`
+	// Emits is where an event of this module lands; `{event}` stands for the event's name.
+	Emits string `json:"emits"`
+	// Reaches is each tool this module may call, `<module>.<tool>`, to the subjects that reach it.
+	Reaches map[string][]string `json:"reaches,omitempty"`
+	// Tools is where this instance answers what it serves.
+	Tools string `json:"tools"`
+	// Receives is what this assignment is given for each requirement it receives, by requirement (novox/hq
+	// ADR 0167): kept as JSON because the catalogue owns the shape of a contribution.
+	Receives map[string]json.RawMessage `json:"receives,omitempty"`
+	// Mesh is every machine's address on the private network (novox/hq ADR 0167).
+	Mesh []string `json:"mesh,omitempty"`
+	// State is every bucket this module's code may reach, and whether it may write it (novox/hq ADR 0201).
+	State []StateIssued `json:"state,omitempty"`
+	// Logs is every log this module's code may reach (novox/hq ADR 0297).
+	Logs []LogIssued `json:"logs,omitempty"`
+	// SeatTraffic is what this module's code may submit, say, hear, take, ask, answer and read on seats
+	// that name their caller or their kind (novox/hq ADR 0259 §3).
+	SeatTraffic *SeatTraffic `json:"seat-traffic,omitempty"`
+	// Streams are this module's own streams, Hears the module streams it hears (novox/hq ADR 0363).
+	Streams []StreamIssued `json:"streams,omitempty"`
+	Hears   []HeardIssued  `json:"hears,omitempty"`
+	// Waits are the event families a session may wait on through the mesh MCP server (novox/hq ADR 0367 §2).
+	Waits []WaitIssued `json:"waits,omitempty"`
+}
+
+// Served is one address a tool is answered on.
+type Served struct {
+	Subject string `json:"subject"`
+	Queue   string `json:"queue,omitempty"`
+}
+
+// SeatServed is one verb of a held seat, where its callers ask.
+type SeatServed struct {
+	Seat    string `json:"seat"`
+	Verb    string `json:"verb"`
+	Subject string `json:"subject"`
+}
+
+// StateIssued is one bucket an assignment may reach, by the name its module uses for it (novox/hq ADR 0201).
+// Key, when set, is the one key it may reach (novox/hq ADR 0260): this machine's.
+type StateIssued struct {
+	Name   string `json:"name"`
+	Bucket string `json:"bucket"`
+	Writes bool   `json:"writes,omitempty"`
+	Key    string `json:"key,omitempty"`
+}
+
+// LogIssued is one log an assignment may reach, by the name its module uses for it (novox/hq ADR 0297).
+type LogIssued struct {
+	Name    string `json:"name"`
+	Stream  string `json:"stream"`
+	Subject string `json:"subject"`
+	Writes  bool   `json:"writes"`
+}
+
+// Worker is one durable consumer a holder pulls a seat's work from.
+type Worker struct {
+	Stream   string
+	Consumer string
+	Filter   string
+}
+
+// SeatTraffic is one module's seat traffic beyond tools. Publish and Subscribe are subject patterns, in the
+// server's wildcards.
+type SeatTraffic struct {
+	Publish   []string   `json:"publish,omitempty"`
+	Subscribe []string   `json:"subscribe,omitempty"`
+	Answers   []string   `json:"answers,omitempty"`
+	Workers   []Worker   `json:"workers,omitempty"`
+	Records   []string   `json:"records,omitempty"`
+	Kinds     []KindHeld `json:"kinds,omitempty"`
+}
+
+// KindHeld is one kind of a kinded bench and who holds it.
+type KindHeld struct {
+	Seat         string   `json:"seat"`
+	Kind         string   `json:"kind"`
+	Module       string   `json:"module"`
+	Node         string   `json:"node"`
+	Capabilities []string `json:"capabilities,omitempty"`
+}
+
+// StreamIssued is one of a module's own streams as its membership names it (ADR 0363 §2).
+type StreamIssued struct {
+	Stream  string   `json:"stream"`
+	Events  []string `json:"events"`
+	Subject string   `json:"subject"`
+}
+
+// HeardIssued is one module stream an assignment hears (ADR 0363 §8).
+type HeardIssued struct {
+	Stream   string `json:"stream"`
+	Consumer string `json:"consumer"`
+}
+
+// WaitIssued is one family as a membership issues it: the name a session asks for, and its subject.
+type WaitIssued struct {
+	Event   string `json:"event"`
+	Subject string `json:"subject"`
+}
+
+// CredentialIn reads the credential out of a bus address, `[scheme://]user:password@host:port`, splitting on
+// the last at-sign so a password containing one stays whole, and returns the address without it.
+func CredentialIn(address string) (user, password, bare string) {
+	at := strings.LastIndex(address, "@")
+	if at < 0 {
+		return "", "", address
+	}
+	scheme := ""
+	rest := address[:at]
+	if i := strings.Index(rest, "://"); i >= 0 {
+		scheme, rest = rest[:i+3], rest[i+3:]
+	}
+	user, password, _ = strings.Cut(rest, ":")
+	return user, password, scheme + address[at+1:]
+}
+
+// BareAddress is a bus address with any credential stripped, for something that only needs to know
+// whether a server is answering there.
+func BareAddress(address string) string {
+	_, _, bare := CredentialIn(address)
+	if bare == "" {
+		return address
+	}
+	if strings.Contains(bare, "://") {
+		return bare
+	}
+	return "nats://" + bare
+}

modules/route-proxy/vendor/git.novox.be/novox/mesh-sdk/go/process/account.go

@@ -0,0 +1,54 @@
+// Package process is a module's own process's connection to the bus (novox/hq ADR 0436 clause 4): it reads
+// the account the controller delivers, connects as it with its pinned fingerprint and its inbox prefix, and
+// offers emitting an event, the module's states with compare-and-set, consuming a work queue, reading the
+// router's records of the module's own asks, and calling a tool or verb — each only as the account's grants
+// allow. It offers no Serve and no way to serve a tool: a process never answers a call. A sibling of stdio,
+// which it imports only for stdio's pure types (ErrChanged, CodeChanged, StateEntry, EmitOptions); it never
+// touches stdio's current, channel or live(), which stay the bundle's own way to the bus.
+package process
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+)
+
+// Account is a process's own bus account, exactly as the controller delivers it as the module's own secret
+// broker-<process id> (mesh-controller cmd/mesh-controller/modules.go issueProcess, heldProcessAccount, and
+// issueWith for a module's own broker account, which also carries claims). A process account carries no
+// claims at all; this type reads either file without error.
+type Account struct {
+	URL         string `json:"url"`
+	Fingerprint string `json:"fingerprint,omitempty"`
+	Node        string `json:"node"`
+	Module      string `json:"module"`
+	User        string `json:"user"`
+	Password    string `json:"password"`
+	// Claims rides on a module's own broker account only; a process holds no seat, so its own account
+	// carries none (novox/hq ADR 0436 §2, §3). Kept raw: this package never reads it.
+	Claims json.RawMessage `json:"claims,omitempty"`
+}
+
+// InboxPrefix is this account's own inbox, and nothing wider: `_INBOX.<user>`.
+func (a Account) InboxPrefix() string { return "_INBOX." + a.User }
+
+// ReadAccount reads and validates the account file the controller delivers: it refuses a file missing url,
+// user or password, naming the field — never the password, which does not appear in an error.
+func ReadAccount(path string) (Account, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return Account{}, fmt.Errorf("reading the process account at %s: %w", path, err)
+	}
+	var a Account
+	if err := json.Unmarshal(data, &a); err != nil {
+		return Account{}, fmt.Errorf("the process account at %s is not JSON: %w", path, err)
+	}
+	for _, f := range []struct{ name, value string }{
+		{"url", a.URL}, {"user", a.User}, {"password", a.Password},
+	} {
+		if f.value == "" {
+			return Account{}, fmt.Errorf("the process account at %s has no %s", path, f.name)
+		}
+	}
+	return a, nil
+}

modules/route-proxy/vendor/git.novox.be/novox/mesh-sdk/go/process/asks.go

@@ -0,0 +1,68 @@
+package process
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// Ask reads the router's record of one of this process's module's own asks, under its own module and no
+// other's (novox/hq ADR 0436 clause 4, ADR 0259 §3): by direct get on bucket, the same subject the tool
+// runner reads (mesh-tools node-tools/internal/bus/seat.go ~300-345):
+//
+//	$JS.API.DIRECT.GET.KV_<bucket>.$KV.<bucket>.<module>.<id>
+//
+// bucket is the router's records bucket as the caller's own manifest names it (operator-channel's is
+// messenger_asks in the controller's own test fixtures) — never hard-coded to one bucket here, since a
+// process may read records of more than one seat's router. A missing, deleted or purged key is nil, not
+// an error.
+func (c *Conn) Ask(bucket, id string) (*stdio.StateEntry, error) {
+	if err := checkAskID(id); err != nil {
+		return nil, err
+	}
+	subject := "$JS.API.DIRECT.GET.KV_" + bucket + ".$KV." + bucket + "." + c.account.Module + "." + id
+	ctx, cancel := context.WithTimeout(context.Background(), stateTimeout)
+	defer cancel()
+	reply, err := c.nc.RequestWithContext(ctx, subject, nil)
+	if err != nil {
+		return nil, fmt.Errorf("reading %s's ask %s from %s: %w", c.account.Module, id, bucket, err)
+	}
+	if status := reply.Header.Get("Status"); status == "404" {
+		return nil, nil
+	} else if status != "" {
+		return nil, fmt.Errorf("the record %s.%s could not be read: %s %s", c.account.Module, id, status,
+			reply.Header.Get("Description"))
+	}
+	if op := reply.Header.Get("KV-Operation"); op == "DEL" || op == "PURGE" {
+		return nil, nil
+	}
+	var revision uint64
+	if _, err := fmt.Sscan(reply.Header.Get("Nats-Sequence"), &revision); err != nil {
+		return nil, fmt.Errorf("the record %s.%s carries no readable revision: %w", c.account.Module, id, err)
+	}
+	return &stdio.StateEntry{Key: c.account.Module + "." + id, Value: askValueOf(reply.Data), Revision: revision}, nil
+}
+
+// checkAskID refuses an id holding a dot or a wildcard before anything is sent: either would name a
+// different key under the direct-get subject's own dot-joined path, never this one (novox/hq issue 1189
+// AC2).
+func checkAskID(id string) error {
+	if id == "" || strings.ContainsAny(id, ".*>") {
+		return fmt.Errorf("%q is not an ask id: an ask id holds no dot and no wildcard, naming one key and "+
+			"no other", id)
+	}
+	return nil
+}
+
+// askValueOf is a record's raw bytes as JSON, quoting them when they are not already valid JSON
+// (mesh-tools node-tools/internal/bus/state.go:351-357, valueOf).
+func askValueOf(raw []byte) json.RawMessage {
+	if len(raw) == 0 || !json.Valid(raw) {
+		b, _ := json.Marshal(string(raw))
+		return b
+	}
+	return json.RawMessage(append([]byte(nil), raw...))
+}

modules/route-proxy/vendor/git.novox.be/novox/mesh-sdk/go/process/call.go

@@ -0,0 +1,122 @@
+package process
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/nats-io/nats.go"
+)
+
+// CallTimeout bounds a call to a tool or a seat verb (mesh-tools node-tools/internal/bus/bus.go:35,
+// RequestTimeout): what a module already expects.
+var CallTimeout = 30 * time.Second
+
+// Call invokes a tool or a seat verb as this process's own account (novox/hq ADR 0436 clause 4), on the
+// caller-named subject, falling back to the subject that names no caller when nothing answers it —
+// exactly the provisioner client's own pattern (mesh-catalog modules/mesh-provisioner-client/cmd/
+// mesh-provisioner-client/secrets.go:59-61, 93-97, 119, 125-133). key is "seat:<seat>.<verb>" for a seat's
+// verb, or "<module>.<tool>" for a module's own tool, as a process's bus.invokes names it. The reply is
+// {result, error, node} (mesh-tools node-tools/internal/bus/bus.go answerOf); a non-empty error is the
+// call's failure. It offers no way to answer a call — a process reaches the bus only as itself, and
+// never serves anything.
+func (c *Conn) Call(key string, body any) (json.RawMessage, error) {
+	called, fallback, err := callSubjects(key, c.callerToken())
+	if err != nil {
+		return nil, err
+	}
+	return c.callOn(called, fallback, body)
+}
+
+// CallOn is Call to the tool or seat verb of one named machine (novox/hq ADR 0469 §3; issue 1470): the tool
+// runner of that node alone answers, on mesh.mod.<module>.call.<tool>.<node>.<token> (a seat verb:
+// mesh.seat.<seat>.call.<verb>.<node>.<token>), falling back to the subject that names no caller
+// (mesh-tools node-tools/internal/bus/caller.go:15-19). node is one subject token: an empty one, or one
+// holding '.', '*', '>' or white space, is refused before anything is published.
+func (c *Conn) CallOn(node, key string, body any) (json.RawMessage, error) {
+	if err := checkNode(node); err != nil {
+		return nil, err
+	}
+	called, fallback, err := callSubjectsOn(key, node, c.callerToken())
+	if err != nil {
+		return nil, err
+	}
+	return c.callOn(called, fallback, body)
+}
+
+func (c *Conn) callOn(called, fallback string, body any) (json.RawMessage, error) {
+	data, err := json.Marshal(body)
+	if err != nil {
+		return nil, err
+	}
+	result, err := c.request(called, data)
+	if errors.Is(err, nats.ErrNoResponders) {
+		result, err = c.request(fallback, data)
+	}
+	return result, err
+}
+
+// callerToken is this account's user name as the last token of a call it publishes, each dot written ~
+// (mesh-tools node-tools/internal/bus/caller.go:43, CallerToken).
+func (c *Conn) callerToken() string { return strings.ReplaceAll(c.account.User, ".", "~") }
+
+// callSubjects is the caller-named subject key is called on, and its plain fallback (mesh-tools
+// node-tools/internal/bus/caller.go CalledSubject, toolShape, calledPattern).
+func callSubjects(key, token string) (called, fallback string, err error) {
+	return callSubjectsOn(key, "", token)
+}
+
+// checkNode refuses a node name that is not one subject token.
+func checkNode(node string) error {
+	if node == "" || strings.ContainsAny(node, ".*> \t\r\n") {
+		return fmt.Errorf("%q is not a node name (one subject token: no '.', '*', '>' or space)", node)
+	}
+	return nil
+}
+
+// callSubjectsOn is callSubjects for one named node ("" names none): the node is a token between the tool and
+// the caller on the called subject, and the last one of the fallback.
+func callSubjectsOn(key, node, token string) (called, fallback string, err error) {
+	at := ""
+	if node != "" {
+		at = "." + node
+	}
+	if rest, ok := strings.CutPrefix(key, "seat:"); ok {
+		seat, verb, ok := strings.Cut(rest, ".")
+		if !ok || seat == "" || verb == "" {
+			return "", "", fmt.Errorf("%q names no seat and verb (seat:<seat>.<verb>)", key)
+		}
+		return "mesh.seat." + seat + ".call." + verb + at + "." + token, "mesh.seat." + seat + ".tool." + verb + at, nil
+	}
+	module, tool, ok := strings.Cut(key, ".")
+	if !ok || module == "" || tool == "" {
+		return "", "", fmt.Errorf("%q is not <module>.<tool>, and does not start seat:<seat>.<verb>", key)
+	}
+	return "mesh.mod." + module + ".call." + tool + at + "." + token, "mesh.mod." + module + ".tool." + tool + at, nil
+}
+
+// request asks one subject once and reads its reply ({result, error, node}); a reply naming an error is
+// the call's failure, not a transport one.
+func (c *Conn) request(subject string, data []byte) (json.RawMessage, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), CallTimeout)
+	defer cancel()
+	msg, err := c.nc.RequestWithContext(ctx, subject, data)
+	if err != nil {
+		return nil, err
+	}
+	var r struct {
+		Result json.RawMessage `json:"result"`
+		Error  string          `json:"error"`
+		Node   string          `json:"node"`
+	}
+	if err := json.Unmarshal(msg.Data, &r); err != nil {
+		return nil, fmt.Errorf("%s answered something that is not a seat's answer: %w", subject, err)
+	}
+	if r.Error != "" {
+		return nil, errors.New(r.Error)
+	}
+	return r.Result, nil
+}

modules/route-proxy/vendor/git.novox.be/novox/mesh-sdk/go/process/conn.go

@@ -0,0 +1,164 @@
+package process
+
+import (
+	"context"
+	"crypto/sha256"
+	"crypto/tls"
+	"crypto/x509"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"regexp"
+	"sync"
+
+	"github.com/nats-io/nats.go"
+)
+
+// Conn is one process's own connection to the bus (novox/hq ADR 0436 clause 4): dialled with the account
+// the controller delivered, pinned to its fingerprint, on its own inbox prefix. It offers no Serve and no
+// way to serve a tool — a process reaches the bus only as itself, and never answers a call.
+type Conn struct {
+	nc      *nats.Conn
+	account Account
+
+	mu      sync.Mutex
+	next    uint64
+	pending map[string]map[uint64]context.CancelCauseFunc
+}
+
+// errPermissionRefused marks a context cancelled because the bus refused this account's publish of the
+// subject a pending call was waiting an answer on: a denied publish is refused only as an async protocol
+// error with no reply (mesh-tools node-tools/internal/bus/caller.go publishRefused), so without this a
+// call would wait out its whole timeout instead of failing at once.
+var errPermissionRefused = errors.New("the bus refused this account's publish")
+
+// refusedPublish reads the subject out of the bus's "-ERR 'Permissions Violation for Publish to
+// "<subject>"'" (mesh-tools node-tools/internal/bus/caller.go's own regexp).
+var refusedPublish = regexp.MustCompile(`(?i)Publish to "(\S+)"`)
+
+// Connect dials the bus with account: pinned to its fingerprint when it carries one (refused with any
+// other certificate), authenticated as its user and password, on the inbox prefix _INBOX.<user> and no
+// other, reconnecting without limit as the tool runner does (novox/hq issue 1192: a process outlives a
+// bus restart, never giving up the way the client library's own default of 60 attempts would). Ported
+// from mesh-controller internal/broker/jetstream.go (DialPinned, PinnedToFingerprint), which now uses this one since this
+// package may not import the controller.
+//
+// An ErrorHandler among opts is chained behind this package's own, which watches every async error for a
+// permission violation refusing a publish this connection is waiting an answer to, and cancels that wait
+// at once.
+func Connect(account Account, opts ...nats.Option) (*Conn, error) {
+	c := &Conn{account: account, pending: map[string]map[uint64]context.CancelCauseFunc{}}
+	nc, err := nats.Connect(account.URL, c.options(opts)...)
+	if err != nil {
+		return nil, fmt.Errorf("connecting the process account %s: %w", account.User, err)
+	}
+	c.nc = nc
+	return c, nil
+}
+
+// options is the full option list Connect dials with, apart from Connect so a unit test can check what
+// it carries without a live bus: this package's own (the inbox prefix, the credentials, the pin,
+// reconnecting without limit, and an ErrorHandler chaining any the caller passed), then opts, then this
+// package's own ErrorHandler again last, so it is the one AsyncErrorCB nats.Connect keeps however opts
+// ordered theirs.
+func (c *Conn) options(opts []nats.Option) []nats.Option {
+	// opts are functions over a *nats.Options; applied to a scratch value, this reads off a caller's own
+	// ErrorHandler (if any) to chain, without needing nats.Connect's own URL/Servers parsing here.
+	var scratch nats.Options
+	for _, opt := range opts {
+		if opt != nil {
+			_ = opt(&scratch)
+		}
+	}
+	chained := scratch.AsyncErrorCB
+
+	all := []nats.Option{
+		nats.CustomInboxPrefix(c.account.InboxPrefix()),
+		nats.UserInfo(c.account.User, c.account.Password),
+		nats.MaxReconnects(-1),
+	}
+	if c.account.Fingerprint != "" {
+		all = append(all, nats.Secure(PinnedToFingerprint(c.account.Fingerprint)))
+	}
+	all = append(all, opts...)
+	return append(all, nats.ErrorHandler(func(nc *nats.Conn, sub *nats.Subscription, err error) {
+		c.publishRefused(err)
+		if chained != nil {
+			chained(nc, sub, err)
+		}
+	}))
+}
+
+// Close ends the connection.
+func (c *Conn) Close() { c.nc.Close() }
+
+// withRefusal derives a context from ctx that is also cancelled, with errPermissionRefused as its cause,
+// the moment the bus refuses this account's publish of subject — before ctx's own deadline, which a
+// denied publish would otherwise run out, refused only as an async error with no reply. Every call that
+// requests on the bus registers the subject it is about to publish to here first.
+func (c *Conn) withRefusal(ctx context.Context, subject string) (context.Context, func()) {
+	derived, cancel := context.WithCancelCause(ctx)
+	c.mu.Lock()
+	c.next++
+	id := c.next
+	if c.pending[subject] == nil {
+		c.pending[subject] = map[uint64]context.CancelCauseFunc{}
+	}
+	c.pending[subject][id] = cancel
+	c.mu.Unlock()
+	return derived, func() {
+		c.mu.Lock()
+		if list := c.pending[subject]; list != nil {
+			delete(list, id)
+			if len(list) == 0 {
+				delete(c.pending, subject)
+			}
+		}
+		c.mu.Unlock()
+		cancel(nil)
+	}
+}
+
+// publishRefused ends every call waiting on the subject the bus's error names, with errPermissionRefused
+// as the cause (mesh-tools node-tools/internal/bus/caller.go publishRefused): true when there was one
+// waiting.
+func (c *Conn) publishRefused(err error) bool {
+	if !errors.Is(err, nats.ErrPermissionViolation) {
+		return false
+	}
+	m := refusedPublish.FindStringSubmatch(err.Error())
+	if len(m) < 2 {
+		return false
+	}
+	c.mu.Lock()
+	cancels := c.pending[m[1]]
+	delete(c.pending, m[1])
+	c.mu.Unlock()
+	for _, cancel := range cancels {
+		cancel(errPermissionRefused)
+	}
+	return len(cancels) > 0
+}
+
+// PinnedToFingerprint accepts exactly the certificate with this SHA-256 and no other — the leaf alone, its
+// name and chain deliberately not consulted, as mesh-controller's own pin does (jetstream.go:116-132).
+// PinnedToFingerprint is public so that a process dialling the bus on its own terms, and the controller,
+// share this one pin (novox/hq issue 1633).
+func PinnedToFingerprint(want string) *tls.Config {
+	return &tls.Config{
+		InsecureSkipVerify: true, //nolint:gosec // replaced by the pin below, which is stricter
+		MinVersion:         tls.VersionTLS12,
+		VerifyPeerCertificate: func(rawCerts [][]byte, _ [][]*x509.Certificate) error {
+			if len(rawCerts) == 0 {
+				return errors.New("the bus presented no certificate")
+			}
+			sum := sha256.Sum256(rawCerts[0])
+			got := "sha256:" + hex.EncodeToString(sum[:])
+			if got != want {
+				return fmt.Errorf("the bus presented a certificate this mesh does not know (%s…), expected %s…",
+					got[:23], want[:23])
+			}
+			return nil
+		},
+	}
+}

modules/route-proxy/vendor/git.novox.be/novox/mesh-sdk/go/process/emit.go

@@ -0,0 +1,69 @@
+package process
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"time"
+
+	"github.com/nats-io/nats.go"
+	"github.com/nats-io/nats.go/jetstream"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// Emit publishes an event as this process's module (novox/hq ADR 0436 clause 4), under its module's own
+// namespace (mesh.mod.<module>.event.<type>, the same subject the module's own principal would publish it
+// on), with the SDK's own envelope and headers (stdio.go:498-509). A chosen message id
+// (EmitOptions.MessageID) is sent as x-event-id, and as the bus's own dedup id (Nats-Msg-Id), so a second
+// publish inside the stream's duplicate window is dropped; empty is a random one, as stdio.Emit on main.
+func (c *Conn) Emit(eventType string, body any, opts ...stdio.EmitOptions) error {
+	data, err := json.Marshal(body)
+	if err != nil {
+		return err
+	}
+	id := ""
+	for _, o := range opts {
+		if o.MessageID != "" {
+			id = o.MessageID
+		}
+	}
+	if id == "" {
+		id = eventID()
+	}
+	msg := nats.NewMsg("mesh.mod." + c.account.Module + ".event." + eventType)
+	msg.Header.Set("x-event-id", id)
+	msg.Header.Set("x-source", c.account.Module)
+	msg.Header.Set("x-node", c.account.Node)
+	msg.Header.Set("x-time", time.Now().UTC().Format(time.RFC3339Nano))
+	msg.Header.Set("content-type", "application/json")
+	for _, o := range opts {
+		if o.CausationID != "" {
+			msg.Header.Set("x-causation-id", o.CausationID)
+		}
+		if o.Schema != "" {
+			msg.Header.Set("x-schema", o.Schema)
+		}
+	}
+	msg.Data = data
+	js, err := jetstream.New(c.nc)
+	if err != nil {
+		return err
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), stateTimeout)
+	defer cancel()
+	_, err = js.PublishMsg(ctx, msg, jetstream.WithMsgID(id))
+	return err
+}
+
+// eventID is a random UUID, version 4, as stdio's own eventID (go/stdio.go:515-522) — duplicated rather
+// than imported, since stdio's is unexported and this package touches none of stdio's bundle machinery.
+func eventID() string {
+	var b [16]byte
+	_, _ = rand.Read(b[:])
+	b[6] = (b[6] & 0x0f) | 0x40
+	b[8] = (b[8] & 0x3f) | 0x80
+	h := hex.EncodeToString(b[:])
+	return h[0:8] + "-" + h[8:12] + "-" + h[12:16] + "-" + h[16:20] + "-" + h[20:32]
+}

modules/route-proxy/vendor/git.novox.be/novox/mesh-sdk/go/process/follow.go

@@ -0,0 +1,53 @@
+package process
+
+import (
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/nats-io/nats.go"
+
+	"git.novox.be/novox/mesh-sdk/go/membership"
+)
+
+// FollowMembership reads this account's own membership and follows it (novox/hq ADR 0160): apply is called
+// with every membership the mesh issues this account's node and module, the one already issued first and
+// each later one as it is published, so a change reaches a running process without a restart. A body that is
+// not a membership is handed to onBad (nil to ignore it) and skipped.
+//
+// The subject is followed before it is read, so an issue landing between the two is applied, not missed. The
+// read is the subject-addressed direct get, the one request this account may make of the stream; no
+// membership issued yet, or the read failing, is not an error: the process follows the subject and is told
+// when one arrives. The returned error is a refusal to follow at all.
+func (c *Conn) FollowMembership(apply func(membership.Membership), onBad func(error)) error {
+	if c.account.Node == "" || c.account.Module == "" {
+		return fmt.Errorf("the account names no node or module, so it has no membership")
+	}
+	bad := func(err error) {
+		if onBad != nil {
+			onBad(err)
+		}
+	}
+	take := func(body []byte) {
+		var issued membership.Membership
+		if err := json.Unmarshal(body, &issued); err != nil {
+			bad(fmt.Errorf("a membership arrived that is not one: %w", err))
+			return
+		}
+		apply(issued)
+	}
+	subject := membership.Subject(c.account.Node, c.account.Module)
+	if _, err := c.nc.Subscribe(subject, func(m *nats.Msg) { take(m.Data) }); err != nil {
+		return fmt.Errorf("cannot follow %s: %w", subject, err)
+	}
+	got, err := c.nc.Request(membership.DirectGetSubject(c.account.Node, c.account.Module), nil, 5*time.Second)
+	switch {
+	case err != nil:
+		bad(fmt.Errorf("cannot read the membership issued on %s yet (%v); following it", subject, err))
+	case got.Header.Get("Status") != "" || len(got.Data) == 0:
+		// None issued yet: the follow above delivers it.
+	default:
+		take(got.Data)
+	}
+	return nil
+}