R11: a source-only registration's head is run on request as its check's one step

A run whose one member is a source-only registration's key
source.<owner>.<name> runs that registration's check: one step of its
kind on the build seat it names, at the repository's root, asked on the
seat's check stream as every step, its status the registration's policy's.
Its mover is the registration's key, its repository the origin and its
fingerprint the commit's root tree hash, read through the seat git's trees
as a kept call; so its step-ended names the key, escaped into one subject
part, and the tree. A candidate's revision places nothing of it; at its
turn in the queue its step is placed from its registration. A source member
beside another, or a key with no source-only registration, is refused. The
registrations follower keys a source-only registration by its key.

Builds: design 47 H2 §815, §775; H-A-408, H-A-438
This commit is contained in:
2026-11-22 01:43:20 +01:00
parent 38ad9ed84d
commit 515688cf6f
12 changed files with 280 additions and 9 deletions
@@ -6,6 +6,7 @@ import (
"fmt"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/sourcebranches"
"slices"
"strings"
"time"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
@@ -166,9 +167,19 @@ func (r *Registrations) ask(_ context.Context, _ string) (views.Answer, error) {
values := make(map[string]json.RawMessage, len(a.Registrations))
for _, reg := range a.Registrations {
v, _ := json.Marshal(reg)
values[reg.Module] = v
values[KeyOf(reg)] = v
}
return views.Answer{V: 1, Owner: seat.Seat, State: seat.StateRegistrations, Created: registrationsCreated, Values: values, At: time.Now()}, nil
}
// KeyOf is a registration's key in the seat's state registrations: its module, or source.<owner>.<name> for a
// source-only registration, which names none (design 47 H2 §815); a part reads either by Registration with that key.
func KeyOf(reg seat.Registration) string {
if reg.Module != "" {
return reg.Module
}
owner, name, _ := strings.Cut(reg.Origin, "/")
return seat.RegistrationsBySourceOwnerNameKey(owner, name)
}
func clipBytes(b []byte) string { return sourcebranches.ClipBytes(b) }
@@ -4,6 +4,7 @@ import (
"context"
"encoding/json"
"fmt"
"strings"
"sync"
"testing"
"time"
@@ -36,6 +37,12 @@ func (f *fakeRegistrations) call(key string, body any) (json.RawMessage, error)
}
a := seat.RegistrationsAnswer{Registrations: []seat.Registration{}}
for m, v := range versions {
if name, ok := strings.CutPrefix(m, "source.novox."); ok {
// A source-only registration names no module and no path (design 47 H2 §815).
a.Registrations = append(a.Registrations, seat.Registration{Version: v, Origin: "novox/" + name, Branches: []string{"main"},
Check: &seat.SourceCheck{Seat: "node-build-go", Step: "unit"}})
continue
}
a.Registrations = append(a.Registrations, seat.Registration{Module: m, Version: v, Origin: "novox/" + m, Path: "module.json", Branches: []string{"main"}})
}
return json.Marshal(a)
@@ -75,7 +82,7 @@ func TestRegistrationsAreAFirstViewThenTheirEvents(t *testing.T) {
return seat.Registration{}
}
}
f := &fakeRegistrations{versions: map[string]int64{"nats": 1, "zsh": 3}}
f := &fakeRegistrations{versions: map[string]int64{"nats": 1, "zsh": 3, "source.novox.hq": 1}}
r := NewRegistrations(f.call)
r.Follower.Wait = time.Nanosecond
r.Follower.Changed = typedChanged(func(reg seat.Registration, gone bool) {
@@ -95,10 +102,14 @@ func TestRegistrationsAreAFirstViewThenTheirEvents(t *testing.T) {
if reg, ok := r.Registration("nats"); !ok || reg.Version != 1 || reg.Origin != "novox/nats" {
t.Fatalf("first view holds nats as %+v, %v", reg, ok)
}
if all := r.All(); len(all) != 2 || all[0].Module != "nats" || all[1].Module != "zsh" {
// design 47 H2 §815: a source-only registration is held under its key source.<owner>.<name>.
if reg, ok := r.Registration("source.novox.hq"); !ok || reg.Check == nil || reg.Origin != "novox/hq" {
t.Fatalf("first view holds the source-only registration as %+v, %v", reg, ok)
}
if all := r.All(); len(all) != 3 || all[1].Module != "nats" || all[2].Module != "zsh" {
t.Fatalf("All = %+v", all)
}
for range 2 {
for range 3 {
next()
}
@@ -119,7 +130,7 @@ func TestRegistrationsAreAFirstViewThenTheirEvents(t *testing.T) {
// The answer to the ask the event starts was read before the change was written: it is asked once more.
f.mu.Lock()
f.stale = map[string]int64{"nats": 2, "zsh": 3}
f.stale = map[string]int64{"nats": 2, "zsh": 3, "source.novox.hq": 1}
f.mu.Unlock()
f.set("zsh", 4)
if err := r.Hear(ctx, changedEvent("zsh", 4)); err != nil {
@@ -5,8 +5,8 @@ import (
"strings"
"testing"
nodebuildgo "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
nodebuildgo "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo"
"mesh-delivery-pipeline/internal/pipeline"
)
@@ -12,6 +12,7 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
gitseat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/git"
"git.novox.be/novox/mesh-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/busretry"
"git.novox.be/novox/mesh-sdk/go/process"
@@ -107,3 +108,30 @@ func commitAuthor(call meshcatalogclient.Call) func(repository, commit string) (
return a.Pull.Author, nil
}
}
// rootTree reads a commit's root tree hash through the seat git's verb trees, as a kept call (design 47 H2 §775, §815,
// H-A-408): a source-only check's fingerprint. An answer naming an error, or no root, is an error, never an empty hash.
func rootTree(calls keptCaller) func(repository, commit string) (string, error) {
return func(repository, commit string) (string, error) {
key := "seat:" + gitseat.Seat + "." + gitseat.VerbTrees
raw, err := calls.CallKept(key, gitseat.TreesInput{Repository: repository, Commit: commit})
if err != nil {
return "", err
}
answer, said, ok := buscalls.Unwrap(raw)
if !ok {
return "", fmt.Errorf("%s answered: %s", key, said)
}
var a gitseat.TreesAnswer
if err := json.Unmarshal(answer, &a); err != nil {
return "", fmt.Errorf("the answer of %s is not its seat's: %w", key, err)
}
switch {
case a.Error != "":
return "", fmt.Errorf("%s (%s)", a.Error, a.ErrorKind)
case a.Root == "":
return "", fmt.Errorf("%s names no root tree of %s at %s", key, repository, commit)
}
return a.Root, nil
}
}
@@ -180,7 +180,7 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
Kept: keptReader(ctx, kept), Toolchain: toolchainReader(ctx, toolchains),
Fills: fills, Recovered: kvRecoveries{ctx, recovered}.Has, Holders: rv.Holders.Holders, Ended: hearer.EndedAtPlacing,
Findings: rv.Findings, Observer: cred.Module, // a mover waiting on its registration is registration-missing (H-A-262)
Unfinished: unfinished}
Unfinished: unfinished, RootTree: rootTree(calls)}
hearer.Unfinished = unfinished
hearer.AskSteps = starter.AskSteps
hearer.RegistrationWaits = func() { starter.JudgeRegistrationMissing(store) } // at every end (H-A-265 (4))
@@ -300,6 +300,10 @@ func (s *Starter) placeQueued(wkey, key string, view func(branch string) (Half,
}
s.logf("%s is placed: its turn under pipelines-at-once came", key)
s.sayQueueWait(seat.EventWaitEnded, p, now, "ran")
if isSourceRun(p) {
// A source-only check places its one step from its registration (design 47 H2 §815).
return true, s.placeSourceRun(key)
}
if p.Run != "" {
// A run's steps are placed from its candidate's newest revision, as at the runner's start (A-222).
if s.RunTurn != nil {
@@ -60,6 +60,23 @@ func (s *Starter) Run(caller string, in seat.RunInput, newID func() (string, err
}
movers = append(movers, seat.Mover{Module: m.Module, Commit: m.Commit})
}
// A source-only registration's head is checked alone, by its registration's one step (design 47 H2 §815, H-A-408).
checksSource := false
for _, m := range in.Members {
if IsSourceKey(m.Module) {
checksSource = true
}
}
if checksSource {
if len(in.Members) != 1 {
return seat.RunAnswer{}, fmt.Errorf("a source-only registration's head is run alone, never with another member: nothing was started")
}
m, err := s.sourceMover(in.Members[0])
if err != nil {
return seat.RunAnswer{}, err
}
movers = []seat.Mover{m}
}
// Its source is the branch's newest source revision, what the run is checked against (H-A-85): a branch with none yet
// is refused, naming it.
var source int64
@@ -93,6 +110,11 @@ func (s *Starter) Run(caller string, in seat.RunInput, newID func() (string, err
}
if place {
s.ran(key)
if checksSource {
if err := s.placeSourceRun(key); err != nil {
s.logf("the source-only check %s is not placed: %v", key, err)
}
}
} else {
s.logf("the run %s waits its turn under pipelines-at-once, sequence %d", id, p.Seq)
s.sayQueueWait(seat.EventWaitHeld, p, now, "")
@@ -206,7 +228,7 @@ func (s *Starter) placeRunPipeline(key, id string, ev catalog.CatalogRevisionEve
if err != nil {
return false, fmt.Errorf("the pipeline %s is not read: %w", key, err)
}
if p.Run != id || p.Outcome != seat.PipelineOutcomeRunning || p.Revision != 0 {
if p.Run != id || p.Outcome != seat.PipelineOutcomeRunning || p.Revision != 0 || isSourceRun(p) {
return false, nil
}
now := s.now()
@@ -2,12 +2,14 @@ package pipeline
import (
"errors"
"slices"
"strings"
"testing"
builds "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshbuilds"
catalog "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
nodebuildgo "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo"
)
// RN12 (design 47 G §64, §373, §420; A-180, A-193; H H-A-83, H-A-85): `run` writes the run's one pipeline at once, keyed
@@ -136,3 +138,80 @@ func TestRunOnRequest(t *testing.T) {
t.Errorf("its pipeline is %s, want failed", p.Outcome)
}
}
// design 47 H2 §815, H-A-408: a run of a source-only registration's head runs its registration's one step on the seat its
// check names, at the repository's root, as a pipeline step: its mover is the registration's key and its fingerprint the
// commit's root tree hash, so its step events name both. A source member beside another, or a key with no source-only
// registration, is refused and starts nothing.
func TestASourceOnlyHeadRunsItsChecksOneStep(t *testing.T) {
store := memCreated{memStore{}}
var said []string
var stepEnded []seat.StepEvent
asks := &stepAsks{}
hq := catalog.Registration{Origin: "novox/hq", Branches: []string{"main"}, Check: &catalog.SourceCheck{Seat: "node-build-go", Step: "unit"},
Policy: catalog.Policy{Steps: catalog.StepStatuses{Unit: "required"}}}
s := &Starter{Pipelines: store, Store: store, Steps: asks, Name: "the-runner",
Registration: func(m string) (catalog.Registration, bool) { return hq, m == "source.novox.hq" },
RootTree: func(repository, commit string) (string, error) {
if repository != "novox/hq" || commit != "c9" {
return "", errors.New("asked " + repository + " " + commit)
}
return "t0ee", nil
},
Say: func(subject string, body any) error {
said = append(said, subject[strings.Index(subject, ".event.")+7:])
if ev, ok := body.(seat.StepEvent); ok {
stepEnded = append(stepEnded, ev)
}
return nil
}}
id := func() (string, error) { return "0a1b2c3d4e5f", nil }
view := func(string) (Half, bool) { return Half{Source: 41}, true }
for _, members := range [][]seat.Member{{{Module: "source.novox.hq", Commit: "c9", Branch: "main"}, {Module: "app", Commit: "c1", Branch: "main"}},
{{Module: "source.novox.other", Commit: "c9", Branch: "main"}}} {
if _, err := s.Run("sessions", seat.RunInput{Members: members}, id, view); err == nil {
t.Errorf("a run of %+v was taken", members)
}
}
if len(store.memStore) != 0 {
t.Fatalf("a refused run wrote %v", store.memStore)
}
a, err := s.Run("sessions", seat.RunInput{Members: []seat.Member{{Module: "source.novox.hq", Commit: "c9", Branch: "main"}}}, id, view)
if err != nil {
t.Fatal(err)
}
p, _, _ := store.Get(a.Pipelines[0])
if len(p.Movers) != 1 || p.Movers[0].Fingerprint != "t0ee" || p.Movers[0].Repository != "novox/hq" || len(p.Steps) != 1 ||
p.Steps[0].Step != "unit" || p.Steps[0].Status != "required" || p.Steps[0].Seat != "node-build-go" || p.Steps[0].Outcome != seat.StepResultOutcomeRunning {
t.Fatalf("the source-only check's pipeline = %+v", p)
}
if len(asks.asks) != 1 {
t.Fatalf("asked %d steps, want the check's one", len(asks.asks))
}
ask := asks.asks[0].(nodebuildgo.StepAsk)
if ask.Step.Fetch.Repository != "novox/hq" || ask.Step.Fetch.Dir != "" || ask.Step.Fingerprint != "t0ee" || ask.Step.Module != "source.novox.hq" ||
!strings.Contains(asks.at[0], "node-build-go") {
t.Errorf("the check's ask = %+v on %s", ask.Step, asks.at[0])
}
// A candidate's revision of the run places nothing more: the check is its registration's, never a catalog entry's.
if n, err := s.PlaceRun(catalog.CatalogRevisionEvent{Kind: "candidate", Group: "run-" + a.Run, Revision: 12}, Half{}, func(string) (Half, bool) { return Half{}, false }); n != 0 || err != nil {
t.Errorf("a candidate's revision placed the source-only check again: %d, %v", n, err)
}
// Its step-ended names the registration's key, escaped into one subject part, and the root tree (H-A-408).
h := &Hearer{Store: store, Say: s.Say}
if _, err := h.OnStepEnded(goSeat, goSeat.Prefix+"n1", StepEnded{ID: p.Steps[0].Ask, Ask: p.Steps[0].Ask, Node: "n1", Pipeline: p.Pipeline, Module: "source.novox.hq", Commit: "c9", Fingerprint: "t0ee", Step: "unit", Outcome: "passed"}); err != nil {
t.Fatal(err)
}
var ended *seat.StepEvent
for i := range stepEnded {
if stepEnded[i].Result.Outcome == "passed" {
ended = &stepEnded[i]
}
}
if ended == nil || ended.Module != "source.novox.hq" || ended.Fingerprint != "t0ee" || !slices.Contains(said, seat.EventStepEnded+".source=2enovox=2ehq.main.c9") {
t.Errorf("step-ended %+v said on %v", ended, said)
}
if q, _, _ := store.Get(a.Pipelines[0]); q.Outcome != seat.PipelineOutcomePassed {
t.Errorf("the source-only check's pipeline ended %q after its one step passed", q.Outcome)
}
}
@@ -0,0 +1,110 @@
package pipeline
import (
"errors"
"fmt"
"strings"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
nodebuildgo "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo"
sdkstep "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
)
// SourcePrefix begins the key of a source-only registration, source.<owner>.<name> (design 47 H2 §815): a run whose one
// member names such a key is that registration's check, one step on the seat its check names.
const SourcePrefix = "source."
// IsSourceKey says whether a member's module is a source-only registration's key.
func IsSourceKey(module string) bool { return strings.HasPrefix(module, SourcePrefix) }
// isSourceRun says whether p is a run on request of a source-only registration's head.
func isSourceRun(p seat.Pipeline) bool {
return p.Run != "" && len(p.Movers) == 1 && IsSourceKey(p.Movers[0].Module)
}
// sourceMover is the one mover of a source-only check (design 47 H2 §815, H-A-408): the registration's key as its module,
// its origin as the repository, and as its fingerprint the commit's root tree hash, the source's whole build input, read
// through RootTree. A key with no source-only registration, or one with no check, is refused.
func (s *Starter) sourceMover(m seat.Member) (seat.Mover, error) {
var reg = s.sourceRegistration(m.Module)
if reg == nil {
return seat.Mover{}, fmt.Errorf("%s is no source-only registration with a check: nothing was started", m.Module)
}
if s.RootTree == nil {
return seat.Mover{}, errors.New("the runner reads no commit's root tree, which a source-only check is fingerprinted by")
}
tree, err := s.RootTree(reg.Origin, m.Commit)
if err != nil {
return seat.Mover{}, fmt.Errorf("the root tree of %s at %s is not read, which its check is fingerprinted by: %w", reg.Origin, m.Commit, err)
}
if tree == "" {
return seat.Mover{}, fmt.Errorf("the seat git names no root tree of %s at %s", reg.Origin, m.Commit)
}
return seat.Mover{Module: m.Module, Commit: m.Commit, Repository: reg.Origin, Fingerprint: tree}, nil
}
func (s *Starter) sourceRegistration(key string) *sourceReg {
if s.Registration == nil {
return nil
}
reg, ok := s.Registration(key)
if !ok || reg.Check == nil || reg.Module != "" {
return nil
}
return &sourceReg{Origin: reg.Origin, Seat: reg.Check.Seat, Step: reg.Check.Step, Status: Status(reg, "", reg.Check.Step)}
}
type sourceReg struct{ Origin, Seat, Step, Status string }
// placeSourceRun places a source-only check's one step (design 47 H2 §815): its registration's check, a step kind on a build
// seat, run at the repository's root at the head's commit, asked on the seat's check stream as every step. Its status is
// the registration's policy's; the pipeline ends when the step ends. A run already placed places nothing again.
func (s *Starter) placeSourceRun(key string) error {
for {
p, rev, err := s.Store.Get(key)
if err != nil {
return fmt.Errorf("the pipeline %s is not read: %w", key, err)
}
if !isSourceRun(p) || p.Outcome != seat.PipelineOutcomeRunning || len(p.Steps) > 0 {
return nil
}
m, now := p.Movers[0], s.now()
reg := s.sourceRegistration(m.Module)
st := seat.StepResult{Module: m.Module, Outcome: seat.StepResultOutcomeCouldNotRun, Started: &now, Ended: &now}
var asks []Asked
language, lerr := "", error(nil)
if reg != nil {
st.Step, st.Status, st.Seat = reg.Step, reg.Status, reg.Seat
language, lerr = sdkstep.AskLanguageOfSeat(reg.Seat)
}
switch {
case reg == nil:
st.Step, st.Status, st.Why = seat.StepResultStepUnit, seat.StepResultStatusRequired, m.Module+" is no longer a source-only registration with a check"
case lerr != nil:
st.Why = lerr.Error()
case reg.Status == seat.StepResultStatusBypass:
st.Outcome, st.Why = seat.StepResultOutcomeBypassed, "bypassed by the registration's policy"
default:
st.Outcome, st.Ended, st.AskedAt = seat.StepResultOutcomeRunning, nil, &now
st.Ask = keptAskID(startOf(p, now), p.Pipeline, m.Module, "", st.Step, 0)
asks = append(asks, Asked{Seat: reg.Seat, ID: st.Ask, Commit: m.Commit, Ask: nodebuildgo.StepAsk{V: 1, ID: st.Ask, Asker: s.Name,
Kind: "step", Language: language, At: &now, Step: &nodebuildgo.StepRun{Branch: p.Branch, Commit: m.Commit,
Fetch: nodebuildgo.Fetch{Repository: m.Repository, Commit: m.Commit}, Fingerprint: m.Fingerprint, Module: m.Module,
Pipeline: p.Pipeline, Source: p.Source, Step: st.Step}}})
}
p.Steps = []seat.StepResult{st}
if _, err := s.Store.Update(key, p, rev); errors.Is(err, ErrChanged) {
continue
} else if err != nil {
return fmt.Errorf("the pipeline %s cannot be written: %w", key, err)
}
s.sayStartedPipeline(p, now)
if len(asks) == 0 {
return s.endedAtPlacing(p, []int{0})
}
if s.Steps != nil {
return s.askSteps(key, asks)
}
return nil
}
}
@@ -166,7 +166,10 @@ type Starter struct {
// RegistrationsRead says whether the registrations view's first read is in (design 47 H2 §788): before it no
// registration-missing is judged and "registrations not yet read" is said once; nil reads as read.
RegistrationsRead func() bool
unreadSaid atomic.Bool
// RootTree reads a commit's root tree hash through the seat git's trees: a source-only check's fingerprint (design 47
// H2 §815, H-A-408).
RootTree func(repository, commit string) (string, error)
unreadSaid atomic.Bool
// Steps asks each build seat for its step, as the pipeline's asking half (§22, §24); Name is the runner's own name as an
// asker.
Steps StepAsker
@@ -101,6 +101,8 @@ func TestManifest(t *testing.T) {
"seat:mesh-grants.grants-for",
// RN11 (§33, A-191): the author of a failed head, read as the forge records it.
"seat:git.pull",
// design 47 H2 §815, H-A-408: a source-only check is fingerprinted by its commit's root tree.
"seat:git.trees",
// RN8 (§31, §350; A-182): a superseded step's ask dropped of the build seat that holds it.
"seat:node-build-go.drop", "seat:node-build-node.drop", "seat:node-build-image.drop",
// A-74, A-89: who holds the seat operator-channel, whose state asks holds the router's record of the approval ask.
@@ -82,6 +82,7 @@
"seat:mesh-catalog.revision",
"seat:mesh-hand-acts.hand-act",
"seat:git.pull",
"seat:git.trees",
"seat:mesh-module-assigner.assignments",
"seat:mesh-grants.grants-for",
"seat:mesh-builds.step",