GATE-7: gate_heads reads the untaken heads; gate_head_take takes one in by hand

gate_heads reads the state heads with each head's since and finding;
gate_head_take, recorded in the hand-act log first, names the held head a
source revision as a merge call does, with a call of its own, its record
marked by hand with who and when and its member <repository>@<commit 12>,
and the finding clears.

Builds: design 47 H §742; H-A-24 (hand, by and the time in the trace), H-A-48 (a hand take's member <repository>@<commit 12>)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 03:18:27 +01:00
parent 4f10af81b0
commit e534f667da
4 changed files with 158 additions and 0 deletions
@@ -3,6 +3,7 @@ package main
import (
"context"
"encoding/json"
"errors"
"os"
"strings"
"testing"
@@ -115,6 +116,41 @@ func TestAHeadNoMergeCallDeliveredIsAnUntakenHead(t *testing.T) {
t.Fatalf("after the merge call: held %+v, findings %+v", heads, fw.held)
}
})
// GATE-7 (§742): gate_heads reads each held head with since and finding; gate_head_take writes one revision of its own
// call, opens its record marked by hand, writes the hand-act log first and clears the finding.
t.Run("gate_heads reads the held heads; gate_head_take takes one in after the log and clears head-untaken", func(t *testing.T) {
h, heads, fw, now := setup()
h.Records = &Records{Ledger: newLedgerFake(t), Now: h.Now}
if err := h.HeadMoved(moved(c2)); err != nil {
t.Fatal(err)
}
*now = at.Add(DefaultUntakenBound)
h.React()
out, err := h.HeadsHeld()
lines, _ := out["heads"].([]HeadLine)
if err != nil || len(lines) != 1 || lines[0].Repository != "novox/app" || lines[0].Branch != "main" || lines[0].Head != c2 ||
!strings.Contains(lines[0].Finding, WordsUntaken) || lines[0].Since == "" {
t.Fatalf("gate_heads %+v %v", out, err)
}
acts := &handActsFake{refuse: errors.New("log down")}
if _, err := h.HeadTake("novox/app", "main", "pushed by hand", "lead@shanks", acts); err == nil || len(heads) != 1 {
t.Fatalf("taken without the log: %v", err)
}
acts.refuse = nil
if _, err := h.HeadTake("novox/other", "main", "x", "lead@shanks", acts); err == nil {
t.Fatal("a head the gate does not hold is taken")
}
got, err := h.HeadTake("novox/app", "main", "pushed by hand", "lead@shanks", acts)
if err != nil || got["source"] != int64(5) || len(acts.took) != 1 || acts.took[0].Cause != "gate_head_take" {
t.Fatalf("take %+v %v, log %+v", got, err, acts.took)
}
src, _, _ := h.Source.Read("main")
kept, _ := h.Records.Kept()
if src.Heads["novox/app"] != c2 || len(heads) != 0 || len(fw.held) != 0 || len(kept) != 1 || kept[0].Trace == nil ||
!kept[0].Trace.Hand || kept[0].Trace.By != "lead@shanks" || kept[0].Heads["novox/app@222222222222"] != c2 {
t.Fatalf("source %+v, held %+v, findings %+v, records %+v", src, heads, fw.held, kept)
}
})
t.Run("the setting untaken-bound, at least one minute", func(t *testing.T) {
h, _, _, _ := setup()
n := 3
@@ -0,0 +1,119 @@
package main
// Taking an untaken head in by hand (design 47 H §742; ADR 0682 §3; H-A-24, H-A-48): gate_heads reads the state heads with
// each head's since and finding; gate_head_take, with repository, branch and why, written in the hand-act log first, names
// that head a source revision as a merge call does (§737), its call one of its own and its trace marked by hand with who and
// when, its record's member `<repository>@<commit 12>`, and the chain follows. Nothing else delivers an untaken head.
import (
"errors"
"fmt"
"sort"
"strings"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// HeadLine is one held head as gate_heads reads it.
type HeadLine struct {
Repository string `json:"repository"`
Branch string `json:"branch"`
Head string `json:"head"`
Since string `json:"since"`
// Finding is head-untaken's summary when it is raised.
Finding string `json:"finding,omitempty"`
}
// HeadsHeld is gate_heads: every held head, ordered by key.
func (h *Holder) HeadsHeld() (map[string]any, error) {
if h.Heads == nil {
return nil, errors.New("this gate watches no heads")
}
held, err := h.Heads.All()
if err != nil {
return nil, err
}
raised := map[string]string{}
if h.Findings != nil {
for _, f := range h.Findings.Held() {
if f.Scope == FindingScope && f.Kind == HeadUntaken {
raised[f.ID] = f.Summary
}
}
}
lines := []HeadLine{}
for key, v := range held {
repository, escaped, ok := seat.ParseHeadsByRepositoryBranchKey(key)
branch, err := keys.UnescapeName(escaped)
if !ok || err != nil {
continue
}
lines = append(lines, HeadLine{Repository: repository, Branch: branch, Head: v.Head, Since: timeText(&v.Since), Finding: raised[key]})
}
sort.Slice(lines, func(i, j int) bool { return headKey(lines[i].Repository, lines[i].Branch) < headKey(lines[j].Repository, lines[j].Branch) })
return map[string]any{"heads": lines}, nil
}
// HeadTake is gate_head_take: the held head of a repository on a branch named one source revision, after the hand-act log took it.
func (h *Holder) HeadTake(repository, branch, why, by string, acts handActs) (map[string]any, error) {
if strings.TrimSpace(repository) == "" || strings.TrimSpace(branch) == "" || strings.TrimSpace(why) == "" {
return nil, errors.New("say the repository, the branch and why its head is taken in by hand")
}
if h.Heads == nil || h.Source == nil {
return nil, errors.New("this gate watches no heads or keeps no source")
}
held, err := h.Heads.Get(headKey(repository, branch))
if err != nil {
return nil, err
}
if held == nil {
return nil, fmt.Errorf("the gate holds no untaken head of %s on %s: gate_heads lists them", repository, branch)
}
if acts == nil {
return nil, errors.New("the hand-act log cannot be reached here, so nothing was taken in")
}
at := h.Now().UTC()
if _, err := acts.Record(meshhandactsclient.Request{What: fmt.Sprintf("took the head %s of %s on %s in by hand (hand by %s at %s)",
shortOf(held.Head, 12), repository, branch, by, at.Format("2006-01-02T15:04:05Z")), Why: why, Cause: "gate_head_take",
Verb: "head-take"}); err != nil {
return nil, fmt.Errorf("the hand act was not recorded through mesh-hand-acts, so nothing was taken in: %w", err)
}
call, err := newCall()
if err != nil {
return nil, err
}
member := IDOf(repository, held.Head)
trace := RecordTrace{Call: call, By: by, Hand: true, At: at, Pulls: []string{member}, Commits: []string{held.Head}}
if err := h.deliverRevision(branch, call, []revisionHead{{Repository: repository, Commit: held.Head}},
map[string]string{member: held.Head}, trace); err != nil {
return nil, err
}
named, _, err := h.Source.Read(branch)
if err != nil || named == nil {
return nil, fmt.Errorf("the head is taken in and source.%s cannot be read back: %v", branch, err)
}
return map[string]any{"repository": repository, "branch": branch, "head": held.Head, "source": named.Source, "call": call, "by": by}, nil
}
// headTools are the watchdog's tools; acts is the hand-act log.
func headTools(h *Holder, acts handActs) []stdio.Tool {
return []stdio.Tool{
{Name: "gate_heads",
Description: "Every watched branch's head the gate holds as untaken (design 47 H §740, §742): moved, and named by no source " +
"revision yet, each with its repository, branch, head, since when, and head-untaken's summary once raised. Read, never written.",
Run: func(map[string]any) (any, error) { return h.HeadsHeld() }},
{Name: "gate_head_take",
Description: "Take one untaken head in by hand (design 47 H §742): the head the gate holds for the repository on the branch is " +
"named one source revision as a merge call does, with its record, and the chain follows; recorded in the hand-act log of " +
"the seat mesh-hand-acts first. Nothing else delivers a head moved outside the mesh.",
Input: map[string]any{"type": "object", "properties": map[string]any{"repository": str("owner/repository"),
"branch": str("the watched branch"), "why": str("why it is taken in by hand, in plain words")},
"required": []string{"repository", "branch", "why"}},
Run: func(a map[string]any) (any, error) {
return h.HeadTake(strArg(a, "repository"), strArg(a, "branch"), strArg(a, "why"), stdio.CallerOf(a), acts)
}},
}
}
@@ -249,6 +249,7 @@ func tools(h *Holder, l *listening) []stdio.Tool {
}
list = append(list, recordTools(h, meshhandactsclient.Recorder{Ask: stdio.Ask})...)
list = append(list, sourceTools(h, meshhandactsclient.Recorder{Ask: stdio.Ask})...)
list = append(list, headTools(h, meshhandactsclient.Recorder{Ask: stdio.Ask})...)
// A verb that changes a delivery asks for a look at what it makes possible (react.go).
for i := range list {
run := list[i].Run
+2
View File
@@ -306,6 +306,8 @@
"tools": [
"delivery_status",
"gate_consumer",
"gate_head_take",
"gate_heads",
"gate_record",
"gate_record_end",
"gate_record_repair",