Record the forge-made merge in the delivery gate, so the indexer takes it in (issue 1966, recovery)

mesh-sdk #172 (c861bd8a) was merged on the forge and has no gate merge record; the indexer holds its take-in. An empty merge through the gate covers it, and the forge-made wait is dropped (indexer_drop_pending).

Claude-Session: https://claude.ai/code/session_01NcbgfFfQ4Z9UE5jK32PmE5

go/catalogue/seat_pass.go

@@ -1,14 +1,97 @@
 package catalogue
 
-// An assignment as the passing of a seat reads it: a module on a machine, with its manifest.
+import (
+	"fmt"
+	"sort"
+)
+
+// An assignment as the passing of a seat reads it: a module on a machine, with the manifest of the build that machine
+// runs, else the trunk's (novox/hq ADR 0660 §2).
 type Assignment struct {
 	Node     string
 	Manifest Manifest
+	// Unread is an assignment whose manifest could not be read at all: it is still assigned, so its holdings stand,
+	// and it claims nothing.
+	Unread bool
 }
 
-// SeatPass is one seat whose holder on record is assigned nowhere, and the only assignment that can take it.
+// SeatPass is one seat whose holder on record has left it, and the only assignment that can take it.
 type SeatPass struct {
 	Seat Seat
 	From Held
 	To   Held
 }
+
+// SeatsToPassOn reads the mesh for seats held once whose holder on record has left (novox/hq ADR 0449 §4, ADR 0660).
+//
+// **A holder on record that is assigned on no machine, or whose every assignment's manifest no longer claims the seat
+// (or claims it and cannot hold it, by CanHold), holds nothing.** Of such a seat, exactly one assignment in the mesh
+// able to hold it takes it over: that is a pass, and the caller applies it and says it. An assignment is a module on
+// one node, so one module placed on two nodes is two claimants. With no such assignment the record stays; with two or
+// more nothing is passed and the answer says so, naming two and the `seat --to` that settles it. A holder with an
+// assignment whose manifest still claims the seat changes nothing (ADR 0131), and so does one whose manifest could not
+// be read. Only mesh seats held once are read: a replicated seat's holders are added by an act (ADR 0223), a kinded
+// bench is held by its claims, and a seat with several holders on record is a store that disagrees with the mesh.
+// Nothing here records a pass (ADR 0660 §4).
+func SeatsToPassOn(holdings []Held, assignments []Assignment) ([]SeatPass, []string) {
+	bySeat := map[string][]Held{}
+	var order []string
+	for _, h := range holdings {
+		s, ok := SeatNamed(h.Claim)
+		if !ok || s.Replicated || s.Scope != ScopeMesh || h.Scope != ScopeMesh || KindedBenches[s.Name] {
+			continue
+		}
+		if _, seen := bySeat[s.Name]; !seen {
+			order = append(order, s.Name)
+		}
+		bySeat[s.Name] = append(bySeat[s.Name], h)
+	}
+	sort.Strings(order)
+
+	var passes []SeatPass
+	var said []string
+	for _, name := range order {
+		recs := bySeat[name]
+		if len(recs) != 1 {
+			continue
+		}
+		seat, _ := SeatNamed(name)
+		holds := false
+		for _, a := range assignments {
+			if a.Manifest.Module != recs[0].Module {
+				continue
+			}
+			if a.Unread || CanHold(a.Manifest, seat) == nil {
+				holds = true
+			}
+		}
+		if holds {
+			continue
+		}
+		var claimants []Held
+		for _, a := range assignments {
+			if a.Unread || CanHold(a.Manifest, seat) != nil {
+				continue
+			}
+			claimants = append(claimants, Held{Claim: seat.Name, Scope: seat.Scope, Node: a.Node, Module: a.Manifest.Module})
+		}
+		sort.Slice(claimants, func(i, j int) bool {
+			if claimants[i].Node != claimants[j].Node {
+				return claimants[i].Node < claimants[j].Node
+			}
+			return claimants[i].Module < claimants[j].Module
+		})
+		switch len(claimants) {
+		case 0:
+		case 1:
+			passes = append(passes, SeatPass{Seat: seat, From: recs[0], To: claimants[0]})
+		default:
+			said = append(said, fmt.Sprintf(
+				"%s on %s is on record as the holder of %q and holds it nowhere, and %s on %s and %s on %s both claim it "+
+					"— nothing is passed; `seat %s --to <node>/<module>` records the one that holds it",
+				recs[0].Module, recs[0].Node, seat.Name, claimants[0].Module, claimants[0].Node,
+				claimants[1].Module, claimants[1].Node, seat.Name))
+		}
+	}
+	return passes, said
+}

go/catalogue/seat_pass_test.go

