Resolve a group's order rules by precedence, not as a cycle (hq issue 309)

The group feat/a-machine-joins-through-the-tunnel was refused: the
controller's member moved the build agent, which builds the node-engine
(built by: controller first), and the node-engine goes before the
controller (engine before controller: engine first). Both rules applied
to one pair in opposite directions, and every two-way pair was a cycle.

Rules now have a precedence (hq ADR 0249): a declared after: line, then
what the graph and the change say (built by, version skew), then the
rollout default engine-before-controller. The higher rule decides the
pair, which says what it won over. Rules of one rank both ways are still
refused, as a contradiction naming both rules and how to declare the
order. TestReplay309 replays the group with only what orderOf had before.

cmd/mesh-controller/delivery.go

@@ -168,11 +168,22 @@ func (m orderMember) pull() link.PullUpdated {
 		ModuleDirs: m.ModuleDirs, ModuleDirsSaid: m.ModuleDirsSaid}
 }
 
-// orderPair is one "before" among a group's members, and why.
+// orderPair is one "before" among a group's members, why, and the rules it won over.
 type orderPair struct {
 	Before string `json:"before"`
 	After  string `json:"after"`
 	Why    string `json:"why"`
+	// Over is the rules that ordered the pair the other way and lost to Why, by precedence (novox/hq ADR
+	// 0249): said, so a person reading the order sees which rule won.
+	Over []string `json:"over,omitempty"`
+}
+
+// orderContradiction is two members that rules of one rank order both ways: no precedence resolves it, so
+// the group is refused, the rules named, and Said says how a person declares the order.
+type orderContradiction struct {
+	Members []string    `json:"members"`
+	Rules   []orderPair `json:"rules"`
+	Said    string      `json:"said"`
 }
 
 // orderReach is what a member moves, as the planner says.
@@ -183,12 +194,14 @@ type orderReach struct {
 	Manifests  []string `json:"manifests,omitempty"`
 }
 
-// groupOrder is a group's order: the members in it, every pair and why, and the cycle when there is one.
+// groupOrder is a group's order: the members in it, every pair and why, and the cycle when there is one —
+// with each contradiction no precedence resolves.
 type groupOrder struct {
-	Order []string              `json:"order"`
-	Pairs []orderPair           `json:"pairs,omitempty"`
-	Cycle []string              `json:"cycle,omitempty"`
-	Reach map[string]orderReach `json:"reach,omitempty"`
+	Order          []string              `json:"order"`
+	Pairs          []orderPair           `json:"pairs,omitempty"`
+	Cycle          []string              `json:"cycle,omitempty"`
+	Contradictions []orderContradiction  `json:"contradictions,omitempty"`
+	Reach          map[string]orderReach `json:"reach,omitempty"`
 }
 
 // The reasons a pair is ordered, in the words the delivery plan shows.
@@ -199,7 +212,23 @@ const (
 	orderEngineFirst = "engine before controller"
 )
 
-// orderOf is a group's order (novox/hq ADR 0239 decision 4), pure. A member goes before another when:
+// orderRank is a rule's precedence when two rules order one pair both ways (novox/hq ADR 0249), the lower
+// winning: what a person declared; then what the graph and the change say (built by, version skew); then
+// the rollout default, which infers a direction from the modules' names alone.
+func orderRank(why string) int {
+	switch why {
+	case orderDeclared:
+		return 0
+	case orderBuiltBy, orderVersionSkew:
+		return 1
+	case orderEngineFirst:
+		return 2
+	}
+	return 3
+}
+
+// orderOf is a group's order (novox/hq ADR 0239 decision 4, ADR 0249), pure. A member goes before another
+// when:
 //
 //   - its pull request is named in the other's `after:` lines (declared);
 //   - it moves a module the other's moved modules are built by, stand on, package or declare (built by);
