Merge pull request '57/V1: The vault's seat promises get (issue 674)' (#317) from pkg/57-v1-vault-in-go into feat/57-config-and-provisioning

The vault hands a secret only on request and reply, sealed to the asker's key
(hq ADR 0349 §11). The seat set is the controller's, so the verb is promised
here; optional until the vault that runs serves it (design 33 §7).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

RELEASE-57.md

@@ -0,0 +1,6 @@
+# Release 57: config and provisioning
+
+This branch carries the work of hq design 57 (ADR 0348, ADR 0349) in this repository. Each package
+merges here through its own reviewed pull request; the branch reaches main as one pull request, in one
+delivery group with the branch of the same name in mesh-controller, mesh-host, mesh-sdk, mesh-catalog
+and hq, after a rehearsal in the lab. This file is deleted by the last commit before that pull request.

cmd/mesh-builder/busy.go

@@ -0,0 +1,146 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+)
+
+// **The build agent says whether it is busy, and being asked drains it** (novox/hq ADR 0335 §1, §5). Its
+// container declares `busy` as `mesh-builder busy`: the node-engine runs it inside the container before it
+// replaces it. It exits 0 while a build is in hand and 1 when none is; and from the first ask the agent takes
+// no new build request, so its answer ends once the build in hand ends — a replaced builder finishes the check
+// it runs, instead of the build queue handing it out again from the start (issue 594).
+//
+// Two marks in the container's own temporary directory, as the ready mark (ready.go): a new container starts
+// without them, and a restarted one removes them before it takes work again.
+//
+//   - in hand: written by the agent when it claims a request, before it reads whether it is drained; removed
+//     when the build ends.
+//   - drained: written by the ask, before it reads whether a build is in hand.
+//
+// Each side writes its own mark before it reads the other's, so an ask racing a fetch sees the build in hand,
+// or the agent sees the drain and hands the request back; never neither.
+
+func inHandMark() string { return filepath.Join(os.TempDir(), "mesh-builder.in-hand") }
+func drainMark() string  { return filepath.Join(os.TempDir(), "mesh-builder.drained") }
+
+// The drain lapses when no ask has come for drainLapse: the node-engine asks every 20 seconds for as long as it
+// really waits, so an agent whose replacement was withdrawn — the declaration put back, the walk stopped —
+// takes work again rather than staying drained for ever (review of ADR 0335). And an agent drained for longer
+// than the node-engine's bound and the slack says it is not ready: the replacement it was drained for never
+// came, which is a fault to see.
+const (
+	drainLapse   = 2 * time.Minute
+	drainTooLong = 15*time.Minute + 5*time.Minute
+)
+
+// drainedAt is when the drain began and when it was last asked, from its mark; false when there is no mark.
+func drainedAt() (began, asked time.Time, ok bool) {
+	info, err := os.Stat(drainMark())
+	if err != nil {
+		return time.Time{}, time.Time{}, false
+	}
+	asked = info.ModTime()
+	began = asked
+	if raw, err := os.ReadFile(drainMark()); err == nil {
+		if t, err := time.Parse(time.RFC3339, strings.TrimSpace(string(raw))); err == nil && !t.After(asked) {
+			began = t
+		}
+	}
+	return began, asked, true
+}
+
+// drained says the agent was asked whether it is busy within drainLapse: it takes no new build request.
+func drained() bool { return drainedSince(time.Now()) }
+
+func drainedSince(now time.Time) bool {
+	_, asked, ok := drainedAt()
+	return ok && now.Sub(asked) < drainLapse
+}
+
+// drainedTooLong is the health check's second half: nil unless the agent has been drained, asked all along, for
+// longer than its node-engine's bound and the slack.
+func drainedTooLong(now time.Time) error {
+	began, asked, ok := drainedAt()
+	if !ok || now.Sub(asked) >= drainLapse || now.Sub(began) <= drainTooLong {
+		return nil
+	}
+	return fmt.Errorf("drained since %s and still asked: the replacement its node-engine waits for has not come "+
+		"within %s (novox/hq ADR 0335)", began.UTC().Format(time.RFC3339), drainTooLong)
+}
+
+// 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 {
+	// 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)
+		return false
+	}
+	_, err = f.WriteString(time.Now().UTC().Format(time.RFC3339) + "\n")
+	if closeErr := f.Close(); err == nil {
+		err = closeErr
+	}
+	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)
+		return false
+	}
+	if drained() {
+		_ = os.Remove(inHandMark())
+		fmt.Fprintln(os.Stderr, "asked whether busy, so this agent takes no new build: handed back")
+		return false
+	}
+	return true
+}
+
+// holding says what is in hand, for the ask to print: written once the request is read.
+func holding(what string) {
+	_ = os.WriteFile(inHandMark(), []byte(time.Now().UTC().Format(time.RFC3339)+" "+what+"\n"), 0o644)
+}
+
+// released ends the build in hand.
+func released() {
+	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)
+	}
+}
+
+// undrained clears both marks at the start of a holder: a container started again is asked afresh.
+func undrained() error {
+	for _, mark := range []string{drainMark(), inHandMark()} {
+		if err := os.Remove(mark); err != nil && !errors.Is(err, os.ErrNotExist) {
+			return fmt.Errorf("cannot remove %s: %w", mark, err)
+		}
+	}
+	return nil
+}
+
+// busy is the ask: it drains the agent, then says whether a build is in hand. Nil — exit 0 — while one is.
+func busy() (string, error) {
+	// The mark keeps when the drain began while it is asked within drainLapse, and is written again on every
+	// ask: its time is the last ask.
+	began := time.Now().UTC()
+	if was, _, ok := drainedAt(); ok && drained() {
+		began = was.UTC()
+	}
+	if err := os.WriteFile(drainMark(), []byte(began.Format(time.RFC3339)+"\n"), 0o644); err != nil {
+		// Not drained, it could take the next build: said, and answered busy only for what is in hand now.
+		fmt.Fprintf(os.Stderr, "cannot mark this agent drained (%s): %v\n", drainMark(), err)
+	}
+	held, err := os.ReadFile(inHandMark())
+	if err != nil {
+		return "", errors.New("idle: no build in hand, and this agent takes no new one")
+	}
+	since, what, _ := strings.Cut(strings.TrimSpace(string(held)), " ")
+	if what == "" {
+		what = "a build"
+	}
+	return fmt.Sprintf("busy: %s, in hand since %s; taking no new build", what, since), nil
+}

cmd/mesh-builder/busy_test.go

@@ -0,0 +1,162 @@
+package main
+
+import (
+	"os"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// `mesh-builder busy` answers 0 while a build is in hand and non-zero when idle, and after its first ask the
+// agent takes no new build request (novox/hq ADR 0335 §5).
+func TestBusyAnswersWhileABuildIsInHandAndDrainsTheAgent(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	if err := undrained(); err != nil {
+		t.Fatal(err)
+	}
+	if drained() {
+		t.Fatal("an agent never asked is drained")
+	}
+	// A build is claimed and runs.
+	if !claim() {
+		t.Fatal("an agent never asked refused a build")
+	}
+	holding("novox/mesh-controller (check-280)")
+	said, err := busy()
+	if err != nil || !strings.Contains(said, "novox/mesh-controller (check-280)") {
+		t.Fatalf("an agent with a build in hand did not answer busy with what it holds: %q %v", said, err)
+	}
+	// From that ask on it takes nothing new: the fetch is not made, and one fetched is handed back.
+	if !drained() {
+		t.Fatal("the ask did not drain the agent")
+	}
+	if claim() {
+		t.Fatal("a drained agent took a new build")
+	}
+	// The build in hand is still in hand after the refused claim, and busy goes on saying so.
+	if _, err := busy(); err != nil {
+		t.Fatalf("a refused claim ended the build in hand: %v", err)
+	}
+	// It ends: idle, and still drained.
+	released()
+	if _, err := busy(); err == nil {
+		t.Fatal("an agent with nothing in hand answered busy")
+	}
+	if claim() {
+		t.Fatal("a drained agent took a build after its last one ended")
+	}
+	// Started again, it is asked afresh.
+	if err := undrained(); err != nil {
+		t.Fatal(err)
+	}
+	if drained() || !claim() {
+		t.Fatal("a holder started again is still drained")
+	}
+	released()
+}
+
+// An ask racing a fetch sees the build in hand, or the agent sees the drain and hands the request back: never
+// neither, which would replace the container under a build just taken.
+func TestAnAskRacingAFetchNeverMissesTheBuild(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	for i := 0; i < 200; i++ {
+		if err := undrained(); err != nil {
+			t.Fatal(err)
+		}
+		var claimed bool
+		var askErr error
+		var wg sync.WaitGroup
+		wg.Add(2)
+		go func() { defer wg.Done(); claimed = claim() }()
+		go func() { defer wg.Done(); _, askErr = busy() }()
+		wg.Wait()
+		if claimed && askErr != nil {
+			t.Fatalf("round %d: the agent took a build and the ask said idle", i)
+		}
+		released()
+	}
+}
+
+// A drain no longer asked lapses: an agent whose replacement was withdrawn after the first ask (a put-back, a
+// revert, a stopped walk) takes work again after drainLapse, rather than staying drained with its health green.
+func TestADrainNoLongerAskedLapses(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	if err := undrained(); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := busy(); err == nil {
+		t.Fatal("an idle agent answered busy")
+	}
+	if !drained() || claim() {
+		t.Fatal("an agent just asked takes work")
+	}
+	// The last ask was three minutes ago.
+	old := time.Now().Add(-3 * time.Minute)
+	if err := os.Chtimes(drainMark(), old, old); err != nil {
+		t.Fatal(err)
+	}
+	if drained() {
+		t.Fatal("a drain no longer asked for three minutes still holds")
+	}
+	if !claim() {
+		t.Fatal("an agent whose drain lapsed takes no work")
+	}
+	released()
+}
+
+// An agent drained, and asked all along, for longer than its node-engine's bound and the slack is not ready: the
+// replacement it was drained for never came. One asked again after a lapse starts a new drain.
+func TestAnAgentDrainedTooLongIsNotReady(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	if err := undrained(); err != nil {
+		t.Fatal(err)
+	}
+	taking("mesh-build-machine")
+	if _, err := busy(); err == nil {
+		t.Fatal("an idle agent answered busy")
+	}
+	now := time.Now()
+	if err := drainedTooLong(now); err != nil {
+		t.Fatalf("an agent drained a moment ago is not ready: %v", err)
+	}
+	// The drain began 25 minutes ago, and the node-engine asked a moment ago.
+	began := now.Add(-25 * time.Minute).UTC().Format(time.RFC3339)
+	if err := os.WriteFile(drainMark(), []byte(began+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	err := drainedTooLong(time.Now())
+	if err == nil || !strings.Contains(err.Error(), "has not come") {
+		t.Fatalf("an agent drained for 25 minutes reads ready: %v", err)
+	}
+	// Each ask keeps when the drain began.
+	if _, err := busy(); err == nil {
+		t.Fatal("an idle agent answered busy")
+	}
+	if err := drainedTooLong(time.Now()); err == nil {
+		t.Fatal("an ask started the drain again")
+	}
+	// The asks stopped: the drain lapsed, and so did the fault.
+	old := time.Now().Add(-3 * time.Minute)
+	if err := os.Chtimes(drainMark(), old, old); err != nil {
+		t.Fatal(err)
+	}
+	if err := drainedTooLong(time.Now()); err != nil {
+		t.Fatalf("a lapsed drain still reads not ready: %v", err)
+	}
+}
+
+// An ask this build does not know exits non-zero: an older image asked `busy` reads idle, not busy for the
+// node-engine's whole bound.
+func TestAnUnknownCommandFails(t *testing.T) {
+	was := os.Args
+	t.Cleanup(func() { os.Args = was })
+	os.Args = []string{"mesh-builder", "some-later-word"}
+	if err := run(); err == nil {
+		t.Fatal("an unknown command exited 0")
+	}
+	os.Args = []string{"mesh-builder", "help"}
+	if err := run(); err != nil {
+		t.Fatalf("help failed: %v", err)
+	}
+}

cmd/mesh-builder/holder.go

@@ -41,6 +41,9 @@ type holder struct {
 	say func(link.HolderState) error
 	// remove runs what a kill needs outside the build: the containers left behind.
 	remove builder.Runner
+	// scratch is where check builds are kept (novox/hq ADR 0350 §5): what the week's sweep lets go of. Nil where
+	// this machine publishes to no artifact store.
+	scratch builder.Scratch
 
 	mu      sync.Mutex
 	paused  bool
@@ -131,6 +134,34 @@ func (h *holder) stateWhilePaused(ctx context.Context, every time.Duration) {
 	}
 }
 
+// expireChecks lets go of every check build older than a week (novox/hq ADR 0350 §5), at start and every while
+// after. Every holder sweeps the one store; what one let go of, another finds gone.
+func (h *holder) expireChecks(ctx context.Context, every time.Duration, now func() time.Time) {
+	sweep := func() {
+		if h.scratch == nil {
+			return
+		}
+		n, err := h.scratch.Expire(ctx, builder.CheckBuildsKept, now())
+		switch {
+		case err != nil:
+			fmt.Fprintf(os.Stderr, "check builds older than %s: %d let go of, and not all: %v\n", builder.CheckBuildsKept, n, err)
+		case n > 0:
+			fmt.Fprintf(os.Stderr, "check builds older than %s: %d check(s)' builds let go of\n", builder.CheckBuildsKept, n)
+		}
+	}
+	sweep()
+	tick := time.NewTicker(every)
+	defer tick.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-tick.C:
+			sweep()
+		}
+	}
+}
+
 // begin records the build this machine took, with the cancel that ends it.
 func (h *holder) begin(request link.BuildRequest, cancel context.CancelFunc) *running {
 	r := &running{request: request, started: time.Now(), cancel: cancel, done: make(chan struct{})}

cmd/mesh-builder/main.go

@@ -75,6 +75,12 @@ digest of their own configuration. The result is printed as JSON.
 
 exits 0 once the agent running in this container is bound to its build work and pulls it, and
 1 before: its container's health check.
+
+  mesh-builder busy
+
+exits 0 while the agent running in this container has a build in hand, and 1 when it has none;
+from the first ask the agent takes no new build: its container's busy command, asked before the
+container is replaced (novox/hq ADR 0335).
 `
 
 func run() error {
@@ -86,17 +92,41 @@ func run() error {
 		case "build":
 			return buildOnce(context.Background(), os.Args[2:])
 		case "ready":
-			// The container's health check (novox/hq issue 544): exits non-zero until the agent takes work.
-			return ready()
-		default:
+			// The container's health check (novox/hq issue 544): exits non-zero until the agent takes work, and
+			// once it has been drained longer than its node-engine would wait to replace it (ADR 0335).
+			if err := ready(); err != nil {
+				return err
+			}
+			return drainedTooLong(time.Now())
+		case "busy":
+			// The container's busy command (novox/hq ADR 0335): drains the agent, and exits non-zero once
+			// nothing is in hand.
+			said, err := busy()
+			if err != nil {
+				return err
+			}
+			fmt.Println(said)
+			return nil
+		case "help", "-h", "--help":
 			fmt.Print(usage)
 			return nil
+		default:
+			// **An ask this build does not know fails** (novox/hq ADR 0335): an image older than `busy`, asked
+			// it, must read as idle — exiting 0 would hold its container for the node-engine's whole bound.
+			fmt.Fprint(os.Stderr, usage)
+			return fmt.Errorf("%q is not a command this mesh-builder knows", os.Args[1])
 		}
 	}
 
 	if err := notReady(); err != nil {
 		return err
 	}
+	// **The builder's own version is part of every reuse key** (novox/hq ADR 0350 §1): a builder that builds
+	// differently never takes a build another one made.
+	builder.Version = builder.SelfVersion(version)
+	if err := undrained(); err != nil {
+		return err
+	}
 	credential, err := brokerFrom()
 	if err != nil {
 		return err
@@ -149,8 +179,13 @@ func run() error {
 	// **What an earlier holder here left goes before anything is taken** (novox/hq issue 306): a holder
 	// recreated mid-check left the check's store and bus running, and the ask went to another machine.
 	h.removeLeftBehind()
-	machine := link.MachineOverNATSWith(js, on, seat, link.MachineOptions{Paused: h.Paused,
-		Taking: func() { taking(seat) }})
+	// 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() },
+		Taking: func() { taking(seat) },
+		Claim:  claim,
+	})
 	defer machine.Close()
 
 	// The seat's verbs, on this machine's subjects. Only the seat that declares them: the retired
@@ -174,8 +209,13 @@ func run() error {
 
 	fmt.Fprintf(os.Stderr, "building for the mesh, publishing to %s\n", registry)
 	publisher := builder.Registry{Address: registry, Run: builder.Command}
+	// Check builds are let go of after a week (novox/hq ADR 0350 §5).
+	h.scratch = publisher
+	go h.expireChecks(ctx, time.Hour, time.Now)
 
 	return machine.Take(ctx, func(ctx context.Context, work link.Build) {
+		defer released()
+		holding(work.Request().Repository + " (" + work.Request().ID + ")")
 		answer(ctx, publisher, on, workspace, work, h)
 	})
 }
@@ -262,6 +302,7 @@ func answer(ctx context.Context, publisher builder.Publisher, on, workspace stri
 	if err == nil {
 		say("packages", saysRegistry(npmrc))
 	}
+	registryHere, isRegistry := publisher.(builder.Registry)
 	var built builder.Result
 	if request.Check != nil {
 		// **A pull request's merge check, not a build** (novox/hq to-be 45 §9): nothing is built,
@@ -271,12 +312,21 @@ func answer(ctx context.Context, publisher builder.Publisher, on, workspace stri
 		if r, ok := publisher.(builder.Registry); ok {
 			registry = r.Address
 		}
+		spec := checkSpecOf(request)
+		// What the merge would move, built by the check for the walk to take (novox/hq ADR 0350 §1): into the
+		// scratch namespace. **Never with the package registry's credential**: this is code nobody has approved
+		// yet, and a recipe could read the credential it is handed (issue 462). A module that resolves packages
+		// at build time has no reuse key anyway, so nothing is lost by refusing it here.
+		if isRegistry && len(spec.Builds) > 0 {
+			spec.BuildWith = &builder.CheckBuilding{Publish: publisher, Scratch: registryHere, Held: request.Held,
+				Seats: request.Seats}
+		}
 		var v builder.CheckVerdict
-		v, err = builder.Check(building, builder.Command, checkSpecOf(request), workspace, registry, forgeFrom(), say)
+		v, err = builder.Check(building, builder.Command, spec, workspace, registry, forgeFrom(), say)
 		if err == nil {
 			result.Check = &link.CheckOutcome{Verdict: v.Verdict, Summary: v.Summary, Report: v.Report,
 				Took: v.Took.Round(time.Second).String(), Gate: layerOf(v.Gate), RepoCheck: layerOf(v.Repo),
-				Head: v.Head, Trunk: v.Trunk, Beside: v.Beside}
+				Head: v.Head, Trunk: v.Trunk, Beside: v.Beside, Built: checkBuiltOf(v.Built)}
 			// What each of a group's heads was judged as (novox/hq ADR 0323 §6).
 			for _, m := range v.Members {
 				result.Check.Members = append(result.Check.Members, link.CheckedMember{Owner: m.Owner, Repo: m.Repo,
@@ -289,9 +339,30 @@ func answer(ctx context.Context, publisher builder.Publisher, on, workspace stri
 		// after a clone that then fails at npm ci.
 		// Every container it starts is labelled with its id, so a kill finds what outlived the
 		// docker client (ADR 0219).
-		built, err = builder.Build(building, builder.Labelled(builder.Command, request.ID), publisher,
-			request.Repository, request.Path, request.Ref, workspace, request.Held, npmrc,
-			forgeFrom(), say, request.Seats)
+		if request.Reuse != nil && isRegistry && !request.DryRun {
+			// **A walk's build takes the check's build of the same key** (novox/hq ADR 0350 §2).
+			reuse := builder.Reuse{Scratch: registryHere}
+			for _, p := range request.Reuse.Pulls {
+				reuse.Pulls = append(reuse.Pulls, builder.PullRef{Owner: p.Owner, Repo: p.Repo, Number: p.Number})
+			}
+			// Only what a verdict names is taken (ADR 0350 §2).
+			for _, b := range request.Reuse.Builds {
+				named := builder.NamedBuild{Pull: builder.PullRef{Owner: b.Pull.Owner, Repo: b.Pull.Repo,
+					Number: b.Pull.Number}, Check: b.Check, Module: b.Built.Module, Key: b.Built.Key,
+					Digests: map[string]string{}}
+				for _, m := range b.Built.Made {
+					named.Digests[m.Name] = builder.DigestOf(m.Reference)
+				}
+				reuse.Named = append(reuse.Named, named)
+			}
+			built, err = builder.BuildReusing(building, builder.Labelled(builder.Command, request.ID), publisher, reuse,
+				request.Repository, request.Path, request.Ref, workspace, request.Held, npmrc,
+				forgeFrom(), say, request.Seats)
+		} else {
+			built, err = builder.Build(building, builder.Labelled(builder.Command, request.ID), publisher,
+				request.Repository, request.Path, request.Ref, workspace, request.Held, npmrc,
+				forgeFrom(), say, request.Seats)
+		}
 	}
 	// What it copied into the store, whatever became of the build (novox/hq ADR 0257).
 	result.Mirrored = built.Mirrored
@@ -327,6 +398,19 @@ func answer(ctx context.Context, publisher builder.Publisher, on, workspace stri
 			}
 			result.Against = built.Against
 			result.SourceFingerprint = built.Source
+			// What the walk did instead of building, or why it built (novox/hq ADR 0350 §3, §4).
+			result.ReuseKey = built.ReuseKey
+			if built.Reused != nil {
+				f := built.Reused.From
+				result.Reused = built.Reused.Words()
+				result.ReusedFrom = &link.ReusedFrom{Pull: link.PullRef{Owner: f.Pull.Owner, Repo: f.Pull.Repo,
+					Number: f.Pull.Number}, Head: f.Head, Trunk: f.Trunk, Check: f.Check, Key: f.Key}
+			} else if request.Reuse != nil {
+				result.BuiltWhy = built.Why
+				if result.BuiltWhy == "" {
+					result.BuiltWhy = "it has no artifact to build"
+				}
+			}
 			result.Trunk, result.OnTrunk, result.Branches = built.Trunk, built.OnTrunk, built.Branches
 			for _, r := range built.Read {
 				result.Read = append(result.Read, link.ReadRepository{Repository: r.Repository, Ref: r.Ref})
@@ -377,6 +461,10 @@ func checkSpecOf(request link.BuildRequest) builder.CheckSpec {
 	for dir, b := range c.Beside {
 		spec.Beside[dir] = builder.Beside{Repository: b.Repository, Ref: b.Ref}
 	}
+	for _, b := range c.Builds {
+		spec.Builds = append(spec.Builds, builder.CheckBuildSpec{Module: b.Module, Repository: b.Repository, Path: b.Path,
+			Ref: b.Ref, Merged: b.Merged, Tier: b.Tier, Skip: b.Skip})
+	}
 	for _, m := range c.Members {
 		spec.Group = append(spec.Group, builder.GroupHead{Owner: m.Owner, Repo: m.Repo, Repository: m.Repository,
 			Ref: m.Ref, Paths: m.Paths, Base: m.Base})
@@ -384,6 +472,19 @@ func checkSpecOf(request link.BuildRequest) builder.CheckSpec {
 	return spec
 }
 
+// checkBuiltOf is a check's builds for its merge as the outcome carries them (novox/hq ADR 0350 §1).
+func checkBuiltOf(built []builder.CheckBuilt) []link.CheckBuilt {
+	var out []link.CheckBuilt
+	for _, b := range built {
+		c := link.CheckBuilt{Module: b.Module, Key: b.Key, NotBuilt: b.NotBuilt, Took: b.Took.Round(time.Second).String()}
+		for _, m := range b.Made {
+			c.Made = append(c.Made, link.MadeArtifact{Name: m.Name, Kind: m.Kind, Reference: m.Reference})
+		}
+		out = append(out, c)
+	}
+	return out
+}
+
 // layerOf is one layer of a check as the outcome carries it.
 func layerOf(l *builder.Layer) *link.CheckLayer {
 	if l == nil {

cmd/mesh-builder/stdout_test.go

@@ -16,6 +16,7 @@ func TestBuilderDiagnosticsStayOffStdout(t *testing.T) {
 		"version)":     true, // --version
 		`"stopping")`:  true, // the loop.s shutdown line
 		"usage)":       true, // --help text, for a human
+		"said)":        true, // busy: the answer its node-engine reads (novox/hq ADR 0335)
 	}
 	for _, file := range []string{"once.go", "main.go"} {
 		src, err := os.ReadFile(file)

cmd/mesh-controller/adoption.go

@@ -424,8 +424,9 @@ func comparisonOf(module string, c comparison, opts takeOptions) (preview string
 	}
 	// And its settings on this machine, composed against its definition (rule 1, rule 6).
 	for _, layer := range c.layers {
-		keys := make([]string, 0, len(layer.Values))
-		for k := range layer.Values {
+		said := layer.Whole()
+		keys := make([]string, 0, len(said))
+		for k := range said {
 			keys = append(keys, k)
 		}
 		sort.Strings(keys)

cmd/mesh-controller/build.go

@@ -15,6 +15,7 @@ import (
 	"github.com/nats-io/nats.go"
 
 	"github.com/novox/mesh-controller/internal/broker"
+	"github.com/novox/mesh-controller/internal/builder"
 	"github.com/novox/mesh-controller/internal/catalogue"
 	"github.com/novox/mesh-controller/internal/inventory"
 	"github.com/novox/mesh-controller/internal/link"
@@ -483,6 +484,7 @@ func buildOneAsked(ctx context.Context, source buildSource, path, ref string, wa
 		Seats:      seatBases(ctx),
 		DryRun:     dryRun,
 	}
+	request.Reuse = reuseAsked(ctx, dryRun)
 	fmt.Printf("asked for %s", source)
 	if source.Seat != "" {
 		fmt.Printf(" (%s)", repository)
@@ -669,6 +671,12 @@ func takeIn(ctx context.Context, inv *inventory.Inventory, result link.BuildResu
 		return manifest, kept, fmt.Errorf("%s built %s (%s), recorded and not registered: %w", result.On,
 			manifest.Module, short(result.Commit), err)
 	}
+	// **Never a build in the scratch namespace** (novox/hq ADR 0239 §9, ADR 0350 §2): what a check builds is
+	// registered only as the walk's copy in the module's own namespace.
+	if scratch := inScratch(result.Made); scratch != "" {
+		return manifest, kept, fmt.Errorf("%s built %s (%s), recorded and not registered: %s is in the scratch "+
+			"namespace, which only a walk's copy leaves (ADR 0350)", result.On, manifest.Module, short(result.Commit), scratch)
+	}
 	// **A build that failed its gate is never registered again** (novox/hq ADR 0236): an outcome heard
 	// twice, or replayed, would otherwise make the build a rollback put back what the module is again,
 	// and the next push would send it.
@@ -714,6 +722,16 @@ func takeIn(ctx context.Context, inv *inventory.Inventory, result link.BuildResu
 	return manifest, kept, nil
 }
 
+// inScratch is the first artifact a build made into the scratch namespace; empty when none is.
+func inScratch(made []link.MadeArtifact) string {
+	for _, m := range made {
+		if path, kept := catalogue.InArtifactStore(catalogue.Recorded(m.Reference)); kept && strings.HasPrefix(path, builder.ScratchPrefix) {
+			return m.Reference
+		}
+	}
+	return ""
+}
+
 // errOffTheTrunk is a build of a commit off its repository's trunk, which is never published.
 var errOffTheTrunk = errors.New("the commit is not on its repository's trunk: a commit off the trunk is checked, " +
 	"never published (ADR 0238) — merge it, and the merge builds it")

cmd/mesh-controller/busy.go

@@ -0,0 +1,103 @@
+package main
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// A first-node gate waits for a busy container (novox/hq ADR 0335 §4).
+//
+// When a machine reports, on what the gate sent it, that a container of a judged module was left running
+// because it said busy, the judging has not started: the build is not yet what runs there. The walk says it
+// waits for a busy container on that machine, counts no pass and no bound, and starts the judging — its
+// Since — at the report that no longer lists the container waiting. The wait is the node-engine's, bounded
+// at 15 minutes; the controller's own bound (busyGateBound past the engine's) is for an engine that stopped
+// reporting while it waited, so no walk waits for ever. An engine older than the field never lists one, and
+// its gate starts as before.
+
+// busyGateSlack is how long past the engine's bound the controller still waits for the report that says the
+// container replaced: a pass of the engine (its asks every 20 seconds) and the report's way here.
+var busyGateSlack = 5 * time.Minute
+
+// busyEngineBound is the node-engine's bound on a wait (novox/hq ADR 0335 §3), counted again here on this
+// controller's clock from when it first read the wait.
+const busyEngineBound = 15 * time.Minute
+
+// busyGateEnds is when the gate stops waiting: the engine's own word on its bound, or this controller's count of
+// it from when it first read the wait, whichever is sooner, and the slack — so neither a clock ahead on the
+// machine nor a wrong word from it holds a walk longer.
+func busyGateEnds(b *inventory.GateBusy) time.Time {
+	until := b.Seen.Add(busyEngineBound)
+	if !b.Until.IsZero() && b.Until.Before(until) {
+		until = b.Until
+	}
+	return until.Add(busyGateSlack)
+}
+
+// busyWait decides, before a judging, whether the gate waits for a busy container on a machine it judges:
+// true while it waits, the gate saying so. False when nothing waits, or no longer: a wait that ended moves the
+// gate's Since to its end. Pure but for the gate it is handed.
+func busyWait(g *inventory.PlanGate, pairs []judged, f gateFacts, now time.Time) bool {
+	if g.Busy != nil && g.Busy.Ended != nil {
+		return false
+	}
+	for _, j := range pairs {
+		b, waits := busyOn(j, f)
+		if !waits {
+			continue
+		}
+		if g.Busy == nil {
+			g.Busy = &inventory.GateBusy{Machine: j.node, Module: j.module, Container: b.Container, Since: b.Since,
+				Seen: now}
+		}
+		if g.Busy.Seen.IsZero() {
+			g.Busy.Seen = now
+		}
+		g.Busy.Until, g.Busy.Said = b.Until, b.Said
+		if now.After(busyGateEnds(g.Busy)) {
+			// The engine said it would have replaced it by now: the judging starts, and finds the module not
+			// yet healthy while the machine still lists it waiting (busyStill), until the gate's own bound.
+			end := now
+			g.Busy.Ended, g.Busy.PastBound = &end, true
+			g.Since, g.Passes, g.LastPass, g.Healthy, g.HealthyAt, g.Applied = &end, 0, nil, nil, nil, nil
+			return false
+		}
+		g.Passes, g.LastPass, g.Last, g.Failing = 0, nil, g.Busy.Words(), nil
+		g.Read(now, false, g.Busy.Words())
+		return true
+	}
+	if g.Busy == nil {
+		return false
+	}
+	// Replaced: the judging starts at the report that said so.
+	end := now
+	if r, said := f.reports[g.Busy.Machine]; said && r.At != nil && r.At.After(g.Busy.Since) && r.At.Before(now) {
+		end = r.At.UTC()
+	}
+	g.Busy.Ended = &end
+	g.Since, g.Passes, g.LastPass, g.Last, g.Healthy, g.HealthyAt, g.Applied = &end, 0, nil, "", nil, nil, nil
+	return false
+}
+
+// busyOn is the container of a judged module its machine last reported, on what the gate sent it, as left
+// running because it said busy.
+func busyOn(j judged, f gateFacts) (inventory.BusyWait, bool) {
+	r, said := f.reports[j.node]
+	if !said || r.At == nil || !f.reportedOn(j.node, r) {
+		return inventory.BusyWait{}, false
+	}
+	return inventory.WaitingFor(r.Busy, j.module)
+}
+
+// busyStill is a judged module whose container its machine still lists waiting once the gate stopped waiting
+// for it: not yet what was sent, so not healthy, whatever its health says of the container still running.
+func busyStill(j judged, f gateFacts) (string, bool) {
+	b, waits := busyOn(j, f)
+	if !waits {
+		return "", false
+	}
+	return fmt.Sprintf("%s still runs its busy container %s, past its node-engine's bound of %s",
+		j.node, b.Container, b.Until.UTC().Format(time.RFC3339)), true
+}

cmd/mesh-controller/busy_test.go

@@ -0,0 +1,148 @@
+package main
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// A walk whose module's container waits as busy on its first machine says so, and starts that machine's
+// first-machine gate only once the machine reports the container replaced (novox/hq ADR 0335 §4).
+func TestAGateWaitsForABusyContainerAndStartsWhenItIsReplaced(t *testing.T) {
+	sent := time.Date(2026, 10, 13, 1, 0, 0, 0, time.UTC)
+	g := &inventory.PlanGate{Machines: []string{"novox"}, Since: &sent,
+		Sent: map[string]inventory.SentDeclaration{"novox": {Digest: "d1", Sequence: 7}}}
+	pairs := []judged{{module: "build-agent", node: "novox"}, {module: "mesh-controller", node: "novox"}}
+	reported := sent.Add(20 * time.Second)
+	waiting := []inventory.BusyWait{{ID: "build-agent.server", Container: "mesh-build-agent",
+		State: inventory.BusyWaiting, Since: reported, Until: reported.Add(15 * time.Minute),
+		Said: "busy: novox/mesh-controller (check of #280), in hand since 00:58:00Z"}}
+	facts := func(at time.Time, busy []inventory.BusyWait) gateFacts {
+		// As judgeMoves hands it: the report held against the gate's own send.
+		return gateFacts{sent: g.Sent, reports: map[string]inventory.Reported{"novox": {Node: "novox",
+			Outcome: inventory.OutcomeApplied, At: &at, Declared: "d1", ReportedSequence: 7, Busy: busy}}}
+	}
+
+	now := reported.Add(time.Minute)
+	if !busyWait(g, pairs, facts(reported, waiting), now) {
+		t.Fatal("a gate whose module's container waits as busy judged it")
+	}
+	if !g.Since.Equal(sent) || g.Busy == nil || g.Busy.Machine != "novox" || g.Busy.Ended != nil {
+		t.Fatalf("the gate does not keep the wait: %+v %+v", g.Since, g.Busy)
+	}
+	for _, said := range []string{gateLine(g), g.Last} {
+		if !strings.Contains(said, "waits for a busy container on novox") {
+			t.Errorf("the walk does not say it waits for a busy container there: %s", said)
+		}
+	}
+	if !strings.Contains(g.Last, "check of #280") {
+		t.Errorf("the wait does not say what the container holds: %s", g.Last)
+	}
+
+	// Ten minutes on, still busy, within the engine's bound: still waiting, nothing judged, no bound run.
+	now = reported.Add(10 * time.Minute)
+	if !busyWait(g, pairs, facts(reported.Add(9*time.Minute), waiting), now) || g.Passes != 0 {
+		t.Fatalf("the gate stopped waiting within the bound: %+v", g)
+	}
+
+	// The machine reports it replaced: the judging starts at that report.
+	replacedAt := reported.Add(12 * time.Minute)
+	now = replacedAt.Add(5 * time.Second)
+	replaced := []inventory.BusyWait{{ID: "build-agent.server", Container: "mesh-build-agent",
+		State: "replaced-when-idle", Since: reported, Until: reported.Add(15 * time.Minute)}}
+	if busyWait(g, pairs, facts(replacedAt, replaced), now) {
+		t.Fatal("the gate still waits after the container was replaced")
+	}
+	if g.Since == nil || !g.Since.Equal(replacedAt) || g.Busy.Ended == nil || !g.Busy.Ended.Equal(replacedAt) {
+		t.Fatalf("the gate does not start at the report that said it replaced: since %v, %+v", g.Since, g.Busy)
+	}
+	if strings.Contains(gateLine(g), "waits for a busy container") {
+		t.Errorf("a gate judging still says it waits: %s", gateLine(g))
+	}
+	// And a later report listing it waiting again does not hold a gate that started.
+	if busyWait(g, pairs, facts(now, waiting), now.Add(time.Minute)) {
+		t.Error("a gate that started waits again")
+	}
+}
+
+// An engine that stops reporting while it waits holds no walk for ever: past the engine's bound and the slack,
+// the judging starts, and finds the module not yet healthy while its container is still listed waiting.
+func TestAGateWaitsNoLongerThanTheEnginesBound(t *testing.T) {
+	sent := time.Date(2026, 10, 13, 1, 0, 0, 0, time.UTC)
+	g := &inventory.PlanGate{Machines: []string{"novox"}, Since: &sent}
+	pairs := []judged{{module: "build-agent", node: "novox"}}
+	waiting := []inventory.BusyWait{{ID: "build-agent.server", Container: "mesh-build-agent",
+		State: inventory.BusyWaiting, Since: sent, Until: sent.Add(15 * time.Minute)}}
+	f := gateFacts{reports: map[string]inventory.Reported{"novox": {Node: "novox", Outcome: inventory.OutcomeApplied,
+		At: &sent, Current: true, Busy: waiting}}}
+	now := sent.Add(15*time.Minute + busyGateSlack + time.Second)
+	if busyWait(g, pairs, f, now) {
+		t.Fatal("a gate waited past the engine's bound and the slack")
+	}
+	if !g.Busy.PastBound || !g.Since.Equal(now) {
+		t.Fatalf("the gate does not start, said past the bound: %+v %v", g.Busy, g.Since)
+	}
+	if why, still := busyStill(pairs[0], f); !still || !strings.Contains(why, "past its node-engine's bound") {
+		t.Fatalf("a module still running its busy container reads as what was sent: %q", why)
+	}
+}
+
+// A report from an engine older than the field lists nothing: the gate starts at the send, as before; and a
+// report not about the gate's send says nothing of it.
+func TestAGateOfAnEngineThatNeverWaitsStartsAsBefore(t *testing.T) {
+	sent := time.Date(2026, 10, 13, 1, 0, 0, 0, time.UTC)
+	g := &inventory.PlanGate{Machines: []string{"ace"}, Since: &sent,
+		Sent: map[string]inventory.SentDeclaration{"ace": {Digest: "d2", Sequence: 9}}}
+	pairs := []judged{{module: "build-agent", node: "ace"}}
+	at := sent.Add(time.Minute)
+	older := gateFacts{sent: g.Sent, reports: map[string]inventory.Reported{"ace": {Node: "ace", Outcome: inventory.OutcomeApplied,
+		At: &at, Declared: "d2", ReportedSequence: 9}}}
+	if busyWait(g, pairs, older, at) || g.Busy != nil || !g.Since.Equal(sent) {
+		t.Fatalf("a gate on an engine that never waits did not start at the send: %+v %v", g.Busy, g.Since)
+	}
+	elsewhere := gateFacts{sent: g.Sent, reports: map[string]inventory.Reported{"ace": {Node: "ace", Outcome: inventory.OutcomeApplied,
+		At: &at, Declared: "d1", ReportedSequence: 8, Busy: []inventory.BusyWait{{ID: "build-agent.server",
+			State: inventory.BusyWaiting, Until: at.Add(time.Hour)}}}}}
+	if busyWait(g, pairs, elsewhere, at) {
+		t.Fatal("a wait reported about an earlier declaration held the gate")
+	}
+}
+
+// The wait is bounded on this controller's clock: an engine whose clock runs an hour ahead, saying it waits until
+// then, holds the gate no longer than 15 minutes and the slack from when the controller first read the wait.
+func TestAGateWaitIsBoundedOnTheControllersClock(t *testing.T) {
+	seen := time.Date(2026, 10, 13, 1, 0, 0, 0, time.UTC)
+	g := &inventory.PlanGate{Machines: []string{"novox"}, Since: &seen}
+	pairs := []judged{{module: "build-agent", node: "novox"}}
+	ahead := seen.Add(time.Hour)
+	f := gateFacts{reports: map[string]inventory.Reported{"novox": {Node: "novox", Outcome: inventory.OutcomeApplied,
+		At: &seen, Current: true, Busy: []inventory.BusyWait{{ID: "build-agent.server", Container: "mesh-build-agent",
+			State: inventory.BusyWaiting, Since: ahead, Until: ahead.Add(15 * time.Minute)}}}}}
+	if !busyWait(g, pairs, f, seen) || !g.Busy.Seen.Equal(seen) {
+		t.Fatalf("the gate did not start waiting, seen now: %+v", g.Busy)
+	}
+	if !busyWait(g, pairs, f, seen.Add(15*time.Minute+busyGateSlack-time.Second)) {
+		t.Fatal("the gate stopped waiting within the bound on its own clock")
+	}
+	if busyWait(g, pairs, f, seen.Add(15*time.Minute+busyGateSlack+time.Second)) || !g.Busy.PastBound {
+		t.Fatalf("an engine's later word held the gate past the controller's bound: %+v", g.Busy)
+	}
+}
+
+// `plan` says, for a machine whose node-engine is older than the field, each container whose busy is not sent.
+func TestAPlanSaysABusyAnOlderEngineIsNotSent(t *testing.T) {
+	modules := []catalogue.Manifest{{Module: "build-agent", Resources: []map[string]any{
+		{"id": "server", "type": "container", "busy": map[string]any{"command": "mesh-builder busy"}},
+		{"id": "agent-env", "type": "file"}}}}
+	lines := busyNotSent(modules, false)
+	if len(lines) != 1 || !strings.Contains(lines[0], "build-agent.server declares busy") ||
+		!strings.Contains(lines[0], "replaced at once") {
+		t.Fatalf("the plan does not say the busy not sent: %v", lines)
+	}
+	if lines := busyNotSent(modules, true); len(lines) != 0 {
+		t.Fatalf("a busy sent is said as not sent: %v", lines)
+	}
+}

cmd/mesh-controller/check.go

@@ -55,6 +55,11 @@ func moduleCheckFor(paths []string, longestMachine int, out io.Writer) error {
 			continue
 		}
 		m, err := catalogue.ParseManifest(raw)
+		if err == nil {
+			// Each template's text read from the tree beside the manifest, and judged as inline content is
+			// (novox/hq ADR 0349 §2): a missing template is refused by name.
+			m, err = catalogue.WithTemplatesFrom(m, filepath.Dir(path))
+		}
 		if err != nil {
 			fmt.Fprintf(out, "%s: %v\n", path, err)
 			failed++

cmd/mesh-controller/check_builds.go

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

cmd/mesh-controller/check_builds_test.go

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

cmd/mesh-controller/checks.go

@@ -282,10 +282,59 @@ func checkRequestFor(ctx context.Context, open *stores, p link.PullUpdated, scop
 		Source:     sourceOnSeat(source),
 		Check: &link.CheckRequest{Owner: p.Owner, Repo: p.Repo, Number: p.Number, Base: p.Base,
 			Paths: p.Paths, Beside: beside, Modules: scope.Modules, Dependents: scope.Dependents, New: scope.New,
-			Manifests: scope.Manifests, Judge: scope.Judge},
+			Manifests: scope.Manifests, Judge: scope.Judge, Builds: checkBuildsOf(p, scope, entries, clone)},
 	}, nil
 }
 
+// checkBuildsOf are the modules a merge of the change would build, in the walk's order, as the check builds them
+// for the walk to take (novox/hq ADR 0350 §1): a module built from the repository checked, at the branch it merges
+// into, from the merge the check makes; any other — a module standing on one — from its own repository at the
+// branch it follows, as the walk builds it. A module whose build reads the repository checked through a context,
+// or that the merge deletes, cannot be built as the walk would: said, and nothing after it is built. A change that
+// moves no module builds nothing.
+func checkBuildsOf(p link.PullUpdated, scope checkScope, entries []inventory.Entry,
+	clone func(inventory.Source) (string, error)) []link.CheckBuild {
+	if len(scope.Reach.Plan.Tiers) == 0 {
+		return nil
+	}
+	m := link.SourceMoved{Owner: p.Owner, Repo: p.Repo, Base: p.Base, CloneURL: p.CloneURL}
+	byName := map[string]inventory.Entry{}
+	for _, e := range entries {
+		byName[e.Manifest.Module] = e
+	}
+	skip := map[string]string{}
+	for _, e := range scope.Reach.Packaging {
+		skip[e.Manifest.Module] = "its build reads " + p.Owner + "/" + p.Repo + " through a context, which a check " +
+			"cannot hand the merge"
+	}
+	for _, e := range scope.Reach.Deleted {
+		skip[e.Manifest.Module] = "the merge deletes it"
+	}
+	var out []link.CheckBuild
+	for tier, names := range scope.Reach.Plan.Tiers {
+		for _, name := range names {
+			e, known := byName[name]
+			b := link.CheckBuild{Module: name, Tier: tier, Skip: skip[name]}
+			switch {
+			case !known:
+				b.Skip = "the catalogue does not hold it"
+			case b.Skip != "":
+			case sourceIs(e.Source, m):
+				b.Merged, b.Path = true, e.Source.Path
+			default:
+				url, err := clone(e.Source)
+				if err != nil {
+					b.Skip = "its repository cannot be cloned: " + err.Error()
+					break
+				}
+				b.Repository, b.Path, b.Ref = url, e.Source.Path, followedBranch(e.Source.Ref)
+			}
+			out = append(out, b)
+		}
+	}
+	return out
+}
+
 // besideRefs is the ref each repository is cloned at beside a check, by the directory it is found under:
 // a core repository at the commit the mesh runs of the module built from it (`running`) — but the
 // catalogue, whose checkout beside is what tests read its files from, at its main, what the next merge
@@ -382,6 +431,7 @@ func checkedOf(result link.BuildResult) link.Checked {
 		// What was judged (novox/hq ADR 0323 §3): the head merged into the trunk commit, and the commits of the
 		// repositories read beside it.
 		c.Trunk, c.Beside, c.Took = result.Check.Trunk, result.Check.Beside, result.Check.Took
+		c.Built = result.Check.Built
 		if c.Gate == nil {
 			// A build seat from before the layers: its verdict is the gate's.
 			c.Gate = &link.CheckLayer{Verdict: c.Verdict, Summary: c.Summary}

cmd/mesh-controller/facts.go

@@ -348,11 +348,11 @@ func gatherFacts(ctx context.Context, open *stores, busVersion string) (snapshot
 				if layer.From == catalogue.MeshWideLayer {
 					if !meshWide[module] {
 						meshWide[module] = true
-						f.Settings = append(f.Settings, snapshot.Settings{Module: module, Values: scrub.Values(layer.Values)})
+						f.Settings = append(f.Settings, snapshot.Settings{Module: module, Values: scrub.Values(layer.Whole())})
 					}
 					continue
 				}
-				m.Settings = append(m.Settings, snapshot.Settings{Module: module, Values: scrub.Values(layer.Values)})
+				m.Settings = append(m.Settings, snapshot.Settings{Module: module, Values: scrub.Values(layer.Whole())})
 			}
 		}
 		m.Declaration = declarationFacts(ctx, open, n.Name, gens, gensErr, scrub)

cmd/mesh-controller/found_wait_test.go

@@ -81,9 +81,13 @@ func TestAFixGoesThroughPastADirectoryFoundBefore(t *testing.T) {
 				}
 				return f, err
 			}
-			wasSettle, wasEvery, wasBound := gateSettle, gateEvery, gateBound
-			t.Cleanup(func() { gateSettle, gateEvery, gateBound = wasSettle, wasEvery, wasBound })
-			gateSettle, gateEvery, gateBound = 0, 0, 300*time.Millisecond
+			wasWithin, wasEvery, wasBound := gateWithin, gateEvery, gateBound
+			// The witness window is the node-engine's, from a start no test makes (novox/hq ADR 0351).
+			wasWindow := gateWitnessWindow
+			gateWitnessWindow = 0
+			t.Cleanup(func() { gateWitnessWindow = wasWindow })
+			t.Cleanup(func() { gateWithin, gateEvery, gateBound = wasWithin, wasEvery, wasBound })
+			gateWithin, gateEvery, gateBound = time.Hour, 0, 300*time.Millisecond
 			deadline := time.Now().Add(5 * time.Second)
 			for time.Now().Before(deadline) {
 				advancePlans(ctx, b.open)

cmd/mesh-controller/gate.go

@@ -28,9 +28,12 @@ import (
 // that machine reported it applied. A build that applies and then does nothing, crashes, serves no
 // tools, or breaks the machine's word to the mesh passed that test. Now the first machine is judged by
 // the component's health — the core's health definitions, or a module's own — within ten minutes of the
-// apply: a core module passing three times over at least two minutes, a leaf module once, as soon as the
-// node-engine states it healthy (novox/hq ADR 0282 decision 4 as ADR 0304 decision 3 changed it). Only then
-// are the rest sent.
+// apply, each module by its rule (gateRuleOf): the node-engine and the mesh's resolver passing on their third
+// healthy reading, and never later than two minutes after the send while healthy; the controller and the tool runner once, no earlier than the end of the
+// node-engine's witness window for it; mesh-delivery and a leaf module once, as soon as the node-engine states
+// it healthy (novox/hq ADR 0351 and ADR 0352, changing ADR 0236 decision 3, ADR 0282 decision 4 and ADR 0304
+// decision 3).
+// Only then are the rest sent.
 //
 // **A failing gate stops the plan and puts the previous build back there.** The build is marked failed
 // at its gate — registration refuses it and nothing sends it again on its own — the module's registered
@@ -41,22 +44,30 @@ import (
 
 // The gate's bounds (to-be 45 §8). Variables so a test can judge in a second, not in minutes.
 var (
-	// gateSettle is how long the first machine must stay healthy, at the least.
-	gateSettle = 2 * time.Minute
+	// gateWithin is the longest a module under the three-reading rule that stays healthy is held: at it, the
+	// gate passes on the healthy readings it has, the newest healthy and none since the send not (novox/hq ADR
+	// 0352). Readings gateEvery apart, the first at the apply, put three inside it.
+	gateWithin = 2 * time.Minute
 	// gateBound is how long after the apply the build may take to become healthy.
 	gateBound = 10 * time.Minute
-	// gatePasses is how many consecutive judgings must find a core module healthy, gateEvery apart at the
-	// least, after gateSettle. gateLeafPasses is a leaf module's: one, taken once the node-engine states every
-	// resource of it healthy by its own check, with no settle (novox/hq ADR 0282 decision 4 as ADR 0304
-	// decision 3 changed it, issue 524).
+	// gatePasses is how many consecutive judgings must find such a core module healthy, gateEvery apart at
+	// the least, counted from the send: it passes on the third (novox/hq ADR 0352). gateLeafPasses is a leaf module's: one, taken once the
+	// node-engine states every resource of it healthy by its own check, with no settle (novox/hq ADR 0282
+	// decision 4 as ADR 0304 decision 3 changed it, issue 524).
 	gatePasses      = 3
 	gateLeafPasses  = 1
 	gateLeafSettles = false
 	gateEvery       = 40 * time.Second
+	// gateWitnessWindow is the node-engine's witness window for a new controller or tool runner, from its
+	// start (ADR 0236 decision 27, lease.ControllerWithin and lease.NodeToolsWithin): a reading of either
+	// counts only after it has ended, so the build is judged by the witness and the gate both (novox/hq ADR
+	// 0351 decisions 1 and 4).
+	gateWitnessWindow = max(lease.ControllerWithin, lease.NodeToolsWithin)
 )
 
 // coreModule is whether a module is judged as the core (novox/hq ADR 0282 decision 1): one on the controller's
-// own path, or one holding the mesh's resolver. Every other module is a leaf.
+// own path, or one holding the mesh's resolver. Every other module is a leaf. Its class sets the module's
+// delivery budget; how many readings its gate takes is gateRuleOf's.
 func coreModule(module string, m catalogue.Manifest) bool {
 	if _, own := onTheControllersPath[module]; own {
 		return true
@@ -69,12 +80,72 @@ func coreModule(module string, m catalogue.Manifest) bool {
 	return coreComponent(module) != ""
 }
 
-// gateWants is how many passes a module needs, and whether it must stay healthy gateSettle first.
-func gateWants(module string, m catalogue.Manifest) (passes int, settles bool) {
-	if coreModule(module, m) {
-		return gatePasses, true
+// gateRule is how a module's first-node gate judges it: passes healthy readings, gateEvery apart at the
+// least, counted from the send or, where witnessed, from the end of the node-engine's witness window for it;
+// and, where within is set, passed at within after the send on fewer, if it was healthy at every reading
+// (novox/hq ADR 0352). said names the rule in the gate's text.
+type gateRule struct {
+	passes    int
+	within    time.Duration
+	witnessed bool
+	said      string
+}
+
+// gateRuleOf is a module's gate rule (novox/hq ADR 0351): a core module keeps three readings only where its
+// build, broken on every machine, could not receive its own fix — the node-engine, which applies every send,
+// and the mesh's resolver, which gives every machine the bus's name (decisions 2, 3 and 6); the bus is never
+// walked through a gate but kept so (decision 7). The controller, run on one machine, and the tool runner,
+// whose fix the node-engine applies, are judged by one reading after the witness window (decisions 1 and 4);
+// mesh-delivery, whose fix goes the controller's own path, by one (decision 5); a leaf module by one (ADR 0304
+// decision 3).
+func gateRuleOf(module string, m catalogue.Manifest) gateRule {
+	switch {
+	case coreComponent(module) == lease.ComponentController:
+		return gateRule{passes: 1, witnessed: true, said: "the controller's rule: one reading once it is ready, " +
+			"after the node-engine's witness window (novox/hq ADR 0351)"}
+	case coreComponent(module) == lease.ComponentNodeTools:
+		return gateRule{passes: 1, witnessed: true, said: "the tool runner's rule: one reading once it answers, " +
+			"after the node-engine's witness window (novox/hq ADR 0351)"}
+	case module == catalogue.DeliverySeat:
+		return gateRule{passes: 1, said: "mesh-delivery's rule: one reading (novox/hq ADR 0351)"}
+	case coreModule(module, m):
+		return gateRule{passes: gatePasses, within: gateWithin, said: fmt.Sprintf("the core's rule: %d readings, "+
+			"or healthy throughout %s after the send (novox/hq ADR 0352)", gatePasses, gateWithin)}
 	}
-	return gateLeafPasses, gateLeafSettles
+	r := gateRule{passes: gateLeafPasses, said: "a leaf module's rule: one reading (novox/hq ADR 0304)"}
+	if gateLeafSettles {
+		r.within = gateWithin
+		r.said = fmt.Sprintf("a leaf module's rule, judged as the core: %d readings, or healthy throughout %s after the send",
+			gateLeafPasses, gateWithin)
+	}
+	return r
+}
+
+// gateFloor is the earliest a module's reading counts by its rule: the send and, for a witnessed module, the
+// end of the node-engine's witness window on every machine judged (novox/hq ADR 0351 decisions 1 and 4). A
+// module under the three-reading rule counts from the send (novox/hq ADR 0352). The window opens when the node-engine starts the build, which is before the machine reports it
+// applied (applied, as the gate first read it) and, for the controller, before the new controller took the
+// lease (holder): the later of those, the send's time at the least, plus the window, is never before its end.
+// A controller that starts again takes the lease again, and so moves its floor on. Pure.
+func gateFloor(module string, rule gateRule, since time.Time, machines []string, applied map[string]time.Time,
+	holder *lease.Holder) time.Time {
+	floor := since
+	if !rule.witnessed {
+		return floor
+	}
+	for _, n := range machines {
+		start := since
+		if at, read := applied[n]; read && at.After(start) {
+			start = at
+		}
+		if coreComponent(module) == lease.ComponentController && holder != nil && holder.Taken.After(start) {
+			start = holder.Taken
+		}
+		if end := start.Add(gateWitnessWindow); end.After(floor) {
+			floor = end
+		}
+	}
+	return floor
 }
 
 // gateProbe is the registry's row for the gate's verdicts and the witnesses' rollbacks: its conditions
@@ -501,6 +572,13 @@ func judgeGate(ctx context.Context, open *stores, p *inventory.Plan, module stri
 	return judgeMoves(ctx, open, g, pairs, now)
 }
 
+// dueAtTheMost says a gate healthy since its send has reached gateWithin and not been judged since: the one
+// judging that may come sooner than gateEvery after the last pass (novox/hq ADR 0352).
+func dueAtTheMost(g *inventory.PlanGate, now time.Time) bool {
+	most := g.Since.Add(gateWithin)
+	return !g.Faulted && g.LastPass != nil && !now.Before(most) && g.LastPass.Before(most)
+}
+
 // judged is one module on one machine, as a gate judges it.
 type judged struct{ module, node string }
 
@@ -511,7 +589,9 @@ func judgeMoves(ctx context.Context, open *stores, g *inventory.PlanGate, pairs
 	if g.Verdict != "" {
 		return g.Verdict, nil
 	}
-	if g.LastPass != nil && now.Sub(*g.LastPass) < gateEvery {
+	// A judging comes gateEvery after the last pass, and once at gateWithin after the send whatever the spacing:
+	// a module healthy throughout is never held past it (novox/hq ADR 0352).
+	if g.LastPass != nil && now.Sub(*g.LastPass) < gateEvery && !dueAtTheMost(g, now) {
 		return "", nil
 	}
 	for _, c := range g.Carried {
@@ -544,6 +624,11 @@ func judgeMoves(ctx context.Context, open *stores, g *inventory.PlanGate, pairs
 			facts.sentBuilds[j.node] = builds
 		}
 	}
+	// **A busy container on a judged machine holds the judging before it starts** (novox/hq ADR 0335 §4): the
+	// walk says it waits there, and its gate starts at the report that says the container replaced.
+	if busyWait(g, pairs, facts, now) {
+		return "", nil
+	}
 	// **What is wrong with a machine itself is the machine's** (novox/hq issue 281): read once for each
 	// machine judged, apart from what is wrong with a module there, and never pinned on the module the
 	// gate happens to be kept on.
@@ -568,6 +653,9 @@ func judgeMoves(ctx context.Context, open *stores, g *inventory.PlanGate, pairs
 	for _, j := range pairs {
 		w := words[j.node]
 		h, said := judgeHealth(j.module, coreComponent(j.module), shelf[j.module], j.node, *g.Since, w.facts)
+		if why, still := busyStill(j, facts); still && (h == healthGood || h == healthPerson) {
+			h, said = healthNotYet, why
+		}
 		if h == healthGood || h == healthPerson {
 			if on, named := w.on[j.module]; named {
 				h, said = healthNotYet, on
@@ -608,6 +696,51 @@ func judgeMoves(ctx context.Context, open *stores, g *inventory.PlanGate, pairs
 			why = said
 		}
 	}
+	// **Each module counts its readings by its own rule** (novox/hq ADR 0351): from when the gate first read
+	// each machine report its send applied, and who holds the controller lease, the earliest its reading counts.
+	if g.Applied == nil {
+		g.Applied = map[string]time.Time{}
+	}
+	for node := range byMachine {
+		r, said := facts.reports[node]
+		if _, read := g.Applied[node]; !read && said && r.At != nil && r.Outcome == inventory.OutcomeApplied &&
+			facts.reportedOn(node, r) {
+			g.Applied[node] = *r.At
+		}
+	}
+	rules, floors := map[string]gateRule{}, map[string]time.Time{}
+	for _, m := range modules {
+		var on []string
+		for _, j := range pairs {
+			if j.module == m {
+				on = append(on, j.node)
+			}
+		}
+		rules[m] = gateRuleOf(m, shelf[m])
+		floors[m] = gateFloor(m, rules[m], *g.Since, on, g.Applied, facts.holder)
+	}
+	tallyGate(g, gateJudging{modules: modules, reading: reading, waits: waits, worst: worst, why: why,
+		rules: rules, floors: floors}, now)
+	return g.Verdict, nil
+}
+
+// gateJudging is one judging's readings, as tallyGate counts them: the modules judged, each one's reading
+// (the worst of its machines'), its waits for a person, the send's worst reading and why, and each module's
+// rule and the earliest its reading counts.
+type gateJudging struct {
+	modules []string
+	reading map[string]health
+	waits   map[string]string
+	worst   health
+	why     string
+	rules   map[string]gateRule
+	floors  map[string]time.Time
+}
+
+// tallyGate counts one judging into the gate: a pass counted, a pass missed (and why), or the verdict. Pure but
+// for the gate it writes.
+func tallyGate(g *inventory.PlanGate, j gateJudging, now time.Time) {
+	modules, reading, waits, worst, why := j.modules, j.reading, j.waits, j.worst, j.why
 	if g.Healthy == nil {
 		g.Healthy = map[string]int{}
 	}
@@ -623,38 +756,53 @@ func judgeMoves(ctx context.Context, open *stores, g *inventory.PlanGate, pairs
 			delete(g.HealthyAt, m)
 			continue
 		}
-		// **A pass is counted only gateEvery after the one before** (issue 318 review): a send judged more
-		// often while another module beside it is not yet healthy counts no faster.
-		if at, counted := g.HealthyAt[m]; !counted || now.Sub(at) >= gateEvery {
-			g.Healthy[m]++
-			g.HealthyAt[m] = now
-		}
 		if w := waits[m]; w != "" {
 			if g.Waits == nil {
 				g.Waits = map[string]string{}
 			}
 			g.Waits[m] = w
 		}
+		// **A reading counts only from the module's floor** (novox/hq ADR 0351 decisions 1 and 4): the
+		// controller's and the tool runner's after the witness window, any other module's from the send.
+		if now.Before(j.floors[m]) {
+			continue
+		}
+		// **A pass is counted only gateEvery after the one before** (issue 318 review): a send judged more
+		// often while another module beside it is not yet healthy counts no faster.
+		if at, counted := g.HealthyAt[m]; !counted || now.Sub(at) >= gateEvery {
+			g.Healthy[m]++
+			g.HealthyAt[m] = now
+		}
 	}
-	settled := now.Sub(*g.Since) >= gateSettle
-	// What the send needs is what its most demanding module needs: a send carrying a core module is judged
-	// as the core.
-	wants, settles := 0, false
+	// What the send needs is what its most demanding module needs — the most readings, then the latest
+	// floor: a send carrying the node-engine is judged by its three readings, or by being healthy throughout
+	// its two minutes (novox/hq ADR 0352).
+	wants, floor, within, said := 0, time.Time{}, time.Duration(0), ""
 	for _, m := range modules {
-		p, s := gateWants(m, shelf[m])
-		wants, settles = max(wants, p), settles || s
+		r, f := j.rules[m], j.floors[m]
+		if r.passes > wants || (r.passes == wants && f.After(floor)) {
+			wants, within, said = r.passes, r.within, r.said
+		}
+		if f.After(floor) {
+			floor = f
+		}
 	}
 	if len(modules) == 0 {
 		// A send judged on no machine of its modules (its first machine not running them) has no class to
 		// be judged by: it is judged as the core, never passed at once without a reading.
-		wants, settles = gatePasses, true
+		wants, floor, within = gatePasses, *g.Since, gateWithin
+		said = fmt.Sprintf("the core's rule: %d readings, or healthy throughout %s after the send", gatePasses, gateWithin)
+	}
+	// heldLongEnough is a rule's most: within after the send, healthy at every reading since it.
+	heldLongEnough := func(within time.Duration) bool {
+		return within > 0 && !g.Faulted && !now.Before(g.Since.Add(within))
 	}
 	g.Wants = wants
-	// A module's own pass is its own class's: a leaf beside a core module that fails keeps its build after
+	// A module's own pass is its own rule's: a leaf beside a core module that fails keeps its build after
 	// its one reading, and only what did not pass is put back (issue 318's rule, by class since issue 524).
 	passedAlone := func(m string) bool {
-		p, s := gateWants(m, shelf[m])
-		return (settled || !s) && reading[m] <= healthPerson && g.Healthy[m] >= p
+		r := j.rules[m]
+		return reading[m] <= healthPerson && (g.Healthy[m] >= r.passes || (g.Healthy[m] >= 1 && heldLongEnough(r.within)))
 	}
 	// fail decides the send failed: what passed on its own keeps its pass, everything else is put back.
 	fail := func(why string) {
@@ -671,6 +819,7 @@ func judgeMoves(ctx context.Context, open *stores, g *inventory.PlanGate, pairs
 	pastBound := now.Sub(*g.Since) > gateBound
 	switch {
 	case worst == healthBroken:
+		g.Faulted = true
 		g.Read(now, false, g.BrokenWhy)
 		var judging []string
 		for _, m := range modules {
@@ -689,25 +838,36 @@ func judgeMoves(ctx context.Context, open *stores, g *inventory.PlanGate, pairs
 	case worst == healthWaiting:
 		// Waiting on a provider that is unhealthy: not a pass, and not a failure at the bound either —
 		// the provider's own condition says what is wrong (ADR 0240 rule 5).
+		g.Faulted = g.Faulted || g.HealthySeen // not healthy after a healthy reading; before one, still starting
 		g.Passes, g.LastPass, g.Last, g.Failing = 0, nil, why, failing
 		g.Read(now, false, why)
 	case worst == healthNotYet:
+		g.Faulted = g.Faulted || g.HealthySeen // not healthy after a healthy reading; before one, still starting
 		g.Passes, g.LastPass, g.Last, g.Failing = 0, nil, why, failing
 		g.Read(now, false, why)
 		if pastBound {
 			fail(fmt.Sprintf("not healthy within %s of its apply: %s", gateBound, why))
 		}
+	case now.Before(floor):
+		// Healthy before its rule lets a reading count: not a pass yet, and not a fault (novox/hq ADR 0351).
+		g.HealthySeen = true
+		// The bound still holds: a module that cannot be read healthy after its floor fails at it.
+		g.Last, g.Failing = fmt.Sprintf("healthy, and a reading counts from %s by %s",
+			floor.UTC().Format(time.RFC3339), said), nil
+		if pastBound {
+			fail(fmt.Sprintf("not judged within %s of its apply: %s", gateBound, g.Last))
+		}
 	default:
 		// Healthy, or waiting for a person (ADR 0254): a pass, the wait carried along in the verdict.
+		g.HealthySeen = true
 		g.Passes++
 		g.LastPass, g.Last, g.Failing = &now, "", nil
 		g.Read(now, true, "")
-		if g.Passes >= wants && (settled || !settles) {
-			decide(g, inventory.GatePassed, fmt.Sprintf("healthy %d times over %s", g.Passes,
-				now.Sub(*g.Since).Round(time.Second))+waitsSaid(g.Waits), now)
+		if g.Passes >= wants || heldLongEnough(within) {
+			decide(g, inventory.GatePassed, fmt.Sprintf("healthy %d times over %s, by %s", g.Passes,
+				now.Sub(*g.Since).Round(time.Second), said)+waitsSaid(g.Waits), now)
 		}
 	}
-	return g.Verdict, nil
 }
 
 // judgedCommits is the commit of each module a gate judges: the gate's own To for its module, and each
@@ -1372,6 +1532,9 @@ func gateLine(g *inventory.PlanGate) string {
 	case inventory.GateFailed:
 		what = "FAILED"
 	}
+	if g.Verdict == "" && g.Waiting() {
+		what = "waits for a busy container on " + g.Busy.Machine
+	}
 	line := fmt.Sprintf("gate on %s: %s", strings.Join(g.Machines, ", "), what)
 	if g.Component != "" {
 		line += " (core: " + g.Component + ")"

cmd/mesh-controller/gate_followup_test.go

@@ -21,11 +21,15 @@ import (
 // wait, and a provider waiting for a login says who waits on it.
 
 // withGateBounds sets the gate's bounds for one test.
-func withGateBounds(t *testing.T, settle, every, bound time.Duration) {
+func withGateBounds(t *testing.T, within, every, bound time.Duration) {
 	t.Helper()
-	wasSettle, wasEvery, wasBound := gateSettle, gateEvery, gateBound
-	gateSettle, gateEvery, gateBound = settle, every, bound
-	t.Cleanup(func() { gateSettle, gateEvery, gateBound = wasSettle, wasEvery, wasBound })
+	wasWithin, wasEvery, wasBound := gateWithin, gateEvery, gateBound
+	// The witness window is the node-engine's, from a start no test makes (novox/hq ADR 0351).
+	wasWindow := gateWitnessWindow
+	gateWitnessWindow = 0
+	t.Cleanup(func() { gateWitnessWindow = wasWindow })
+	gateWithin, gateEvery, gateBound = within, every, bound
+	t.Cleanup(func() { gateWithin, gateEvery, gateBound = wasWithin, wasEvery, wasBound })
 }
 
 // factsOn is a judging's facts for one machine that applied its send: the node tools answer, and what it says
@@ -56,7 +60,7 @@ func TestAFaultBeforeTheSettleTimeWaitsForTheModuleBesideIt(t *testing.T) {
 	judgeLeavesAsTheCore(t)
 	open := aMesh(t)
 	ctx := t.Context()
-	withGateBounds(t, 150*time.Millisecond, 20*time.Millisecond, 10*time.Second)
+	withGateBounds(t, time.Hour, 20*time.Millisecond, 10*time.Second)
 	since := time.Now().Add(-time.Second)
 	base := factsOn(t, "laptop", since, healthyContainer("app"))
 	wasGather := gatherGateFacts
@@ -97,7 +101,7 @@ const broker_runtime = "node-tools"
 func TestAPassIsCountedNoFasterThanTheGatesSpacing(t *testing.T) {
 	open := aMesh(t)
 	ctx := t.Context()
-	withGateBounds(t, 0, time.Hour, time.Hour)
+	withGateBounds(t, time.Hour, time.Hour, time.Hour)
 	since := time.Now().Add(-time.Minute)
 	base := factsOn(t, "laptop", since, healthyContainer("app"), inventory.ResourceHealth{Module: "late",
 		Resource: "late.web", Kind: "container", Target: "late", State: link.StateUnhealthy, Reason: "down"})
@@ -376,7 +380,7 @@ func TestABrokenModuleIsPutBackAtOnceAndTheOneBesideItGetsItsOwnVerdict(t *testi
 		f.health = map[string]inventory.NodeHealth{"laptop": {Node: "laptop", HeardAt: now, Resources: []inventory.ResourceHealth{app}}}
 		return f, nil
 	}
-	withGateBounds(t, 100*time.Millisecond, 0, 10*time.Second)
+	withGateBounds(t, time.Hour, 0, 10*time.Second)
 
 	release := func() inventory.Plan {
 		t.Helper()

cmd/mesh-controller/gate_rule_test.go

@@ -0,0 +1,338 @@
+package main
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+	"github.com/novox/mesh-controller/internal/inventory"
+	"github.com/novox/mesh-controller/internal/lease"
+)
+
+// The first-node gate's readings by module (novox/hq ADR 0351, ADR 0352): the controller and the tool runner pass
+// on one reading after the node-engine's witness window, mesh-delivery on one, the node-engine and the mesh's
+// resolver on their third healthy reading and never later than two minutes while healthy; the bus is kept so.
+
+// withTheGatesTimes sets the gate's production bounds for a test, whatever another test left.
+func withTheGatesTimes(t *testing.T) {
+	t.Helper()
+	wasWithin, wasEvery, wasBound, wasWindow := gateWithin, gateEvery, gateBound, gateWitnessWindow
+	wasPasses, wasLeafPasses, wasLeafSettles := gatePasses, gateLeafPasses, gateLeafSettles
+	gateWithin, gateEvery, gateBound, gateWitnessWindow = 2*time.Minute, 40*time.Second, 10*time.Minute, 60*time.Second
+	gatePasses, gateLeafPasses, gateLeafSettles = 3, 1, false
+	t.Cleanup(func() {
+		gateWithin, gateEvery, gateBound, gateWitnessWindow = wasWithin, wasEvery, wasBound, wasWindow
+		gatePasses, gateLeafPasses, gateLeafSettles = wasPasses, wasLeafPasses, wasLeafSettles
+	})
+}
+
+func TestEachModuleHasItsGateRule(t *testing.T) {
+	withTheGatesTimes(t)
+	for _, c := range []struct {
+		module    string
+		claims    []catalogue.Claim
+		passes    int
+		within    time.Duration
+		witnessed bool
+		said      string
+	}{
+		{"mesh-controller", nil, 1, 0, true, "the controller's rule"},
+		{"node-tools", nil, 1, 0, true, "the tool runner's rule"},
+		{catalogue.DeliverySeat, nil, 1, 0, false, "mesh-delivery's rule"},
+		{"mesh-host", nil, 3, 2 * time.Minute, false, "the core's rule"},
+		{"dnsmasq", []catalogue.Claim{{Name: resolverSeat}}, 3, 2 * time.Minute, false, "the core's rule"},
+		{"nats", nil, 3, 2 * time.Minute, false, "the core's rule"},
+		{"app", nil, 1, 0, false, "a leaf module's rule"},
+	} {
+		r := gateRuleOf(c.module, catalogue.Manifest{Module: c.module, Claims: c.claims})
+		if r.passes != c.passes || r.within != c.within || r.witnessed != c.witnessed || !strings.HasPrefix(r.said, c.said) {
+			t.Errorf("%s: %+v; want %d readings, within %s, witnessed %v, said %q", c.module, r, c.passes, c.within,
+				c.witnessed, c.said)
+		}
+	}
+}
+
+// Every module that was core stays core for its delivery budget and its walk: only its readings change.
+func TestTheCoreStaysTheCore(t *testing.T) {
+	for _, m := range []string{"mesh-controller", "mesh-host", "node-tools", "nats", catalogue.DeliverySeat} {
+		if !coreModule(m, catalogue.Manifest{Module: m}) {
+			t.Errorf("%s is no longer judged as the core for its class", m)
+		}
+	}
+	if !coreModule("dnsmasq", catalogue.Manifest{Module: "dnsmasq", Claims: []catalogue.Claim{{Name: resolverSeat}}}) {
+		t.Error("the resolver's holder is no longer judged as the core for its class")
+	}
+}
+
+// gateOn judges one module on one machine, healthy at every reading.
+type gateOn struct {
+	module, node string
+	g            *inventory.PlanGate
+	holder       *lease.Holder
+}
+
+func aGateOn(module, node string, since time.Time) *gateOn {
+	return &gateOn{module: module, node: node, g: &inventory.PlanGate{Machines: []string{node}, Since: &since,
+		Applied: map[string]time.Time{}}}
+}
+
+func (o *gateOn) read(at time.Time, h health, why string) {
+	r := gateRuleOf(o.module, catalogue.Manifest{Module: o.module})
+	floor := gateFloor(o.module, r, *o.g.Since, []string{o.node}, o.g.Applied, o.holder)
+	tallyGate(o.g, gateJudging{modules: []string{o.module}, reading: map[string]health{o.module: h},
+		worst: h, why: why, rules: map[string]gateRule{o.module: r}, floors: map[string]time.Time{o.module: floor}}, at)
+}
+
+func TestTheControllerPassesOnOneReadingAfterTheWitnessWindow(t *testing.T) {
+	withTheGatesTimes(t)
+	sent := time.Date(2026, 10, 13, 20, 0, 0, 0, time.UTC)
+	o := aGateOn("mesh-controller", "novox", sent)
+	o.g.Applied["novox"] = sent.Add(15 * time.Second)
+	o.holder = &lease.Holder{Instance: "new", Taken: sent.Add(20 * time.Second)}
+
+	// Ready, but inside the witness window, which opened before it took the lease: not counted.
+	for _, after := range []time.Duration{30 * time.Second, 60 * time.Second, 79 * time.Second} {
+		o.read(sent.Add(after), healthGood, "")
+		if o.g.Verdict != "" || o.g.Passes != 0 || !strings.Contains(o.g.Last, "counts from") {
+			t.Fatalf("at %s: %+v; want no reading counted inside the witness window", after, o.g)
+		}
+	}
+	o.read(sent.Add(80*time.Second), healthGood, "")
+	if o.g.Verdict != inventory.GatePassed || o.g.Passes != 1 || o.g.Wants != 1 {
+		t.Fatalf("after the witness window: %+v; want passed on one reading", o.g)
+	}
+	if !strings.Contains(o.g.Why, "healthy 1 times") || !strings.Contains(o.g.Why, "the controller's rule") ||
+		!strings.Contains(o.g.Why, "ADR 0351") {
+		t.Errorf("the verdict says %q; want the rule it applied", o.g.Why)
+	}
+}
+
+// A controller that starts again takes the lease again: its witness window starts again, and so does the
+// gate's wait.
+func TestAControllerThatStartsAgainWaitsOutItsNewWindow(t *testing.T) {
+	withTheGatesTimes(t)
+	sent := time.Now()
+	o := aGateOn("mesh-controller", "novox", sent)
+	o.g.Applied["novox"] = sent.Add(10 * time.Second)
+	o.holder = &lease.Holder{Instance: "again", Taken: sent.Add(70 * time.Second)}
+	o.read(sent.Add(90*time.Second), healthGood, "")
+	if o.g.Verdict != "" {
+		t.Fatalf("passed %s after a start the witness still judges: %+v", 20*time.Second, o.g)
+	}
+	o.read(sent.Add(130*time.Second), healthGood, "")
+	if o.g.Verdict != inventory.GatePassed {
+		t.Fatalf("not passed after the new window: %+v", o.g)
+	}
+}
+
+// Without the lease's word (a controller carried by another gate), the window counts from the applied report,
+// and from the send at the least.
+func TestTheWitnessWindowCountsFromTheSendAtTheLeast(t *testing.T) {
+	withTheGatesTimes(t)
+	sent := time.Now()
+	r := gateRuleOf("mesh-controller", catalogue.Manifest{})
+	if f := gateFloor("mesh-controller", r, sent, []string{"novox"}, nil, nil); !f.Equal(sent.Add(time.Minute)) {
+		t.Errorf("floor %s after the send; want 1m", f.Sub(sent))
+	}
+	if f := gateFloor("node-tools", gateRuleOf("node-tools", catalogue.Manifest{}), sent, []string{"ace"},
+		map[string]time.Time{"ace": sent.Add(12 * time.Second)}, nil); !f.Equal(sent.Add(72 * time.Second)) {
+		t.Errorf("the tool runner's floor %s after the send; want 1m12s", f.Sub(sent))
+	}
+}
+
+// A controller that a witness put back, or that never becomes ready, fails its gate as before.
+func TestAControllerThatFailsIsStillFailed(t *testing.T) {
+	withTheGatesTimes(t)
+	sent := time.Now()
+	o := aGateOn("mesh-controller", "novox", sent)
+	o.read(sent.Add(30*time.Second), healthBroken, "the witness on novox judged the controller and rolled-back")
+	if o.g.Verdict != inventory.GateFailed {
+		t.Fatalf("a controller put back by its witness: %+v; want failed", o.g)
+	}
+	o = aGateOn("mesh-controller", "novox", sent)
+	o.read(sent.Add(5*time.Minute), healthNotYet, "the controller holding the lease does not say it is ready")
+	if o.g.Verdict != "" {
+		t.Fatalf("failed before the bound: %+v", o.g)
+	}
+	o.read(sent.Add(10*time.Minute+time.Second), healthNotYet, "the controller holding the lease does not say it is ready")
+	if o.g.Verdict != inventory.GateFailed || !strings.Contains(o.g.Why, "not healthy within") {
+		t.Fatalf("never ready: %+v; want failed at the bound", o.g)
+	}
+}
+
+// threeReadings judges a module under the three-reading rule on one machine, the send at sent.
+func threeReadings(t *testing.T, module string, sent time.Time) (*inventory.PlanGate, func(time.Duration, health)) {
+	t.Helper()
+	g := &inventory.PlanGate{Machines: []string{"ace"}, Since: &sent}
+	rule := gateRuleOf(module, catalogue.Manifest{Module: module, Claims: []catalogue.Claim{{Name: resolverSeat}}})
+	floor := gateFloor(module, rule, sent, []string{"ace"}, nil, nil)
+	return g, func(after time.Duration, h health) {
+		why := ""
+		if h != healthGood {
+			why = "the node-engine reports another build"
+		}
+		tallyGate(g, gateJudging{modules: []string{module}, reading: map[string]health{module: h}, worst: h, why: why,
+			rules: map[string]gateRule{module: rule}, floors: map[string]time.Time{module: floor}}, sent.Add(after))
+	}
+}
+
+// A healthy node-engine or resolver passes at its third healthy reading, 40 s apart from the apply: before two
+// minutes (novox/hq ADR 0352).
+func TestTheNodeEngineAndTheResolverPassAtTheirThirdReading(t *testing.T) {
+	withTheGatesTimes(t)
+	for _, module := range []string{"mesh-host", "dnsmasq"} {
+		g, judge := threeReadings(t, module, time.Now())
+		judge(15*time.Second, healthGood)
+		judge(55*time.Second, healthGood)
+		if g.Verdict != "" || g.Passes != 2 {
+			t.Fatalf("%s: after two readings %+v; want still judging", module, g)
+		}
+		judge(95*time.Second, healthGood)
+		if g.Verdict != inventory.GatePassed || g.Passes != 3 || g.Wants != 3 ||
+			!strings.Contains(g.Why, "over 1m35s") || !strings.Contains(g.Why, "the core's rule: 3 readings") {
+			t.Fatalf("%s: after three readings %+v; want passed at 1m35s by the core's rule", module, g)
+		}
+	}
+}
+
+// One healthy throughout whose readings came late passes at two minutes on the readings it has; the judging at
+// two minutes comes sooner than the spacing after the last pass.
+func TestAHealthyNodeEngineIsNeverHeldPastTwoMinutes(t *testing.T) {
+	withTheGatesTimes(t)
+	sent := time.Now()
+	last := sent.Add(100 * time.Second)
+	held := &inventory.PlanGate{Since: &sent, LastPass: &last}
+	if dueAtTheMost(held, sent.Add(119*time.Second)) || !dueAtTheMost(held, sent.Add(2*time.Minute)) {
+		t.Fatal("the judging at two minutes is not due, or is due before")
+	}
+	held.Faulted = true
+	if dueAtTheMost(held, sent.Add(2*time.Minute)) {
+		t.Fatal("a send that was not healthy at a reading is judged at two minutes")
+	}
+
+	g, judge := threeReadings(t, "mesh-host", time.Now())
+	judge(100*time.Second, healthGood)
+	judge(2*time.Minute, healthGood)
+	if g.Verdict != inventory.GatePassed || g.Passes != 2 {
+		t.Fatalf("late readings, healthy throughout, at two minutes: %+v; want passed on two", g)
+	}
+	g, judge = threeReadings(t, "mesh-host", time.Now())
+	judge(2*time.Minute, healthGood)
+	if g.Verdict != inventory.GatePassed || g.Passes != 1 {
+		t.Fatalf("one healthy reading, at two minutes: %+v; want passed on it", g)
+	}
+}
+
+// A reading not yet healthy before the first healthy one is the build still starting: the two minutes still hold.
+func TestANodeEngineStillStartingKeepsItsTwoMinutes(t *testing.T) {
+	withTheGatesTimes(t)
+	g, judge := threeReadings(t, "mesh-host", time.Now())
+	judge(10*time.Second, healthNotYet)
+	judge(100*time.Second, healthGood)
+	judge(2*time.Minute, healthGood)
+	if g.Verdict != inventory.GatePassed || g.Faulted {
+		t.Fatalf("%+v; want passed at two minutes", g)
+	}
+}
+
+// A reading that is not healthy after a healthy one takes the two minutes away: the module needs its three readings, and one
+// never healthy fails at the bound and is put back; one found broken fails.
+func TestANodeEngineThatFailsAReadingIsNotPassedAtTwoMinutes(t *testing.T) {
+	withTheGatesTimes(t)
+	g, judge := threeReadings(t, "mesh-host", time.Now())
+	judge(20*time.Second, healthNotYet)
+	judge(60*time.Second, healthGood)
+	judge(100*time.Second, healthGood)
+	judge(2*time.Minute+10*time.Second, healthGood)
+	if g.Verdict != inventory.GatePassed || g.Passes != 3 {
+		t.Fatalf("%+v; want passed only on its third healthy reading", g)
+	}
+	g, judge = threeReadings(t, "mesh-host", time.Now())
+	judge(60*time.Second, healthGood)
+	judge(100*time.Second, healthNotYet)
+	judge(2*time.Minute, healthGood)
+	if g.Verdict != "" || !g.Faulted {
+		t.Fatalf("passed at two minutes after a reading that was not healthy: %+v", g)
+	}
+	judge(10*time.Minute+time.Second, healthNotYet)
+	if g.Verdict != inventory.GateFailed || !strings.Contains(g.Why, "not healthy within") {
+		t.Fatalf("never healthy again: %+v; want failed at the bound", g)
+	}
+	g, judge = threeReadings(t, "mesh-host", time.Now())
+	judge(60*time.Second, healthGood)
+	judge(100*time.Second, healthBroken)
+	if g.Verdict != inventory.GateFailed {
+		t.Fatalf("a broken reading: %+v; want failed, to be put back", g)
+	}
+}
+
+// The tool runner passes on one reading after its witness window; mesh-delivery on one, at once.
+func TestTheToolRunnerAndMeshDeliveryPassOnOneReading(t *testing.T) {
+	withTheGatesTimes(t)
+	sent := time.Now()
+	o := aGateOn("node-tools", "ace", sent)
+	o.g.Applied["ace"] = sent.Add(10 * time.Second)
+	o.read(sent.Add(30*time.Second), healthGood, "")
+	if o.g.Verdict != "" {
+		t.Fatalf("the tool runner passed inside its witness window: %+v", o.g)
+	}
+	o.read(sent.Add(70*time.Second), healthGood, "")
+	if o.g.Verdict != inventory.GatePassed || o.g.Passes != 1 || !strings.Contains(o.g.Why, "the tool runner's rule") {
+		t.Fatalf("the tool runner: %+v; want passed on one reading", o.g)
+	}
+
+	o = aGateOn(catalogue.DeliverySeat, "novox", sent)
+	o.read(sent.Add(5*time.Second), healthGood, "")
+	if o.g.Verdict != inventory.GatePassed || o.g.Passes != 1 || !strings.Contains(o.g.Why, "mesh-delivery's rule") {
+		t.Fatalf("mesh-delivery: %+v; want passed on one reading", o.g)
+	}
+}
+
+// A dip after a healthy reading taken before the controller's witness floor is a fault: the send is not passed at
+// two minutes (novox/hq ADR 0352 decision 3).
+func TestADipAfterAnUncountedHealthyReadingIsAFault(t *testing.T) {
+	withTheGatesTimes(t)
+	sent := time.Now()
+	g := &inventory.PlanGate{Machines: []string{"novox"}, Since: &sent}
+	modules := []string{"mesh-controller", "mesh-host"}
+	rules, floors := map[string]gateRule{}, map[string]time.Time{}
+	for _, m := range modules {
+		rules[m] = gateRuleOf(m, catalogue.Manifest{Module: m})
+	}
+	floors["mesh-host"] = sent
+	floors["mesh-controller"] = sent.Add(90 * time.Second)
+	judge := func(after time.Duration, h health) {
+		tallyGate(g, gateJudging{modules: modules, reading: map[string]health{"mesh-controller": h, "mesh-host": h},
+			worst: h, why: "not yet", rules: rules, floors: floors}, sent.Add(after))
+	}
+	judge(30*time.Second, healthGood)
+	if g.Passes != 0 {
+		t.Fatalf("a reading before the controller's floor was counted: %+v", g)
+	}
+	judge(70*time.Second, healthNotYet)
+	judge(2*time.Minute, healthGood)
+	if !g.Faulted || g.Verdict != "" {
+		t.Fatalf("%+v; want the dip a fault, and no pass at two minutes", g)
+	}
+}
+
+// A send carrying the controller and the node-engine is judged by the node-engine's three readings.
+func TestASendIsJudgedByItsMostDemandingRule(t *testing.T) {
+	withTheGatesTimes(t)
+	sent := time.Now()
+	g := &inventory.PlanGate{Machines: []string{"novox"}, Since: &sent}
+	modules := []string{"mesh-controller", "mesh-host"}
+	rules, floors := map[string]gateRule{}, map[string]time.Time{}
+	for _, m := range modules {
+		rules[m] = gateRuleOf(m, catalogue.Manifest{Module: m})
+		floors[m] = gateFloor(m, rules[m], sent, []string{"novox"}, nil, nil)
+	}
+	for _, after := range []time.Duration{70 * time.Second, 110 * time.Second} {
+		tallyGate(g, gateJudging{modules: modules, reading: map[string]health{"mesh-controller": healthGood,
+			"mesh-host": healthGood}, worst: healthGood, rules: rules, floors: floors}, sent.Add(after))
+	}
+	if g.Verdict != "" || g.Wants != 3 || g.Passes != 2 || g.Healthy["mesh-controller"] != 2 {
+		t.Fatalf("%+v; want the send judged by the node-engine's three readings, the controller's own counted", g)
+	}
+}

cmd/mesh-controller/gate_test.go

@@ -124,10 +124,14 @@ func aGateMesh(t *testing.T) *gateMesh {
 	}
 	t.Cleanup(func() { gatherGateFacts = wasGather })
 
-	wasSettle, wasEvery, wasBound := gateSettle, gateEvery, gateBound
+	wasWithin, wasEvery, wasBound := gateWithin, gateEvery, gateBound
+	// The witness window is the node-engine's, from a start no test makes (novox/hq ADR 0351).
+	wasWindow := gateWitnessWindow
+	gateWitnessWindow = 0
+	t.Cleanup(func() { gateWitnessWindow = wasWindow })
 	// One judging per advance until a test says otherwise: a pass waits gateEvery for the next.
-	gateSettle, gateEvery = 0, time.Hour
-	t.Cleanup(func() { gateSettle, gateEvery, gateBound = wasSettle, wasEvery, wasBound })
+	gateWithin, gateEvery = time.Hour, time.Hour
+	t.Cleanup(func() { gateWithin, gateEvery, gateBound = wasWithin, wasEvery, wasBound })
 
 	built := time.Now().UTC()
 	plan := inventory.Plan{ID: "plan-gate", Repository: "novox/mesh-catalog", Branch: "main", Commit: "c2",
@@ -272,7 +276,7 @@ func TestABuildThatPassesItsGateRollsEverywhereUnattended(t *testing.T) {
 func TestALeafModulePassesOnOneHealthyReading(t *testing.T) {
 	g := aGateMesh(t)
 	ctx := t.Context()
-	gateSettle = time.Hour    // a core module could not pass for an hour
+	gateWithin = time.Hour    // a core module could not pass on fewer readings for an hour
 	advancePlans(ctx, g.open) // the first machine is sent the new build
 	advancePlans(ctx, g.open) // one healthy judging
 	p := g.plan(t)
@@ -285,31 +289,6 @@ func TestALeafModulePassesOnOneHealthyReading(t *testing.T) {
 	}
 }
 
-// Which modules are judged as the core: those on the controller's own path and the resolver's holder, three
-// readings after the settle time; every other module one (novox/hq ADR 0282 decision 1, ADR 0304 decision 3).
-func TestAModuleIsJudgedByItsClass(t *testing.T) {
-	for _, c := range []struct {
-		module  string
-		claims  []catalogue.Claim
-		passes  int
-		settles bool
-	}{
-		{"app", nil, 1, false},
-		{"nzbget", nil, 1, false},
-		{"mesh-controller", nil, 3, true},
-		{"mesh-host", nil, 3, true},
-		{"node-tools", nil, 3, true},
-		{"nats", nil, 3, true},
-		{catalogue.DeliverySeat, nil, 3, true},
-		{"dnsmasq", []catalogue.Claim{{Name: resolverSeat}}, 3, true},
-	} {
-		p, s := gateWants(c.module, catalogue.Manifest{Module: c.module, Claims: c.claims})
-		if p != c.passes || s != c.settles {
-			t.Errorf("%s: %d passes, settles %v; want %d, %v", c.module, p, s, c.passes, c.settles)
-		}
-	}
-}
-
 // A first machine that never becomes healthy fails its gate at the bound, and is put back.
 func TestABuildNeverHealthyFailsAtTheBound(t *testing.T) {
 	judgeLeavesAsTheCore(t)

cmd/mesh-controller/main.go

@@ -104,6 +104,8 @@ func run() error {
 		return replayCommand(ctx, args[1:])
 	case "kill":
 		return killCommand(ctx, args[1:])
+	case "forget-checks":
+		return forgetChecksCommand(ctx, args[1:])
 	case "pause", "resume":
 		return pauseCommand(ctx, args[0], args[1:])
 	case "collection":
@@ -429,8 +431,14 @@ func (b builds) Built(ctx context.Context, result link.BuildResult) error {
 	}
 	fmt.Printf("%s: %s %s registered, built on %s from %s\n",
 		result.ID, manifest.Module, manifest.Version, result.On, short(result.Commit))
+	// What the walk's build did, kept on the walk whose ask it answers (novox/hq ADR 0350 §4); a build seat from
+	// before it says nothing, and that is what is kept.
+	made := result.MadeWords()
+	if result.Reused != "" || result.BuiltWhy != "" {
+		fmt.Printf("%s: %s %s\n", result.ID, manifest.Module, made)
+	}
 	saysWhenThePolicyActs(ctx, b.inv, manifest.Module)
-	planBuilt(ctx, b.open, manifest.Module, result.Commit, "", asked, result.ID)
+	planBuiltSaying(ctx, b.open, manifest.Module, result.Commit, "", asked, result.ID, made)
 	// A module registered may be one a machine is now behind: `status` is composed again.
 	statusFrom.nudge()
 	return nil

cmd/mesh-controller/merge_gate.go

@@ -576,6 +576,11 @@ func shelfWithChange(base map[string]catalogue.Manifest, sources map[string]inve
 			return err
 		}
 		m, err := catalogue.ParseManifest(raw)
+		if err == nil {
+			// Each template's text from the tree beside the manifest, as the build reads it back from the archive it
+			// packs (novox/hq ADR 0349 §2): so a change to a template alone is a change to its module.
+			m, err = catalogue.WithTemplatesFrom(m, filepath.Dir(path))
+		}
 		if err != nil {
 			if inScope(dir) {
 				failures = append(failures, fmt.Sprintf("%s: the controller judging this (%s) refuses it — %s",

cmd/mesh-controller/mesh_for_test.go

@@ -33,7 +33,21 @@ import (
 func aMesh(t *testing.T) *stores {
 	t.Helper()
 	inventory.ForTest(t) // raises the store, migrates it, and points the environment at it
-	licences.ForTest(t)  // planning reaches this one too, by name and never by connection
+	return aMeshOnTheStore(t)
+}
+
+// aMeshBefore is aMesh on a store migrated only below migration `number`, with the function that runs the
+// rest: for a test of what a migration that moves data does to what the mesh composes (novox/hq issue 651).
+func aMeshBefore(t *testing.T, number int) (*stores, func()) {
+	t.Helper()
+	_, migrate := inventory.ForTestBefore(t, number)
+	return aMeshOnTheStore(t), migrate
+}
+
+// aMeshOnTheStore is the mesh aMesh makes, on the store the environment points at.
+func aMeshOnTheStore(t *testing.T) *stores {
+	t.Helper()
+	licences.ForTest(t) // planning reaches this one too, by name and never by connection
 
 	open, err := openStores(t.Context())
 	if err != nil {

cmd/mesh-controller/modules.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"net"
 	"os"
+	"path/filepath"
 	"sort"
 	"strings"
 	"time"
@@ -127,6 +128,10 @@ func moduleCommand(ctx context.Context, args []string) error {
 		if err != nil {
 			return err
 		}
+		// A manifest handed over by hand takes each template's text from the tree beside it (novox/hq ADR 0349 §2).
+		if m, err = catalogue.WithTemplatesFrom(m, filepath.Dir(positionals[0])); err != nil {
+			return err
+		}
 		from, err := whereItComesFrom(*repo, *ref, *commit, *path, *self)
 		if err != nil {
 			return err
@@ -537,6 +542,10 @@ func settingsCommand(ctx context.Context, args []string) error {
 				if p.SetBy != "" {
 					by = "; " + p.SetBy
 				}
+				if p.Why != "" {
+					// A layer whose placement moved out of it (migration 0097): still the layer, as it stands.
+					by += "; " + p.Why
+				}
 				fmt.Printf("%s on %s, until %s (%s%s):\n  %s\n", positionals[0], where,
 					p.ReplacedAt.Local().Format("2006-01-02 15:04:05"), p.ReplacedBy, by, shown)
 			}

cmd/mesh-controller/network.go

@@ -684,7 +684,7 @@ func artifactStoreOnNetwork(ctx context.Context, inv *inventory.Inventory,
 			if !offers {
 				continue
 			}
-			serves, err := servedOnNode(ctx, inv, machine, m, catalogue.ArtifactStoreProvision)
+			serves, _, err := servedOnNode(ctx, inv, machine, m, catalogue.ArtifactStoreProvision)
 			if err != nil {
 				return "", "", false, fmt.Errorf("reading where %s puts the artifact store: %w", machine, err)
 			}

cmd/mesh-controller/placement_moved_test.go

@@ -0,0 +1,113 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// **Placement leaves the settings layers and no machine is told anything new** (novox/hq ADR 0348 clause
+// 11, issue 651). A mesh is seeded as the store holds it before migration 0097 — `places`, `accesses` and a
+// kept network among the settings, at the mesh's level and a machine's, one layer of placement only — then
+// migrated, and every machine's declaration is composed. What each machine is told of the seeded modules is
+// byte for byte what the controller before this change composed from the same seed: the golden files were
+// written by the integration branch's controller at bfc79c6 running this same test (MESH_WRITE_GOLDEN=1),
+// where there was no migration 0097 to run.
+func TestADeclarationIsTheSameAfterPlacementMoves(t *testing.T) {
+	open, migrate := aMeshBefore(t, 97)
+	ctx := t.Context()
+	inv := open.inventory
+	image := "registry.invalid:5000/library@sha256:" + strings.Repeat("a", 64)
+	register(t, open, catalogue.Manifest{Module: "library", Version: "1",
+		Accesses: []catalogue.Access{{ID: "series"}, {ID: "downloads", Mode: catalogue.AccessRead}},
+		Resources: []map[string]any{
+			{"id": "config", "type": "directory", "mode": "0750"},
+			{"id": "server", "type": "container", "image": image,
+				"volumes": []any{"${dir:config}:/config", "${access:series}:/series", "${access:downloads}:/downloads:ro"}},
+			// Today's form: a mergeable file naming no keys takes every key of the layer (ADR 0326 §3).
+			{"id": "runtime-config", "type": "file", "path": "${dir:config}/runtime.json", "mode": "0640",
+				"content": `{"log":"info"}`, "merge": "json"},
+		}})
+	register(t, open, catalogue.Manifest{Module: "found", Version: "1",
+		Resources: []map[string]any{{"id": "server", "type": "container", "image": image}}})
+	if err := inv.SetAdopted(ctx, "anchor", true); err != nil {
+		t.Fatal(err)
+	}
+	for _, l := range []struct{ node, module, values string }{
+		{"", "library", `{"accesses": {"downloads": "/storage/downloads"}, "log": "warn"}`},
+		{"anchor", "library", `{"places": {"config": {"path": "/var/lib/library/config", "owner": "1001:2000"}},
+			"accesses": {"series": "/storage/media/series"}, "workers": 4}`},
+		{"laptop", "library", `{"accesses": {"series": "/home/media/series"}}`},
+		{"anchor", "found", `{"networks": {"server": ["predecessor_default"]}}`},
+	} {
+		if l.node == "" {
+			inv.ExecForTest(t, `insert into settings (node, module, values) values (null, $1, $2)`, l.module, l.values)
+			continue
+		}
+		inv.ExecForTest(t, `insert into settings (node, module, values) select id, $2, $3 from node where name = $1`,
+			l.node, l.module, l.values)
+	}
+
+	migrate()
+	// Assigned once the store is migrated: an assignment reads the layers, as this controller holds them.
+	for _, a := range [][]string{{"anchor", "library", "found"}, {"laptop", "library"}} {
+		if _, err := assign(ctx, open, a[0], a[1:]...); err != nil {
+			t.Fatalf("assign %v: %v", a, err)
+		}
+	}
+
+	gens, err := generators(ctx, open)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, node := range []string{"anchor", "laptop"} {
+		plan, settings, err := planFor(ctx, open, node)
+		if err != nil {
+			t.Fatal(err)
+		}
+		with, _, err := renderingFor(ctx, open, node, plan, settings, gens, Allocating)
+		if err != nil {
+			t.Fatal(err)
+		}
+		composed, err := plan.Compose(with)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if len(composed.LeftOut) > 0 {
+			t.Fatalf("%s leaves out %v", node, composed.LeftOut)
+		}
+		var told []map[string]any
+		for _, r := range composed.Resources {
+			if owner := composed.Owner[r["id"].(string)]; owner == "library" || owner == "found" {
+				told = append(told, r)
+			}
+		}
+		sort.Slice(told, func(i, j int) bool { return told[i]["id"].(string) < told[j]["id"].(string) })
+		got, err := json.MarshalIndent(told, "", "  ")
+		if err != nil {
+			t.Fatal(err)
+		}
+		golden := filepath.Join("testdata", "placement-moved", node+".json")
+		if os.Getenv("MESH_WRITE_GOLDEN") != "" {
+			if err := os.MkdirAll(filepath.Dir(golden), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			if err := os.WriteFile(golden, append(got, '\n'), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			continue
+		}
+		want, err := os.ReadFile(golden)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if string(want) != string(got)+"\n" {
+			t.Errorf("%s is told something else after placement moved:\n%s\nwas:\n%s", node, got, want)
+		}
+	}
+}

cmd/mesh-controller/plan.go

@@ -289,9 +289,14 @@ func theRestOfTheMesh(ctx context.Context, inv *inventory.Inventory,
 			continue
 		}
 		caps, _ := inv.ProfileOf(ctx, n.Name)
+		// Its public domain too (novox/hq ADR 0346): a provider elsewhere serves its own composed names,
+		// and composes them as its own plan does, under its own domain.
+		// Read as its profile is: a machine whose domain cannot be read (removed since the list was read)
+		// composes no public name, which leaves the key out and says so, and fails no other machine's plan.
+		domain, _ := inv.PublicDomainOf(ctx, n.Name)
 		others = append(others, candidate{
 			catalogue.Node{Name: n.Name, Site: siteOf[n.Name], Capabilities: caps,
-				At: onNetwork[n.Name]}, theirs})
+				At: onNetwork[n.Name], PublicDomain: domain}, theirs})
 	}
 
 	offered := map[string][]catalogue.Provider{}
@@ -310,12 +315,18 @@ func theRestOfTheMesh(ctx context.Context, inv *inventory.Inventory,
 				// What that module says a consumer needs to know, with that node's settings on
 				// it: a port somebody moved on the provider is a port its consumers must be told
 				// about, and the two coming from different places is how they come to disagree.
-				serves, err := servedOnNode(ctx, inv, o.node.Name, m, name)
+				serves, layers, err := servedOnNode(ctx, inv, o.node.Name, m, name)
+				if err != nil {
+					return catalogue.World{}, err
+				}
+				// And its own composed names, as that node composes them (novox/hq ADR 0346): a name it
+				// does not compose leaves the key out, said under each consumer's need.
+				serves, leftOut, err := got.ServedOwnNames(m, name, serves, catalogue.WithDefaults(m, layers))
 				if err != nil {
 					return catalogue.World{}, err
 				}
 				offered[name] = append(offered[name], catalogue.Provider{
-					Node: o.node.Name, At: o.node.At, Serves: serves, Module: m.Module})
+					Node: o.node.Name, At: o.node.At, Serves: serves, Module: m.Module, LeftOut: leftOut})
 			}
 		}
 	}
@@ -997,9 +1008,14 @@ func renderingFor(ctx context.Context, open *stores, node string,
 	if err != nil {
 		return catalogue.Rendering{}, inventory.Node{}, err
 	}
+	readsBusy, err := engineReadsBusy(ctx, inv, node)
+	if err != nil {
+		return catalogue.Rendering{}, inventory.Node{}, err
+	}
 	return catalogue.Rendering{
 		ReadsHealth:   readsHealth,
 		JudgesRoot:    judgesRoot,
+		ReadsBusy:     readsBusy,
 		BusMembership: memberships[node],
 		Settings:      settings, Generators: gens, Grants: grants, Needed: needed, Foreseen: foreseen, Ports: ports,
 		Certificate: certificate, Authority: authority, Mesh: private, Names: names,
@@ -1033,6 +1049,35 @@ func engineJudgesRoot(ctx context.Context, inv *inventory.Inventory, node string
 	return had && stated.Contract >= link.RootContract, nil
 }
 
+// engineReadsBusy says whether a machine's node-engine reads a container's `busy` (novox/hq ADR 0335), by its
+// own newest statement, for the same reason as engineReadsHealth: an older engine parses strictly.
+func engineReadsBusy(ctx context.Context, inv *inventory.Inventory, node string) (bool, error) {
+	stated, had, err := inv.HealthOf(ctx, node)
+	if err != nil {
+		return false, err
+	}
+	return had && stated.Contract >= link.BusyContract, nil
+}
+
+// busyNotSent is, for a node-engine that does not read a container's busy, each container whose module declares
+// one: not sent it, so replaced at once while it may hold work (novox/hq ADR 0335). Nothing for one that reads it.
+func busyNotSent(modules []catalogue.Manifest, reads bool) []string {
+	if reads {
+		return nil
+	}
+	var out []string
+	for _, m := range modules {
+		for _, r := range m.Resources {
+			if _, has := r[catalogue.BusyField]; has {
+				out = append(out, fmt.Sprintf("%s.%v declares busy, and this node-engine does not read it yet (its "+
+					"statement's contract is below %d): not sent, so the container is replaced at once, busy or not "+
+					"(novox/hq ADR 0335)", m.Module, r["id"], link.BusyContract))
+			}
+		}
+	}
+	return out
+}
+
 // zonesInTheMesh is every zone a module in the mesh declares, where the mesh placed it (novox/hq ADR
 // 0199): the zone settled from that node's settings, the node's private address, the port the
 // answering listen is published on there.
@@ -1426,10 +1471,29 @@ func planCommand(ctx context.Context, args []string) error {
 	// in this output would have told anybody that.
 	for _, n := range plan.Needs {
 		fmt.Printf("  needs %s from %s, for %s\n", n.Name, n.From, n.For)
+		// And a served key the provider left out, because its machine composes no name it asks for
+		// (novox/hq ADR 0346 §3).
+		for _, line := range n.LeftOut {
+			fmt.Printf("    %s\n", line)
+		}
+	}
+	// What the providers on this machine leave out of what they serve, and why: said where the remedy
+	// is (novox/hq ADR 0346 §3).
+	for _, line := range plan.ServedLeftOut(settings) {
+		fmt.Printf("%s: %s\n", args[0], line)
 	}
 	for _, line := range unboundLines(plan) {
 		fmt.Println(line)
 	}
+	// And a container's busy that this machine's node-engine is too old to be sent (novox/hq ADR 0335): its
+	// container is replaced at once, as before. A statement that cannot be read is said as such.
+	if reads, err := engineReadsBusy(ctx, open.inventory, args[0]); err != nil {
+		fmt.Printf("%s: whether its node-engine reads a container's busy could not be read: %v\n", args[0], err)
+	} else {
+		for _, line := range busyNotSent(plan.Modules, reads) {
+			fmt.Printf("%s: %s\n", args[0], line)
+		}
+	}
 	declared, err := declarationFor(ctx, open, args[0], plan, settings)
 	if err != nil {
 		return err
@@ -1566,19 +1630,20 @@ func managerPublicKeyFor(
 // artifact store's trust and the references composed through it (04-ISSUES/102). Unreadable
 // given ports are that node's refusal to report, not this reader's.
 func servedOnNode(ctx context.Context, inv *inventory.Inventory, node string,
-	m catalogue.Manifest, provision string) (map[string]any, error) {
+	m catalogue.Manifest, provision string) (map[string]any, []catalogue.Layer, error) {
 	ports, layers, err := portsGivenOn(ctx, inv, node, m)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 	serves := catalogue.ServedOn(m, provision, ports)
 	if len(serves) > 0 {
 		serves, err = catalogue.Settle(serves, catalogue.WithDefaults(m, layers))
 		if err != nil {
-			return nil, err
+			return nil, nil, err
 		}
 	}
-	return serves, nil
+	// The layers too, read once, for what is filled after (novox/hq ADR 0346).
+	return serves, layers, nil
 }
 
 // portsGivenOn is where a node puts a module's ports — assigned, then given over them — and the

cmd/mesh-controller/proposals.go

@@ -18,8 +18,9 @@ package main
 // it beside the layer (`settings` says it back), and records the warrant in the hand-act log on the bus, where a
 // person's decisions are read; the router edits the ask on every channel to its outcome. No seat event of its
 // own: nothing consumes one, and the installer's first user list in the node-engine's repository names every
-// controller event, so one would cost a node-engine change for a fact without a reader. The push afterwards is a
-// separate act, as it is for a layer set at the terminal.
+// controller event, so one would cost a node-engine change for a fact without a reader. No push is left for
+// afterwards: the warrant that sets the layer opens the walk that sends it (novox/hq ADR 0344, settings_walk.go),
+// so the operator's one Approve is the act that makes the change take effect.
 //
 // **What the operator reads** is the module, the machine, each key with its exact new value and, for a changed
 // key, the value it replaces. A value that may not leave the mesh (an address, a path, a secret's shape: the
@@ -27,6 +28,13 @@ package main
 // ask says so, and the whole is read with `settings proposals <id>` — whose fingerprint must be the one on the
 // phone. Fail closed: a proposal nothing can carry to the operator is refused at once, in words, and never left
 // waiting for an answer that cannot come.
+//
+// **On a channel that proves who answers, the values are shown WHOLE** (novox/hq issue 383, the operator's
+// decision of 2026-10-10): a mount point, a share name or a private address is the thing being approved and must
+// be readable, so the ask carries them whole beside the explanation (asks.Ask.Whole), the router shows that only
+// on a kind that verifies its sender, and only a value shaped like a secret is withheld there. The message is the
+// headline, one line per key, who proposed it and when; the fingerprint and how to read the proposal whole are
+// the Details answer's (asks.Ask.Details). The masking stays for conditions and for channels that prove nothing.
 
 import (
 	"context"
@@ -47,6 +55,7 @@ import (
 	"git.novox.be/novox/mesh-sdk/go/asks"
 
 	"github.com/novox/mesh-controller/internal/conditions"
+	"github.com/novox/mesh-controller/internal/inventory"
 	"github.com/novox/mesh-controller/internal/link"
 	"github.com/novox/mesh-controller/internal/outward"
 )
@@ -154,47 +163,48 @@ func (p settingsProposal) ask(id string, machines []string) (asks.Ask, map[strin
 	if len([]rune(headline)) > asks.HeadlineLength {
 		headline = verb + " settings?"
 	}
-	shown, whole := p.change(machines)
-	var b strings.Builder
-	if p.Clear {
-		fmt.Fprintf(&b, "Clear the settings of %s on %s, back to what the module says?\n\n", p.Module, p.where())
-	} else {
-		fmt.Fprintf(&b, "Set the settings of %s on %s to these values?\n\n", p.Module, p.where())
+	// The message reads at a glance (issues 383 and 639): a summary of what changes where, then at most three
+	// points, a key each; every key with its whole value, who proposed it, the fingerprint and how to read it at the
+	// terminal are its Details, which the router notes after the answers.
+	shown, shownAll, shownWhole := p.change(machines, false)
+	whole, wholeAll, _ := p.change(machines, true)
+	summary := p.summary()
+	compose := func(points []string) string {
+		return strings.Join(append([]string{summary}, points...), "\n")
 	}
-	fmt.Fprintf(&b, "Proposed by %s, at %s. ", sayable(p.From, machines), p.At.Local().Format("15:04 on 2 Jan"))
-	switch {
-	case p.Clear && p.HadLayer:
-		b.WriteString("The layer it removes:\n\n")
-	case p.Clear:
-		b.WriteString("There is no layer to remove; approving changes nothing.")
-	case !p.HadLayer:
-		b.WriteString("There is no layer yet; this is the whole of it:\n\n")
-	default:
-		b.WriteString("The layer is replaced whole; what changes against it:\n\n")
+	// The Details: every setting it sets, one line each, uncut — whole where the sender is proven (WholeDetails),
+	// masked elsewhere — then who proposed it, the fingerprint and how to read it at the terminal.
+	details := func(lines []string) string {
+		var d strings.Builder
+		d.WriteString(strings.Join(lines, "\n") + "\n")
+		d.WriteString(p.onApprove() + "\n")
+		fmt.Fprintf(&d, "Proposed by %s at %s. Fingerprint %s.\n", sayable(p.From, machines), p.At.Local().Format("15:04 on 2 Jan"),
+			fingerprint(p.Digest))
+		if !shownWhole {
+			d.WriteString("Where who answers is not proven, its values are shown as ‹address›, ‹path› or ‹withheld›.\n")
+		}
+		fmt.Fprintf(&d, "Read it whole, with this fingerprint: settings proposals %s at the controller's terminal, or the "+
+			"controller's settings verb with proposal %s through the mesh MCP server.", id, id)
+		return d.String()
 	}
-	b.WriteString(shown)
-	fmt.Fprintf(&b, "\n\nFingerprint %s.", fingerprint(p.Digest))
-	if !whole {
-		b.WriteString(" Parts shown as ‹address›, ‹path› or ‹withheld› may not leave the mesh: read it whole, with " +
-			"this fingerprint, through the mesh MCP server (mesh-controller.settings, proposal " + id + ") or with " +
-			"mesh-cli settings proposals " + id + ".")
-	}
-	if p.Clear {
-		b.WriteString(" Approved, the layer is removed at once and the machine takes it at its next push.")
-	} else {
-		b.WriteString(" Approved, the layer is set at once and the machine takes it at its next push.")
-	}
-	q := asks.Ask{ID: id, Headline: headline, Explanation: b.String(), Who: asks.Operator,
+	q := asks.Ask{ID: id, Headline: headline, Explanation: compose(shown), Who: asks.Operator,
 		Expires: p.At.Add(askApproveFor), OnExpiry: "the proposal is discarded; nothing changes",
-		About: p.about()}
+		About: p.about(), Details: details(shownAll)}
+	// Only where a value was masked: an ask whose values all pass the content rule shows the same everywhere.
+	if w := compose(whole); w != q.Explanation {
+		q.Whole = w
+	}
+	if w := details(wholeAll); w != q.Details {
+		q.WholeDetails = w
+	}
 	options := map[string]int{}
 	for i, act := range p.actions(id) {
 		binds, _ := asks.ActDigest(boundAct(act))
 		oid := optionID(act.Label)
 		options[oid] = i
-		does := "the settings are set; nothing is pushed yet"
+		does := "the settings are set and sent to " + p.reaches() + " at once, each machine judged"
 		if p.Clear {
-			does = "the layer is removed; nothing is pushed yet"
+			does = "the layer is removed and that is sent to " + p.reaches() + " at once, each machine judged"
 		}
 		if act.Arguments["answer"] == answerDecline {
 			does = "nothing changes; the proposal is discarded"
@@ -205,55 +215,141 @@ func (p settingsProposal) ask(id string, machines []string) (asks.Ask, map[strin
 	return q, options
 }
 
-// shownMost is the most of a change the phone is shown, in bytes; the rest is read whole with `settings proposals`.
-const shownMost = 1400
+// summary is the proposal's first line, what changes where: how many settings, how many stay, and that Approve sends
+// the layer at once by a walk, one machine at a time (novox/hq ADR 0344); the rest of what Approve does
+// (onApprove) is the Details'.
+func (p settingsProposal) summary() string {
+	if p.Clear {
+		if !p.HadLayer {
+			return "There is no layer to remove; approving changes nothing."
+		}
+		return fmt.Sprintf("Removes the %d setting(s) of %s set on %s; approved, the layer is removed and that is sent at once "+
+			"by a walk to %s, one machine at a time, each judged.", len(leaves(p.Before, "")), p.Module, p.where(), p.reaches())
+	}
+	added, changed, removed := settingsChange(p.Before, p.Values)
+	n := len(added) + len(changed) + len(removed)
+	unchanged := len(leaves(p.Values, "")) - len(added) - len(changed)
+	if n == 0 {
+		return fmt.Sprintf("Nothing changes: the %d setting(s) of %s on %s are as they stand.", unchanged, p.Module, p.where())
+	}
+	stay := ""
+	if unchanged > 0 {
+		stay = fmt.Sprintf(", and %d stay as they are", unchanged)
+	}
+	return fmt.Sprintf("Changes %d setting(s) of %s on %s%s; approved, the layer is set and sent at once by a walk to %s, "+
+		"one machine at a time, each judged.", n, p.Module, p.where(), stay, p.reaches())
+}
 
-// change is what changes, line by line, each value shown under the content rule, and whether every value was
-// shown whole: "+ key: value" added, "~ key: value (was: old)" changed, "- key (was: old)" removed, and the
-// count of keys unchanged.
-func (p settingsProposal) change(machines []string) (string, bool) {
+// change is what changes: as at most asks.MostPoints points for the glance, as every line whole for the note, and
+// whether every value was shown exactly: "+ key: value"
+// added, "~ key: value (was: old)" changed, "- key (was: old)" removed. Each value is shown under the content rule
+// (sayableValue), or — exact, for a channel that proves who answers — as it is, withheld only when shaped like a
+// secret (wholeValue). More changes than points: the first two, and the keys of the rest; a point longer than a
+// phone shows at a glance is cut and says so. The note carries every line uncut (the review of #304: Approve sets
+// exactly what the operator can read).
+func (p settingsProposal) change(machines []string, exact bool) ([]string, []string, bool) {
 	whole := true
 	say := func(v any) string {
 		s, w := sayableValue(v, machines)
+		if exact {
+			s, w = wholeValue(v, machines)
+		}
 		whole = whole && w
 		return s
 	}
-	var lines []string
+	type line struct{ key, text string }
+	var lines []line
 	if p.Clear {
 		was := leaves(p.Before, "")
 		for _, k := range layerKeys(was) {
-			lines = append(lines, fmt.Sprintf("- %s: %s", k, say(was[k])))
+			lines = append(lines, line{k, fmt.Sprintf("- %s: %s", k, say(was[k]))})
 		}
 	} else {
 		added, changed, removed := settingsChange(p.Before, p.Values)
 		was, now := leaves(p.Before, ""), leaves(p.Values, "")
 		for _, k := range added {
-			lines = append(lines, fmt.Sprintf("+ %s: %s", k, say(now[k])))
+			lines = append(lines, line{k, fmt.Sprintf("+ %s: %s", k, say(now[k]))})
 		}
 		for _, k := range changed {
-			lines = append(lines, fmt.Sprintf("~ %s: %s (was: %s)", k, say(now[k]), say(was[k])))
+			lines = append(lines, line{k, fmt.Sprintf("~ %s: %s (was: %s)", k, say(now[k]), say(was[k]))})
 		}
 		for _, k := range removed {
-			lines = append(lines, fmt.Sprintf("- %s (was: %s)", k, say(was[k])))
-		}
-		unchanged := len(now) - len(added) - len(changed)
-		switch {
-		case len(lines) == 0 && unchanged > 0:
-			lines = append(lines, fmt.Sprintf("= nothing changes: the %d key(s) are as they stand", unchanged))
-		case unchanged > 0:
-			lines = append(lines, fmt.Sprintf("= %d key(s) unchanged", unchanged))
+			lines = append(lines, line{k, fmt.Sprintf("- %s (was: %s)", k, say(was[k]))})
 		}
 	}
-	out := strings.Join(lines, "\n")
-	if len(out) > shownMost {
-		cut := shownMost
-		for cut > 0 && out[cut] != '\n' {
-			cut--
+	// **Each line is judged as the router will judge it** (the review of #304, ADR 0347 §1 and §3): a line the
+	// content rule (masked) or the secret rule (whole) would refuse — a value given to a secret's name, say
+	// "+ password: hunter2" — is said with its key still named and its value withheld, never left for the
+	// router to withhold whole and unnamed. A line refused even so is the propose's refusal (judgeLines).
+	for i, l := range lines {
+		if lineLeaves(l.text, exact, machines) {
+			continue
 		}
-		out = out[:cut] + fmt.Sprintf("\n… NOT SHOWN IN FULL here: %d more bytes", len(strings.Join(lines, "\n"))-cut)
+		lines[i].text = l.text[:2] + l.key + " (value withheld)"
 		whole = false
 	}
-	return out, whole
+	all := make([]string, len(lines))
+	for i, l := range lines {
+		all[i] = l.text
+	}
+	// What the note holds of a value: whole where the glance is the whole one (shown only where the sender is
+	// proven, with the whole details beside it), under the content rule elsewhere — so the marker says no more than
+	// the note it points to (the review of ADR 0347).
+	inNote := "in the note"
+	if exact {
+		inNote = "whole in the note"
+	}
+	var out []string
+	for i, l := range lines {
+		if len(lines) > asks.MostPoints && i == asks.MostPoints-1 {
+			var rest []string
+			for _, r := range lines[i:] {
+				rest = append(rest, r.key)
+			}
+			out = append(out, fmt.Sprintf("and %d more, each %s: %s", len(rest), inNote, strings.Join(rest, ", ")))
+			break
+		}
+		out = append(out, l.text)
+	}
+	// A point too long for a glance is cut, and says so: its value is the note's.
+	cut := "… (cut: " + inNote + ")"
+	for i, l := range out {
+		if r := []rune(l); len(r) > asks.PointLength {
+			out[i] = string(r[:asks.PointLength-len([]rune(cut))]) + cut
+		}
+	}
+	return out, all, whole
+}
+
+// lineLeaves says whether a line may leave the mesh as the router judges it: under the content rule for the masked
+// form, the secret rule alone for the whole one.
+func lineLeaves(line string, exact bool, machines []string) bool {
+	if exact {
+		_, ok := outward.Secret(line, machines...)
+		return ok
+	}
+	_, ok := outward.Check(line, machines...)
+	return ok
+}
+
+// judgeLines is the first line of an ask's details the router would refuse, or withhold, and why: masked under
+// the content rule line by line, whole under the secret rule. Empty when every line may leave.
+func judgeLines(details string, exact bool, machines []string) (string, string) {
+	for _, line := range strings.Split(details, "\n") {
+		if strings.TrimSpace(line) == "" {
+			continue
+		}
+		if exact {
+			if refusal, ok := outward.Secret(line, machines...); !ok {
+				return line, refusal.String()
+			}
+			continue
+		}
+		if refusal, ok := outward.Check(line, machines...); !ok {
+			return line, refusal.String()
+		}
+	}
+	return "", ""
 }
 
 func layerKeys(m map[string]any) []string {
@@ -300,6 +396,27 @@ func sayableValue(v any, machines []string) (string, bool) {
 	return out, out == text
 }
 
+// wholeValue is a value as a channel that proves who answers is shown it (asks.Ask.Whole), and whether it was
+// shown whole: as it is, unless it is shaped like a secret (outward.Secret), which is withheld whole — never in
+// part, so no half of a key reaches the phone.
+func wholeValue(v any, machines []string) (string, bool) {
+	text, ok := v.(string)
+	if !ok {
+		raw, err := json.Marshal(v)
+		if err != nil {
+			return markWithheld, false
+		}
+		text = string(raw)
+	}
+	if text == "" {
+		return `""`, true
+	}
+	if _, ok := outward.Secret(text, machines...); !ok {
+		return markWithheld, false
+	}
+	return text, true
+}
+
 // sayable is a text with what may not leave the mesh replaced in place by a marker; what the markers cannot make
 // pass is withheld whole.
 func sayable(text string, machines []string) string {
@@ -432,6 +549,23 @@ func (pr proposer) propose(ctx context.Context, in proposeInput) (string, error)
 		return refuse("the ask's words would carry %s, which may not leave the mesh, and the change could not be "+
 			"shown without it; %s", refusal, atTheTerminalInstead(in))
 	}
+	// The whole words are shown only where the sender is proven, and never a secret's shape: wholeValue withholds
+	// one, and the router would refuse the ask if one were left, so it is refused here first, in words.
+	if refusal, ok := outward.Secret(q.Whole, machines...); !ok {
+		return refuse("the change shown whole would carry %s, which may not leave the mesh on any channel; %s",
+			refusal, atTheTerminalInstead(in))
+	}
+	// So are the details (ADR 0347 §1, §3): every line the router would withhold from the note, or refuse the ask
+	// for, is refused here, in the controller's own words, naming the line's key — Approve never sets a value the
+	// operator was shown nothing of.
+	if line, why := judgeLines(q.Details, false, machines); line != "" {
+		return refuse("the change's line %q would carry %s, which the operator's note may not show; %s",
+			keyOfLine(line), why, atTheTerminalInstead(in))
+	}
+	if line, why := judgeLines(q.WholeDetails, true, machines); line != "" {
+		return refuse("the change's line %q shown whole would carry %s, which may not leave the mesh on any channel; %s",
+			keyOfLine(line), why, atTheTerminalInstead(in))
+	}
 	// Fail closed, before anything is kept: no router, no grant, no channel means no ask.
 	if pr.routerHere != nil {
 		here, err := pr.routerHere(ctx)
@@ -519,15 +653,29 @@ func (pr proposer) propose(ctx context.Context, in proposeInput) (string, error)
 		fingerprint(p.Digest))
 	fmt.Fprintf(&b, "  until %s nothing changes: the layer is set only on Approve, and discarded on Decline or at expiry\n",
 		q.Expires.Local().Format("2006-01-02 15:04"))
-	fmt.Fprintf(&b, "  `settings proposals %s` shows it whole; once approved, `push %s` sends it", id, pushWord(p.Node))
+	fmt.Fprintf(&b, "  `settings proposals %s` shows it whole; once approved, a walk sends it to %s at once, one machine at "+
+		"a time, each judged, and its end is told as every walk's is (novox/hq ADR 0344)", id, p.reaches())
 	return b.String(), nil
 }
 
-func pushWord(node string) string {
-	if node == "" {
-		return "--behind"
+// reaches is the machines an approved layer is sent to, in words: the one it names, or every machine running the
+// module.
+func (p settingsProposal) reaches() string {
+	if p.Node == "" {
+		return "every machine running " + p.Module
 	}
-	return node
+	return p.Node
+}
+
+// onApprove is what the ask says Approve does (novox/hq ADR 0344 §4): the one Approve sets the layer and sends it.
+func (p settingsProposal) onApprove() string {
+	what := "the layer is set"
+	if p.Clear {
+		what = "the layer is removed"
+	}
+	return fmt.Sprintf("Approved, %s and sent at once to %s, one machine at a time, each judged, every build there "+
+		"kept; its end is told as every walk's is. A module that reads its settings only when it starts takes them at "+
+		"its next start.", what, p.reaches())
 }
 
 func newProposalID() string {
@@ -788,6 +936,40 @@ func setLayerIn(open *stores) setOnWarrant {
 				changed = "nothing changed"
 			}
 		}
-		return changed + " (ask " + askID + ")", nil
+		// **And sends it** (novox/hq ADR 0344): the layer the operator approved is walked to the machines it reaches
+		// at once. A walk that cannot be opened is said as the act's failure — the layer is set and nothing sends it.
+		walked, err := openSettingsWalk(ctx, open, inventory.PlanSettings{Module: p.Module, Node: p.Node, Ask: askID,
+			Change: changed})
+		if err != nil {
+			return "", fmt.Errorf("%s (ask %s) is set, and the walk that sends it could not be opened: %v — `push %s` sends it",
+				changed, askID, err, pushTo(p.Node))
+		}
+		return changed + " (ask " + askID + "); " + walked, nil
 	}
 }
+
+// pushTo is the push that sends a layer by hand when its walk could not: the machine, or every one behind.
+func pushTo(node string) string {
+	if node == "" {
+		return "--behind"
+	}
+	return node
+}
+
+// keyOfLine is what a refusal names of a line: the key of a change's line ("+ key: …"), or the line's first words.
+func keyOfLine(line string) string {
+	if len(line) > 2 && strings.ContainsRune("+~-=", rune(line[0])) && line[1] == ' ' {
+		rest := line[2:]
+		if i := strings.IndexAny(rest, ": "); i > 0 {
+			rest = rest[:i]
+		}
+		if _, ok := outward.Secret(rest); !ok {
+			return "whose key is shaped like a secret"
+		}
+		return rest
+	}
+	if r := []rune(line); len(r) > 40 {
+		return string(r[:40]) + "…"
+	}
+	return line
+}

cmd/mesh-controller/proposals_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"io"
 	"os"
 	"slices"
@@ -116,24 +117,43 @@ func TestAProposalAsksAtTheLevelApproveWithTheExactChange(t *testing.T) {
 	if q.Options[0].Binds == q.Options[1].Binds {
 		t.Error("Approve and Decline bind the same act")
 	}
-	for _, line := range []string{
-		"Set the settings of mounts on shanks to these values?",
-		"Proposed by g14/claude-code, through the mesh-controller seat, at " + r.now.Local().Format("15:04 on 2 Jan") + ".",
-		"+ sources: recalbox=‹address›@‹path›:ro",
-		"~ shares: library=‹path› (was: none)",
-		"- old (was: x)",
-		"Fingerprint " + fingerprint(layerDigest(mountsSources)) + ".",
-		"read it whole, with this fingerprint",
-	} {
-		if !strings.Contains(q.Explanation, line) {
-			t.Errorf("the explanation lacks %q:\n%s", line, q.Explanation)
-		}
+	// The message reads at a glance (issues 383 and 639): a summary, then one point per key — and nothing else:
+	// who proposed it, the fingerprint and the how-to are the Details, which the router notes after the answers.
+	summary := "Changes 3 setting(s) of mounts on shanks; approved, the layer is set and sent at once by a walk to shanks, one machine at a time, each judged."
+	if q.Explanation != summary+"\n+ sources: recalbox=‹address›@‹path›:ro\n~ shares: library=‹path› (was: none)\n- old (was: x)" {
+		t.Errorf("the explanation:\n%s", q.Explanation)
+	}
+	if err := asks.Glance(q.Explanation); err != nil {
+		t.Error(err)
 	}
 	for _, leak := range []string{"nas.lan", "/mnt/recalbox", "/mnt/library", "smb://"} {
 		if strings.Contains(q.Explanation, leak) {
 			t.Errorf("the explanation carries %q, which may not leave the mesh", leak)
 		}
 	}
+	// Where the sender is proven, the values whole: the mount point and the share are what is approved.
+	if q.Whole != summary+"\n+ sources: recalbox=smb://nas.lan/recalbox@/mnt/recalbox:ro\n~ shares: library=/mnt/library (was: none)\n- old (was: x)" ||
+		asks.Glance(q.Whole) != nil {
+		t.Errorf("the whole words:\n%s", q.Whole)
+	}
+	for _, line := range []string{
+		"Proposed by g14/claude-code, through the mesh-controller seat at " + r.now.Local().Format("15:04 on 2 Jan") +
+			". Fingerprint " + fingerprint(layerDigest(mountsSources)) + ".",
+		"Where who answers is not proven, its values are shown as ‹address›, ‹path› or ‹withheld›.",
+		"Read it whole, with this fingerprint: settings proposals " + kept(r).ID + " at the controller's terminal",
+	} {
+		if !strings.Contains(q.Details, line) {
+			t.Errorf("Details lack %q:\n%s", line, q.Details)
+		}
+	}
+	if refusal, ok := outward.Check(q.Details, "anchor", "laptop", "shanks"); !ok {
+		t.Errorf("the router would withhold a line of the details: %s", refusal)
+	}
+	for _, howTo := range []string{"ingerprint", "settings proposals", "settings verb", "not proven", "Proposed by"} {
+		if strings.Contains(q.Explanation, howTo) || strings.Contains(q.Whole, howTo) {
+			t.Errorf("the message carries the how-to %q", howTo)
+		}
+	}
 	all := []string{q.Headline, q.Explanation, q.OnExpiry}
 	for _, o := range q.Options {
 		all = append(all, o.Label, o.Does)
@@ -141,6 +161,9 @@ func TestAProposalAsksAtTheLevelApproveWithTheExactChange(t *testing.T) {
 	if refusal, ok := outward.Check(strings.Join(all, "\n"), "anchor", "laptop", "shanks"); !ok {
 		t.Errorf("the router would refuse the ask: %s", refusal)
 	}
+	if refusal, ok := outward.Secret(q.Whole, "anchor", "laptop", "shanks"); !ok {
+		t.Errorf("the router would refuse the whole words: %s", refusal)
+	}
 	// Kept as the controller's own ask, about no condition, with the proposal whole and its digests.
 	kept := r.theProposal(t)
 	p := kept.Proposal
@@ -173,11 +196,98 @@ func TestAMeshWideLayerIsProposed(t *testing.T) {
 	}
 	q := r.askSent(t)
 	if q.Headline != "Set notes on the whole mesh?" || q.About != "settings.notes.mesh" ||
-		!strings.Contains(q.Explanation, "Set the settings of notes on the whole mesh to these values?") {
+		q.Explanation != "Changes 1 setting(s) of notes on the whole mesh; approved, the layer is set and sent at once by a walk to every machine running notes, one machine at a time, each judged.\n+ x: 1" ||
+		q.Whole != "" {
 		t.Errorf("%+v", q)
 	}
 }
 
+// kept is the one proposal the rig keeps.
+func kept(r *proposerRig) asked {
+	for _, a := range r.store {
+		if a.Proposal != nil {
+			return a
+		}
+	}
+	return asked{}
+}
+
+// The switch between the masked and the whole change (issue 383): the same change, under the content rule and
+// exact, differs in the masked values alone; a value shaped like a secret is withheld in both, whole, with its
+// key still named; and a change no value of which is masked carries no whole words of its own.
+func TestAProposalShowsItsValuesWholeOnlyWhereTheSenderIsProvenAndNeverASecret(t *testing.T) {
+	machines := []string{"anchor", "laptop", "shanks"}
+	r := newProposerRig(t)
+	values := map[string]any{"shares": "media=/storage/media", "sources": "recalbox=smb://nas.lan/recalbox@/mnt/recalbox", "font": "Inter 13"}
+	if _, err := r.pr.propose(context.Background(), proposeInput{module: "mounts", node: "shanks", values: values}); err != nil {
+		t.Fatal(err)
+	}
+	q := r.askSent(t)
+	masked, _, _ := kept(r).Proposal.change(machines, false)
+	whole, _, _ := kept(r).Proposal.change(machines, true)
+	if !strings.HasSuffix(q.Explanation, "\n"+strings.Join(masked, "\n")) || !strings.HasSuffix(q.Whole, "\n"+strings.Join(whole, "\n")) {
+		t.Fatalf("the ask does not carry the change masked and whole:\n%s\n--\n%s", q.Explanation, q.Whole)
+	}
+	if want := []string{"+ font: Inter 13", "+ shares: media=‹path›", "+ sources: recalbox=‹address›@‹path›"}; strings.Join(masked, "\n") != strings.Join(want, "\n") {
+		t.Errorf("masked: %q", masked)
+	}
+	if want := []string{"+ font: Inter 13", "+ shares: media=/storage/media", "+ sources: recalbox=smb://nas.lan/recalbox@/mnt/recalbox"}; strings.Join(whole, "\n") != strings.Join(want, "\n") {
+		t.Errorf("whole: %q", whole)
+	}
+	if _, ok := outward.Secret(q.Whole, "shanks"); !ok {
+		t.Error("the router would refuse the whole words")
+	}
+	// Mutation: the masked and the whole change differ in exactly the lines whose value was masked.
+	differ := 0
+	for i := range masked {
+		if masked[i] != whole[i] {
+			differ++
+			if !strings.Contains(masked[i], "‹") || strings.Contains(whole[i], "‹") {
+				t.Errorf("the lines differ otherwise than by the mask:\n%s\n%s", masked[i], whole[i])
+			}
+		}
+	}
+	if differ != 2 {
+		t.Errorf("%d lines differ, and the mask covered 2", differ)
+	}
+	// A value shaped like a secret is withheld in both, whole, with its key still named.
+	r1 := newProposerRig(t)
+	secrets := map[string]any{"github": "ghp_abcdefghijklmnopqrstuvwxyz0123456789", "cert": "-----BEGIN CERTIFICATE-----"}
+	if _, err := r1.pr.propose(context.Background(), proposeInput{module: "mounts", node: "shanks", values: secrets}); err != nil {
+		t.Fatal(err)
+	}
+	q1 := r1.askSent(t)
+	for _, line := range []string{"+ cert: ‹withheld›", "+ github: ‹withheld›"} {
+		if !strings.Contains(q1.Explanation, line) {
+			t.Errorf("lacks %q:\n%s", line, q1.Explanation)
+		}
+	}
+	for _, secret := range []string{"ghp_", "BEGIN CERTIFICATE"} {
+		if strings.Contains(q1.Explanation, secret) || strings.Contains(q1.Whole, secret) || strings.Contains(q1.Details, secret) {
+			t.Errorf("the secret %q reaches the phone", secret)
+		}
+	}
+	// More keys than points (issue 639): the first two, then the keys of the rest, read whole at the terminal.
+	r3 := newProposerRig(t)
+	five := map[string]any{"a": "1", "b": "2", "c": "3", "d": "4", "e": "5"}
+	if _, err := r3.pr.propose(context.Background(), proposeInput{module: "notes", node: "laptop", values: five}); err != nil {
+		t.Fatal(err)
+	}
+	if q3 := r3.askSent(t); !strings.HasSuffix(q3.Explanation, "\n+ a: 1\n+ b: 2\nand 3 more, each in the note: c, d, e") || asks.Glance(q3.Explanation) != nil ||
+		!strings.Contains(q3.Details, "settings proposals") {
+		t.Errorf("five keys:\n%s", q3.Explanation)
+	}
+	// No value masked: the message is the same everywhere, and the ask says no whole words.
+	r2 := newProposerRig(t)
+	if _, err := r2.pr.propose(context.Background(), proposeInput{module: "dunst", node: "laptop", values: map[string]any{"font-size": 13, "width": 500}}); err != nil {
+		t.Fatal(err)
+	}
+	if q2 := r2.askSent(t); q2.Whole != "" || !strings.HasSuffix(q2.Explanation, "\n+ font-size: 13\n+ width: 500") ||
+		strings.Contains(q2.Details, "not proven") {
+		t.Errorf("%+v", q2)
+	}
+}
+
 // A proposal expired unanswered is kept so by the reconciling, and a warrant for it afterwards sets nothing.
 func TestAnExpiredProposalIsKeptExpired(t *testing.T) {
 	r := newAskerRig(t)
@@ -205,7 +315,8 @@ func TestAClearIsProposedAndShowsWhatItRemoves(t *testing.T) {
 	}
 	q := r.askSent(t)
 	if q.Headline != "Clear notes on laptop?" || !strings.Contains(q.Explanation, "- places.data.owner: 1001:1001") ||
-		!strings.Contains(q.Explanation, "- places.data.path: ‹path›") {
+		!strings.Contains(q.Explanation, "- places.data.path: ‹path›") || !strings.Contains(q.Whole, "- places.data.path: /srv/notes") ||
+		!strings.HasPrefix(q.Explanation, "Removes the 2 setting(s) of notes set on laptop; approved, the layer is removed and that is sent at once by a walk to laptop, one machine at a time") {
 		t.Errorf("%+v", q)
 	}
 	if p := r.theProposal(t).Proposal; !p.Clear || p.Digest != layerDigest(r.before) || len(r.judged) != 0 {
@@ -744,3 +855,125 @@ func captureStdout(t *testing.T, f func()) string {
 	_ = w.Close()
 	return <-done
 }
+
+// The review of #304: Approve sets exactly what the operator can read. A proposal of five keys, one value 300
+// characters long, shows two keys at a glance, says what it cut, and carries every key with its whole value in its
+// Details for a channel that proves who answers (WholeDetails), and every key masked for one that does not.
+func TestEveryKeyAndItsWholeValueReachTheOperator(t *testing.T) {
+	var long strings.Builder
+	long.WriteString("library=/storage")
+	for i := 0; long.Len() < 300; i++ {
+		long.WriteString(fmt.Sprintf("/album-%02d", i))
+	}
+	value := long.String()[:300]
+	values := map[string]any{"a": "1", "b": "2", "c": "3", "d": "4", "shares": value}
+	r := newProposerRig(t)
+	if _, err := r.pr.propose(context.Background(), proposeInput{module: "mounts", node: "shanks", values: values}); err != nil {
+		t.Fatal(err)
+	}
+	q := r.askSent(t)
+	if err := q.Check(r.now); err != nil {
+		t.Fatal(err)
+	}
+	// What the operator reads on a proving channel: the whole words, then the note's whole details.
+	visible := q.Whole + "\n" + q.WholeDetails
+	if q.Whole == "" {
+		visible = q.Explanation + "\n" + q.WholeDetails
+	}
+	for k, v := range values {
+		if !strings.Contains(visible, "+ "+k+": "+v.(string)) {
+			t.Errorf("the operator never reads %s whole:\n%s", k, visible)
+		}
+	}
+	// The masked glance points to a note that holds the values masked, and says no more; the whole glance, shown only
+	// beside the whole details, says they are whole there.
+	if asks.Glance(q.Explanation) != nil || !strings.HasSuffix(q.Explanation, "\nand 3 more, each in the note: c, d, shares") ||
+		strings.Contains(q.Explanation, "whole in the note") || !strings.HasSuffix(q.Whole, "\nand 3 more, each whole in the note: c, d, shares") {
+		t.Errorf("the glance:\n%s", q.Explanation)
+	}
+	for k := range values {
+		if !strings.Contains(q.Details, "+ "+k+": ") {
+			t.Errorf("the masked details lack %s:\n%s", k, q.Details)
+		}
+	}
+	if strings.Contains(q.Details, "/storage") {
+		t.Errorf("the masked details show a path:\n%s", q.Details)
+	}
+	if refusal, ok := outward.Check(q.Details, "shanks"); !ok {
+		t.Errorf("the router would withhold the masked details: %s", refusal)
+	}
+	if _, ok := outward.Secret(q.WholeDetails, "shanks"); !ok {
+		t.Error("the router would refuse the whole details")
+	}
+	// A value too long for a glance is cut there, and says so.
+	r2 := newProposerRig(t)
+	if _, err := r2.pr.propose(context.Background(), proposeInput{module: "mounts", node: "shanks", values: map[string]any{"shares": value}}); err != nil {
+		t.Fatal(err)
+	}
+	q2 := r2.askSent(t)
+	// The cut point is 160 characters, its marker inside the bound.
+	if last := q2.Whole[strings.LastIndex(q2.Whole, "\n")+1:]; len([]rune(last)) != asks.PointLength {
+		t.Errorf("the cut point is %d characters, not %d: %q", len([]rune(last)), asks.PointLength, last)
+	}
+	if !strings.HasSuffix(q2.Whole, "… (cut: whole in the note)") || !strings.HasSuffix(q2.Explanation, "‹path›") && !strings.HasSuffix(q2.Explanation, "… (cut: in the note)") || !strings.Contains(q2.WholeDetails, "+ shares: "+value) || asks.Glance(q2.Whole) != nil {
+		t.Errorf("the cut is not said, or the note lacks the whole:\n%s\n--\n%s", q2.Whole, q2.WholeDetails)
+	}
+}
+
+// The review of #304: a value given to a secret's name, past the second key, is said with its key named and its
+// value withheld, in the note on every channel; the router has nothing left to withhold unnamed or refuse. A line
+// the router would refuse even so is refused at propose, in the controller's words.
+func TestASecretNamedKeyIsNamedAndItsValueWithheld(t *testing.T) {
+	r := newProposerRig(t)
+	values := map[string]any{"a": "1", "b": "2", "c": "3", "password": "hunter2"}
+	if _, err := r.pr.propose(context.Background(), proposeInput{module: "notes", node: "laptop", values: values}); err != nil {
+		t.Fatal(err)
+	}
+	q := r.askSent(t)
+	for _, form := range []string{q.Details, q.WholeDetails, q.Explanation, q.Whole} {
+		if strings.Contains(form, "hunter2") {
+			t.Errorf("the value reaches the phone:\n%s", form)
+		}
+	}
+	if !strings.Contains(q.Details, "+ password (value withheld)") {
+		t.Errorf("the key is not named with its value withheld:\n%s", q.Details)
+	}
+	if q.WholeDetails != "" && !strings.Contains(q.WholeDetails, "+ password (value withheld)") {
+		t.Errorf("the whole details do not name the key:\n%s", q.WholeDetails)
+	}
+	if line, why := judgeLines(q.Details, false, nil); line != "" {
+		t.Errorf("the router would withhold %q: %s", line, why)
+	}
+	if line, why := judgeLines(q.WholeDetails, true, nil); line != "" {
+		t.Errorf("the router would refuse %q: %s", line, why)
+	}
+	if !strings.HasSuffix(q.Explanation, "\nand 2 more, each in the note: c, password") {
+		t.Errorf("the glance:\n%s", q.Explanation)
+	}
+	// A key shaped like a secret cannot be named on any channel: refused at propose, in the controller's words, and
+	// the key itself not echoed.
+	r2 := newProposerRig(t)
+	secretKey := "ghp_abcdefghijklmnopqrstuvwxyz0123456789"
+	_, err := r2.pr.propose(context.Background(), proposeInput{module: "notes", node: "laptop",
+		values: map[string]any{"a": "1", "b": "2", secretKey: "3"}})
+	if err == nil || !strings.Contains(err.Error(), "Nothing was proposed") || strings.Contains(err.Error(), secretKey) {
+		t.Errorf("a secret-shaped key: %v", err)
+	}
+	if len(r2.sent) != 0 {
+		t.Errorf("the refused proposal was asked")
+	}
+}
+
+// keyOfLine names a change's key, and never one shaped like a secret.
+func TestARefusalNamesTheKeyAndNeverASecret(t *testing.T) {
+	for line, want := range map[string]string{
+		"+ password (value withheld)":                   "password",
+		"~ shares: ‹path› (was: none)":                  "shares",
+		"+ ghp_abcdefghijklmnopqrstuvwxyz0123456789: 1": "whose key is shaped like a secret",
+		"Proposed by g14 at 15:04.":                     "Proposed by g14 at 15:04.",
+	} {
+		if got := keyOfLine(line); got != want {
+			t.Errorf("%q: %q, want %q", line, got, want)
+		}
+	}
+}

cmd/mesh-controller/push.go

@@ -249,7 +249,13 @@ func serve(ctx context.Context) (err error) {
 	// (novox/hq to-be 45 §9).
 	checkEvents = bus
 	// And every walk this controller keeps in a new state, for the delivery it walks (novox/hq ADR 0239).
-	inventory.PlanSaved = func(_ *inventory.Inventory, p inventory.Plan) { sayPlanMoved(ctx, bus, open.inventory, p) }
+	inventory.PlanSaved = func(_ *inventory.Inventory, p inventory.Plan) {
+		sayPlanMoved(ctx, bus, open.inventory, p)
+		// A walk ended has taken what it reuses: its merges' check builds go (novox/hq ADR 0350 §5).
+		if p.WalkSaid == inventory.WalkEnded {
+			go forgetChecksOfWalk(context.WithoutCancel(ctx), open.inventory, p)
+		}
+	}
 	if err := server.Checks(following{open}); err != nil {
 		return err
 	}

cmd/mesh-controller/recorded_kept.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"sort"
 
@@ -83,6 +84,27 @@ func everyBuildKept(ctx context.Context, node string) bool {
 	return on != "" && on == node
 }
 
+type keepForSettingsKey struct{}
+
+// keepingBuildsForSettings is a context whose sends compose every module of one machine — recorded or rolling out —
+// at the build that machine was last sent, as keepingEveryBuild does, for a settings walk's send (novox/hq ADR 0344):
+// the layer the operator approved, and nothing of any module's new code. A build held for a person, or waiting
+// for a gate, stays where it is; the walk that is its own carries it.
+func keepingBuildsForSettings(ctx context.Context, node string) context.Context {
+	return context.WithValue(ctx, keepForSettingsKey{}, node)
+}
+
+// errSettingsCannotKeep is a settings walk's send refused because a build of its machine cannot be kept: what the
+// machine was last sent is not known, or a build it runs is gone from the records. It does not clear by itself, so
+// the walk fails on it rather than trying again (ADR 0344).
+var errSettingsCannotKeep = errors.New("the settings cannot be sent with every build kept")
+
+// settingsKeptOn is whether this context is a settings walk's send to this machine.
+func settingsKeptOn(ctx context.Context, node string) bool {
+	on, _ := ctx.Value(keepForSettingsKey{}).(string)
+	return on != "" && on == node
+}
+
 // recordedKept is, for a send under keepingRecorded, every recorded module the machine was last sent a
 // build of that the mesh's build is not identical to: module → the commit it keeps. Nil when the context
 // keeps nothing, or when what the machine was last sent is not known (it is then held whole elsewhere —
@@ -92,7 +114,7 @@ func everyBuildKept(ctx context.Context, node string) bool {
 // 490), and a machine whose last send is not known refuses the send: there is nothing to keep it at, and
 // composing the mesh's builds would be the very move the grants step must not make.
 func recordedKept(ctx context.Context, open *stores, node string) (map[string]string, error) {
-	every := everyBuildKept(ctx, node)
+	every := everyBuildKept(ctx, node) || settingsKeptOn(ctx, node)
 	skip, on := keptExcept(ctx)
 	if !on && !every {
 		return nil, nil
@@ -106,6 +128,9 @@ func recordedKept(ctx context.Context, open *stores, node string) (map[string]st
 		return nil, err
 	}
 	if !known {
+		if settingsKeptOn(ctx, node) {
+			return nil, fmt.Errorf("%w: what %s was last sent is not known (novox/hq ADR 0344)", errSettingsCannotKeep, node)
+		}
 		if every {
 			return nil, fmt.Errorf("what %s was last sent is not known, so the bus's user list cannot be sent "+
 				"there alone with every build kept (novox/hq issue 490)", node)
@@ -166,6 +191,10 @@ func keepRecorded(ctx context.Context, open *stores, node string, shelf map[stri
 		if err != nil {
 			return nil, err
 		}
+		if !found && settingsKeptOn(ctx, node) {
+			return nil, fmt.Errorf("%w: %s runs %s's build %s, which the build records no longer hold (novox/hq ADR 0344)",
+				errSettingsCannotKeep, node, m, short(kept[m]))
+		}
 		if !found && everyBuildKept(ctx, node) {
 			return nil, fmt.Errorf("%s runs %s's build %s, which the build records no longer hold: the bus's user "+
 				"list cannot be sent there alone with it kept (novox/hq issue 490)", node, m, short(kept[m]))

cmd/mesh-controller/release.go

@@ -616,6 +616,10 @@ func releaseBacklog(ctx context.Context, open *stores, by string) (*inventory.Pl
 	}
 	for _, p := range plans {
 		if p.Release != nil {
+			if by != "" && p.Release.Settings != nil {
+				return nil, fmt.Errorf("%s is sending %s; what waits is released once it ends — `plans %s` says where it is",
+					p.ID, p.Repository, p.ID)
+			}
 			if by != "" {
 				return nil, fmt.Errorf("%s is already releasing what waits; `plans %s` says where it is", p.ID, p.ID)
 			}
@@ -641,7 +645,9 @@ func releaseBacklog(ctx context.Context, open *stores, by string) (*inventory.Pl
 			return nil, err
 		}
 		for _, p := range recent {
-			if p.Release == nil {
+			// A settings walk that failed holds nothing back (novox/hq ADR 0344 §6): its failure is its module's
+			// settings on one machine, said on its own, not a build no gate passed.
+			if p.Release == nil || p.Release.Settings != nil {
 				continue
 			}
 			if p.State == inventory.PlanFailed {
@@ -702,6 +708,9 @@ func releaseBacklog(ctx context.Context, open *stores, by string) (*inventory.Pl
 // gate, or the machine being judged judged once more; the plan done when every machine is.
 func advanceRelease(ctx context.Context, open *stores, p *inventory.Plan) (bool, error) {
 	r := p.Release
+	if r.Settings != nil {
+		return advanceSettingsWalk(ctx, open, p)
+	}
 	now := time.Now().UTC()
 	if r.Gate == nil {
 		heard, err := releaseHeard(ctx, open)

cmd/mesh-controller/release_plan.go

@@ -13,6 +13,7 @@ import (
 
 	"github.com/nats-io/nats.go"
 
+	"github.com/novox/mesh-controller/internal/builder"
 	"github.com/novox/mesh-controller/internal/inventory"
 	"github.com/novox/mesh-controller/internal/link"
 )
@@ -313,6 +314,86 @@ func init() {
 	}
 }
 
+// reuseKey carries a walk's leave to take a check's build from askModule to the ask it makes (novox/hq ADR 0350 §2).
+type reuseKey struct{}
+
+// withReuse is ctx carrying a walk's leave to take a check's build.
+func withReuse(ctx context.Context, r *link.ReuseAsk) context.Context {
+	return context.WithValue(ctx, reuseKey{}, r)
+}
+
+// reuseIn is the leave ctx carries; nil for every ask but a walk's.
+func reuseIn(ctx context.Context) *link.ReuseAsk {
+	r, _ := ctx.Value(reuseKey{}).(*link.ReuseAsk)
+	return r
+}
+
+// reuseAsked is the leave an ask carries: a walk's, and never a dry run's — a dry run registers nothing, so it
+// takes nothing either (novox/hq ADR 0350 §2, §6).
+func reuseAsked(ctx context.Context, dryRun bool) *link.ReuseAsk {
+	if dryRun {
+		return nil
+	}
+	return reuseIn(ctx)
+}
+
+// reuseAskOf is a walk's leave to take a check's build: the pull requests of the merges it answers.
+func reuseAskOf(p *inventory.Plan) *link.ReuseAsk {
+	r := &link.ReuseAsk{}
+	if p.Delivery == nil {
+		return r
+	}
+	seen := map[link.PullRef]bool{}
+	for _, m := range p.Delivery.Merges {
+		pull, ok := pullOf(m)
+		if !ok {
+			continue
+		}
+		if !seen[pull] {
+			seen[pull] = true
+			r.Pulls = append(r.Pulls, pull)
+		}
+	}
+	return r
+}
+
+// checkedBuildsOf are the builds the build seat's checks of those pull requests said they made for their merges,
+// within the week check builds are kept (novox/hq ADR 0350 §2): read from the seat's own outcomes on the bus. A
+// variable so a test needs no bus.
+var checkedBuildsOf = func(ctx context.Context, pulls []link.PullRef) ([]link.CheckedBuild, error) {
+	if len(pulls) == 0 {
+		return nil, nil
+	}
+	js, err := aBus()
+	if err != nil {
+		return nil, err
+	}
+	defer js.Close()
+	return link.ReadCheckBuilds(ctx, js, buildSeatHeld(ctx), pulls, time.Now().Add(-builder.CheckBuildsKept))
+}
+
+// reuseWithVerdicts is a walk's leave with the builds its pull requests' verdicts name: the only builds the builder
+// may take (ADR 0350 §2). When they cannot be read the leave names none, and the walk builds, saying why.
+func reuseWithVerdicts(ctx context.Context, r *link.ReuseAsk) *link.ReuseAsk {
+	builds, err := checkedBuildsOf(ctx, r.Pulls)
+	if err != nil {
+		fmt.Printf("  the checks' builds of %d pull request(s) could not be read, so the walk builds: %v\n", len(r.Pulls), err)
+		return r
+	}
+	r.Builds = builds
+	return r
+}
+
+// pullOf is a merge's pull request: owner and repository, the last two parts of however the repository is spelled
+// (owner/repo, a path on the git seat, a URL), and its number. False when the merge names none.
+func pullOf(m inventory.PlanMerge) (link.PullRef, bool) {
+	parts := strings.Split(strings.Trim(strings.TrimSuffix(m.Repository, ".git"), "/"), "/")
+	if len(parts) < 2 || m.Number <= 0 || parts[len(parts)-2] == "" || parts[len(parts)-1] == "" {
+		return link.PullRef{}, false
+	}
+	return link.PullRef{Owner: parts[len(parts)-2], Repo: parts[len(parts)-1], Number: m.Number}, true
+}
+
 // askModule asks the build machine for one module of a plan and marks it asked, with the id it was
 // asked under (novox/hq ADR 0219) — or failed, with the plan, when it could not be asked.
 func askModule(ctx context.Context, p *inventory.Plan, name string, byName map[string]inventory.Entry) {
@@ -340,7 +421,9 @@ func askModule(ctx context.Context, p *inventory.Plan, name string, byName map[s
 	if p.Delivery != nil && p.Delivery.Alone && carried != "" {
 		ref = carried
 	}
-	id, err := askABuild(ctx, source, e.Source.Path, ref)
+	// **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.
+	id, err := askABuild(withReuse(ctx, reuseWithVerdicts(ctx, reuseAskOf(p))), source, e.Source.Path, ref)
 	if err != nil {
 		state.State = "failed"
 		state.Why = err.Error()
@@ -359,7 +442,7 @@ func askModule(ctx context.Context, p *inventory.Plan, name string, byName map[s
 	state.State = "asked"
 	state.AskedAt = &now
 	state.Build = id
-	state.Why, state.Commit, state.BuiltAt = "", "", nil
+	state.Why, state.Commit, state.BuiltAt, state.Made = "", "", nil, ""
 }
 
 // planBuilt marks a module built (or failed) in every open plan whose current tier holds it, and
@@ -371,6 +454,12 @@ func askModule(ctx context.Context, p *inventory.Plan, name string, byName map[s
 // would send machines, and the next tier, what the later merge replaced. asked is zero when the
 // build's request time is not known, and such an outcome is taken as before.
 func planBuilt(ctx context.Context, open *stores, module, commit, failed string, asked time.Time, id string) {
+	planBuiltSaying(ctx, open, module, commit, failed, asked, id, "")
+}
+
+// planBuiltSaying is planBuilt keeping what the build did — "reused from <check build>" or "built: <why>" (novox/hq
+// ADR 0350 §4) — on the module of the walk it answers.
+func planBuiltSaying(ctx context.Context, open *stores, module, commit, failed string, asked time.Time, id, made string) {
 	inv := open.inventory
 	// One controller works the plans at a time (novox/hq issue 213); an outcome waits its turn rather
 	// than write over what the holder is about to save. Not taken, it is still in the build records,
@@ -436,6 +525,7 @@ func planBuilt(ctx context.Context, open *stores, module, commit, failed string,
 			state.State = "built"
 			state.BuiltAt = &now
 			state.Commit = commit
+			state.Made = made
 		}
 		if err := inv.SavePlan(ctx, p); err != nil {
 			fmt.Printf("%s: cannot keep the plan: %v\n", p.ID, err)

cmd/mesh-controller/release_test.go

@@ -133,11 +133,15 @@ func aBacklog(t *testing.T) *backlogMesh {
 		}
 		return f, nil
 	}
-	wasSettle, wasEvery, wasBound := gateSettle, gateEvery, gateBound
-	gateSettle, gateEvery = 0, time.Hour
+	wasWithin, wasEvery, wasBound := gateWithin, gateEvery, gateBound
+	// The witness window is the node-engine's, from a start no test makes (novox/hq ADR 0351).
+	wasWindow := gateWitnessWindow
+	gateWitnessWindow = 0
+	t.Cleanup(func() { gateWitnessWindow = wasWindow })
+	gateWithin, gateEvery = time.Hour, time.Hour
 	t.Cleanup(func() {
 		machineMoves, releaseHeard, sendRollout, gatherGateFacts = wasMoves, wasHeard, wasSend, wasGather
-		gateSettle, gateEvery, gateBound = wasSettle, wasEvery, wasBound
+		gateWithin, gateEvery, gateBound = wasWithin, wasEvery, wasBound
 	})
 	return b
 }

cmd/mesh-controller/replay318_test.go

@@ -112,10 +112,14 @@ func TestReplay318(t *testing.T) {
 	}
 
 	wasMoves, wasHeard, wasSend, wasGather := machineMoves, releaseHeard, sendRollout, gatherGateFacts
-	wasSettle, wasEvery, wasBound := gateSettle, gateEvery, gateBound
+	wasWithin, wasEvery, wasBound := gateWithin, gateEvery, gateBound
+	// The witness window is the node-engine's, from a start no test makes (novox/hq ADR 0351).
+	wasWindow := gateWitnessWindow
+	gateWitnessWindow = 0
+	t.Cleanup(func() { gateWitnessWindow = wasWindow })
 	t.Cleanup(func() {
 		machineMoves, releaseHeard, sendRollout, gatherGateFacts = wasMoves, wasHeard, wasSend, wasGather
-		gateSettle, gateEvery, gateBound = wasSettle, wasEvery, wasBound
+		gateWithin, gateEvery, gateBound = wasWithin, wasEvery, wasBound
 	})
 	machineMoves = func(ctx context.Context, open *stores, f moveFacts, node string, all bool) ([]inventory.CarriedMove, error) {
 		modules, err := open.inventory.Assigned(ctx, node)
@@ -184,7 +188,7 @@ func TestReplay318(t *testing.T) {
 		return f, nil
 	}
 	// The bound is reached at the first judging that is not a pass: what happened at 11:21 happens at once.
-	gateSettle, gateEvery, gateBound = 0, 0, 0
+	gateWithin, gateEvery, gateBound = time.Hour, 0, 0
 
 	for i := 0; i < 12; i++ {
 		advancePlans(ctx, open)

cmd/mesh-controller/replays_test.go

@@ -248,9 +248,13 @@ func TestReplayCrashLoopFailsItsGateOnTheFirstMachine(t *testing.T) {
 		return names, nil
 	}
 	t.Cleanup(func() { sendRollout = wasSend })
-	wasSettle, wasEvery, wasBound := gateSettle, gateEvery, gateBound
-	gateSettle, gateEvery = 0, 0
-	t.Cleanup(func() { gateSettle, gateEvery, gateBound = wasSettle, wasEvery, wasBound })
+	wasWithin, wasEvery, wasBound := gateWithin, gateEvery, gateBound
+	// The witness window is the node-engine's, from a start no test makes (novox/hq ADR 0351).
+	wasWindow := gateWitnessWindow
+	gateWitnessWindow = 0
+	t.Cleanup(func() { gateWitnessWindow = wasWindow })
+	gateWithin, gateEvery = time.Hour, 0
+	t.Cleanup(func() { gateWithin, gateEvery, gateBound = wasWithin, wasEvery, wasBound })
 
 	built := time.Now().UTC()
 	plan := inventory.Plan{ID: "plan-crashloop", Repository: "novox/mesh-catalog", Branch: "main", Commit: "c2",

cmd/mesh-controller/seatverbs.go

@@ -452,6 +452,11 @@ func (a *verbArguments) commandLine() ([]string, error) {
 	case "queue":
 		// As data, the table its output (novox/hq issue 455).
 		return []string{"queue", "--json"}, nil
+	case "forget-checks":
+		if err := need("owner", "repo", "number"); err != nil {
+			return nil, err
+		}
+		return []string{"forget-checks", str("owner"), str("repo"), str("number")}, nil
 	case "cancel", "kill":
 		if err := need("id"); err != nil {
 			return nil, err

cmd/mesh-controller/served_own_names_test.go

@@ -0,0 +1,60 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// novox/hq ADR 0346, issue 624: a provider on another machine serves its consumers its own composed
+// names, as that machine composes them; one it does not compose is left out, said under the need.
+func TestAProviderElsewhereServesItsOwnComposedName(t *testing.T) {
+	open := aMesh(t)
+	ctx := t.Context()
+	forge, err := catalogue.ParseManifest([]byte(`{"module":"forge","version":"1","requires":["route"],
+	  "provides":[{"name":"npm-package-registry","scope":"mesh"}],
+	  "contributes":{"route":{"web":{"label":"git","port":3000}}},
+	  "serves":{"npm-package-registry":{"scheme":"http","port":3000,"npm-path":"/api/packages/novox/npm/",
+	    "public-root":"https://${bound:route:name-web}/api/packages/novox/npm/"}}}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	register(t, open, catalogue.Manifest{Module: "proxy", Version: "1", Provides: catalogue.FromAnywhere("route"),
+		Receives: map[string]string{"route": "/var/lib/proxy/routes.json"}})
+	register(t, open, forge)
+	register(t, open, catalogue.Manifest{Module: "lab", Version: "1", Requires: []string{"npm-package-registry"},
+		Binds: map[string]string{"npm-package-registry": "/var/lib/lab/package-registry.json"}})
+	for _, a := range [][2]string{{"anchor", "proxy"}, {"anchor", "forge"}, {"laptop", "lab"}} {
+		if _, err := assign(ctx, open, a[0], a[1]); err != nil {
+			t.Fatalf("assign %s %s: %v", a[0], a[1], err)
+		}
+	}
+
+	if err := open.inventory.SetPublicDomain(ctx, "anchor", "example.test"); err != nil {
+		t.Fatal(err)
+	}
+	plan, _, err := planFor(ctx, open, "laptop")
+	if err != nil {
+		t.Fatal(err)
+	}
+	n := need(t, plan, "lab", "npm-package-registry")
+	if n.Serves["public-root"] != "https://git.example.test/api/packages/novox/npm/" || len(n.LeftOut) != 0 {
+		t.Fatalf("the consumer elsewhere is served the forge's public root: %v, left out %v", n.Serves, n.LeftOut)
+	}
+
+	if err := open.inventory.SetPublicDomain(ctx, "anchor", ""); err != nil {
+		t.Fatal(err)
+	}
+	plan, _, err = planFor(ctx, open, "laptop")
+	if err != nil {
+		t.Fatal(err)
+	}
+	n = need(t, plan, "lab", "npm-package-registry")
+	if _, there := n.Serves["public-root"]; there {
+		t.Fatalf("anchor composes no public name, so the key is left out: %v", n.Serves)
+	}
+	if len(n.LeftOut) != 1 || !strings.Contains(n.LeftOut[0], `without "public-root"`) {
+		t.Fatalf("and the need says so: %v", n.LeftOut)
+	}
+}

cmd/mesh-controller/settings_walk.go

@@ -0,0 +1,281 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"slices"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// An approved settings change is sent by a walk at once, and the operator's one Approve is its push (novox/hq ADR
+// 0344, issue 641).
+//
+// On 2026-10-13 the operator approved a betterbird proposal on Telegram and nothing happened: the warrant set the
+// layer, and the push stayed a separate act (ADR 0277 §18) that nobody took. Now the warrant that sets the layer
+// opens a **settings walk**: the walk ADR 0236 opens for builds waiting for a gate, with a layer in place of the
+// builds. Its order is every machine running the module that the layer reaches, the control node last; each is
+// sent and its module judged there, from the machine's report on that send, before the next is sent. The send is
+// the layer alone: every module there stays at the build its machine was last sent (keepingBuildsForSettings), so a
+// build held for a person (ADR 0242) or waiting for a gate stays where it is — a policy of `record` holds a build,
+// never a setting — and a send that would move a running module's data stops the walk (ADR 0217 §3). The walk says its start and end on `plan-moved` (ADR 0308), and the holder of the operator's
+// channel tells its end once. A failure stops the walk and leaves the layer as approved; it holds back nothing
+// else.
+
+// settingsWalkPrefix names a settings walk's id.
+const settingsWalkPrefix = "settings-"
+
+// settingsWalkFor is what a settings walk says it is for, where a merge's walk says its repository.
+func settingsWalkFor(s inventory.PlanSettings) string {
+	where := s.Node
+	if where == "" {
+		where = "the whole mesh"
+	}
+	return fmt.Sprintf("the settings of %s on %s", s.Module, where)
+}
+
+// settingsWalkOrder is the machines a layer reaches, in the order a settings walk sends them: every machine
+// running the module, or the one the layer names when it runs it there, sorted, the control node last. Pure.
+func settingsWalkOrder(node string, running, controllers []string) []string {
+	var order, last []string
+	for _, n := range running {
+		if node != "" && n != node {
+			continue
+		}
+		if slices.Contains(controllers, n) {
+			last = append(last, n)
+		} else {
+			order = append(order, n)
+		}
+	}
+	sort.Strings(order)
+	sort.Strings(last)
+	return append(order, last...)
+}
+
+// openSettingsWalk opens the walk that sends an approved layer, and answers the words of what it does: the
+// machines it sends, or that no machine runs the module and nothing is sent. Called on the operator's warrant,
+// after the layer is set.
+var openSettingsWalk = func(ctx context.Context, open *stores, s inventory.PlanSettings) (string, error) {
+	inv := open.inventory
+	running, err := inv.Running(ctx, s.Module)
+	if err != nil {
+		return "", err
+	}
+	controllers, err := inv.Running(ctx, catalogue.ControllerSeatName)
+	if err != nil {
+		return "", err
+	}
+	order := settingsWalkOrder(s.Node, running, controllers)
+	if len(order) == 0 {
+		return fmt.Sprintf("no machine runs %s there, so there is nothing to send", s.Module), nil
+	}
+	release, err := inv.HoldPlans(ctx, true)
+	if err != nil {
+		return "", err
+	}
+	defer release()
+	now := time.Now().UTC()
+	p := inventory.Plan{ID: fmt.Sprintf("%s%d", settingsWalkPrefix, now.UnixNano()), Repository: settingsWalkFor(s),
+		Created: now, State: inventory.PlanRolling, Tiers: [][]string{{s.Module}}, Modules: map[string]*inventory.PlanModule{},
+		Release: &inventory.PlanRelease{Order: order, Settings: &s},
+		Note: fmt.Sprintf("approved (ask %s): sent to %s, one machine at a time, each judged", s.Ask,
+			strings.Join(order, ", "))}
+	if err := inv.SavePlan(ctx, &p); err != nil {
+		return "", err
+	}
+	fmt.Printf("%s: %s — %s\n", p.ID, p.Repository, p.Note)
+	return fmt.Sprintf("%s sends it to %s, one machine at a time, each judged", p.ID, strings.Join(order, ", ")), nil
+}
+
+// settingsDataMoves is what a settings walk's send to a machine would move of a running module's data: composed as
+// that send composes it, every build kept, and compared with what the machine was last sent (ADR 0217 §3).
+var settingsDataMoves = func(ctx context.Context, open *stores, node string) ([]dataMove, error) {
+	keeping := keepingBuildsForSettings(keepingRecorded(ctx), node)
+	gens, err := generators(keeping, open)
+	if err != nil {
+		return nil, err
+	}
+	plan, settings, err := planFor(keeping, open, node)
+	if err != nil {
+		return nil, err
+	}
+	declared, err := declarationWith(keeping, open, node, plan, settings, gens, Reading)
+	if err != nil {
+		return nil, err
+	}
+	body, err := declared.Body()
+	if err != nil {
+		return nil, err
+	}
+	return heldMoves(keeping, open.inventory, node, body, nil)
+}
+
+// judgingOn is the open walk, other than the one named, whose gate is judging on a machine; empty when none is. A
+// settings walk sends a machine only when no other walk judges there: its send would set aside the declaration
+// that walk's gate reads the machine's report against.
+var judgingOn = func(ctx context.Context, open *stores, self, node string) (string, error) {
+	plans, err := open.inventory.OpenPlans(ctx)
+	if err != nil {
+		return "", err
+	}
+	return judgingIn(plans, self, node), nil
+}
+
+// judgingIn is judgingOn over plans read. Pure.
+func judgingIn(plans []inventory.Plan, self, node string) string {
+	judging := func(g *inventory.PlanGate) bool {
+		return g != nil && g.Verdict == "" && slices.Contains(g.Machines, node)
+	}
+	for _, p := range plans {
+		if p.ID == self || !p.Open() {
+			continue
+		}
+		if p.Release != nil {
+			if judging(p.Release.Gate) {
+				return p.ID
+			}
+			continue
+		}
+		for _, s := range p.Modules {
+			if s != nil && judging(s.Gate) {
+				return p.ID
+			}
+		}
+	}
+	return ""
+}
+
+// advanceSettingsWalk takes one step of a settings walk: the next machine sent and its module judged there, or the
+// machine being judged judged once more; done when every machine is.
+func advanceSettingsWalk(ctx context.Context, open *stores, p *inventory.Plan) (bool, error) {
+	r, s := p.Release, p.Release.Settings
+	now := time.Now().UTC()
+	wait := func(note string) (bool, error) {
+		changed := p.Note != note
+		p.Note = note
+		return changed, nil
+	}
+	if r.Gate == nil {
+		heard, err := releaseHeard(ctx, open)
+		if err != nil {
+			return false, err
+		}
+		for r.Next < len(r.Order) {
+			node := r.Order[r.Next]
+			if !heard[node] {
+				r.Skipped = append(r.Skipped, node)
+				r.Next++
+				continue
+			}
+			if id, err := judgingOn(ctx, open, p.ID, node); err != nil {
+				return false, err
+			} else if id != "" {
+				return wait(fmt.Sprintf("waiting before %s: %s is judging there", node, id))
+			}
+			// **A running module's data that would move is a person's word** (ADR 0217 §3): the walk stops before
+			// that machine, failed and said, and `push --move` sends it.
+			held, err := settingsDataMoves(ctx, open, node)
+			if errors.Is(err, errSettingsCannotKeep) {
+				return failBefore(p, node, err.Error())
+			}
+			if err != nil {
+				return false, fmt.Errorf("whether %s's data would move could not be read: %w", node, err)
+			}
+			if len(held) > 0 {
+				var said strings.Builder
+				sayDataHeld(&said, node, held)
+				return failBefore(p, node, "a running module's data would move there — "+
+					strings.Join(strings.Fields(said.String()), " "))
+			}
+			// A build that cannot be kept is refused by the composition above, which is the send's own, and fails the
+			// walk there: the send flattens its refusals into words, so it is not looked for again here.
+			sent, grants, err := sendJudged(keepingBuildsForSettings(ctx, node), open, node)
+			if err != nil {
+				return false, fmt.Errorf("sending %s %s: %w", node, settingsWalkFor(*s), err)
+			}
+			// **The module's build is the one the gate judges** (issue 641 review): kept by this send, it is what a
+			// crossing send — a merge's walk sending the machine a new build of the module — supersedes, so this gate
+			// never reads that send's report as its own.
+			kept := ""
+			if builds, known, err := open.inventory.SentBuilds(ctx, node); err == nil && known {
+				kept = builds[s.Module]
+			}
+			r.Gate = &inventory.PlanGate{Component: coreComponent(s.Module), Machines: sent, Since: &now,
+				From: kept, To: kept, Sent: sentNow(ctx, open.inventory, sent), Grants: grants}
+			p.Note = fmt.Sprintf("sent %s %s (ask %s), every build there kept; judging %s there", node,
+				settingsWalkFor(*s), s.Ask, s.Module)
+			if said := grantsSaid(grants); said != "" {
+				p.Note += "; " + said
+			}
+			fmt.Printf("%s: %s\n", p.ID, p.Note)
+			return true, nil
+		}
+		p.State, p.Tier = inventory.PlanDone, len(p.Tiers)
+		p.Note = fmt.Sprintf("%s (ask %s) delivered on %s", settingsWalkFor(*s), s.Ask, strings.Join(r.Done, ", "))
+		if len(r.Done) == 0 {
+			// Sent nowhere is not delivered: said as the walk's failure, so the operator is not told it landed.
+			p.State = inventory.PlanFailed
+			p.Note = fmt.Sprintf("%s (ask %s) was sent to no machine", settingsWalkFor(*s), s.Ask)
+		}
+		if len(r.Skipped) > 0 {
+			p.Note += "; not heard from, left as they were, their next send carries it: " + strings.Join(r.Skipped, ", ")
+		}
+		fmt.Printf("%s: %s\n", p.ID, p.Note)
+		return true, nil
+	}
+	g := r.Gate
+	node := r.Order[r.Next]
+	verdict, err := judgeMoves(ctx, open, g, []judged{{module: s.Module, node: node}}, now)
+	if err != nil {
+		return false, err
+	}
+	switch verdict {
+	case "":
+		return wait(fmt.Sprintf("judging %s on %s: %s", s.Module, node, gateLine(g)))
+	case inventory.GatePassed:
+		r.Done = append(r.Done, node)
+		r.Next++
+		r.Gate = nil
+		return true, nil
+	case inventory.GateSuperseded:
+		p.State = inventory.PlanSuperseded
+		p.Note = fmt.Sprintf("superseded on %s: %s — nothing judged, nothing put back; the layer is set, and the "+
+			"machines not yet sent take it at their next send", node, g.Why)
+		fmt.Printf("%s: %s\n", p.ID, p.Note)
+		return true, nil
+	}
+	p.State = inventory.PlanFailed
+	p.Note = fmt.Sprintf("%s failed its gate on %s: %s — the layer stays as the operator approved it, and the one it "+
+		"replaced is in `settings %s` history", settingsWalkFor(*s), node, g.Why, s.Module) + unreached(r)
+	fmt.Printf("%s: %s\n", p.ID, p.Note)
+	return true, nil
+}
+
+// failBefore ends a settings walk failed before it sent a machine, saying why, and that the layer stays.
+func failBefore(p *inventory.Plan, node, why string) (bool, error) {
+	r, s := p.Release, p.Release.Settings
+	p.State = inventory.PlanFailed
+	p.Note = fmt.Sprintf("%s not sent to %s: %s; the layer stays as the operator approved it", settingsWalkFor(*s),
+		node, why) + unreached(r)
+	fmt.Printf("%s: %s\n", p.ID, p.Note)
+	return true, nil
+}
+
+// unreached is what a stopped settings walk left without the layer, in words: the machines after the one it stopped
+// at, and those passed over as away (ADR 0344 §6). Empty when there are none.
+func unreached(r *inventory.PlanRelease) string {
+	var out string
+	if r.Next+1 < len(r.Order) {
+		out += "; not sent: " + strings.Join(r.Order[r.Next+1:], ", ")
+	}
+	if len(r.Skipped) > 0 {
+		out += "; not heard from, left as they were: " + strings.Join(r.Skipped, ", ")
+	}
+	return out
+}

cmd/mesh-controller/settings_walk_test.go

@@ -0,0 +1,572 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+	"github.com/novox/mesh-controller/internal/inventory"
+	"github.com/novox/mesh-controller/internal/lease"
+)
+
+// novox/hq ADR 0344, issue 641: the operator's one Approve on a settings proposal is the act that makes it take
+// effect. The warrant sets the layer and opens a settings walk, which sends it to the machines it reaches one at a
+// time, judging the module on each; the ask says so before the Approve, and nothing names a push.
+
+// The order: every machine running the module, or the one the layer names, the control node last.
+func TestASettingsWalkGoesToTheMachinesTheLayerReachesTheControlNodeLast(t *testing.T) {
+	running := []string{"shanks", "novox", "g14", "ace"}
+	for _, c := range []struct {
+		node string
+		want []string
+	}{
+		{"", []string{"ace", "g14", "shanks", "novox"}},
+		{"g14", []string{"g14"}},
+		{"novox", []string{"novox"}},
+		{"elsewhere", nil},
+	} {
+		if got := settingsWalkOrder(c.node, running, []string{"novox"}); !reflect.DeepEqual(got, c.want) {
+			t.Errorf("a layer on %q goes to %v, want %v", c.node, got, c.want)
+		}
+	}
+}
+
+// A settings walk sends a machine only when no other walk judges there.
+func TestASettingsWalkWaitsWhileAnotherWalkJudgesOnTheMachine(t *testing.T) {
+	judging := &inventory.PlanGate{Machines: []string{"g14"}}
+	passed := &inventory.PlanGate{Machines: []string{"g14"}, Verdict: inventory.GatePassed}
+	plans := []inventory.Plan{
+		{ID: "settings-1", State: inventory.PlanRolling, Release: &inventory.PlanRelease{Gate: judging}},
+		{ID: "release-2", State: inventory.PlanRolling, Release: &inventory.PlanRelease{Gate: passed}},
+		{ID: "plan-3", State: inventory.PlanRolling, Modules: map[string]*inventory.PlanModule{"app": {Gate: judging}}},
+		{ID: "plan-4", State: inventory.PlanDone, Modules: map[string]*inventory.PlanModule{"app": {Gate: judging}}},
+	}
+	if id := judgingIn(plans, "settings-1", "g14"); id != "plan-3" {
+		t.Errorf("on g14 %q judges, want plan-3 (itself, a passed gate and an ended walk are not judging)", id)
+	}
+	if id := judgingIn(plans[1:2], "x", "g14"); id != "" {
+		t.Errorf("a passed gate judges: %q", id)
+	}
+	if id := judgingIn(plans, "x", "shanks"); id != "" {
+		t.Errorf("on shanks %q judges", id)
+	}
+}
+
+// The ask says, before the Approve, that the layer is sent at once and judged, and that its end is told as every
+// walk's is; neither the ask nor the proposer's answer names a push any more.
+func TestTheAskSaysAnApprovedLayerIsSentAtOnce(t *testing.T) {
+	for _, c := range []struct {
+		in    proposeInput
+		where string
+		had   bool
+	}{
+		{proposeInput{module: "mounts", node: "shanks", values: mountsSources}, "shanks", false},
+		{proposeInput{module: "notes", values: map[string]any{"x": "1"}}, "every machine running notes", true},
+		{proposeInput{module: "notes", node: "laptop", clear: true}, "laptop", true},
+	} {
+		r := newProposerRig(t)
+		if c.had {
+			r.before, r.had = map[string]any{"x": "0"}, true
+		}
+		words, err := r.pr.propose(context.Background(), c.in)
+		if err != nil {
+			t.Fatal(err)
+		}
+		q := r.askSent(t)
+		if err := q.Check(r.now); err != nil {
+			t.Fatalf("the ask is refused: %v", err)
+		}
+		// At a glance (ADR 0345): the summary says it is sent at once by a walk, one machine at a time; the rest of
+		// what Approve does is the Details', which the router notes after the answers.
+		if !strings.Contains(q.Explanation, "sent at once by a walk to "+c.where+", one machine at a time, each judged") ||
+			!strings.Contains(q.Details, "and sent at once to "+c.where+", one machine at a time, each judged, "+
+				"every build there kept; its end is told as every walk's is") {
+			t.Errorf("the ask does not say the layer is sent at once to %s:\n%s", c.where, q.Explanation)
+		}
+		approve := q.Options[0]
+		if approve.Label != "Approve" || !strings.Contains(approve.Does, "sent to "+c.where+" at once") {
+			t.Errorf("Approve does %q", approve.Does)
+		}
+		if !strings.Contains(words, "a walk sends it to "+c.where+" at once") {
+			t.Errorf("the proposer's answer:\n%s", words)
+		}
+		for _, said := range []string{q.Explanation, q.Whole, approve.Does, words} {
+			if strings.Contains(said, "push") {
+				t.Errorf("a push is still named, as if a second act were needed:\n%s", said)
+			}
+		}
+	}
+}
+
+// ---- on the real stores -----------------------------------------------------------------------------
+
+// The warrant sets the layer and opens the walk that sends it, naming the machines it reaches; a layer for a
+// machine that does not run the module opens none and says so.
+func TestAnApprovedLayerOpensTheWalkThatSendsIt(t *testing.T) {
+	open := aMesh(t)
+	ctx := t.Context()
+	register(t, open, catalogue.Manifest{Module: "notes", Version: "1",
+		Resources: []map[string]any{{"id": "rc", "type": "file", "path": "/etc/notes.conf", "mode": "0644",
+			"content": "x = ${setting:x}\n"}}})
+	if _, err := assign(ctx, open, "laptop", "notes"); err != nil {
+		t.Fatal(err)
+	}
+	// A layer set by hand opens no walk: it still waits for a push (ADR 0344 §7).
+	if err := atTheTerminal(t, "settings", "set", "notes", `{"x":"0"}`, "--node", "laptop"); err != nil {
+		t.Fatal(err)
+	}
+	if plans, _ := open.inventory.OpenPlans(ctx); len(plans) != 0 {
+		t.Fatalf("a layer set at the terminal opened %d walk(s)", len(plans))
+	}
+	set := setLayerIn(open)
+	now := time.Now()
+	values := map[string]any{"x": "1"}
+	p := settingsProposal{Module: "notes", Values: values, From: "g14/claude-code", At: now,
+		Digest: layerDigest(values), BeforeDigest: layerDigest(nil)}
+	words, err := set(ctx, p, "s9", "approved by the operator (ask s9)")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(words, "+ x (ask s9); settings-") || !strings.Contains(words, "sends it to laptop, one machine at a time") {
+		t.Errorf("the warrant's words: %q", words)
+	}
+	plans, err := open.inventory.OpenPlans(ctx)
+	if err != nil || len(plans) != 1 {
+		t.Fatalf("open walks: %+v %v", plans, err)
+	}
+	w := plans[0]
+	if w.Release == nil || w.Release.Settings == nil || w.Release.Settings.Module != "notes" || w.Release.Settings.Ask != "s9" ||
+		!reflect.DeepEqual(w.Release.Order, []string{"laptop"}) || w.Repository != "the settings of notes on the whole mesh" ||
+		!reflect.DeepEqual(w.Tiers, [][]string{{"notes"}}) {
+		t.Fatalf("the settings walk: %+v %+v", w, w.Release)
+	}
+
+	// A machine's layer where the module does not run: set, and nothing to send.
+	q := settingsProposal{Module: "notes", Node: "anchor", Values: values, From: "g14/claude-code", At: now,
+		Digest: layerDigest(values), BeforeDigest: layerDigest(nil)}
+	words, err = set(ctx, q, "s10", "approved by the operator (ask s10)")
+	if err != nil || !strings.Contains(words, "no machine runs notes there, so there is nothing to send") {
+		t.Fatalf("a layer nobody runs: %q %v", words, err)
+	}
+	if plans, _ := open.inventory.OpenPlans(ctx); len(plans) != 1 {
+		t.Fatalf("a walk was opened for a machine that does not run the module: %d open", len(plans))
+	}
+
+	// A walk that cannot be opened is the act's failure, said with the push that sends it by hand.
+	was := openSettingsWalk
+	openSettingsWalk = func(context.Context, *stores, inventory.PlanSettings) (string, error) {
+		return "", fmt.Errorf("the plans are not to be had")
+	}
+	t.Cleanup(func() { openSettingsWalk = was })
+	again := map[string]any{"x": "2"}
+	byHand := map[string]any{"x": "0"}
+	r := settingsProposal{Module: "notes", Node: "laptop", Values: again, Before: byHand, HadLayer: true,
+		From: "g14/claude-code", At: now, Digest: layerDigest(again), BeforeDigest: layerDigest(byHand)}
+	if _, err := set(ctx, r, "s11", "approved"); err == nil || !strings.Contains(err.Error(), "is set, and the walk that "+
+		"sends it could not be opened: the plans are not to be had — `push laptop` sends it") {
+		t.Errorf("an unopened walk: %v", err)
+	}
+}
+
+// walkMesh is a mesh where `app` runs c1 on anchor and laptop and nothing waits for a gate: every send applied at
+// once, recorded, and judged from the reports, with a machine named broken failing what it was sent.
+type walkMesh struct {
+	open   *stores
+	sent   [][]string
+	broken map[string]bool
+	// kept says, per send, whether it kept every build of its machine; moves is the data a machine's send would move.
+	kept  []bool
+	moves map[string][]dataMove
+	heard map[string]bool
+}
+
+func aSettledMesh(t *testing.T) *walkMesh {
+	t.Helper()
+	open := aMesh(t)
+	ctx := t.Context()
+	inv := open.inventory
+	w := &walkMesh{open: open, broken: map[string]bool{}, moves: map[string][]dataMove{},
+		heard: map[string]bool{"anchor": true, "laptop": true}}
+	withConditionsInMemory(t)
+	was := doctorFrom
+	doctorFrom = nil
+	t.Cleanup(func() { doctorFrom = was })
+	old := time.Now().Add(-2 * time.Hour)
+	manifest, _ := json.Marshal(catalogue.Manifest{Module: "app", Version: "1"})
+	if err := inv.RecordBuild(ctx, inventory.Build{ID: "build-app-c1", Module: "app", Commit: "c1",
+		Repository: "novox/mesh-catalog", Path: "modules/app", Manifest: manifest, Asked: old, At: old,
+		Made: []inventory.Artifact{{Name: "x", Kind: "bundle", Reference: "sha256:app-1"}}}); err != nil {
+		t.Fatal(err)
+	}
+	if err := inv.RegisterModule(ctx, catalogue.Manifest{Module: "app", Version: "1"}, inventory.Source{
+		Repository: "novox/mesh-catalog", Seat: "git", Path: "modules/app", BuiltFrom: "c1", Head: "c1", Asked: old}); err != nil {
+		t.Fatal(err)
+	}
+	for _, n := range []string{"anchor", "laptop"} {
+		if _, err := inv.Assign(ctx, n, "app"); err != nil {
+			t.Fatal(err)
+		}
+		if err := inv.RecordSent(ctx, nodeID(t, open, n), "d-"+n, map[string]string{"app": "c1"}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	wasMoves, wasHeard, wasSend, wasGather, wasData := machineMoves, releaseHeard, sendRollout, gatherGateFacts, settingsDataMoves
+	settingsDataMoves = func(_ context.Context, _ *stores, node string) ([]dataMove, error) { return w.moves[node], nil }
+	machineMoves = func(ctx context.Context, open *stores, f moveFacts, node string, all bool) ([]inventory.CarriedMove, error) {
+		modules, err := open.inventory.Assigned(ctx, node)
+		if err != nil {
+			return nil, err
+		}
+		sent, known, err := open.inventory.SentBuilds(ctx, node)
+		if err != nil {
+			return nil, err
+		}
+		return f.moves(node, modules, sent, known, all), nil
+	}
+	releaseHeard = func(context.Context, *stores) (map[string]bool, error) { return w.heard, nil }
+	n := 0
+	sendRollout = func(ctx context.Context, open *stores, names []string) ([]string, error) {
+		w.sent = append(w.sent, append([]string(nil), names...))
+		w.kept = append(w.kept, len(names) == 1 && settingsKeptOn(ctx, names[0]))
+		current, err := open.inventory.CurrentBuilds(ctx)
+		if err != nil {
+			return nil, err
+		}
+		for _, node := range names {
+			modules, _ := open.inventory.Assigned(ctx, node)
+			carried := map[string]string{}
+			for _, m := range modules {
+				carried[m] = current[m].Commit
+			}
+			n++
+			digest := fmt.Sprintf("d-%s-%d", node, n)
+			if err := open.inventory.RecordSent(ctx, nodeID(t, open, node), digest, carried); err != nil {
+				return nil, err
+			}
+			if _, err := open.inventory.RecordDoing(ctx, nodeID(t, open, node), inventory.Doing{Node: node,
+				Outcome: inventory.OutcomeApplied, Declared: digest, Applied: 1, At: time.Now()}); err != nil {
+				return nil, err
+			}
+		}
+		return names, nil
+	}
+	gatherGateFacts = func(ctx context.Context, open *stores, component string) (gateFacts, error) {
+		f := gateFacts{now: time.Now(), reports: map[string]inventory.Reported{}, engines: map[string]string{},
+			rolledBack: map[string][]lease.Rollback{}, served: map[string]served{}}
+		reports, err := open.inventory.LastReports(ctx)
+		if err != nil {
+			return f, err
+		}
+		for _, r := range reports {
+			if w.broken[r.Node] {
+				r.Outcome = inventory.OutcomeFailed
+			}
+			f.reports[r.Node] = r
+		}
+		return f, nil
+	}
+	wasWithin, wasEvery, wasBound := gateWithin, gateEvery, gateBound
+	// The witness window is the node-engine's, from a start no test makes (novox/hq ADR 0351).
+	wasWindow := gateWitnessWindow
+	gateWitnessWindow = 0
+	t.Cleanup(func() { gateWitnessWindow = wasWindow })
+	gateWithin, gateEvery = time.Hour, time.Hour
+	t.Cleanup(func() {
+		machineMoves, releaseHeard, sendRollout, gatherGateFacts = wasMoves, wasHeard, wasSend, wasGather
+		settingsDataMoves = wasData
+		gateWithin, gateEvery, gateBound = wasWithin, wasEvery, wasBound
+	})
+	return w
+}
+
+func (w *walkMesh) walk(t *testing.T) inventory.Plan {
+	t.Helper()
+	plans, err := w.open.inventory.RecentPlans(t.Context(), 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, p := range plans {
+		if p.Release != nil && p.Release.Settings != nil {
+			return p
+		}
+	}
+	t.Fatal("no settings walk")
+	return inventory.Plan{}
+}
+
+// The walk sends the first machine alone and judges the module there before it sends the next, and ends
+// delivered on both; nothing waited for a gate, so each send carried the layer alone.
+func TestASettingsWalkSendsOneMachineAtATimeEachJudged(t *testing.T) {
+	judgeLeavesAsTheCore(t)
+	w := aSettledMesh(t)
+	ctx := t.Context()
+	words, err := openSettingsWalk(ctx, w.open, inventory.PlanSettings{Module: "app", Ask: "s1", Change: "~ x"})
+	if err != nil || !strings.Contains(words, "sends it to anchor, laptop") {
+		t.Fatalf("%q %v", words, err)
+	}
+	advancePlans(ctx, w.open)
+	if !reflect.DeepEqual(w.sent, [][]string{{"anchor"}}) {
+		t.Fatalf("sent %v: the first machine alone, before it is judged", w.sent)
+	}
+	p := w.walk(t)
+	if p.Release.Gate == nil || p.Release.Next != 0 || !strings.Contains(p.Note, "judging app on anchor") {
+		t.Fatalf("the walk after its first send: %s %+v", p.Note, p.Release)
+	}
+	gateEvery = 0
+	for i := 0; i < 6; i++ {
+		advancePlans(ctx, w.open)
+	}
+	if !reflect.DeepEqual(w.sent, [][]string{{"anchor"}, {"laptop"}}) {
+		t.Fatalf("sent %v", w.sent)
+	}
+	p = w.walk(t)
+	if p.State != inventory.PlanDone || !reflect.DeepEqual(p.Release.Done, []string{"anchor", "laptop"}) ||
+		p.Outcome() != inventory.WalkDelivered || !strings.Contains(p.Note, "delivered on anchor, laptop") {
+		t.Fatalf("the walk is %s: %s %+v", p.State, p.Note, p.Release)
+	}
+	// It said its start and its end, so the operator is told once (ADR 0308).
+	if p.Times == nil || p.Times.Started == nil || p.Times.Ended == nil {
+		t.Fatalf("the walk's start and end are not marked: %+v", p.Times)
+	}
+	// Nothing waits, and no walk of waiting builds opened beside it.
+	if r, err := releaseBacklog(ctx, w.open, ""); err != nil || r != nil {
+		t.Fatalf("%+v %v", r, err)
+	}
+}
+
+// A machine that fails what it was sent stops the walk there: the next is not sent, the layer stays, and the
+// failure holds back no walk of waiting builds.
+func TestAFailedSettingsWalkStopsAndHoldsNothingBack(t *testing.T) {
+	w := aSettledMesh(t)
+	ctx := t.Context()
+	inv := w.open.inventory
+	w.broken["anchor"] = true
+	if err := inv.KeepSettings(ctx, "", "app", map[string]any{"x": "1"}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := openSettingsWalk(ctx, w.open, inventory.PlanSettings{Module: "app", Ask: "s2"}); err != nil {
+		t.Fatal(err)
+	}
+	for i := 0; i < 4; i++ {
+		advancePlans(ctx, w.open)
+	}
+	p := w.walk(t)
+	if p.State != inventory.PlanFailed || p.Outcome() != inventory.WalkFailed ||
+		!strings.Contains(p.Note, "the settings of app on the whole mesh failed its gate on anchor") ||
+		!strings.Contains(p.Note, "the layer stays as the operator approved it") || !strings.Contains(p.Note, "not sent: laptop") {
+		t.Fatalf("the walk is %s: %s", p.State, p.Note)
+	}
+	if !reflect.DeepEqual(w.sent, [][]string{{"anchor"}}) {
+		t.Fatalf("sent %v: anchor alone, nothing to laptop", w.sent)
+	}
+	if layer, has, err := inv.Layer(ctx, "", "app"); err != nil || !has || layer["x"] != "1" {
+		t.Fatalf("the layer after the failure: %v %v %v", layer, has, err)
+	}
+	// A build that waits for a gate is still walked: the failed settings walk holds nothing back.
+	w.broken["anchor"] = false
+	now := time.Now().Add(-time.Minute)
+	manifest, _ := json.Marshal(catalogue.Manifest{Module: "app", Version: "1"})
+	if err := inv.RecordBuild(ctx, inventory.Build{ID: "build-app-c2", Module: "app", Commit: "c2",
+		Repository: "novox/mesh-catalog", Path: "modules/app", Manifest: manifest, Asked: now, At: now,
+		Made: []inventory.Artifact{{Name: "x", Kind: "bundle", Reference: "sha256:app-2"}}}); err != nil {
+		t.Fatal(err)
+	}
+	if err := inv.RegisterModule(ctx, catalogue.Manifest{Module: "app", Version: "1"}, inventory.Source{
+		Repository: "novox/mesh-catalog", Seat: "git", Path: "modules/app", BuiltFrom: "c2", Head: "c2", Asked: now}); err != nil {
+		t.Fatal(err)
+	}
+	if r, err := releaseBacklog(ctx, w.open, ""); err != nil || r == nil {
+		t.Fatalf("the waiting build is held back by a failed settings walk: %+v %v", r, err)
+	}
+}
+
+// Each send of a settings walk keeps every build of its machine: the layer goes, and a build held for a person or
+// waiting for a gate stays where it is (ADR 0344 §3).
+func TestASettingsWalkSendsTheLayerAloneEveryBuildKept(t *testing.T) {
+	w := aSettledMesh(t)
+	ctx := t.Context()
+	inv := w.open.inventory
+	gateEvery = 0
+	if _, err := openSettingsWalk(ctx, w.open, inventory.PlanSettings{Module: "app", Ask: "s3"}); err != nil {
+		t.Fatal(err)
+	}
+	for i := 0; i < 4; i++ {
+		advancePlans(ctx, w.open)
+	}
+	if !reflect.DeepEqual(w.kept, []bool{true, true}) || w.walk(t).State != inventory.PlanDone {
+		t.Fatalf("the sends kept every build: %v; the walk: %s", w.kept, w.walk(t).Note)
+	}
+	// What such a send keeps, on the store: a rolled-out build waiting there is kept at the one last sent.
+	now := time.Now().Add(-time.Minute)
+	manifest, _ := json.Marshal(catalogue.Manifest{Module: "app", Version: "1"})
+	if err := inv.RecordBuild(ctx, inventory.Build{ID: "build-app-c2", Module: "app", Commit: "c2",
+		Repository: "novox/mesh-catalog", Path: "modules/app", Manifest: manifest, Asked: now, At: now,
+		Made: []inventory.Artifact{{Name: "x", Kind: "bundle", Reference: "sha256:app-2"}}}); err != nil {
+		t.Fatal(err)
+	}
+	if err := inv.RegisterModule(ctx, catalogue.Manifest{Module: "app", Version: "1"}, inventory.Source{
+		Repository: "novox/mesh-catalog", Seat: "git", Path: "modules/app", BuiltFrom: "c2", Head: "c2", Asked: now}); err != nil {
+		t.Fatal(err)
+	}
+	kept, err := recordedKept(keepingBuildsForSettings(ctx, "anchor"), w.open, "anchor")
+	if err != nil || kept["app"] != "c1" {
+		t.Fatalf("a settings send to anchor keeps %v (%v), want app at c1", kept, err)
+	}
+	if kept, _ := recordedKept(ctx, w.open, "anchor"); kept["app"] != "" {
+		t.Fatalf("an ordinary send keeps a rolled-out build: %v", kept)
+	}
+	// And so the ungated build waiting on anchor is no move of the settings send's: nothing for a gate to see.
+	f, err := readMoveFacts(ctx, inv)
+	if err != nil {
+		t.Fatal(err)
+	}
+	waiting, _ := machineMoves(ctx, w.open, f, "anchor", false)
+	if len(waiting) != 1 || waiting[0].Module != "app" {
+		t.Fatalf("anchor waits for %+v, want app's c2", waiting)
+	}
+	if moved, err := withoutKept(keepingBuildsForSettings(ctx, "anchor"), w.open, "anchor", waiting); err != nil || len(moved) != 0 {
+		t.Fatalf("a settings send to anchor would move %+v (%v)", moved, err)
+	}
+}
+
+// A machine whose send would move a running module's data stops the walk there, failed and said with the push that
+// sends it on a person's word (ADR 0217 §3); one not heard from is passed over and named; and a walk that reached
+// no machine is not said delivered.
+func TestASettingsWalkStopsBeforeADataMoveAndPassesOverAMachineAway(t *testing.T) {
+	w := aSettledMesh(t)
+	ctx := t.Context()
+	gateEvery = 0
+	w.moves["laptop"] = []dataMove{{Container: "app-server", Inside: "/data", From: "/srv/a", To: "/srv/b"}}
+	if _, err := openSettingsWalk(ctx, w.open, inventory.PlanSettings{Module: "app", Ask: "s4"}); err != nil {
+		t.Fatal(err)
+	}
+	for i := 0; i < 4; i++ {
+		advancePlans(ctx, w.open)
+	}
+	p := w.walk(t)
+	if p.State != inventory.PlanFailed || !reflect.DeepEqual(w.sent, [][]string{{"anchor"}}) ||
+		!strings.Contains(p.Note, "not sent to laptop: a running module's data would move there") ||
+		!strings.Contains(p.Note, "push laptop --move app") {
+		t.Fatalf("sent %v; the walk is %s: %s", w.sent, p.State, p.Note)
+	}
+
+	v := aSettledMesh(t)
+	v.heard = map[string]bool{"laptop": true}
+	gateEvery = 0
+	if _, err := openSettingsWalk(ctx, v.open, inventory.PlanSettings{Module: "app", Ask: "s5"}); err != nil {
+		t.Fatal(err)
+	}
+	for i := 0; i < 4; i++ {
+		advancePlans(ctx, v.open)
+	}
+	p = v.walk(t)
+	if p.State != inventory.PlanDone || !reflect.DeepEqual(p.Release.Skipped, []string{"anchor"}) ||
+		!strings.Contains(p.Note, "delivered on laptop; not heard from, left as they were, their next send carries it: anchor") {
+		t.Fatalf("the walk with anchor away is %s: %s", p.State, p.Note)
+	}
+
+	u := aSettledMesh(t)
+	u.heard = map[string]bool{}
+	if _, err := openSettingsWalk(ctx, u.open, inventory.PlanSettings{Module: "app", Ask: "s6"}); err != nil {
+		t.Fatal(err)
+	}
+	advancePlans(ctx, u.open)
+	if p := u.walk(t); p.State != inventory.PlanFailed || p.Outcome() != inventory.WalkFailed ||
+		!strings.Contains(p.Note, "was sent to no machine") || len(u.sent) != 0 {
+		t.Fatalf("a walk that reached nobody is %s: %s", p.State, p.Note)
+	}
+}
+
+// The gate keeps the module's build its send kept, so a crossing send — a merge's walk sending the machine a new
+// build of the module while the settings gate judges there — supersedes it, and its report is never read as the
+// settings send's (issue 641 review, finding 1).
+func TestACrossingSendSupersedesASettingsGate(t *testing.T) {
+	judgeLeavesAsTheCore(t)
+	w := aSettledMesh(t)
+	ctx := t.Context()
+	inv := w.open.inventory
+	if _, err := openSettingsWalk(ctx, w.open, inventory.PlanSettings{Module: "app", Ask: "s7"}); err != nil {
+		t.Fatal(err)
+	}
+	advancePlans(ctx, w.open)
+	p := w.walk(t)
+	if g := p.Release.Gate; g == nil || g.To != "c1" || g.From != "c1" {
+		t.Fatalf("the settings gate judges no build: %+v", p.Release.Gate)
+	}
+	// Another walk sends anchor app's c2 while the settings gate judges there.
+	now := time.Now().Add(-time.Minute)
+	manifest, _ := json.Marshal(catalogue.Manifest{Module: "app", Version: "1"})
+	if err := inv.RecordBuild(ctx, inventory.Build{ID: "build-app-c2", Module: "app", Commit: "c2",
+		Repository: "novox/mesh-catalog", Path: "modules/app", Manifest: manifest, Asked: now, At: now,
+		Made: []inventory.Artifact{{Name: "x", Kind: "bundle", Reference: "sha256:app-2"}}}); err != nil {
+		t.Fatal(err)
+	}
+	if err := inv.RecordSent(ctx, nodeID(t, w.open, "anchor"), "d-merge", map[string]string{"app": "c2"}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := inv.RecordDoing(ctx, nodeID(t, w.open, "anchor"), inventory.Doing{Node: "anchor",
+		Outcome: inventory.OutcomeApplied, Declared: "d-merge", Applied: 1, At: time.Now()}); err != nil {
+		t.Fatal(err)
+	}
+	gateEvery = 0
+	advancePlans(ctx, w.open)
+	p = w.walk(t)
+	if p.State != inventory.PlanSuperseded || p.Release.Gate == nil || p.Release.Gate.Verdict != inventory.GateSuperseded ||
+		!strings.Contains(p.Note, "superseded on anchor") || len(p.Release.Done) != 0 {
+		t.Fatalf("the settings walk after a crossing send is %s: %s %+v", p.State, p.Note, p.Release)
+	}
+	if !reflect.DeepEqual(w.sent, [][]string{{"anchor"}}) {
+		t.Fatalf("sent %v: laptop was sent after a superseded judging", w.sent)
+	}
+}
+
+// A send refusal that cannot clear by itself — what the machine was last sent is not known, or a build it runs is
+// gone — fails the walk with why, rather than keeping it open and holding the walk of waiting builds; and a
+// failure names the machines passed over as away (issue 641 review, findings 2 and 3).
+func TestASettingsWalkFailsOnARefusalThatCannotClear(t *testing.T) {
+	w := aSettledMesh(t)
+	ctx := t.Context()
+	inv := w.open.inventory
+	// What a send to a machine never sent can keep: nothing, and said as the refusal the walk fails on.
+	if _, err := inv.AddNode(ctx, "fresh"); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := recordedKept(keepingBuildsForSettings(ctx, "fresh"), w.open, "fresh"); !errors.Is(err, errSettingsCannotKeep) {
+		t.Fatalf("a settings send to a machine never sent: %v", err)
+	}
+	w.heard = map[string]bool{"laptop": true}
+	settingsDataMoves = func(_ context.Context, _ *stores, node string) ([]dataMove, error) {
+		return nil, fmt.Errorf("%w: what %s was last sent is not known", errSettingsCannotKeep, node)
+	}
+	if _, err := openSettingsWalk(ctx, w.open, inventory.PlanSettings{Module: "app", Ask: "s8"}); err != nil {
+		t.Fatal(err)
+	}
+	advancePlans(ctx, w.open)
+	p := w.walk(t)
+	if p.State != inventory.PlanFailed || len(w.sent) != 0 ||
+		!strings.Contains(p.Note, "not sent to laptop: the settings cannot be sent with every build kept: what laptop was last sent is not known") ||
+		!strings.Contains(p.Note, "not heard from, left as they were: anchor") {
+		t.Fatalf("the walk is %s: %s", p.State, p.Note)
+	}
+	// It is not open, so a build waiting for a gate is walked.
+	now := time.Now().Add(-time.Minute)
+	manifest, _ := json.Marshal(catalogue.Manifest{Module: "app", Version: "1"})
+	if err := inv.RecordBuild(ctx, inventory.Build{ID: "build-app-c2", Module: "app", Commit: "c2",
+		Repository: "novox/mesh-catalog", Path: "modules/app", Manifest: manifest, Asked: now, At: now,
+		Made: []inventory.Artifact{{Name: "x", Kind: "bundle", Reference: "sha256:app-2"}}}); err != nil {
+		t.Fatal(err)
+	}
+	if err := inv.RegisterModule(ctx, catalogue.Manifest{Module: "app", Version: "1"}, inventory.Source{
+		Repository: "novox/mesh-catalog", Seat: "git", Path: "modules/app", BuiltFrom: "c2", Head: "c2", Asked: now}); err != nil {
+		t.Fatal(err)
+	}
+	if r, err := releaseBacklog(ctx, w.open, ""); err != nil || r == nil {
+		t.Fatalf("the waiting build is held by the failed settings walk: %+v %v", r, err)
+	}
+}

cmd/mesh-controller/template_test.go

@@ -0,0 +1,204 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+	snapshot "github.com/novox/mesh-controller/internal/facts"
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// A file's text kept as a template file in its module's repository (novox/hq ADR 0349 §2, design 57 package T1,
+// issue 654): `module check` and the merge gate read it from the tree beside the manifest, so a change to a
+// template alone is judged as a change to its module.
+
+const templatedNotifier = `{"module":"notifier","version":"1",
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]},
+  "resources":[{"id":"conf","type":"file","path":"/etc/notifier/notifier.conf","mode":"0644","template":"files/notifier.conf"}]}`
+
+// inlineNotifier is the same module as the mesh holds it: built, its text inline.
+const inlineNotifier = `{"module":"notifier","version":"1",
+  "resources":[{"id":"conf","type":"file","path":"/etc/notifier/notifier.conf","mode":"0644","content":"volume = 3\n"}]}`
+
+// aTemplatedModule writes a module's directory: its manifest and its files/.
+func aTemplatedModule(t *testing.T, dir, manifest string, files map[string]string) string {
+	t.Helper()
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(dir, "module.json")
+	if err := os.WriteFile(path, []byte(manifest), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	for name, text := range files {
+		full := filepath.Join(dir, filepath.FromSlash(name))
+		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(full, []byte(text), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return path
+}
+
+func TestModuleCheckReadsTemplatesFromTheTreeBesideTheManifest(t *testing.T) {
+	good := aTemplatedModule(t, t.TempDir(), templatedNotifier, map[string]string{"files/notifier.conf": "volume = 3\n"})
+	var out bytes.Buffer
+	if err := moduleCheck([]string{good}, &out); err != nil || !strings.Contains(out.String(), "notifier: ok") {
+		t.Fatalf("a module with its text in files/ was refused: %v\n%s", err, out.String())
+	}
+
+	// A change to the template alone, to text the controller refuses inline, is refused the same.
+	bad := aTemplatedModule(t, t.TempDir(), templatedNotifier,
+		map[string]string{"files/notifier.conf": "volume = 3\nstore = ${dir:nowhere}\n"})
+	out.Reset()
+	if err := moduleCheck([]string{bad}, &out); err == nil || !strings.Contains(out.String(), "nowhere") {
+		t.Fatalf("a template whose text is refused inline passed:\n%s", out.String())
+	}
+
+	// A symlink under files/ that no template names: the build's packing refuses it, so the check does too.
+	linked := t.TempDir()
+	aTemplatedModule(t, linked, templatedNotifier, map[string]string{"files/notifier.conf": "volume = 3\n"})
+	if err := os.Symlink("/etc/hostname", filepath.Join(linked, "files", "elsewhere")); err != nil {
+		t.Fatal(err)
+	}
+	out.Reset()
+	if err := moduleCheck([]string{filepath.Join(linked, "module.json")}, &out); err == nil ||
+		!strings.Contains(out.String(), "files/elsewhere is a symlink") {
+		t.Fatalf("a symlink under files/ passed the check:\n%s", out.String())
+	}
+
+	// And a template the tree lacks, by name.
+	missing := aTemplatedModule(t, t.TempDir(), templatedNotifier, nil)
+	out.Reset()
+	if err := moduleCheck([]string{missing}, &out); err == nil || !strings.Contains(out.String(), "files/notifier.conf") {
+		t.Fatalf("a missing template was not refused by name:\n%s", out.String())
+	}
+}
+
+// templatedMesh is catalogueMesh with the notifier on the laptop, registered as built: its text inline.
+func templatedMesh(t *testing.T) (snapshot.Facts, map[string]string) {
+	t.Helper()
+	open := aMesh(t)
+	ctx := t.Context()
+	manifests := map[string]string{
+		"lemurs": `{"module":"lemurs","version":"1","capabilities":["systemd"],
+			"resources":[{"id":"service","type":"service","unit":"lemurs.service","state":"running","boot":"enabled"}]}`,
+		"notifier": inlineNotifier,
+	}
+	for name, raw := range manifests {
+		m, err := catalogue.ParseManifest([]byte(raw))
+		if err != nil {
+			t.Fatalf("%s: %v", name, err)
+		}
+		if err := open.inventory.RegisterModule(ctx, m, inventory.Source{Repository: "novox/mesh-catalog",
+			Path: "modules/" + name, BuiltFrom: "c0ffee"}); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := assign(ctx, open, "laptop", name); err != nil {
+			t.Fatalf("assign %s: %v", name, err)
+		}
+	}
+	f, err := gatherFacts(ctx, open, "2.11.17")
+	if err != nil {
+		t.Fatal(err)
+	}
+	return f, manifests
+}
+
+// aTemplatedTree is the catalogue's checkout with the notifier's text in files/.
+func aTemplatedTree(t *testing.T, manifests map[string]string, text string, has bool) string {
+	t.Helper()
+	tree := aTree(t, withEdit(manifests, "notifier", ""))
+	files := map[string]string{}
+	if has {
+		files["files/notifier.conf"] = text
+	}
+	aTemplatedModule(t, filepath.Join(tree, "modules", "notifier"), templatedNotifier, files)
+	return tree
+}
+
+const notifierTemplate = "modules/notifier/files/notifier.conf"
+
+func TestTheMergeGateJudgesAChangeToATemplateAlone(t *testing.T) {
+	f, manifests := templatedMesh(t)
+
+	// The module moved to its template, the same text: nothing changes on any machine.
+	v := gateJudged(t, f, aTemplatedTree(t, manifests, "volume = 3\n", true), "modules/notifier/module.json",
+		notifierTemplate)
+	if v.Verdict == "fail" || v.Modules["notifier"] != "" {
+		t.Fatalf("the module moved to its template with the same text reads as a change (%v):\n%s", v.Modules, v.Report())
+	}
+
+	// The template alone changed: its module changed, and composes.
+	v = gateJudged(t, f, aTemplatedTree(t, manifests, "volume = 4\n", true), notifierTemplate)
+	if v.Verdict == "fail" || v.Modules["notifier"] != "changed" {
+		t.Fatalf("a change to the template alone is not a change to its module (%v):\n%s", v.Modules, v.Report())
+	}
+	if v.Width == nil || strings.Join(v.Width.Modules, ",") != "notifier" {
+		t.Fatalf("a change to the template rebuilds %+v, not its module", v.Width)
+	}
+
+	// The template alone changed to text the controller refuses: the pull request fails, naming the module.
+	v = gateJudged(t, f, aTemplatedTree(t, manifests, "store = ${dir:nowhere}\n", true), notifierTemplate)
+	if v.Verdict != "fail" || !strings.Contains(v.Report(), "notifier") {
+		t.Fatalf("a template the controller refuses passed the gate:\n%s", v.Report())
+	}
+
+	// A symlinked files/ fails: nothing is read from outside the tree.
+	tree := aTree(t, withEdit(manifests, "notifier", ""))
+	elsewhere := t.TempDir()
+	if err := os.WriteFile(filepath.Join(elsewhere, "notifier.conf"), []byte("volume = 3\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	aTemplatedModule(t, filepath.Join(tree, "modules", "notifier"), templatedNotifier, nil)
+	if err := os.Symlink(elsewhere, filepath.Join(tree, "modules", "notifier", "files")); err != nil {
+		t.Fatal(err)
+	}
+	v = gateJudged(t, f, tree, notifierTemplate)
+	if v.Verdict != "fail" || !strings.Contains(v.Report(), "files/ is a symlink") {
+		t.Fatalf("a symlinked files/ passed the gate:\n%s", v.Report())
+	}
+
+	// And the template removed from the tree fails, naming it.
+	v = gateJudged(t, f, aTemplatedTree(t, manifests, "", false), notifierTemplate)
+	if v.Verdict != "fail" || !strings.Contains(v.Report(), "files/notifier.conf") {
+		t.Fatalf("a missing template passed the gate:\n%s", v.Report())
+	}
+}
+
+// What the gate composes for the module in its template form is what the mesh composes for it inline.
+func TestTheMergeGateResolvesATemplatedModuleToItsInlineTwin(t *testing.T) {
+	dir := t.TempDir()
+	path := aTemplatedModule(t, dir, templatedNotifier, map[string]string{"files/notifier.conf": "volume = 3\n"})
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	m, err := catalogue.ParseManifest(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	m, err = catalogue.WithTemplatesFrom(m, dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resolved, err := standInBuild(m)
+	if err != nil {
+		t.Fatal(err)
+	}
+	inline, err := catalogue.ParseManifest([]byte(inlineNotifier))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if builtAlike(resolved) != builtAlike(inline) {
+		got, _ := json.Marshal(resolved)
+		t.Fatalf("the templated module resolves to %s, not its inline twin", got)
+	}
+}

cmd/mesh-controller/testdata/placement-moved/anchor.json

@@ -0,0 +1,46 @@
+[
+  {
+    "id": "found.server",
+    "image": "registry.invalid:5000/library@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "networks": [
+      "predecessor_default"
+    ],
+    "type": "container"
+  },
+  {
+    "id": "library.access-storage/downloads",
+    "mode": "read",
+    "path": "/storage/downloads",
+    "type": "access"
+  },
+  {
+    "id": "library.access-storage/media/series",
+    "mode": "read",
+    "path": "/storage/media/series",
+    "type": "access"
+  },
+  {
+    "id": "library.config",
+    "mode": "0750",
+    "owner": "1001:2000",
+    "path": "/var/lib/library/config",
+    "type": "directory"
+  },
+  {
+    "content": "{\n  \"accesses\": {\n    \"downloads\": \"/storage/downloads\",\n    \"series\": \"/storage/media/series\"\n  },\n  \"log\": \"warn\",\n  \"places\": {\n    \"config\": {\n      \"owner\": \"1001:2000\",\n      \"path\": \"/var/lib/library/config\"\n    }\n  },\n  \"workers\": 4\n}\n",
+    "id": "library.runtime-config",
+    "mode": "0640",
+    "path": "/var/lib/library/config/runtime.json",
+    "type": "file"
+  },
+  {
+    "id": "library.server",
+    "image": "registry.invalid:5000/library@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "type": "container",
+    "volumes": [
+      "/var/lib/library/config:/config",
+      "/storage/media/series:/series",
+      "/storage/downloads:/downloads:ro"
+    ]
+  }
+]

cmd/mesh-controller/testdata/placement-moved/laptop.json

@@ -0,0 +1,37 @@
+[
+  {
+    "id": "library.access-home/media/series",
+    "mode": "read",
+    "path": "/home/media/series",
+    "type": "access"
+  },
+  {
+    "id": "library.access-storage/downloads",
+    "mode": "read",
+    "path": "/storage/downloads",
+    "type": "access"
+  },
+  {
+    "id": "library.config",
+    "mode": "0750",
+    "path": "/var/lib/library/config",
+    "type": "directory"
+  },
+  {
+    "content": "{\n  \"accesses\": {\n    \"downloads\": \"/storage/downloads\",\n    \"series\": \"/home/media/series\"\n  },\n  \"log\": \"warn\"\n}\n",
+    "id": "library.runtime-config",
+    "mode": "0640",
+    "path": "/var/lib/library/config/runtime.json",
+    "type": "file"
+  },
+  {
+    "id": "library.server",
+    "image": "registry.invalid:5000/library@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "type": "container",
+    "volumes": [
+      "/var/lib/library/config:/config",
+      "/home/media/series:/series",
+      "/storage/downloads:/downloads:ro"
+    ]
+  }
+]

cmd/mesh-controller/tier_send_test.go

@@ -130,10 +130,14 @@ func aTierMesh(t *testing.T, modules ...string) *tierMesh {
 	}
 	t.Cleanup(func() { gatherGateFacts = wasGather })
 
-	wasSettle, wasEvery, wasBound := gateSettle, gateEvery, gateBound
+	wasWithin, wasEvery, wasBound := gateWithin, gateEvery, gateBound
+	// The witness window is the node-engine's, from a start no test makes (novox/hq ADR 0351).
+	wasWindow := gateWitnessWindow
+	gateWitnessWindow = 0
+	t.Cleanup(func() { gateWitnessWindow = wasWindow })
 	// One judging per advance until a test says otherwise: a pass waits gateEvery for the next.
-	gateSettle, gateEvery = 0, time.Hour
-	t.Cleanup(func() { gateSettle, gateEvery, gateBound = wasSettle, wasEvery, wasBound })
+	gateWithin, gateEvery = time.Hour, time.Hour
+	t.Cleanup(func() { gateWithin, gateEvery, gateBound = wasWithin, wasEvery, wasBound })
 
 	built := time.Now().UTC()
 	states := map[string]*inventory.PlanModule{}
@@ -222,6 +226,9 @@ func TestACoreBehindWhileTheNodeToolsSettleFailsNoOtherModule(t *testing.T) {
 	tm := aTierMesh(t, "app1", "app2", broker.RuntimeModule)
 	ctx := t.Context()
 	inv := tm.open.inventory
+	// The node tools are held inside their witness window, which the node-engine keeps while they settle: their
+	// one reading does not count yet, so the core behind raised meanwhile is theirs (novox/hq ADR 0351 decision 4).
+	gateWitnessWindow = time.Hour
 
 	advancePlans(ctx, tm.open)
 	if len(tm.sent) != 1 {
@@ -405,7 +412,10 @@ func TestATierPutsABrokenModuleBackAtOnce(t *testing.T) {
 				}
 				return f, err
 			}
-			gateEvery, gateSettle, gateBound = 0, 100*time.Millisecond, 10*time.Second
+			// app1, judged as the core, counts a reading at most every 100 ms: it cannot have its three in the
+			// judgings that find the node tools broken, and is judged to its own pass after them (the hold the
+			// settle time gave before novox/hq ADR 0352 counted readings from the send).
+			gateEvery, gateWithin, gateBound = 100*time.Millisecond, time.Hour, 10*time.Second
 			for i := 0; i < 20 && len(seen) < 2; i++ {
 				advancePlans(ctx, tm.open)
 			}
@@ -440,15 +450,15 @@ func TestATierPutsABrokenModuleBackAtOnce(t *testing.T) {
 	}
 }
 
-// **A send carrying a core module waits for the core's readings** (issue 524 review): the leaf beside the node
-// tools has its one reading at once, but the send is judged as the core: not before the settle time, and three
-// readings.
-func TestASendCarryingTheCoreIsJudgedAsTheCore(t *testing.T) {
+// **A send carrying the tool runner waits for its witness window** (issue 524 review, novox/hq ADR 0351
+// decision 4): the leaf beside the node tools has its one reading at once, but the send is judged by the tool
+// runner's rule: one reading, not before the node-engine's witness window for it has ended.
+func TestASendCarryingTheToolRunnerWaitsForItsWitnessWindow(t *testing.T) {
 	tm := aTierMesh(t, broker.RuntimeModule, "app1")
 	ctx := t.Context()
 	// One reading counted per advance, as every test with a gate left open does: a gate judged with no time
 	// between readings would count a pass at every look and never let an advance rest.
-	gateEvery, gateSettle = time.Hour, time.Hour
+	gateEvery, gateWitnessWindow = time.Hour, time.Hour
 	for i := 0; i < 6; i++ {
 		advancePlans(ctx, tm.open)
 	}
@@ -457,10 +467,10 @@ func TestASendCarryingTheCoreIsJudgedAsTheCore(t *testing.T) {
 	if lead == nil {
 		lead = p.Modules["app1"].Gate
 	}
-	if !reflect.DeepEqual(tm.sent, [][]string{{"anchor"}}) || !p.Open() || lead == nil || lead.Verdict != "" || lead.Wants != gatePasses {
-		t.Fatalf("passed before the core's settle time: sent %v, plan %s (%s), gate %+v", tm.sent, p.State, p.Note, lead)
+	if !reflect.DeepEqual(tm.sent, [][]string{{"anchor"}}) || !p.Open() || lead == nil || lead.Verdict != "" || lead.Wants != 1 {
+		t.Fatalf("passed inside the witness window: sent %v, plan %s (%s), gate %+v", tm.sent, p.State, p.Note, lead)
 	}
-	gateEvery, gateSettle = 0, 0
+	gateEvery, gateWitnessWindow = 0, 0
 	for i := 0; i < 6; i++ {
 		advancePlans(ctx, tm.open)
 	}
@@ -469,8 +479,9 @@ func TestASendCarryingTheCoreIsJudgedAsTheCore(t *testing.T) {
 		t.Fatalf("the plan is %s (%s), sent %v", p.State, p.Note, tm.sent)
 	}
 	for _, m := range []string{broker.RuntimeModule, "app1"} {
-		if g := p.Modules[m].Gate; g != nil && (g.Verdict != inventory.GatePassed || g.Passes < gatePasses) {
-			t.Fatalf("%s's gate: %+v; want passed on %d readings", m, g, gatePasses)
+		if g := p.Modules[m].Gate; g != nil && (g.Verdict != inventory.GatePassed || g.Passes < 1 ||
+			!strings.Contains(g.Why, "the tool runner's rule")) {
+			t.Fatalf("%s's gate: %+v; want passed on one reading by the tool runner's rule", m, g)
 		}
 	}
 }

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.20261010191001-33917f91ac3c
+	git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261013182924-5933eb757d44
 	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
@@ -36,4 +36,4 @@ require (
 // committed. Every build (the build agent's `go build`, the Dockerfile) compiles from vendor/ and
 // fetches nothing; go refuses to build when vendor/ and this file disagree, so a pin moved without
 // `go mod vendor` fails loudly, at once, everywhere.
-replace github.com/novox/mesh-host => git.novox.be/novox/mesh-host v0.0.0-20261011092230-20d5af9b2d5f
+replace github.com/novox/mesh-host => git.novox.be/novox/mesh-host v0.0.0-20261013220009-b9a293f8c8bc

go.sum

@@ -1,7 +1,13 @@
-git.novox.be/novox/mesh-host v0.0.0-20261011092230-20d5af9b2d5f h1:8N5OW2mdTNIck2pe4EciTYX5NsrPsHrTLENGNIWYNTU=
-git.novox.be/novox/mesh-host v0.0.0-20261011092230-20d5af9b2d5f/go.mod h1:tcTK4LMs1d6JpZUwy3hSHMFG/MIuDr/XFs7/nbeaW/c=
+git.novox.be/novox/mesh-host v0.0.0-20261013220009-b9a293f8c8bc h1:h5v2AbdjM/clMY1YxS9p7VuyYtIjkcw85w9Oz1cOYQc=
+git.novox.be/novox/mesh-host v0.0.0-20261013220009-b9a293f8c8bc/go.mod h1:tcTK4LMs1d6JpZUwy3hSHMFG/MIuDr/XFs7/nbeaW/c=
 git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261010191001-33917f91ac3c h1:l5onJwoIeH8yE/PjVlEeoPyXBsHp2NQiWLllz2fwX7s=
 git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261010191001-33917f91ac3c/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261013141520-9588871d6629 h1:7TYFV1Q6Mcz+lsLP/sds87tysET4rKCn3rRIQV8gNmA=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261013141520-9588871d6629/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261013145622-f4745447ba6d h1:HEJyqorKktrkJPeeJdwEo0kdrJjH3fm/YVS9MGftCqY=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261013145622-f4745447ba6d/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261013182924-5933eb757d44 h1:r5xIo5qWOXQdCSMxvqJy8kV4U+P/QWXFK6971Ha6wU8=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261013182924-5933eb757d44/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
 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/artifacts/scratch.go

@@ -0,0 +1,91 @@
+package artifacts
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+)
+
+// Listing and letting go of tagged documents: the check builds the scratch namespace keeps (novox/hq ADR 0350
+// §5). A check build is found by its tag, and the build seat's holder lets each go when its pull request closes
+// or it is seven days old, so the store keeps a week of check builds and no more.
+
+// Tags is every tag repository holds, in the store's order. None for a repository the store does not hold.
+func (s Store) Tags(ctx context.Context, repository string) ([]string, error) {
+	if s.Address == "" {
+		return nil, fmt.Errorf("this mesh has no artifact store on its network to list %s in", repository)
+	}
+	var tags []string
+	next := "http://" + s.Address + "/v2/" + repository + "/tags/list?n=1000"
+	for next != "" {
+		request, err := http.NewRequestWithContext(ctx, http.MethodGet, next, nil)
+		if err != nil {
+			return nil, err
+		}
+		response, err := s.client().Do(request)
+		if err != nil {
+			return nil, fmt.Errorf("cannot reach the artifact store at %s: %w", s.Address, err)
+		}
+		switch response.StatusCode {
+		case http.StatusOK:
+		case http.StatusNotFound:
+			response.Body.Close()
+			return tags, nil
+		default:
+			response.Body.Close()
+			return nil, fmt.Errorf("the artifact store answered %s for the tags of %s", response.Status, repository)
+		}
+		var page struct {
+			Tags []string `json:"tags"`
+		}
+		err = json.NewDecoder(io.LimitReader(response.Body, 8<<20)).Decode(&page)
+		link := response.Header.Get("Link")
+		response.Body.Close()
+		if err != nil {
+			return nil, fmt.Errorf("the tags of %s could not be read: %w", repository, err)
+		}
+		tags = append(tags, page.Tags...)
+		next = nextPage(link, s.Address)
+	}
+	return tags, nil
+}
+
+// nextPage is the registry's `Link: </v2/…>; rel="next"`, made whole; empty when there is no next page.
+func nextPage(link, address string) string {
+	if !strings.Contains(link, `rel="next"`) {
+		return ""
+	}
+	start, end := strings.Index(link, "<"), strings.Index(link, ">")
+	if start < 0 || end <= start+1 {
+		return ""
+	}
+	target := link[start+1 : end]
+	if strings.HasPrefix(target, "/") {
+		return "http://" + address + target
+	}
+	return target
+}
+
+// DeleteTagged lets go of the document tag names in repository: its manifest, by digest, so the next
+// collection takes its layer. Gone when the tag names nothing.
+func (s Store) DeleteTagged(ctx context.Context, repository, tag string) error {
+	if s.Address == "" {
+		return fmt.Errorf("this mesh has no artifact store on its network to let go of %s:%s in", repository, tag)
+	}
+	digest, err := s.manifestDigest(ctx, repository, tag)
+	if err != nil {
+		return err
+	}
+	if digest == "" {
+		return Gone
+	}
+	err = s.remove(ctx, s.url(repository, "manifests", digest), repository+":"+tag)
+	if errors.Is(err, Gone) {
+		return Gone
+	}
+	return err
+}

internal/builder/builder.go

@@ -91,6 +91,16 @@ type Result struct {
 	// (novox/hq issue 280).
 	Source string
 
+	// ReuseKey is the build's reuse key (novox/hq ADR 0350 §1): its source fingerprint's parts with the builder's
+	// version, and ReuseParts those parts; empty, with NoKey saying why, where the source does not pin the build.
+	ReuseKey   string
+	ReuseParts map[string]string
+	NoKey      string
+	// Reused is the check build a walk took instead of building (ADR 0350 §2), and Why, when it built, why it did
+	// not take one (§3). Both empty for a build not asked to reuse.
+	Reused *Reused
+	Why    string
+
 	// Sources are what this build was made from, as files (novox/hq ADR 0267 rule 1): per repository, the
 	// entries a changed file is tested against (SourceHolds). The module's own repository has an empty
 	// Repository. Said only for a build of a commit on the trunk, and only for a repository whose every
@@ -136,14 +146,44 @@ func Build(ctx context.Context, run Runner, publish Publisher,
 	// one record that it is there.
 	var mirrored []string
 	result, err := build(ctx, run, publish, repository, path, ref, workspace, held, npmrc, forge, log,
-		&mirrored, seats...)
+		&mirrored, nil, seats...)
+	result.Mirrored = mirrored
+	return result, err
+}
+
+// Reuse is what a walk's build may take instead of building (novox/hq ADR 0350 §2): the scratch namespace's check
+// builds, and the pull requests the walk answers, whose checks name a differing key.
+type Reuse struct {
+	Scratch Scratch
+	Pulls   []PullRef
+	// Named are the builds the verdicts of the walk's own pull requests name (novox/hq ADR 0350 §2): a scratch build
+	// is taken only when one of them names its key and every digest. The record in the store alone is never enough.
+	Named []NamedBuild
+	// keyFirst is a check's build (§1): its key is taken before anything is built, and a module with none is not
+	// built at all — nothing could ever take it.
+	keyFirst bool
+}
+
+// errNoKey is a check's build of a module whose source does not pin it: not built (ADR 0350 §1).
+var errNoKey = errors.New("it has no reuse key")
+
+// BuildReusing is Build for the walk of a trunk commit (novox/hq ADR 0350 §2): before building, it takes the reuse
+// key of the commit's tree, and where a check build holds the same key it copies that build into the module's
+// namespace by digest and answers with it, building nothing. Otherwise it builds, and Result.Why says why (§3).
+// Only a commit on its trunk takes a check build: anything else builds, as Build does.
+func BuildReusing(ctx context.Context, run Runner, publish Publisher, reuse Reuse,
+	repository, path, ref, workspace string, held map[string]string, npmrc Npmrc,
+	forge GitCredential, log Log, seats ...map[string]string) (Result, error) {
+	var mirrored []string
+	result, err := build(ctx, run, publish, repository, path, ref, workspace, held, npmrc, forge, log,
+		&mirrored, &reuse, seats...)
 	result.Mirrored = mirrored
 	return result, err
 }
 
 func build(ctx context.Context, run Runner, publish Publisher,
 	repository, path, ref, workspace string, held map[string]string, npmrc Npmrc,
-	forge GitCredential, log Log, mirrored *[]string, seats ...map[string]string) (Result, error) {
+	forge GitCredential, log Log, mirrored *[]string, reuse *Reuse, seats ...map[string]string) (Result, error) {
 	// The clone base of each seat a context may name (novox/hq ADR 0155); variadic so the callers
 	// that hand none — tests of everything but contexts — read as they did.
 	var seatBases map[string]string
@@ -228,7 +268,14 @@ func build(ctx context.Context, run Runner, publish Publisher,
 	}
 	// What is judged only where a definition is written (novox/hq ADR 0326 §3, issue 574): a build is
 	// where a changed definition is first read, so it is refused here before anything is made of it.
-	if problems := catalogue.WrittenSettingsProblems(manifest); len(problems) > 0 {
+	// Judged with each template's text in its file, as written in the tree (novox/hq ADR 0349 §2): a template the
+	// module's directory lacks is refused here, before anything is built.
+	judged, err := catalogue.WithTemplatesFrom(manifest, within)
+	if err != nil {
+		say("manifest", "INVALID: %v", err)
+		return Result{}, err
+	}
+	if problems := catalogue.WrittenSettingsProblems(judged); len(problems) > 0 {
 		err := fmt.Errorf("%s", strings.Join(problems, "; "))
 		say("manifest", "INVALID: %v", err)
 		return Result{}, err
@@ -284,6 +331,9 @@ func build(ctx context.Context, run Runner, publish Publisher,
 	var built []catalogue.Built
 	// stoodOn is every base the build was handed, as resolved — the edges the catalogue derives.
 	var stoodOn []string
+	// reused is the check build a walk took, and builtWhy why it built instead (novox/hq ADR 0350).
+	var reused *Reused
+	builtWhy := ""
 	if manifest.Build != nil {
 		// What this module said it stands on, answered with what this mesh actually holds. Done
 		// before anything is built, so a missing base is refused in front of the person who can
@@ -327,7 +377,35 @@ func build(ctx context.Context, run Runner, publish Publisher,
 		// Ordered, so two builds of one commit do the same work in the same sequence and their
 		// logs can be compared.
 		sort.Slice(artifacts, func(i, j int) bool { return artifacts[i].Name < artifacts[j].Name })
+		// **A walk takes the check's build of the same key** (novox/hq ADR 0350 §2): only a commit on its trunk, and
+		// only when asked — a check, a dry run, `build --ref` and `rebuild` never are. Its key is taken by the same
+		// steps a build takes, stopped before anything is built; what it takes is copied by digest.
+		if reuse != nil && reuse.keyFirst {
+			_, key, err := keyFor(ctx, run, publish, manifest, within, workspace, commit, credentials, artifacts, args,
+				held, npmrcPath, npmrc, seatBases, src, say)
+			if err == nil && key.Key == "" {
+				err = fmt.Errorf("%w: %s", errNoKey, key.Why)
+			}
+			if err != nil {
+				say("reuse", "not built for the merge: %v", err)
+				return Result{Commit: commit, NoKey: err.Error()}, err
+			}
+		} else if reuse != nil && reuse.Scratch != nil {
+			taken, keyed, why := takeACheckBuild(ctx, run, publish, *reuse, manifest, within, workspace, commit,
+				credentials, artifacts, args, held, npmrcPath, npmrc, seatBases, src, onTrunk, say)
+			if taken != nil {
+				built = taken.Made
+				src = keyed
+				reused = taken
+			} else {
+				builtWhy = why
+				say("reuse", "built: %s", why)
+			}
+		}
 		for _, a := range artifacts {
+			if reused != nil {
+				break
+			}
 			say("artifact", "%s (%s%s) — starting", a.Name, a.Kind, langSuffix(a))
 			made, err := one(ctx, run, publish, manifest.Module, within, workspace, commit, credentials, a, args, held, npmrcPath, npmrc, seatBases, src, say)
 			if err != nil {
@@ -339,6 +417,11 @@ func build(ctx context.Context, run Runner, publish Publisher,
 		}
 	}
 
+	// Each template's text, read back from the archive the build made or took (novox/hq ADR 0349 §2).
+	if built, err = withTemplateTexts(manifest, within, built); err != nil {
+		say("templates", "FAILED: %v", err)
+		return Result{}, err
+	}
 	resolved, err := manifest.Resolve(built)
 	if err != nil {
 		say("resolve", "FAILED: %v", err)
@@ -363,9 +446,107 @@ func build(ctx context.Context, run Runner, publish Publisher,
 			say("source", "%d path(s) of %s", len(s.Paths), where)
 		}
 	}
+	// The reuse key (novox/hq ADR 0350 §1): what a check keeps its build under, and what a walk takes one by.
+	key := keyOf(src, manifest, Version)
 	return Result{Manifest: resolved, Commit: commit, Built: built,
 		Against: against(within, manifest, stoodOn), Read: readBy(manifest), Source: fingerprint,
-		Trunk: trunk, OnTrunk: onTrunk, Branches: branches, Sources: sources}, nil
+		Trunk: trunk, OnTrunk: onTrunk, Branches: branches, Sources: sources,
+		ReuseKey: key.Key, ReuseParts: key.Parts, NoKey: key.Why, Reused: reused, Why: builtWhy}, nil
+}
+
+// takeACheckBuild is the walk's look for a check build of its key (novox/hq ADR 0350 §2, §3): the key taken by
+// the steps a build takes, each artifact stopped before it is built; the build kept under it copied by digest into
+// the module's namespace. Answers what it took and the source inputs its key was taken from, or why it builds. A
+// copy that fails is said, and the walk builds (§3): it never fails the walk on its own.
+func takeACheckBuild(ctx context.Context, run Runner, publish Publisher, reuse Reuse, manifest catalogue.Manifest,
+	within, workspace, commit, credentials string, artifacts []catalogue.Artifact, args []string,
+	held map[string]string, npmrcPath string, npmrc Npmrc, seats map[string]string, src *sourceInputs, onTrunk bool,
+	say func(step, format string, args ...any)) (*Reused, *sourceInputs, string) {
+	if !onTrunk {
+		return nil, nil, "the commit is not on its trunk, and only a trunk commit's walk takes a check's build"
+	}
+	keyed, key, err := keyFor(ctx, run, publish, manifest, within, workspace, commit, credentials, artifacts, args,
+		held, npmrcPath, npmrc, seats, src, say)
+	if err != nil {
+		return nil, nil, err.Error()
+	}
+	if key.Key == "" {
+		return nil, nil, "it has no reuse key: " + key.Why
+	}
+	found, ok, err := reuse.Scratch.Find(ctx, manifest.Module, key.Key)
+	if err != nil {
+		return nil, nil, "the scratch namespace could not be read: " + err.Error()
+	}
+	if !ok {
+		return nil, nil, notKeptWhy(ctx, reuse, manifest.Module, key)
+	}
+	// **Only a build a verdict names** (ADR 0350 §2): the store takes writes from anything on the network, so a
+	// record is believed only when a check verdict of the walk's own pull requests names its key and its digests.
+	if why := unnamed(reuse.Named, manifest.Module, key.Key, found); why != "" {
+		return nil, nil, why
+	}
+	taken := &Reused{From: found}
+	for _, made := range found.Made {
+		copied, err := reuse.Scratch.Take(ctx, manifest.Module, made)
+		if err != nil {
+			why := fmt.Sprintf("copying %s's %s from %s failed (%v)", manifest.Module, made.Name, found.Said(), err)
+			say("reuse", "%s; built instead", why)
+			return nil, nil, why
+		}
+		taken.Made = append(taken.Made, copied)
+	}
+	// Every artifact the manifest declares, or none: a check build missing one is not this build.
+	if len(taken.Made) != len(artifacts) {
+		return nil, nil, fmt.Sprintf("%s holds %d artifact(s) of %s, which declares %d", found.Said(), len(taken.Made),
+			manifest.Module, len(artifacts))
+	}
+	say("reuse", "%s", taken.Words())
+	return taken, keyed, ""
+}
+
+// keyFor takes a build's reuse key by the steps a build takes, each artifact stopped before anything is built or
+// published (ADR 0350 §2): its own copy of the source inputs, so the build's are untouched.
+func keyFor(ctx context.Context, run Runner, publish Publisher, manifest catalogue.Manifest,
+	within, workspace, commit, credentials string, artifacts []catalogue.Artifact, args []string,
+	held map[string]string, npmrcPath string, npmrc Npmrc, seats map[string]string, src *sourceInputs,
+	say func(step, format string, args ...any)) (*sourceInputs, reuseKey, error) {
+	keyed := src.copy()
+	keyed.onlyKey = true
+	for _, a := range artifacts {
+		if _, err := one(ctx, run, publish, manifest.Module, within, workspace, commit, credentials, a, args, held,
+			npmrcPath, npmrc, seats, keyed, say); err != nil {
+			return nil, reuseKey{}, fmt.Errorf("its reuse key could not be taken: %w", err)
+		}
+	}
+	keyed.onlyKey = false
+	return keyed, keyOf(keyed, manifest, Version), nil
+}
+
+// notKeptWhy is why no check build has the key (§3): no check of the walk's pull requests built the module, the
+// key differs — naming the part — or the build it made is gone.
+func notKeptWhy(ctx context.Context, reuse Reuse, module string, key reuseKey) string {
+	if len(reuse.Pulls) == 0 {
+		return "no check built it with this key"
+	}
+	builds, err := reuse.Scratch.OfPulls(ctx, reuse.Pulls)
+	if err != nil {
+		return "no check build has this key, and which checks built it could not be read: " + err.Error()
+	}
+	for _, b := range builds {
+		if b.Module != module {
+			continue
+		}
+		if b.Key == key.Key {
+			return b.Said() + " built it with this key, and it was removed"
+		}
+		return "the key differs from " + b.Said() + "'s in " + strings.Join(differing(b.Parts, key.Parts), ", ")
+	}
+	var pulls []string
+	for _, p := range reuse.Pulls {
+		pulls = append(pulls, p.String())
+	}
+	return "no check of " + strings.Join(pulls, ", ") + " built it (a module its check did not move, or a check " +
+		"that did not finish)"
 }
 
 // branchesHolding is every branch of a fresh clone's origin the commit is on, without `origin/`.
@@ -754,6 +935,10 @@ func one(ctx context.Context, run Runner, publish Publisher,
 
 	switch a.Kind {
 	case catalogue.ArtifactUpstream:
+		// Its key is the image it copies, read from the manifest (keyOf): nothing to take here.
+		if src.keyOnly() {
+			return catalogue.Built{Name: a.Name, Kind: a.Kind}, nil
+		}
 		// Mirrored, not built: copied under a name of the mesh's own, so what a machine fetches is
 		// pinned by a digest this registry assigned rather than by a tag somebody else can move.
 		//
@@ -882,6 +1067,10 @@ func one(ctx context.Context, run Runner, publish Publisher,
 		} else {
 			src.ownWhole()
 		}
+		// Taken for a reuse key (novox/hq ADR 0350 §2): everything its fingerprint reads is read; nothing is built.
+		if src.keyOnly() {
+			return catalogue.Built{Name: a.Name, Kind: a.Kind}, nil
+		}
 		invocation := append([]string{"build", "-f", recipePath, "-t", local}, args...)
 		if a.Target != "" {
 			invocation = append(invocation, "--target", a.Target)
@@ -949,6 +1138,9 @@ func one(ctx context.Context, run Runner, publish Publisher,
 				src.notPinned(a.Name + " resolves packages of its own at build time")
 			}
 		}
+		if src.keyOnly() {
+			return catalogue.Built{Name: a.Name, Kind: a.Kind}, nil
+		}
 		// The module's own packages first, where the compiler and the bundler resolve them from
 		// (dependencies.go); nothing at all for a module whose package.json names only the SDK.
 		if err := installOwn(ctx, run, tree, chain, base, registry, say); err != nil {
@@ -992,6 +1184,9 @@ func one(ctx context.Context, run Runner, publish Publisher,
 		say("package", "building and publishing %s (%s)", a.Name, a.Language)
 		src.ownWhole()
 		src.notPinned(a.Name + " is a package, built from what the registry holds when it is built")
+		if src.keyOnly() {
+			return catalogue.Built{Name: a.Name, Kind: a.Kind}, nil
+		}
 		reference, err := publishPackage(ctx, run, module, tree, a, npmrc, say)
 		if err != nil {
 			return catalogue.Built{}, fmt.Errorf("%s: publishing %s failed: %w", module, a.Name, err)
@@ -1000,6 +1195,12 @@ func one(ctx context.Context, run Runner, publish Publisher,
 		return catalogue.Built{Name: a.Name, Kind: a.Kind, Reference: reference}, nil
 
 	case catalogue.ArtifactArchive:
+		if src.keyOnly() {
+			if a.URL == "" {
+				src.ownHas(cleanEntry(a.From) + "/**")
+			}
+			return catalogue.Built{Name: a.Name, Kind: a.Kind}, nil
+		}
 		var body []byte
 		var err error
 		if a.URL != "" {

internal/builder/check.go

@@ -98,6 +98,11 @@ type CheckSpec struct {
 	// and composed with it by the gate as one future state. The repository's own check is not run for a
 	// group: each member's pull request runs its own.
 	Group []GroupHead
+	// Builds are the modules the delivery plan moves, in the walk's order, and BuildWith what they are built with
+	// (novox/hq ADR 0350 §1): built from the merge the check judged into the scratch namespace once it has judged,
+	// for the walk to take. None for a group's composed check, whose members' own checks build.
+	Builds    []CheckBuildSpec
+	BuildWith *CheckBuilding
 }
 
 // GroupHead is one other head of a delivery group's composed check.
@@ -155,6 +160,8 @@ type CheckVerdict struct {
 	// Members are a delivery group's other heads as the composed check judged them, each with the trunk
 	// commit it was merged into (ADR 0323 §6).
 	Members []JudgedHead
+	// Built are the builds it made for its merge (novox/hq ADR 0350 §1), each with its key, or why not.
+	Built []CheckBuilt
 }
 
 // Layer is one layer of a check, judged.
@@ -572,9 +579,38 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 	v.Report, v.Took = redact.redact(withWhatFailed(out.String(), v.Repo)), time.Since(began)
 	say("check", "gate %s — %s; repository %s — %s (%s)", strings.ToUpper(v.Gate.Verdict), v.Gate.Summary,
 		strings.ToUpper(v.Repo.Verdict), v.Repo.Summary, v.Took.Round(time.Second))
+
+	// **What the merge would move, built once, here** (novox/hq ADR 0350 §1): after the judging, from the merge it
+	// judged, into the scratch namespace — so the walk of the merge commit takes it rather than building again.
+	if len(spec.Builds) > 0 && spec.BuildWith != nil && len(spec.Group) == 0 {
+		if why := skipsTheBuilds(v); why != "" {
+			say("check", "%s", why)
+		} else {
+			began := time.Now()
+			v.Built = buildForTheMerge(ctx, run, spec, *spec.BuildWith, workspace, tree, judged.Merge, judged, forge,
+				func(step, message string) {
+					if log != nil {
+						log(step, redact.redact(message))
+					}
+				}, say)
+			say("check", "built for the merge: %d of %d module(s) (%s)", builtCount(v.Built), len(v.Built),
+				time.Since(began).Round(time.Second))
+		}
+	}
 	return named(v), nil
 }
 
+// builtCount is how many of a check's builds for its merge were built.
+func builtCount(built []CheckBuilt) int {
+	n := 0
+	for _, b := range built {
+		if b.NotBuilt == "" {
+			n++
+		}
+	}
+	return n
+}
+
 // ownCheck runs the repository's own check, part by part, each in its toolchain's own container: the
 // layer's verdict. Nil when the check was ended from outside (not past its bound), which the caller
 // answers as the context's error.

internal/builder/check_builds.go

@@ -0,0 +1,151 @@
+package builder
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// The builds a merge check makes for its merge (novox/hq ADR 0350 §1): every artifact of every module the delivery
+// plan moves, built from the merged tree the check judged into the scratch namespace, kept under its reuse key, so
+// the walk of the merge commit takes it instead of building again. Built after the check has judged, and only when
+// it did not fail: a change that fails is not merged, and nothing it built would be taken.
+
+// CheckBuildSpec is one module a check builds for its merge, in the walk's order (Tier).
+type CheckBuildSpec struct {
+	Module string
+	// Repository, Path and Ref are where it is built from; Merged says from the merge the check made instead — the
+	// module is built from the repository checked, at the branch merged into.
+	Repository string
+	Path       string
+	Ref        string
+	Merged     bool
+	Tier       int
+	// Skip says why it cannot be built as the walk would build it: not built, and nothing after it.
+	Skip string
+}
+
+// CheckBuilding is what a check builds with: where it publishes and keeps its builds, and what a build is handed.
+type CheckBuilding struct {
+	Publish Publisher
+	Scratch Scratch
+	Held    map[string]string
+	Npmrc   Npmrc
+	Seats   map[string]string
+}
+
+// CheckBuilt is one module a check built for its merge, as its verdict lists it (§1): its key and its artifacts, or
+// why it was not built.
+type CheckBuilt struct {
+	Module string
+	Key    string
+	Made   []catalogue.Built
+	// NotBuilt says why it was not: no key, a build that failed, or a module after one of those.
+	NotBuilt string
+	Took     time.Duration
+}
+
+// skipsTheBuilds is why a check builds nothing for its merge; empty when it builds.
+func skipsTheBuilds(v CheckVerdict) string {
+	for _, l := range []*Layer{v.Gate, v.Repo} {
+		if l != nil && (l.Verdict == "fail" || l.Verdict == "error") {
+			return "the check did not pass, so nothing is built for its merge"
+		}
+	}
+	return ""
+}
+
+// buildForTheMerge builds each module the plan moves, tier by tier, into the scratch namespace, and keeps what it
+// built under its keys. A module standing after one not built is not built either: what it stands on in the walk
+// is not what it would stand on here. tree is the check's clone and merge the merge commit it made there.
+func buildForTheMerge(ctx context.Context, run Runner, spec CheckSpec, with CheckBuilding, workspace, tree, merge string,
+	judged CheckVerdict, forge GitCredential, log Log, say func(step, format string, args ...any)) []CheckBuilt {
+	if len(spec.Builds) == 0 || with.Publish == nil || with.Scratch == nil {
+		return nil
+	}
+	ref := merge
+	if ref == "" {
+		ref = spec.Ref
+	}
+	held := map[string]string{}
+	for k, v := range with.Held {
+		held[k] = v
+	}
+	var out []CheckBuilt
+	var kept []CheckBuild
+	stopAt, stopWhy := -1, ""
+	for _, b := range spec.Builds {
+		began := time.Now()
+		if stopAt >= 0 && b.Tier > stopAt {
+			out = append(out, CheckBuilt{Module: b.Module, NotBuilt: stopWhy})
+			continue
+		}
+		if b.Skip != "" {
+			say("build", "%s not built for the merge: %s", b.Module, b.Skip)
+			out = append(out, CheckBuilt{Module: b.Module, NotBuilt: b.Skip})
+			if stopAt < 0 || b.Tier < stopAt {
+				stopAt, stopWhy = b.Tier, "it stands after "+b.Module+", which was not built for the merge"
+			}
+			continue
+		}
+		repository, at := b.Repository, b.Ref
+		if b.Merged {
+			repository, at = tree, ref
+		}
+		say("build", "for the merge: %s (tier %d)", b.Module, b.Tier)
+		var mirrored []string
+		result, err := build(ctx, run, scratchPublisher{to: with.Publish}, repository, b.Path, at,
+			filepath.Join(workspace, "for-the-merge"), held, with.Npmrc, forge, log, &mirrored, &Reuse{keyFirst: true},
+			with.Seats)
+		built := CheckBuilt{Module: b.Module, Key: result.ReuseKey, Took: time.Since(began)}
+		switch {
+		case errors.Is(err, errNoKey):
+			built.NotBuilt = err.Error()
+		case err != nil:
+			built.NotBuilt = "its build failed: " + err.Error()
+		case result.ReuseKey == "":
+			built.NotBuilt = "it has no reuse key: " + result.NoKey
+		}
+		if built.NotBuilt != "" {
+			say("build", "%s not built for the merge: %s", b.Module, built.NotBuilt)
+			out = append(out, built)
+			if stopAt < 0 || b.Tier < stopAt {
+				stopAt, stopWhy = b.Tier, "it stands after "+b.Module+", which was not built for the merge"
+			}
+			continue
+		}
+		built.Made = result.Built
+		for _, m := range result.Built {
+			held[b.Module+"/"+m.Name] = m.Reference
+		}
+		say("build", "%s built for the merge under %s (%s)", b.Module, twelve(result.ReuseKey[3:]), built.Took.Round(time.Second))
+		out = append(out, built)
+		if len(result.Built) > 0 {
+			kept = append(kept, CheckBuild{Key: result.ReuseKey, Module: b.Module, Parts: result.ReuseParts,
+				Made: result.Built, Pull: PullRef{Owner: spec.Owner, Repo: spec.Repo, Number: spec.Number},
+				Head: judged.Head, Trunk: judged.Trunk, Check: spec.ID, At: time.Now().UTC()})
+		}
+	}
+	_ = os.RemoveAll(filepath.Join(workspace, "for-the-merge"))
+	if len(kept) > 0 {
+		if err := with.Scratch.Keep(ctx, PullRef{Owner: spec.Owner, Repo: spec.Repo, Number: spec.Number}, spec.ID,
+			time.Now().UTC(), kept); err != nil {
+			// Built and not findable: the walk builds, and says no check built it. Said, never the check's verdict.
+			say("build", "the builds for the merge could not be kept, and the walk will build: %v", err)
+			if err := with.Scratch.Discard(ctx, kept); err != nil {
+				say("build", "and what they made could not all be let go of: %v", err)
+			}
+			for i := range out {
+				if out[i].NotBuilt == "" {
+					out[i].NotBuilt = fmt.Sprintf("built, and could not be kept: %v", err)
+				}
+			}
+		}
+	}
+	return out
+}

internal/builder/reuse.go

@@ -0,0 +1,608 @@
+package builder
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/artifacts"
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// One build per change (novox/hq ADR 0350).
+//
+// **The merge check builds what the merge would move** (§1): every artifact of every module the delivery plan
+// moves, from the merged tree it checks, into the artifact store's scratch namespace — never a module's own —
+// kept under a **reuse key**: the source fingerprint as the build takes it (the module's tree, its contexts' trees,
+// its bases and toolchains by digest; issue 280) with the builder's own version and, for an upstream artifact, the
+// image it copies. **The walk of a trunk commit takes that build** (§2): before building, it takes the reuse key
+// of the trunk commit's tree the same way, and where a check build holds the same key it copies it by digest into
+// the module's namespace and answers with that, building nothing. Otherwise it builds and says why (§3): no check
+// built it, the key differs (naming the part), or the check build is gone; a copy that fails is said and built.
+//
+// **What the key names is what a fresh build could differ by.** The tree is every file the recipe and the
+// compiler see; the contexts are the other repositories it reads, by tree; the bases and toolchains are what it
+// stands on, by digest; the builder's version is how it is built. A build whose source does not pin it — one that
+// resolves packages from the mesh's registry when it is built, or copies an upstream image named by tag — has no
+// key, and is always built.
+
+// Version is this builder's own version, as the reuse key takes it: the digest of the running executable, so any
+// change to how it builds is a change of key (§1). Set once by the build seat's holder (SelfVersion); empty — no
+// key, every build its own — when it cannot be said.
+var Version string
+
+// SelfVersion is the version the reuse key takes: the running executable's digest, or the version stamped at build
+// when the executable cannot be read. Empty when neither says anything ("development" says nothing: every unstamped
+// builder would read as one).
+func SelfVersion(stamped string) string {
+	if exe, err := os.Executable(); err == nil {
+		if f, err := os.Open(exe); err == nil {
+			defer f.Close()
+			sum := sha256.New()
+			if _, err := io.Copy(sum, f); err == nil {
+				return "exe:sha256:" + hex.EncodeToString(sum.Sum(nil))
+			}
+		}
+	}
+	if stamped == "" || stamped == "development" {
+		return ""
+	}
+	return stamped
+}
+
+// ScratchPrefix is the namespace a check builds into (novox/hq ADR 0239 §9, ADR 0350 §1): `scratch/<module>/<artifact>`.
+// Registration refuses a reference into it; only the walk's copy, in the module's own namespace, is registered.
+const ScratchPrefix = "scratch/"
+
+// checksRepository holds one document per check that built: which builds it made, of which pull request, when.
+// What the holder lets go of by (§5).
+const checksRepository = ScratchPrefix + "checks"
+
+// reuseTagPrefix names a check build's record under its module's scratch repository: `r1-<hex>`.
+const reuseTagPrefix = "r1-"
+
+// CheckBuildsKept is how long a check build is kept in the scratch namespace (§5).
+const CheckBuildsKept = 7 * 24 * time.Hour
+
+// The parts of a reuse key, as the walk names the one that differs (§3).
+const (
+	partModule   = "the module"
+	partTree     = "the build source"
+	partBases    = "a base image"
+	partBuilder  = "the builder's version"
+	partContext  = "a context"
+	partTool     = "a toolchain"
+	partUpstream = "an upstream image"
+)
+
+// reuseKey is a build's reuse key and the parts it was made from; Key empty, with why, when it has none.
+type reuseKey struct {
+	Key   string
+	Parts map[string]string
+	Why   string
+}
+
+// keyOf is the reuse key of what src says the build was made from, built by version (ADR 0350 §1).
+func keyOf(src *sourceInputs, manifest catalogue.Manifest, version string) reuseKey {
+	if src == nil || src.unpinned != "" || src.tree == "" {
+		why := "its source does not pin the build"
+		if src != nil && src.unpinned != "" {
+			why = src.unpinned
+		} else if src != nil && src.tree == "" {
+			why = "its tree could not be named"
+		}
+		return reuseKey{Why: why}
+	}
+	if version == "" {
+		return reuseKey{Why: "the builder's version cannot be said"}
+	}
+	parts := map[string]string{partModule: src.module, partTree: src.tree, partBuilder: version}
+	var bases []string
+	seen := map[string]bool{}
+	for _, b := range src.bases {
+		if d := referenceDigest(b); !seen[d] {
+			seen[d] = true
+			bases = append(bases, d)
+		}
+	}
+	sort.Strings(bases)
+	parts[partBases] = strings.Join(bases, " ")
+	for a, t := range src.contexts {
+		parts[partContext+" "+a] = t
+	}
+	for a, t := range src.toolchains {
+		parts[partTool+" "+a] = t
+	}
+	// An upstream artifact is copied, not built: what it copies is in module.json, and so in the tree — but a tag
+	// names whatever its registry says today, so only an image pinned by digest is the same image tomorrow.
+	if manifest.Build != nil {
+		for _, a := range manifest.Build.Artifacts {
+			if a.Kind != catalogue.ArtifactUpstream {
+				continue
+			}
+			if !strings.Contains(a.From, "@sha256:") {
+				return reuseKey{Why: fmt.Sprintf("%s copies %s, named by tag, which can move", a.Name, a.From)}
+			}
+			parts[partUpstream+" "+a.Name] = a.From
+		}
+	}
+	lines := make([]string, 0, len(parts))
+	for k, v := range parts {
+		lines = append(lines, k+"="+v)
+	}
+	sort.Strings(lines)
+	sum := sha256.Sum256([]byte(strings.Join(lines, "\n")))
+	return reuseKey{Key: "r1:" + hex.EncodeToString(sum[:]), Parts: parts}
+}
+
+// tagOf is the tag a key's record is kept under.
+func tagOf(key string) string { return reuseTagPrefix + strings.TrimPrefix(key, "r1:") }
+
+// differing names the parts of two keys that differ, in a fixed order: what the walk says when it builds (§3).
+func differing(was, now map[string]string) []string {
+	names := map[string]bool{}
+	for k := range was {
+		names[k] = true
+	}
+	for k := range now {
+		names[k] = true
+	}
+	var out []string
+	for k := range names {
+		if was[k] != now[k] {
+			out = append(out, k)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// PullRef names a pull request.
+type PullRef struct {
+	Owner  string `json:"owner"`
+	Repo   string `json:"repo"`
+	Number int    `json:"number"`
+}
+
+func (p PullRef) String() string { return fmt.Sprintf("%s/%s#%d", p.Owner, p.Repo, p.Number) }
+
+// slug is the pull request as a tag's first part: owner.repo.number, every other character a dash.
+func (p PullRef) slug() string {
+	clean := func(s string) string {
+		return strings.Map(func(r rune) rune {
+			if r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z' || r >= '0' && r <= '9' || r == '_' || r == '-' {
+				return r
+			}
+			return '-'
+		}, s)
+	}
+	return clean(p.Owner) + "." + clean(p.Repo) + "." + strconv.Itoa(p.Number)
+}
+
+// CheckBuild is one module a check built into the scratch namespace, kept under its reuse key (§1).
+type CheckBuild struct {
+	Key    string            `json:"key"`
+	Module string            `json:"module"`
+	Parts  map[string]string `json:"parts"`
+	// Made are its artifacts, in the scratch namespace.
+	Made []catalogue.Built `json:"made"`
+	// Pull is the pull request checked, Head its head and Trunk the trunk commit it was merged into; Check the
+	// check's ask; At when it was built.
+	Pull  PullRef   `json:"pull"`
+	Head  string    `json:"head,omitempty"`
+	Trunk string    `json:"trunk,omitempty"`
+	Check string    `json:"check"`
+	At    time.Time `json:"at"`
+}
+
+// Said is the check build as the walk names it: "the check of owner/repo#n at head H (trunk T)".
+func (c CheckBuild) Said() string {
+	s := "the check of " + c.Pull.String()
+	if c.Head != "" {
+		s += " at head " + twelve(c.Head)
+	}
+	if c.Trunk != "" {
+		s += " (merged into trunk " + twelve(c.Trunk) + ")"
+	}
+	return s
+}
+
+// checkIndex is one check's document under checksRepository: every build it made.
+type checkIndex struct {
+	Pull   PullRef      `json:"pull"`
+	Check  string       `json:"check"`
+	At     time.Time    `json:"at"`
+	Builds []CheckBuild `json:"builds"`
+}
+
+// Scratch is where check builds are kept and taken from: the artifact store's scratch namespace (ADR 0350). The
+// Registry is one; a test's is a map.
+type Scratch interface {
+	// Keep records a check's builds: each under its module and key, and the check's own document.
+	Keep(ctx context.Context, pull PullRef, check string, at time.Time, builds []CheckBuild) error
+	// Find is the check build kept under a module's key; false when none is.
+	Find(ctx context.Context, module, key string) (CheckBuild, bool, error)
+	// OfPulls are the check builds kept for those pull requests, newest first: what the walk names a differing
+	// key from.
+	OfPulls(ctx context.Context, pulls []PullRef) ([]CheckBuild, error)
+	// Take copies one artifact of a check build by digest into the module's own namespace, and answers it there.
+	Take(ctx context.Context, module string, made catalogue.Built) (catalogue.Built, error)
+	// Forget lets go of every check build of a pull request, and Expire of every check older than the bound;
+	// each answers how many checks it let go of.
+	Forget(ctx context.Context, pull PullRef) (int, error)
+	Expire(ctx context.Context, older time.Duration, now time.Time) (int, error)
+	// Discard lets go of what builds a check could not keep made: nothing would ever find them.
+	Discard(ctx context.Context, builds []CheckBuild) error
+}
+
+// scratchPublisher is a Publisher into the scratch namespace: what a check builds is never under a module's
+// own name (ADR 0239 §9). A base the build stands on is copied where every build copies it.
+type scratchPublisher struct{ to Publisher }
+
+func (s scratchPublisher) PublishImage(ctx context.Context, localTag, repository string) (string, error) {
+	return s.to.PublishImage(ctx, localTag, ScratchPrefix+repository)
+}
+
+func (s scratchPublisher) PublishArchive(ctx context.Context, repository string, body []byte, digest string) (string, error) {
+	return s.to.PublishArchive(ctx, ScratchPrefix+repository, body, digest)
+}
+
+func (s scratchPublisher) MirrorImage(ctx context.Context, from, repository string) (string, error) {
+	m, can := s.to.(Mirrorer)
+	if !can {
+		return "", errors.New("the artifact store here cannot copy an upstream image")
+	}
+	return m.MirrorImage(ctx, from, ScratchPrefix+repository)
+}
+
+func (s scratchPublisher) MirrorBase(ctx context.Context, from, repository, former string) (string, error) {
+	if m, can := s.to.(BaseMirrorer); can {
+		return m.MirrorBase(ctx, from, repository, former)
+	}
+	if m, can := s.to.(Mirrorer); can {
+		return m.MirrorImage(ctx, from, repository)
+	}
+	return "", errors.New("the artifact store here cannot copy a base")
+}
+
+// The registry as the scratch namespace.
+
+func (r Registry) store() artifacts.Store {
+	return artifacts.Store{Address: r.Address, HTTP: r.client()}
+}
+
+const recordMedia = "application/vnd.novox.mesh.check-build.v1+json"
+
+// Keep puts each build's record under its module's scratch repository, by key, and the check's document.
+func (r Registry) Keep(ctx context.Context, pull PullRef, check string, at time.Time, builds []CheckBuild) error {
+	store := r.store()
+	for _, b := range builds {
+		body, err := json.Marshal(b)
+		if err != nil {
+			return err
+		}
+		if _, err := store.PutTagged(ctx, ScratchPrefix+b.Module, tagOf(b.Key), recordMedia, body); err != nil {
+			return fmt.Errorf("keeping %s's check build: %w", b.Module, err)
+		}
+	}
+	body, err := json.Marshal(checkIndex{Pull: pull, Check: check, At: at, Builds: builds})
+	if err != nil {
+		return err
+	}
+	if _, err := store.PutTagged(ctx, checksRepository, pull.slug()+"."+check, recordMedia, body); err != nil {
+		return fmt.Errorf("keeping which builds the check of %s made: %w", pull, err)
+	}
+	return nil
+}
+
+// Find reads the record kept under a module's key.
+func (r Registry) Find(ctx context.Context, module, key string) (CheckBuild, bool, error) {
+	body, _, err := r.store().GetTagged(ctx, ScratchPrefix+module, tagOf(key))
+	if errors.Is(err, artifacts.ErrNoTag) {
+		return CheckBuild{}, false, nil
+	}
+	if err != nil {
+		return CheckBuild{}, false, err
+	}
+	var b CheckBuild
+	if err := json.Unmarshal(body, &b); err != nil {
+		return CheckBuild{}, false, fmt.Errorf("%s's check build under %s is not one: %w", module, tagOf(key), err)
+	}
+	if b.Key != key || b.Module != module {
+		return CheckBuild{}, false, nil
+	}
+	return b, true, nil
+}
+
+// checks are the check documents kept, by tag; only those of the pull requests named when any are.
+func (r Registry) checks(ctx context.Context, pulls []PullRef) (map[string]checkIndex, error) {
+	store := r.store()
+	tags, err := store.Tags(ctx, checksRepository)
+	if err != nil {
+		return nil, err
+	}
+	wanted := map[string]PullRef{}
+	for _, p := range pulls {
+		wanted[p.slug()+"."] = p
+	}
+	out := map[string]checkIndex{}
+	for _, tag := range tags {
+		if len(pulls) > 0 {
+			match := false
+			for prefix := range wanted {
+				match = match || strings.HasPrefix(tag, prefix)
+			}
+			if !match {
+				continue
+			}
+		}
+		body, _, err := store.GetTagged(ctx, checksRepository, tag)
+		if errors.Is(err, artifacts.ErrNoTag) {
+			continue
+		}
+		if err != nil {
+			return nil, err
+		}
+		var c checkIndex
+		if err := json.Unmarshal(body, &c); err != nil {
+			continue // not a document this wrote: left to nobody, said by nothing — it names no build
+		}
+		if len(pulls) > 0 {
+			if p := wanted[c.Pull.slug()+"."]; p != c.Pull {
+				continue // a slug two pull requests share: only the one named
+			}
+		}
+		out[tag] = c
+	}
+	return out, nil
+}
+
+// OfPulls are the check builds of those pull requests, newest first.
+func (r Registry) OfPulls(ctx context.Context, pulls []PullRef) ([]CheckBuild, error) {
+	if len(pulls) == 0 {
+		return nil, nil
+	}
+	checks, err := r.checks(ctx, pulls)
+	if err != nil {
+		return nil, err
+	}
+	var out []CheckBuild
+	for _, c := range checks {
+		out = append(out, c.Builds...)
+	}
+	sort.SliceStable(out, func(i, j int) bool { return out[i].At.After(out[j].At) })
+	return out, nil
+}
+
+// Take copies one artifact of a check build into the module's namespace by digest: an image's manifests as they
+// are, so the digest registered is the digest the check built; an archive's blob mounted across, and held.
+func (r Registry) Take(ctx context.Context, module string, made catalogue.Built) (catalogue.Built, error) {
+	repository := module + "/" + made.Name
+	from := ScratchPrefix + repository
+	if made.Digest != "" || strings.Contains(made.Reference, "/blobs/") {
+		digest := made.Digest
+		if digest == "" {
+			_, digest, _ = strings.Cut(made.Reference, "/blobs/")
+		}
+		where := upstream{base: "http://" + r.Address, repository: from, reference: digest}
+		if err := r.copyBlob(ctx, &source{client: r.client(), mountFrom: from}, where, digest, repository); err != nil {
+			return catalogue.Built{}, err
+		}
+		size, err := r.blobSize(ctx, repository, digest)
+		if err != nil {
+			return catalogue.Built{}, err
+		}
+		if err := r.hold(ctx, repository, digest, int(size)); err != nil {
+			return catalogue.Built{}, err
+		}
+		return catalogue.Built{Name: made.Name, Kind: made.Kind, Digest: digest, Launchers: made.Launchers,
+			Reference: "http://" + r.Address + "/v2/" + repository + "/blobs/" + digest}, nil
+	}
+	_, digest, pinned := strings.Cut(made.Reference, "@")
+	if !pinned || !strings.HasPrefix(digest, "sha256:") {
+		return catalogue.Built{}, fmt.Errorf("%s's check build %s is not pinned by digest", module, made.Reference)
+	}
+	reference, err := r.MirrorBase(ctx, r.Address+"/"+from+"@"+digest, repository, from)
+	if err != nil {
+		return catalogue.Built{}, err
+	}
+	if !strings.HasSuffix(reference, "@"+digest) {
+		return catalogue.Built{}, fmt.Errorf("%s's check build was copied as %s, not as %s", module, reference, digest)
+	}
+	return catalogue.Built{Name: made.Name, Kind: made.Kind, Reference: reference, Launchers: made.Launchers}, nil
+}
+
+// blobSize is the size the store says a blob has.
+func (r Registry) blobSize(ctx context.Context, repository, digest string) (int64, error) {
+	request, err := http.NewRequestWithContext(ctx, http.MethodHead, "http://"+r.Address+"/v2/"+repository+"/blobs/"+digest, nil)
+	if err != nil {
+		return 0, err
+	}
+	response, err := r.client().Do(request)
+	if err != nil {
+		return 0, err
+	}
+	response.Body.Close()
+	if response.StatusCode != http.StatusOK || response.ContentLength < 0 {
+		return 0, fmt.Errorf("%s/blobs/%s: %s", repository, digest, response.Status)
+	}
+	return response.ContentLength, nil
+}
+
+// Forget lets go of every check build of a pull request (§5): what each check built in the scratch namespace, the
+// record under its key when it is still that check's, and the check's document.
+func (r Registry) Forget(ctx context.Context, pull PullRef) (int, error) {
+	all, err := r.checks(ctx, nil)
+	if err != nil {
+		return 0, err
+	}
+	mine := map[string]checkIndex{}
+	for tag, c := range all {
+		if c.Pull == pull {
+			mine[tag] = c
+		}
+	}
+	return r.letGo(ctx, mine, all)
+}
+
+// Expire lets go of every check older than the bound (§5).
+func (r Registry) Expire(ctx context.Context, older time.Duration, now time.Time) (int, error) {
+	checks, err := r.checks(ctx, nil)
+	if err != nil {
+		return 0, err
+	}
+	old := map[string]checkIndex{}
+	for tag, c := range checks {
+		if now.Sub(c.At) > older {
+			old[tag] = c
+		}
+	}
+	return r.letGo(ctx, old, checks)
+}
+
+// Discard lets go of builds no check document names.
+func (r Registry) Discard(ctx context.Context, builds []CheckBuild) error {
+	all, err := r.checks(ctx, nil)
+	if err != nil {
+		return err
+	}
+	_, err = r.letGo(ctx, map[string]checkIndex{"": {Builds: builds}}, all)
+	return err
+}
+
+// letGo lets go of each check's builds, then its document; a check whose builds could not all be let go of keeps
+// its document, so the next sweep asks again. **A build another check still names stays**: deletion is by digest,
+// and two checks that built one digest in one repository — a check asked again, a dependent two pull requests move —
+// share it; it goes with the last check that names it. all are every check kept, the ones going among them.
+func (r Registry) letGo(ctx context.Context, checks, all map[string]checkIndex) (int, error) {
+	store := r.store()
+	stays := map[string]bool{}
+	for tag, c := range all {
+		if _, going := checks[tag]; going {
+			continue
+		}
+		for _, b := range c.Builds {
+			for _, m := range b.Made {
+				stays[catalogue.Recorded(m.Reference)] = true
+			}
+		}
+	}
+	gone := 0
+	var failed []string
+	for tag, c := range checks {
+		ok := true
+		for _, b := range c.Builds {
+			for _, m := range b.Made {
+				reference := catalogue.Recorded(m.Reference)
+				if path, kept := catalogue.InArtifactStore(reference); !kept || !strings.HasPrefix(path, ScratchPrefix) {
+					continue // never anything outside the scratch namespace
+				}
+				if stays[reference] {
+					continue // another check still names it
+				}
+				if err := store.LetGo(ctx, reference); err != nil && !errors.Is(err, artifacts.Gone) {
+					ok = false
+					failed = append(failed, fmt.Sprintf("%s: %v", m.Reference, err))
+				}
+			}
+			// The record under the key, only while it is still this check's: a later check of the same key
+			// replaced it, and that one is its own check's to let go of.
+			if kept, found, err := r.Find(ctx, b.Module, b.Key); err == nil && found && kept.Check == c.Check {
+				if err := store.DeleteTagged(ctx, ScratchPrefix+b.Module, tagOf(b.Key)); err != nil && !errors.Is(err, artifacts.Gone) {
+					ok = false
+					failed = append(failed, fmt.Sprintf("%s's record: %v", b.Module, err))
+				}
+			}
+		}
+		if !ok {
+			continue
+		}
+		if tag == "" {
+			gone++
+			continue
+		}
+		if err := store.DeleteTagged(ctx, checksRepository, tag); err != nil && !errors.Is(err, artifacts.Gone) {
+			failed = append(failed, fmt.Sprintf("%s: %v", tag, err))
+			continue
+		}
+		gone++
+	}
+	if len(failed) > 0 {
+		sort.Strings(failed)
+		return gone, fmt.Errorf("not let go of: %s", strings.Join(failed, "; "))
+	}
+	return gone, nil
+}
+
+// Reused is what the walk took from a check instead of building (§2, §4).
+type Reused struct {
+	From CheckBuild
+	// Made are the copies in the module's namespace: what is registered.
+	Made []catalogue.Built
+}
+
+// Words is the walk's word for a module it took: "reused from <check build>", with each digest (§4).
+func (r Reused) Words() string {
+	var digests []string
+	for _, m := range r.Made {
+		d := m.Digest
+		if d == "" {
+			_, d, _ = strings.Cut(m.Reference, "@")
+		}
+		digests = append(digests, m.Name+" "+d)
+	}
+	return "reused from " + r.From.Said() + ": " + strings.Join(digests, ", ")
+}
+
+// NamedBuild is a build a check's verdict names (ADR 0350 §2): its module, key and each artifact's digest.
+type NamedBuild struct {
+	Pull    PullRef
+	Check   string
+	Module  string
+	Key     string
+	Digests map[string]string
+}
+
+// DigestOf is the digest a reference names: an image's after `@`, an archive's after `/blobs/`.
+func DigestOf(reference string) string {
+	if _, d, ok := strings.Cut(reference, "/blobs/"); ok {
+		return d
+	}
+	if _, d, ok := strings.Cut(reference, "@"); ok {
+		return d
+	}
+	return ""
+}
+
+// unnamed is why a record found under a key is not taken: no verdict of the walk's pull requests names that module,
+// key and every one of its digests. Empty when one does.
+func unnamed(named []NamedBuild, module, key string, found CheckBuild) string {
+	for _, n := range named {
+		if n.Module != module || n.Key != key || n.Check != found.Check || len(n.Digests) != len(found.Made) {
+			continue
+		}
+		same := true
+		for _, m := range found.Made {
+			d := m.Digest
+			if d == "" {
+				d = DigestOf(m.Reference)
+			}
+			same = same && d != "" && n.Digests[m.Name] == d
+		}
+		if same {
+			return ""
+		}
+	}
+	return "a build is kept under this key, and no check verdict of the walk's pull requests names it with its " +
+		"digests: not taken"
+}

internal/builder/reuse_test.go

@@ -0,0 +1,639 @@
+package builder
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// One build per change (novox/hq ADR 0350): the merge check builds what the merge would move into the scratch
+// namespace under its reuse key, and the walk of the trunk commit takes that build by digest instead of building.
+
+// aScratch is the scratch namespace in memory: check builds by module and key, and what the walk took.
+type aScratch struct {
+	builds   map[string]CheckBuild
+	took     []string
+	failTake bool
+}
+
+func newScratch() *aScratch { return &aScratch{builds: map[string]CheckBuild{}} }
+
+func (s *aScratch) Keep(_ context.Context, _ PullRef, _ string, _ time.Time, builds []CheckBuild) error {
+	for _, b := range builds {
+		s.builds[b.Module+" "+b.Key] = b
+	}
+	return nil
+}
+
+func (s *aScratch) Find(_ context.Context, module, key string) (CheckBuild, bool, error) {
+	b, ok := s.builds[module+" "+key]
+	return b, ok, nil
+}
+
+func (s *aScratch) OfPulls(_ context.Context, pulls []PullRef) ([]CheckBuild, error) {
+	var out []CheckBuild
+	for _, b := range s.builds {
+		if slices.Contains(pulls, b.Pull) {
+			out = append(out, b)
+		}
+	}
+	return out, nil
+}
+
+func (s *aScratch) Take(_ context.Context, module string, made catalogue.Built) (catalogue.Built, error) {
+	if s.failTake {
+		return catalogue.Built{}, errors.New("the store refused the mount")
+	}
+	s.took = append(s.took, made.Reference)
+	made.Reference = strings.Replace(made.Reference, ScratchPrefix, "", 1)
+	return made, nil
+}
+
+func (s *aScratch) Forget(context.Context, PullRef) (int, error)                  { return 0, nil }
+func (s *aScratch) Expire(context.Context, time.Duration, time.Time) (int, error) { return 0, nil }
+func (s *aScratch) Discard(context.Context, []CheckBuild) error                   { return nil }
+
+const reusedModule = `{"module":"meshboard","version":"1",
+  "build":{"artifacts":[
+    {"name":"server","kind":"image","from":"Dockerfile"},
+    {"name":"look","kind":"archive","from":"files"}]},
+  "resources":[
+    {"id":"svc","type":"container","name":"meshboard","artifact":"server"},
+    {"id":"theme","type":"archive","path":"/opt/meshboard","artifact":"look"}]}`
+
+// aModuleAt is a repository holding the module under mod/, whose directory git names as tree, on its trunk.
+func aModuleAt(t *testing.T, tree string) (*recorded, Runner, string) {
+	t.Helper()
+	return aModuleWith(t, tree, map[string]string{"mod/" + ManifestName: reusedModule,
+		"mod/Dockerfile": "FROM scratch", "mod/files/theme.conf": "dark"})
+}
+
+// aModuleWith is aModuleAt with the repository's files given.
+func aModuleWith(t *testing.T, tree string, contents map[string]string) (*recorded, Runner, string) {
+	t.Helper()
+	r := &recorded{tree: tree, contents: contents}
+	run := func(ctx context.Context, dir, name string, args ...string) (string, error) {
+		if name == "git" && len(args) > 0 && args[0] == "symbolic-ref" {
+			r.ran = append(r.ran, name+" "+strings.Join(args, " "))
+			return "origin/main\n", nil
+		}
+		return r.run(ctx, dir, name, args...)
+	}
+	return r, run, t.TempDir()
+}
+
+func dockerBuilt(r *recorded) bool {
+	for _, line := range r.ran {
+		if strings.HasPrefix(line, "docker build") {
+			return true
+		}
+	}
+	return false
+}
+
+var aPull = PullRef{Owner: "novox", Repo: "meshboard", Number: 7}
+
+// aCheckBuilt is the check of aPull building the module from a tree, into the scratch namespace.
+func aCheckBuilt(t *testing.T, scratch *aScratch, tree string) CheckBuilt {
+	t.Helper()
+	r, run, workspace := aModuleAt(t, tree)
+	return aCheckBuiltBy(t, scratch, r, run, workspace)
+}
+
+// aCheckBuiltBy is aCheckBuilt of the repository given.
+func aCheckBuiltBy(t *testing.T, scratch *aScratch, r *recorded, run Runner, workspace string) CheckBuilt {
+	t.Helper()
+	spec := CheckSpec{ID: "build-1", Owner: aPull.Owner, Repo: aPull.Repo, Number: aPull.Number,
+		Builds: []CheckBuildSpec{{Module: "meshboard", Repository: "https://forge.invalid/meshboard.git", Path: "mod",
+			Ref: "main"}}}
+	built := buildForTheMerge(t.Context(), run, spec, CheckBuilding{Publish: r, Scratch: scratch}, workspace, "", "",
+		CheckVerdict{Head: "abcdefabcdef", Trunk: "123456123456"}, GitCredential{}, nil, logging(nil))
+	if len(built) != 1 || built[0].NotBuilt != "" || built[0].Key == "" {
+		t.Fatalf("the check did not build the module for its merge: %+v", built)
+	}
+	if !dockerBuilt(r) {
+		t.Fatal("the check built no image")
+	}
+	for repository := range r.images {
+		if !strings.HasPrefix(repository, ScratchPrefix) {
+			t.Fatalf("the check published %s outside the scratch namespace", repository)
+		}
+	}
+	for repository := range r.archives {
+		if !strings.HasPrefix(repository, ScratchPrefix) {
+			t.Fatalf("the check published %s outside the scratch namespace", repository)
+		}
+	}
+	return built[0]
+}
+
+// named is the walk's leave naming what a check's verdict says it built, as the controller reads it.
+func named(c CheckBuilt) []NamedBuild {
+	n := NamedBuild{Pull: aPull, Check: "build-1", Module: c.Module, Key: c.Key, Digests: map[string]string{}}
+	for _, m := range c.Made {
+		d := m.Digest
+		if d == "" {
+			d = DigestOf(m.Reference)
+		}
+		n.Digests[m.Name] = d
+	}
+	return []NamedBuild{n}
+}
+
+func withVersion(t *testing.T, v string) {
+	t.Helper()
+	was := Version
+	Version = v
+	t.Cleanup(func() { Version = was })
+}
+
+// A merge whose reuse key equals its check's builds nothing again: the walk copies the check's build by digest
+// and registers that digest.
+func TestAWalkWhoseKeyIsItsChecksBuildsNothingAndRegistersTheChecksDigest(t *testing.T) {
+	withVersion(t, "builder-1")
+	scratch := newScratch()
+	checked := aCheckBuilt(t, scratch, "tree-one")
+
+	r, run, workspace := aModuleAt(t, "tree-one")
+	got, err := BuildReusing(t.Context(), run, r, Reuse{Scratch: scratch, Pulls: []PullRef{aPull}, Named: named(checked)},
+		"https://forge.invalid/meshboard.git", "mod", "main", workspace, nil, Npmrc{}, GitCredential{}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if dockerBuilt(r) || len(r.images) > 0 || len(r.archives) > 0 {
+		t.Fatalf("the walk built again: ran %v, published %v %v", r.ran, r.images, r.archives)
+	}
+	if got.Reused == nil || got.Why != "" {
+		t.Fatalf("the walk did not say it reused the check's build: reused %+v, why %q", got.Reused, got.Why)
+	}
+	if got.ReuseKey != checked.Key {
+		t.Fatalf("the walk's key %s is not the check's %s", got.ReuseKey, checked.Key)
+	}
+	if len(scratch.took) != 2 {
+		t.Fatalf("the walk copied %v, not the check's two artifacts", scratch.took)
+	}
+	for _, made := range checked.Made {
+		registered := strings.Replace(made.Reference, ScratchPrefix, "", 1)
+		found := false
+		for _, b := range got.Built {
+			found = found || (b.Reference == registered && b.Digest == made.Digest)
+		}
+		if !found {
+			t.Fatalf("the walk registers %+v, not the check's %s copied", got.Built, made.Reference)
+		}
+	}
+	if image, _ := got.Manifest.Resources[0]["image"].(string); image != "registry.invalid/meshboard/server@sha256:"+strings.Repeat("a", 64) {
+		t.Fatalf("the manifest pins %q, not the check's digest in the module's namespace", image)
+	}
+	words := got.Reused.Words()
+	if !strings.HasPrefix(words, "reused from the check of novox/meshboard#7 at head abcdefabcdef (merged into trunk 123456123456)") ||
+		!strings.Contains(words, "sha256:") {
+		t.Fatalf("the walk says %q", words)
+	}
+}
+
+// A record no verdict names is refused and built instead, and the walk says so: the store takes writes from anything
+// on its network, so a record planted under another merge's key is never registered.
+func TestARecordNoVerdictNamesIsRefusedAndBuilt(t *testing.T) {
+	withVersion(t, "builder-1")
+	scratch := newScratch()
+	checked := aCheckBuilt(t, scratch, "tree-one")
+	for name, leave := range map[string][]NamedBuild{
+		"no verdict": nil,
+		"another digest": func() []NamedBuild {
+			n := named(checked)
+			n[0].Digests["server"] = "sha256:" + strings.Repeat("e", 64)
+			return n
+		}(),
+		"another check": func() []NamedBuild { n := named(checked); n[0].Check = "build-9"; return n }(),
+	} {
+		t.Run(name, func(t *testing.T) {
+			scratch.took = nil
+			r, run, workspace := aModuleAt(t, "tree-one")
+			got, err := BuildReusing(t.Context(), run, r, Reuse{Scratch: scratch, Pulls: []PullRef{aPull}, Named: leave},
+				"https://forge.invalid/meshboard.git", "mod", "main", workspace, nil, Npmrc{}, GitCredential{}, nil)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if got.Reused != nil || len(scratch.took) > 0 || !dockerBuilt(r) {
+				t.Fatalf("a record no verdict names was taken: %+v, copied %v", got.Reused, scratch.took)
+			}
+			if !strings.Contains(got.Why, "no check verdict of the walk's pull requests names it") {
+				t.Fatalf("the walk says %q", got.Why)
+			}
+		})
+	}
+}
+
+// A differing key builds, and says which part differs.
+func TestAWalkWhoseKeyDiffersBuildsAndSaysWhy(t *testing.T) {
+	withVersion(t, "builder-1")
+	scratch := newScratch()
+	checked := aCheckBuilt(t, scratch, "tree-one")
+
+	r, run, workspace := aModuleAt(t, "tree-two")
+	got, err := BuildReusing(t.Context(), run, r, Reuse{Scratch: scratch, Pulls: []PullRef{aPull}, Named: named(checked)},
+		"https://forge.invalid/meshboard.git", "mod", "main", workspace, nil, Npmrc{}, GitCredential{}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !dockerBuilt(r) || got.Reused != nil {
+		t.Fatalf("a walk whose source differs did not build: reused %+v", got.Reused)
+	}
+	if !strings.Contains(got.Why, "the key differs") || !strings.Contains(got.Why, partTree) {
+		t.Fatalf("the walk says %q, not which part of the key differs", got.Why)
+	}
+
+	// And a builder of another version builds too, saying so.
+	withVersion(t, "builder-2")
+	r, run, workspace = aModuleAt(t, "tree-one")
+	got, err = BuildReusing(t.Context(), run, r, Reuse{Scratch: scratch, Pulls: []PullRef{aPull}, Named: named(checked)},
+		"https://forge.invalid/meshboard.git", "mod", "main", workspace, nil, Npmrc{}, GitCredential{}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !dockerBuilt(r) || !strings.Contains(got.Why, partBuilder) {
+		t.Fatalf("a newer builder took the older one's build, or did not say why not: %q", got.Why)
+	}
+
+	// No check of the walk's pull requests built it: said.
+	r, run, workspace = aModuleAt(t, "tree-one")
+	got, _ = BuildReusing(t.Context(), run, r, Reuse{Scratch: newScratch(), Pulls: []PullRef{aPull}},
+		"https://forge.invalid/meshboard.git", "mod", "main", workspace, nil, Npmrc{}, GitCredential{}, nil)
+	if !dockerBuilt(r) || !strings.Contains(got.Why, "no check of novox/meshboard#7 built it") {
+		t.Fatalf("the walk says %q", got.Why)
+	}
+}
+
+// A copy that fails is said and falls back to a build; it never fails the walk.
+func TestAFailedCopyOfAChecksBuildFallsBackToBuilding(t *testing.T) {
+	withVersion(t, "builder-1")
+	scratch := newScratch()
+	checked := aCheckBuilt(t, scratch, "tree-one")
+	scratch.failTake = true
+
+	r, run, workspace := aModuleAt(t, "tree-one")
+	got, err := BuildReusing(t.Context(), run, r, Reuse{Scratch: scratch, Pulls: []PullRef{aPull}, Named: named(checked)},
+		"https://forge.invalid/meshboard.git", "mod", "main", workspace, nil, Npmrc{}, GitCredential{}, nil)
+	if err != nil {
+		t.Fatalf("a failed copy failed the walk: %v", err)
+	}
+	if !dockerBuilt(r) || got.Reused != nil || len(r.images) == 0 {
+		t.Fatal("a failed copy did not fall back to a build")
+	}
+	if !strings.Contains(got.Why, "copying meshboard's") || !strings.Contains(got.Why, "refused the mount") {
+		t.Fatalf("the walk says %q", got.Why)
+	}
+	for repository := range r.images {
+		if strings.HasPrefix(repository, ScratchPrefix) {
+			t.Fatalf("the walk's own build went into the scratch namespace: %s", repository)
+		}
+	}
+}
+
+// Only a walk takes a check's build: a plain build — a check's, a dry run's, `build --ref`'s — builds, and a commit
+// off the trunk never takes one.
+func TestOnlyAWalkOfATrunkCommitTakesAChecksBuild(t *testing.T) {
+	withVersion(t, "builder-1")
+	scratch := newScratch()
+	checked := aCheckBuilt(t, scratch, "tree-one")
+
+	r, run, workspace := aModuleAt(t, "tree-one")
+	if _, err := Build(t.Context(), run, r, "https://forge.invalid/meshboard.git", "mod", "main", workspace, nil,
+		Npmrc{}, GitCredential{}, nil); err != nil {
+		t.Fatal(err)
+	}
+	if !dockerBuilt(r) || len(scratch.took) > 0 {
+		t.Fatal("a build not asked to reuse took a check's build")
+	}
+
+	r, _, workspace = aModuleAt(t, "tree-one") // no trunk said: off it
+	got, err := BuildReusing(t.Context(), r.run, r, Reuse{Scratch: scratch, Named: named(checked)}, "https://forge.invalid/meshboard.git",
+		"mod", "main", workspace, nil, Npmrc{}, GitCredential{}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !dockerBuilt(r) || got.Reused != nil || !strings.Contains(got.Why, "not on its trunk") {
+		t.Fatalf("a commit off the trunk took a check's build: %q", got.Why)
+	}
+}
+
+// A check that did not pass builds nothing for its merge, and one asked to build nothing builds nothing.
+func TestACheckThatFailedBuildsNothingForItsMerge(t *testing.T) {
+	if skipsTheBuilds(CheckVerdict{Gate: &Layer{Verdict: "pass"}, Repo: &Layer{Verdict: "fail"}}) == "" {
+		t.Fatal("a check whose repository layer failed builds for its merge")
+	}
+	if skipsTheBuilds(CheckVerdict{Gate: &Layer{Verdict: "pass"}, Repo: &Layer{Verdict: "warning"}}) != "" {
+		t.Fatal("a check that passed with a warning builds nothing for its merge")
+	}
+	r, run, workspace := aModuleAt(t, "tree-one")
+	if built := buildForTheMerge(t.Context(), run, CheckSpec{ID: "build-1"}, CheckBuilding{Publish: r, Scratch: newScratch()},
+		workspace, "", "", CheckVerdict{}, GitCredential{}, nil, logging(nil)); built != nil || len(r.ran) > 0 {
+		t.Fatalf("a check moving no module built %v, ran %v", built, r.ran)
+	}
+}
+
+// A module whose source does not pin its build has no key and is not built by the check; what stands after it
+// is not built either.
+func TestACheckBuildsNoModuleWithoutAKeyNorWhatStandsAfterIt(t *testing.T) {
+	withVersion(t, "builder-1")
+	r, run, workspace := aModuleAt(t, "tree-one")
+	r.contents["mod/"+ManifestName] = `{"module":"meshboard","version":"1","build":{"artifacts":[
+		{"name":"mirror","kind":"upstream","from":"docker.io/library/alpine:3"}]}}`
+	spec := CheckSpec{ID: "build-1", Owner: "novox", Repo: "meshboard", Number: 7, Builds: []CheckBuildSpec{
+		{Module: "meshboard", Repository: "https://forge.invalid/meshboard.git", Path: "mod", Tier: 0},
+		{Module: "after", Repository: "https://forge.invalid/after.git", Tier: 1}}}
+	built := buildForTheMerge(t.Context(), run, spec, CheckBuilding{Publish: r, Scratch: newScratch()}, workspace, "", "",
+		CheckVerdict{}, GitCredential{}, nil, logging(nil))
+	if len(built) != 2 || !strings.Contains(built[0].NotBuilt, "named by tag") ||
+		!strings.Contains(built[1].NotBuilt, "stands after meshboard") {
+		t.Fatalf("built %+v", built)
+	}
+	if len(r.images) > 0 {
+		t.Fatalf("a module without a key was published: %v", r.images)
+	}
+}
+
+// What the key names: every input a fresh build could differ by.
+func TestTheReuseKeyNamesEveryInputOfTheBuild(t *testing.T) {
+	src := newSourceInputs("m")
+	src.tree = "t1"
+	src.bases = []string{"store:5000/b/x@sha256:" + strings.Repeat("b", 64)}
+	src.contexts["server"] = "ctx1"
+	src.toolchains["tools"] = "go sha256:c 1234"
+	manifest := catalogue.Manifest{Module: "m"}
+	base := keyOf(src, manifest, "v1")
+	if base.Key == "" {
+		t.Fatalf("no key: %s", base.Why)
+	}
+	for name, change := range map[string]func(*sourceInputs) string{
+		partTree: func(s *sourceInputs) string { s.tree = "t2"; return "v1" },
+		partBases: func(s *sourceInputs) string {
+			s.bases = []string{"other@sha256:" + strings.Repeat("c", 64)}
+			return "v1"
+		},
+		partContext: func(s *sourceInputs) string { s.contexts["server"] = "ctx2"; return "v1" },
+		partTool:    func(s *sourceInputs) string { s.toolchains["tools"] = "go sha256:d 1234"; return "v1" },
+		partBuilder: func(*sourceInputs) string { return "v2" },
+	} {
+		s := src.copy()
+		version := change(s)
+		if k := keyOf(s, manifest, version); k.Key == base.Key {
+			t.Errorf("a change of %s left the key the same", name)
+		}
+	}
+	// A base copied to another address is the same base: the key names it by digest.
+	moved := src.copy()
+	moved.bases = []string{"elsewhere:5000/scratch/b/x@sha256:" + strings.Repeat("b", 64)}
+	if keyOf(moved, manifest, "v1").Key != base.Key {
+		t.Error("the same base at another address changed the key")
+	}
+	if k := keyOf(src, manifest, ""); k.Key != "" {
+		t.Error("a builder whose version cannot be said keyed its build")
+	}
+	unpinned := src.copy()
+	unpinned.notPinned("it resolves packages from the mesh's registry at build time")
+	if k := keyOf(unpinned, manifest, "v1"); k.Key != "" || !strings.Contains(k.Why, "registry") {
+		t.Errorf("a build its source does not pin was keyed: %+v", k)
+	}
+}
+
+// aTaggingRegistry is the in-memory registry with tags and their listing, as the store's scratch namespace needs.
+type aTaggingRegistry struct {
+	*aRegistryOfRepositories
+	tags map[string]map[string]string // repository → tag → manifest digest
+}
+
+func (m *aTaggingRegistry) serve() http.Handler {
+	under := m.handler()
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if repository, ok := strings.CutSuffix(strings.TrimPrefix(r.URL.Path, "/v2/"), "/tags/list"); ok {
+			m.mu.Lock()
+			var tags []string
+			for tag := range m.tags[repository] {
+				tags = append(tags, tag)
+			}
+			m.mu.Unlock()
+			if tags == nil {
+				w.WriteHeader(http.StatusNotFound)
+				return
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{"name": repository, "tags": tags})
+			return
+		}
+		repository, kind, rest := splitPath(r.URL.Path)
+		if kind == "blobs" && r.Method == http.MethodHead {
+			m.mu.Lock()
+			body, linked := m.blobs[rest], m.links[repository][rest]
+			m.mu.Unlock()
+			if !linked {
+				w.WriteHeader(http.StatusNotFound)
+				return
+			}
+			w.Header().Set("Content-Length", strconv.Itoa(len(body)))
+			w.WriteHeader(http.StatusOK)
+			return
+		}
+		if kind != "manifests" {
+			under.ServeHTTP(w, r)
+			return
+		}
+		if !strings.HasPrefix(rest, "sha256:") {
+			m.mu.Lock()
+			switch r.Method {
+			case http.MethodPut:
+				body, _ := readAll(r)
+				if m.tags[repository] == nil {
+					m.tags[repository] = map[string]string{}
+				}
+				m.tags[repository][rest] = digestOf(body)
+				m.manifests[repository+"@"+digestOf(body)] = body
+				m.mu.Unlock()
+				w.WriteHeader(http.StatusCreated)
+				return
+			default:
+				digest, ok := m.tags[repository][rest]
+				body, held := m.manifests[repository+"@"+digest]
+				m.mu.Unlock()
+				if !ok || !held {
+					w.WriteHeader(http.StatusNotFound)
+					return
+				}
+				w.Header().Set("Docker-Content-Digest", digest)
+				w.Header().Set("Content-Type", mediaTypeOf(body))
+				if r.Method == http.MethodGet {
+					_, _ = w.Write(body)
+					return
+				}
+				w.WriteHeader(http.StatusOK)
+				return
+			}
+		}
+		if r.Method == http.MethodDelete {
+			m.mu.Lock()
+			for _, tags := range m.tags {
+				for tag, digest := range tags {
+					if digest == rest {
+						delete(tags, tag)
+					}
+				}
+			}
+			m.mu.Unlock()
+		}
+		under.ServeHTTP(w, r)
+	})
+}
+
+// A check's builds go after seven days, and when its pull request closes or is merged; the walk's copy in the
+// module's own namespace stays.
+func TestCheckBuildsExpireAfterSevenDaysAndGoWhenTheirPullRequestCloses(t *testing.T) {
+	m := &aTaggingRegistry{aRegistryOfRepositories: newRegistryOfRepositories(), tags: map[string]map[string]string{}}
+	server := httptest.NewServer(m.serve())
+	defer server.Close()
+	address := strings.TrimPrefix(server.URL, "http://")
+	registry := Registry{Address: address}
+	ctx := t.Context()
+	now := time.Date(2026, 10, 13, 20, 0, 0, 0, time.UTC)
+
+	image := func(repository, body string) string {
+		digest := digestOf([]byte(body))
+		m.manifests[repository+"@"+digest] = []byte(body)
+		return address + "/" + repository + "@" + digest
+	}
+	check := func(pull PullRef, id string, at time.Time, key string) string {
+		reference := image("scratch/meshboard/server", `{"mediaType":"`+mediaManifestOCI+`","layers":[],"n":"`+id+`"}`)
+		build := CheckBuild{Key: key, Module: "meshboard", Made: []catalogue.Built{{Name: "server", Kind: "image",
+			Reference: reference}}, Pull: pull, Check: id, At: at}
+		if err := registry.Keep(ctx, pull, id, at, []CheckBuild{build}); err != nil {
+			t.Fatal(err)
+		}
+		return reference
+	}
+	held := func(reference string) bool {
+		_, digest, _ := strings.Cut(reference, "@")
+		_, ok := m.manifests["scratch/meshboard/server@"+digest]
+		return ok
+	}
+	other := PullRef{Owner: "novox", Repo: "meshboard", Number: 8}
+	old := check(aPull, "build-1", now.Add(-8*24*time.Hour), "r1:"+strings.Repeat("1", 64))
+	fresh := check(aPull, "build-2", now.Add(-time.Hour), "r1:"+strings.Repeat("2", 64))
+	others := check(other, "build-3", now.Add(-time.Hour), "r1:"+strings.Repeat("3", 64))
+	walked := image("meshboard/server", `{"mediaType":"`+mediaManifestOCI+`","layers":[],"n":"walk"}`)
+
+	if _, found, err := registry.Find(ctx, "meshboard", "r1:"+strings.Repeat("2", 64)); err != nil || !found {
+		t.Fatalf("a check build kept is not found by its key: %v %v", found, err)
+	}
+	n, err := registry.Expire(ctx, CheckBuildsKept, now)
+	if err != nil || n != 1 {
+		t.Fatalf("expired %d checks (%v), want the one eight days old", n, err)
+	}
+	if held(old) || !held(fresh) || !held(others) {
+		t.Fatalf("after the week's sweep: old %v, fresh %v, another's %v", held(old), held(fresh), held(others))
+	}
+	if _, found, _ := registry.Find(ctx, "meshboard", "r1:"+strings.Repeat("1", 64)); found {
+		t.Fatal("the expired check build's record is still found")
+	}
+
+	n, err = registry.Forget(ctx, aPull)
+	if err != nil || n != 1 {
+		t.Fatalf("forgot %d checks of %s (%v)", n, aPull, err)
+	}
+	if held(fresh) || !held(others) {
+		t.Fatalf("after %s closed: its build held %v, another pull request's %v", aPull, held(fresh), held(others))
+	}
+	if _, ok := m.manifests["meshboard/server@"+strings.SplitN(walked, "@", 2)[1]]; !ok {
+		t.Fatal("letting go of check builds took the walk's copy in the module's namespace")
+	}
+	if left, _ := registry.OfPulls(ctx, []PullRef{aPull}); len(left) != 0 {
+		t.Fatalf("%s still has check builds: %+v", aPull, left)
+	}
+}
+
+// The walk copies a check build by digest: the digest registered is the digest the check built, and the copy is
+// in the module's own namespace.
+func TestAChecksBuildIsCopiedByDigestIntoTheModulesNamespace(t *testing.T) {
+	m := &aTaggingRegistry{aRegistryOfRepositories: newRegistryOfRepositories(), tags: map[string]map[string]string{}}
+	server := httptest.NewServer(m.serve())
+	defer server.Close()
+	address := strings.TrimPrefix(server.URL, "http://")
+	registry := Registry{Address: address}
+
+	layer := []byte("layer")
+	m.blobs[digestOf(layer)] = layer
+	m.link("scratch/meshboard/server", digestOf(layer))
+	manifest := []byte(`{"mediaType":"` + mediaManifestOCI + `","layers":[{"digest":"` + digestOf(layer) + `","size":5}]}`)
+	m.manifests["scratch/meshboard/server@"+digestOf(manifest)] = manifest
+	archive := []byte("archive")
+	m.blobs[digestOf(archive)] = archive
+	m.link("scratch/meshboard/look", digestOf(archive))
+
+	got, err := registry.Take(t.Context(), "meshboard", catalogue.Built{Name: "server", Kind: "image",
+		Reference: address + "/scratch/meshboard/server@" + digestOf(manifest)})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Reference != address+"/meshboard/server@"+digestOf(manifest) {
+		t.Fatalf("copied as %s", got.Reference)
+	}
+	if m.uploads != 0 || m.mounts != 1 {
+		t.Fatalf("the image's layer was moved (%d uploads, %d mounts), not mounted", m.uploads, m.mounts)
+	}
+	got, err = registry.Take(t.Context(), "meshboard", catalogue.Built{Name: "look", Kind: "archive",
+		Digest: digestOf(archive), Reference: "http://" + address + "/v2/scratch/meshboard/look/blobs/" + digestOf(archive)})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Digest != digestOf(archive) || got.Reference != "http://"+address+"/v2/meshboard/look/blobs/"+digestOf(archive) ||
+		!m.links["meshboard/look"][digestOf(archive)] {
+		t.Fatalf("the archive was copied as %+v", got)
+	}
+}
+
+// Two checks that built one digest in one repository share it: letting go of one check's builds keeps it while the
+// other still names it, and the last to go takes it.
+func TestABuildTwoChecksShareGoesWithTheLastOfThem(t *testing.T) {
+	m := &aTaggingRegistry{aRegistryOfRepositories: newRegistryOfRepositories(), tags: map[string]map[string]string{}}
+	server := httptest.NewServer(m.serve())
+	defer server.Close()
+	address := strings.TrimPrefix(server.URL, "http://")
+	registry := Registry{Address: address}
+	ctx := t.Context()
+	now := time.Date(2026, 10, 13, 20, 0, 0, 0, time.UTC)
+
+	body := `{"mediaType":"` + mediaManifestOCI + `","layers":[]}`
+	digest := digestOf([]byte(body))
+	m.manifests["scratch/meshboard/server@"+digest] = []byte(body)
+	reference := address + "/scratch/meshboard/server@" + digest
+	other := PullRef{Owner: "novox", Repo: "meshboard", Number: 8}
+	for i, pull := range []PullRef{aPull, other} {
+		id := "build-" + strconv.Itoa(i+1)
+		b := CheckBuild{Key: "r1:" + strings.Repeat(strconv.Itoa(i+1), 64), Module: "meshboard", Pull: pull, Check: id,
+			At: now, Made: []catalogue.Built{{Name: "server", Kind: "image", Reference: reference}}}
+		if err := registry.Keep(ctx, pull, id, now, []CheckBuild{b}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	held := func() bool { _, ok := m.manifests["scratch/meshboard/server@"+digest]; return ok }
+
+	if n, err := registry.Forget(ctx, aPull); err != nil || n != 1 {
+		t.Fatalf("forgot %d (%v)", n, err)
+	}
+	if !held() {
+		t.Fatal("letting go of one check's builds took a build another check still names")
+	}
+	if n, err := registry.Forget(ctx, other); err != nil || n != 1 {
+		t.Fatalf("forgot %d (%v)", n, err)
+	}
+	if held() {
+		t.Fatal("the build stayed after the last check naming it went")
+	}
+}

internal/builder/source.go

@@ -64,6 +64,43 @@ type sourceInputs struct {
 	// contextsAtHead is false once a context was cloned at something other than its trunk's head: its
 	// closure is not the one the next merge there meets, and the build says no build source.
 	contextsAtHead bool
+	// onlyKey says the inputs are being taken for a reuse key (novox/hq ADR 0350 §2): each artifact goes as far
+	// as what its source fingerprint reads, and nothing is built or published.
+	onlyKey bool
+}
+
+// keyOnly is whether these inputs are only being taken for a reuse key.
+func (s *sourceInputs) keyOnly() bool { return s != nil && s.onlyKey }
+
+// copy is the inputs taken so far, apart: a walk's key is taken from them without touching the build's own.
+func (s *sourceInputs) copy() *sourceInputs {
+	c := newSourceInputs(s.module)
+	c.tree, c.unpinned, c.prefix, c.ownIsAll, c.contextsAtHead = s.tree, s.unpinned, s.prefix, s.ownIsAll, s.contextsAtHead
+	c.bases = append([]string{}, s.bases...)
+	for k, v := range s.contexts {
+		c.contexts[k] = v
+	}
+	for k, v := range s.toolchains {
+		c.toolchains[k] = v
+	}
+	for k, v := range s.own {
+		c.own[k] = v
+	}
+	for k, v := range s.read {
+		if v == nil {
+			c.read[k] = nil
+			continue
+		}
+		set := map[string]bool{}
+		for e := range v {
+			set[e] = true
+		}
+		c.read[k] = set
+	}
+	for k, v := range s.readAs {
+		c.readAs[k] = v
+	}
+	return c
 }
 
 // contextOffHead says a context was not its trunk's head.

internal/builder/template.go

@@ -0,0 +1,94 @@
+package builder
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"path/filepath"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// withTemplateTexts is what was built with each template's text, for a module whose files name templates
+// (novox/hq ADR 0349 §2): its templates archive gains the text of every file in it, read back from the packed
+// bytes, by its path inside the archive. Resolve reads them into the files' content.
+//
+// **Read from the archive, proven by its digest.** The module's files/ is packed again, as the build packs it,
+// and the bytes are read only when they hash to the digest the build made or took: a fresh build's own archive,
+// or a check's build a walk copied by digest without building (novox/hq ADR 0350 §2). Packing is deterministic,
+// so one source packs to one digest; a tree that packs to another is not the archive, and its text is refused.
+func withTemplateTexts(manifest catalogue.Manifest, within string, built []catalogue.Built) ([]catalogue.Built, error) {
+	if !manifest.Templated() {
+		return built, nil
+	}
+	name := catalogue.TemplatesArtifact(manifest)
+	at := -1
+	for i, b := range built {
+		if b.Name == name {
+			at = i
+		}
+	}
+	if name == "" || at < 0 {
+		return nil, fmt.Errorf("%s names templates and built no archive of %s/ to read them from",
+			manifest.Module, catalogue.TemplatesDir)
+	}
+	body, err := pack(filepath.Join(within, catalogue.TemplatesDir))
+	if err != nil {
+		return nil, fmt.Errorf("%s: packing %s/ to read its templates back failed: %w", manifest.Module,
+			catalogue.TemplatesDir, err)
+	}
+	sum := sha256.Sum256(body)
+	digest := "sha256:" + hex.EncodeToString(sum[:])
+	if built[at].Digest != digest {
+		return nil, fmt.Errorf("%s: %s/ packs to the digest %s, and the archive %q built or taken is %s: the "+
+			"templates are read only from the archive the mesh records", manifest.Module, catalogue.TemplatesDir,
+			digest, name, orNone(built[at].Digest))
+	}
+	texts, err := unpackTexts(body)
+	if err != nil {
+		return nil, fmt.Errorf("%s: reading the archive %q back failed: %w", manifest.Module, name, err)
+	}
+	out := append([]catalogue.Built(nil), built...)
+	out[at].Texts = texts
+	return out, nil
+}
+
+// unpackTexts is every file of a packed archive (pack), by its path inside it.
+func unpackTexts(body []byte) (map[string]string, error) {
+	zipped, err := gzip.NewReader(bytes.NewReader(body))
+	if err != nil {
+		return nil, err
+	}
+	defer zipped.Close()
+	reader := tar.NewReader(zipped)
+	texts := map[string]string{}
+	for {
+		header, err := reader.Next()
+		if errors.Is(err, io.EOF) {
+			return texts, nil
+		}
+		if err != nil {
+			return nil, err
+		}
+		if header.Typeflag != tar.TypeReg {
+			continue
+		}
+		text, err := io.ReadAll(reader)
+		if err != nil {
+			return nil, err
+		}
+		texts[header.Name] = string(text)
+	}
+}
+
+func orNone(digest string) string {
+	if digest == "" {
+		return "no digest"
+	}
+	return digest
+}

internal/builder/template_test.go

@@ -0,0 +1,136 @@
+package builder
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// A module's files kept as template files in its repository (novox/hq ADR 0349 §2, design 57 package T1, issue
+// 654): the build packs files/ into the module's templates archive and reads each template's text back from the
+// packed bytes into the file's content, so the manifest the mesh holds is the one it would hold for the text inline.
+
+const templatedModule = `{"module":"meshboard","version":"1",
+  "build":{"artifacts":[
+    {"name":"server","kind":"image","from":"Dockerfile"},
+    {"name":"files","kind":"archive","from":"files"}]},
+  "resources":[
+    {"id":"svc","type":"container","name":"meshboard","artifact":"server"},
+    {"id":"conf","type":"file","path":"/etc/meshboard/meshboard.conf","template":"files/meshboard.conf"},
+    {"id":"deeper","type":"file","path":"/etc/meshboard/deeper.conf","template":"files/a/deeper.conf"}]}`
+
+var templatedFiles = map[string]string{
+	"Dockerfile": "FROM scratch", "files/meshboard.conf": "listen = 8080\n\"quoted\" é\n",
+	"files/a/deeper.conf": "deeper\n", "files/unused.conf": "packed, named by nothing",
+}
+
+func contentOf(t *testing.T, m catalogue.Manifest, id string) string {
+	t.Helper()
+	for _, r := range m.Resources {
+		if r["id"] == id {
+			if _, has := r[catalogue.TemplateField]; has {
+				t.Fatalf("%s still names its template in the built manifest: %v", id, r)
+			}
+			text, ok := r["content"].(string)
+			if !ok {
+				t.Fatalf("%s carries no content: %v", id, r)
+			}
+			return text
+		}
+	}
+	t.Fatalf("no resource %s in %v", id, m.Resources)
+	return ""
+}
+
+func TestABuildReadsEachTemplateBackFromItsArchive(t *testing.T) {
+	r, workspace := aRepository(t, templatedModule, templatedFiles)
+	got, err := Build(context.Background(), r.run, r, "https://forge.invalid/meshboard.git", "", "", workspace, nil,
+		Npmrc{}, GitCredential{}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if text := contentOf(t, got.Manifest, "conf"); text != templatedFiles["files/meshboard.conf"] {
+		t.Fatalf("the template's text is %q, not the file's", text)
+	}
+	if text := contentOf(t, got.Manifest, "deeper"); text != templatedFiles["files/a/deeper.conf"] {
+		t.Fatalf("the template's text is %q, not the file's", text)
+	}
+	if r.archives["meshboard/files"] == "" {
+		t.Fatalf("the templates archive was not published: %v", r.archives)
+	}
+	if problem := catalogue.HeldTemplateProblem(got.Manifest); problem != "" {
+		t.Fatal(problem)
+	}
+}
+
+func TestABuildWhoseTemplateIsMissingFailsNamingIt(t *testing.T) {
+	files := map[string]string{}
+	for k, v := range templatedFiles {
+		files[k] = v
+	}
+	delete(files, "files/a/deeper.conf")
+	r, workspace := aRepository(t, templatedModule, files)
+	_, err := Build(context.Background(), r.run, r, "https://forge.invalid/meshboard.git", "", "", workspace, nil,
+		Npmrc{}, GitCredential{}, nil)
+	if err == nil || !strings.Contains(err.Error(), "files/a/deeper.conf") {
+		t.Fatalf("a build whose template is missing did not fail naming it: %v", err)
+	}
+}
+
+// A walk that takes its check's build copies the archive by digest and builds nothing: the templates are read back
+// from the tree packed again, which is the archive only when it packs to the digest taken.
+func TestAWalkTakingAChecksBuildReadsTheTemplatesBackToo(t *testing.T) {
+	withVersion(t, "builder-1")
+	contents := map[string]string{"mod/" + ManifestName: templatedModule}
+	for k, v := range templatedFiles {
+		contents["mod/"+k] = v
+	}
+	scratch := newScratch()
+	r, run, workspace := aModuleWith(t, "tree-one", contents)
+	checked := aCheckBuiltBy(t, scratch, r, run, workspace)
+
+	r, run, workspace = aModuleWith(t, "tree-one", contents)
+	got, err := BuildReusing(t.Context(), run, r, Reuse{Scratch: scratch, Pulls: []PullRef{aPull}, Named: named(checked)},
+		"https://forge.invalid/meshboard.git", "mod", "main", workspace, nil, Npmrc{}, GitCredential{}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Reused == nil || len(r.archives) > 0 {
+		t.Fatalf("the walk built again: reused %+v, why %q, published %v", got.Reused, got.Why, r.archives)
+	}
+	if text := contentOf(t, got.Manifest, "conf"); text != templatedFiles["files/meshboard.conf"] {
+		t.Fatalf("the template's text is %q, not the file's", text)
+	}
+}
+
+// The tree packed again must be the archive taken; text read from anything else is not the archive's.
+func TestTemplateTextsAreRefusedWhenTheTreeDoesNotPackToTheDigestTaken(t *testing.T) {
+	m, err := catalogue.ParseManifest([]byte(templatedModule))
+	if err != nil {
+		t.Fatal(err)
+	}
+	within := writeTree(t, t.TempDir(), templatedFiles)
+	built := []catalogue.Built{{Name: "files", Kind: catalogue.ArtifactArchive, Digest: "sha256:" + strings.Repeat("0", 64)}}
+	if _, err := withTemplateTexts(m, within, built); err == nil || !strings.Contains(err.Error(), "digest") {
+		t.Fatalf("text was read from a tree that does not pack to the archive taken: %v", err)
+	}
+}
+
+// writeTree writes files under dir and answers dir.
+func writeTree(t *testing.T, dir string, files map[string]string) string {
+	t.Helper()
+	for name, body := range files {
+		full := filepath.Join(dir, filepath.FromSlash(name))
+		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(full, []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return dir
+}

internal/catalogue/bound.go

@@ -127,6 +127,7 @@ func boundNeed(n Needed, bound Chosen, catalogue map[string]Manifest, node Node,
 		identity = pm.IdentityBoundOf(n.Name)
 	}
 	held.From, held.At, held.Module, held.Serves, held.Identity = p.Node, p.At, p.Module, p.Serves, identity
+	held.LeftOut = p.LeftOut
 	return held, true, ""
 }
 

internal/catalogue/build.go

@@ -35,6 +35,10 @@ type Built struct {
 	// Launchers are, for a bundle in an interpreted language, the executable the build wrote beside
 	// each entrypoint, by entrypoint (novox/hq ADR 0193): what the node's runtime starts to serve it.
 	Launchers map[string]string
+	// Texts are, for the archive a module packs its templates into (TemplatesArtifact), each file's text as the
+	// build read it back from the packed archive, by its path inside it (novox/hq ADR 0349 §2). Never carried on
+	// the wire or kept: Resolve reads them into the files' content, which is what the mesh holds.
+	Texts map[string]string `json:"-"`
 }
 
 // Resolve fills a manifest's resources in from what was built.
@@ -71,6 +75,26 @@ func (m Manifest) Resolve(built []Built) (Manifest, error) {
 			m.Module, strings.Join(missing, " and "), oneOrOther(len(missing)))
 	}
 
+	// **Each template's text, as the build read it back from its templates archive** (novox/hq ADR 0349 §2): into
+	// the file's content, so what the mesh holds and composes is what the same text inline would be.
+	if m.Templated() {
+		name := TemplatesArtifact(m)
+		texts := by[name].Texts
+		if name == "" || texts == nil {
+			return Manifest{}, fmt.Errorf("%s names templates, and the build carried no text read back from the "+
+				"archive it packs %s/ into (%q): the builder that built it does not read templates",
+				m.Module, TemplatesDir, name)
+		}
+		filled, err := fillTemplates(m.Module, m.Resources, func(template string) (string, bool) {
+			t, ok := texts[strings.TrimPrefix(template, TemplatesDir+"/")]
+			return t, ok
+		}, fmt.Sprintf("the archive %q", name))
+		if err != nil {
+			return Manifest{}, err
+		}
+		m.Resources = filled
+	}
+
 	out := m
 	out.Build = nil
 	out.Resources = nil

internal/catalogue/busy.go

@@ -0,0 +1,124 @@
+package catalogue
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+)
+
+// A long-running container may say it is busy (novox/hq ADR 0335 §1).
+//
+// **Beside its health, on the container**: a command run inside it, by its shell, as an exec health check
+// is, that exits 0 while the container holds work a replacement would lose and non-zero when it is idle;
+// and how long one ask may take. Being asked is also its notice that it is about to be replaced: from the
+// first ask it takes no new work. The node-engine asks before it replaces the container, leaves it running
+// while it says busy, and replaces it on the first pass it says idle, or at 15 minutes — the engine's bound,
+// never the module's.
+//
+// Sent only to a node-engine that reads it (link.BusyContract): an older, strict engine refuses a field it
+// does not know, whole, and to it the container is replaced at once, as before.
+
+// BusyField is the resource field.
+const BusyField = "busy"
+
+// The bounds of one ask (ADR 0335), the node-engine's own, held here near the author.
+const (
+	BusyTimeoutDefault = 10 * time.Second
+	BusyTimeoutCeiling = time.Minute
+)
+
+// Busy is one container's busy, read.
+type Busy struct {
+	Command string
+	Timeout time.Duration
+}
+
+// ReadBusy reads a resource's `busy` field, its default applied. False when it carries none.
+func ReadBusy(r map[string]any) (Busy, bool, []string) {
+	raw, present := r[BusyField]
+	if !present {
+		return Busy{}, false, nil
+	}
+	id := fmt.Sprint(r["id"])
+	fields, ok := raw.(map[string]any)
+	if !ok {
+		return Busy{}, true, []string{fmt.Sprintf("%s: busy is %T; it is an object with a command", id, raw)}
+	}
+	var problems []string
+	keys := make([]string, 0, len(fields))
+	for k := range fields {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	for _, k := range keys {
+		if k != "command" && k != "timeout" {
+			problems = append(problems, fmt.Sprintf("%s: its busy says %q; busy has a command and a timeout", id, k))
+		}
+	}
+	b := Busy{Timeout: BusyTimeoutDefault}
+	if v, has := fields["command"]; has {
+		s, ok := v.(string)
+		if !ok {
+			problems = append(problems, fmt.Sprintf("%s: its busy's command is %T; it is text", id, v))
+		}
+		b.Command = strings.TrimSpace(s)
+	}
+	if v, has := fields["timeout"]; has {
+		s, _ := v.(string)
+		d, err := time.ParseDuration(strings.TrimSpace(s))
+		switch {
+		case err != nil:
+			problems = append(problems, fmt.Sprintf("%s: its busy's timeout is %v; it is a duration such as \"10s\"", id, v))
+		case d <= 0 || d > BusyTimeoutCeiling:
+			problems = append(problems, fmt.Sprintf("%s: an ask of its busy takes more than nothing and at most %s, not %s",
+				id, BusyTimeoutCeiling, d))
+		default:
+			b.Timeout = d
+		}
+	}
+	return b, true, problems
+}
+
+// busyProblems is everything wrong with a manifest's `busy` fields, in the manifest's words: a command on
+// one line, a timeout within its bounds, and only on a container that stays up.
+func busyProblems(m Manifest) []string {
+	var problems []string
+	for _, r := range m.Resources {
+		b, has, read := ReadBusy(r)
+		if !has {
+			continue
+		}
+		where := m.Module + ": " + fmt.Sprint(r["id"])
+		for _, p := range read {
+			problems = append(problems, m.Module+": "+p)
+		}
+		if fmt.Sprint(r["type"]) != "container" || !LongRunning(r) {
+			problems = append(problems, fmt.Sprintf("%s declares busy and is not a container that stays up: busy is "+
+				"asked of a running container before it is replaced (ADR 0335)", where))
+		}
+		if b.Command == "" {
+			problems = append(problems, where+"'s busy names no command: one run inside the container, exiting 0 "+
+				"while it is busy")
+		}
+		if strings.ContainsAny(b.Command, "\n\r") {
+			problems = append(problems, where+"'s busy command is one line")
+		}
+	}
+	return problems
+}
+
+// busyInto composes a container's `busy` into the node-engine's words, or takes it away: for an engine that
+// reads it, the command and its timeout written out; for one that does not, the field is not sent, and the
+// container is replaced at once, as before.
+func busyInto(resource map[string]any, with Rendering) {
+	if _, has := resource[BusyField]; !has {
+		return
+	}
+	if !with.ReadsBusy {
+		delete(resource, BusyField)
+		return
+	}
+	b, _, _ := ReadBusy(resource)
+	resource[BusyField] = map[string]any{"command": b.Command, "timeout": b.Timeout.String()}
+}

internal/catalogue/busy_test.go

@@ -0,0 +1,94 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-host/validate"
+)
+
+// A long-running container may say it is busy (novox/hq ADR 0335 §1): `module check` holds the field to its
+// shape near its author, and it is sent only to a node-engine that reads it, in words the engine's own
+// validator accepts.
+
+func busyManifest(t *testing.T, on string, busy any) []byte {
+	t.Helper()
+	extra := map[string]any{"id": "agent", "type": "container", "name": "app-agent",
+		"image": "registry.example/app" + healthDigest}
+	var m map[string]any
+	if err := json.Unmarshal(healthManifest(t, "", nil, extra), &m); err != nil {
+		t.Fatal(err)
+	}
+	for _, r := range m["resources"].([]any) {
+		if r := r.(map[string]any); r["id"] == on {
+			r[BusyField] = busy
+		}
+	}
+	out, err := json.Marshal(m)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return out
+}
+
+func TestABusyIsHeldToItsShape(t *testing.T) {
+	if _, err := ParseManifest(busyManifest(t, "agent", map[string]any{"command": "mesh-builder busy"})); err != nil {
+		t.Fatalf("a well-formed busy was refused: %v", err)
+	}
+	if _, err := ParseManifest(busyManifest(t, "agent", map[string]any{"command": "x", "timeout": "30s"})); err != nil {
+		t.Fatalf("a busy with its timeout was refused: %v", err)
+	}
+	for name, c := range map[string]struct {
+		on   string
+		busy any
+		says string
+	}{
+		"text":           {"agent", "mesh-builder busy", "it is an object"},
+		"no command":     {"agent", map[string]any{"timeout": "5s"}, "names no command"},
+		"two lines":      {"agent", map[string]any{"command": "a\nb"}, "one line"},
+		"a long timeout": {"agent", map[string]any{"command": "x", "timeout": "5m"}, "at most 1m0s"},
+		"an unknown key": {"agent", map[string]any{"command": "x", "every": "1m"}, `says "every"`},
+		"on a step":      {"seed", map[string]any{"command": "x"}, "not a container that stays up"},
+		"on a service":   {"daemon", map[string]any{"command": "x"}, "not a container that stays up"},
+	} {
+		_, err := ParseManifest(busyManifest(t, c.on, c.busy))
+		if err == nil || !strings.Contains(err.Error(), c.says) {
+			t.Errorf("%s: want a refusal saying %q, got %v", name, c.says, err)
+		}
+	}
+}
+
+func TestABusyIsSentOnlyToAnEngineThatReadsIt(t *testing.T) {
+	m, err := ParseManifest(busyManifest(t, "agent", map[string]any{"command": "mesh-builder busy"}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	compose := func(with Rendering) []map[string]any {
+		out, err := Resolution{Node: "laptop", Modules: []Manifest{m}}.Declaration(with)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return out
+	}
+	older := compose(Rendering{})
+	if b, sent := older[indexOfID(older, "app.agent")][BusyField]; sent {
+		t.Fatalf("busy was sent to an engine that does not read it: %v", b)
+	}
+	newer := compose(Rendering{ReadsBusy: true})
+	got, _ := newer[indexOfID(newer, "app.agent")][BusyField].(map[string]any)
+	if got["command"] != "mesh-builder busy" || got["timeout"] != "10s" {
+		t.Fatalf("busy composed as %v", got)
+	}
+	// And the engine's own validator takes the container with it.
+	body, err := json.Marshal(map[string]any{"declaration": validate.Version, "resources": newer})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if problems := validate.Declaration(body); len(problems) > 0 {
+		t.Fatalf("the node-engine's validator refuses the composed busy: %v", problems)
+	}
+	if _, has := m.Resources[len(m.Resources)-1][BusyField].(map[string]any)["timeout"]; has {
+		t.Error("composing wrote the timeout into the catalogue's own manifest")
+	}
+}

internal/catalogue/consumer_into_serves.go

@@ -135,6 +135,9 @@ func CheckServes(m Manifest) []string {
 		for _, key := range sortedAnyKeys(m.Serves[provision]) {
 			text, ok := m.Serves[provision][key].(string)
 			if !ok {
+				// A provider's own name is filled only in a value of its own (novox/hq ADR 0346): one
+				// nested in a list or an object would be served as the placeholder, unsaid.
+				problems = append(problems, nestedOwnNames(m, provision, key, m.Serves[provision][key])...)
 				continue
 			}
 			// A probe identity, because what is checked is the shape of the statement and not
@@ -143,6 +146,8 @@ func CheckServes(m Manifest) []string {
 				problems = append(problems, fmt.Sprintf(
 					"%s serves %s, and the value it serves as %q %s", m.Module, provision, key, err))
 			}
+			// And the provider's own names it may serve (novox/hq ADR 0346).
+			problems = append(problems, checkServedOwnNames(m, provision, key, text)...)
 			// A label longer than DNS keeps is not truncated here (asDNSLabel), so the offer's own
 			// bound has to keep the identity inside one (ADR 0225).
 			if strings.Contains(text, "${consumer:as:dns}") {

internal/catalogue/data_test.go

@@ -173,7 +173,7 @@ func TestTheBackupHoldersLinesAreDerivedFromTheData(t *testing.T) {
 			{"id":"meta","path":"${dir:meta}","class":"rebuildable"}]},
 		"resources":[{"id":"meta","type":"directory","mode":"0700"}]}`)
 	facts := map[string]string{"account-home": "/home/op"}
-	with := Rendering{Settings: SettingsBy{"media": {{From: "node", Values: map[string]any{AccessesSetting: map[string]any{"films": "/tank/films"}}}}}}
+	with := Rendering{Settings: SettingsBy{"media": {LayerOf("node", map[string]any{AccessesSetting: map[string]any{"films": "/tank/films"}})}}}
 	backup, _, err := seatContributions([]Manifest{pg, agent, media}, Manifest{}, BackupSeat+":"+BackupKindBackup, with, facts, nil)
 	if err != nil {
 		t.Fatal(err)

internal/catalogue/declaration.go

@@ -252,6 +252,11 @@ type Rendering struct {
 	// statement's contract is link.RootContract or later). To an older, strict engine the field is not
 	// sent, and the account it names is not judged — which the self-check says, as not judged.
 	JudgesRoot bool
+
+	// ReadsBusy says this machine's node-engine reads a container's `busy` (novox/hq ADR 0335: its statement's
+	// contract is link.BusyContract or later). To an older, strict engine the field is not sent, and the
+	// container is replaced at once, as before.
+	ReadsBusy bool
 }
 
 // RootField is a user resource's field saying the account must never become root without a person
@@ -1062,6 +1067,8 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 			// How it is ready, in the node-engine's words: its endpoint as the port this machine
 			// published it on — or not sent at all to an engine older than the field (ADR 0240).
 			healthInto(copied, m, with)
+			// And whether it is busy (novox/hq ADR 0335): sent only to an engine that asks it.
+			busyInto(copied, with)
 			// And a user's `root` (novox/hq ADR 0266): sent only when it asserts something, to an engine
 			// that judges it.
 			rootInto(copied, with)
@@ -2039,7 +2046,13 @@ func (r Resolution) servedOnThisMachine(provision string, with Rendering) (map[s
 		if err != nil {
 			return nil, false, fmt.Errorf("%s serving %s: %w", m.Module, provision, err)
 		}
-		return settled, true, nil
+		// And the provider's own names, as this machine composes them (novox/hq ADR 0346); one it does
+		// not compose leaves its key out, said by the plan on this machine (ServedLeftOut).
+		named, _, err := r.ServedOwnNames(m, provision, settled, WithDefaults(m, with.Settings[m.Module]))
+		if err != nil {
+			return nil, false, fmt.Errorf("%s serving %s: %w", m.Module, provision, err)
+		}
+		return named, true, nil
 	}
 	return nil, false, nil
 }

internal/catalogue/manifest.go

@@ -1853,6 +1853,9 @@ func ParseManifest(raw []byte) (Manifest, error) {
 		}
 	}
 	problems = append(problems, m.Build.problems(m.Module)...)
+	// A file's text in a template file of the module's repository (novox/hq ADR 0349 §2): only a file, never beside
+	// content, only under files/, and packed by the module's build.
+	problems = append(problems, templateProblems(m)...)
 	problems = append(problems, undeliveredBundles(m)...)
 	// **What provides the artifact store cannot be delivered through it** (novox/hq 04-ISSUES/029).
 	//
@@ -2336,6 +2339,8 @@ func ParseManifest(raw []byte) (Manifest, error) {
 	// How each long-running resource is ready (novox/hq ADR 0240 rule 2): said near its author, in the
 	// words the node-engine would refuse it in far away.
 	problems = append(problems, healthProblems(m)...)
+	// And whether a container is busy (novox/hq ADR 0335), likewise.
+	problems = append(problems, busyProblems(m)...)
 	if len(problems) > 0 {
 		sort.Strings(problems)
 		return Manifest{}, fmt.Errorf("this manifest cannot be used:\n  - %s",

internal/catalogue/placement.go

@@ -34,6 +34,69 @@ const PlacesSetting = "places"
 // AccessesSetting is the settings key that says where a module's accesses are on this node, by id.
 const AccessesSetting = "accesses"
 
+// **Placement is not config** (novox/hq ADR 0348 clause 11, issue 651). `places`, `accesses` and
+// `networks` are facts of an assignment the controller decides, held beside the assignment and apart
+// from its settings: a Layer carries them in Placement, never in Values, and only Places, AccessPlaces
+// and KeptNetworks read them. A person still says them as keys of a layer through `settings`; LayerOf
+// splits such a layer, so what they type is routed to the placement and nothing they do changes.
+
+// placementKeys are the keys of a layer that are placement, not config.
+var placementKeys = map[string]bool{PlacesSetting: true, AccessesSetting: true, NetworksSetting: true}
+
+// SplitPlacement divides a layer as a person says it into its config values and its placement. Each is
+// nil when it holds nothing; the values themselves are not copied.
+func SplitPlacement(values map[string]any) (config, placement map[string]any) {
+	for key, value := range values {
+		if placementKeys[key] {
+			if placement == nil {
+				placement = map[string]any{}
+			}
+			placement[key] = value
+			continue
+		}
+		if config == nil {
+			config = map[string]any{}
+		}
+		config[key] = value
+	}
+	return config, placement
+}
+
+// LayerOf is a layer as a person says it — config values and placement in one map — split into the two.
+func LayerOf(from string, values map[string]any) Layer {
+	config, placement := SplitPlacement(values)
+	if config == nil {
+		config = map[string]any{}
+	}
+	return Layer{From: from, Values: config, Placement: placement}
+}
+
+// Whole is the layer as a person says it: its values and its placement in one map, a new map.
+func (l Layer) Whole() map[string]any {
+	out := make(map[string]any, len(l.Values)+len(l.Placement))
+	for k, v := range l.Values {
+		out[k] = v
+	}
+	for k, v := range l.Placement {
+		out[k] = v
+	}
+	return out
+}
+
+// asSaid is the layers with placement folded back into the values, for what reads a layer whole as it
+// did while placement was kept in it: today's mergeable file, which takes every key (ADR 0326 §3), and
+// the judgement that no value holds a line end.
+func asSaid(layers []Layer) []Layer {
+	out := make([]Layer, len(layers))
+	for i, l := range layers {
+		out[i] = l
+		if len(l.Placement) > 0 {
+			out[i] = Layer{From: l.From, Values: l.Whole(), Default: l.Default}
+		}
+	}
+	return out
+}
+
 // Placement is what an assignment says about one of a module's directories.
 type Placement struct {
 	// Path is where the directory is on this machine. Absolute.
@@ -208,7 +271,7 @@ func Places(m Manifest, layers []Layer) (map[string]Placement, error) {
 	}
 	out := map[string]Placement{}
 	for _, layer := range layers {
-		raw, ok := layer.Values[PlacesSetting]
+		raw, ok := layer.Placement[PlacesSetting]
 		if !ok {
 			continue
 		}
@@ -278,7 +341,7 @@ func AccessPlaces(m Manifest, layers []Layer) (map[string]string, error) {
 	}
 	out := map[string]string{}
 	for _, layer := range layers {
-		raw, ok := layer.Values[AccessesSetting]
+		raw, ok := layer.Placement[AccessesSetting]
 		if !ok {
 			continue
 		}

internal/catalogue/placement_test.go

@@ -23,7 +23,7 @@ func placeable() Manifest {
 }
 
 func placedBy(values map[string]any) Rendering {
-	return Rendering{Settings: SettingsBy{"arr": {{From: "node anchor", Values: values}}}}
+	return Rendering{Settings: SettingsBy{"arr": {LayerOf("node anchor", values)}}}
 }
 
 func TestAnAssignmentPlacesDirectoriesAndAccesses(t *testing.T) {
@@ -179,3 +179,43 @@ func TestAnUnknownAccessReferenceIsRefusedAtParse(t *testing.T) {
 		t.Fatalf("an access with no id and no path was accepted: %v", err)
 	}
 }
+
+// **Placement is read from the placement, never from a layer's values** (novox/hq ADR 0348 clause 11, issue
+// 651). A `places` or `accesses` among the config values places nothing; the same in Placement does. A
+// mergeable file of today's form still takes every key of the layer as it is said, placement too, so it
+// composes as it did while placement was kept in the layer.
+func TestPlacementIsReadFromThePlacementOnly(t *testing.T) {
+	m := placeable()
+	said := map[string]any{
+		PlacesSetting:   map[string]any{"config": "/services/arr/config"},
+		AccessesSetting: map[string]any{"series": "/storage/media/series", "spool": "/storage/downloads"},
+		"log":           "warn",
+	}
+	among := []Layer{{From: "anchor", Values: said}}
+	if placed, err := Places(m, among); err != nil || placed != nil {
+		t.Fatalf("a place among the config values placed %v (%v)", placed, err)
+	}
+	if _, _, err := accessesFor(m, among); err == nil {
+		t.Fatal("an access among the config values placed it")
+	}
+	beside := []Layer{LayerOf("anchor", said)}
+	if beside[0].Values["log"] != "warn" || beside[0].Values[PlacesSetting] != nil || beside[0].Placement[PlacesSetting] == nil {
+		t.Fatalf("LayerOf split %+v", beside[0])
+	}
+	if placed, err := Places(m, beside); err != nil || placed["config"].Path != "/services/arr/config" {
+		t.Fatalf("the placement did not place: %v (%v)", placed, err)
+	}
+
+	file := map[string]any{"id": "runtime", "type": "file", "path": "/x", "content": `{"a":1}`, "merge": "json"}
+	whole, err := ApplySettings(file, among)
+	if err != nil {
+		t.Fatal(err)
+	}
+	split, err := ApplySettings(file, beside)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if whole["content"] != split["content"] || !strings.Contains(split["content"].(string), `"places"`) {
+		t.Fatalf("today's mergeable file composes %q, was %q", split["content"], whole["content"])
+	}
+}

internal/catalogue/resolve.go

@@ -111,6 +111,9 @@ type Provider struct {
 	// (novox/hq to-be 23), and the pair is what tells the holder of a seat apart from another module
 	// providing the same thing (ADR 0110).
 	Module string
+	// LeftOut says each served key left out of Serves because that node composes no name it asks
+	// for (novox/hq ADR 0346 §3): said under each consumer's need.
+	LeftOut []string
 }
 
 // Held is a claim somebody already has, used for the scopes wider than one node.
@@ -230,6 +233,9 @@ type Needed struct {
 	// state, not a consumer missing its key. Set by the plan, which is the only layer that knows a
 	// licence's manager; empty for every consumer.
 	Manager bool
+	// LeftOut says each served key the provider left out, because its machine composes no name the
+	// value asks for (novox/hq ADR 0346 §3).
+	LeftOut []string
 	// Module is the providing module on From, empty for a need answered by a record or by nothing
 	// that serves it. A provider is a (node, module) pair (novox/hq to-be 23), and a binding to data
 	// is a binding to the pair (ADR 0232).
@@ -582,7 +588,7 @@ func Resolve(catalogue map[string]Manifest, assigned []string, node Node, world
 					bound = pm.IdentityBoundOf(want)
 				}
 				needs = append(needs, Needed{Name: want, From: p.Node, At: p.At, Module: p.Module,
-					Serves: p.Serves, For: because[want], SharedOwn: shared, Identity: bound})
+					Serves: p.Serves, For: because[want], SharedOwn: shared, Identity: bound, LeftOut: p.LeftOut})
 			}
 			switch {
 			case world.Unchecked:

internal/catalogue/seats.go

@@ -128,7 +128,19 @@ var defaultSeats = append([]Seat{
 	// The vault: the controller seals every minted credential with what it provides, which is the
 	// test for a seat of the mesh's own (novox/hq ADR 0161) — a second provider of `secret` is a
 	// second claimant, refused by name, rather than a candidate for a pin.
-	{Name: "mesh-vault", Scope: ScopeMesh, Delivers: "secret", Decision: "novox/hq ADR 0161"},
+	//
+	// Its one verb, `get`, hands a secret on request and reply, sealed to the key the asker sends and only
+	// to an asker the vault allows (novox/hq ADR 0349 §11, issue 674). Optional until the vault that runs
+	// serves it (design 33 §7).
+	{Name: "mesh-vault", Scope: ScopeMesh, Delivers: "secret", Decision: "novox/hq ADR 0161",
+		Serves: []Verb{
+			{Name: "get", Optional: true, Description: "One secret, sealed to the public key the asker sends (the " +
+				"sealed box of ADR 0206), with its generation; answered only to an asker the vault allows, as the " +
+				"bus proved it. Never the value in the clear, and never to a private key.",
+				Input: schema(map[string]string{"name": "the secret's name",
+					"public_key": "the asker's X25519 public key as SPKI PEM — never a private key"},
+					[]string{"name", "public_key"})},
+		}},
 	// Named for its scope since 2026-09-30 (novox/hq ADR 0156); `the-artifact-store` resolves to it as
 	// an alias on a mesh that predates the rename. It serves artifacts of every kind a build makes —
 	// images and archives, by digest — which is why the provision is the artifact store and not an

internal/catalogue/served_own_names.go

@@ -0,0 +1,202 @@
+package catalogue
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// A provider may tell its consumers its own composed names (novox/hq ADR 0346, issue 624).
+//
+// **The name is already the mesh's.** A module contributes a label to a requirement — a route — and
+// the mesh joins it with the providing machine's domains; the module reads the result in its own files
+// as `${bound:<requirement>:name}` (novox/hq 04-ISSUES/122). Its consumers could not be told it: a
+// served value named only the consumer (ADR 0202) and settings. The forge's package registry writes
+// every tarball at its public name, and a consumer that must trust that name had no source for it but a
+// second copy kept by hand. So a served value may say `${bound:<requirement>:<name>}` for a requirement
+// the provider contributes to, and the mesh fills it from the same composition the provider's own files
+// and its proxy receive.
+//
+// **A name the providing machine does not compose leaves the key out** (ADR 0346 §3): a machine with
+// no public domain has no public name to give, and an empty value or a refusal would be worse than a
+// consumer told nothing — a refused provider machine takes every provision it offers down with it. The
+// plan says which key was left out, and why, on the provider's machine and under each consumer's need.
+
+// ownNameFacts are what a served value may name of the provider's own composition: the names, as its
+// own files read them (withOwnNames).
+var ownNameFacts = []string{"name", "internal-name"}
+
+// requirementsContributedTo is every requirement m contributes to, sorted.
+func requirementsContributedTo(m Manifest) []string {
+	seen := map[string]bool{}
+	for to := range m.Contributes {
+		seen[to] = true
+	}
+	for to := range m.ContributesMany {
+		seen[to] = true
+	}
+	out := make([]string, 0, len(seen))
+	for to := range seen {
+		out = append(out, to)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// ownNameKeys is every name a served value of m may say for one requirement it contributes to:
+// `name` and `internal-name`, and `name-<local>` and `internal-name-<local>` for each local name it
+// contributes under.
+func ownNameKeys(m Manifest, to string) []string {
+	keys := append([]string{}, ownNameFacts...)
+	for _, local := range sortedKeys(m.ContributesMany[to]) {
+		for _, fact := range ownNameFacts {
+			keys = append(keys, fact+"-"+local)
+		}
+	}
+	return keys
+}
+
+// ServedOwnNames fills the provider's own composed names into what it serves one provision's
+// consumers, from this resolution's composition of the provider's machine (ADR 0346).
+//
+// A value naming a name this machine does not compose is left out, with its key, and said. The map is
+// copied only when something changes, as ServedTo does: the caller's may be the manifest's.
+func (r Resolution) ServedOwnNames(m Manifest, provision string, serves map[string]any, layers []Layer) (
+	map[string]any, []string, error) {
+	var asking []string
+	for _, key := range sortedAnyKeys(serves) {
+		if text, ok := serves[key].(string); ok && bound.MatchString(text) {
+			asking = append(asking, key)
+		}
+	}
+	if len(asking) == 0 {
+		return serves, nil, nil
+	}
+	own := map[string]map[string]string{}
+	for _, to := range requirementsContributedTo(m) {
+		names, err := r.ownNames(m, to, layers)
+		if err != nil {
+			return nil, nil, err
+		}
+		values := map[string]string{}
+		withOwnNames(values, names)
+		own[to] = values
+	}
+	out := make(map[string]any, len(serves))
+	for k, v := range serves {
+		out[k] = v
+	}
+	var said []string
+	for _, key := range asking {
+		text := serves[key].(string)
+		var missing string
+		filled := bound.ReplaceAllStringFunc(text, func(token string) string {
+			parts := bound.FindStringSubmatch(token)
+			if value := own[parts[1]][parts[2]]; value != "" && parts[3] == "" {
+				return value
+			}
+			if missing == "" {
+				missing = token
+			}
+			return token
+		})
+		if missing != "" {
+			delete(out, key)
+			said = append(said, fmt.Sprintf(
+				"%s serves %s without %q: it names %s, and %s composes no such name for %s (it has no "+
+					"public domain, or the endpoint is not reached publicly) (novox/hq ADR 0346)",
+				m.Module, provision, key, missing, orHere(r.Node), m.Module))
+			continue
+		}
+		out[key] = filled
+	}
+	return out, said, nil
+}
+
+func orHere(node string) string {
+	if node == "" {
+		return "this machine"
+	}
+	return node
+}
+
+// ServedLeftOut is what the providers in this node's own set leave out of what they serve, because
+// this machine composes no name a served value asks for (ADR 0346 §3): said on the provider's machine,
+// where the remedy is.
+func (r Resolution) ServedLeftOut(settings SettingsBy) []string {
+	var said []string
+	for _, m := range r.Modules {
+		for _, provision := range sortedServes(m.Serves) {
+			_, lines, err := r.ServedOwnNames(m, provision, m.Serves[provision], WithDefaults(m, settings[m.Module]))
+			if err != nil {
+				said = append(said, fmt.Sprintf("%s serves %s, and its own names could not be composed: %v",
+					m.Module, provision, err))
+				continue
+			}
+			said = append(said, lines...)
+		}
+	}
+	return said
+}
+
+// checkServedOwnNames refuses a served `${bound:…}` that names a requirement the module does not
+// contribute to, a fact other than its own names, or a local name it does not contribute under; and
+// one with a default, since a served value is left out rather than given one (ADR 0346 §3, §4).
+func checkServedOwnNames(m Manifest, provision, key, text string) []string {
+	var problems []string
+	contributes := requirementsContributedTo(m)
+	for _, parts := range bound.FindAllStringSubmatch(text, -1) {
+		to, fact, fallback := parts[1], parts[2], parts[3]
+		says := fmt.Sprintf("%s serves %s, and the value it serves as %q says %s", m.Module, provision, key, parts[0])
+		switch {
+		case fallback != "":
+			problems = append(problems, says+": a served name takes no default; one the machine does not "+
+				"compose leaves the key out (novox/hq ADR 0346)")
+		case !oneOf(contributes, to):
+			problems = append(problems, fmt.Sprintf(
+				"%s, and %s contributes to %s: a served value names only the provider's own names "+
+					"(novox/hq ADR 0346)", says, m.Module, orNothing(quoted(contributes))))
+		case !oneOf(ownNameKeys(m, to), fact):
+			problems = append(problems, fmt.Sprintf("%s, and what %s is called through %s is %s (novox/hq ADR 0346)",
+				says, m.Module, to, strings.Join(ownNameKeys(m, to), ", ")))
+		}
+	}
+	return problems
+}
+
+func quoted(values []string) []string {
+	out := make([]string, len(values))
+	for i, v := range values {
+		out[i] = fmt.Sprintf("%q", v)
+	}
+	return out
+}
+
+// nestedOwnNames refuses a `${bound:…}` inside a served list or object: only a string value of its own is
+// filled (ServedOwnNames), so a nested one would reach the consumer as the placeholder (ADR 0346 §5).
+func nestedOwnNames(m Manifest, provision, key string, value any) []string {
+	var found []string
+	var walk func(v any)
+	walk = func(v any) {
+		switch x := v.(type) {
+		case string:
+			found = append(found, bound.FindAllString(x, -1)...)
+		case []any:
+			for _, e := range x {
+				walk(e)
+			}
+		case map[string]any:
+			for _, k := range sortedAnyKeys(x) {
+				walk(x[k])
+			}
+		}
+	}
+	walk(value)
+	if len(found) == 0 {
+		return nil
+	}
+	return []string{fmt.Sprintf(
+		"%s serves %s, and the value it serves as %q holds %s inside a list or an object: a provider's own "+
+			"name is filled only in a string value of its own (novox/hq ADR 0346)",
+		m.Module, provision, key, strings.Join(found, ", "))}
+}

internal/catalogue/served_own_names_test.go

@@ -0,0 +1,168 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// novox/hq ADR 0346, issue 624: the forge's package registry writes every tarball at its public name,
+// and the lab, its consumer, must trust that name and no other. The name is the mesh's own composition
+// of the forge's route, which the forge's files read as ${bound:route:name-web}; a consumer can now be
+// served it.
+
+const aRegistryForge = `{"module":"forge","version":"1","requires":["route"],
+  "provides":[{"name":"npm-package-registry","scope":"mesh"}],
+  "contributes":{"route":{"web":{"label":"git","port":3000}}},
+  "serves":{"npm-package-registry":{"scheme":"http","port":3000,"npm-path":"/api/packages/novox/npm/",
+    "public-root":"https://${bound:route:name-web}/api/packages/novox/npm/"}}}`
+
+func aForgeManifest(t *testing.T) Manifest {
+	t.Helper()
+	m, err := ParseManifest([]byte(aRegistryForge))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return m
+}
+
+func TestAProviderServesItsOwnComposedName(t *testing.T) {
+	m := aForgeManifest(t)
+	r := Resolution{Node: "home", PublicDomain: "example.org"}
+	got, said, err := r.ServedOwnNames(m, "npm-package-registry", m.Serves["npm-package-registry"], nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got["public-root"] != "https://git.example.org/api/packages/novox/npm/" || len(said) != 0 {
+		t.Fatalf("the public root is the route's composed name: %v, said %v", got, said)
+	}
+	if got["npm-path"] != "/api/packages/novox/npm/" || got["port"] != float64(3000) {
+		t.Fatalf("the rest is served as it was: %v", got)
+	}
+	if m.Serves["npm-package-registry"]["public-root"] != "https://${bound:route:name-web}/api/packages/novox/npm/" {
+		t.Fatal("the manifest's own map was rewritten")
+	}
+}
+
+func TestANameTheMachineDoesNotComposeLeavesTheKeyOutAndSaysSo(t *testing.T) {
+	m := aForgeManifest(t)
+	r := Resolution{Node: "home"} // no public domain
+	got, said, err := r.ServedOwnNames(m, "npm-package-registry", m.Serves["npm-package-registry"], nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, there := got["public-root"]; there {
+		t.Fatalf("a name not composed is left out, never written as the placeholder or empty: %v", got)
+	}
+	if got["npm-path"] == nil {
+		t.Fatalf("only the key that names it is left out: %v", got)
+	}
+	if len(said) != 1 || !strings.Contains(said[0], `forge serves npm-package-registry without "public-root"`) ||
+		!strings.Contains(said[0], "home composes no such name") {
+		t.Fatalf("said: %v", said)
+	}
+	if lines := (Resolution{Node: "home", Modules: []Manifest{m}}).ServedLeftOut(nil); len(lines) != 1 {
+		t.Fatalf("the plan on the provider's machine says it: %v", lines)
+	}
+	if lines := (Resolution{Node: "home", PublicDomain: "example.org", Modules: []Manifest{m}}).ServedLeftOut(nil); len(lines) != 0 {
+		t.Fatalf("nothing to say when the name is composed: %v", lines)
+	}
+}
+
+// On the provider's own machine the consumer is served the same name (ADR 0346 §2).
+func TestAConsumerBesideTheProviderIsServedItsName(t *testing.T) {
+	m := aForgeManifest(t)
+	consumer := Manifest{Module: "lab", Version: "1", Requires: []string{"npm-package-registry"},
+		Binds: map[string]string{"npm-package-registry": "/var/lib/lab/package-registry.json"}}
+	node := workstation()
+	node.PublicDomain = "example.org"
+	got, err := Resolve(shelf(minimalRouteProxy(), m, consumer), []string{"route-proxy", "forge", "lab"}, node, World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	served, answered, err := got.servedOnThisMachine("npm-package-registry", Rendering{})
+	if err != nil || !answered {
+		t.Fatalf("answered %v: %v", answered, err)
+	}
+	if served["public-root"] != "https://git.example.org/api/packages/novox/npm/" {
+		t.Fatalf("served beside the provider: %v", served)
+	}
+	out, err := got.Declaration(Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var binding string
+	for _, r := range out {
+		if r["path"] == "/var/lib/lab/package-registry.json" {
+			binding, _ = r["content"].(string)
+		}
+	}
+	if !strings.Contains(binding, `"public-root": "https://git.example.org/api/packages/novox/npm/"`) &&
+		!strings.Contains(binding, `"public-root":"https://git.example.org/api/packages/novox/npm/"`) {
+		t.Fatalf("the consumer's binding carries the name:\n%s", binding)
+	}
+	if strings.Contains(binding, "${bound:") {
+		t.Fatalf("a placeholder reached the consumer:\n%s", binding)
+	}
+}
+
+// From another machine, the provider's served values carry what that machine composed, and a key it
+// left out is said on the consumer's need (ADR 0346 §2, §3).
+func TestAConsumerElsewhereIsToldWhatTheProviderLeftOut(t *testing.T) {
+	consumer := Manifest{Module: "lab", Version: "1", Requires: []string{"npm-package-registry"},
+		Binds: map[string]string{"npm-package-registry": "/var/lib/lab/package-registry.json"}}
+	node := workstation()
+	node.At = "workstation.internal"
+	world := World{Offered: map[string][]Provider{"npm-package-registry": {{Node: "home", At: "home.internal",
+		Module: "forge", Serves: map[string]any{"port": 3000},
+		LeftOut: []string{`forge serves npm-package-registry without "public-root"`}}}}}
+	got, err := Resolve(shelf(aForgeManifest(t), consumer), []string{"lab"}, node, world)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, n := range got.Needs {
+		if n.Name == "npm-package-registry" {
+			if len(n.LeftOut) != 1 {
+				t.Fatalf("the need carries what was left out: %+v", n)
+			}
+			return
+		}
+	}
+	t.Fatalf("no need: %+v", got.Needs)
+}
+
+func TestAServedNameIsCheckedWhenTheDefinitionIsRead(t *testing.T) {
+	for bad, want := range map[string]string{
+		`"public-root":"https://${bound:route:name-api}/x"`:           "what forge is called through route is name, internal-name, name-web, internal-name-web",
+		`"public-root":"https://${bound:postgres-database:name}/x"`:   `forge contributes to "route"`,
+		`"public-root":"https://${bound:route:name-web|default:x}/x"`: "takes no default",
+		`"public-root":"https://${bound:route:at}/x"`:                 "what forge is called through route",
+	} {
+		raw := strings.Replace(aRegistryForge, `"public-root":"https://${bound:route:name-web}/api/packages/novox/npm/"`, bad, 1)
+		_, err := ParseManifest([]byte(raw))
+		if err == nil || !strings.Contains(err.Error(), want) {
+			t.Errorf("%s: want a refusal saying %q, got %v", bad, want, err)
+		}
+	}
+	nested := strings.Replace(aRegistryForge, `"public-root":"https://${bound:route:name-web}/api/packages/novox/npm/"`,
+		`"roots":["https://${bound:route:name-web}/x"]`, 1)
+	if _, err := ParseManifest([]byte(nested)); err == nil || !strings.Contains(err.Error(), "inside a list or an object") {
+		t.Errorf("a nested own name is refused, not served as the placeholder: %v", err)
+	}
+	if _, err := ParseManifest([]byte(aRegistryForge)); err != nil {
+		t.Fatalf("its own name is accepted: %v", err)
+	}
+}
+
+// The provider's contributions file carries no own name on a consumer's entry (ADR 0346 §4): only what
+// is derived for that consumer is there (ADR 0202 §5), and the provider reads its own names in its files.
+func TestAProvidersOwnNameIsNotOnItsConsumersEntry(t *testing.T) {
+	m := aForgeManifest(t)
+	r := Resolution{Node: "home", PublicDomain: "example.org", Modules: []Manifest{m}}
+	derived, err := r.derivedFor("npm-package-registry", "lab_home", "lab", "", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if derived != nil {
+		t.Fatalf("a consumer's entry carries only what was derived for it: %v", derived)
+	}
+}

internal/catalogue/setting_defaults.go

@@ -207,7 +207,8 @@ func Effective(m Manifest, layers []Layer) []SettingSource {
 			Default: d.Default, HasDefault: true}
 	}
 	for _, layer := range layers {
-		for key, v := range layer.Values {
+		// As the layer is said, placement too: `settings` answers it as a person set it.
+		for key, v := range layer.Whole() {
 			s, ok := byKey[key]
 			if !ok {
 				s = &SettingSource{Key: key}

internal/catalogue/setting_defaults_test.go

@@ -427,7 +427,7 @@ func TestALeftOutModulesUnplaceableBackupLineCostsOnlyThatLine(t *testing.T) {
 	r := anAdoptedAnchor()
 	r.Modules = append(r.Modules, holder, media, placedBadly)
 	with := anchorRendering(false)
-	with.Settings["notes"] = []Layer{{From: "anchor", Values: map[string]any{PlacesSetting: "not a map"}}}
+	with.Settings["notes"] = []Layer{LayerOf("anchor", map[string]any{PlacesSetting: "not a map"})}
 	composed, err := r.Compose(with)
 	if err != nil {
 		t.Fatalf("an unplaceable line of a left-out module failed the machine: %v", err)

internal/catalogue/settings.go

@@ -37,6 +37,11 @@ type Layer struct {
 	// Default marks the layer a module's own defaults make (novox/hq ADR 0262). Marked rather than
 	// recognised by From, which is a node's name for a node's layer, and a node may be called anything.
 	Default bool
+	// Placement is the assignment's placement at this layer's scope — `places`, `accesses`, `networks`
+	// — which the controller holds apart from settings (novox/hq ADR 0348 clause 11, issue 651): read
+	// by Places, AccessPlaces and KeptNetworks, and never from Values. LayerOf splits a layer as a person
+	// says it into the two.
+	Placement map[string]any
 }
 
 // ApplySettings produces a resource's final content from the module's own and the layers over it.
@@ -45,6 +50,10 @@ type Layer struct {
 // module first, then this node's. A node that differs from the rest is expressed by differing,
 // rather than by repeating everything the rest already say.
 func ApplySettings(resource map[string]any, layers []Layer) (map[string]any, error) {
+	// Today's form reaches a mergeable file with every key of the layer as it was said, placement too
+	// (novox/hq ADR 0326 §3, ADR 0348 clause 11: a module not yet moved keeps it), so a file composes
+	// byte for byte as it did while placement was kept in the layer.
+	layers = asSaid(layers)
 	how, _ := resource["merge"].(string)
 	taken, names := takenKeys(resource)
 	if how == "" {
@@ -192,6 +201,16 @@ func settle(base map[string]any, layers []Layer, protected map[string]bool, what
 					"%s sets %q on %v, and that module keeps %q for itself — it is not settable",
 					layer.From, key, what, key)
 			}
+			// **No layer replaces a secret the vault fills, at any depth** (novox/hq issue 610): a
+			// mergeable file's `${secret:<name>}` is the vault's value, and a layer that reached it —
+			// `server.secret_key` under a `server` the file takes — would put a value the operator or an
+			// agent chose where the vault's belongs. Judged against the file's own content, so it holds
+			// whatever a module's `protected` list says.
+			if at := secretReplacedBy(base[key], value, key); at != "" {
+				return nil, fmt.Errorf(
+					"%s sets %q on %v, which the vault fills (${secret:…}); a secret comes from the vault, "+
+						"never from a setting (novox/hq issues 342, 610)", layer.From, at, what)
+			}
 			merged[key] = mergeValue(merged[key], value)
 		}
 	}
@@ -385,7 +404,7 @@ func UnusedSettings(m Manifest, layers []Layer) []string {
 	}
 	var unused []string
 	for _, layer := range layers {
-		for key := range layer.Values {
+		for key := range layer.Whole() {
 			if lands[key] {
 				continue
 			}
@@ -473,7 +492,7 @@ func KeptNetworks(m Manifest, layers []Layer, adopted bool) (map[string][]string
 	}
 	out := map[string][]string{}
 	for _, layer := range layers {
-		raw, ok := layer.Values[NetworksSetting]
+		raw, ok := layer.Placement[NetworksSetting]
 		if !ok {
 			continue
 		}
@@ -533,7 +552,8 @@ var networkName = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_.-]*$`)
 // refused where it is stored (SetSettings, with UnusedSettings) and said where a plan is read,
 // and never costs a module its place.
 func JudgeSettings(m Manifest, layers []Layer, adopted bool) error {
-	if err := settingsHoldOneLine(m.Module, layers); err != nil {
+	// Placement is judged for line ends as it always was: a path is written into files as well.
+	if err := settingsHoldOneLine(m.Module, asSaid(layers)); err != nil {
 		return err
 	}
 	// Which keys each mergeable file takes is the definition's to say right (novox/hq ADR 0326);
@@ -576,3 +596,54 @@ func JudgeSettings(m Manifest, layers []Layer, adopted bool) error {
 	}
 	return nil
 }
+
+// secretReplacedBy is the path in a mergeable file's own content that a layer's value would replace while the
+// vault fills it — a string holding `${secret:` — or "" when the value leaves every such string as it is
+// (novox/hq issue 610). Maps merge key by key (mergeValue), so only the keys the value names are judged; any
+// other value replaces the whole of what it lands on.
+func secretReplacedBy(base, value any, at string) string {
+	if baseMap, isMap := base.(map[string]any); isMap {
+		if valueMap, also := value.(map[string]any); also {
+			keys := make([]string, 0, len(valueMap))
+			for k := range valueMap {
+				keys = append(keys, k)
+			}
+			sort.Strings(keys)
+			for _, k := range keys {
+				if found := secretReplacedBy(baseMap[k], valueMap[k], at+"."+k); found != "" {
+					return found
+				}
+			}
+			return ""
+		}
+	}
+	return secretIn(base, at)
+}
+
+// secretIn is the first path under v holding a vault placeholder, or "".
+func secretIn(v any, at string) string {
+	switch t := v.(type) {
+	case string:
+		if strings.Contains(t, "${secret:") {
+			return at
+		}
+	case map[string]any:
+		keys := make([]string, 0, len(t))
+		for k := range t {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		for _, k := range keys {
+			if found := secretIn(t[k], at+"."+k); found != "" {
+				return found
+			}
+		}
+	case []any:
+		for i, item := range t {
+			if found := secretIn(item, fmt.Sprintf("%s[%d]", at, i)); found != "" {
+				return found
+			}
+		}
+	}
+	return ""
+}

internal/catalogue/settings_judge_test.go

@@ -27,7 +27,7 @@ func TestASettingThatCannotComposeIsRefusedByNameAndLeavesOnlyItsModuleOut(t *te
 		if c.name == "a mesh-wide port" {
 			from = MeshWideLayer
 		}
-		err := JudgeSettings(web, []Layer{{From: from, Values: c.layer}}, true)
+		err := JudgeSettings(web, []Layer{LayerOf(from, c.layer)}, true)
 		if err == nil || !strings.Contains(err.Error(), c.refuse) {
 			t.Errorf("%s: judged %v, want %q", c.name, err, c.refuse)
 		}
@@ -69,8 +69,8 @@ func TestASettingThatCannotComposeIsRefusedByNameAndLeavesOnlyItsModuleOut(t *te
 // declaration as the networks it also joins.
 func TestAKeptNetworkReachesTheContainerOnAnAdoptedMachineOnly(t *testing.T) {
 	r := anAdoptedAnchor()
-	keep := SettingsBy{"hello-web": {{From: "anchor",
-		Values: map[string]any{NetworksSetting: map[string]any{"server": []any{"predecessor_default"}}}}}}
+	keep := SettingsBy{"hello-web": {LayerOf("anchor",
+		map[string]any{NetworksSetting: map[string]any{"server": []any{"predecessor_default"}}})}}
 
 	with := anchorRendering(true)
 	with.Settings = keep
@@ -107,13 +107,13 @@ func TestAKeptNetworkReachesTheContainerOnAnAdoptedMachineOnly(t *testing.T) {
 		layer Layer
 		want  string
 	}{
-		{"mesh-wide", Layer{From: MeshWideLayer, Values: map[string]any{NetworksSetting: map[string]any{"server": []any{"x"}}}},
+		{"mesh-wide", LayerOf(MeshWideLayer, map[string]any{NetworksSetting: map[string]any{"server": []any{"x"}}}),
 			"a found network is a fact about one machine"},
-		{"an unknown container", Layer{From: "anchor", Values: map[string]any{NetworksSetting: map[string]any{"db": []any{"x"}}}},
+		{"an unknown container", LayerOf("anchor", map[string]any{NetworksSetting: map[string]any{"db": []any{"x"}}}),
 			`names the container "db", which it does not declare`},
-		{"not a list", Layer{From: "anchor", Values: map[string]any{NetworksSetting: map[string]any{"server": "x"}}},
+		{"not a list", LayerOf("anchor", map[string]any{NetworksSetting: map[string]any{"server": "x"}}),
 			"is a list of network names"},
-		{"not a network name", Layer{From: "anchor", Values: map[string]any{NetworksSetting: map[string]any{"server": []any{"a/b"}}}},
+		{"not a network name", LayerOf("anchor", map[string]any{NetworksSetting: map[string]any{"server": []any{"a/b"}}}),
 			"which is not a network name"},
 	} {
 		_, err := KeptNetworks(web, []Layer{c.layer}, true)

internal/catalogue/settings_test.go

@@ -234,3 +234,29 @@ func TestAServedValueMayBeTheOperators(t *testing.T) {
 		t.Errorf("a setting a served fact asks for is not stray: %v", unused)
 	}
 }
+
+// No layer replaces a value the vault fills, at any depth (novox/hq issue 610): searxng's server.secret_key
+// sits under `server`, a key its file takes, and a layer reaching it was let through by a top-level-only check.
+func TestNoLayerReplacesAVaultSecretAtAnyDepth(t *testing.T) {
+	file := map[string]any{"id": "settings", "type": "file", "merge": MergeJSON,
+		"content": `{"server": {"secret_key": "${secret:secret}", "port": 8080}, "ui": {"theme": "simple"}, "token": "${secret:token}"}`}
+	layer := func(values map[string]any) []Layer { return []Layer{{From: "anchor", Values: values}} }
+
+	merged, err := ApplySettings(file, layer(map[string]any{"server": map[string]any{"port": float64(9000)}, "ui": map[string]any{"theme": "dark"}}))
+	if err != nil {
+		t.Fatalf("a key beside the secret was refused: %v", err)
+	}
+	if c := merged["content"].(string); !strings.Contains(c, `"secret_key": "${secret:secret}"`) || !strings.Contains(c, `"port": 9000`) {
+		t.Fatalf("the secret or the setting did not land as meant:\n%s", c)
+	}
+	for name, values := range map[string]map[string]any{
+		"the nested secret":        {"server": map[string]any{"secret_key": "chosen"}},
+		"the whole map holding it": {"server": "elsewhere"},
+		"a top-level secret":       {"token": "chosen"},
+		"the secret, emptied":      {"server": map[string]any{"secret_key": ""}},
+	} {
+		if _, err := ApplySettings(file, layer(values)); err == nil || !strings.Contains(err.Error(), "vault") {
+			t.Errorf("%s: %v, want a refusal naming the vault", name, err)
+		}
+	}
+}

internal/catalogue/template.go

@@ -0,0 +1,334 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path"
+	"path/filepath"
+	"sort"
+	"strings"
+	"unicode/utf8"
+)
+
+// A file's text kept as a template file in its module's repository (novox/hq ADR 0349 §2, design 57 package T1,
+// issue 654).
+//
+// **Two forms, one composition.** A file resource says its text inline (`content`) or names a template file
+// beside its manifest (`"template": "files/<name>"`), never both. The module's build packs `files/` into an
+// archive artifact of its own — an `archive` artifact built `from: "files"` — and resolving the build reads each
+// template's text back from that packed archive into `content` and drops `template`. So the manifest the mesh
+// holds, composition and the node-engine are exactly as they were: a module with its text in `files/` composes
+// byte-identically to the same module with it inline. Where there is no build — `module check`, the merge gate,
+// `module add` — the text is read from the repository tree beside the manifest (WithTemplatesFrom).
+//
+// **Read back by the builder, carried in the resolved manifest.** The builder reads each template from the very
+// bytes it hashed into the archive's digest, so the text the mesh holds is the archive's. The controller
+// registers the resolved manifest as the build result carries it and fetches nothing from the artifact store; a
+// manifest that still names a template when it would be held — built by a builder that predates templates — is
+// refused at registration (HeldTemplateProblem).
+
+// TemplateField is the key a file resource names its template file by.
+const TemplateField = "template"
+
+// TemplatesDir is the module's directory its template files are kept in, and the directory its templates archive
+// is built from.
+const TemplatesDir = "files"
+
+// Templated is whether any of the manifest's resources names a template.
+func (m Manifest) Templated() bool {
+	for _, r := range m.Resources {
+		if _, has := r[TemplateField]; has {
+			return true
+		}
+	}
+	return false
+}
+
+// TemplatesArtifact is the name of the archive artifact the module packs its templates into — the one built from
+// files/ — or "" when it declares none, or more than one (both refused by templateProblems for a module naming a
+// template).
+func TemplatesArtifact(m Manifest) string {
+	found := templatesArtifacts(m)
+	if len(found) != 1 {
+		return ""
+	}
+	return found[0]
+}
+
+func templatesArtifacts(m Manifest) []string {
+	if m.Build == nil {
+		return nil
+	}
+	var found []string
+	for _, a := range m.Build.Artifacts {
+		if a.Kind == ArtifactArchive && a.URL == "" && cleanFrom(a.From) == TemplatesDir {
+			found = append(found, a.Name)
+		}
+	}
+	return found
+}
+
+// cleanFrom is an artifact's directory as one relative path: "./files/" is "files".
+func cleanFrom(from string) string {
+	c := path.Clean(strings.TrimSpace(from))
+	return strings.TrimPrefix(c, "./")
+}
+
+// templateOf is the template a resource names, whether it names one, and what is wrong with it ("" when nothing).
+func templateOf(module string, r map[string]any) (string, bool, string) {
+	raw, has := r[TemplateField]
+	if !has {
+		return "", false, ""
+	}
+	id := fmt.Sprint(r["id"])
+	if t := fmt.Sprint(r["type"]); t != "file" {
+		return "", true, fmt.Sprintf("%s: %s is a %s and names a template; only a file takes its text from one "+
+			"(novox/hq ADR 0349 §2)", module, id, t)
+	}
+	name, ok := raw.(string)
+	if !ok || strings.TrimSpace(name) == "" {
+		return "", true, fmt.Sprintf("%s: %s names a template that is not a path: %v; a template is %q",
+			module, id, raw, TemplatesDir+"/<name>")
+	}
+	if _, both := r["content"]; both {
+		return name, true, fmt.Sprintf("%s: %s names the template %q and says its content too; a file's text is "+
+			"in one place, the template or the content, never both (novox/hq ADR 0349 §2)", module, id, name)
+	}
+	if strings.HasPrefix(name, "/") || path.Clean(name) != name || !strings.HasPrefix(name, TemplatesDir+"/") ||
+		strings.Contains(name, "\\") {
+		return name, true, fmt.Sprintf("%s: %s names the template %q, which is not a file under %s/ of its own "+
+			"repository: a template is %q, a plain relative path, and the build packs only %s/",
+			module, id, name, TemplatesDir, TemplatesDir+"/<name>", TemplatesDir)
+	}
+	return name, true, ""
+}
+
+// templateProblems is what is wrong with the manifest's templates, as written: a template on something not a file,
+// beside content, outside files/, or a module naming templates whose build packs no archive from files/. Whether
+// each template exists is judged where a tree is (ReadTemplates) or the archive's text is (Resolve).
+func templateProblems(m Manifest) []string {
+	var problems []string
+	templated := false
+	for _, r := range m.Resources {
+		_, has, wrong := templateOf(m.Module, r)
+		templated = templated || has
+		if wrong != "" {
+			problems = append(problems, wrong)
+		}
+	}
+	if !templated {
+		return problems
+	}
+	switch found := templatesArtifacts(m); len(found) {
+	case 0:
+		problems = append(problems, fmt.Sprintf("%s names templates and its build packs no archive from %s/: "+
+			"declare an artifact {\"name\": \"files\", \"kind\": \"archive\", \"from\": %q} (novox/hq ADR 0349 §2)",
+			m.Module, TemplatesDir, TemplatesDir))
+	case 1:
+	default:
+		sort.Strings(found)
+		problems = append(problems, fmt.Sprintf("%s packs %s/ into %s; its templates are read from one archive",
+			m.Module, TemplatesDir, strings.Join(found, " and ")))
+	}
+	return problems
+}
+
+// fillTemplates is resources with each template's text as its content and the template key dropped: text says the
+// text of a template by its path ("files/<name>"), and whether it has one. A template it has no text for, or text
+// that is not UTF-8, is refused by name. Every resource is copied; the manifest's own are left as they were.
+func fillTemplates(module string, resources []map[string]any, text func(string) (string, bool),
+	where string) ([]map[string]any, error) {
+	out := make([]map[string]any, 0, len(resources))
+	var problems []string
+	for _, r := range resources {
+		name, has, wrong := templateOf(module, r)
+		if !has {
+			out = append(out, r)
+			continue
+		}
+		if wrong != "" {
+			problems = append(problems, wrong)
+			continue
+		}
+		body, ok := text(name)
+		if !ok {
+			problems = append(problems, fmt.Sprintf("%s: %v names the template %q, and %s holds no such file",
+				module, r["id"], name, where))
+			continue
+		}
+		if !utf8.ValidString(body) {
+			// A manifest is JSON: text that is not UTF-8 would be changed on the way, silently.
+			problems = append(problems, fmt.Sprintf("%s: %v names the template %q, which is not UTF-8 text; a "+
+				"file's text is carried as JSON and would not reach the machine as written", module, r["id"], name))
+			continue
+		}
+		filled := make(map[string]any, len(r))
+		for k, v := range r {
+			filled[k] = v
+		}
+		delete(filled, TemplateField)
+		filled["content"] = body
+		out = append(out, filled)
+	}
+	if len(problems) > 0 {
+		return nil, errors.New(strings.Join(problems, "; "))
+	}
+	return out, nil
+}
+
+// ReadTemplates is the text of each template the manifest names, read from the module's directory in a repository
+// tree, by template path. Refused by name: a template the directory lacks, and anything under files/ the build's
+// packing refuses — files/ itself, or any directory or file under it, that is a symlink or not a plain file — so
+// nothing judged here can be read from outside the tree, and no tree passes here that the build would refuse. Each
+// template is read through an os.Root of the module's directory besides, which no path element can leave.
+func ReadTemplates(m Manifest, dir string) (map[string]string, error) {
+	problems := templatesTreeProblems(m.Module, dir)
+	root, err := os.OpenRoot(dir)
+	if err != nil {
+		return nil, fmt.Errorf("%s: the module's directory cannot be opened to read its templates: %w", m.Module, err)
+	}
+	defer root.Close()
+	texts := map[string]string{}
+	for _, r := range m.Resources {
+		name, has, wrong := templateOf(m.Module, r)
+		if !has {
+			continue
+		}
+		if wrong != "" {
+			problems = append(problems, wrong)
+			continue
+		}
+		if _, read := texts[name]; read {
+			continue
+		}
+		info, err := root.Lstat(name)
+		switch {
+		case errors.Is(err, fs.ErrNotExist):
+			problems = append(problems, fmt.Sprintf("%s: %v names the template %q, and the module's directory "+
+				"has no such file", m.Module, r["id"], name))
+			continue
+		case err != nil:
+			problems = append(problems, fmt.Sprintf("%s: %v names the template %q, which cannot be read: %v",
+				m.Module, r["id"], name, err))
+			continue
+		case !info.Mode().IsRegular():
+			problems = append(problems, fmt.Sprintf("%s: %v names the template %q, which is not a plain file; "+
+				"the build packs only files", m.Module, r["id"], name))
+			continue
+		}
+		body, err := root.ReadFile(name)
+		if err != nil {
+			problems = append(problems, fmt.Sprintf("%s: %v names the template %q, which cannot be read: %v",
+				m.Module, r["id"], name, err))
+			continue
+		}
+		texts[name] = string(body)
+	}
+	if len(problems) > 0 {
+		return nil, errors.New(strings.Join(problems, "; "))
+	}
+	return texts, nil
+}
+
+// templatesTreeProblems is everything under the module's files/ that the build's packing refuses: files/ itself not
+// a plain directory, and any entry under it that is neither a directory nor a plain file — a symlink, to a file or a
+// directory, a device, a pipe. Each said by its path. A files/ that does not exist is no problem here: each template
+// it would have held is refused as missing.
+func templatesTreeProblems(module, dir string) []string {
+	top := filepath.Join(dir, TemplatesDir)
+	info, err := os.Lstat(top)
+	if errors.Is(err, fs.ErrNotExist) {
+		return nil
+	}
+	if err != nil {
+		return []string{fmt.Sprintf("%s: %s/ cannot be read: %v", module, TemplatesDir, err)}
+	}
+	if !info.IsDir() {
+		return []string{fmt.Sprintf("%s: %s/ is %s, not a directory of the module's own; its templates are read "+
+			"only from inside the repository, and the build packs only directories and files", module, TemplatesDir,
+			kindOf(info.Mode()))}
+	}
+	var problems []string
+	err = filepath.WalkDir(top, func(at string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() || d.Type().IsRegular() {
+			return nil
+		}
+		rel, _ := filepath.Rel(dir, at)
+		problems = append(problems, fmt.Sprintf("%s: %s is %s; the build packs only directories and files, so "+
+			"%s/ holds nothing else", module, filepath.ToSlash(rel), kindOf(d.Type()), TemplatesDir))
+		return nil
+	})
+	if err != nil {
+		problems = append(problems, fmt.Sprintf("%s: %s/ cannot be read: %v", module, TemplatesDir, err))
+	}
+	return problems
+}
+
+// kindOf says what a file that is not a plain file is.
+func kindOf(mode fs.FileMode) string {
+	switch {
+	case mode&fs.ModeSymlink != 0:
+		return "a symlink"
+	case mode&fs.ModeDevice != 0:
+		return "a device"
+	case mode&fs.ModeNamedPipe != 0:
+		return "a named pipe"
+	case mode&fs.ModeSocket != 0:
+		return "a socket"
+	case mode.IsDir():
+		return "a directory"
+	}
+	return "not a plain file"
+}
+
+// WithTemplatesFrom is the manifest with each template's text read from the module's directory in a repository
+// tree as its content: what `module check`, the merge gate and `module add` judge, where nothing was built. Read
+// again strictly afterwards, so every rule about a file's text judges the template's text exactly as it judges
+// inline content. A manifest naming no template is returned as it is.
+func WithTemplatesFrom(m Manifest, dir string) (Manifest, error) {
+	if !m.Templated() {
+		return m, nil
+	}
+	texts, err := ReadTemplates(m, dir)
+	if err != nil {
+		return Manifest{}, err
+	}
+	filled, err := fillTemplates(m.Module, m.Resources, func(name string) (string, bool) {
+		t, ok := texts[name]
+		return t, ok
+	}, "the module's directory")
+	if err != nil {
+		return Manifest{}, err
+	}
+	out := m
+	out.Resources = filled
+	raw, err := json.Marshal(out)
+	if err != nil {
+		return Manifest{}, err
+	}
+	return ParseManifest(raw)
+}
+
+// HeldTemplateProblem is why a manifest cannot be held by the mesh because it still names a template, or "": the
+// manifest the mesh holds carries every file's text, which a build reads back from its templates archive. One
+// naming a template was resolved by a builder that does not read templates, and would compose files with no text.
+func HeldTemplateProblem(m Manifest) string {
+	var named []string
+	for _, r := range m.Resources {
+		if t, has := r[TemplateField]; has {
+			named = append(named, fmt.Sprintf("%v (%v)", r["id"], t))
+		}
+	}
+	if len(named) == 0 {
+		return ""
+	}
+	return fmt.Sprintf("%s still names the template(s) of %s: the manifest the mesh holds carries each file's "+
+		"text, read back from the build's templates archive — this one was resolved by a builder that does not "+
+		"read templates, or not built at all (novox/hq ADR 0349 §2)", m.Module, strings.Join(named, ", "))
+}

internal/catalogue/template_test.go

@@ -0,0 +1,323 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// A file resource may name a template file in its module's repository (novox/hq ADR 0349 §2, design 57 package
+// T1, issue 654): the build packs files/ into an archive, and resolving the build reads each template's text back
+// into content, so the mesh holds, composes and sends exactly what it would for the same text inline.
+
+// The two forms of one module: its text inline, and its text in files/.
+const (
+	inlineTwin = `{"module":"tidy","version":"1",
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]},
+  "resources":[
+    {"id":"conf","type":"directory","path":"${dir:conf}"},
+    {"id":"main","type":"file","path":"${dir:conf}/tidy.conf","mode":"0644","content":"` + mainText + `"},
+    {"id":"extra","type":"file","path":"${dir:conf}/extra.conf","content":"` + extraText + `"}]}`
+	templatedTwin = `{"module":"tidy","version":"1",
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]},
+  "resources":[
+    {"id":"conf","type":"directory","path":"${dir:conf}"},
+    {"id":"main","type":"file","path":"${dir:conf}/tidy.conf","mode":"0644","template":"files/tidy.conf"},
+    {"id":"extra","type":"file","path":"${dir:conf}/extra.conf","template":"files/deeper/extra.conf"}]}`
+	mainText  = `# tidy\nroot = ${dir:conf}\nquoted = \"yes\" é\n`
+	extraText = `one\ntwo\n`
+)
+
+// templateTexts is what a build reads back from the packed files/ archive: by path inside it.
+func templateTexts(t *testing.T) map[string]string {
+	t.Helper()
+	var m struct{ Main, Extra string }
+	if err := json.Unmarshal([]byte(`{"Main":"`+mainText+`","Extra":"`+extraText+`"}`), &m); err != nil {
+		t.Fatal(err)
+	}
+	return map[string]string{"tidy.conf": m.Main, "deeper/extra.conf": m.Extra, "unused.conf": "not named"}
+}
+
+func builtFiles(texts map[string]string) []Built {
+	return []Built{{Name: "files", Kind: ArtifactArchive,
+		Reference: ArtifactStoreScheme + "tidy/files/blobs/sha256:" + strings.Repeat("c", 64),
+		Digest:    "sha256:" + strings.Repeat("c", 64), Texts: texts}}
+}
+
+// held is a manifest as registration holds it: resolved with what was built, then read again strictly.
+func held(t *testing.T, raw string, built []Built) Manifest {
+	t.Helper()
+	m, err := ParseManifest([]byte(raw))
+	if err != nil {
+		t.Fatal(err)
+	}
+	resolved, err := m.Resolve(built)
+	if err != nil {
+		t.Fatal(err)
+	}
+	again, err := json.Marshal(resolved)
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := ParseManifest(again)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if problem := HeldTemplateProblem(out); problem != "" {
+		t.Fatal(problem)
+	}
+	return out
+}
+
+func composed(t *testing.T, m Manifest) string {
+	t.Helper()
+	got, err := Resolve(shelf(m), []string{m.Module}, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := json.Marshal(mustDeclare(t, got))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(out)
+}
+
+func TestATemplatedModuleComposesByteIdenticallyToItsInlineTwin(t *testing.T) {
+	inline := composed(t, held(t, inlineTwin, builtFiles(nil)))
+	templated := composed(t, held(t, templatedTwin, builtFiles(templateTexts(t))))
+	if inline != templated {
+		t.Fatalf("the two forms compose differently:\ninline:    %s\ntemplated: %s", inline, templated)
+	}
+	if !strings.Contains(templated, "quoted = \\\"yes\\\"") || strings.Contains(templated, `"template"`) {
+		t.Fatalf("the composition does not carry the template's text as content: %s", templated)
+	}
+}
+
+// What `module check`, the merge gate and `module add` judge: the text read from the tree beside the manifest.
+func TestATemplatedModuleReadFromItsTreeComposesByteIdenticallyToItsInlineTwin(t *testing.T) {
+	dir := t.TempDir()
+	for name, text := range templateTexts(t) {
+		full := filepath.Join(dir, "files", filepath.FromSlash(name))
+		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(full, []byte(text), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	m, err := ParseManifest([]byte(templatedTwin))
+	if err != nil {
+		t.Fatal(err)
+	}
+	filled, err := WithTemplatesFrom(m, dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if filled.Templated() {
+		t.Fatal("a manifest read from its tree still names a template")
+	}
+	resolved, err := filled.Resolve(builtFiles(nil))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := composed(t, resolved), composed(t, held(t, inlineTwin, builtFiles(nil))); got != want {
+		t.Fatalf("read from the tree, the module composes differently:\ninline:    %s\ntemplated: %s", want, got)
+	}
+}
+
+func TestAFileNamingBothATemplateAndContentIsRefused(t *testing.T) {
+	raw := strings.Replace(templatedTwin, `"template":"files/tidy.conf"`,
+		`"template":"files/tidy.conf","content":"x"`, 1)
+	_, err := ParseManifest([]byte(raw))
+	if err == nil || !strings.Contains(err.Error(), "main") || !strings.Contains(err.Error(), "never both") {
+		t.Fatalf("a file with both a template and content was not refused by name: %v", err)
+	}
+}
+
+func TestATemplateOutsideFilesIsRefusedByName(t *testing.T) {
+	for _, bad := range []string{"../tidy.conf", "/etc/tidy.conf", "files", "files/", "files/../tidy.conf",
+		"files/./tidy.conf", "other/tidy.conf", "tidy.conf", "files//tidy.conf", `files\\tidy.conf`} {
+		raw := strings.Replace(templatedTwin, `"files/tidy.conf"`, `"`+bad+`"`, 1)
+		_, err := ParseManifest([]byte(raw))
+		if err == nil || !strings.Contains(err.Error(), "main") || !strings.Contains(err.Error(), "not a file under files/") {
+			t.Errorf("the template %q was not refused by name: %v", bad, err)
+		}
+	}
+}
+
+func TestATemplateOnAResourceThatIsNotAFileIsRefused(t *testing.T) {
+	raw := strings.Replace(templatedTwin, `{"id":"conf","type":"directory","path":"${dir:conf}"}`,
+		`{"id":"conf","type":"directory","path":"${dir:conf}","template":"files/tidy.conf"}`, 1)
+	_, err := ParseManifest([]byte(raw))
+	if err == nil || !strings.Contains(err.Error(), "conf is a directory and names a template") {
+		t.Fatalf("a directory naming a template was not refused: %v", err)
+	}
+}
+
+func TestATemplatedModuleWhoseBuildPacksNoFilesIsRefused(t *testing.T) {
+	for _, build := range []string{
+		``,
+		`"build":{"artifacts":[{"name":"look","kind":"archive","from":"theme"}]},`,
+		`"build":{"artifacts":[{"name":"a","kind":"archive","from":"files"},{"name":"b","kind":"archive","from":"./files/"}]},`,
+	} {
+		raw := strings.Replace(templatedTwin,
+			`"build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]},`, build, 1)
+		_, err := ParseManifest([]byte(raw))
+		if err == nil || !strings.Contains(err.Error(), "files/") {
+			t.Errorf("a templated module with the build %q was not refused: %v", build, err)
+		}
+	}
+}
+
+func TestAMissingTemplateIsRefusedByName(t *testing.T) {
+	m, err := ParseManifest([]byte(templatedTwin))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// In the tree beside the manifest.
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "files"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "files", "tidy.conf"), []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	_, err = WithTemplatesFrom(m, dir)
+	if err == nil || !strings.Contains(err.Error(), "extra") || !strings.Contains(err.Error(), "files/deeper/extra.conf") {
+		t.Fatalf("a template missing from the tree was not refused by name: %v", err)
+	}
+	// And in what the build read back from its archive.
+	texts := templateTexts(t)
+	delete(texts, "deeper/extra.conf")
+	_, err = m.Resolve(builtFiles(texts))
+	if err == nil || !strings.Contains(err.Error(), "extra") || !strings.Contains(err.Error(), "files/deeper/extra.conf") {
+		t.Fatalf("a template missing from the archive was not refused by name: %v", err)
+	}
+}
+
+func TestATemplateThatIsASymlinkIsRefused(t *testing.T) {
+	m, err := ParseManifest([]byte(templatedTwin))
+	if err != nil {
+		t.Fatal(err)
+	}
+	dir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(dir, "files", "deeper"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "elsewhere"), []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "files", "tidy.conf"), []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink(filepath.Join(dir, "elsewhere"), filepath.Join(dir, "files", "deeper", "extra.conf")); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := WithTemplatesFrom(m, dir); err == nil || !strings.Contains(err.Error(), "not a plain file") {
+		t.Fatalf("a template that is a symlink was not refused: %v", err)
+	}
+}
+
+func TestAResolveWithoutTheArchivesTextIsRefused(t *testing.T) {
+	m, err := ParseManifest([]byte(templatedTwin))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := m.Resolve(builtFiles(nil)); err == nil || !strings.Contains(err.Error(), "files") {
+		t.Fatalf("a templated module resolved with no text read back from its archive: %v", err)
+	}
+}
+
+func TestATemplateThatIsNotUTF8IsRefused(t *testing.T) {
+	m, err := ParseManifest([]byte(templatedTwin))
+	if err != nil {
+		t.Fatal(err)
+	}
+	texts := templateTexts(t)
+	texts["tidy.conf"] = "\xff\xfe"
+	if _, err := m.Resolve(builtFiles(texts)); err == nil || !strings.Contains(err.Error(), "UTF-8") {
+		t.Fatalf("a template that is not UTF-8 was resolved: %v", err)
+	}
+}
+
+// What registration refuses: a manifest to be held that still names a template — one resolved by a builder that
+// predates templates would otherwise compose files with no text.
+func TestAManifestStillNamingATemplateIsNotHeld(t *testing.T) {
+	m, err := ParseManifest([]byte(templatedTwin))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if problem := HeldTemplateProblem(m); !strings.Contains(problem, "main") || !strings.Contains(problem, "files/tidy.conf") {
+		t.Fatalf("a manifest naming a template would be held: %q", problem)
+	}
+	if problem := HeldTemplateProblem(held(t, inlineTwin, builtFiles(nil))); problem != "" {
+		t.Fatalf("an inline manifest is refused: %s", problem)
+	}
+}
+
+// A symlinked files/, or a symlinked directory under it, would read a file outside the tree: refused by name,
+// as is any symlink or special file under files/ that no template names, which the build's packing refuses.
+func TestASymlinkAnywhereUnderFilesIsRefusedByName(t *testing.T) {
+	m, err := ParseManifest([]byte(templatedTwin))
+	if err != nil {
+		t.Fatal(err)
+	}
+	outside := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(outside, "deeper"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for _, name := range []string{"tidy.conf", "deeper/extra.conf", "secret"} {
+		if err := os.WriteFile(filepath.Join(outside, filepath.FromSlash(name)), []byte("outside"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	write := func(t *testing.T, dir, name string) {
+		t.Helper()
+		full := filepath.Join(dir, filepath.FromSlash(name))
+		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(full, []byte("inside"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	link := func(t *testing.T, target, at string) {
+		t.Helper()
+		if err := os.MkdirAll(filepath.Dir(at), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Symlink(target, at); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, c := range []struct {
+		name  string
+		make  func(t *testing.T, dir string)
+		names string
+	}{
+		{"files/ itself", func(t *testing.T, dir string) {
+			link(t, outside, filepath.Join(dir, "files"))
+		}, "files/ is a symlink"},
+		{"a directory under files/", func(t *testing.T, dir string) {
+			write(t, dir, "files/tidy.conf")
+			link(t, filepath.Join(outside, "deeper"), filepath.Join(dir, "files", "deeper"))
+		}, "files/deeper is a symlink"},
+		{"a file no template names", func(t *testing.T, dir string) {
+			write(t, dir, "files/tidy.conf")
+			write(t, dir, "files/deeper/extra.conf")
+			link(t, filepath.Join(outside, "secret"), filepath.Join(dir, "files", "unnamed"))
+		}, "files/unnamed is a symlink"},
+	} {
+		dir := t.TempDir()
+		c.make(t, dir)
+		_, err := WithTemplatesFrom(m, dir)
+		if err == nil || !strings.Contains(err.Error(), c.names) {
+			t.Errorf("a symlinked %s was not refused by name: %v", c.name, err)
+		}
+		if err != nil && strings.Contains(err.Error(), "outside") {
+			t.Errorf("a symlinked %s was read: %v", c.name, err)
+		}
+	}
+}

internal/catalogue/terminal_settings_test.go

@@ -13,22 +13,22 @@ func TestAPlacementOrAnAccessAtTheMachinesOwnIsRefused(t *testing.T) {
 	for _, path := range []string{"/", "/etc", "/etc/", "/etc/sudoers.d", "/usr/bin", "/root", "/var", "/var/lib",
 		"/home", "/home/", "/run", "/run/user/1000", "/var/lib/mesh/x", "/var/lib/mesh-host", "/var/lib/mesh-host/identity",
 		"/srv/../etc", "//etc", "/proc/1", "/sys", "/dev", "/boot/efi", "/bin", "/sbin", "/lib", "/lib64"} {
-		layers := []Layer{{From: "laptop", Values: map[string]any{PlacesSetting: map[string]any{"data": path}}}}
+		layers := []Layer{LayerOf("laptop", map[string]any{PlacesSetting: map[string]any{"data": path}})}
 		if _, err := Places(m, layers); err == nil || !strings.Contains(err.Error(), "issue 339") {
 			t.Errorf("a place at %s: %v", path, err)
 		}
-		layers = []Layer{{From: "laptop", Values: map[string]any{AccessesSetting: map[string]any{"media": path}}}}
+		layers = []Layer{LayerOf("laptop", map[string]any{AccessesSetting: map[string]any{"media": path}})}
 		if _, err := AccessPlaces(m, layers); err == nil || !strings.Contains(err.Error(), "issue 339") {
 			t.Errorf("an access at %s: %v", path, err)
 		}
 	}
 	for _, path := range []string{"/srv/notes", "/mnt/plex/data", "/storage/media", "/services/media/movies",
 		"/var/lib/notes/data", "/home/restic/repo", "/var/lib/mesh-store"} {
-		layers := []Layer{{From: "laptop", Values: map[string]any{PlacesSetting: map[string]any{"data": path}}}}
+		layers := []Layer{LayerOf("laptop", map[string]any{PlacesSetting: map[string]any{"data": path}})}
 		if got, err := Places(m, layers); err != nil || got["data"].Path != path {
 			t.Errorf("a place at %s: %v %v", path, got, err)
 		}
-		layers = []Layer{{From: "laptop", Values: map[string]any{AccessesSetting: map[string]any{"media": path}}}}
+		layers = []Layer{LayerOf("laptop", map[string]any{AccessesSetting: map[string]any{"media": path}})}
 		if got, err := AccessPlaces(m, layers); err != nil || got["media"] != path {
 			t.Errorf("an access at %s: %v %v", path, got, err)
 		}
@@ -111,17 +111,17 @@ func TestTheRuntimesDataAndAnyHomesSSHAreTheMachinesOwn(t *testing.T) {
 	for _, path := range []string{"/var/spool", "/var/spool/cron", "/var/lib/docker", "/var/lib/docker/volumes",
 		"/var/lib/containers/storage", "/var/lib/containerd", "/var/lib/containerd/io.containerd.snapshotter.v1", "/opt", "/opt/app", "/home/alice/.ssh", "/home/alice/.ssh/keys",
 		"/srv/backup/.ssh", "/root/.ssh"} {
-		layers := []Layer{{From: "laptop", Values: map[string]any{PlacesSetting: map[string]any{"data": path}}}}
+		layers := []Layer{LayerOf("laptop", map[string]any{PlacesSetting: map[string]any{"data": path}})}
 		if _, err := Places(m, layers); err == nil || !strings.Contains(err.Error(), "issue 339") {
 			t.Errorf("a place at %s: %v", path, err)
 		}
-		layers = []Layer{{From: "laptop", Values: map[string]any{AccessesSetting: map[string]any{"media": path}}}}
+		layers = []Layer{LayerOf("laptop", map[string]any{AccessesSetting: map[string]any{"media": path}})}
 		if _, err := AccessPlaces(m, layers); err == nil || !strings.Contains(err.Error(), "issue 339") {
 			t.Errorf("an access at %s: %v", path, err)
 		}
 	}
 	for _, path := range []string{"/var/lib/dockerish", "/home/alice/ssh", "/home/alice/.sshd-notes", "/storage/media"} {
-		layers := []Layer{{From: "laptop", Values: map[string]any{PlacesSetting: map[string]any{"data": path}}}}
+		layers := []Layer{LayerOf("laptop", map[string]any{PlacesSetting: map[string]any{"data": path}})}
 		if _, err := Places(m, layers); err != nil {
 			t.Errorf("a place at %s: %v", path, err)
 		}

internal/catalogue/vault_seat_test.go

@@ -23,3 +23,34 @@ func TestTheVaultsSeatDeliversSecret(t *testing.T) {
 		t.Fatal("a provider of secret that does not claim the seat was allowed to hold it")
 	}
 }
+
+// The vault answers `get` on request and reply (novox/hq ADR 0349 §11, issue 674): the seat promises the
+// verb, so a holder serving it is accepted — and, optional while the vault that runs is the TypeScript one,
+// so is a holder that does not yet.
+func TestTheVaultsSeatPromisesGet(t *testing.T) {
+	seat, _ := SeatNamed("mesh-vault")
+	var get *Verb
+	for i := range seat.Serves {
+		if seat.Serves[i].Name == "get" {
+			get = &seat.Serves[i]
+		}
+	}
+	if get == nil {
+		t.Fatal("the vault's seat does not promise get")
+	}
+	for _, arg := range []string{"name", "public_key"} {
+		if props, _ := get.Input["properties"].(map[string]any); props[arg] == nil {
+			t.Errorf("get takes no %s", arg)
+		}
+	}
+	serving := Manifest{Module: "mesh-vault", Provides: []Offer{{Name: "secret", Scope: ScopeMesh}},
+		Claims: []Claim{{Name: "mesh-vault", Scope: ScopeMesh, Serves: []string{"get"}}}}
+	if err := CanHold(serving, seat); err != nil {
+		t.Fatalf("the vault serving get was refused: %v", err)
+	}
+	notYet := Manifest{Module: "mesh-vault", Provides: []Offer{{Name: "secret", Scope: ScopeMesh}},
+		Claims: []Claim{{Name: "mesh-vault", Scope: ScopeMesh}}}
+	if err := CanHold(notYet, seat); err != nil {
+		t.Fatalf("the vault that does not serve get yet was refused: %v", err)
+	}
+}

internal/catalogue/verbs.go

@@ -362,6 +362,12 @@ var ControllerVerbs = []Verb{
 			"register": "\"true\" to register what it builds",
 			"older":    "\"true\", with register: even though a newer build of the module is registered",
 		}, []string{"id"}, "register", "older")},
+	// novox/hq ADR 0350 §5: asked by the delivery's owner when the forge says a pull request closed unmerged.
+	{Name: "forget-checks", Description: "Let go of every build a pull request's merge checks made for its merge in " +
+		"the artifact store's scratch namespace (novox/hq ADR 0350 §5): asked when it closed unmerged; a merged one's go " +
+		"when the walk answering its merge ends, and any check build goes after a week.",
+		Input: schema(map[string]string{"owner": "the repository's owner", "repo": "the repository",
+			"number": "the pull request's number"}, []string{"owner", "repo", "number"})},
 	{Name: "kill", Description: "End a build where it runs: the machine that took it stops its commands and containers and " +
 		"announces it failed, killed by hand — settled, never handed to another machine.",
 		Input: schema(map[string]string{"id": "the build's id"}, []string{"id"})},

internal/inventory/busy_test.go

@@ -0,0 +1,197 @@
+package inventory
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+// A walk whose first machine waited for a busy container counts the wait as a phase of its own, between the
+// send to the first machine and the judging, and its delivery time holds it (novox/hq ADR 0335 §4): the
+// recorded walk again, its judging started only at 17:54:07, a minute after the send, when the machine said
+// the container replaced.
+func TestABusyWaitIsAPhaseOfTheDeliveryTime(t *testing.T) {
+	raw := strings.Replace(recordedWalk, `"gate": {"machines": ["novox"], "since": "2026-10-10T17:53:07.287136827Z",`,
+		`"gate": {"machines": ["novox"], "since": "2026-10-10T17:54:07.287136827Z",
+		  "busy": {"machine": "novox", "module": "mesh-delivery", "container": "mesh-delivery",
+		    "since": "2026-10-10T17:53:07Z", "until": "2026-10-10T18:08:07Z", "ended": "2026-10-10T17:54:07.287136827Z"},`, 1)
+	w := walkOf(t, raw).WalkPhases(time.Date(2026, 10, 10, 18, 0, 0, 0, time.UTC), nil)
+	sumsUp(t, w)
+	if w.TotalMS != 282894 {
+		t.Fatalf("the wait changed the delivery's total: %dms", w.TotalMS)
+	}
+	busy := phase(w, PhaseBusy, 0)
+	if busy.State != PhaseMeasured || busy.TookMS != 60000 {
+		t.Fatalf("the busy wait is not a measured phase of a minute: %+v", busy)
+	}
+	if judged := phase(w, PhaseJudge, 0); judged.TookMS != 148607-60000 {
+		t.Fatalf("the judging still counts from the send, not from the replacement: %+v", judged)
+	}
+	var names []string
+	for _, ph := range w.Phases {
+		names = append(names, ph.Name)
+	}
+	if !strings.Contains(strings.Join(names, " "), PhaseSend+" "+PhaseBusy+" "+PhaseJudge) {
+		t.Fatalf("the busy wait is not between the send and the judging: %v", names)
+	}
+}
+
+// While the wait goes on, the walk says it waits for a busy container there; a walk where nothing waited has no
+// such phase.
+func TestAnOpenBusyWaitIsSaid(t *testing.T) {
+	raw := strings.Replace(recordedWalk, `"gate": {"machines": ["novox"], "since": "2026-10-10T17:53:07.287136827Z", "passes": 3,
+      "verdict": "passed", "judged_at": "2026-10-10T17:55:35.894985053Z"}`,
+		`"gate": {"machines": ["novox"], "since": "2026-10-10T17:53:07.287136827Z",
+		  "busy": {"machine": "novox", "module": "mesh-delivery", "container": "mesh-delivery",
+		    "since": "2026-10-10T17:53:07Z", "until": "2026-10-10T18:08:07Z"}}`, 1)
+	raw = strings.Replace(raw, `"state": "done"`, `"state": "rolling"`, 1)
+	p := walkOf(t, raw)
+	if !p.Modules["mesh-delivery"].Gate.Waiting() {
+		t.Fatal("a gate whose busy wait has not ended does not say it waits")
+	}
+	w := p.WalkPhases(time.Date(2026, 10, 10, 17, 58, 0, 0, time.UTC), nil)
+	busy := phase(w, PhaseBusy, 0)
+	if busy.State != PhaseUnknown || !strings.Contains(busy.Said, "waits for a busy container on novox") {
+		t.Fatalf("an open busy wait is not said: %+v", busy)
+	}
+	if plain := walkOf(t, recordedWalk).WalkPhases(time.Date(2026, 10, 10, 18, 0, 0, 0, time.UTC), nil); phase(plain, PhaseBusy, 0).Name != "" {
+		t.Fatalf("a walk where nothing waited has a busy phase: %+v", plain.Phases)
+	}
+}
+
+// A container a report lists waiting is its module's by its id; its output alone is not a new account.
+func TestABusyContainerIsItsModules(t *testing.T) {
+	list := []BusyWait{{ID: "build-agent.server", Container: "mesh-build-agent", State: BusyWaiting, Said: "a"},
+		{ID: "web.server", State: "replaced-when-idle"}}
+	if b, ok := WaitingFor(list, "build-agent"); !ok || b.Container != "mesh-build-agent" {
+		t.Fatalf("build-agent's container is not found waiting: %+v", b)
+	}
+	if _, ok := WaitingFor(list, "web"); ok {
+		t.Error("a container replaced reads as waiting")
+	}
+	if _, ok := WaitingFor(list, "build"); ok {
+		t.Error("another module's container is found by a prefix of its name")
+	}
+	again := []BusyWait{{ID: "build-agent.server", State: BusyWaiting, Said: "b, a minute on"}, list[1]}
+	if !sameBusy(list, again) {
+		t.Error("a wait whose output changed is a new account")
+	}
+	if sameBusy(list, list[1:]) || !(Doing{Busy: list}).Waiting() || (Doing{Busy: list[1:]}).Waiting() {
+		t.Error("a wait that ended is not a new account")
+	}
+}
+
+// A machine's report of a busy container is kept with its last account and read back beside it, and its
+// starting and its end are news; its output alone is not (novox/hq ADR 0335). Needs the store.
+func TestAReportOfABusyContainerIsKeptAndReadBack(t *testing.T) {
+	inv, node := aNodeWithModules(t)
+	ctx := t.Context()
+	record, err := inv.NodeByName(ctx, node)
+	if err != nil {
+		t.Fatal(err)
+	}
+	since := time.Date(2026, 10, 13, 1, 0, 0, 0, time.UTC)
+	waiting := []BusyWait{{ID: "build-agent.server", Container: "mesh-build-agent", State: BusyWaiting,
+		Since: since, Until: since.Add(15 * time.Minute), Said: "busy: a check"}}
+	keep := func(busy []BusyWait) bool {
+		t.Helper()
+		news, err := inv.RecordOrderedDoing(ctx, record.ID, Doing{Outcome: OutcomeApplied, Declared: "d1", Applied: 1,
+			Busy: busy}, ReportOrder{Epoch: 1, Sequence: 1}, func(ReportOrder) bool { return false })
+		if err != nil {
+			t.Fatal(err)
+		}
+		return news
+	}
+	read := func() []BusyWait {
+		t.Helper()
+		reports, err := inv.LastReports(ctx)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for _, r := range reports {
+			if r.Node == node {
+				return r.Busy
+			}
+		}
+		t.Fatal("the machine's report is not read back")
+		return nil
+	}
+	keep(nil)
+	if got := read(); len(got) != 0 {
+		t.Fatalf("a report with nothing busy reads back %+v", got)
+	}
+	if !keep(waiting) {
+		t.Error("a container starting to wait is not news")
+	}
+	got := read()
+	if b, ok := WaitingFor(got, "build-agent"); !ok || !b.Since.Equal(since) || b.Said != "busy: a check" {
+		t.Fatalf("the wait is not read back: %+v", got)
+	}
+	again := []BusyWait{waiting[0]}
+	again[0].Said = "busy: a check, a minute on"
+	if keep(again) {
+		t.Error("a wait whose output changed is news")
+	}
+	if !keep([]BusyWait{{ID: "build-agent.server", Container: "mesh-build-agent", State: "replaced-when-idle",
+		Since: since, Until: since.Add(15 * time.Minute)}}) {
+		t.Error("a container replaced after it waited is not news")
+	}
+	if _, ok := WaitingFor(read(), "build-agent"); ok {
+		t.Error("a container replaced still reads as waiting")
+	}
+}
+
+// A machine of the rest that answered and waits for a busy container is never read as silent, its wait is kept
+// out of its apply time, and once replaced its report is the end of the wait (novox/hq ADR 0335).
+func TestARestMachineWaitingForABusyContainerIsNeverSilent(t *testing.T) {
+	c := walk582(t)
+	shanks := c.walk.Modules["build-agent"].Rest["shanks"]
+	ref := shanks.Digest + "@" + shanks.At.Format("2006-01-02T15:04:05.000000")
+	answered := shanks.At.Add(15 * time.Second)
+	// shanks answered, and said a container waits: its apply row is the answer, marked busy.
+	c.rows["shanks"][0].Detail = ApplyBusy
+	at := c.judged.Add(20 * time.Minute) // past ApplySilentAfter from its send
+	w := c.walk.WalkPhases(at, c.lookup)
+	var got RestReport
+	for _, r := range w.Rest {
+		if r.Node == "shanks" {
+			got = r
+		}
+	}
+	if got.State != RestBusy || slicesContains(w.Silent, "shanks") {
+		t.Fatalf("a machine waiting for a busy container reads %q (silent: %v)", got.State, w.Silent)
+	}
+	if w.End != nil || !strings.Contains(phase(w, PhaseApply, -1).Said, "waits for a busy container on shanks") {
+		t.Fatalf("the walk ended, or does not say it waits: %+v", phase(w, PhaseApply, -1))
+	}
+
+	// 17 minutes on, shanks says it replaced the container: its wait is its own duration, and its report is then.
+	c.rows["shanks"] = append(c.rows["shanks"], Duration{Kind: DurationBusy, Subject: "shanks", Node: "shanks", Ref: ref,
+		Started: answered, Took: 17 * time.Minute})
+	w = c.walk.WalkPhases(c.judged.Add(time.Hour), c.lookup)
+	sumsUp(t, w)
+	for _, r := range w.Rest {
+		if r.Node == "shanks" {
+			got = r
+		}
+	}
+	if got.State != RestApplied || got.Busy != "17m0s" || !got.Reported.Equal(answered.Add(17*time.Minute)) {
+		t.Fatalf("a machine replaced after its wait reads %+v", got)
+	}
+	if slicesContains(w.Silent, "shanks") || !w.End.Equal(answered.Add(17*time.Minute)) {
+		t.Fatalf("the walk read shanks as silent, or ended elsewhere: %v %v", w.Silent, w.End)
+	}
+	// And the apply time itself is the answer's, never the wait's.
+	if r, _ := FirstReportOf(c.rows["shanks"], shanks, c.walkSent); !r.Answered.Equal(answered) || r.Busy != 17*time.Minute {
+		t.Fatalf("the busy wait is not kept apart from the apply: %+v", r)
+	}
+}
+
+func slicesContains(list []string, s string) bool {
+	for _, x := range list {
+		if x == s {
+			return true
+		}
+	}
+	return false
+}

internal/inventory/catalogue.go

@@ -117,6 +117,11 @@ func (i *Inventory) RegisterModule(ctx context.Context, m catalogue.Manifest, fr
 			}
 		}
 	}
+	// **The manifest the mesh holds carries each file's text** (novox/hq ADR 0349 §2): one still naming a template
+	// would compose a file with no text, so it is refused by name — a build by a builder that predates templates.
+	if why := catalogue.HeldTemplateProblem(m); why != "" {
+		return fmt.Errorf("%s is not registered: %s", m.Module, why)
+	}
 	raw, err := json.Marshal(m)
 	if err != nil {
 		return err
@@ -839,7 +844,18 @@ func (i *Inventory) KeepSettings(ctx context.Context, nodeName, module string, v
 }
 
 func (i *Inventory) setSettings(ctx context.Context, nodeName, module string, values map[string]any, judge bool, setBy string) error {
-	raw, err := json.Marshal(values)
+	// **Placement is not config** (novox/hq ADR 0348 clause 11, issue 651): the layer is said whole, as
+	// it always was, and its placement keys are kept beside the assignment, never in the settings row.
+	// Both are written in one transaction, and the layer a set replaces is the whole of both.
+	config, placement := catalogue.SplitPlacement(values)
+	if config == nil {
+		config = map[string]any{}
+	}
+	raw, err := json.Marshal(config)
+	if err != nil {
+		return err
+	}
+	placed, err := placementJSON(placement)
 	if err != nil {
 		return err
 	}
@@ -881,6 +897,9 @@ func (i *Inventory) setSettings(ctx context.Context, nodeName, module string, va
 			 do update set values = excluded.values, set_at = now(), set_by = excluded.set_by`, module, raw, nullable(setBy)); err != nil {
 			return wrapModule(err, module)
 		}
+		if err := keepPlacement(ctx, tx, nil, module, placed, setBy); err != nil {
+			return err
+		}
 		return tx.Commit(ctx)
 	}
 	node, err := i.NodeByName(ctx, nodeName)
@@ -912,6 +931,9 @@ func (i *Inventory) setSettings(ctx context.Context, nodeName, module string, va
 	if err != nil {
 		return wrapModule(err, module)
 	}
+	if err := keepPlacement(ctx, tx, &node.ID, module, placed, setBy); err != nil {
+		return err
+	}
 	// A given port replaces what the mesh assigned for that port: the assignment is given back,
 	// so the number is free for the next module rather than held for ever in the name of a port
 	// that now lives elsewhere.
@@ -942,21 +964,15 @@ func (i *Inventory) judgeSettings(ctx context.Context, nodeName, module string,
 			return err
 		}
 		where, from, adopted = nodeName, nodeName, node.Adopted
-		var meshWide []byte
-		err = i.store.Pool().QueryRow(ctx,
-			`select values from settings where module = $1 and node is null`, module).Scan(&meshWide)
-		if err != nil && !errors.Is(err, pgx.ErrNoRows) {
+		under, has, err := i.Layer(ctx, "", module)
+		if err != nil {
 			return err
 		}
-		if len(meshWide) > 0 {
-			var under map[string]any
-			if err := json.Unmarshal(meshWide, &under); err != nil {
-				return err
-			}
-			layers = append(layers, catalogue.Layer{From: catalogue.MeshWideLayer, Values: under})
+		if has {
+			layers = append(layers, catalogue.LayerOf(catalogue.MeshWideLayer, under))
 		}
 	}
-	layers = append(layers, catalogue.Layer{From: from, Values: values})
+	layers = append(layers, catalogue.LayerOf(from, values))
 	if err := catalogue.JudgeSettings(m, layers, adopted); err != nil {
 		return fmt.Errorf("refused: %s on %s cannot compose with the layer %q — %w", module, where, from, err)
 	}
@@ -1089,7 +1105,8 @@ func refuseGivenCollisions(ctx context.Context, tx pgx.Tx, nodeID any, node, mod
 }
 
 func wrapModule(err error, module string) error {
-	if err != nil && strings.Contains(err.Error(), "settings_module_fkey") {
+	if err != nil && (strings.Contains(err.Error(), "settings_module_fkey") ||
+		strings.Contains(err.Error(), "placement_module_fkey")) {
 		return fmt.Errorf("%w: %s", ErrNoSuchModule, module)
 	}
 	return err
@@ -1130,6 +1147,11 @@ func (i *Inventory) ClearSettingsBy(ctx context.Context, nodeName, module, clear
 		`delete from settings where module = $1 and node is not distinct from $2::uuid`, module, nodeID); err != nil {
 		return err
 	}
+	// And its placement, which is the same layer as a person says it (novox/hq ADR 0348 clause 11).
+	if _, err := tx.Exec(ctx,
+		`delete from placement where module = $1 and node is not distinct from $2::uuid`, module, nodeID); err != nil {
+		return err
+	}
 	return tx.Commit(ctx)
 }
 
@@ -1142,10 +1164,13 @@ func (i *Inventory) SettingsFor(ctx context.Context, nodeName, module string) ([
 	if err != nil {
 		return nil, err
 	}
+	// Each layer's placement beside it, from the placement the controller holds (novox/hq ADR 0348
+	// clause 11): a layer's Values hold its config values only, its Placement where things are.
 	rows, err := i.store.Pool().Query(ctx,
-		`select node is null, values from settings
-		  where module = $1 and (node is null or node = $2)
-		  order by node is null desc`, module, node.ID)
+		`select s.node is null, s.values, p.values from settings s
+		   left join placement p on p.module = s.module and p.node is not distinct from s.node
+		  where s.module = $1 and (s.node is null or s.node = $2)
+		  order by s.node is null desc`, module, node.ID)
 	if err != nil {
 		return nil, err
 	}
@@ -1154,23 +1179,62 @@ func (i *Inventory) SettingsFor(ctx context.Context, nodeName, module string) ([
 	var layers []catalogue.Layer
 	for rows.Next() {
 		var meshWide bool
-		var raw []byte
-		if err := rows.Scan(&meshWide, &raw); err != nil {
+		var raw, placed []byte
+		if err := rows.Scan(&meshWide, &raw, &placed); err != nil {
 			return nil, err
 		}
 		values := map[string]any{}
 		if err := json.Unmarshal(raw, &values); err != nil {
 			return nil, err
 		}
+		var placement map[string]any
+		if len(placed) > 0 {
+			if err := json.Unmarshal(placed, &placement); err != nil {
+				return nil, err
+			}
+		}
 		from := nodeName
 		if meshWide {
 			from = catalogue.MeshWideLayer
 		}
-		layers = append(layers, catalogue.Layer{From: from, Values: values})
+		layers = append(layers, catalogue.Layer{From: from, Values: values, Placement: placement})
 	}
 	return layers, rows.Err()
 }
 
+// placementJSON is a layer's placement as the placement table keeps it, or nil when it has none.
+func placementJSON(placement map[string]any) ([]byte, error) {
+	if len(placement) == 0 {
+		return nil, nil
+	}
+	return json.Marshal(placement)
+}
+
+// keepPlacement writes one layer's placement beside its settings row, in the write's transaction: the
+// placement the layer says, or none when it says none — a set replaces the layer whole, placement too.
+func keepPlacement(ctx context.Context, tx pgx.Tx, nodeID *string, module string, placed []byte, setBy string) error {
+	if placed == nil {
+		_, err := tx.Exec(ctx,
+			`delete from placement where module = $1 and node is not distinct from $2::uuid`, module, nodeID)
+		return err
+	}
+	var err error
+	if nodeID == nil {
+		_, err = tx.Exec(ctx,
+			`insert into placement (node, module, values, set_by) values (null, $1, $2, $3)
+			 on conflict (module) where node is null
+			 do update set values = excluded.values, set_at = now(), set_by = excluded.set_by`,
+			module, placed, nullable(setBy))
+	} else {
+		_, err = tx.Exec(ctx,
+			`insert into placement (node, module, values, set_by) values ($1, $2, $3, $4)
+			 on conflict (node, module) where node is not null
+			 do update set values = excluded.values, set_at = now(), set_by = excluded.set_by`,
+			*nodeID, module, placed, nullable(setBy))
+	}
+	return wrapModule(err, module)
+}
+
 // PinProvision records which provider a machine gets a provision from: a module, and the node it
 // runs on — both, always (novox/hq #258). A provision comes from a module, and the same module on
 // two machines is two answers, so neither half alone says which.

internal/inventory/durations.go

@@ -20,10 +20,19 @@ const (
 	// DurationWalkPhase is one phase of an ended walk, per class (novox/hq ADR 0282 decision 6): subject
 	// "<class>/<phase>", and "<class>/total" for its merge to every machine running it.
 	DurationWalkPhase = "walk-phase"
+	// DurationBusy is a machine's wait for a busy container (novox/hq ADR 0335): from its first report of a
+	// send, which said a container waits because it is busy, to the report that says it replaced — the same
+	// send's ref as its `apply` row, whose detail is ApplyBusy. Its own measure, never in the apply's.
+	DurationBusy = "busy-wait"
 )
 
+// ApplyBusy is the detail of an `apply` duration whose report said a container waits because it is busy: the
+// machine answered, and is not yet running what it was sent (novox/hq ADR 0335).
+const ApplyBusy = "busy"
+
 // DurationKinds are every kind, in the order `durations` shows them.
-var DurationKinds = []string{DurationApply, DurationHeartbeatGap, DurationPlanTier, DurationBuild, DurationWalkPhase}
+var DurationKinds = []string{DurationApply, DurationHeartbeatGap, DurationPlanTier, DurationBuild, DurationWalkPhase,
+	DurationBusy}
 
 // DurationsKeptFor is how long a duration is kept: long enough to set a bound from, and to correct it
 // in Phase 1's first live week.
@@ -70,6 +79,25 @@ func (i *Inventory) RecordApplyDuration(ctx context.Context, node, declared, out
 	return err
 }
 
+// RecordBusyDuration measures a machine's wait for a busy container, at the report that says it replaced
+// (novox/hq ADR 0335): from the end of its `apply` duration of the send it was last sent, which said it waited, to
+// now. Nothing when that send's first report did not say a wait, and once per send.
+func (i *Inventory) RecordBusyDuration(ctx context.Context, node, declared string) error {
+	if declared == "" {
+		return nil
+	}
+	_, err := i.store.Pool().Exec(ctx,
+		`insert into duration (kind, subject, node, ref, started, took_ms, detail)
+		 select $1, d.subject, d.node, d.ref, d.started + d.took_ms * interval '1 millisecond',
+		        greatest(0, (extract(epoch from (now() - (d.started + d.took_ms * interval '1 millisecond'))) * 1000)::bigint), ''
+		   from duration d join node n on n.name = d.node
+		  where d.kind = $2 and d.subject = $3 and d.detail = $5 and n.sent = $4 and n.sent_at is not null
+		    and d.ref = n.sent || '@' || to_char(n.sent_at at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US')
+		 on conflict do nothing`,
+		DurationBusy, DurationApply, node, declared, ApplyBusy)
+	return err
+}
+
 // RecordHeartbeatGap measures the silence before a machine's word: from the last word heard before
 // it, which the caller read before recording this one.
 func (i *Inventory) RecordHeartbeatGap(ctx context.Context, node string, before time.Time) error {

internal/inventory/fortest.go

@@ -2,6 +2,7 @@ package inventory
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"os"
 	"strings"
@@ -75,3 +76,94 @@ func (i *Inventory) RemoveNodeForTest(ctx context.Context, name string) (bool, e
 	}
 	return tag.RowsAffected() == 1, nil
 }
+
+// ForTestBefore is ForTest with the store migrated only below migration `number`, and a function that runs the
+// rest: for a test of a migration that moves data, which seeds the store as the mesh holds it before the
+// migration, migrates, and reads what the migration made of it (novox/hq issue 651).
+func ForTestBefore(t *testing.T, number int) (*Inventory, func()) {
+	t.Helper()
+	admin := os.Getenv("MESH_TEST_POSTGRES")
+	if admin == "" {
+		t.Skip("no MESH_TEST_POSTGRES; run `make check` to raise one")
+	}
+	name := fmt.Sprintf("invb_%d_%s", time.Now().UnixNano()%1_000_000,
+		strings.ToLower(strings.NewReplacer("/", "", "-", "").Replace(t.Name())))
+	if len(name) > 60 {
+		name = name[:60]
+	}
+	all, err := Migrations()
+	if err != nil {
+		t.Fatal(err)
+	}
+	var before []store.Migration
+	for _, m := range all {
+		if m.Number < number {
+			before = append(before, m)
+		}
+	}
+	store.CreateMigratedForTest(t, admin, name, before)
+	busPasswordCostForTest.Store(int32(bcrypt.MinCost))
+	cut := strings.LastIndex(admin, "/")
+	t.Setenv(store.Variable(Name), admin[:cut]+"/"+name+"?sslmode=disable")
+	inv, err := Open(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		inv.Close()
+		c, err := pgx.Connect(context.Background(), admin)
+		if err != nil {
+			return
+		}
+		defer c.Close(context.Background())
+		_, _ = c.Exec(context.Background(), "drop database if exists "+name+" with (force)")
+	})
+	if err := inv.Ready(t.Context(), 20*time.Second); err != nil {
+		t.Fatal(err)
+	}
+	return inv, func() {
+		t.Helper()
+		if _, err := inv.store.Migrate(t.Context(), all); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+// ExecForTest runs one statement against a test's store, for a fixture no verb of the mesh writes: a row as an
+// older migration left it.
+func (i *Inventory) ExecForTest(t *testing.T, sql string, args ...any) {
+	t.Helper()
+	if _, err := i.store.Pool().Exec(t.Context(), sql, args...); err != nil {
+		t.Fatalf("%s: %v", sql, err)
+	}
+}
+
+// QueryForTest reads rows of a test's store, each row's columns as JSON text, for a test that checks what a
+// migration left.
+func (i *Inventory) QueryForTest(t *testing.T, sql string, args ...any) [][]string {
+	t.Helper()
+	rows, err := i.store.Pool().Query(t.Context(), sql, args...)
+	if err != nil {
+		t.Fatalf("%s: %v", sql, err)
+	}
+	defer rows.Close()
+	var out [][]string
+	for rows.Next() {
+		values, err := rows.Values()
+		if err != nil {
+			t.Fatal(err)
+		}
+		row := make([]string, len(values))
+		for k, v := range values {
+			row[k] = fmt.Sprint(v)
+			if b, err := json.Marshal(v); err == nil {
+				row[k] = string(b)
+			}
+		}
+		out = append(out, row)
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatal(err)
+	}
+	return out
+}

internal/inventory/migrations/0096-a-report-says-a-busy-container.sql

@@ -0,0 +1,11 @@
+-- A machine's report says which container it left running because it said busy, and which it replaced
+-- after it waited (novox/hq ADR 0335, issue 594).
+--
+-- A send that replaced the build agent killed the check it ran, and the queue started it again elsewhere.
+-- A container may now declare `busy`; the node-engine asks it before replacing it, leaves it running while it
+-- says busy, within 15 minutes, and says so in its report's `busy`: [{"id", "container", "state", "since",
+-- "until", "said"}], state `waiting`, `replaced-when-idle` or `replaced-at-bound`. Kept with the machine's
+-- last account, so a walk's first-machine gate waits while its module's container is listed waiting — across
+-- a restart of the controller, which a merge into mesh-controller makes in the same walk that moves the build
+-- agent. Empty from an engine that never waits.
+alter table node_report add column busy jsonb not null default '[]';

internal/inventory/migrations/0097-placement-is-not-config.sql

@@ -0,0 +1,46 @@
+-- Placement is not config (novox/hq ADR 0348 clause 11, issue 651).
+--
+-- Where a module's directories are on a machine (`places`), where the operator's data it reads is
+-- (`accesses`) and which found networks a taken container keeps (`networks`) were kept as keys of a
+-- settings layer. They are facts of an assignment that the controller decides, never config values, and
+-- the config values are leaving for the mesh-config module (ADR 0348 clause 9) while placement stays with
+-- the controller. So they get a table of their own beside the assignment, and every settings layer's
+-- placement keys move into it, unchanged.
+--
+-- Scoped exactly as the layer they came from: one machine's, or the whole mesh's (node null) for a
+-- module's every assignment, which is how a mesh-wide `places` or `accesses` layer composes today. The
+-- composer reads placement from here only; the `settings` verb still takes the three keys and routes
+-- them here, so nothing a person types changes.
+create table placement (
+    node   uuid        references node(id) on delete cascade,
+    module text        not null references module(name) on delete cascade,
+    -- Only `places`, `accesses` and `networks`, as the settings layer held them.
+    values jsonb       not null,
+    set_at timestamptz not null default now(),
+    set_by text
+);
+create unique index placement_for_the_mesh on placement (module) where node is null;
+create unique index placement_for_a_node   on placement (node, module) where node is not null;
+
+-- Why a layer went into the history, beside how (`replaced_by`): said for a layer this migration moved.
+alter table settings_history add column why text;
+
+-- Each layer that held a placement key is kept whole in the history first, as a `settings history` reads it.
+insert into settings_history (node, module, values, set_at, replaced_by, set_by, why)
+select node, module, values, set_at, 'moved', set_by, 'moved to placement, ADR 0348 clause 11'
+  from settings
+ where values ?| array['places', 'accesses', 'networks'];
+
+insert into placement (node, module, values, set_at, set_by)
+select node, module,
+       (select jsonb_object_agg(e.key, e.value) from jsonb_each(values) as e
+         where e.key in ('places', 'accesses', 'networks')),
+       set_at, set_by
+  from settings
+ where values ?| array['places', 'accesses', 'networks'];
+
+-- The layer keeps its other keys, when it was set and who set it; a layer that held only placement stays,
+-- empty, so a layer that existed still exists.
+update settings
+   set values = values - 'places' - 'accesses' - 'networks'
+ where values ?| array['places', 'accesses', 'networks'];

internal/inventory/nodes.go

@@ -10,6 +10,7 @@ import (
 	"errors"
 	"fmt"
 	"regexp"
+	"slices"
 	"sort"
 	"strings"
 	"time"
@@ -846,6 +847,46 @@ type Doing struct {
 	// machine doing what it was told.
 	Since *time.Time
 	Times int
+
+	// Busy is every container the apply left running because it said busy, and every one it replaced after
+	// it waited (novox/hq ADR 0335).
+	Busy []BusyWait
+}
+
+// BusyWait is one container a busy command held, as the machine reported it (novox/hq ADR 0335): its
+// resource id (`<module>.<resource>`), its name, its state (link.BusyWaiting, BusyReplacedIdle or
+// BusyReplacedAtBound), since when it waits, until when at the latest, and the last output of its command.
+type BusyWait struct {
+	ID        string    `json:"id"`
+	Container string    `json:"container"`
+	State     string    `json:"state"`
+	Since     time.Time `json:"since"`
+	Until     time.Time `json:"until"`
+	Said      string    `json:"said,omitempty"`
+}
+
+// BusyWaiting is the state of a container left running because it said busy (link.BusyWaiting).
+const BusyWaiting = "waiting"
+
+// WaitingFor is the container of a module that waits because it said busy, and whether one does: a
+// resource whose id is `<module>.<resource>`.
+func WaitingFor(busy []BusyWait, module string) (BusyWait, bool) {
+	for _, b := range busy {
+		if b.State == BusyWaiting && strings.HasPrefix(b.ID, module+".") {
+			return b, true
+		}
+	}
+	return BusyWait{}, false
+}
+
+// Waiting says whether any container waits because it said busy.
+func (d Doing) Waiting() bool {
+	for _, b := range d.Busy {
+		if b.State == BusyWaiting {
+			return true
+		}
+	}
+	return false
 }
 
 // FailedResource is one thing a node could not do.
@@ -873,6 +914,20 @@ func (d Doing) Stuck() bool { return d.Wrong() && d.Times >= StuckAfter && d.Sin
 // the same failed resources BY ID. Not by the host's words: an error that carries a duration, a
 // counter or a temporary path would read as new on every report, and the resource looping on it —
 // which is what stuck is for — would never be said to be (novox/hq 04-ISSUES/065).
+// sameBusy says two reports hold the same containers in the same state of a busy wait: its output, which
+// may change on every ask, is not compared.
+func sameBusy(a, b []BusyWait) bool {
+	key := func(list []BusyWait) []string {
+		out := make([]string, 0, len(list))
+		for _, w := range list {
+			out = append(out, w.ID+"="+w.State)
+		}
+		sort.Strings(out)
+		return out
+	}
+	return slices.Equal(key(a), key(b))
+}
+
 func sameFailure(a, b Doing) bool {
 	if a.Outcome != b.Outcome || a.Refused != b.Refused || len(a.Failed) != len(b.Failed) {
 		return false
@@ -937,13 +992,20 @@ func recordDoing(ctx context.Context, q queries, node string, d Doing) (news boo
 	if err != nil {
 		return false, err
 	}
+	if d.Busy == nil {
+		d.Busy = []BusyWait{}
+	}
+	busy, err := json.Marshal(d.Busy)
+	if err != nil {
+		return false, err
+	}
 	var before Doing
-	var beforeFailed []byte
+	var beforeFailed, beforeBusy []byte
 	found := q.QueryRow(ctx,
-		`select outcome, refused, failed, failing_since, failures, coalesce(declared,'')
+		`select outcome, refused, failed, failing_since, failures, coalesce(declared,''), busy
 		   from node_report where node = $1`,
 		node).Scan(&before.Outcome, &before.Refused, &beforeFailed, &before.Since, &before.Times,
-		&before.Declared)
+		&before.Declared, &beforeBusy)
 	switch {
 	case errors.Is(found, pgx.ErrNoRows):
 		news = true
@@ -953,7 +1015,13 @@ func recordDoing(ctx context.Context, q queries, node string, d Doing) (news boo
 		if err := json.Unmarshal(beforeFailed, &before.Failed); err != nil {
 			return false, err
 		}
-		news = before.Outcome != d.Outcome || before.Declared != d.Declared || !sameFailure(before, d)
+		if err := json.Unmarshal(beforeBusy, &before.Busy); err != nil {
+			return false, err
+		}
+		// A container that starts or ends a wait because it said busy is news (novox/hq ADR 0335): the walk
+		// waiting on this machine is told by it.
+		news = before.Outcome != d.Outcome || before.Declared != d.Declared || !sameFailure(before, d) ||
+			!sameBusy(before.Busy, d.Busy)
 	}
 	var since *time.Time
 	times := 0
@@ -966,13 +1034,13 @@ func recordDoing(ctx context.Context, q queries, node string, d Doing) (news boo
 	}
 	_, err = q.Exec(ctx,
 		`insert into node_report (node, outcome, refused, failed, applied, at, declared,
-		                          failing_since, failures)
-		 values ($1, $2, $3, $4, $5, now(), $6, $7, $8)
+		                          failing_since, failures, busy)
+		 values ($1, $2, $3, $4, $5, now(), $6, $7, $8, $9)
 		 on conflict (node) do update set outcome = excluded.outcome, refused = excluded.refused,
 		   failed = excluded.failed, applied = excluded.applied, at = excluded.at,
 		   declared = excluded.declared,
-		   failing_since = excluded.failing_since, failures = excluded.failures`,
-		node, d.Outcome, d.Refused, failed, d.Applied, d.Declared, since, times)
+		   failing_since = excluded.failing_since, failures = excluded.failures, busy = excluded.busy`,
+		node, d.Outcome, d.Refused, failed, d.Applied, d.Declared, since, times, busy)
 	if err != nil {
 		return false, err
 	}
@@ -1059,6 +1127,8 @@ type Reported struct {
 	// gate holds against the send it made, rather than against the send made last (novox/hq issue 352).
 	Declared         string
 	ReportedSequence int64
+	// Busy is what the last report said of containers held by their busy command (novox/hq ADR 0335).
+	Busy []BusyWait
 }
 
 // SentDeclaration is what one send carried to a machine, as a gate keeps it: the declaration's digest and
@@ -1112,8 +1182,8 @@ func (i *Inventory) SentTo(ctx context.Context, name string) (SentDeclaration, b
 func (i *Inventory) LastReports(ctx context.Context) ([]Reported, error) {
 	rows, err := i.store.Pool().Query(ctx,
 		`select n.name, coalesce(r.outcome, ''), r.at, n.sent_at,
-		        r.declared is not null and r.declared <> '' and r.declared = n.sent,
-		        coalesce(r.declared, ''), coalesce(r.reported_sequence, 0)
+		        coalesce(r.declared is not null and r.declared <> '' and r.declared = n.sent, false),
+		        coalesce(r.declared, ''), coalesce(r.reported_sequence, 0), coalesce(r.busy, '[]')
 		 from node n left join node_report r on r.node = n.id
 		 order by n.name`)
 	if err != nil {
@@ -1123,7 +1193,12 @@ func (i *Inventory) LastReports(ctx context.Context) ([]Reported, error) {
 	var out []Reported
 	for rows.Next() {
 		var r Reported
-		if err := rows.Scan(&r.Node, &r.Outcome, &r.At, &r.Sent, &r.Current, &r.Declared, &r.ReportedSequence); err != nil {
+		var busy []byte
+		if err := rows.Scan(&r.Node, &r.Outcome, &r.At, &r.Sent, &r.Current, &r.Declared, &r.ReportedSequence,
+			&busy); err != nil {
+			return nil, err
+		}
+		if err := json.Unmarshal(busy, &r.Busy); err != nil {
 			return nil, err
 		}
 		out = append(out, r)

internal/inventory/placement_test.go

@@ -0,0 +1,222 @@
+package inventory
+
+import (
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// placedLibrary is a module with each kind of placement: a directory to place, two accesses, a container that
+// may keep a found network.
+func placedLibrary() catalogue.Manifest {
+	return catalogue.Manifest{Module: "library", Version: "1",
+		Accesses: []catalogue.Access{{ID: "series"}, {ID: "downloads"}},
+		Resources: []map[string]any{
+			{"id": "config", "type": "directory", "mode": "0750"},
+			{"id": "server", "type": "container",
+				"image":   "registry.invalid:5000/library@sha256:" + strings.Repeat("a", 64),
+				"volumes": []any{"${dir:config}:/config", "${access:series}:/series", "${access:downloads}:/downloads"}},
+			{"id": "runtime-config", "type": "file", "path": "${dir:config}/runtime.json", "mode": "0640",
+				"content": `{"log":"info"}`, "merge": "json"},
+		}}
+}
+
+// The layers of the issue (651): a mesh-wide layer with an access and a config value, a node's layer with a
+// place, an access and a kept network beside a config value, a node's layer of placement only, and one with
+// none.
+var placementLayers = []struct {
+	node   string
+	values string
+}{
+	{"", `{"accesses": {"downloads": "/storage/downloads"}, "log": "warn"}`},
+	{"anchor", `{"places": {"config": {"path": "/var/lib/library/config", "owner": "1001:2000"}},
+		"accesses": {"series": "/storage/media/series"}, "networks": {"server": ["predecessor_default"]}, "workers": 4}`},
+	{"laptop", `{"accesses": {"series": "/home/media/series"}}`},
+	{"spare", `{"log": "debug"}`},
+}
+
+// **Placement moves out of the settings layers, and every layer reads as it did** (novox/hq ADR 0348 clause
+// 11, issue 651). Migration 0097 moves each layer's places, accesses and kept networks beside it: no settings
+// row holds a placement key after, every layer the settings verb and composition read is what it was, each
+// moved layer is kept whole in the history with why, and a layer without placement is not touched.
+func TestPlacementMovesOutOfTheSettingsLayers(t *testing.T) {
+	inv, migrate := ForTestBefore(t, 97)
+	ctx := t.Context()
+	if err := inv.RegisterModule(ctx, placedLibrary(), Source{}); err != nil {
+		t.Fatal(err)
+	}
+	for _, n := range []string{"anchor", "laptop", "spare"} {
+		if _, err := inv.AddNode(ctx, n); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := inv.SetAdopted(ctx, "anchor", true); err != nil {
+		t.Fatal(err)
+	}
+	// As the mesh holds them before the migration: placement among the settings.
+	for _, l := range placementLayers {
+		if l.node == "" {
+			inv.ExecForTest(t, `insert into settings (node, module, values, set_by) values (null, 'library', $1, 'the operator')`, l.values)
+			continue
+		}
+		inv.ExecForTest(t, `insert into settings (node, module, values) select id, 'library', $2 from node where name = $1`,
+			l.node, l.values)
+	}
+	setAt := inv.QueryForTest(t, `select coalesce(n.name, ''), s.set_at from settings s left join node n on n.id = s.node order by 1`)
+
+	migrate()
+
+	if held := inv.QueryForTest(t, `select module from settings where values ?| array['places', 'accesses', 'networks']`); len(held) != 0 {
+		t.Fatalf("a settings layer still holds a placement key: %v", held)
+	}
+	if after := inv.QueryForTest(t, `select coalesce(n.name, ''), s.set_at from settings s left join node n on n.id = s.node order by 1`); !reflect.DeepEqual(after, setAt) {
+		t.Fatalf("the layers or when they were set changed: %v, was %v", after, setAt)
+	}
+	for _, l := range placementLayers {
+		var want map[string]any
+		if err := json.Unmarshal([]byte(l.values), &want); err != nil {
+			t.Fatal(err)
+		}
+		got, has, err := inv.Layer(ctx, l.node, "library")
+		if err != nil || !has || !reflect.DeepEqual(roundTrip(t, got), want) {
+			t.Errorf("the layer on %q reads %v (%v, %v), was %v", l.node, got, has, err, want)
+		}
+	}
+	// Composition's view: the config values in Values, the placement in Placement, together the layer.
+	layers, err := inv.SettingsFor(ctx, "anchor", "library")
+	if err != nil || len(layers) != 2 {
+		t.Fatalf("anchor's layers: %v, %v", layers, err)
+	}
+	if layers[1].Values["workers"] == nil || layers[1].Values["places"] != nil || layers[1].Placement["places"] == nil ||
+		layers[1].Placement["networks"] == nil || layers[0].Placement["accesses"] == nil || layers[0].Values["log"] != "warn" {
+		t.Fatalf("anchor's layers split wrong: %+v", layers)
+	}
+	for i, l := range layers {
+		var want map[string]any
+		_ = json.Unmarshal([]byte(placementLayers[i].values), &want)
+		if !reflect.DeepEqual(roundTrip(t, l.Whole()), want) {
+			t.Errorf("anchor's layer %s is %v whole, was %v", l.From, l.Whole(), want)
+		}
+	}
+	// Judged as composition judges them, as before: anchor is adopted, so its kept network composes.
+	if err := catalogue.JudgeSettings(placedLibrary(), layers, true); err != nil {
+		t.Fatalf("the moved layers no longer compose: %v", err)
+	}
+
+	moved := inv.QueryForTest(t, `select coalesce(n.name, ''), h.replaced_by, h.why, h.set_by from settings_history h
+		left join node n on n.id = h.node order by 1`)
+	want := [][]string{
+		{`""`, `"moved"`, `"moved to placement, ADR 0348 clause 11"`, `"the operator"`},
+		{`"anchor"`, `"moved"`, `"moved to placement, ADR 0348 clause 11"`, `null`},
+		{`"laptop"`, `"moved"`, `"moved to placement, ADR 0348 clause 11"`, `null`},
+	}
+	if !reflect.DeepEqual(moved, want) {
+		t.Fatalf("the history of what moved: %v, want %v", moved, want)
+	}
+	past, err := inv.SettingsHistory(ctx, "anchor", "library")
+	if err != nil || len(past) != 1 || past[0].Why != "moved to placement, ADR 0348 clause 11" || past[0].Values["places"] == nil {
+		t.Fatalf("settings history on anchor: %+v, %v", past, err)
+	}
+}
+
+// **The settings verb's path still takes a placement key, and routes it** (issue 651): a set keeps the
+// placement beside the layer and the rest in it, reads back whole, is refused as before when the placement
+// cannot compose (nothing written), and a set or a clear replaces the placement with the layer.
+func TestASettingRoutesPlacementBesideTheLayer(t *testing.T) {
+	inv := ForTest(t)
+	ctx := t.Context()
+	if err := inv.RegisterModule(ctx, placedLibrary(), Source{}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := inv.AddNode(ctx, "anchor"); err != nil {
+		t.Fatal(err)
+	}
+	// Placement alone is a layer as well: the whole mesh's says where both accesses are.
+	meshWide := map[string]any{"accesses": map[string]any{
+		"downloads": "/storage/downloads", "series": "/storage/series"}}
+	if err := inv.SetSettings(ctx, "", "library", meshWide); err != nil {
+		t.Fatal(err)
+	}
+	if got, has, _ := inv.Layer(ctx, "", "library"); !has || !reflect.DeepEqual(roundTrip(t, got), roundTrip(t, meshWide)) {
+		t.Fatalf("the mesh-wide layer of placement only reads %v (%v)", got, has)
+	}
+	set := map[string]any{"log": "warn",
+		"places":   map[string]any{"config": map[string]any{"path": "/var/lib/library/config"}},
+		"accesses": map[string]any{"series": "/storage/media/series"}}
+	if err := inv.SetSettings(ctx, "anchor", "library", set); err != nil {
+		t.Fatal(err)
+	}
+	stored := inv.QueryForTest(t, `select s.values, p.values from settings s join placement p using (module, node)
+		where s.node is not null`)
+	if len(stored) != 1 || stored[0][0] != `{"log":"warn"}` ||
+		!strings.Contains(stored[0][1], `"places"`) || !strings.Contains(stored[0][1], `"accesses"`) {
+		t.Fatalf("the layer and its placement are kept as %v", stored)
+	}
+	if got, _, _ := inv.Layer(ctx, "anchor", "library"); !reflect.DeepEqual(roundTrip(t, got), roundTrip(t, set)) {
+		t.Fatalf("the layer reads %v, was set %v", got, set)
+	}
+
+	// Refused as before, by the same judgement, and nothing changes.
+	for name, bad := range map[string]map[string]any{
+		"an undeclared directory": {"places": map[string]any{"cache": "/var/lib/library/cache"}},
+		"the machine's own":       {"accesses": map[string]any{"series": "/etc"}},
+		"a kept network on a converged machine": {
+			"networks": map[string]any{"server": []any{"predecessor_default"}}},
+	} {
+		if err := inv.SetSettings(ctx, "anchor", "library", bad); err == nil {
+			t.Errorf("%s was kept", name)
+		}
+	}
+	if err := inv.SetSettings(ctx, "", "library", map[string]any{"accesses": meshWide["accesses"],
+		"networks": map[string]any{"server": []any{"x"}}}); err == nil || !strings.Contains(err.Error(), "per node") {
+		t.Errorf("a mesh-wide kept network: %v", err)
+	}
+	if got, _, _ := inv.Layer(ctx, "anchor", "library"); !reflect.DeepEqual(roundTrip(t, got), roundTrip(t, set)) {
+		t.Fatalf("a refused set changed the layer to %v", got)
+	}
+
+	// A set without placement replaces it too, and the history keeps the layer whole.
+	if err := inv.SetSettings(ctx, "anchor", "library", map[string]any{"log": "debug"}); err != nil {
+		t.Fatal(err)
+	}
+	if rows := inv.QueryForTest(t, `select module from placement where node is not null`); len(rows) != 0 {
+		t.Fatalf("a set without placement left it: %v", rows)
+	}
+	past, err := inv.SettingsHistory(ctx, "anchor", "library")
+	if err != nil || len(past) != 1 || past[0].Values["places"] == nil || past[0].Values["log"] != "warn" {
+		t.Fatalf("the replaced layer is not kept whole: %+v, %v", past, err)
+	}
+
+	// The merge gate's way in keeps a layer as the facts carry it, whole: split the same way.
+	if err := inv.KeepSettings(ctx, "anchor", "library", map[string]any{"log": "info",
+		"places": map[string]any{"config": "/var/lib/library/config"}}); err != nil {
+		t.Fatal(err)
+	}
+	if rows := inv.QueryForTest(t, `select values from settings where values ? 'places'`); len(rows) != 0 {
+		t.Fatalf("a kept layer put placement among the settings: %v", rows)
+	}
+	for _, node := range []string{"", "anchor"} {
+		if err := inv.ClearSettings(ctx, node, "library"); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if rows := inv.QueryForTest(t, `select module from placement`); len(rows) != 0 {
+		t.Fatalf("a clear left the placement: %v", rows)
+	}
+}
+
+func roundTrip(t *testing.T, v map[string]any) map[string]any {
+	t.Helper()
+	b, err := json.Marshal(v)
+	if err != nil {
+		t.Fatal(err)
+	}
+	out := map[string]any{}
+	if err := json.Unmarshal(b, &out); err != nil {
+		t.Fatal(err)
+	}
+	return out
+}

internal/inventory/plans.go

@@ -286,6 +286,9 @@ type PlanModule struct {
 	FirstAt *time.Time `json:"first_at,omitempty"`
 	Commit  string     `json:"commit,omitempty"`
 	Why     string     `json:"why,omitempty"`
+	// Made is what the walk's build of it did (novox/hq ADR 0350 §4): "reused from <check build>", naming the pull
+	// request's head, the trunk commit and the digests, or "built: <why>". Said in `plan-moved` and kept here.
+	Made string `json:"made,omitempty"`
 	// Build is the id of the build the plan asked for this module (novox/hq ADR 0219), so the plan
 	// matches its outcome by id — the one thing every outcome echoes, a failed one that never learnt
 	// its module's name included. Empty in a plan from before it was kept, which is matched by
@@ -323,13 +326,25 @@ type PlanGate struct {
 	// machine's report is held against. Absent on a gate kept before it was, which reads the report
 	// against the send made last, as before.
 	Sent map[string]SentDeclaration `json:"sent,omitempty"`
+	// Applied is, per machine, the time of the first report the gate read of its send applied: the
+	// node-engine started the build before it, so a witness window counted from it ends no earlier than the
+	// node-engine's own (novox/hq ADR 0351 decisions 1 and 4).
+	Applied map[string]time.Time `json:"applied,omitempty"`
 	// Passes counts the consecutive judgings that found it healthy, LastPass the newest; a judging that
 	// does not resets them.
 	Passes int `json:"passes,omitempty"`
-	// Wants is how many passes the send needs: a core module's three, a leaf module's one (novox/hq ADR 0282
-	// decision 4 as ADR 0304 decision 3 changed it). Zero in a gate judged before it was said: three.
+	// Wants is how many passes the send needs: three for the node-engine or the mesh's resolver, or fewer at two
+	// minutes when healthy throughout, one for any other module (novox/hq ADR 0351 and ADR 0352, changing ADR
+	// 0282 decision 4 and ADR 0304 decision 3). Zero in a gate
+	// judged before it was said: three.
 	Wants    int        `json:"wants,omitempty"`
 	LastPass *time.Time `json:"last_pass,omitempty"`
+	// Faulted says a judging found the send broken, or not healthy after a healthy reading: a module under the three-reading
+	// rule then passes on its readings alone, never at its two minutes (novox/hq ADR 0352).
+	Faulted bool `json:"faulted,omitempty"`
+	// HealthySeen says a judging found the send healthy, counted or not: one taken before a module's floor
+	// counts too, so a dip after it is a fault (novox/hq ADR 0352 decision 3).
+	HealthySeen bool `json:"healthy_seen,omitempty"`
 	// Last is what the newest judging found wanting, while it still may pass.
 	Last string `json:"last,omitempty"`
 	// Verdict is empty while judging, then passed or failed, with Why, at JudgedAt, Took after Since.
@@ -372,6 +387,42 @@ type PlanGate struct {
 	// alone to the machine holding the bus, every build there kept, so what the send newly grants is on the
 	// bus before the gate judges it. Nil when the list did not change, or the gate's machine holds the bus.
 	Grants *GrantsStep `json:"grants,omitempty"`
+	// Busy is the wait for a busy container on a judged machine (novox/hq ADR 0335 §4): while the machine
+	// reports its module's container left running because it said busy, the judging waits and has not
+	// started; once it reports the container replaced, Since is moved to then. Nil when nothing waited.
+	Busy *GateBusy `json:"busy,omitempty"`
+}
+
+// GateBusy is a first-node gate's wait for a busy container (novox/hq ADR 0335 §4).
+type GateBusy struct {
+	Machine   string `json:"machine"`
+	Module    string `json:"module"`
+	Container string `json:"container"`
+	// Since is when the machine's first apply that would have replaced it ran, Until when its node-engine
+	// replaces it at the latest; Ended when the machine reported it replaced and the judging began — or when
+	// the controller stopped waiting past the engine's bound, which PastBound says.
+	Since time.Time `json:"since"`
+	Until time.Time `json:"until"`
+	// Seen is when this controller first read the wait, on its own clock: the gate's bound runs from it, never
+	// from the engine's word alone.
+	Seen      time.Time  `json:"seen,omitzero"`
+	Ended     *time.Time `json:"ended,omitempty"`
+	PastBound bool       `json:"past_bound,omitempty"`
+	// Said is the last output of its busy command, as the machine reported it.
+	Said string `json:"said,omitempty"`
+}
+
+// Waiting says the gate waits for a busy container and has not started.
+func (g *PlanGate) Waiting() bool { return g != nil && g.Busy != nil && g.Busy.Ended == nil }
+
+// Words is the wait in a line, as the walk says it.
+func (b *GateBusy) Words() string {
+	said := ""
+	if b.Said != "" {
+		said = "; its busy command says: " + b.Said
+	}
+	return fmt.Sprintf("waits for a busy container on %s: %s holds work, and is replaced once it says idle, by %s "+
+		"at the latest (novox/hq ADR 0335)%s", b.Machine, b.Container, b.Until.UTC().Format(time.RFC3339), said)
 }
 
 // GrantsStep is the bus's user list sent to the machine holding the bus ahead of a gated send (novox/hq
@@ -433,6 +484,20 @@ type PlanRelease struct {
 	Skipped []string `json:"skipped,omitempty"`
 	// By is the person who released it, empty when the mesh did.
 	By string `json:"by,omitempty"`
+	// Settings is set on a settings walk (novox/hq ADR 0344): not the builds waiting for a gate, but a settings
+	// layer the operator approved, sent to the machines it reaches one at a time, its module judged on each.
+	Settings *PlanSettings `json:"settings,omitempty"`
+}
+
+// PlanSettings is what a settings walk sends (novox/hq ADR 0344): the module whose layer the operator approved, the
+// layer's scope, the ask that approved it and what changed, in words.
+type PlanSettings struct {
+	Module string `json:"module"`
+	// Node is the machine the layer is for, empty for the whole mesh.
+	Node string `json:"node,omitempty"`
+	// Ask is the proposal the operator approved, and Change what its layer changed ("~ prefs").
+	Ask    string `json:"ask"`
+	Change string `json:"change,omitempty"`
 }
 
 // The states a plan passes through.

internal/inventory/template_test.go

@@ -0,0 +1,25 @@
+package inventory
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// The manifest the mesh holds carries each file's text (novox/hq ADR 0349 §2): one still naming a template — a
+// build by a builder that predates templates, or a manifest handed over unbuilt — would compose a file with no
+// text, and is refused by name.
+func TestAManifestStillNamingATemplateIsNotRegistered(t *testing.T) {
+	inv := ForTest(t)
+	m := catalogue.Manifest{Module: "notifier", Version: "1", Resources: []map[string]any{
+		{"id": "conf", "type": "file", "path": "/etc/notifier.conf", "template": "files/notifier.conf"}}}
+	err := inv.RegisterModule(t.Context(), m, Source{})
+	if err == nil || !strings.Contains(err.Error(), "files/notifier.conf") {
+		t.Fatalf("a manifest naming a template was registered: %v", err)
+	}
+	m.Resources[0] = map[string]any{"id": "conf", "type": "file", "path": "/etc/notifier.conf", "content": "x"}
+	if err := inv.RegisterModule(t.Context(), m, Source{}); err != nil {
+		t.Fatalf("the same manifest with its text was refused: %v", err)
+	}
+}

internal/inventory/unseen.go

@@ -20,9 +20,11 @@ func (i *Inventory) Layer(ctx context.Context, nodeName, module string) (map[str
 	if err != nil {
 		return nil, false, err
 	}
+	// Said whole, as it was set: its config values and the placement kept beside them (novox/hq ADR 0348
+	// clause 11), so a person reading it before setting it sees every key they may keep or remove.
 	var raw []byte
-	err = i.store.Pool().QueryRow(ctx,
-		`select values from settings where module = $1 and node is not distinct from $2::uuid`,
+	err = i.store.Pool().QueryRow(ctx, `select `+layerWhole+` from settings s
+		  where s.module = $1 and s.node is not distinct from $2::uuid`,
 		module, nodeID).Scan(&raw)
 	if errors.Is(err, pgx.ErrNoRows) {
 		return nil, false, nil
@@ -46,6 +48,9 @@ type PastLayer struct {
 	ReplacedBy string
 	// SetBy is who had set the layer, when it was kept (novox/hq ADR 0277); empty for one set before that was kept.
 	SetBy string
+	// Why is why it went, where that was said: "moved to placement, ADR 0348 clause 11" for a layer whose
+	// placement keys migration 0097 moved out of it (ReplacedBy "moved").
+	Why string
 }
 
 // LayerOrigin is who set a layer and when (novox/hq ADR 0277): empty words for a layer set before who set it was
@@ -79,7 +84,7 @@ func (i *Inventory) SettingsHistory(ctx context.Context, nodeName, module string
 		return nil, err
 	}
 	rows, err := i.store.Pool().Query(ctx,
-		`select values, set_at, replaced_at, replaced_by, set_by from settings_history
+		`select values, set_at, replaced_at, replaced_by, set_by, why from settings_history
 		  where module = $1 and node is not distinct from $2::uuid order by replaced_at desc`,
 		module, nodeID)
 	if err != nil {
@@ -90,13 +95,16 @@ func (i *Inventory) SettingsHistory(ctx context.Context, nodeName, module string
 	for rows.Next() {
 		var raw []byte
 		var p PastLayer
-		var by *string
-		if err := rows.Scan(&raw, &p.SetAt, &p.ReplacedAt, &p.ReplacedBy, &by); err != nil {
+		var by, why *string
+		if err := rows.Scan(&raw, &p.SetAt, &p.ReplacedAt, &p.ReplacedBy, &by, &why); err != nil {
 			return nil, err
 		}
 		if by != nil {
 			p.SetBy = *by
 		}
+		if why != nil {
+			p.Why = *why
+		}
 		if err := json.Unmarshal(raw, &p.Values); err != nil {
 			return nil, err
 		}
@@ -107,9 +115,15 @@ func (i *Inventory) SettingsHistory(ctx context.Context, nodeName, module string
 
 // keepReplacedSQL copies a layer into the history before it is replaced or cleared; run in the same
 // transaction as the write where there is one, so a write that fails leaves no history of it.
+//
+// The layer is kept whole, as it was set: its config values and its placement (novox/hq ADR 0348 clause 11).
 const keepReplacedSQL = `insert into settings_history (node, module, values, set_at, replaced_by, set_by)
-	select node, module, values, set_at, $3, set_by from settings
-	 where module = $1 and node is not distinct from $2::uuid`
+	select s.node, s.module, ` + layerWhole + `, s.set_at, $3, s.set_by from settings s
+	 where s.module = $1 and s.node is not distinct from $2::uuid`
+
+// layerWhole is a settings row `s` with the placement kept beside it folded back in: the layer as it was set.
+const layerWhole = `s.values || coalesce((select p.values from placement p
+	 where p.module = s.module and p.node is not distinct from s.node), '{}'::jsonb)`
 
 // layerNode is the node id of a layer, nil for the whole mesh's.
 func (i *Inventory) layerNode(ctx context.Context, nodeName string) (*string, error) {

internal/inventory/walkphases.go

@@ -26,6 +26,7 @@ const (
 	PhaseBetween  = "between-tiers" // one tier's end to the next tier's ask
 	PhaseBuild    = "build"         // a tier asked to its last module built
 	PhaseSend     = "send-first"    // built to sent to the first machines
+	PhaseBusy     = "busy-wait"     // sent first to a busy container there replaced, when one waited (ADR 0335)
 	PhaseJudge    = "judgement"     // sent first to the first-node gate's last verdict: its readings
 	PhaseRest     = "send-rest"     // judged to sent to the rest
 	PhaseApply    = "apply"         // the last send to every machine of the rest reporting the build applied
@@ -90,6 +91,11 @@ type WalkPhase struct {
 type AppliedReport struct {
 	At      time.Time
 	Outcome string
+	// Answered is, for a machine that waited for a busy container (novox/hq ADR 0335), its first report of the
+	// send; Busy how long it then waited; Waiting that it still waits, At being its first report then.
+	Answered time.Time
+	Busy     time.Duration
+	Waiting  bool
 }
 
 // AppliedLookup answers a machine's report of the send the walk made to it: send is what the walk kept of it, and
@@ -108,9 +114,13 @@ type RestReport struct {
 	Reported *time.Time `json:"reported,omitempty"`
 	Took     string     `json:"took,omitempty"`
 	Outcome  string     `json:"outcome,omitempty"`
-	// State is applied, failed, waiting (not yet heard, within ApplySilentAfter) or silent (not heard within it:
-	// listed, never moving the walk's end).
+	// Busy is how long it waited for a busy container before it ran the build (novox/hq ADR 0335): inside Took,
+	// never read as the machine being silent.
+	Busy string `json:"busy,omitempty"`
+	// State is applied, failed, waiting (not yet heard, within ApplySilentAfter), busy (it answered and waits for
+	// a busy container: never silent) or silent (not heard within it: listed, never moving the walk's end).
 	State string `json:"state"`
+	busy  time.Duration
 }
 
 // The states of a machine of the rest.
@@ -118,6 +128,7 @@ const (
 	RestApplied = "applied"
 	RestFailed  = "failed"
 	RestWaiting = "waiting"
+	RestBusy    = "busy"
 	RestSilent  = "silent"
 )
 
@@ -300,8 +311,11 @@ func (p Plan) points(now time.Time, applied AppliedLookup, w *WalkPhases) []poin
 		if t > p.Tier || (t == p.Tier && p.Tier < len(p.Tiers) && !askedAnyOf(p, tier)) {
 			break
 		}
-		var asked, built, first, judged, rest *time.Time
+		var asked, built, first, judged, rest, busyEnded *time.Time
 		allBuilt, anyFirst, allJudged, allRest := true, false, true, true
+		// A busy container on a first machine holds the judging until it is replaced (novox/hq ADR 0335 §4): a
+		// phase of its own, only in a tier where one waited, counted in the delivery time and never exempted.
+		anyBusy, allBusyEnded, busyOn := false, true, ""
 		for _, m := range tier {
 			s := p.Modules[m]
 			if s == nil {
@@ -319,6 +333,14 @@ func (p Plan) points(now time.Time, applied AppliedLookup, w *WalkPhases) []poin
 			if s.FirstAt != nil {
 				anyFirst = true
 				first = earliest(first, s.FirstAt)
+				if s.Gate != nil && s.Gate.Busy != nil {
+					anyBusy = true
+					if s.Gate.Busy.Ended == nil {
+						allBusyEnded, busyOn = false, s.Gate.Busy.Machine
+					} else {
+						busyEnded = latest(busyEnded, s.Gate.Busy.Ended)
+					}
+				}
 				if s.Gate != nil {
 					if s.Gate.JudgedAt == nil {
 						allJudged = false
@@ -349,7 +371,15 @@ func (p Plan) points(now time.Time, applied AppliedLookup, w *WalkPhases) []poin
 			if !allJudged {
 				judged = nil
 			}
-			out = append(out, point{phase: PhaseSend, tier: t, at: first}, point{phase: PhaseJudge, tier: t, at: judged})
+			out = append(out, point{phase: PhaseSend, tier: t, at: first})
+			if anyBusy {
+				said := ""
+				if !allBusyEnded {
+					busyEnded, said = nil, "waits for a busy container on "+busyOn
+				}
+				out = append(out, point{phase: PhaseBusy, tier: t, at: busyEnded, said: said})
+			}
+			out = append(out, point{phase: PhaseJudge, tier: t, at: judged})
 		} else {
 			out = append(out, point{phase: PhaseSend, tier: t, none: true, said: "no first machine: nothing to judge"},
 				point{phase: PhaseJudge, tier: t, none: true, said: "no first machine: nothing to judge"})
@@ -393,6 +423,13 @@ func (p Plan) points(now time.Time, applied AppliedLookup, w *WalkPhases) []poin
 		if r, ok := applied(s.node, s.what, s.walkSent); ok {
 			got := r.At
 			rr.Reported, rr.Outcome, rr.Took = &got, r.Outcome, words(r.At.Sub(at))
+			if r.Busy > 0 {
+				rr.Busy = words(r.Busy)
+				rr.busy = r.Busy
+			}
+			if r.Waiting {
+				rr.Reported, rr.Took, rr.State = nil, "", RestBusy
+			}
 		}
 		reports[key] = rr
 		order = append(order, key)
@@ -409,16 +446,20 @@ func (p Plan) points(now time.Time, applied AppliedLookup, w *WalkPhases) []poin
 			if later.Node == rr.Node && later.Sent.After(rr.Sent) && later.Reported != nil &&
 				(rr.Reported == nil || later.Reported.Before(*rr.Reported)) {
 				got := *later.Reported
-				rr.Reported, rr.Outcome, rr.Took = &got, later.Outcome, words(got.Sub(rr.Sent))
+				rr.Reported, rr.Outcome, rr.Took, rr.State = &got, later.Outcome, words(got.Sub(rr.Sent)), ""
 			}
 		}
 	}
 	var end *time.Time
-	var waiting, failed []string
+	var waiting, failed, busy []string
 	for _, k := range order {
 		rr := reports[k]
 		switch {
-		case rr.Reported == nil && now.Sub(rr.Sent) > ApplySilentAfter, rr.Reported != nil && rr.Reported.Sub(rr.Sent) > ApplySilentAfter:
+		case rr.State == RestBusy:
+			// It answered and waits for a busy container: never silent, and the walk's end waits for it.
+			busy = appendOnce(busy, rr.Node)
+		case rr.Reported == nil && now.Sub(rr.Sent) > ApplySilentAfter,
+			rr.Reported != nil && rr.Reported.Sub(rr.Sent)-rr.busy > ApplySilentAfter:
 			rr.State = RestSilent
 			w.Silent = appendOnce(w.Silent, rr.Node)
 		case rr.Reported == nil:
@@ -443,9 +484,15 @@ func (p Plan) points(now time.Time, applied AppliedLookup, w *WalkPhases) []poin
 	switch {
 	case len(failed) > 0:
 		return append(out, point{phase: PhaseApply, tier: -1, said: "not applied on " + strings.Join(failed, ", ")})
-	case len(waiting) > 0:
-		return append(out, point{phase: PhaseApply, tier: -1, said: "waiting for " + strings.Join(waiting, ", ") +
-			" to report it applied"})
+	case len(waiting) > 0 || len(busy) > 0:
+		var said []string
+		if len(waiting) > 0 {
+			said = append(said, "waiting for "+strings.Join(waiting, ", ")+" to report it applied")
+		}
+		if len(busy) > 0 {
+			said = append(said, "waits for a busy container on "+strings.Join(busy, ", "))
+		}
+		return append(out, point{phase: PhaseApply, tier: -1, said: strings.Join(said, "; ")})
 	case end == nil:
 		return append(out, point{phase: PhaseApply, tier: -1, said: "no machine of the rest heard from: " +
 			strings.Join(w.Silent, ", ")})
@@ -536,19 +583,19 @@ func words(d time.Duration) string {
 func (i *Inventory) FirstAppliedAfter(ctx context.Context, node string, send SentDeclaration, walkSent time.Time) (AppliedReport, bool, error) {
 	from, to := applyRowsBetween(send, walkSent)
 	rows, err := i.store.Pool().Query(ctx,
-		`select ref, started, took_ms, detail from duration
-		  where kind = $1 and subject = $2 and started >= $3 and started < $4
+		`select kind, ref, started, took_ms, detail from duration
+		  where subject = $2 and ((kind = $1 and started >= $3 and started < $4) or (kind = $5 and started >= $3))
 		  order by started`,
-		DurationApply, node, from, to)
+		DurationApply, node, from, to, DurationBusy)
 	if err != nil {
 		return AppliedReport{}, false, err
 	}
 	defer rows.Close()
 	var ds []Duration
 	for rows.Next() {
-		d := Duration{Kind: DurationApply, Subject: node, Node: node}
+		d := Duration{Subject: node, Node: node}
 		var ms int64
-		if err := rows.Scan(&d.Ref, &d.Started, &ms, &d.Detail); err != nil {
+		if err := rows.Scan(&d.Kind, &d.Ref, &d.Started, &ms, &d.Detail); err != nil {
 			return AppliedReport{}, false, err
 		}
 		d.Took = time.Duration(ms) * time.Millisecond
@@ -583,16 +630,30 @@ func applyRowsBetween(send SentDeclaration, walkSent time.Time) (time.Time, time
 //     before the walk's record of its send, as it was read before.
 //
 // A send past ApplySilentAfter is never read: its machine slept, and is listed silent (ADR 0282 decision 1).
+//
+// **A first report that said a container waits because it is busy** (novox/hq ADR 0335) is the machine's answer,
+// and not yet the build running: its report is the end of its busy wait, the `busy-wait` duration of the same
+// send, with the wait said apart (Busy). While none is kept the machine is still waiting (Waiting), never silent.
 func FirstReportOf(ds []Duration, send SentDeclaration, walkSent time.Time) (AppliedReport, bool) {
 	from, to := applyRowsBetween(send, walkSent)
 	for _, d := range ds {
-		if d.Started.Before(from) || !d.Started.Before(to) {
+		if d.Kind == DurationBusy || d.Started.Before(from) || !d.Started.Before(to) {
 			continue
 		}
 		if send.Digest != "" && !strings.HasPrefix(d.Ref, send.Digest+"@") {
 			continue
 		}
-		return AppliedReport{At: d.Started.Add(d.Took).UTC(), Outcome: d.Detail}, true
+		answered := d.Started.Add(d.Took).UTC()
+		if d.Detail != ApplyBusy {
+			return AppliedReport{At: answered, Outcome: d.Detail}, true
+		}
+		for _, b := range ds {
+			if b.Kind == DurationBusy && b.Ref == d.Ref {
+				return AppliedReport{At: b.Started.Add(b.Took).UTC(), Outcome: OutcomeApplied, Answered: answered,
+					Busy: b.Took}, true
+			}
+		}
+		return AppliedReport{At: answered, Outcome: OutcomeApplied, Answered: answered, Waiting: true}, true
 	}
 	return AppliedReport{}, false
 }

internal/link/build.go

@@ -92,6 +92,38 @@ type BuildRequest struct {
 	// facts snapshot, raises the throwaway stores the check needs, runs the repository's own
 	// merge-check.sh and answers its verdict. Nothing is built, published or registered.
 	Check *CheckRequest `json:"check,omitempty"`
+	// Reuse makes this ask a walk's build of a trunk commit (novox/hq ADR 0350 §2): the builder takes the reuse key
+	// of the commit's tree and, where a check build holds the same key, copies it by digest into the module's
+	// namespace instead of building. Pulls are the pull requests the walk answers, whose checks name the part of a
+	// differing key. Nil for every other ask — a check, a dry run, `build --ref`, `rebuild`, `replay` — which never
+	// takes a check's build. A builder from before it ignores it and builds.
+	Reuse *ReuseAsk `json:"reuse,omitempty"`
+}
+
+// ReuseAsk is a walk's leave to take a check's build (novox/hq ADR 0350 §2).
+//
+// **Only a build a verdict names is taken.** Builds are the builds the build seat said, in the outcomes of its checks
+// of the walk's own pull requests, that it made for their merges: each key with its artifacts' digests. The record
+// in the scratch namespace is not trusted alone — the artifact store takes writes from anything on the network, a
+// check runs a pull request's own script on that network, and a record planted under another merge's key would
+// otherwise be registered. The builder takes a scratch build only when a build here names its key and every digest.
+type ReuseAsk struct {
+	Pulls  []PullRef      `json:"pulls,omitempty"`
+	Builds []CheckedBuild `json:"builds,omitempty"`
+}
+
+// CheckedBuild is one build a check's verdict names: the pull request it checked, its ask, and the build.
+type CheckedBuild struct {
+	Pull  PullRef    `json:"pull"`
+	Check string     `json:"check"`
+	Built CheckBuilt `json:"built"`
+}
+
+// PullRef names a pull request.
+type PullRef struct {
+	Owner  string `json:"owner"`
+	Repo   string `json:"repo"`
+	Number int    `json:"number"`
 }
 
 // CheckRequest is what a merge check needs beyond the repository and its head.
@@ -128,6 +160,34 @@ type CheckRequest struct {
 	// repository's own check is not run for a group: each member's pull request runs its own.
 	Group   string        `json:"group,omitempty"`
 	Members []GroupMember `json:"members,omitempty"`
+	// Builds are the modules the delivery plan moves, in the walk's order (novox/hq ADR 0350 §1): the check builds
+	// each, from the merge it judged, into the scratch namespace once it has judged and not failed, for the walk to
+	// take. A build seat from before it builds nothing, and the walk builds as before.
+	Builds []CheckBuild `json:"builds,omitempty"`
+}
+
+// CheckBuild is one module a check builds for its merge: from the merge it made when Merged — a module built from
+// the repository checked, at the branch merged into — else from Repository at Ref, as the walk would.
+type CheckBuild struct {
+	Module     string `json:"module"`
+	Repository string `json:"repository,omitempty"`
+	Path       string `json:"path,omitempty"`
+	Ref        string `json:"ref,omitempty"`
+	Merged     bool   `json:"merged,omitempty"`
+	Tier       int    `json:"tier"`
+	// Skip says why the check cannot build it as the walk would — a module that reads the repository checked
+	// through a context, which a check cannot hand the merge — and nothing after it is built either.
+	Skip string `json:"skip,omitempty"`
+}
+
+// CheckBuilt is one build a check made for its merge, as its verdict lists it (novox/hq ADR 0350 §1): the reuse key
+// and the artifacts, in the scratch namespace — or why it was not built.
+type CheckBuilt struct {
+	Module   string         `json:"module"`
+	Key      string         `json:"key,omitempty"`
+	Made     []MadeArtifact `json:"made,omitempty"`
+	NotBuilt string         `json:"not-built,omitempty"`
+	Took     string         `json:"took,omitempty"`
 }
 
 // GroupMember is one other head of a delivery group's composed check.
@@ -175,6 +235,8 @@ type CheckOutcome struct {
 	Trunk   string            `json:"trunk,omitempty"`
 	Beside  map[string]string `json:"beside,omitempty"`
 	Members []CheckedMember   `json:"members,omitempty"`
+	// Built are the builds it made for its merge (novox/hq ADR 0350 §1).
+	Built []CheckBuilt `json:"built,omitempty"`
 }
 
 // SourceOnSeat names a repository by the seat whose holder serves it and its path there.
@@ -264,6 +326,14 @@ type BuildResult struct {
 	// Failed is why, when it did.
 	Failed string `json:"failed,omitempty"`
 
+	// ReuseKey is the build's reuse key (novox/hq ADR 0350 §1). Reused, on a walk's build that took a check's build
+	// instead of building, is "reused from <check build>" with its digests, and ReusedFrom which; BuiltWhy, on one
+	// that built, why it took none (§3, §4). Both empty from a builder that predates it.
+	ReuseKey   string      `json:"reuse-key,omitempty"`
+	Reused     string      `json:"reused,omitempty"`
+	ReusedFrom *ReusedFrom `json:"reused-from,omitempty"`
+	BuiltWhy   string      `json:"built-why,omitempty"`
+
 	// Source is the request's, echoed: the seat form of the repository, for whoever registers.
 	Source *SourceOnSeat `json:"source,omitempty"`
 
@@ -300,3 +370,25 @@ type MadeArtifact struct {
 	Kind      string `json:"kind"`
 	Reference string `json:"reference"`
 }
+
+// ReusedFrom is the check build a walk's build took (novox/hq ADR 0350 §4): its pull request, the head and the trunk
+// commit the check merged it into, the check's ask, and its key.
+type ReusedFrom struct {
+	Pull  PullRef `json:"pull"`
+	Head  string  `json:"head,omitempty"`
+	Trunk string  `json:"trunk,omitempty"`
+	Check string  `json:"check,omitempty"`
+	Key   string  `json:"key"`
+}
+
+// MadeWords is what a walk says a module's build did (novox/hq ADR 0350 §4): "reused from <check build>", or "built:
+// <why>". A build seat from before it says neither, and that is said.
+func (r BuildResult) MadeWords() string {
+	switch {
+	case r.Reused != "":
+		return r.Reused
+	case r.BuiltWhy != "":
+		return "built: " + r.BuiltWhy
+	}
+	return "built: the build seat did not say whether a check's build could be taken (it predates ADR 0350)"
+}

internal/link/builds_nats.go

@@ -175,6 +175,11 @@ type MachineOptions struct {
 	// can take a build, which is what its container's health check reads (novox/hq issue 544). Nil is
 	// told nothing.
 	Taking func()
+	// Claim is asked once a request is fetched, just before it is handed over: false hands it back to the
+	// queue at once, for another holder. A holder being drained says so here (novox/hq ADR 0335): it marks
+	// 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
 }
 
 // MachineOverNATS takes build work from the current build role.
@@ -317,6 +322,12 @@ func (m *natsMachine) Take(ctx context.Context, do func(context.Context, Build))
 				endCancelled(ctx, build)
 				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 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.

internal/link/check_builds_test.go

@@ -0,0 +1,39 @@
+package link
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+)
+
+// The builds a walk may take are read from the build seat's own outcomes of its checks (novox/hq ADR 0350 §2): only
+// checks of the walk's pull requests, only builds made, newest first.
+func TestNatsTheBuildsAWalkMayTakeAreTheChecksOutcomesOfItsPullRequests(t *testing.T) {
+	js := aBus(t)
+	since := time.Now().Add(-time.Minute)
+	say := func(r BuildResult) {
+		body, _ := json.Marshal(r)
+		if _, err := js.Context().Publish(BuildOutcomeOf(TheBuildMachine), body); err != nil {
+			t.Fatal(err)
+		}
+	}
+	mine := &CheckRequest{Owner: "novox", Repo: "shop", Number: 7}
+	built := CheckBuilt{Module: "app", Key: "r1:1", Made: []MadeArtifact{{Name: "server", Reference: "s/app/server@sha256:a"}}}
+	say(BuildResult{ID: "build-1", Checked: mine, Check: &CheckOutcome{Verdict: "pass", Built: []CheckBuilt{built,
+		{Module: "web", NotBuilt: "it has no reuse key"}}}})
+	say(BuildResult{ID: "build-2", Checked: &CheckRequest{Owner: "novox", Repo: "shop", Number: 8},
+		Check: &CheckOutcome{Verdict: "pass", Built: []CheckBuilt{built}}})
+	say(BuildResult{ID: "build-3", Repository: "novox/shop", Commit: "c0ffee"}) // a build, not a check
+	newer := built
+	newer.Key = "r1:2"
+	say(BuildResult{ID: "build-4", Checked: mine, Check: &CheckOutcome{Verdict: "pass", Built: []CheckBuilt{newer}}})
+
+	got, err := ReadCheckBuilds(t.Context(), js, TheBuildMachine, []PullRef{{Owner: "novox", Repo: "shop", Number: 7}}, since)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 2 || got[0].Check != "build-4" || got[0].Built.Key != "r1:2" || got[1].Check != "build-1" ||
+		got[1].Pull.Number != 7 {
+		t.Fatalf("read %+v", got)
+	}
+}

internal/link/enrolment.go

@@ -11,6 +11,7 @@ import (
 	"fmt"
 	"log"
 	"sort"
+	"strings"
 	"time"
 
 	"github.com/novox/mesh-controller/internal/broker"
@@ -418,6 +419,12 @@ func (e Enrolment) Heard(ctx context.Context, report Report) (news bool, err err
 	for id, why := range report.Failed {
 		doing.Failed = append(doing.Failed, inventory.FailedResource{ID: id, Error: why})
 	}
+	// And a container left running because it said busy, or replaced after it waited (novox/hq ADR 0335):
+	// kept with the account, for the walk whose first-machine gate waits on it.
+	for _, b := range report.Busy {
+		doing.Busy = append(doing.Busy, inventory.BusyWait{ID: b.ID, Container: b.Container, State: b.State,
+			Since: b.Since, Until: b.Until, Said: b.Said})
+	}
 	// Ordered, so two readings of one failure are the same reading.
 	sort.Slice(doing.Failed, func(i, j int) bool { return doing.Failed[i].ID < doing.Failed[j].ID })
 
@@ -492,7 +499,22 @@ func (e Enrolment) Heard(ctx context.Context, report Report) (news bool, err err
 	}
 	// And how long the machine took, from the send to this first account of it (novox/hq to-be 45
 	// Phase 0): what the sent-not-reported bound will be set from. Said if lost, never a failure.
-	if err := e.Inventory.RecordApplyDuration(ctx, report.Node, report.Declared, doing.Outcome); err != nil {
+	//
+	// **A wait for a busy container is its own measure** (novox/hq ADR 0335): the first report that says one
+	// waits is the machine's answer, kept as its apply with the detail ApplyBusy; the report that says the
+	// container replaced ends the wait, kept as a `busy-wait` of the same send — so the apply's time holds no
+	// busy time, and the walk reads the machine as answered and waiting, never as silent.
+	outcome := doing.Outcome
+	if doing.Waiting() {
+		outcome = inventory.ApplyBusy
+		log.Printf("%s applied declaration %s and leaves a busy container running until it says idle: %s",
+			report.Node, short(report.Declared), busyWords(doing.Busy))
+	} else if replacedAfterWaiting(doing.Busy) {
+		if err := e.Inventory.RecordBusyDuration(ctx, report.Node, report.Declared); err != nil {
+			log.Printf("how long %s waited for a busy container could not be recorded: %v", report.Node, err)
+		}
+	}
+	if err := e.Inventory.RecordApplyDuration(ctx, report.Node, report.Declared, outcome); err != nil {
 		log.Printf("how long %s took to apply could not be recorded: %v", report.Node, err)
 	}
 
@@ -504,3 +526,25 @@ func (e Enrolment) Heard(ctx context.Context, report Report) (news bool, err err
 	}
 	return news, e.Inventory.RecordOwned(ctx, node.ID, report.Applied)
 }
+
+// busyWords is every container waiting because it said busy, in a line (novox/hq ADR 0335).
+func busyWords(busy []inventory.BusyWait) string {
+	var out []string
+	for _, b := range busy {
+		if b.State == inventory.BusyWaiting {
+			out = append(out, fmt.Sprintf("%s since %s, at the latest until %s", b.Container,
+				b.Since.UTC().Format(time.RFC3339), b.Until.UTC().Format(time.RFC3339)))
+		}
+	}
+	return strings.Join(out, "; ")
+}
+
+// replacedAfterWaiting says a report replaced a container that had waited because it was busy.
+func replacedAfterWaiting(busy []inventory.BusyWait) bool {
+	for _, b := range busy {
+		if b.State != inventory.BusyWaiting {
+			return true
+		}
+	}
+	return false
+}

internal/link/events.go

@@ -290,6 +290,9 @@ type Checked struct {
 	Trunk  string            `json:"trunk,omitempty"`
 	Beside map[string]string `json:"beside,omitempty"`
 	Took   string            `json:"took,omitempty"`
+	// Built are the builds the check made for its merge, each with its reuse key and digests, or why not
+	// (novox/hq ADR 0350 §1): what the walk of the merge takes instead of building.
+	Built []CheckBuilt `json:"built,omitempty"`
 }
 
 // CheckedMember is one head a group's composed check judged, and the trunk commit it was merged into (novox/hq

internal/link/protocol.go

@@ -272,6 +272,12 @@ type Report struct {
 	// `witness` and `not-reversible` are sent only to a machine whose report carries it.
 	Witness int `json:"witness,omitempty"`
 
+	// Busy is every container the reporting apply left running because it said busy, and every one it
+	// replaced after it had waited (novox/hq ADR 0335; mesh-host internal/link/messages.go): a walk's
+	// first-machine gate waits while its module's container is listed waiting, and starts at the report
+	// that no longer lists it so. Absent from an engine older than BusyContract, which never waits.
+	Busy []Busy `json:"busy,omitempty"`
+
 	// Health is the machine's word on every long-running resource it runs for a module (novox/hq ADR
 	// 0240, to-be 48 §4; mesh-host's internal/liveness): its state, since when, its failing streak and
 	// the restarts its node-engine counted. **Absent from an engine older than the judging**, which is
@@ -436,6 +442,31 @@ const ReadinessContract = 2
 // parses strictly and would refuse the whole declaration for it.
 const RootContract = 3
 
+// BusyContract is the statement of an engine that also reads a container's `busy` (novox/hq ADR 0335): it asks
+// a container that declares it before replacing it and says the wait in its report. Only to such an engine is
+// the field sent: an older one parses strictly and would refuse the whole declaration for it. The same number as
+// mesh-host internal/link/messages.go's BusyContract.
+const BusyContract = 8
+
+// The states of a busy container in a report (novox/hq ADR 0335 §2, §3).
+const (
+	BusyWaiting         = "waiting"
+	BusyReplacedIdle    = "replaced-when-idle"
+	BusyReplacedAtBound = "replaced-at-bound"
+)
+
+// Busy is one container a busy command held, as a node-engine reports it (novox/hq ADR 0335). ID is the
+// resource's id, `<module>.<resource>`; Since when the first apply that would have replaced it ran, Until when
+// the engine's bound replaces it at the latest, Said the last output of its busy command.
+type Busy struct {
+	ID        string    `json:"id"`
+	Container string    `json:"container"`
+	State     string    `json:"state"`
+	Since     time.Time `json:"since"`
+	Until     time.Time `json:"until"`
+	Said      string    `json:"said,omitempty"`
+}
+
 // ReasonRoot starts the reason of an account verdict that found a way to root (ADR 0266); the node-engine's
 // own words (mesh-host internal/accounts ReasonRoot).
 const ReasonRoot = "can become root without a person"

internal/link/queue.go

@@ -364,6 +364,64 @@ func ReadBuildEvents(ctx context.Context, js *broker.JetStream, seat string, sin
 	return heard, nil
 }
 
+// ReadCheckBuilds is every build the seat's checks of those pull requests said they made for their merges since a
+// moment (novox/hq ADR 0350 §2): read from the seat's own outcomes on the events stream, which only its holders may
+// publish, never from the artifact store. Newest first.
+func ReadCheckBuilds(ctx context.Context, js *broker.JetStream, seat string, pulls []PullRef, since time.Time) ([]CheckedBuild, error) {
+	if len(pulls) == 0 {
+		return nil, nil
+	}
+	wanted := map[PullRef]bool{}
+	for _, p := range pulls {
+		wanted[p] = true
+	}
+	subject := BuildOutcomeOf(seat)
+	sub, err := js.Context().PullSubscribe(subject, "",
+		nats.BindStream(broker.EventsStream), nats.StartTime(since), nats.AckNone())
+	if err != nil {
+		return nil, fmt.Errorf("cannot read %s from the bus: %w", subject, err)
+	}
+	defer func() { _ = sub.Unsubscribe() }()
+	info, err := sub.ConsumerInfo()
+	if err != nil {
+		return nil, fmt.Errorf("cannot read %s from the bus: %w", subject, err)
+	}
+	var out []CheckedBuild
+	for remaining := info.NumPending; remaining > 0; {
+		batch, err := sub.Fetch(int(min(remaining, 500)), nats.MaxWait(2*time.Second))
+		if err != nil && !errors.Is(err, nats.ErrTimeout) && !errors.Is(err, context.DeadlineExceeded) {
+			return nil, fmt.Errorf("reading %s: %w", subject, err)
+		}
+		if len(batch) == 0 {
+			break
+		}
+		remaining -= uint64(len(batch))
+		for _, msg := range batch {
+			var r BuildResult
+			if json.Unmarshal(msg.Data, &r) != nil || r.Checked == nil || r.Check == nil || r.Failed != "" {
+				continue
+			}
+			pull := PullRef{Owner: r.Checked.Owner, Repo: r.Checked.Repo, Number: r.Checked.Number}
+			if !wanted[pull] {
+				continue
+			}
+			for _, b := range r.Check.Built {
+				if b.NotBuilt == "" && b.Key != "" {
+					out = append(out, CheckedBuild{Pull: pull, Check: r.ID, Built: b})
+				}
+			}
+		}
+		if ctx.Err() != nil {
+			return nil, ctx.Err()
+		}
+	}
+	// Newest first: the stream's order is the order they were said.
+	for i, j := 0, len(out)-1; i < j; i, j = i+1, j-1 {
+		out[i], out[j] = out[j], out[i]
+	}
+	return out, nil
+}
+
 // --- the cancelled set ----------------------------------------------------------------------
 
 // safeKey is an id that can be a key, and a subject token, as it is: a build id, never a pattern.

internal/outward/outward.go

@@ -80,6 +80,57 @@ func Check(text string, machines ...string) (Refusal, bool) {
 		return Refusal{"address", "a hardware address"}, false
 	case reIPv6.MatchString(text):
 		return Refusal{"address", "an IPv6 address"}, false
+	}
+	if refusal, ok := secretShape(text); !ok {
+		return refusal, false
+	}
+	if reWinPath.MatchString(text) {
+		return Refusal{"path", "a drive path"}, false
+	}
+	if refusal, ok := randomRun(text); !ok {
+		return refusal, false
+	}
+	for _, word := range strings.FieldsFunc(text, isSeparator) {
+		w := strings.TrimRight(word, ".:!?")
+		if isPath(w) {
+			return Refusal{"path", "a file path"}, false
+		}
+		if isHostName(w) {
+			return Refusal{"address", "a host name"}, false
+		}
+	}
+	return Refusal{}, true
+}
+
+// Secret says whether a text carries a secret's shape, the one class that leaves the mesh nowhere — the
+// messenger's CheckSecret, one for one. It is what an ask's whole words (asks.Ask.Whole, novox/hq issue 383)
+// are held to: on a channel that proves who answers, a path or an address is what the operator approves and
+// is shown; a secret never is. A path is read as one: a run with a slash in it is judged piece by piece
+// between the slashes, so "/mnt/Photos_2024/Jochen" is a path and not a random string (the review of
+// 2026-10-10); the named shapes hold whatever the run holds.
+func Secret(text string, machines ...string) (Refusal, bool) {
+	text = withoutMachines(text, machines)
+	if refusal, ok := secretShape(text); !ok {
+		return refusal, false
+	}
+	return randomRunOutsidePaths(text)
+}
+
+// randomRunOutsidePaths is randomRun with each run that holds a slash judged by its pieces between the slashes.
+func randomRunOutsidePaths(text string) (Refusal, bool) {
+	for _, run := range reRun.FindAllString(text, -1) {
+		for _, piece := range strings.Split(run, "/") {
+			if len(piece) >= 20 && looksRandom(piece) {
+				return Refusal{"secret", "a long random-looking string"}, false
+			}
+		}
+	}
+	return Refusal{}, true
+}
+
+// secretShape is the secret shapes a pattern names.
+func secretShape(text string) (Refusal, bool) {
+	switch {
 	case rePEM.MatchString(text):
 		return Refusal{"secret", "a key block"}, false
 	case reJWT.MatchString(text):
@@ -92,23 +143,17 @@ func Check(text string, machines ...string) (Refusal, bool) {
 		return Refusal{"secret", "a value given to a secret's name"}, false
 	case reHex.MatchString(text):
 		return Refusal{"secret", "a long hexadecimal string"}, false
-	case reWinPath.MatchString(text):
-		return Refusal{"path", "a drive path"}, false
 	}
+	return Refusal{}, true
+}
+
+// randomRun is a long unbroken run of characters spread as a random string's are.
+func randomRun(text string) (Refusal, bool) {
 	for _, run := range reRun.FindAllString(text, -1) {
 		if looksRandom(run) {
 			return Refusal{"secret", "a long random-looking string"}, false
 		}
 	}
-	for _, word := range strings.FieldsFunc(text, isSeparator) {
-		w := strings.TrimRight(word, ".:!?")
-		if isPath(w) {
-			return Refusal{"path", "a file path"}, false
-		}
-		if isHostName(w) {
-			return Refusal{"address", "a host name"}, false
-		}
-	}
 	return Refusal{}, true
 }
 

internal/outward/outward_test.go

@@ -86,3 +86,40 @@ func TestScrubAlwaysGivesWhatMayLeave(t *testing.T) {
 		t.Errorf("a text that passes was changed: %q", got)
 	}
 }
+
+// Secret is the one class that leaves the mesh nowhere (novox/hq issue 383): it refuses every secret's shape
+// Check refuses, and nothing Check refuses as an address or a path — those an ask's whole words may carry.
+func TestSecretRefusesOnlyASecretsShape(t *testing.T) {
+	for _, text := range []string{
+		"-----BEGIN RSA PRIVATE KEY-----",
+		"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.abc",
+		"123456789:ABCdefGHIjklMNOpqrSTUvwxYZ0123456789ab",
+		"ghp_abcdefghijklmnopqrstuvwxyz0123456789",
+		"password=hunter2",
+		"0123456789abcdef0123456789abcdef",
+		"a key xK9mQ2vL8pR4tW7yB3nF6hJ1dG5sA0zC",
+	} {
+		r, ok := Secret(text)
+		if ok || r.Class != "secret" {
+			t.Errorf("not refused as a secret: %q (%s)", text, r)
+		}
+	}
+	for _, text := range []string{
+		"recalbox=smb://nas.lan/recalbox@/mnt/recalbox:ro",
+		"library=/mnt/library",
+		"photos=/mnt/Photos_2024/Jochen",
+		"games=smb://nas.lan/Recalbox_Games2024",
+		"/srv/media/Series_Archive/Season01",
+		"10.77.0.9:53",
+		"jochen@example.com",
+		"C:\\Users\\jo",
+		"anchor and the laptop",
+	} {
+		if r, ok := Secret(text, "anchor"); !ok {
+			t.Errorf("refused as %s: %q", r, text)
+		}
+		if _, ok := Check(text, "anchor"); ok && text != "anchor and the laptop" {
+			t.Errorf("Check lets %q leave, so Secret is not the narrower rule", text)
+		}
+	}
+}