@@ -0,0 +1,96 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+func passSeat(t *testing.T) {
+	t.Helper()
+	was := Seats()
+	t.Cleanup(func() { UseSeats(was) })
+	UseSeats([]Seat{
+		{Name: "mesh-broker", Scope: ScopeMesh, Delivers: "mesh-bus", Decision: "test"},
+		{Name: "mesh-dns-resolver", Scope: ScopeMesh, Replicated: true, Decision: "test"},
+	})
+}
+
+func broker(module string) Manifest {
+	return Manifest{Module: module, Provides: []Offer{{Name: "mesh-bus", Scope: ScopeMesh}},
+		Claims: []Claim{{Name: "mesh-broker", Scope: ScopeMesh}}}
+}
+
+// A module that still runs but no longer claims the seat.
+func dropped(module string) Manifest { return Manifest{Module: module} }
+
+func recorded(node, module string) []Held {
+	return []Held{{Claim: "mesh-broker", Scope: ScopeMesh, Node: node, Module: module}}
+}
+
+// novox/hq ADR 0660 "How it is checked", and ADR 0449 §4's original case.
+func TestSeatsToPassOn(t *testing.T) {
+	passSeat(t)
+	rec := recorded("novox", "old")
+	cases := []struct {
+		name  string
+		rec   []Held
+		as    []Assignment
+		to    string // "node/module" of the one pass, "" for none
+		saidW []string
+	}{
+		{"holder assigned nowhere, one claimant (ADR 0449 §4)", rec,
+			[]Assignment{{Node: "novox", Manifest: broker("new")}}, "novox/new", nil},
+		{"holder assigned but its manifest dropped the claim", rec,
+			[]Assignment{{Node: "novox", Manifest: dropped("old")}, {Node: "novox", Manifest: broker("new")}}, "novox/new", nil},
+		{"holder claims but cannot hold the seat", rec,
+			[]Assignment{{Node: "novox", Manifest: Manifest{Module: "old", Claims: []Claim{{Name: "mesh-broker", Scope: ScopeMesh}}}},
+				{Node: "ace", Manifest: broker("new")}}, "ace/new", nil},
+		{"the running build still claims: the holder keeps the seat", rec,
+			[]Assignment{{Node: "novox", Manifest: broker("old")}, {Node: "novox", Manifest: broker("new")}}, "", nil},
+		{"one of the holder's two nodes still claims it", rec,
+			[]Assignment{{Node: "novox", Manifest: dropped("old")}, {Node: "ace", Manifest: broker("old")},
+				{Node: "g14", Manifest: broker("new")}}, "", nil},
+		{"holder's manifest unread: still assigned", rec,
+			[]Assignment{{Node: "novox", Manifest: Manifest{Module: "old"}, Unread: true}, {Node: "novox", Manifest: broker("new")}}, "", nil},
+		{"an unread assignment is no claimant", rec,
+			[]Assignment{{Node: "novox", Manifest: dropped("old")}, {Node: "ace", Manifest: Manifest{Module: "new"}, Unread: true}}, "", nil},
+		{"a claimant whose running manifest does not claim is not counted", rec,
+			[]Assignment{{Node: "novox", Manifest: dropped("old")}, {Node: "ace", Manifest: dropped("new")}}, "", nil},
+		{"no claimant keeps the record", rec,
+			[]Assignment{{Node: "novox", Manifest: dropped("old")}, {Node: "novox", Manifest: dropped("other")}}, "", nil},
+		{"holder gone, no claimant keeps the record", rec, nil, "", nil},
+		{"one module on two nodes is two claimants: none passed, said", rec,
+			[]Assignment{{Node: "novox", Manifest: dropped("old")}, {Node: "ace", Manifest: broker("new")}, {Node: "novox", Manifest: broker("new")}},
+			"", []string{"old", "new on ace", "new on novox", "seat mesh-broker --to <node>/<module>"}},
+		{"two claimants, holder gone: said", rec,
+			[]Assignment{{Node: "novox", Manifest: broker("a")}, {Node: "ace", Manifest: broker("b")}},
+			"", []string{"a on novox", "b on ace", "seat mesh-broker --to <node>/<module>"}},
+		{"a seat with two holders on record is not read", append(rec[:1:1], Held{Claim: "mesh-broker", Scope: ScopeMesh, Node: "ace", Module: "x"}),
+			[]Assignment{{Node: "novox", Manifest: broker("new")}}, "", nil},
+		{"a replicated seat is never passed",
+			[]Held{{Claim: "mesh-dns-resolver", Scope: ScopeMesh, Node: "novox", Module: "gone"}},
+			[]Assignment{{Node: "novox", Manifest: Manifest{Module: "r", Claims: []Claim{{Name: "mesh-dns-resolver", Scope: ScopeMesh}}}}}, "", nil},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			passes, said := SeatsToPassOn(c.rec, c.as)
+			if c.to == "" && len(passes) != 0 || c.to != "" && len(passes) != 1 {
+				t.Fatalf("passes=%+v said=%v", passes, said)
+			}
+			if c.to != "" {
+				p := passes[0]
+				if p.Seat.Name != "mesh-broker" || p.From.Module != "old" || p.To.Node+"/"+p.To.Module != c.to {
+					t.Fatalf("the pass is %+v", p)
+				}
+			}
+			if (len(c.saidW) == 0) != (len(said) == 0) {
+				t.Fatalf("said=%v, want %v", said, c.saidW)
+			}
+			for _, w := range c.saidW {
+				if !strings.Contains(said[0], w) {
+					t.Fatalf("the answer does not say %q: %s", w, said[0])
+				}
+			}
+		})
+	}
+}

