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>

cmd/mesh-builder/main.go

@@ -24,6 +24,7 @@ import (
 	"net/url"
 	"os"
 	"os/signal"
+	"path/filepath"
 	"sort"
 	"strings"
 	"syscall"
@@ -313,6 +314,9 @@ func answer(ctx context.Context, publisher builder.Publisher, on, workspace stri
 			registry = r.Address
 		}
 		spec := checkSpecOf(request)
+		// A release branch's judge is kept beside the workspace, never in it: the check's containers mount the
+		// workspace, and a pull request's script must not plant the judge of the next check (novox/hq ADR 0358 §2).
+		spec.JudgeCache = judgeCacheOf(workspace)
 		// 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
@@ -326,7 +330,8 @@ func answer(ctx context.Context, publisher builder.Publisher, on, workspace stri
 		if err == nil {
 			result.Check = &link.CheckOutcome{Verdict: v.Verdict, Summary: v.Summary, Report: v.Report,
 				Took: v.Took.Round(time.Second).String(), Gate: layerOf(v.Gate), RepoCheck: layerOf(v.Repo),
-				Head: v.Head, Trunk: v.Trunk, Beside: v.Beside, Built: checkBuiltOf(v.Built)}
+				Head: v.Head, Trunk: v.Trunk, Beside: v.Beside, Built: checkBuiltOf(v.Built),
+				Release: v.Release, JudgedBy: v.JudgedBy, BesideAt: v.BesideAt}
 			// 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,
@@ -456,9 +461,9 @@ func checkSpecOf(request link.BuildRequest) builder.CheckSpec {
 		Owner: c.Owner, Repo: c.Repo, Number: c.Number, Paths: c.Paths, Beside: map[string]builder.Beside{},
 		Modules: c.Modules, New: c.New, Manifests: c.Manifests, Judge: c.Judge, Base: c.Base,
 		Toolchain: builder.ToolchainOf(request.Held), Toolchains: builder.ToolchainsOf(request.Held),
-		Tests: c.Tests, StoreOnly: c.StoreOnly}
+		Tests: c.Tests, StoreOnly: c.StoreOnly, Release: c.Release}
 	for dir, b := range c.Beside {
-		spec.Beside[dir] = builder.Beside{Repository: b.Repository, Ref: b.Ref}
+		spec.Beside[dir] = builder.Beside{Repository: b.Repository, Ref: b.Ref, Else: b.Else}
 	}
 	for _, b := range c.Builds {
 		spec.Builds = append(spec.Builds, builder.CheckBuildSpec{Module: b.Module, Repository: b.Repository, Path: b.Path,
@@ -471,6 +476,12 @@ func checkSpecOf(request link.BuildRequest) builder.CheckSpec {
 	return spec
 }
 
+// judgeCacheOf is where a release branch's judge is kept (novox/hq ADR 0358 §2): beside the workspace, outside what
+// a check's containers mount.
+func judgeCacheOf(workspace string) string {
+	return filepath.Clean(workspace) + "-judges"
+}
+
 // triedOf is a try's outcome as its log line says it (novox/hq issue 686): the repository's own check's verdict,
 // or the check's where that did not run — a head that does not merge — and the lines naming what failed.
 func triedOf(v builder.CheckVerdict) link.Tried {

cmd/mesh-builder/release_test.go

@@ -0,0 +1,26 @@
+package main
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// **A pull request into a release branch reaches the check as one** (novox/hq ADR 0358): the build seat hands the
+// check the release branch and, beside it, the trunk each repository is read at when it has no branch of that name;
+// and it keeps the release branch's judge outside the workspace a check's containers mount.
+func TestTheBuildSeatHandsTheCheckItsReleaseBranch(t *testing.T) {
+	spec := checkSpecOf(link.BuildRequest{ID: "b", Repository: "r", Ref: "abc", Check: &link.CheckRequest{
+		Owner: "novox", Repo: "mesh-catalog", Base: "feat/57", Release: "feat/57",
+		Beside: map[string]link.CheckedOut{"mesh-host": {Repository: "h", Ref: "feat/57", Else: "main"}}}})
+	if spec.Release != "feat/57" || spec.Beside["mesh-host"].Ref != "feat/57" || spec.Beside["mesh-host"].Else != "main" {
+		t.Fatalf("the check was handed release %q and mesh-host %+v", spec.Release, spec.Beside["mesh-host"])
+	}
+	workspace := filepath.Join(t.TempDir(), "mesh-builder")
+	cache := judgeCacheOf(workspace)
+	if rel, err := filepath.Rel(workspace, cache); err != nil || !strings.HasPrefix(rel, "..") {
+		t.Fatalf("the judge cache %s lies inside the workspace %s, which a check's containers mount", cache, workspace)
+	}
+}

cmd/mesh-controller/checks.go

@@ -3,6 +3,7 @@ package main
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"path"
 	"regexp"
@@ -248,30 +249,14 @@ func checkRequestFor(ctx context.Context, open *stores, p link.PullUpdated, scop
 	if err != nil {
 		return link.BuildRequest{}, err
 	}
-	// Beside it, at what the mesh runs: each core repository by the module the mesh builds from it.
-	beside := map[string]link.CheckedOut{}
-	for _, e := range entries {
-		dir, core := coreModules[e.Manifest.Module]
-		if !core || e.Provided || e.Source.Repository == "" {
-			continue
-		}
-		url, err := clone(e.Source)
-		if err != nil {
-			return link.BuildRequest{}, err
-		}
-		refs := besideRefs(dir, current[e.Manifest.Module].Commit)
-		beside[dir] = link.CheckedOut{Repository: url, Ref: refs[dir]}
-		if dir == "mesh-controller" {
-			beside["mesh-controller-main"] = link.CheckedOut{Repository: url, Ref: refs["mesh-controller-main"]}
-			if e.Source.Seat != "" {
-				for _, sibling := range []string{"mesh-lab", "mesh-sdk"} {
-					if url, err := clone(inventory.Source{Seat: e.Source.Seat, Repository: siblingOf(e.Source.Repository,
-						sibling)}); err == nil {
-						beside[sibling] = link.CheckedOut{Repository: url, Ref: refs[sibling]}
-					}
-				}
-			}
-		}
+	// **A pull request into a release branch is judged by that branch** (novox/hq ADR 0358): asked of the forge once.
+	release, err := releaseBranchOf(ctx, p, scope, entries)
+	if err != nil {
+		return link.BuildRequest{}, err
+	}
+	beside, err := besideOf(entries, func(module string) string { return current[module].Commit }, clone, release)
+	if err != nil {
+		return link.BuildRequest{}, err
 	}
 	builds := checkBuildsOf(p, scope, entries, clone)
 	return link.BuildRequest{
@@ -283,10 +268,142 @@ 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, Builds: builds, Named: namedForTheCheck(ctx, p, builds)},
+			Manifests: scope.Manifests, Judge: scope.Judge, Builds: builds, Named: namedForTheCheck(ctx, p, builds),
+			Release: release},
 	}, nil
 }
 
+// besideOf is what a check reads beside its own repository, by the directory it is found under: each core repository
+// by the module the mesh builds from it, at besideRefs — or, for a pull request into a release branch (novox/hq ADR
+// 0358 §3), at its branch of that name where it has one and at its trunk otherwise, the controller's main kept for
+// its judge. running is the commit the mesh runs of a module.
+func besideOf(entries []inventory.Entry, running func(module string) string,
+	clone func(inventory.Source) (string, error), release string) (map[string]link.CheckedOut, error) {
+	beside := map[string]link.CheckedOut{}
+	for _, e := range entries {
+		dir, core := coreModules[e.Manifest.Module]
+		if !core || e.Provided || e.Source.Repository == "" {
+			continue
+		}
+		url, err := clone(e.Source)
+		if err != nil {
+			return nil, err
+		}
+		refs := besideRefs(dir, running(e.Manifest.Module))
+		at := func(dir, trunk string) link.CheckedOut {
+			if release == "" {
+				return link.CheckedOut{Repository: url, Ref: refs[dir]}
+			}
+			if trunk == "" {
+				trunk = "main"
+			}
+			return link.CheckedOut{Repository: url, Ref: release, Else: trunk}
+		}
+		beside[dir] = at(dir, followedBranch(e.Source.Ref))
+		if dir == "mesh-controller" {
+			// The controller's main stays its main: it judges only a check the running controller predates.
+			beside["mesh-controller-main"] = link.CheckedOut{Repository: url, Ref: refs["mesh-controller-main"]}
+			if release != "" {
+				// mesh-controller has the release branch: that is what makes it one (ADR 0358 §1).
+				beside[dir] = link.CheckedOut{Repository: url, Ref: release}
+			}
+			if e.Source.Seat != "" {
+				for _, sibling := range []string{"mesh-lab", "mesh-sdk"} {
+					if url, err := clone(inventory.Source{Seat: e.Source.Seat, Repository: siblingOf(e.Source.Repository,
+						sibling)}); err == nil {
+						b := link.CheckedOut{Repository: url, Ref: refs[sibling]}
+						if release != "" {
+							b = link.CheckedOut{Repository: url, Ref: release, Else: "main"}
+						}
+						beside[sibling] = b
+					}
+				}
+			}
+		}
+	}
+	return beside, nil
+}
+
+// releaseBranchOf is the release branch a pull request merges into (novox/hq ADR 0358 §1): its base, when that is not
+// its repository's trunk and mesh-controller has a branch of that name; empty otherwise, and the pull request is
+// checked as before it. **A base that is a trunk asks nothing**: main, the branch a module built from the repository
+// follows, or mesh-controller's own trunk. Any other base is asked of the forge once, and an answer it cannot give is
+// an error, never read as "no release branch".
+func releaseBranchOf(ctx context.Context, p link.PullUpdated, scope checkScope, entries []inventory.Entry) (string, error) {
+	base := p.Base
+	if base == "" || base == "main" {
+		return "", nil
+	}
+	if scope.From != nil && base == followedBranch(scope.From.Source.Ref) {
+		return "", nil
+	}
+	var controller *inventory.Entry
+	for i, e := range entries {
+		if e.Manifest.Module == "mesh-controller" && !e.Provided && e.Source.Repository != "" {
+			controller = &entries[i]
+			break
+		}
+	}
+	if controller == nil || base == followedBranch(controller.Source.Ref) {
+		return "", nil
+	}
+	if !tryRef.MatchString(base) || strings.Contains(base, "..") {
+		return "", nil // no branch the forge could hold: checked as before
+	}
+	owner, repo := sourceOwner(controller.Source.Repository), sourceName(controller.Source.Repository)
+	if owner == "" || repo == "" {
+		return "", nil
+	}
+	has, err := forgeHasBranch(ctx, owner, repo, base)
+	if err != nil {
+		return "", fmt.Errorf("whether %s/%s#%d merges into a release branch cannot be told — the forge did not say "+
+			"whether %s/%s has a branch %s (novox/hq ADR 0358): %w", p.Owner, p.Repo, p.Number, owner, repo, base, err)
+	}
+	if !has {
+		return "", nil
+	}
+	return base, nil
+}
+
+// sourceName is the name of a recorded repository, a path on the git seat or a URL: novox/mesh-host → mesh-host.
+func sourceName(repository string) string {
+	parts := strings.Split(strings.Trim(strings.TrimSuffix(repository, ".git"), "/"), "/")
+	if len(parts) < 2 {
+		return ""
+	}
+	return parts[len(parts)-1]
+}
+
+// forgeHasBranch asks the forge, through its module's tools on the bus, whether a repository has a branch. A
+// variable so a test needs no forge.
+var forgeHasBranch = func(ctx context.Context, owner, repo, branch string) (bool, error) {
+	js, err := aBus()
+	if err != nil {
+		return false, err
+	}
+	defer js.Close()
+	raw, _ := json.Marshal(map[string]any{"path": "/repos/" + owner + "/" + repo + "/branches/" + branch})
+	answer, err := link.Ask(ctx, link.OverNATS{Conn: js.Conn()}, "gitea", "gitea_api", raw, 30*time.Second)
+	if err != nil {
+		return false, err
+	}
+	if answer.Error != "" {
+		if strings.Contains(answer.Error, " 404 ") {
+			return false, nil
+		}
+		return false, errors.New(answer.Error)
+	}
+	var found struct {
+		Result struct {
+			Name string `json:"name"`
+		} `json:"result"`
+	}
+	if err := json.Unmarshal(answer.Result, &found); err != nil {
+		return false, err
+	}
+	return found.Result.Name == branch, nil
+}
+
 // namedForTheCheck are the builds earlier checks of the same pull request at the same head named, read once for the
 // check (novox/hq issue 703): asked again because only the trunk moved, the check keeps what they built of a key
 // still the same. Another pull request's build, or one of an earlier head, is never kept. None when they cannot be
@@ -458,6 +575,7 @@ func checkedOf(result link.BuildResult) link.Checked {
 		// repositories read beside it.
 		c.Trunk, c.Beside, c.Took = result.Check.Trunk, result.Check.Beside, result.Check.Took
 		c.Built = result.Check.Built
+		c.Release, c.JudgedBy, c.BesideAt = result.Check.Release, result.Check.JudgedBy, result.Check.BesideAt
 		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/release_branch_test.go

@@ -0,0 +1,167 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/inventory"
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// **A pull request into a release branch is judged by that branch** (novox/hq ADR 0358, issue 704): a base that is
+// not its repository's trunk, where mesh-controller has a branch of that name, is a release branch; the check then
+// reads every repository beside it at its branch of that name where it has one, else at its trunk. Any other base is
+// checked exactly as before.
+
+const aRelease = "feat/57-config-and-provisioning"
+
+// theCore is the mesh's core as a check reads it beside: the controller, the node-engine, the tool runner and the
+// catalogue's bus, on the git seat.
+func theCore() []inventory.Entry {
+	onSeat := func(module, repository string) inventory.Entry {
+		e := fromRepo(module, repository, "")
+		e.Source.Seat = "git"
+		return e
+	}
+	nats := onSeat("nats", "novox/mesh-catalog")
+	nats.Source.Path = "modules/nats"
+	return []inventory.Entry{onSeat("mesh-controller", "novox/mesh-controller"), onSeat("mesh-host", "novox/mesh-host"),
+		onSeat("node-tools", "novox/mesh-tools"), nats, onSeat("gitea", "novox/mesh-catalog")}
+}
+
+// aForgeWithBranches stands in for the forge: which branches each repository has, and how often it was asked.
+func aForgeWithBranches(t *testing.T, branches map[string][]string, failing error) *int {
+	t.Helper()
+	asked := 0
+	was := forgeHasBranch
+	t.Cleanup(func() { forgeHasBranch = was })
+	forgeHasBranch = func(_ context.Context, owner, repo, branch string) (bool, error) {
+		asked++
+		if failing != nil {
+			return false, failing
+		}
+		for _, b := range branches[owner+"/"+repo] {
+			if b == branch {
+				return true, nil
+			}
+		}
+		return false, nil
+	}
+	return &asked
+}
+
+func TestABaseIsAReleaseBranchWhenTheControllerHasABranchOfThatName(t *testing.T) {
+	entries := theCore()
+	scopeOf := func(p link.PullUpdated) checkScope { return pullScope(p, entries, nil, nil) }
+	pull := func(repo, base string) link.PullUpdated {
+		return link.PullUpdated{Owner: "novox", Repo: repo, Number: 286, Base: base, Commit: "abc",
+			Paths: []string{"modules/gitea/index.ts"}}
+	}
+
+	asked := aForgeWithBranches(t, map[string][]string{"novox/mesh-controller": {"main", aRelease}}, nil)
+	for _, c := range []struct {
+		what    string
+		p       link.PullUpdated
+		release string
+		asks    int
+	}{
+		{"a pull request into the trunk asks nothing and is no release", pull("mesh-catalog", "main"), "", 0},
+		{"a catalogue pull request into the release branch", pull("mesh-catalog", aRelease), aRelease, 1},
+		{"a controller pull request into the release branch", pull("mesh-controller", aRelease), aRelease, 1},
+		{"a base mesh-controller has no branch of is checked as today", pull("mesh-catalog", "feat/other"), "", 1},
+		{"no base: as today", pull("mesh-catalog", ""), "", 0},
+	} {
+		*asked = 0
+		got, err := releaseBranchOf(t.Context(), c.p, scopeOf(c.p), entries)
+		if err != nil {
+			t.Fatalf("%s: %v", c.what, err)
+		}
+		if got != c.release || *asked != c.asks {
+			t.Errorf("%s: release %q after %d question(s) to the forge, not %q after %d", c.what, got, *asked,
+				c.release, c.asks)
+		}
+	}
+
+	// The branch a module built from the repository follows is its trunk: never asked about.
+	photos := fromRepo("photos", "novox/photos", "")
+	photos.Source.Ref = "nox-mesh"
+	withPhotos := append(theCore(), photos)
+	p := link.PullUpdated{Owner: "novox", Repo: "photos", Base: "nox-mesh", Commit: "abc", Paths: []string{"x.js"}}
+	*asked = 0
+	if got, err := releaseBranchOf(t.Context(), p, pullScope(p, withPhotos, nil, nil), withPhotos); err != nil ||
+		got != "" || *asked != 0 {
+		t.Fatalf("a module's own trunk read as release %q (%v) after %d question(s)", got, err, *asked)
+	}
+
+	// A forge that cannot answer is an error, never "no release branch".
+	aForgeWithBranches(t, nil, errors.New("nothing serves gitea.gitea_api"))
+	q := pull("mesh-catalog", aRelease)
+	if _, err := releaseBranchOf(t.Context(), q, scopeOf(q), entries); err == nil ||
+		!strings.Contains(err.Error(), "cannot be told") {
+		t.Fatalf("an unanswered forge was read as an answer: %v", err)
+	}
+}
+
+func TestBesideAReleaseBranchCheckEachRepositoryIsReadAtThatBranchElseItsTrunk(t *testing.T) {
+	entries := theCore()
+	clone := func(s inventory.Source) (string, error) { return "http://git/" + s.Repository + ".git", nil }
+	running := func(module string) string { return "running-" + module }
+
+	beside, err := besideOf(entries, running, clone, aRelease)
+	if err != nil {
+		t.Fatal(err)
+	}
+	at := func(repo string, ref, orElse string) link.CheckedOut {
+		return link.CheckedOut{Repository: "http://git/novox/" + repo + ".git", Ref: ref, Else: orElse}
+	}
+	want := map[string]link.CheckedOut{
+		// The judge: mesh-controller's release branch, which it has.
+		"mesh-controller":      at("mesh-controller", aRelease, ""),
+		"mesh-controller-main": at("mesh-controller", "main", ""),
+		// A controller pull request into the release branch reads mesh-host at that branch where it has one.
+		"mesh-host":    at("mesh-host", aRelease, "main"),
+		"mesh-tools":   at("mesh-tools", aRelease, "main"),
+		"mesh-catalog": at("mesh-catalog", aRelease, "main"),
+		"mesh-lab":     at("mesh-lab", aRelease, "main"),
+		"mesh-sdk":     at("mesh-sdk", aRelease, "main"),
+	}
+	if !reflect.DeepEqual(beside, want) {
+		t.Fatalf("beside a release-branch check:\n got %v\nwant %v", beside, want)
+	}
+
+	// Any other base: exactly as before — what the mesh runs, the catalogue's and the lab's main.
+	beside, err = besideOf(entries, running, clone, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want = map[string]link.CheckedOut{
+		"mesh-controller":      at("mesh-controller", "running-mesh-controller", ""),
+		"mesh-controller-main": at("mesh-controller", "main", ""),
+		"mesh-host":            at("mesh-host", "running-mesh-host", ""),
+		"mesh-tools":           at("mesh-tools", "running-node-tools", ""),
+		"mesh-catalog":         at("mesh-catalog", "main", ""),
+		"mesh-lab":             at("mesh-lab", "main", ""),
+		"mesh-sdk":             at("mesh-sdk", sdkPinned(), ""),
+	}
+	if !reflect.DeepEqual(beside, want) {
+		t.Fatalf("beside a trunk check:\n got %v\nwant %v", beside, want)
+	}
+}
+
+func TestAReleaseBranchVerdictNamesTheBranchTheJudgeAndWhatItRead(t *testing.T) {
+	asked := &link.CheckRequest{Owner: "novox", Repo: "mesh-catalog", Number: 286, Base: aRelease, Release: aRelease}
+	c := checkedOf(link.BuildResult{ID: "b", Ref: "aaaaaaaaaaaa0000", Checked: asked, Check: &link.CheckOutcome{
+		Verdict: "pass", Head: "aaaaaaaaaaaa", Trunk: "111111111111", Gate: &link.CheckLayer{Verdict: "pass"},
+		RepoCheck: &link.CheckLayer{Verdict: "pass"}, Release: aRelease, JudgedBy: "fcdecb436117",
+		Beside:   map[string]string{"mesh-host": "222222222222", "mesh-lab": "333333333333"},
+		BesideAt: map[string]string{"mesh-host": aRelease, "mesh-lab": "main"}}})
+	if c.Release != aRelease || c.JudgedBy != "fcdecb436117" {
+		t.Fatalf("the verdict names release %q judged by %q", c.Release, c.JudgedBy)
+	}
+	if c.BesideAt["mesh-host"] != aRelease || c.BesideAt["mesh-lab"] != "main" || c.Beside["mesh-host"] != "222222222222" {
+		t.Fatalf("the verdict names what it read beside it as %v at %v", c.Beside, c.BesideAt)
+	}
+}