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"))