Files
mesh-host/internal/agent/order.go
T
jschoubben dd2b3a16df MH-2b: the node-engine reads the want by the real contract: composed, kept-on and newest go
A want carries no composed digest, no keeping node and no newest build (design 47 H 750,
H-A-37): the agent takes the digest from the composition the node made for the want's
build, the shadow's resolution around a missing entry (A-405) and KeptBuildOf's keeping node
go, and the artifact is fetched from the store. Tests of the removed behaviour go.

Builds: design 47 H §750; H-A-37

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 03:09:22 +01:00

250 lines
8.7 KiB
Go

package agent
import (
"context"
"fmt"
"sort"
"strconv"
"strings"
"git.novox.be/novox/mesh-contracts/go/clients/nodeengineclient"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
)
// The order on one machine (design 47 H §771, H-A-46, H-A-59): the node-engine applies its changed wants, one module at a time,
// the node's own composition first, a reverted module, then the holder of the seat node-backup and the bus module, then each pipeline's wants by
// rank (the older source first), then the rest by name, and its own module last. It reads the order from the wants alone and
// consumes no event of the runner.
const (
// SeatBackup and SeatBus are the seats whose holders are applied first on a machine: found by the claim of the manifest the
// composer holds for the module, never by a module's name.
SeatBackup = "node-backup"
SeatBus = "mesh-broker"
)
// order classes: the lower is applied first.
const (
classNode = iota
classRevert
classBackup
classBus
classPipeline
classRest
classOwn
)
// rowOf is one module's place in the order.
type rowOf struct {
module string
class int
pipeline string
branch string
source int64
rank int64
}
// changedLocked says a module's want is not applied yet: it is there, and what runs of the module is not what it names
// (a.mu held).
func (a *Agent) changedLocked(module string) bool {
w, ok := a.wants[module]
if !ok || !w.Present {
return false
}
r, runs := a.running[module]
if w.Want.Removed {
return runs && r.Phase != nodeengineclient.PhaseRemoved
}
if module == NodeModule {
return !runs || r.Composed != w.Composed || r.Phase == nodeengineclient.PhaseFailed
}
return !(runs && r.Fp == w.Want.Fp && r.Phase != nodeengineclient.PhaseRemoved && r.Phase != nodeengineclient.PhaseFailed)
}
// revertLocked says a module's want is a revert: it names no pipeline and no rank (a placement's build) and a fingerprint other
// than the one the module runs (design 47 H §771, H-A-68; a.mu held).
func (a *Agent) revertLocked(module string) bool {
w, ok := a.wants[module]
if !ok || !w.Present || w.Want.Removed || module == NodeModule || w.Want.Pipeline != "" || w.Want.Rank > 0 || w.Want.Fp == "" {
return false
}
r, runs := a.running[module]
return runs && r.Phase != nodeengineclient.PhaseRemoved && r.Fp != "" && r.Fp != w.Want.Fp
}
// waitsOn is the modules a want waits on: the changed wants of the same pipeline of a lower rank, that did not fail here
// (a.mu held). A want of no pipeline or of no rank waits on none.
func (a *Agent) waitsOnLocked(module string) []string {
w := a.wants[module].Want
if w.Pipeline == "" || w.Rank <= 0 {
return []string{}
}
out := []string{}
for m, other := range a.wants {
if m == module || other.Want.Pipeline != w.Pipeline || other.Want.Rank <= 0 || other.Want.Rank >= w.Rank || !a.changedLocked(m) {
continue
}
// A lower rank that failed here ends the wait; one retried for a failure of the bus does not (it still waits).
if att, tried := a.attempt[m]; tried && att.FP == other.Want.Fp && !att.Held && !att.Transient && !a.runsLocked(m) {
continue
}
out = append(out, m)
}
sort.Strings(out)
return out
}
// runsLocked says the module runs what its want names (a.mu held).
func (a *Agent) runsLocked(module string) bool {
r, runs := a.running[module]
return runs && r.Fp == a.wants[module].Want.Fp && r.Phase != nodeengineclient.PhaseRemoved && r.Phase != nodeengineclient.PhaseFailed
}
// pipelineParts splits a pipeline's key `<branch>.<source>` into its branch and its source number.
func pipelineParts(key string) (branch string, source int64) {
i := strings.LastIndex(key, ".")
if i < 0 {
return key, 0
}
n, err := strconv.ParseInt(key[i+1:], 10, 64)
if err != nil {
return key, 0
}
return key[:i], n
}
// claims says whether the manifest the node holds for the module claims the seat; a module whose manifest is not read claims none.
func (a *Agent) claims(ctx context.Context, module, seat string) bool {
if a.env.Claims == nil || module == NodeModule {
return false
}
claims, known := a.env.Claims(ctx, module, seat)
return claims && known
}
// orderOf is the modules in the order they are applied, each with its place and why; modules are the ones asked for, whatever
// the state of their wants.
func (a *Agent) orderOf(ctx context.Context, modules []string) ([]rowOf, map[string]string) {
own := ""
if a.env.OwnModule != nil {
own = a.env.OwnModule()
}
// The claims are asked of the composer before a.mu is taken: it asks what the agent runs.
backups, buses := map[string]bool{}, map[string]bool{}
for _, m := range modules {
backups[m] = a.claims(ctx, m, SeatBackup)
buses[m] = !backups[m] && a.claims(ctx, m, SeatBus)
}
a.mu.Lock()
defer a.mu.Unlock()
reverts := map[string]bool{}
for _, m := range modules {
reverts[m] = a.revertLocked(m)
}
rows := make([]rowOf, 0, len(modules))
why := map[string]string{}
for _, m := range modules {
w := a.wants[m].Want
r := rowOf{module: m, class: classRest}
switch {
case m == NodeModule:
r.class, why[m] = classNode, "the node's own composition, which every module's openings and accounts depend on"
case m == own && own != "":
r.class, why[m] = classOwn, "the node-engine's own module, applied last"
case reverts[m]:
r.class, why[m] = classRevert, "a revert to the build "+w.Fp+", applied first"
case backups[m]:
r.class, why[m] = classBackup, "holds the seat "+SeatBackup+", applied first"
case buses[m]:
r.class, why[m] = classBus, "claims the seat "+SeatBus+", the bus module, applied first"
case w.Pipeline != "" && w.Rank > 0:
r.class, r.pipeline, r.rank = classPipeline, w.Pipeline, w.Rank
r.branch, r.source = pipelineParts(w.Pipeline)
why[m] = fmt.Sprintf("rank %d of the pipeline %s", w.Rank, w.Pipeline)
default:
why[m] = "in no pipeline: by name"
}
rows = append(rows, r)
}
sort.SliceStable(rows, func(i, j int) bool {
x, y := rows[i], rows[j]
if x.class != y.class {
return x.class < y.class
}
if x.class == classPipeline {
if x.source != y.source {
return x.source < y.source
}
if x.branch != y.branch {
return x.branch < y.branch
}
if x.rank != y.rank {
return x.rank < y.rank
}
}
return x.module < y.module
})
return rows, why
}
// ApplyOrder is the order this machine's node-engine will apply its changed wants in, one row per want not applied yet (the verb
// apply-order of the seat node-engine, design 47 H §771).
func (a *Agent) ApplyOrder(ctx context.Context) []nodeengine.ApplyOrderAnswerOrderItem {
a.mu.Lock()
var modules []string
for m := range a.wants {
if a.changedLocked(m) {
modules = append(modules, m)
}
}
a.mu.Unlock()
rows, why := a.orderOf(ctx, modules)
out := make([]nodeengine.ApplyOrderAnswerOrderItem, 0, len(rows))
a.mu.Lock()
defer a.mu.Unlock()
for i, r := range rows {
w := a.wants[r.module].Want
item := nodeengine.ApplyOrderAnswerOrderItem{Module: r.module, Position: int64(i + 1), Why: why[r.module], Waits: a.waitsOnLocked(r.module)}
if r.class == classPipeline || (w.Pipeline != "" && w.Rank > 0) {
item.Pipeline, item.Rank = w.Pipeline, w.Rank
}
out = append(out, item)
}
return out
}
// placingHave writes a module's have held for the lower rank of its pipeline it waits on, once per distinct wait, the module
// keeping what it runs (design 47 H §771, H-A-59). The reason `placing` is a hold the engine judges again at a start.
func (a *Agent) placingHave(ctx context.Context, module string, waits []string) {
on := strings.Join(waits, ", ")
words := fmt.Sprintf("%s waits for %s of its pipeline, of a lower rank, to be applied on this machine", module, on)
a.mu.Lock()
if a.placing == nil {
a.placing = map[string]string{}
}
same := a.placing[module] == on
a.placing[module] = on
prev, runs := a.running[module]
a.mu.Unlock()
if same {
return
}
if !runs {
if h, found, _ := a.readHave(ctx, module); found {
prev.Fp, prev.Composed = h.FP, h.Composed
}
}
a.env.Say(words)
a.writeHave(ctx, Have{Module: module, FP: prev.Fp, Composed: prev.Composed, Phase: string(nodeengineclient.PhaseHeld), Detail: words,
Wait: &nodeengine.Wait{Owner: nodeengine.Seat, Step: nodeengine.WaitStepPlacing, Reason: nodeengine.WaitStepPlacing, On: on, Since: a.now(), Words: words}})
}
// endPlacing ends the wait of a module whose want was held for a lower rank and is judged again: when its have still carries the
// wait and the module runs a build, the have says it running again, the wait ended.
func (a *Agent) endPlacing(ctx context.Context, module string) {
h, found, _ := a.readHave(ctx, module)
if !found || h.Wait == nil || h.Wait.Reason != nodeengine.WaitStepPlacing || h.FP == "" {
return
}
a.writeHave(ctx, Have{Module: module, FP: h.FP, Composed: h.Composed, Phase: string(nodeengineclient.PhaseRunning)})
}