go/seatlist/bootstrap/mesh-delivery-checker.json

@@ -140,6 +140,40 @@
           "ended"
         ]
       }
+    },
+    {
+      "name": "input",
+      "description": "A checking program's input the checker keeps, by the sha256 of its exact bytes: the facts of a check its verdict is asked of, or the heads its seat list is asked of, as a run ask names it (its input's verb and digest). Answers the digest and the bytes, base64; a digest it keeps no input of is an error. Asked by the build module that runs the program, as its manifest's invokes grants it. Read-only.",
+      "optional": true,
+      "input": {
+        "type": "object",
+        "properties": {
+          "digest": {
+            "type": "string",
+            "description": "the input's sha256, 64 lowercase hex digits, as the run ask names it"
+          }
+        },
+        "required": [
+          "digest"
+        ]
+      },
+      "answer": {
+        "type": "object",
+        "properties": {
+          "digest": {
+            "type": "string",
+            "description": "the digest asked"
+          },
+          "input": {
+            "type": "string",
+            "description": "the input's exact bytes, base64, so no encoding on the way changes a byte the digest covers"
+          }
+        },
+        "required": [
+          "digest",
+          "input"
+        ]
+      }
     }
   ],
   "description": "The merge check's tries: start one, read one, end one. The checker's own events stay under its own subjects (ADR 0620 §2).",
@@ -455,6 +489,65 @@
                     "to"
                   ]
                 }
+              },
+              "judged-by": {
+                "type": "object",
+                "description": "the checking program that judged the check: where it was built, the key its build is kept under, whether this check's run built it, and the heads it read (ADR 0644, ADR 0656). Absent in a value written before it",
+                "properties": {
+                  "program": {
+                    "type": "object",
+                    "properties": {
+                      "repository": {
+                        "type": "string"
+                      },
+                      "commit": {
+                        "type": "string"
+                      },
+                      "dir": {
+                        "type": "string"
+                      },
+                      "package": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "repository",
+                      "commit",
+                      "dir",
+                      "package"
+                    ]
+                  },
+                  "key": {
+                    "type": "string",
+                    "description": "program- and 16 hex digits"
+                  },
+                  "built": {
+                    "type": "boolean"
+                  },
+                  "heads": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "repository": {
+                          "type": "string"
+                        },
+                        "commit": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "repository",
+                        "commit"
+                      ]
+                    }
+                  }
+                },
+                "required": [
+                  "program",
+                  "key",
+                  "heads"
+                ]
               }
             },
             "required": [

go/seatlist/seatlisttest/seats/mesh-delivery-checker.json

@@ -140,6 +140,40 @@
           "ended"
         ]
       }
+    },
+    {
+      "name": "input",
+      "description": "A checking program's input the checker keeps, by the sha256 of its exact bytes: the facts of a check its verdict is asked of, or the heads its seat list is asked of, as a run ask names it (its input's verb and digest). Answers the digest and the bytes, base64; a digest it keeps no input of is an error. Asked by the build module that runs the program, as its manifest's invokes grants it. Read-only.",
+      "optional": true,
+      "input": {
+        "type": "object",
+        "properties": {
+          "digest": {
+            "type": "string",
+            "description": "the input's sha256, 64 lowercase hex digits, as the run ask names it"
+          }
+        },
+        "required": [
+          "digest"
+        ]
+      },
+      "answer": {
+        "type": "object",
+        "properties": {
+          "digest": {
+            "type": "string",
+            "description": "the digest asked"
+          },
+          "input": {
+            "type": "string",
+            "description": "the input's exact bytes, base64, so no encoding on the way changes a byte the digest covers"
+          }
+        },
+        "required": [
+          "digest",
+          "input"
+        ]
+      }
     }
   ],
   "description": "The merge check's tries: start one, read one, end one. The checker's own events stay under its own subjects (ADR 0620 §2).",
@@ -455,6 +489,65 @@
                     "to"
                   ]
                 }
