delivery: the gate's merge turns, so the checker holds new checks off a repository an approved merge waits on (ADR 0548 §3, §4; issue 568 S1)

go/delivery/gate_test.go

@@ -123,6 +123,15 @@ func sampleMerge() Merge {
 	}}
 }
 
+func sampleTurn() Turn {
+	at := time.Date(2026, 10, 26, 9, 0, 0, 0, time.UTC)
+	return Turn{Repository: "novox/mesh-sdk", Waiting: []TurnWait{
+		{Group: "feat/x", Heads: mustHash(gateHeads()), Ask: "merge.feat/x." + mustHash(gateHeads()), Approved: at, Since: at,
+			WaitsFor: "feat/y.0123456789ab", WaitsSince: at.Add(-time.Minute), Step: "the check ask of novox/mesh-sdk#40"},
+		{Group: "fix/1.2", Heads: "0123456789ac", Approved: at.Add(time.Minute), Since: at.Add(time.Minute)},
+	}}
+}
+
 func sampleAsk() Ask {
 	key, _ := MergeAskKey("feat/x", gateHeads())
 	return Ask{Group: "feat/x", Heads: gateHeads(), Ask: asks.Ask{
@@ -181,7 +190,24 @@ func TestGateValuesRoundTrip(t *testing.T) { // 1201/AC4
 			t.Errorf("owed %s round trip: %+v %v", o.Act, got, err)
 		}
 	}
+	tu := sampleTurn()
+	data, err = EncodeTurn(tu)
+	hasV("turn", data, err)
+	tu.V = Version
+	if got, err := DecodeTurn(data); err != nil || !SameTurn(got, tu) {
+		t.Errorf("turn round trip: %+v %v", got, err)
+	}
+	for _, field := range []string{`"waits-for":"feat/y.0123456789ab"`, `"waits-since":`, `"approved":`, `"step":`} {
+		if !strings.Contains(string(data), field) {
+			t.Errorf("the turn lacks %s: %s", field, data)
+		}
+	}
+	// ADR 0548 §3: a turn holds off every check but the one of a waiting delivery's own heads.
+	if !TurnHolds(tu, "fedcba987654") || TurnHolds(Turn{Waiting: tu.Waiting[:1]}, tu.Waiting[0].Heads) || !TurnHolds(tu, tu.Waiting[0].Heads) {
+		t.Error("TurnHolds: a turn holds other heads' checks and never its only delivery's own")
+	}
 	for name, dec := range map[string]func([]byte) error{
+		"turn":   func(b []byte) error { _, err := DecodeTurn(b); return err },
 		"merge":  func(b []byte) error { _, err := DecodeMerge(b); return err },
 		"ask":    func(b []byte) error { _, err := DecodeAsk(b); return err },
 		"answer": func(b []byte) error { _, err := DecodeAnswer(b); return err },
@@ -265,6 +291,27 @@ func TestGateValuesRefused(t *testing.T) { // 1201/AC5
 	}
 	_, err = EncodeOwed(Owed{Act: OwedNote, Text: "line"})
 	wantErr("note without ref", err, "ref")
+
+	for name, c := range map[string]struct {
+		edit  func(*Turn)
+		words []string
+	}{
+		"no delivery":                {func(t *Turn) { t.Waiting = nil }, []string{"no delivery", "deleted"}},
+		"a repository in capitals":   {func(t *Turn) { t.Repository = "novox/Mesh-SDK" }, []string{"lowercase"}},
+		"no repository":              {func(t *Turn) { t.Repository = "" }, []string{"repository"}},
+		"no group":                   {func(t *Turn) { t.Waiting[0].Group = "" }, []string{"group"}},
+		"a bad heads hash":           {func(t *Turn) { t.Waiting[0].Heads = "xyz" }, []string{"xyz"}},
+		"the same heads twice":       {func(t *Turn) { t.Waiting[1].Heads = t.Waiting[0].Heads }, []string{"twice"}},
+		"no Approve time":            {func(t *Turn) { t.Waiting[1].Approved = time.Time{} }, []string{"Approve"}},
+		"out of the Approve's order": {func(t *Turn) { t.Waiting[1].Approved = t.Waiting[0].Approved.Add(-time.Hour) }, []string{"order"}},
+		"waits for no verdict key":   {func(t *Turn) { t.Waiting[0].WaitsFor = "feat/y" }, []string{"verdict key"}},
+		"a step and no check":        {func(t *Turn) { t.Waiting[1].Step = "x" }, []string{"names no check"}},
+	} {
+		tu := sampleTurn()
+		c.edit(&tu)
+		_, err = EncodeTurn(tu)
+		wantErr("turn with "+name, err, c.words...)
+	}
 	_, err = EncodeOwed(Owed{Act: OwedStatus, State: "success"})
 	wantErr("status without context", err, "context")
 }
@@ -297,7 +344,8 @@ func TestGateSame(t *testing.T) { // 1201/AC6
 func TestGateBuckets(t *testing.T) {
 	if MergesBucket != "mesh-delivery-gate_merges" || AsksBucket != "mesh-delivery-gate_asks" ||
 		OwedBucket != "mesh-delivery-gate_owed" || AnswersBucket != "mesh-delivery-teller_answers" ||
-		MergesHistory != 10 || AsksHistory != 5 || OwedHistory != 5 || AnswersHistory != 5 {
+		MergesHistory != 10 || AsksHistory != 5 || OwedHistory != 5 || AnswersHistory != 5 ||
+		TurnsBucket != "mesh-delivery-gate_turns" || TurnsHistory != 5 {
 		t.Error("a bucket or history differs from the decided layout")
 	}
 }
@@ -370,6 +418,21 @@ func TestKeysEscapeAndRoundTrip(t *testing.T) { // 1323/AC1
 		if r, n, h, a, err := ParseOwedKey(ok); err != nil || r != repo || n != 3 || h != "aaaa" || a != "view" {
 			t.Errorf("owed round trip %q = %q %d %q %q %v", repo, r, n, h, a, err)
 		}
+		// ADR 0548 §3: a repository's turn key is <owner>.<name>, lowercase, each part escaped.
+		tk, err := TurnsKey(repo)
+		if err != nil || strings.Count(tk, ".") != 1 {
+			t.Errorf("turns key for repository %q = %q, %v", repo, tk, err)
+		} else if r, err := ParseTurnsKey(tk); err != nil || r != strings.ToLower(repo) {
+			t.Errorf("turns round trip %q = %q, %v", repo, r, err)
+		}
+	}
+	if k, err := TurnsKey("novox/Mesh-SDK"); err != nil || k != "novox.mesh-sdk" {
+		t.Errorf("turns key = %q, %v; want novox.mesh-sdk", k, err)
+	}
+	for _, bad := range []string{"", "novox", "novox.", ".x", "a.b.c", "Novox.mesh-sdk", "novox.a=zz"} {
+		if _, err := ParseTurnsKey(bad); err == nil {
+			t.Errorf("parse turns key %q accepted", bad)
+		}
 	}
 	if EscapeName("a.b") != "a=2eb" || EscapeName("a=b") != "a=3db" || EscapeName("a+b") != "a=2bb" {
 		t.Errorf("escapes: %q %q %q", EscapeName("a.b"), EscapeName("a=b"), EscapeName("a+b"))

go/delivery/turns.go

@@ -0,0 +1,170 @@
+package delivery
+
+import (
+	"encoding/json"
+	"fmt"
+	"reflect"
+	"strings"
+	"time"
+)
+
+// **The merge turns** (novox/hq ADR 0548 clauses 3 and 4). An approved merge holds a turn on each repository it goes into:
+// before it reads the checker's verdicts for the merge, the gate writes one key per repository in its bucket turns, naming
+// the deliveries that wait in the order of their Approve, the verdict key each waits for and since when. The gate is the
+// key's one writer; the checker is granted to read the bucket, reads it absent as empty, and claims no check of a repository
+// a turn names, except the check of the waiting delivery's own heads (TurnHolds). The key goes when the last delivery in it
+// merged or left.
+const (
+	// TurnsBucket is the gate's bucket of merge turns.
+	TurnsBucket = GateModule + "_turns"
+	// TurnsHistory is the revisions the turns bucket keeps per key.
+	TurnsHistory = 5
+)
+
+// TurnsKey is the key, in TurnsBucket, of a repository's turn: `<owner>.<name>`, lowercase, each part escaped (EscapeName),
+// so the key names the repository the checker's verdicts name as a trunk whatever its case.
+func TurnsKey(repository string) (string, error) {
+	repository = strings.ToLower(repository)
+	if _, err := escapeRepository(repository); err != nil {
+		return "", err
+	}
+	owner, name, _ := strings.Cut(repository, "/")
+	return EscapeName(owner) + "." + EscapeName(name), nil
+}
+
+// ParseTurnsKey is the inverse of TurnsKey: the repository, lowercase.
+func ParseTurnsKey(key string) (string, error) {
+	owner, name, ok := strings.Cut(key, ".")
+	if !ok || owner == "" || name == "" || strings.Contains(name, ".") {
+		return "", fmt.Errorf("delivery: %q is not a turns key, <owner>.<name>", key)
+	}
+	o, err := UnescapeName(owner)
+	if err != nil {
+		return "", fmt.Errorf("delivery: %q is not a turns key: %w", key, err)
+	}
+	n, err := UnescapeName(name)
+	if err != nil {
+		return "", fmt.Errorf("delivery: %q is not a turns key: %w", key, err)
+	}
+	repository := o + "/" + n
+	if again, err := TurnsKey(repository); err != nil || again != key {
+		return "", fmt.Errorf("delivery: %q is not a turns key: it does not name a lowercase <owner>/<name>", key)
+	}
+	return repository, nil
+}
+
+// Turn is the value of a turns key: the repository and the approved deliveries that wait to merge into it, in the order of
+// their Approve. A turn with no delivery is no value: its key is deleted.
+type Turn struct {
+	V          int        `json:"v"`
+	Repository string     `json:"repository"`
+	Waiting    []TurnWait `json:"waiting"`
+}
+
+// TurnWait is one approved delivery in a turn: its group (a lone pull request's branch), the hash of the heads the Approve
+// covers (the checker's verdict key's hash, HeadsHash over its members), the Approve's ask key, when it was approved and since
+// when it waits; and, while a check of another delivery runs on the repository, that check's verdict key, when the gate saw
+// it start, and the step the checker says it is at.
+type TurnWait struct {
+	Group    string    `json:"group"`
+	Heads    string    `json:"heads"`
+	Ask      string    `json:"ask,omitempty"`
+	Approved time.Time `json:"approved"`
+	Since    time.Time `json:"since"`
+	// WaitsFor is the verdict key (`<group>.<heads hash>`) of the running check the merge waits for; empty when none runs.
+	WaitsFor   string    `json:"waits-for,omitempty"`
+	WaitsSince time.Time `json:"waits-since,omitzero"`
+	Step       string    `json:"step,omitempty"`
+}
+
+func (t Turn) check() error {
+	repository := strings.ToLower(t.Repository)
+	if repository != t.Repository {
+		return fmt.Errorf("delivery: the turn's repository %q is not lowercase", t.Repository)
+	}
+	if _, err := escapeRepository(repository); err != nil {
+		return err
+	}
+	if len(t.Waiting) == 0 {
+		return fmt.Errorf("delivery: the turn of %s names no delivery: its key is deleted instead", t.Repository)
+	}
+	seen := map[string]bool{}
+	for i, w := range t.Waiting {
+		if w.Group == "" {
+			return fmt.Errorf("delivery: a delivery in the turn of %s names no group", t.Repository)
+		}
+		if !isHex12(w.Heads) {
+			return fmt.Errorf("delivery: the heads hash %q in the turn of %s is not 12 lowercase hex digits", w.Heads, t.Repository)
+		}
+		if seen[w.Heads] {
+			return fmt.Errorf("delivery: the turn of %s names the heads %s twice", t.Repository, w.Heads)
+		}
+		seen[w.Heads] = true
+		if w.Approved.IsZero() || w.Since.IsZero() {
+			return fmt.Errorf("delivery: the delivery %s in the turn of %s says no time of its Approve or of its wait", w.Group, t.Repository)
+		}
+		if i > 0 && w.Approved.Before(t.Waiting[i-1].Approved) {
+			return fmt.Errorf("delivery: the turn of %s is not in the order of the Approve: %s was approved before %s", t.Repository, w.Group, t.Waiting[i-1].Group)
+		}
+		if w.WaitsFor != "" {
+			if _, _, err := ParseCheckerVerdictKey(w.WaitsFor); err != nil {
+				return fmt.Errorf("delivery: the delivery %s in the turn of %s waits for what is not a verdict key: %w", w.Group, t.Repository, err)
+			}
+		} else if !w.WaitsSince.IsZero() || w.Step != "" {
+			return fmt.Errorf("delivery: the delivery %s in the turn of %s says when and where a check runs, and names no check", w.Group, t.Repository)
+		}
+	}
+	return nil
+}
+
+// TurnHolds says whether a turn holds off the check of the heads: it names a delivery of other heads. The check of a waiting
+// delivery's own heads (the carry its merge waits for) is never held by its own turn.
+func TurnHolds(t Turn, heads string) bool {
+	for _, w := range t.Waiting {
+		if w.Heads != heads {
+			return true
+		}
+	}
+	return false
+}
+
+// EncodeTurn is t as JSON at Version; it refuses a turn with no delivery, a repository that is not lowercase <owner>/<name>,
+// a delivery without its group, heads hash or times, the same heads twice, an order other than the Approve's, and a check
+// waited for that is not a verdict key.
+func EncodeTurn(t Turn) ([]byte, error) {
+	if err := t.check(); err != nil {
+		return nil, err
+	}
+	t.V = Version
+	return json.Marshal(t)
+}
+
+// DecodeTurn reads a turn; it refuses an unknown version (ErrUnknownVersion) and what EncodeTurn refuses.
+func DecodeTurn(data []byte) (Turn, error) {
+	var t Turn
+	if err := decode(data, &t); err != nil {
+		return Turn{}, err
+	}
+	if err := t.check(); err != nil {
+		return Turn{}, err
+	}
+	return t, nil
+}
+
+// SameTurn says whether two turns are the same value, so the gate writes only when they differ.
+func SameTurn(a, b Turn) bool {
+	if len(a.Waiting) != len(b.Waiting) || a.Repository != b.Repository || a.V != b.V {
+		return false
+	}
+	for i := range a.Waiting {
+		x, y := a.Waiting[i], b.Waiting[i]
+		if !x.Approved.Equal(y.Approved) || !x.Since.Equal(y.Since) || !x.WaitsSince.Equal(y.WaitsSince) {
+			return false
+		}
+		x.Approved, y.Approved, x.Since, y.Since, x.WaitsSince, y.WaitsSince = time.Time{}, time.Time{}, time.Time{}, time.Time{}, time.Time{}, time.Time{}
+		if !reflect.DeepEqual(x, y) {
+			return false
+		}
+	}
+	return true
+}