Judge a pull request's head merged into its trunk, and name the trunk commit

A check judged the head alone, so two pull requests that each passed could break the trunk together (node-engine #66 on 2026-10-09), and a recheck after the trunk moved judged the same head again. The build seat now merges the head into the trunk's head in its own clone, never pushed, fails a head that does not merge cleanly naming the files, and the verdict names the head, the trunk commit and the commits read beside it, for the forge and mesh-delivery to weigh against the trunk's next move (novox/hq ADR 0323, issue 341).
2026-10-12 17:27:01 +02:00
parent 3cfc121670
commit 83a9cf6e3a
10 changed files with 633 additions and 14 deletions
@@ -49,8 +49,10 @@ import (
 //
 // One check:
 //
-//  1. clones the repository at the pull request's head, and beside it the repositories its check
-//     reads — the controller the mesh runs, the catalogue, the host, the lab — each at the ref asked;
+//  1. clones the repository at the pull request's head and **makes the merge of that head into the trunk's
+//     head**, the check's trunk commit, in its own clone (novox/hq ADR 0323, issue 341; check_merge.go): what
+//     is judged is what merging makes, never pushed. Beside it the repositories its check reads — the
+//     controller the mesh runs, the catalogue, the host, the lab — each at the ref asked;
 //  2. reads the facts snapshot the controller keeps, and with it **the versions the mesh runs**: the
 //     store a check's tests stand on is the store's own release, and the bus the bus's;
 //  3. raises a throwaway PostgreSQL and a throwaway bus of those versions, labelled with the ask so a
@@ -79,7 +81,8 @@ type CheckSpec struct {
 	Modules   []string
 	New       []string
 	Manifests []string
-	// Base is the branch the pull request merges into: what the gate compares the change against.
+	// Base is the branch the pull request merges into: what the gate compares the change against, and the trunk
+	// whose head the change is merged into before it is judged (novox/hq ADR 0323). Empty judges the head alone.
 	Base string
 	// 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.
@@ -104,6 +107,9 @@ type GroupHead struct {
 	Repository string
 	Ref        string
 	Paths      []string
+	// Base is the branch it merges into: the head is merged into that trunk's head before it is composed
+	// (novox/hq ADR 0323 §6). Empty composes the head alone, as a controller from before it asks.
+	Base string
 }

 // Gated is whether the change touches the mesh's graph, and so whether the gate runs.
@@ -139,6 +145,16 @@ type CheckVerdict struct {
 	Took    time.Duration
 	Gate    *Layer
 	Repo    *Layer
+	// Head and Trunk are what was judged (novox/hq ADR 0323 §3): the pull request's head merged into the trunk
+	// commit, each as twelve characters. Trunk is empty for a check asked with no trunk, which judged the head
+	// alone. Merge is the merge commit made for the check, whole: only checked, never pushed or registered.
+	Head, Trunk, Merge string
+	// Beside are the commits of the repositories the check read beside its own, by the directory each was
+	// cloned under, as twelve characters: named, not judged against (ADR 0323 §3, issue 568).
+	Beside map[string]string
+	// 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
 }

 // Layer is one layer of a check, judged.
@@ -281,6 +297,34 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 		return CheckVerdict{}, err
 	}
 	tree := filepath.Join(root, name)
+	// **What merging makes is judged, not the head** (novox/hq ADR 0323, issue 341): the head merged into the
+	// trunk's head as this clone found it, in this clone alone. A head that does not merge cleanly fails here.
+	judged := CheckVerdict{Head: twelve(spec.Ref)}
+	paths := spec.Paths
+	if spec.Base != "" {
+		m, err := mergeIntoTrunk(ctx, run, tree, spec.Base, spec.Ref)
+		if err != nil {
+			return CheckVerdict{}, err
+		}
+		judged.Head, judged.Trunk = twelve(m.Head), twelve(m.Trunk)
+		if len(m.Conflicts) > 0 {
+			said := conflictWords(m)
+			say("check", "%s", said)
+			return CheckVerdict{Verdict: "fail", Summary: said, Report: said, Took: time.Since(began),
+				Gate: &Layer{Verdict: "fail", Summary: said}, Repo: &Layer{Verdict: "fail", Summary: said},
+				Head: judged.Head, Trunk: judged.Trunk}, nil
+		}
+		judged.Merge = m.Merge
+		if changed := changedByMerge(ctx, run, tree, m); len(changed) > 0 {
+			paths = changed
+		}
+		say("check", "head %s merged into trunk %s (%s): the merge is judged, and never pushed", judged.Head,
+			judged.Trunk, spec.Base)
+	}
+	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
+		return v
+	}
 	// **The base branch's check judges the change** (novox/hq issue 310), never the one the change brings.
 	judging, err := TheCheckThatJudges(ctx, tree, spec.Base)
 	if err != nil {
@@ -297,7 +341,7 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 		v := CheckVerdict{Verdict: "pass", Summary: noModule, Took: time.Since(began),
 			Gate: &Layer{Verdict: "pass", Summary: noModule}, Repo: &Layer{Verdict: "warning", Summary: noScript}}
 		say("check", "%s; %s", noModule, noScript)
-		return v, nil
+		return named(v), nil
 	}
 	for dir, b := range spec.Beside {
 		if dir == name || !safeName.MatchString(dir) {
@@ -306,6 +350,13 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 		if err := clone(b.Repository, b.Ref, dir); err != nil {
 			return CheckVerdict{}, fmt.Errorf("beside it, %w", err)
 		}
+		// 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 {
+				judged.Beside = map[string]string{}
+			}
+			judged.Beside[dir] = at
+		}
 		say("check", "beside it %s at %s", dir, short(b.Ref))
 	}