+              },
+              "judged-by": {
+                "type": "object",
+                "description": "the checking program that judged the check: where it was built, the key its build is kept under, whether this check's run built it, and the heads it read (ADR 0644, ADR 0656). Absent in a value written before it",
+                "properties": {
+                  "program": {
+                    "type": "object",
+                    "properties": {
+                      "repository": {
+                        "type": "string"
+                      },
+                      "commit": {
+                        "type": "string"
+                      },
+                      "dir": {
+                        "type": "string"
+                      },
+                      "package": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "repository",
+                      "commit",
+                      "dir",
+                      "package"
+                    ]
+                  },
+                  "key": {
+                    "type": "string",
+                    "description": "program- and 16 hex digits"
+                  },
+                  "built": {
+                    "type": "boolean"
+                  },
+                  "heads": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "repository": {
+                          "type": "string"
+                        },
+                        "commit": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "repository",
+                        "commit"
+                      ]
+                    }
+                  }
+                },
+                "required": [
+                  "program",
+                  "key",
+                  "heads"
+                ]
               }
             },
             "required": [

go/testdata/beside/CAPTURED

@@ -12,7 +12,7 @@ repositories; before that it was mesh-controller's copy, which still held two mo
 
 mesh-catalog  b5dbfbb784507e211372a7c9640d91f7d6dadd84  modules/*/module.json, modules/*/files/**, modules/*/templates/**, predefined.json
 mesh-contracts 70fe186d7f5743e61f3ce2bbd97a8bfabc5b596e  the seat files of the eight bootstrapped seats held there (seats/, health-and-repair/seats/, operator-and-conversation/seats/), as seat.json.captured
-mesh-delivery 432df75997637542a441b3c8f855335c9070ebbd  contracts/seats/mesh-catalog and mesh-delivery-checker, as seat.json.captured (go/seatlist's bootstrap test)
+mesh-delivery 932e7ccf025513ec4fce38a534c2c38defbc6701  contracts/seats/mesh-catalog and mesh-delivery-checker, as seat.json.captured (go/seatlist's bootstrap test)
 mesh-host     cdcba9ca73755854d21e4e657d7e46c32b9b5265  internal/apply/placement_guard.go
 
 The two seat copies are put back the same way (git show <commit>:<file> > <file>.captured, the path kept). To move the others, from this repository's go/ directory, with the two repositories checked out beside mesh-sdk:

go/testdata/beside/mesh-delivery/contracts/seats/mesh-delivery-checker/seat.json.captured

@@ -140,6 +140,40 @@
           "ended"
         ]
       }
+    },
+    {
+      "name": "input",
+      "description": "A checking program's input the checker keeps, by the sha256 of its exact bytes: the facts of a check its verdict is asked of, or the heads its seat list is asked of, as a run ask names it (its input's verb and digest). Answers the digest and the bytes, base64; a digest it keeps no input of is an error. Asked by the build module that runs the program, as its manifest's invokes grants it. Read-only.",
+      "optional": true,
+      "input": {
+        "type": "object",
+        "properties": {
+          "digest": {
+            "type": "string",
+            "description": "the input's sha256, 64 lowercase hex digits, as the run ask names it"
+          }
+        },
+        "required": [
+          "digest"
+        ]
+      },
+      "answer": {
+        "type": "object",
+        "properties": {
+          "digest": {
+            "type": "string",
+            "description": "the digest asked"
+          },
+          "input": {
+            "type": "string",
+            "description": "the input's exact bytes, base64, so no encoding on the way changes a byte the digest covers"
+          }
+        },
+        "required": [
+          "digest",
+          "input"
+        ]
+      }
     }
   ],
   "description": "The merge check's tries: start one, read one, end one. The checker's own events stay under its own subjects (ADR 0620 §2).",
@@ -455,6 +489,65 @@
                     "to"
                   ]
                 }
+              },
+              "judged-by": {
+                "type": "object",
+                "description": "the checking program that judged the check: where it was built, the key its build is kept under, whether this check's run built it, and the heads it read (ADR 0644, ADR 0656). Absent in a value written before it",
+                "properties": {
+                  "program": {
+                    "type": "object",
+                    "properties": {
+                      "repository": {
+                        "type": "string"
+                      },
+                      "commit": {
+                        "type": "string"
+                      },
+                      "dir": {
+                        "type": "string"
+                      },
+                      "package": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "repository",
+                      "commit",
+                      "dir",
+                      "package"
+                    ]
+                  },
+                  "key": {
+                    "type": "string",
+                    "description": "program- and 16 hex digits"
+                  },
+                  "built": {
+                    "type": "boolean"
+                  },
+                  "heads": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "repository": {
+                          "type": "string"
+                        },
+                        "commit": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "repository",
+                        "commit"
+                      ]
+                    }
+                  }
+                },
+                "required": [
+                  "program",
+                  "key",
+                  "heads"
+                ]
               }
             },
             "required": [