Judge a pull request into a release branch by that branch's controller and repositories

A release branch could never carry a change that needs another repository's
release-branch change: its pull requests were judged by the running controller
and against the other repositories' main (hq issue 704, ADR 0358).

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

internal/builder/check.go

@@ -13,6 +13,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"regexp"
+	"sort"
 	"strings"
 	"time"
 
@@ -87,6 +88,16 @@ type CheckSpec struct {
 	// Judge is who judges the gate: "" the controller the mesh runs, "self" the change's own, "validator"
 	// the running one with the change's validator.
 	Judge string
+	// Release is the release branch the pull request merges into (novox/hq ADR 0358), empty for any other base. The
+	// gate is then judged by the controller beside it as mesh-controller — mesh-controller's release branch, never
+	// the controller the mesh runs nor its main — with mesh-host's validator from beside it when mesh-host was read at
+	// the release branch too; a change to the controller still judges itself and a change to the node-engine brings
+	// its own validator. The verdict names the branch, the judge's commit and the branch each beside was read at.
+	Release string
+	// JudgeCache is a directory outside the workspace where a release branch's judge is kept by the commits it is
+	// built from, so it is built once per release-branch head (ADR 0358 §2). Outside: the check's containers mount
+	// the workspace and a pull request's own script must not plant a judge for the next check. Empty keeps none.
+	JudgeCache string
 	// Toolchain is the image a check's Go runs in: the mesh's own Go toolchain, as it holds it.
 	// Toolchains is every toolchain the mesh holds, by language, for a script that declares another.
 	Toolchain  string
@@ -153,10 +164,12 @@ func ToolchainsOf(held map[string]string) map[string]string {
 	return out
 }
 
-// Beside is one repository cloned next to the one checked.
+// Beside is one repository cloned next to the one checked: at Ref, or at Else when Else is said and the repository
+// has no branch Ref (novox/hq ADR 0358 §3).
 type Beside struct {
 	Repository string
 	Ref        string
+	Else       string
 }
 
 // CheckVerdict is what came of one check. Verdict and Summary are the gate's; Gate and Repo each layer.
@@ -179,6 +192,12 @@ type CheckVerdict struct {
 	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
+	// Release is the release branch it was judged for (novox/hq ADR 0358 §4), JudgedBy the commit of the controller
+	// that judged its gate (twelve characters), and BesideAt the branch each repository beside it was read at, by
+	// directory. Empty for a check of any other base.
+	Release  string
+	JudgedBy string
+	BesideAt map[string]string
 }
 
 // Layer is one layer of a check, judged.
@@ -303,13 +322,23 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 	if err := forgetLeftCredentials(workspace); err != nil {
 		return CheckVerdict{}, err
 	}
-	clone := func(repository, ref, dir string) error {
+	// cloneAt clones a repository and checks out ref — or, when the repository has no branch ref and orElse is said,
+	// orElse (novox/hq ADR 0358 §3); readAt keeps which, by directory.
+	readAt := map[string]string{}
+	cloneAt := func(repository, ref, orElse, dir string) error {
 		if _, err := run(ctx, root, "git", cloneWith(credentials, "clone", "--quiet", repository, dir)...); err != nil {
 			return fmt.Errorf("cannot clone %s: %s", redact.redact(repository), redact.redact(err.Error()))
 		}
 		if err := recordedWithoutUserinfo(ctx, run, filepath.Join(root, dir), repository); err != nil {
 			return err
 		}
+		if orElse != "" && ref != "" {
+			if _, err := run(ctx, filepath.Join(root, dir), "git", "rev-parse", "--verify", "--quiet",
+				"refs/remotes/origin/"+ref); err != nil {
+				ref = orElse
+			}
+		}
+		readAt[dir] = ref
 		if ref != "" {
 			if _, err := run(ctx, filepath.Join(root, dir), "git", "checkout", "--quiet", ref); err != nil {
 				return fmt.Errorf("%s has no %s: %w", redact.redact(repository), ref, err)
@@ -317,6 +346,9 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 		}
 		return nil
 	}
+	clone := func(repository, ref, dir string) error {
+		return cloneAt(repository, ref, "", dir)
+	}
 	name := spec.Repo
 	if name == "" || !safeName.MatchString(name) {
 		name = "checked"
@@ -352,6 +384,7 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 	}
 	named := func(v CheckVerdict) CheckVerdict {
 		v.Head, v.Trunk, v.Merge, v.Beside, v.Members = judged.Head, judged.Trunk, judged.Merge, judged.Beside, judged.Members
+		v.Release, v.JudgedBy, v.BesideAt = spec.Release, judged.JudgedBy, judged.BesideAt
 		return v
 	}
 	// **What the merge would move is built from a checkout nothing of the check touches** (novox/hq issue 703): the
@@ -392,9 +425,16 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 		if dir == name || !safeName.MatchString(dir) {
 			continue
 		}
-		if err := clone(b.Repository, b.Ref, dir); err != nil {
+		if err := cloneAt(b.Repository, b.Ref, b.Else, dir); err != nil {
 			return CheckVerdict{}, fmt.Errorf("beside it, %w", err)
 		}
+		if spec.Release != "" {
+			// The branch each was read at is named with its commit (ADR 0358 §4).
+			if judged.BesideAt == nil {
+				judged.BesideAt = map[string]string{}
+			}
+			judged.BesideAt[dir] = readAt[dir]
+		}
 		// The commit each one read is named in the verdict (ADR 0323 §3): its move is issue 568's question.
 		if at := headAt(ctx, run, filepath.Join(root, dir)); at != "" {
 			if judged.Beside == nil {
@@ -402,7 +442,7 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 			}
 			judged.Beside[dir] = at
 		}
-		say("check", "beside it %s at %s", dir, short(b.Ref))
+		say("check", "beside it %s at %s", dir, refWords(readAt[dir]))
 	}
 
 	// A delivery group's other heads (novox/hq ADR 0239), each at its head, for the gate to compose with this.
@@ -542,10 +582,21 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 
 	// The judge. Its failing to build is the change's fault when the change is the judge or its validator,
 	// and the check's when it is the controller the mesh runs.
-	gate, judgeFault, err := judgeFor(ctx, labelled, run, spec, root, tree, inToolchain, say)
+	gate, judgeFault, err := judgeFor(ctx, labelled, run, spec, root, tree, judged.BesideAt, inToolchain, say)
 	if err != nil {
 		return CheckVerdict{}, err
 	}
+	if spec.Release != "" {
+		// **A release-branch judgement says so** (novox/hq ADR 0358 §4): the branch, the controller's commit that
+		// judged, and each repository read beside it at its branch and commit.
+		judgedBy := filepath.Join(root, "mesh-controller")
+		if spec.Judge == "self" {
+			judgedBy = tree
+		}
+		judged.JudgedBy = headAt(ctx, run, judgedBy)
+		fmt.Fprintf(&out, "--- %s\n", releaseWords(spec.Release, judged.JudgedBy, judged.BesideAt, judged.Beside))
+		say("check", "%s", releaseWords(spec.Release, judged.JudgedBy, judged.BesideAt, judged.Beside))
+	}
 	verdictFile := filepath.Join(root, "verdict.json")
 	env := []string{EnvFacts + "=" + factsFile, EnvGate + "=" + gate, EnvGateStore + "=" + storeURL,
 		EnvTestStore + "=" + storeURL, EnvTestBus + "=nats://" + bus, EnvRepository + "=" + spec.Owner + "/" + spec.Repo,
@@ -611,6 +662,11 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 		}
 	}
 
+	if spec.Release != "" {
+		// The statuses name the release branch and the judge first, so the forge's short description keeps them.
+		mark := releaseMark(spec.Release, judged.JudgedBy)
+		v.Gate.Summary, v.Repo.Summary = mark+v.Gate.Summary, mark+v.Repo.Summary
+	}
 	// What the check printed travels in the verdict to the forge and the controller: redacted as the log is.
 	v.Gate.Summary, v.Repo.Summary, v.Repo.Failed = redact.redact(v.Gate.Summary), redact.redact(v.Repo.Summary),
 		redact.redact(v.Repo.Failed)
@@ -968,7 +1024,12 @@ func gateLayer(ctx context.Context, spec CheckSpec, tree, root, gate, verdictFil
 // the mesh runs. It answers the judge's path; or, when the change makes its own judge unbuildable, why —
 // the change's fault, a failing gate; or an error when the check cannot build a judge at all. A check
 // whose gate does not run builds a judge only to hand its scripts one, and goes on without when it cannot.
-func judgeFor(ctx context.Context, labelled, run Runner, spec CheckSpec, root, tree string,
+//
+// **A pull request into a release branch is judged by that branch's controller** (novox/hq ADR 0358 §2): the one
+// beside it as mesh-controller, read at the release branch — with mesh-host's validator from beside it when mesh-host
+// has that branch too, or with the change's own validator for a change to the node-engine — never the controller the
+// mesh runs. besideAt is the branch each repository beside it was read at.
+func judgeFor(ctx context.Context, labelled, run Runner, spec CheckSpec, root, tree string, besideAt map[string]string,
 	inToolchain func(string, []string, ...string) []string, say func(step, format string, args ...any)) (string, string, error) {
 	gated := spec.Gated()
 	switch spec.Judge {
@@ -982,7 +1043,14 @@ func judgeFor(ctx context.Context, labelled, run Runner, spec CheckSpec, root, t
 		say("check", "judged by the change's own controller")
 		return bin, "", nil
 	}
-	bin, judgeTree, err := judge(ctx, labelled, run, root, inToolchain, say)
+	var bin, judgeTree string
+	var err error
+	if spec.Release != "" {
+		withHost := spec.Judge != "validator" && besideAt["mesh-host"] == spec.Release
+		bin, judgeTree, err = releaseJudge(ctx, labelled, run, spec, root, withHost, inToolchain, say)
+	} else {
+		bin, judgeTree, err = judge(ctx, labelled, run, root, inToolchain, say)
+	}
 	if err != nil {
 		if !gated {
 			say("check", "no judge for its script: %v", err)
@@ -1004,12 +1072,181 @@ func judgeFor(ctx context.Context, labelled, run Runner, spec CheckSpec, root, t
 	if _, err := labelled(ctx, root, "docker", inToolchain(filepath.Join(root, judgeTree),
 		[]string{"CGO_ENABLED=0", "GOFLAGS=-mod=vendor", "GOPROXY=off", "GOCACHE=" + filepath.Join(filepath.Dir(root), "go-cache")},
 		"go", "build", "-o", withValidator, "./cmd/mesh-controller")...); err != nil {
+		if spec.Release != "" {
+			return "", spec.Release + "'s controller does not build with this change's validator: " +
+				firstLine(err.Error()), nil
+		}
 		return "", "the controller the mesh runs does not build with this change's validator: " + firstLine(err.Error()), nil
 	}
+	if spec.Release != "" {
+		say("check", "judged by %s's controller, with this change's validator", spec.Release)
+		return withValidator, "", nil
+	}
 	say("check", "judged by the controller the mesh runs, with this change's validator")
 	return withValidator, "", nil
 }
 
+// releaseJudge builds the controller that judges a pull request into a release branch (novox/hq ADR 0358 §2): the
+// one beside the check as mesh-controller, read at that branch — with mesh-host's validator from beside it in place
+// of the one it vendors when withHost. **Built once per release-branch head**: kept in the spec's judge cache by the
+// commits it is built from and taken from there while they stand. It answers the binary and the directory it was
+// built from.
+func releaseJudge(ctx context.Context, run, plain Runner, spec CheckSpec, root string, withHost bool,
+	inToolchain func(string, []string, ...string) []string, say func(step, format string, args ...any)) (string, string, error) {
+	const dir = "mesh-controller"
+	if _, err := os.Stat(filepath.Join(root, dir)); err != nil {
+		return "", "", fmt.Errorf("no controller of %s beside the check to judge it with", spec.Release)
+	}
+	key := fullHeadAt(ctx, plain, filepath.Join(root, dir))
+	if key == "" {
+		return "", "", fmt.Errorf("the controller of %s beside the check names no commit", spec.Release)
+	}
+	with := ""
+	if withHost {
+		host := fullHeadAt(ctx, plain, filepath.Join(root, "mesh-host"))
+		if host == "" {
+			return "", "", fmt.Errorf("mesh-host of %s beside the check names no commit", spec.Release)
+		}
+		key += "-with-mesh-host-" + host
+		with = ", with mesh-host's validator of " + spec.Release + " at " + twelve(host)
+	}
+	bin := filepath.Join(root, "bin", "mesh-controller")
+	if took := judgeKept(spec.JudgeCache, key, bin); took {
+		say("check", "judged by %s's controller at %s%s, built for an earlier check of that head", spec.Release,
+			twelve(key), with)
+		return bin, dir, nil
+	}
+	if withHost {
+		vendored := filepath.Join(root, dir, "vendor", "github.com", "novox", "mesh-host")
+		for _, pkg := range []string{"validate", filepath.Join("internal", "declaration")} {
+			if err := replaceGoFiles(filepath.Join(root, "mesh-host", pkg), filepath.Join(vendored, pkg)); err != nil {
+				return "", "", fmt.Errorf("mesh-host's validator of %s could not be put in its controller: %w", spec.Release, err)
+			}
+		}
+	}
+	if _, err := run(ctx, root, "docker", inToolchain(filepath.Join(root, dir),
+		[]string{"CGO_ENABLED=0", "GOFLAGS=-mod=vendor", "GOPROXY=off", "GOCACHE=" + filepath.Join(filepath.Dir(root), "go-cache")},
+		"go", "build", "-o", bin, "./cmd/mesh-controller")...); err != nil {
+		return "", "", fmt.Errorf("the controller of %s does not build%s: %w", spec.Release, with, err)
+	}
+	// Kept before anything of the change runs: nothing a pull request's script writes can reach the cache.
+	keepJudge(spec.JudgeCache, key, bin, say)
+	say("check", "judged by %s's controller at %s%s", spec.Release, twelve(key), with)
+	return bin, dir, nil
+}
+
+// judgesKept is how many release-branch judges a judge cache keeps: a head moved past is not built from again.
+const judgesKept = 4
+
+// judgeKept puts the judge kept under key in the cache at bin, and says whether there was one.
+func judgeKept(cache, key, bin string) bool {
+	if cache == "" {
+		return false
+	}
+	body, err := os.ReadFile(filepath.Join(cache, key, "mesh-controller"))
+	if err != nil {
+		return false
+	}
+	if err := os.MkdirAll(filepath.Dir(bin), 0o755); err != nil {
+		return false
+	}
+	if err := os.WriteFile(bin, body, 0o755); err != nil {
+		return false
+	}
+	now := time.Now()
+	_ = os.Chtimes(filepath.Join(cache, key), now, now)
+	return true
+}
+
+// keepJudge keeps a judge just built under key, and lets go of all but the judgesKept most recently used. A judge
+// that cannot be kept is said and built again next time: the cache only saves time.
+func keepJudge(cache, key, bin string, say func(step, format string, args ...any)) {
+	if cache == "" {
+		return
+	}
+	body, err := os.ReadFile(bin)
+	if err == nil {
+		err = os.MkdirAll(filepath.Join(cache, key), 0o755)
+	}
+	if err == nil {
+		kept := filepath.Join(cache, key, "mesh-controller")
+		if err = os.WriteFile(kept+".part", body, 0o755); err == nil {
+			err = os.Rename(kept+".part", kept)
+		}
+	}
+	if err != nil {
+		say("check", "the judge could not be kept for the next check, which builds it again: %v", err)
+		return
+	}
+	entries, err := os.ReadDir(cache)
+	if err != nil || len(entries) <= judgesKept {
+		return
+	}
+	type used struct {
+		name string
+		at   time.Time
+	}
+	var all []used
+	for _, e := range entries {
+		if info, err := e.Info(); err == nil && e.IsDir() {
+			all = append(all, used{e.Name(), info.ModTime()})
+		}
+	}
+	sort.Slice(all, func(i, j int) bool { return all[i].at.After(all[j].at) })
+	for _, u := range all[min(judgesKept, len(all)):] {
+		if u.name != key {
+			_ = os.RemoveAll(filepath.Join(cache, u.name))
+		}
+	}
+}
+
+// fullHeadAt is the whole commit a checkout stands at, empty when it names none.
+func fullHeadAt(ctx context.Context, run Runner, tree string) string {
+	out, err := run(ctx, tree, "git", "rev-parse", "--verify", "--quiet", "HEAD^{commit}")
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(out)
+}
+
+// releaseWords is how a release-branch check says what judged it and what it read (novox/hq ADR 0358 §4).
+func releaseWords(release, judgedBy string, at, commits map[string]string) string {
+	var read []string
+	for _, dir := range sortedKeys(at) {
+		read = append(read, fmt.Sprintf("%s %s at %s", dir, refWords(at[dir]), commits[dir]))
+	}
+	said := fmt.Sprintf("judged for the release branch %s by its controller at %s", release, judgedBy)
+	if len(read) > 0 {
+		said += "; read beside it: " + strings.Join(read, ", ")
+	}
+	return said
+}
+
+// releaseMark opens each layer's summary of a release-branch check, so a status says it first.
+func releaseMark(release, judgedBy string) string {
+	return fmt.Sprintf("[release %s, judged by its controller %s] ", release, judgedBy)
+}
+
+// refWords is a ref as a line says it: a commit by its first eight characters, a branch whole.
+func refWords(ref string) string {
+	if commitLike.MatchString(ref) {
+		return short(ref)
+	}
+	return ref
+}
+
+// commitLike is a ref that names a commit.
+var commitLike = regexp.MustCompile(`^[0-9a-f]{7,40}$`)
+
+func sortedKeys(m map[string]string) []string {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
 // replaceGoFiles puts a package's Go files — never its tests — in place of another copy's.
 func replaceGoFiles(from, into string) error {
 	old, err := filepath.Glob(filepath.Join(into, "*.go"))

internal/builder/release_branch_test.go

@@ -0,0 +1,308 @@
+package builder
+
+import (
+	"net"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// **A pull request into a release branch is judged by the controller of that branch** (novox/hq ADR 0358, issue
+// 704): the build seat's check builds the judge from mesh-controller read at the release branch — with mesh-host's
+// validator of that branch when mesh-host has one — reads every repository beside it at that branch where it has one
+// and at its trunk otherwise, and names the branch, the judge's commit and each repository read with its commit.
+
+const releaseBranch = "feat/57-config-and-provisioning"
+
+// gitInRepo runs git in a repository made for a test.
+func gitInRepo(t *testing.T, dir string, args ...string) string {
+	t.Helper()
+	cmd := exec.Command("git", args...)
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(), "GIT_AUTHOR_NAME=t", "GIT_AUTHOR_EMAIL=t@example.org",
+		"GIT_COMMITTER_NAME=t", "GIT_COMMITTER_EMAIL=t@example.org")
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("git %v: %v\n%s", args, err, out)
+	}
+	return strings.TrimSpace(string(out))
+}
+
+// commitFiles writes files into a repository and commits them on the branch checked out.
+func commitFiles(t *testing.T, dir string, files map[string]string) string {
+	t.Helper()
+	for name, body := range files {
+		if err := os.MkdirAll(filepath.Dir(filepath.Join(dir, name)), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	gitInRepo(t, dir, "add", "-A")
+	gitInRepo(t, dir, "commit", "--quiet", "-m", "x")
+	return gitInRepo(t, dir, "rev-parse", "HEAD")
+}
+
+// aRepositoryWithARelease is a repository whose main holds mainFiles and, when releaseFiles is not nil, a release
+// branch over them holding releaseFiles. It answers the repository, main's head and the release branch's head.
+func aRepositoryWithARelease(t *testing.T, mainFiles, releaseFiles map[string]string) (string, string, string) {
+	t.Helper()
+	dir := t.TempDir()
+	gitInRepo(t, dir, "init", "--quiet", "-b", "main")
+	main := commitFiles(t, dir, mainFiles)
+	if releaseFiles == nil {
+		return dir, main, ""
+	}
+	gitInRepo(t, dir, "checkout", "--quiet", "-b", releaseBranch)
+	head := commitFiles(t, dir, releaseFiles)
+	gitInRepo(t, dir, "checkout", "--quiet", "main")
+	return dir, main, head
+}
+
+// aJudgeOf is a controller that judges as told: its gate passes, saying who it is and the word of the node-engine
+// validator it vendors — the one it was built with.
+func aJudgeOf(who string) map[string]string {
+	return map[string]string{
+		"go.mod":             "module example.org/judge\n\ngo 1.22\n\nrequire github.com/novox/mesh-host v0.0.0\n",
+		"vendor/modules.txt": "# github.com/novox/mesh-host v0.0.0\n## explicit; go 1.22\ngithub.com/novox/mesh-host/validate\n",
+		"vendor/github.com/novox/mesh-host/validate/v.go":             "package validate\n\nconst Word = \"the vendored validator\"\n",
+		"vendor/github.com/novox/mesh-host/internal/declaration/d.go": "package declaration\n",
+		"cmd/mesh-controller/main.go": `package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/novox/mesh-host/validate"
+)
+
+func main() {
+	if len(os.Args) == 2 && os.Args[1] == "merge-gate" {
+		fmt.Println("usage: merge-gate --facts <file> --store <postgres>")
+		os.Exit(2)
+	}
+	fmt.Printf("{\"verdict\":\"pass\",\"summary\":\"%s with %s\"}\n", "` + who + `", validate.Word)
+}
+`,
+	}
+}
+
+// aHostSaying is the node-engine's validator, saying a word.
+func aHostSaying(word string) map[string]string {
+	return map[string]string{
+		"validate/v.go":                  "package validate\n\nconst Word = \"" + word + "\"\n",
+		"internal/declaration/d.go":      "package declaration\n",
+		"validate/v_test.go":             "package validate\n",
+		"internal/declaration/x_test.go": "package declaration\n",
+	}
+}
+
+// aRuntimeThatBuildsTheJudge puts a container runtime on PATH that runs every container's command on this machine,
+// in the directory and with the environment the check gives it — the judge's build too — and a store and a bus that
+// answer. It answers the file each `go` the check runs is written to.
+func aRuntimeThatBuildsTheJudge(t *testing.T) string {
+	t.Helper()
+	if _, err := exec.LookPath("go"); err != nil {
+		t.Skip("no Go toolchain on this machine to build a judge with")
+	}
+	bus, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { bus.Close() })
+	go func() {
+		for {
+			c, err := bus.Accept()
+			if err != nil {
+				return
+			}
+			c.Close()
+		}
+	}()
+	dir := t.TempDir()
+	built := filepath.Join(dir, "built")
+	runtime := `#!/bin/sh
+cmd="$1"; shift
+case "$cmd" in
+ps|rm|exec) exit 0 ;;
+port) echo "` + bus.Addr().String() + `"; exit 0 ;;
+run)
+  workdir=""; detached=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      -d) detached=1; shift ;;
+      --rm) shift ;;
+      --workdir) workdir="$2"; shift 2 ;;
+      --env) export "$2"; shift 2 ;;
+      --network|--volume|--user|--label|--name|-p|-e) shift 2 ;;
+      *) break ;;
+    esac
+  done
+  if [ -n "$detached" ]; then echo a-container; exit 0; fi
+  shift
+  if [ "$1" = go ]; then echo "$*" >> "` + built + `"; fi
+  cd "$workdir" && exec "$@" ;;
+esac
+exit 1
+`
+	if err := os.WriteFile(filepath.Join(dir, "docker"), []byte(runtime), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	t.Setenv("GOTOOLCHAIN", "local")
+	return built
+}
+
+// builds is how many times the check ran go to build a judge.
+func builds(t *testing.T, file string) int {
+	t.Helper()
+	body, err := os.ReadFile(file)
+	if err != nil {
+		return 0
+	}
+	return strings.Count(string(body), "go build")
+}
+
+// theReleasedMesh is the core beside a release-branch check: a controller whose main and release branch judge
+// differently, a node-engine with a validator of each, and a lab with no release branch.
+func theReleasedMesh(t *testing.T) (map[string]Beside, string, string, string) {
+	t.Helper()
+	controller, _, controllerRelease := aRepositoryWithARelease(t, aJudgeOf("main's controller"),
+		aJudgeOf("the release branch's controller"))
+	host, _, hostRelease := aRepositoryWithARelease(t, aHostSaying("main's validator"),
+		aHostSaying("the release branch's validator"))
+	lab, labMain, _ := aRepositoryWithARelease(t, map[string]string{"README": "the lab"}, nil)
+	return map[string]Beside{
+		"mesh-controller":      {Repository: controller, Ref: releaseBranch},
+		"mesh-controller-main": {Repository: controller, Ref: "main"},
+		"mesh-host":            {Repository: host, Ref: releaseBranch, Else: "main"},
+		"mesh-lab":             {Repository: lab, Ref: releaseBranch, Else: "main"},
+	}, controllerRelease, hostRelease, labMain
+}
+
+// aPullRequestInto is a repository whose pull request's head is cut from base, with a change.
+func aPullRequestInto(t *testing.T, files map[string]string, base string, change map[string]string) (string, string) {
+	t.Helper()
+	repo, _, _ := aRepositoryWithARelease(t, files, map[string]string{"released": "r"})
+	gitInRepo(t, repo, "checkout", "--quiet", "-b", "change", base)
+	head := commitFiles(t, repo, change)
+	gitInRepo(t, repo, "checkout", "--quiet", "main")
+	return repo, head
+}
+
+func TestACataloguePullRequestIntoAReleaseBranchIsJudgedByThatBranchsController(t *testing.T) {
+	built := aRuntimeThatBuildsTheJudge(t)
+	registry := aFactsRegistry(t)
+	beside, controllerRelease, hostRelease, labMain := theReleasedMesh(t)
+	catalogue, head := aPullRequestInto(t, map[string]string{"modules/gitea/module.json": `{"module":"gitea"}`,
+		CheckScript: "true\n"}, releaseBranch, map[string]string{"modules/gitea/index.ts": "x"})
+	cache := t.TempDir()
+	check := func(id string) CheckVerdict {
+		t.Helper()
+		v, err := Check(t.Context(), Command, CheckSpec{ID: id, Repository: catalogue, Ref: head, Owner: "novox",
+			Repo: "mesh-catalog", Number: 286, Base: releaseBranch, Release: releaseBranch, JudgeCache: cache,
+			Paths: []string{"modules/gitea/index.ts"}, Modules: []string{"gitea"}, Beside: beside, Toolchain: "golang"},
+			t.TempDir(), registry, GitCredential{}, nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return v
+	}
+	v := check("check-704-catalogue")
+	// The release branch's controller judged, with mesh-host's validator of the release branch.
+	if v.Gate == nil || v.Gate.Verdict != "pass" ||
+		!strings.HasSuffix(v.Gate.Summary, "the release branch's controller with the release branch's validator") {
+		t.Fatalf("the gate was not judged by the release branch's controller with its node-engine's validator: %+v\n%s",
+			v.Gate, v.Report)
+	}
+	// It names the release branch, the judge's commit, and each repository read beside it at its branch and commit.
+	mark := "[release " + releaseBranch + ", judged by its controller " + controllerRelease[:12] + "] "
+	if !strings.HasPrefix(v.Gate.Summary, mark) || !strings.HasPrefix(v.Repo.Summary, mark) {
+		t.Fatalf("the statuses do not name the release branch and its judge first:\n%s\n%s", v.Gate.Summary, v.Repo.Summary)
+	}
+	if v.Release != releaseBranch || v.JudgedBy != controllerRelease[:12] {
+		t.Fatalf("the verdict names release %q judged by %q, not %s by %s", v.Release, v.JudgedBy, releaseBranch,
+			controllerRelease[:12])
+	}
+	if v.BesideAt["mesh-host"] != releaseBranch || v.Beside["mesh-host"] != hostRelease[:12] {
+		t.Fatalf("mesh-host was read at %q (%s), not its release branch at %s", v.BesideAt["mesh-host"],
+			v.Beside["mesh-host"], hostRelease[:12])
+	}
+	// A repository with no release branch is read at its trunk, and says so.
+	if v.BesideAt["mesh-lab"] != "main" || v.Beside["mesh-lab"] != labMain[:12] {
+		t.Fatalf("the lab, with no release branch, was read at %q (%s), not main at %s", v.BesideAt["mesh-lab"],
+			v.Beside["mesh-lab"], labMain[:12])
+	}
+	if !strings.Contains(v.Report, "read beside it: ") || !strings.Contains(v.Report, "mesh-host "+releaseBranch+" at "+hostRelease[:12]) {
+		t.Fatalf("the report does not say what was read beside it:\n%s", v.Report)
+	}
+	if n := builds(t, built); n != 1 {
+		t.Fatalf("the judge was built %d times for one check", n)
+	}
+
+	// **Built once per release-branch head**: a second check while that head stands takes the judge kept.
+	v = check("check-704-catalogue-again")
+	if !strings.HasSuffix(v.Gate.Summary, "the release branch's controller with the release branch's validator") {
+		t.Fatalf("the kept judge did not judge: %+v\n%s", v.Gate, v.Report)
+	}
+	if n := builds(t, built); n != 1 {
+		t.Fatalf("the judge of the same release-branch head was built again: %d builds", n)
+	}
+}
+
+func TestAControllerPullRequestIntoAReleaseBranchReadsTheNodeEngineAtThatBranch(t *testing.T) {
+	aRuntimeThatBuildsTheJudge(t)
+	registry := aFactsRegistry(t)
+	beside, _, hostRelease, _ := theReleasedMesh(t)
+	delete(beside, "mesh-controller")
+	controller, head := aPullRequestInto(t, aJudgeOf("the change's controller"), releaseBranch,
+		map[string]string{"cmd/x.txt": "x"})
+	v, err := Check(t.Context(), Command, CheckSpec{ID: "check-704-controller", Repository: controller, Ref: head,
+		Owner: "novox", Repo: "mesh-controller", Number: 315, Base: releaseBranch, Release: releaseBranch,
+		JudgeCache: t.TempDir(), Paths: []string{"cmd/x.txt"}, Modules: []string{"mesh-controller"}, Judge: "self",
+		Beside: beside, Toolchain: "golang"}, t.TempDir(), registry, GitCredential{}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if v.Gate == nil || !strings.HasSuffix(v.Gate.Summary, "the change's controller with the vendored validator") {
+		t.Fatalf("a controller change into a release branch did not judge itself: %+v\n%s", v.Gate, v.Report)
+	}
+	if v.BesideAt["mesh-host"] != releaseBranch || v.Beside["mesh-host"] != hostRelease[:12] {
+		t.Fatalf("mesh-host was read beside it at %q (%s), not at the release branch's %s", v.BesideAt["mesh-host"],
+			v.Beside["mesh-host"], hostRelease[:12])
+	}
+	if v.Release != releaseBranch || v.JudgedBy == "" || v.JudgedBy != v.Merge[:12] {
+		t.Fatalf("the verdict names release %q judged by %q, not its own merge %s", v.Release, v.JudgedBy, v.Merge)
+	}
+}
+
+func TestAPullRequestIntoTheTrunkIsJudgedAsBefore(t *testing.T) {
+	aRuntimeThatBuildsTheJudge(t)
+	registry := aFactsRegistry(t)
+	controller, controllerMain, _ := aRepositoryWithARelease(t, aJudgeOf("main's controller"),
+		aJudgeOf("the release branch's controller"))
+	host, hostMain, _ := aRepositoryWithARelease(t, aHostSaying("main's validator"),
+		aHostSaying("the release branch's validator"))
+	catalogue, head := aPullRequestInto(t, map[string]string{"modules/gitea/module.json": `{"module":"gitea"}`,
+		CheckScript: "true\n"}, "main", map[string]string{"modules/gitea/index.ts": "x"})
+	v, err := Check(t.Context(), Command, CheckSpec{ID: "check-704-trunk", Repository: catalogue, Ref: head,
+		Owner: "novox", Repo: "mesh-catalog", Number: 1, Base: "main", JudgeCache: t.TempDir(),
+		Paths: []string{"modules/gitea/index.ts"}, Modules: []string{"gitea"}, Toolchain: "golang",
+		Beside: map[string]Beside{"mesh-controller": {Repository: controller, Ref: controllerMain},
+			"mesh-host": {Repository: host, Ref: hostMain}}}, t.TempDir(), registry, GitCredential{}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if v.Gate == nil || v.Gate.Summary != "main's controller with the vendored validator" {
+		t.Fatalf("a trunk pull request was not judged by the controller beside it as before: %+v\n%s", v.Gate, v.Report)
+	}
+	if v.Release != "" || v.JudgedBy != "" || v.BesideAt != nil || strings.Contains(v.Report, "release branch") {
+		t.Fatalf("a trunk pull request's verdict speaks of a release branch: %q %q %v", v.Release, v.JudgedBy, v.BesideAt)
+	}
+	if v.Beside["mesh-host"] != hostMain[:12] {
+		t.Fatalf("mesh-host was read at %s, not the commit asked %s", v.Beside["mesh-host"], hostMain[:12])
+	}
+}