GATE-6: the watchdog holds a head no merge call delivered and raises head-untaken

The gate consumes the forge bridge's head-moved, keeps in its template
state heads each head source.<branch> does not name, and raises
head-untaken (scope delivery, id <repository>.<branch>, warning, the
operator its resolver) once untaken-bound passes, on its one deadline
timer; a later source revision naming the head lets it go and clears the
finding. The stalled conditions, their state and the operator-channel
use go: the watchman's record-open is the one signal.

Builds: design 47 H §740; H-A-27 (head-moved's form, forgemsg), H-A-48 (the stalled conditions go; untaken-bound on the gate's one timer), H-A-81 (warning, resolver operator, no owner)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 03:17:42 +01:00
parent 6d398264db
commit 4f10af81b0
14 changed files with 445 additions and 239 deletions
@@ -1,211 +0,0 @@
package main
import (
"encoding/json"
"fmt"
"sort"
"strings"
"time"
occ "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// The gate says its own stalled lines to the operator as conditions (novox/hq issue 1275, met again 2026-10-25; ADR 0437
// §9: any module says a condition on the operator-channel seat's one subject, and the router alone chooses the channels).
// Until release 6 the controller's self-check read the `stalled` verb and raised each line as `delivery.<id>.stalled`;
// release 6 deleted that self-check (mesh-controller dc456d56) and nothing read the verb since, so a half-merged group was
// said to no one. Now, after every look, the gate raises each line `stalled` lists, raises it again when its severity or
// its need changes, and clears each it raised that is listed no more. What it raised is kept in its bucket conditions, so a
// gate that restarts clears what ended while it was away.
// ConditionStore keeps the conditions the gate has raised: the condition's key to what it said (conditionSaid).
type ConditionStore interface {
Said() (map[string]string, error)
PutSaid(said map[string]string) error
}
// saidKey is the one key of the bucket conditions.
const saidKey = "said"
// kvConditions is the bucket conditions over the runtime.
type kvConditions struct{}
func (kvConditions) Said() (map[string]string, error) {
e, err := stdio.State("conditions").Get(saidKey)
if err != nil || e == nil {
return map[string]string{}, err
}
said := map[string]string{}
if err := json.Unmarshal(e.Value, &said); err != nil {
return nil, fmt.Errorf("the conditions the gate raised are not readable: %w", err)
}
return said, nil
}
func (kvConditions) PutSaid(said map[string]string) error {
_, err := stdio.State("conditions").Put(saidKey, said)
return err
}
// sayOnSeat says a condition on the operator-channel seat under the gate's own name.
func sayOnSeat(c oc.Condition) error {
subject, err := occ.ConditionSubject("mesh-delivery-gate")
if err != nil {
return err
}
raw, err := occ.EncodeCondition(c)
if err != nil {
return err
}
return stdio.SeatPublish(subject, json.RawMessage(raw), "")
}
// conditionKeyOf is the key of a stalled line's condition: its last part is the condition's kind.
func conditionKeyOf(id string) string { return "mesh-delivery-gate.delivery." + id + ".stalled" }
// conditionSaid is what a raised condition said that, when it changes, raises it again: its severity and what it needs.
// The words of a line hold durations, which change at every look and are no reason to tell the operator again.
func conditionSaid(l StalledLine) string { return severityOfLine(l) + "|" + l.H2 }
func severityOfLine(l StalledLine) string {
if l.Severity == occ.SeverityUrgent {
return occ.SeverityUrgent
}
return occ.SeverityWarning
}
// conditionOf is a stalled line as the condition the operator is told.
func conditionOf(l StalledLine) oc.Condition {
headline := "stalled: " + l.ID
if r := []rune(headline); len(r) > occ.HeadlineLength {
headline = string(r[:occ.HeadlineLength-1]) + "…"
}
needs := "read mesh-delivery.show " + l.ID + " and decide"
return oc.Condition{Key: conditionKeyOf(l.ID), Severity: severityOfLine(l), State: occ.StateRaised,
Subject: oc.ConditionSubject{Scope: "delivery", ID: l.ID}, Summary: l.Says, Headline: headline, Needs: needs,
Explanation: occ.NeedsYou + needs + ". " + l.Says + " What ends it: " + l.H2 + ".",
Resolved: "The gate lists " + l.ID + " as stalled no more."}
}
// sayConditions raises and clears the conditions of the stalled lines (see above). Outside the lock; React runs it after
// the look, so it follows every event. A condition that could not be said is said again at the next look, after
// askAgainAfter at the latest.
func (h *Holder) sayConditions() {
if h.Say == nil || h.Conditions == nil {
return
}
if h.said == nil {
said, err := h.Conditions.Said()
if err != nil {
h.Logf("[mesh-delivery] the conditions raised before cannot be read, so none is said yet: %v; asked again in %s", err, askAgainAfter)
h.again("the conditions the gate raised, read")
return
}
h.said = said
}
if at := h.nextStall(h.Now()); !at.IsZero() {
h.lookAt(at, "a record whose stalled line comes due with no event")
}
lines := map[string]StalledLine{}
for _, l := range h.Stalled() {
// One condition for an id: the most severe of its lines.
if o, ok := lines[l.ID]; !ok || (severityOfLine(o) != occ.SeverityUrgent && severityOfLine(l) == occ.SeverityUrgent) {
lines[l.ID] = l
}
}
ids := make([]string, 0, len(lines))
for id := range lines {
ids = append(ids, id)
}
sort.Strings(ids)
changed, failed := false, false
for _, id := range ids {
l, key := lines[id], conditionKeyOf(id)
said := conditionSaid(l)
if h.said[key] == said {
continue
}
if err := h.Say(conditionOf(l)); err != nil {
h.Logf("[mesh-delivery] the condition of %s could not be said: %v", id, err)
failed = true
continue
}
h.Logf("[mesh-delivery] %s is said to the operator as %s: %s", id, severityOfLine(l), l.Says)
h.said[key], changed = said, true
}
// Cleared when the line is gone: what it raised is kept in the bucket conditions, so a gate that restarts clears what ended.
var gone []string
for key := range h.said {
id := strings.TrimSuffix(strings.TrimPrefix(key, "mesh-delivery-gate.delivery."), ".stalled")
if _, ok := lines[id]; !ok {
gone = append(gone, key)
}
}
sort.Strings(gone)
for _, key := range gone {
id := strings.TrimSuffix(strings.TrimPrefix(key, "mesh-delivery-gate.delivery."), ".stalled")
c := oc.Condition{Key: key, Subject: oc.ConditionSubject{Scope: "delivery", ID: id}, State: occ.StateCleared,
Resolved: "The gate lists " + id + " as stalled no more."}
if err := h.Say(c); err != nil {
h.Logf("[mesh-delivery] the condition of %s could not be cleared: %v", id, err)
failed = true
continue
}
h.Logf("[mesh-delivery] the condition of %s is cleared: it is stalled no more", id)
delete(h.said, key)
changed = true
}
if changed {
if err := h.Conditions.PutSaid(h.said); err != nil {
h.Logf("[mesh-delivery] the conditions raised cannot be kept: %v", err)
}
}
if !failed {
h.sayFailures = 0
return
}
// A seat that keeps refusing is tried again after askAgainAfter, up to sayTries looks in a row; then only at the
// next event, and said once, loudly, in the log (the operator hears nothing while the seat refuses).
h.sayFailures++
switch {
case h.sayFailures < sayTries:
h.again("a condition that could not be said to the operator")
case h.sayFailures == sayTries:
h.Logf("[mesh-delivery] NO CONDITION REACHES THE OPERATOR: the operator-channel seat refused %d looks in a row; "+
"tried again at each event from now on", sayTries)
}
}
// sayTries is how many looks in a row a condition that could not be said is tried again on the clock.
const sayTries = 10
// nextStall is the earliest time after now when a record's stalled line comes due with nothing else happening: a record open
// past its bound, an act unanswered past its. Zero when none.
func (h *Holder) nextStall(now time.Time) time.Time {
var next time.Time
if h.Records == nil {
return next
}
consider := func(at time.Time) {
if at.After(now) && (next.IsZero() || at.Before(next)) {
next = at
}
}
kept, err := h.Records.Kept()
if err != nil {
return next
}
for _, r := range kept {
if r.Ended == nil {
consider(r.Opened.Add(recordOpenBound).Add(time.Second))
}
for _, a := range r.Acts {
if a.Outcome == "" {
consider(a.At.Add(owedBound).Add(time.Second))
}
}
}
return next
}
@@ -28,5 +28,5 @@ type FindingWriter interface {
// generated contract of the seat that defines it (A-17). It is started once the runtime serves (A-40).
func NewFindingWriter() (*views.HeldWriter[meshconditions.Finding, meshconditions.FindingCleared, meshconditions.FindingsStated, meshconditions.FindingsAskedEvent], error) {
return views.NewStdioHeldWriter(views.WriterConfig[meshconditions.Finding, meshconditions.FindingCleared, meshconditions.FindingsStated, meshconditions.FindingsAskedEvent]{
Asked: meshconditions.SubjectFindingsAsked, Module: Module, State: stdio.State("findings"), Kinds: []string{}})
Asked: meshconditions.SubjectFindingsAsked, Module: Module, State: stdio.State("findings"), Kinds: []string{HeadUntaken}})
}
@@ -3,8 +3,6 @@ package main
import (
"sync"
"time"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
)
// The holder of the seat mesh-delivery (novox/hq ADR 0239, to-be 47): from milestone G's delivery it keeps no merge states
@@ -36,13 +34,8 @@ type Holder struct {
SaySeat SeatSay
// Findings is the gate's one held writer of its own findings (findings.go); nil writes none.
Findings FindingWriter
// Say says a condition to the operator, and Conditions keeps which the gate raised (conditions.go); nil says none.
Say func(c oc.Condition) error
Conditions ConditionStore
// said is what Conditions keeps, read at the first look; sayFailures the looks in a row a condition could not be said.
// Touched by React alone.
said map[string]string
sayFailures int
// Heads is the state heads of the watchdog (heads.go); nil watches none.
Heads HeadStore
mu sync.Mutex
started time.Time
@@ -0,0 +1,256 @@
package main
// The watchdog (design 47 H §740; ADR 0682 §3; H-A-48): the gate consumes the forge bridge's head-moved and keeps, in its
// template state heads (one key `<repository>.<branch>`, value {head, since}), each head source.<branch> does not name for
// that repository, deleting the key once source.<branch> names that head. When untaken-bound passes and source.<branch>
// still does not name it, the gate raises head-untaken (scope delivery, id `<repository>.<branch>`), and clears it when a
// later revision names the repository at the newest head. The gate keeps one deadline timer (react.go), set to the
// earliest since plus the bound, and no other clock. Nothing but a merge call or gate_head_take (§742) delivers a head.
import (
"context"
"encoding/json"
"errors"
"fmt"
"sort"
"time"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-forge-bridge/forgemsg"
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"
)
// HeadUntaken is the finding of a head no merge call delivered; warning, the operator its resolver (H-A-81).
const HeadUntaken = "head-untaken"
const untakenSeverity = meshconditions.FindingSeverityWarning
// WordsUntaken are the words the finding names its cause with (§740).
const WordsUntaken = "moved outside the mesh: delivered by nothing"
// headMovedEvent is the bridge's head-moved as the gate's manifest consumes it.
var headMovedEvent = consumedFamily(forgemsg.HeadMovedEvents())
// HeldHead is one value of the state heads.
type HeldHead = seat.HeadsByRepositoryBranchValue
// HeadStore is the gate's state heads.
type HeadStore interface {
Get(key string) (*HeldHead, error)
Put(key string, v HeldHead) error
Delete(key string) error
// All are every key held with its value.
All() (map[string]HeldHead, error)
}
// kvHeads is the state heads over the runtime.
type kvHeads struct{}
func (kvHeads) Get(key string) (*HeldHead, error) {
e, err := stdio.State(seat.StateHeads).Get(key)
if err != nil || e == nil {
return nil, err
}
v, err := seat.DecodeHeadsByRepositoryBranchValue(e.Value)
if err != nil {
return nil, fmt.Errorf("heads %s is not readable: %w", key, err)
}
return &v, nil
}
func (kvHeads) Put(key string, v HeldHead) error {
_, err := stdio.State(seat.StateHeads).Put(key, v)
return err
}
func (kvHeads) Delete(key string) error { return stdio.State(seat.StateHeads).Delete(key) }
func (s kvHeads) All() (map[string]HeldHead, error) {
names, err := stdio.State(seat.StateHeads).Keys()
if err != nil {
return nil, err
}
out := map[string]HeldHead{}
for _, k := range names {
v, err := s.Get(k)
if err != nil {
return nil, err
}
if v != nil {
out[k] = *v
}
}
return out, nil
}
// headKey is a held head's key and the finding's id: `<repository>.<branch>`, the branch escaped as a key's name is.
func headKey(repository, branch string) string {
return seat.HeadsByRepositoryBranchKey(repository, keys.EscapeName(branch))
}
// HeadMoved takes one head-moved: a head source.<branch> names is let go, another is held from when it was first heard.
// A body that cannot be read is said and taken; an error only when the state could not be read or written.
func (h *Holder) HeadMoved(e stdio.Envelope) error {
m, err := forgemsg.DecodeHeadMoved(e.Body)
if err != nil {
h.Refuse(fmt.Errorf("a head-moved (%s) is not readable, so no head is watched: %w", e.Key, err))
return nil
}
return h.holdHead(m.Repository, m.Branch, m.Head)
}
// holdHead holds a branch's head of a repository until source.<branch> names it.
func (h *Holder) holdHead(repository, branch, head string) error {
if h.Heads == nil || h.Source == nil {
return nil
}
src, _, err := h.Source.Read(branch)
if err != nil {
return err
}
key := headKey(repository, branch)
if src != nil && sameCommit(src.Heads[repository], head) {
return h.letHeadGo(key, "source."+branch+" names it")
}
prev, err := h.Heads.Get(key)
if err != nil {
return err
}
next := HeldHead{Head: head, Since: h.Now().UTC()}
if prev != nil {
if prev.Head == head {
return nil
}
next.Since = prev.Since // untaken since the first head no call delivered
}
if err := h.Heads.Put(key, next); err != nil {
return err
}
h.Poke()
return nil
}
// letHeadGo deletes a held head and clears its finding.
func (h *Holder) letHeadGo(key, why string) error {
held, err := h.Heads.Get(key)
if err != nil || held == nil {
return err
}
if err := h.Heads.Delete(key); err != nil {
return err
}
return h.clearUntaken(key, why)
}
// sourceNamed lets go every held head of a branch its newest source revision names.
func (h *Holder) sourceNamed(branch string, s Source) error {
if h.Heads == nil {
return nil
}
var errs []error
for repository, commit := range s.Heads {
key := headKey(repository, branch)
held, err := h.Heads.Get(key)
if err != nil {
errs = append(errs, err)
continue
}
if held != nil && sameCommit(commit, held.Head) {
errs = append(errs, h.letHeadGo(key, fmt.Sprintf("source.%s at %d names it", branch, s.Source)))
}
}
return errors.Join(errs...)
}
// untakenBound is how long a head may stand untaken before head-untaken is raised.
func (h *Holder) untakenBound() time.Duration {
if h.Settings != nil {
if n := h.Settings().UntakenBoundMinutes; n != nil {
return time.Duration(*n) * time.Minute
}
}
return DefaultUntakenBound
}
// lookAtHeads raises head-untaken for every held head past the bound that its branch's source still does not name, and
// asks the one timer for the earliest one not yet past it; taken by React.
func (h *Holder) lookAtHeads() {
if h.Heads == nil || h.Source == nil {
return
}
held, err := h.Heads.All()
if err != nil {
h.Refuse(fmt.Errorf("the held heads cannot be read: %w", err))
h.again("heads")
return
}
names := make([]string, 0, len(held))
for k := range held {
names = append(names, k)
}
sort.Strings(names)
now := h.Now()
for _, key := range names {
v := held[key]
repository, escaped, ok := seat.ParseHeadsByRepositoryBranchKey(key)
branch, uerr := keys.UnescapeName(escaped)
if !ok || uerr != nil {
continue
}
src, _, err := h.Source.Read(branch)
if err != nil {
h.again("heads")
continue
}
if src != nil && sameCommit(src.Heads[repository], v.Head) {
if err := h.letHeadGo(key, "source."+branch+" names it"); err != nil {
h.again("heads")
}
continue
}
due := v.Since.Add(h.untakenBound())
if now.Before(due) {
h.lookAt(due, "head-untaken")
continue
}
if err := h.raiseUntaken(key, repository, branch, v); err != nil {
h.Refuse(err)
h.again("heads")
}
}
}
// raiseUntaken writes head-untaken for a held head, unless the writer holds it for that head already.
func (h *Holder) raiseUntaken(key, repository, branch string, v HeldHead) error {
if h.Findings == nil {
return nil
}
summary := fmt.Sprintf("%s %s at %s since %s: %s", repository, branch, shortOf(v.Head, 12), v.Since.UTC().Format(time.RFC3339), WordsUntaken)
for _, f := range h.Findings.Held() {
if f.Scope == FindingScope && f.ID == key && f.Kind == HeadUntaken && f.Summary == summary {
return nil
}
}
raw, _ := json.Marshal(map[string]any{"repository": repository, "branch": branch, "head": v.Head, "since": v.Since})
f := meshconditions.Finding{Scope: FindingScope, ID: key, Kind: HeadUntaken, Observer: Module, Source: headMovedEvent,
Severity: untakenSeverity, Resolver: "operator", Since: v.Since, At: h.Now().UTC(), Summary: summary,
Headline: "A head no merge call delivered", Subject: meshconditions.Subject{Scope: FindingScope, ID: key},
Explanation: "The head of " + repository + " on " + branch + " moved outside the mesh and nothing delivers it; " +
"gate_head_take takes it in by hand (" + string(raw) + ")."}
return h.Findings.Write(context.Background(), f)
}
// clearUntaken clears head-untaken for a key, when the writer holds it.
func (h *Holder) clearUntaken(key, why string) error {
if h.Findings == nil {
return nil
}
for _, f := range h.Findings.Held() {
if f.Scope == FindingScope && f.ID == key && f.Kind == HeadUntaken {
return h.Findings.Clear(context.Background(), FindingScope, key, HeadUntaken, why)
}
}
return nil
}
@@ -0,0 +1,137 @@
package main
import (
"context"
"encoding/json"
"os"
"strings"
"testing"
"time"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// memHeads is the state heads in memory.
type memHeads map[string]HeldHead
func (m memHeads) Get(key string) (*HeldHead, error) {
if v, ok := m[key]; ok {
return &v, nil
}
return nil, nil
}
func (m memHeads) Put(key string, v HeldHead) error { m[key] = v; return nil }
func (m memHeads) Delete(key string) error { delete(m, key); return nil }
func (m memHeads) All() (map[string]HeldHead, error) {
out := map[string]HeldHead{}
for k, v := range m {
out[k] = v
}
return out, nil
}
// findingsFake is the gate's held writer: what it holds.
type findingsFake struct {
held map[string]meshconditions.Finding
written int
}
func (f *findingsFake) Write(_ context.Context, x meshconditions.Finding) error {
f.held[x.Scope+"."+x.ID+"."+x.Kind] = x
f.written++
return nil
}
func (f *findingsFake) Clear(_ context.Context, scope, id, kind, _ string) error {
delete(f.held, scope+"."+id+"."+kind)
return nil
}
func (f *findingsFake) Held() []meshconditions.Finding {
var out []meshconditions.Finding
for _, x := range f.held {
out = append(out, x)
}
return out
}
// GATE-6 (design 47 H §740; acceptance test 111's gate half): a head a merge call moved raises nothing; a head pushed outside
// the mesh is held and raises head-untaken once untaken-bound passes, naming the repository, the branch, the head, since when
// and why, and starts nothing; a later merge call taking its repository in clears it. The one timer is asked for the earliest
// held head.
func TestAHeadNoMergeCallDeliveredIsAnUntakenHead(t *testing.T) {
at := time.Date(2026, 11, 20, 4, 0, 0, 0, time.UTC)
c1, c2 := strings.Repeat("1", 40), strings.Repeat("2", 40)
setup := func() (*Holder, memHeads, *findingsFake, *time.Time) {
now := at
heads := memHeads{}
fw := &findingsFake{held: map[string]meshconditions.Finding{}}
h := &Holder{Now: func() time.Time { return now }, Heads: heads, Findings: fw,
Source: &memSource{vals: map[string]Source{"main": {Source: 4, Call: "00000000000000aa", Heads: map[string]string{"novox/app": c1}}}}}
h.init()
h.SaySeat = func(string, any, string) error { return nil }
return h, heads, fw, &now
}
moved := func(head string) stdio.Envelope {
return stdio.Envelope{Key: "mesh-delivery-forge-bridge.forge.novox.app.main.head-moved",
Body: json.RawMessage(`{"v":1,"repository":"novox/app","branch":"main","head":"` + head + `"}`)}
}
t.Run("a head the source names raises nothing", func(t *testing.T) {
h, heads, fw, now := setup()
if err := h.HeadMoved(moved(c1)); err != nil {
t.Fatal(err)
}
*now = at.Add(time.Hour)
h.React()
if len(heads) != 0 || len(fw.held) != 0 {
t.Fatalf("held %+v, findings %+v", heads, fw.held)
}
})
t.Run("a head pushed outside the mesh raises head-untaken past the bound and clears on a later merge call", func(t *testing.T) {
h, heads, fw, now := setup()
if err := h.HeadMoved(moved(c2)); err != nil {
t.Fatal(err)
}
h.React()
if heads["novox/app.main"].Head != c2 || len(fw.held) != 0 || !h.wanted.at.Equal(at.Add(DefaultUntakenBound)) {
t.Fatalf("held %+v, findings %+v, next look %s", heads, fw.held, h.wanted.at)
}
*now = at.Add(DefaultUntakenBound)
h.React()
f, ok := fw.held["delivery.novox/app.main."+HeadUntaken]
if !ok || f.Severity != meshconditions.FindingSeverityWarning || f.Resolver != "operator" || !f.Since.Equal(at) ||
!strings.Contains(f.Summary, "novox/app main at 222222222222") || !strings.Contains(f.Summary, WordsUntaken) {
t.Fatalf("findings %+v", fw.held)
}
h.React()
if fw.written != 1 {
t.Fatalf("head-untaken written %d times", fw.written)
}
member := `{"repository":"novox/app","number":9,"branch":"main","head":"h","commit":"` + c2 + `"}`
if err := h.MergeCalled(stdio.Envelope{Key: "git.merge-called.0123456789abcdef", Body: json.RawMessage(
`{"call":"0123456789abcdef","by":"lead@shanks","account":"a","at":"2026-11-20T04:30:00Z","members":[` + member + `]}`)}); err != nil {
t.Fatal(err)
}
if len(heads) != 0 || len(fw.held) != 0 {
t.Fatalf("after the merge call: held %+v, findings %+v", heads, fw.held)
}
})
t.Run("the setting untaken-bound, at least one minute", func(t *testing.T) {
h, _, _, _ := setup()
n := 3
h.Settings = func() Settings { return Settings{UntakenBoundMinutes: &n} }
if h.untakenBound() != 3*time.Minute {
t.Fatalf("bound %s", h.untakenBound())
}
for raw, ok := range map[string]bool{`{"untaken-bound":1}`: true, `{"untaken-bound":0}`: false, `{"untaken-bound":1.5}`: false} {
p := t.TempDir() + "/s.json"
if err := writeFile(p, raw); err != nil {
t.Fatal(err)
}
if _, err := readSettings(p); (err == nil) != ok {
t.Errorf("%s: %v", raw, err)
}
}
})
}
func writeFile(p, s string) error { return os.WriteFile(p, []byte(s), 0o600) }
@@ -6,7 +6,7 @@ import "git.novox.be/novox/mesh-sdk/go/announce"
// issue 1790): the module says it itself, from its code, before it serves, and a reader is granted what it said
// (clause 3). A state is readable when another module's manifest reads it (keeps_test.go names the readers). keeps_test.go holds the list to the
// manifest's `state`, and keeps_integration_test.go that the module announces it on a bus.
var Kept = []announce.State{{Name: "conditions"}, {Name: "findings"}, {Name: "source", Readable: true}}
var Kept = []announce.State{{Name: "findings"}, {Name: "heads"}, {Name: "source", Readable: true}}
// announceKept says Kept through keeps, which is stdio.Keeps.
func announceKept(keeps func(...announce.State) error) error { return keeps(Kept...) }
@@ -90,7 +90,7 @@ func TestTheFourStatesMoveToTheTemplateAndTwoStayOld(t *testing.T) {
}
old := string(raw[strings.Index(string(raw), `"state": [`):])
old = old[:strings.Index(old, "]")]
for _, n := range []string{"conditions"} {
for _, n := range []string{"heads"} { // the stalled conditions' state went (H-A-48); heads is the watchdog's (§740)
if !moved[n] || strings.Contains(old, `"`+n+`"`) {
t.Errorf("%s: template state %v, old section lists it %v", n, moved[n], strings.Contains(old, `"`+n+`"`))
}
@@ -32,7 +32,7 @@ func (l *listening) get() string { l.mu.Lock(); defer l.mu.Unlock(); return l.n
// The events this owner follows: the forge bridge's word on an act owed, and the step events the delivery records are built
// from (consumer.go).
var followed = append(append([]string{owedEndedEvent, mergeCalledEvent}, stepPatterns()...), registrationChangedEvent)
var followed = append(append([]string{owedEndedEvent, mergeCalledEvent, headMovedEvent}, stepPatterns()...), registrationChangedEvent)
func main() {
settingsFile := os.Getenv("MESH_DELIVERY_GATE_SETTINGS")
@@ -57,8 +57,7 @@ func main() {
Source: kvSource{},
Owed: seatOwed{say: stdio.SeatPublish},
// The gate says what stalled to the operator itself (issue 1275, ADR 0437 §9).
Say: sayOnSeat,
Conditions: kvConditions{},
Heads: kvHeads{},
}
h.init()
h.SaySeat = stdio.SeatPublish
@@ -111,6 +110,7 @@ func run(h *Holder, l *listening) {
}
}
l.set("listening")
h.Poke() // the heads held before a stop are looked at, and the one timer armed for them (§740)
logf("[mesh-delivery] listening: %s", strings.Join(followed, ", "))
// A watched branch no source key holds starts from the forge, once at each start and at each registration change (A-401).
go startSourcesAtStart(h)
@@ -128,6 +128,9 @@ func take(h *Holder, e stdio.Envelope) error {
if h.Consumer != nil && h.Consumer.Takes(e.Key) {
return h.Consumer.Hear(e)
}
if stdio.TopicMatches(headMovedEvent, e.Key) {
return h.HeadMoved(e)
}
if stdio.TopicMatches(mergeCalledEvent, e.Key) {
return h.MergeCalled(e)
}
@@ -144,7 +144,7 @@ func TestItClaimsTheDeliverySeatAndFollowsWhatItHandles(t *testing.T) {
}
for _, c := range m.Consumes {
for _, gone := range []string{".forge.", "teller", "view", "forge-pull", "forge-status"} {
if strings.Contains(c, gone) {
if strings.Contains(c, gone) && c != headMovedEvent { // the bridge's one message is the watchdog's (H §740)
t.Errorf("the manifest still consumes %s, which G's gate does not hear (§431, §592, §593)", c)
}
}
@@ -181,10 +181,10 @@ func TestItClaimsTheDeliverySeatAndFollowsWhatItHandles(t *testing.T) {
t.Fatalf("reads %v", m.Reads)
}
// It calls no controller verb and no forge verb: the forge's reads and writes are the bridge's (ADR 0437 §8; design 47 §592).
// It uses operator-channel only to say its conditions (ADR 0437 §9, issue 1275): the teller asks no more (§431).
// It uses no operator-channel: its stalled conditions went, the watchman's record-open the one signal (H-A-48).
want := []string{"seat:git.branch", "seat:mesh-catalog.registrations", "seat:mesh-hand-acts.hand-act", WantsEntryVerb, EngineCompositionVerb}
if !reflect.DeepEqual(m.Uses, []string{"operator-channel"}) {
t.Fatalf("uses %v: operator-channel, for its conditions alone", m.Uses)
if len(m.Uses) != 0 {
t.Fatalf("uses %v", m.Uses)
}
if !reflect.DeepEqual(m.Invokes, want) {
t.Fatalf("invokes %v, wanted %v", m.Invokes, want)
@@ -73,6 +73,10 @@ func (h *Holder) nameRevision(branch, call string, heads []revisionHead) (named
if err != nil {
return Source{}, false, fmt.Errorf("source.%s cannot be written for the call %s: %w", branch, call, err)
}
// The heads the revision names are delivered: their held heads go and their head-untaken clears (§740).
if err := h.sourceNamed(branch, named); err != nil {
return named, wrote, fmt.Errorf("source.%s is at %d and its held heads are not let go: %w", branch, named.Source, err)
}
return named, wrote, nil
}
@@ -55,15 +55,15 @@ func (h *Holder) Work() {
}
}
// React takes every step the facts allow, after an event that can change what they are: the conditions of what stalled
// (conditions.go), and then the time the next look is wanted at, if any step waits on the clock. Never concurrent with itself.
// React takes every step the facts allow, after an event that can change what they are: the held heads past untaken-bound
// (heads.go), and then the time the next look is wanted at, if any step waits on the clock. Never concurrent with itself.
func (h *Holder) React() {
h.reactMu.Lock()
defer h.reactMu.Unlock()
h.wanted.mu.Lock()
h.wanted.at, h.wanted.step = time.Time{}, ""
h.wanted.mu.Unlock()
h.sayConditions()
h.lookAtHeads()
h.arm()
}
@@ -17,8 +17,14 @@ type Settings struct {
// RecordRetentionDays is how many days a delivery record is kept from when it opened (design 47 *The delivery
// record*); nil keeps DefaultRecordRetention.
RecordRetentionDays *int `json:"record-retention"`
// UntakenBoundMinutes is how many minutes a head may stand untaken before head-untaken is raised (design 47 H §740); nil
// keeps DefaultUntakenBound.
UntakenBoundMinutes *int `json:"untaken-bound"`
}
// DefaultUntakenBound is untaken-bound when the setting gives none (§740).
const DefaultUntakenBound = 10 * time.Minute
// readSettings reads the settings file; a value that is not a whole number of days, from 1 to 3650, is refused.
func readSettings(path string) (Settings, error) {
var s Settings
@@ -44,6 +50,17 @@ func readSettings(path string) (Settings, error) {
default:
return Settings{}, errors.New("record-retention is not a number")
}
switch v := loose["untaken-bound"].(type) {
case nil:
case float64:
n := int(v)
if v < 1 || v != float64(n) {
return Settings{}, errors.New("untaken-bound is not a whole number of minutes, at least 1")
}
s.UntakenBoundMinutes = &n
default:
return Settings{}, errors.New("untaken-bound is not a number")
}
return s, nil
}
@@ -1,3 +1,4 @@
{
"record-retention": 90
"record-retention": 90,
"untaken-bound": 10
}
+11 -5
View File
@@ -18,13 +18,11 @@
"consumes": [
"mesh-delivery-forge-bridge.owed.ended",
"git.merge-called.*",
"mesh-delivery-forge-bridge.forge.*.*.*.head-moved",
"mesh-delivery-indexer.take-in.taken",
"mesh-catalog.registration-changed",
"mesh-conditions.findings-asked"
],
"uses": [
"operator-channel"
],
"requires": [
{
"name": "records",
@@ -261,7 +259,7 @@
]
},
{
"name": "conditions",
"name": "heads",
"storage": "key-value",
"template": "state"
},
@@ -325,6 +323,13 @@
"maximum": 3650,
"trusted": false,
"default": 90
},
"untaken-bound": {
"type": "number",
"description": "minutes a watched branch's head may stand that no merge call delivered before the gate raises head-untaken (design 47 H §740); the gate keeps one deadline timer for the earliest.",
"minimum": 1,
"trusted": false,
"default": 10
}
},
"resources": [
@@ -341,7 +346,8 @@
"path": "${dir:state}/settings.json",
"mode": "0600",
"takes-config": [
"record-retention"
"record-retention",
"untaken-bound"
],
"merge": "json",
"template": "files/settings.json"