@@ -322,6 +373,26 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 				return CheckVerdict{}, fmt.Errorf("a head of the group, %w", err)
 			}
 			say("check", "with it, of its group, %s/%s at %s", g.Owner, g.Repo, short(g.Ref))
+			// Each member is composed as its merge into its own trunk's head (ADR 0323 §6).
+			member := JudgedHead{Owner: g.Owner, Repo: g.Repo, Head: twelve(g.Ref)}
+			if g.Base != "" {
+				m, err := mergeIntoTrunk(ctx, run, filepath.Join(root, dir), g.Base, g.Ref)
+				if err != nil {
+					return CheckVerdict{}, fmt.Errorf("a head of the group, %s/%s: %w", g.Owner, g.Repo, err)
+				}
+				member.Head, member.Trunk = twelve(m.Head), twelve(m.Trunk)
+				if len(m.Conflicts) > 0 {
+					said := fmt.Sprintf("%s/%s: %s", g.Owner, g.Repo, conflictWords(m))
+					say("check", "%s", said)
+					judged.Members = append(judged.Members, member)
+					return named(CheckVerdict{Verdict: "fail", Summary: said, Report: said, Took: time.Since(began),
+						Gate: &Layer{Verdict: "fail", Summary: said}, Repo: &Layer{Verdict: "fail", Summary: said}}), nil
+				}
+				if changed := changedByMerge(ctx, run, filepath.Join(root, dir), m); len(changed) > 0 {
+					g.Paths = changed
+				}
+			}
+			judged.Members = append(judged.Members, member)
 			heads = append(heads, map[string]any{"repository": g.Owner + "/" + g.Repo,
 				"tree": filepath.Join(root, dir), "changed": g.Paths})
 		}
@@ -433,7 +504,7 @@ func Check(ctx context.Context, run Runner, spec CheckSpec, workspace, registry
 	verdictFile := filepath.Join(root, "verdict.json")
 	env := []string{EnvFacts + "=" + factsFile, EnvGate + "=" + gate, EnvGateStore + "=" + storeURL,
 		EnvTestStore + "=" + storeURL, EnvTestBus + "=nats://" + bus, EnvRepository + "=" + spec.Owner + "/" + spec.Repo,
-		EnvChanged + "=" + strings.Join(spec.Paths, ","), EnvBeside + "=" + root,
+		EnvChanged + "=" + strings.Join(paths, ","), EnvBeside + "=" + root,
 		EnvModules + "=" + strings.Join(append(append([]string{}, spec.Modules...), spec.New...), ","),
 		EnvGroup + "=" + groupFile,
 		"GOCACHE=" + filepath.Join(workspace, "go-cache"), "GOMODCACHE=" + filepath.Join(workspace, "go-modules")}
@@ -501,7 +572,7 @@ 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))
-	return v, nil
+	return named(v), nil
 }

 // ownCheck runs the repository's own check, part by part, each in its toolchain's own container: the