@@ -209,24 +238,28 @@ const (
 //     does not yet grant, and a controller sends nothing an older engine would refuse — ADR 0236's rollout
 //     order).
 //
-// Otherwise, by repository then id, so every reading gives one order. A pair both ways is a cycle: the
-// members in it are named, and none of them is ordered.
+// When rules order one pair both ways, the one of higher precedence wins (orderRank) and the pair says
+// what it won over. Rules of one rank both ways are a contradiction: both are kept as pairs, the members
+// are the cycle, and the contradiction says how to declare the order. Otherwise, by repository then id, so
+// every reading gives one order. A cycle through three members or more is named by its members, and none
+// of them is ordered.
 func orderOf(members []orderMember, reach map[string]orderReach, edges []inventory.Edge) groupOrder {
 	out := groupOrder{Reach: reach}
 	byID := map[string]orderMember{}
 	for _, m := range members {
 		byID[m.ID] = m
 	}
+	var claims []orderPair
 	add := func(before, after, why string) {
 		if before == after {
 			return
 		}
-		for _, p := range out.Pairs {
-			if p.Before == before && p.After == after {
+		for _, p := range claims {
+			if p.Before == before && p.After == after && p.Why == why {
 				return
 			}
 		}
-		out.Pairs = append(out.Pairs, orderPair{Before: before, After: after, Why: why})
+		claims = append(claims, orderPair{Before: before, After: after, Why: why})
 	}
 	named := func(said, repository string) bool {
 		said = strings.TrimSuffix(strings.TrimSpace(said), ".git")
@@ -263,6 +296,7 @@ func orderOf(members []orderMember, reach map[string]orderReach, edges []invento
 			}
 		}
 	}
+	out.Pairs, out.Contradictions = resolveClaims(claims, byID)
 	sort.Slice(out.Pairs, func(i, j int) bool {
 		if out.Pairs[i].Before != out.Pairs[j].Before {
 			return out.Pairs[i].Before < out.Pairs[j].Before
@@ -312,6 +346,89 @@ func orderOf(members []orderMember, reach map[string]orderReach, edges []invento
 	return out
 }
 
+// orderRules is the rules in the order a pair names them when more than one says the same.
+var orderRules = []string{orderDeclared, orderBuiltBy, orderVersionSkew, orderEngineFirst}
+
+// resolveClaims is the pairs the rules' claims come to (novox/hq ADR 0249): for each two members, the claims
+// of the highest precedence decide, and the claims they overrule are said on the pair. Claims of one rank
+// both ways are a contradiction: both pairs are kept, so the walk finds the cycle, and the contradiction
+// says how a person declares the order.
+func resolveClaims(claims []orderPair, byID map[string]orderMember) ([]orderPair, []orderContradiction) {
+	byTwo := map[[2]string][]orderPair{}
+	var keys [][2]string
+	for _, c := range claims {
+		k := [2]string{min(c.Before, c.After), max(c.Before, c.After)}
+		if _, ok := byTwo[k]; !ok {
+			keys = append(keys, k)
+		}
+		byTwo[k] = append(byTwo[k], c)
+	}
+	slices.SortFunc(keys, func(a, b [2]string) int {
+		if c := strings.Compare(a[0], b[0]); c != 0 {
+			return c
+		}
+		return strings.Compare(a[1], b[1])
+	})
+	ruleIndex := func(why string) int { return slices.Index(orderRules, why) }
+	var pairs []orderPair
+	var contradictions []orderContradiction
+	for _, k := range keys {
+		cs := byTwo[k]
+		slices.SortStableFunc(cs, func(a, b orderPair) int { return ruleIndex(a.Why) - ruleIndex(b.Why) })
+		top := orderRank(cs[0].Why)
+		var won []orderPair
+		ways := map[string]bool{}
+		for _, c := range cs {
+			if orderRank(c.Why) == top {
+				won = append(won, c)
+				ways[c.Before] = true
+			}
+		}
+		if len(ways) == 1 {
+			p := orderPair{Before: won[0].Before, After: won[0].After, Why: won[0].Why}
+			for _, c := range cs {
+				if c.Before != p.Before && !slices.Contains(p.Over, c.Why) {
+					p.Over = append(p.Over, c.Why)
+				}
+			}
+			pairs = append(pairs, p)
+			continue
+		}
+		// One rank both ways: no precedence resolves it.
+		var first, second *orderPair
+		var said []string
+		for i := range won {
+			c := won[i]
+			if c.Before == k[0] && first == nil {
+				first = &won[i]
+			}
+			if c.Before == k[1] && second == nil {
+				second = &won[i]
+			}
+			said = append(said, fmt.Sprintf("%s puts %s first", c.Why, c.Before))
+		}
+		pairs = append(pairs, orderPair{Before: first.Before, After: first.After, Why: first.Why},
+			orderPair{Before: second.Before, After: second.After, Why: second.Why})
+		a, b := byID[k[0]], byID[k[1]]
+		how := fmt.Sprintf("neither outranks the other: declare the order with a line `after: %s` in %s's "+
+			"description, or `after: %s` in %s's", a.Repository, pullName(b), b.Repository, pullName(a))
+		if top == orderRank(orderDeclared) {
+			how = "each pull request declares it goes after the other: remove one of the `after:` lines"
+		}
+		contradictions = append(contradictions, orderContradiction{Members: []string{k[0], k[1]}, Rules: won,
+			Said: fmt.Sprintf("%s and %s: %s; %s", k[0], k[1], strings.Join(said, ", "), how)})
+	}
+	return pairs, contradictions
+}
+
+// pullName is a member as a person finds it: its pull request, or its id when no number was said.
+func pullName(m orderMember) string {
+	if m.Number > 0 {
+		return fmt.Sprintf("%s#%d", m.Repository, m.Number)
+	}
+	return m.ID
+}
+
 // reachOfMembers is each member's reach, as the planner says it.
 func reachOfMembers(members []orderMember, entries []inventory.Entry, read map[string][]inventory.ReadRepository,
 	edges []inventory.Edge) map[string]orderReach {