contracts: shared on a step's end and progress, ask and shared on stands, the four run verbs (C1)

A step that read a composition run or a test run names it in shared, so the result is
traced to the one ask that made it; stands names what a reading step waits on; the
runs' read and drop are seat verbs with their class (seatgen regenerated, no hand edit).

Builds: design 47 G §728, §729, §731; A-468d, A-468e, A-469f, A-469q, A-469r, A-469t, A-469u, A-469v
This commit is contained in:
2026-11-17 11:15:55 +01:00
parent c17ccd3070
commit 8fa1b8aee7
14 changed files with 1447 additions and 24 deletions
@@ -15,18 +15,20 @@ import (
const Seat = "mesh-pipeline-runner"
const (
VerbRun = "run"
VerbStart = "start"
VerbShow = "show"
VerbList = "list"
VerbStands = "stands"
VerbWhyCarried = "why-carried"
VerbKept = "kept"
VerbReview = "review"
VerbRerun = "rerun"
VerbAccept = "accept"
VerbCancel = "cancel"
VerbAskAgain = "ask-again"
VerbRun = "run"
VerbStart = "start"
VerbShow = "show"
VerbList = "list"
VerbStands = "stands"
VerbWhyCarried = "why-carried"
VerbKept = "kept"
VerbReview = "review"
VerbRerun = "rerun"
VerbAccept = "accept"
VerbCancel = "cancel"
VerbAskAgain = "ask-again"
VerbTestRuns = "test-runs"
VerbTestRunsDrop = "test-runs-drop"
)
const (
@@ -45,7 +47,7 @@ const (
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbRun, VerbStart, VerbShow, VerbList, VerbStands, VerbWhyCarried, VerbKept, VerbReview, VerbRerun, VerbAccept, VerbCancel, VerbAskAgain}
return []string{VerbRun, VerbStart, VerbShow, VerbList, VerbStands, VerbWhyCarried, VerbKept, VerbReview, VerbRerun, VerbAccept, VerbCancel, VerbAskAgain, VerbTestRuns, VerbTestRunsDrop}
}
// Events is every event published on the seat's subject: a new copy each call.
@@ -596,6 +598,26 @@ type RunStarted struct {
V int64 `json:"v"`
}
// SharedAskedBy is the step that asked the run, for a test step reading another's run.
type SharedAskedBy struct {
// its artifact, <module>:<artifact>
Artifact string `json:"artifact"`
// its pipeline's key
Pipeline string `json:"pipeline"`
}
// Shared is a run whose result a step took or waits on, asked once for every step that reads it (design 47 G §729, A-469t): for a composition step one per machine composed, `run` the `composition-runs` key and `ask` its run ask's id; for a test step one with no machine, `run` the `test-runs` key, `ask` its build seat ask's id and `asked-by` the step that asked the run, left out for that step itself.
type Shared struct {
// the id of the run's ask of the build seat
Ask string `json:"ask"`
// the step that asked the run, for a test step reading another's run
AskedBy *SharedAskedBy `json:"asked-by,omitempty"`
// the machine composed, for a composition run
Machine string `json:"machine,omitempty"`
// the run's key: in the assigner's composition-runs, or the runner's test-runs
Run string `json:"run"`
}
// StepEvent is a step's start or end: the step, its status, its outcome, its fingerprint, its test counts, what a carried result was carried from, and for a rerun that it is one and its proved caller; a bypassed step too.
type StepEvent struct {
At *time.Time `json:"at,omitempty"`
@@ -645,7 +667,9 @@ type StepResult struct {
// the step was asked again by the runner's rerun
Rerun bool `json:"rerun,omitempty"`
// the seat that serves the step, whose holder alone may end it (ADR 0666 section 21)
Seat string `json:"seat,omitempty"`
Seat string `json:"seat,omitempty"`
// the run the step read or asked for every step that reads it: a composition step's per machine, as mesh-wants' step-ended names them; a test step's one, with asked-by when another step asked it (design 47 G §726, §729; A-468d, A-468e, A-469t)
Shared []Shared `json:"shared,omitempty"`
Started *time.Time `json:"started,omitempty"`
// the step's status in the module's policy
Status string `json:"status"`
@@ -698,6 +722,56 @@ type TestCounts struct {
Unit int64 `json:"unit,omitempty"`
}
// TestRun is one test run of a candidate, level and tested packages, a key of the runner's state test-runs (design 47 G §725, §728; A-469u).
type TestRun struct {
// the id of the build seat's ask
Ask string `json:"ask,omitempty"`
// the share digest (design 47 G §724)
Digest string `json:"digest"`
Ended *time.Time `json:"ended,omitempty"`
// why the packages are not named: the run's output is gone
Gone string `json:"gone,omitempty"`
// the key, <candidate key>.<level>.<digest>, each part escaped as a key's name
Key string `json:"key"`
Level string `json:"level"`
// the node whose holder took the ask
Node string `json:"node,omitempty"`
Outcome string `json:"outcome,omitempty"`
// the run's output object, by its name in test-runs-objects
Output string `json:"output,omitempty"`
// the packages it ran, read from its output object
Packages []TestRunPackage `json:"packages,omitempty"`
// the steps reading the run
Readers []TestRunReader `json:"readers,omitempty"`
// the outcome's words
Said string `json:"said,omitempty"`
// the build seat asked
Seat string `json:"seat,omitempty"`
Started *time.Time `json:"started,omitempty"`
Tests *TestCounts `json:"tests,omitempty"`
}
// The values of TestRun's level.
const (
TestRunLevelLint = "lint"
TestRunLevelUnit = "unit"
TestRunLevelIntegration = "integration"
)
// TestRunPackage is one package a test run ran, with its digest (design 47 G §724).
type TestRunPackage struct {
Digest string `json:"digest"`
Package string `json:"package"`
}
// TestRunReader is a test step reading a test run (design 47 G §725).
type TestRunReader struct {
// its artifact, <module>:<artifact>
Artifact string `json:"artifact"`
// its pipeline's key
Pipeline string `json:"pipeline"`
}
// ToolchainUsed is the toolchain a build was made with: the language, the installed version and the build module's recipe.
type ToolchainUsed struct {
Language string `json:"language"`
@@ -708,6 +782,8 @@ type ToolchainUsed struct {
// Wait is a step's wait, held and ended; a wait on a person is said as waiting on that person, never a stall (ADR 0283).
type Wait struct {
Artifact string `json:"artifact,omitempty"`
// the step's own ask, where it has one (design 47 G §731)
Ask string `json:"ask,omitempty"`
// the watched branch, or the branch of a run on request
Branch string `json:"branch"`
// the commit the module's entry was last changed at
@@ -726,8 +802,10 @@ type Wait struct {
// the catalog graph revision of the branch the pipeline runs for
Revision int64 `json:"revision,omitempty"`
// the run on request's id, for a pipeline of a run; such a pipeline delivers nothing
Run string `json:"run,omitempty"`
Since time.Time `json:"since"`
Run string `json:"run,omitempty"`
// the run the step waits on, where the runner knows it: a test step's run key and ask (design 47 G §731, A-469v)
Shared []Shared `json:"shared,omitempty"`
Since time.Time `json:"since"`
// the source revision of the watched branch; the pipeline is keyed by it (ADR 0666 section 9)
Source int64 `json:"source,omitempty"`
// a pipeline step a wait inside a pipeline is in
@@ -977,6 +1055,44 @@ type AskAgainAnswer struct {
Result StepResult `json:"result"`
}
// TestRunsInput is what test-runs takes.
type TestRunsInput struct {
// the candidate's key
Candidate string `json:"candidate,omitempty"`
Digest string `json:"digest,omitempty"`
Level string `json:"level,omitempty"`
Module string `json:"module,omitempty"`
}
// The values of TestRunsInput's level.
const (
TestRunsInputLevelLint = "lint"
TestRunsInputLevelUnit = "unit"
TestRunsInputLevelIntegration = "integration"
)
// TestRunsAnswer is what test-runs answers.
type TestRunsAnswer struct {
Fill Fill `json:"fill"`
Runs []TestRun `json:"runs"`
}
// TestRunsDropInput is what test-runs-drop takes.
type TestRunsDropInput struct {
// the run's key in test-runs
Key string `json:"key"`
// why, written with the caller the runtime proves in the hand-act log
Why string `json:"why"`
}
// TestRunsDropAnswer is what test-runs-drop answers.
type TestRunsDropAnswer struct {
// the readers it ended
Ended []TestRunReader `json:"ended,omitempty"`
// the entry deleted
Run TestRun `json:"run"`
}
// PipelineStartedEvent is the body of the event pipeline-started.
type PipelineStartedEvent = PipelineStarted
@@ -37,6 +37,12 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v WaitHeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-pipeline-runner\\.event\\.wait-held\\.[^.*> ]+\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "the wait ended answered", subject: "mesh.seat.mesh-pipeline-runner.event.wait-ended.nats.main.0123456789abcdef0123456789abcdef01234567", given: "{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"how\":\"answered\",\"module\":\"nats\",\"on\":\"person\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"since\":\"2026-11-10T10:10:00Z\",\"source\":3589,\"step\":\"approval\",\"v\":1,\"who\":\"the operator\"}", wire: "{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"how\":\"answered\",\"module\":\"nats\",\"on\":\"person\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"since\":\"2026-11-10T10:10:00Z\",\"source\":3589,\"step\":\"approval\",\"v\":1,\"who\":\"the operator\"}",
decode: func(b []byte) (any, error) { var v WaitEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-pipeline-runner\\.event\\.wait-ended\\.[^.*> ]+\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "C1/AC2 a test step started reading a test run, naming its run and ask", subject: "mesh.seat.mesh-pipeline-runner.event.step-started.nats.main.0123456789abcdef0123456789abcdef01234567", given: "{\"at\":\"2026-11-17T10:00:00Z\",\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"result\":{\"artifact\":\"nats:tools\",\"fingerprint\":\"fp-0123\",\"outcome\":\"running\",\"seat\":\"node-build-go\",\"shared\":[{\"ask\":\"t1a2\",\"run\":\"main.12.unit.d1\"}],\"status\":\"required\",\"step\":\"unit\"},\"revision\":12,\"source\":3589,\"v\":1}", wire: "{\"at\":\"2026-11-17T10:00:00Z\",\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"result\":{\"artifact\":\"nats:tools\",\"fingerprint\":\"fp-0123\",\"outcome\":\"running\",\"seat\":\"node-build-go\",\"shared\":[{\"ask\":\"t1a2\",\"run\":\"main.12.unit.d1\"}],\"status\":\"required\",\"step\":\"unit\"},\"revision\":12,\"source\":3589,\"v\":1}",
decode: func(b []byte) (any, error) { var v StepStartedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-pipeline-runner\\.event\\.step-started\\.[^.*> ]+\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "C1/AC2 a test step ended with the run another step asked", subject: "mesh.seat.mesh-pipeline-runner.event.step-ended.nats.main.0123456789abcdef0123456789abcdef01234567", given: "{\"at\":\"2026-11-17T10:05:00Z\",\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"result\":{\"artifact\":\"nats:tools\",\"fingerprint\":\"fp-0123\",\"node\":\"anchor\",\"outcome\":\"failed\",\"seat\":\"node-build-go\",\"shared\":[{\"ask\":\"t1a2\",\"asked-by\":{\"artifact\":\"nats:program\",\"pipeline\":\"main.12.nats\"},\"run\":\"main.12.unit.d1\"}],\"status\":\"required\",\"step\":\"unit\",\"tests\":{\"unit\":42}},\"revision\":12,\"source\":3589,\"v\":1}", wire: "{\"at\":\"2026-11-17T10:05:00Z\",\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"result\":{\"artifact\":\"nats:tools\",\"fingerprint\":\"fp-0123\",\"node\":\"anchor\",\"outcome\":\"failed\",\"seat\":\"node-build-go\",\"shared\":[{\"ask\":\"t1a2\",\"asked-by\":{\"artifact\":\"nats:program\",\"pipeline\":\"main.12.nats\"},\"run\":\"main.12.unit.d1\"}],\"status\":\"required\",\"step\":\"unit\",\"tests\":{\"unit\":42}},\"revision\":12,\"source\":3589,\"v\":1}",
decode: func(b []byte) (any, error) { var v StepEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-pipeline-runner\\.event\\.step-ended\\.[^.*> ]+\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "C1 a composition step ended with mesh-wants' runs as they came", subject: "mesh.seat.mesh-pipeline-runner.event.step-ended.nats.main.0123456789abcdef0123456789abcdef01234567", given: "{\"at\":\"2026-11-17T10:05:00Z\",\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"result\":{\"fingerprint\":\"fp-0123\",\"node\":\"laptop\",\"outcome\":\"passed\",\"seat\":\"mesh-wants\",\"shared\":[{\"ask\":\"r1a2b3\",\"machine\":\"anchor\",\"run\":\"main.12.anchor\"}],\"status\":\"required\",\"step\":\"composition\"},\"revision\":12,\"source\":3589,\"v\":1}", wire: "{\"at\":\"2026-11-17T10:05:00Z\",\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"result\":{\"fingerprint\":\"fp-0123\",\"node\":\"laptop\",\"outcome\":\"passed\",\"seat\":\"mesh-wants\",\"shared\":[{\"ask\":\"r1a2b3\",\"machine\":\"anchor\",\"run\":\"main.12.anchor\"}],\"status\":\"required\",\"step\":\"composition\"},\"revision\":12,\"source\":3589,\"v\":1}",
decode: func(b []byte) (any, error) { var v StepEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-pipeline-runner\\.event\\.step-ended\\.[^.*> ]+\\.[^.*> ]+\\.[^.*> ]+$")},
{name: "a pipeline kept", subject: "", given: "{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"end-count\":1,\"ended\":\"2026-11-10T10:20:00Z\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"outcome\":\"passed\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"source\":3589,\"started\":\"2026-11-10T10:00:00Z\",\"steps\":[{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5e\",\"fingerprint\":\"fp-0123\",\"node\":\"anchor\",\"outcome\":\"passed\",\"seat\":\"node-build-go\",\"status\":\"required\",\"step\":\"lint\"},{\"artifact\":\"nats:program\",\"carried-from\":\"main.11.nats\",\"fingerprint\":\"fp-0123\",\"outcome\":\"carried\",\"status\":\"required\",\"step\":\"unit\",\"tests\":{\"unit\":42}},{\"artifact\":\"nats:program\",\"fingerprint\":\"fp-0123\",\"node\":\"home-server\",\"outcome\":\"failed\",\"seat\":\"node-build-go\",\"status\":\"optional\",\"step\":\"integration\",\"tests\":{\"integration\":3},\"why\":\"TestTheBusWhole failed\"},{\"outcome\":\"passed\",\"seat\":\"mesh-wants\",\"status\":\"required\",\"step\":\"composition\"},{\"outcome\":\"bypassed\",\"status\":\"bypass\",\"step\":\"review\"},{\"outcome\":\"passed\",\"status\":\"required\",\"step\":\"approval\"}],\"v\":1}", wire: "{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"end-count\":1,\"ended\":\"2026-11-10T10:20:00Z\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"outcome\":\"passed\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"source\":3589,\"started\":\"2026-11-10T10:00:00Z\",\"steps\":[{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5e\",\"fingerprint\":\"fp-0123\",\"node\":\"anchor\",\"outcome\":\"passed\",\"seat\":\"node-build-go\",\"status\":\"required\",\"step\":\"lint\"},{\"artifact\":\"nats:program\",\"carried-from\":\"main.11.nats\",\"fingerprint\":\"fp-0123\",\"outcome\":\"carried\",\"status\":\"required\",\"step\":\"unit\",\"tests\":{\"unit\":42}},{\"artifact\":\"nats:program\",\"fingerprint\":\"fp-0123\",\"node\":\"home-server\",\"outcome\":\"failed\",\"seat\":\"node-build-go\",\"status\":\"optional\",\"step\":\"integration\",\"tests\":{\"integration\":3},\"why\":\"TestTheBusWhole failed\"},{\"outcome\":\"passed\",\"seat\":\"mesh-wants\",\"status\":\"required\",\"step\":\"composition\"},{\"outcome\":\"bypassed\",\"status\":\"bypass\",\"step\":\"review\"},{\"outcome\":\"passed\",\"status\":\"required\",\"step\":\"approval\"}],\"v\":1}",
decode: func(b []byte) (any, error) {
var v PipelinesByBranchRevisionModuleValue
@@ -67,6 +73,12 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v StandsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "kept answers by digest", subject: "", given: "{\"fill\":{\"bytes\":300,\"cap\":134217728,\"store\":\"kept\"},\"kept\":[{\"digest\":\"sha256:aa\",\"level\":\"unit\",\"package\":\"git.novox.be/novox/nats\",\"pipeline\":\"main.12.nats\"}]}", wire: "{\"fill\":{\"bytes\":300,\"cap\":134217728,\"store\":\"kept\"},\"kept\":[{\"digest\":\"sha256:aa\",\"level\":\"unit\",\"package\":\"git.novox.be/novox/nats\",\"pipeline\":\"main.12.nats\"}]}",
decode: func(b []byte) (any, error) { var v KeptAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "C1/AC3 stands answers a waiting test step with its ask and the run it waits on", subject: "", given: "{\"stands\":[{\"artifact\":\"nats:tools\",\"ask\":\"t1a2\",\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"on\":\"build node\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"shared\":[{\"ask\":\"t1a2\",\"run\":\"main.12.unit.d1\"}],\"since\":\"2026-11-17T10:00:00Z\",\"source\":3589,\"step\":\"unit\",\"v\":1}]}", wire: "{\"stands\":[{\"artifact\":\"nats:tools\",\"ask\":\"t1a2\",\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"on\":\"build node\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"shared\":[{\"ask\":\"t1a2\",\"run\":\"main.12.unit.d1\"}],\"since\":\"2026-11-17T10:00:00Z\",\"source\":3589,\"step\":\"unit\",\"v\":1}]}",
decode: func(b []byte) (any, error) { var v StandsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "C1 test-runs answers each run with its packages, readers and the fill", subject: "", given: "{\"fill\":{\"bytes\":2048,\"cap\":16777216,\"store\":\"test-runs\"},\"runs\":[{\"ask\":\"t1a2\",\"digest\":\"d1\",\"ended\":\"2026-11-17T10:05:00Z\",\"key\":\"main.12.unit.d1\",\"level\":\"unit\",\"node\":\"anchor\",\"outcome\":\"failed\",\"output\":\"t1a2\",\"packages\":[{\"digest\":\"sha256:aa\",\"package\":\"git.novox.be/novox/nats/internal/x\"}],\"readers\":[{\"artifact\":\"nats:program\",\"pipeline\":\"main.12.nats\"},{\"artifact\":\"nats:tools\",\"pipeline\":\"main.12.nats\"}],\"said\":\"1 test failed\",\"seat\":\"node-build-go\",\"started\":\"2026-11-17T10:00:00Z\",\"tests\":{\"unit\":42}},{\"ask\":\"t1a2\",\"digest\":\"d1\",\"ended\":\"2026-11-17T10:05:00Z\",\"gone\":\"the run's output is gone\",\"key\":\"main.12.unit.d1\",\"level\":\"unit\",\"node\":\"anchor\",\"outcome\":\"failed\",\"output\":\"t1a2\",\"readers\":[{\"artifact\":\"nats:program\",\"pipeline\":\"main.12.nats\"},{\"artifact\":\"nats:tools\",\"pipeline\":\"main.12.nats\"}],\"said\":\"1 test failed\",\"seat\":\"node-build-go\",\"started\":\"2026-11-17T10:00:00Z\",\"tests\":{\"unit\":42}}]}", wire: "{\"fill\":{\"bytes\":2048,\"cap\":16777216,\"store\":\"test-runs\"},\"runs\":[{\"ask\":\"t1a2\",\"digest\":\"d1\",\"ended\":\"2026-11-17T10:05:00Z\",\"key\":\"main.12.unit.d1\",\"level\":\"unit\",\"node\":\"anchor\",\"outcome\":\"failed\",\"output\":\"t1a2\",\"packages\":[{\"digest\":\"sha256:aa\",\"package\":\"git.novox.be/novox/nats/internal/x\"}],\"readers\":[{\"artifact\":\"nats:program\",\"pipeline\":\"main.12.nats\"},{\"artifact\":\"nats:tools\",\"pipeline\":\"main.12.nats\"}],\"said\":\"1 test failed\",\"seat\":\"node-build-go\",\"started\":\"2026-11-17T10:00:00Z\",\"tests\":{\"unit\":42}},{\"ask\":\"t1a2\",\"digest\":\"d1\",\"ended\":\"2026-11-17T10:05:00Z\",\"gone\":\"the run's output is gone\",\"key\":\"main.12.unit.d1\",\"level\":\"unit\",\"node\":\"anchor\",\"outcome\":\"failed\",\"output\":\"t1a2\",\"readers\":[{\"artifact\":\"nats:program\",\"pipeline\":\"main.12.nats\"},{\"artifact\":\"nats:tools\",\"pipeline\":\"main.12.nats\"}],\"said\":\"1 test failed\",\"seat\":\"node-build-go\",\"started\":\"2026-11-17T10:00:00Z\",\"tests\":{\"unit\":42}}]}",
decode: func(b []byte) (any, error) { var v TestRunsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "C1 test-runs-drop answers the run it deleted and the readers it ended", subject: "", given: "{\"ended\":[{\"artifact\":\"nats:program\",\"pipeline\":\"main.12.nats\"},{\"artifact\":\"nats:tools\",\"pipeline\":\"main.12.nats\"}],\"run\":{\"ask\":\"t1a2\",\"digest\":\"d1\",\"ended\":\"2026-11-17T10:05:00Z\",\"key\":\"main.12.unit.d1\",\"level\":\"unit\",\"node\":\"anchor\",\"outcome\":\"failed\",\"output\":\"t1a2\",\"packages\":[{\"digest\":\"sha256:aa\",\"package\":\"git.novox.be/novox/nats/internal/x\"}],\"readers\":[{\"artifact\":\"nats:program\",\"pipeline\":\"main.12.nats\"},{\"artifact\":\"nats:tools\",\"pipeline\":\"main.12.nats\"}],\"said\":\"1 test failed\",\"seat\":\"node-build-go\",\"started\":\"2026-11-17T10:00:00Z\",\"tests\":{\"unit\":42}}}", wire: "{\"ended\":[{\"artifact\":\"nats:program\",\"pipeline\":\"main.12.nats\"},{\"artifact\":\"nats:tools\",\"pipeline\":\"main.12.nats\"}],\"run\":{\"ask\":\"t1a2\",\"digest\":\"d1\",\"ended\":\"2026-11-17T10:05:00Z\",\"key\":\"main.12.unit.d1\",\"level\":\"unit\",\"node\":\"anchor\",\"outcome\":\"failed\",\"output\":\"t1a2\",\"packages\":[{\"digest\":\"sha256:aa\",\"package\":\"git.novox.be/novox/nats/internal/x\"}],\"readers\":[{\"artifact\":\"nats:program\",\"pipeline\":\"main.12.nats\"},{\"artifact\":\"nats:tools\",\"pipeline\":\"main.12.nats\"}],\"said\":\"1 test failed\",\"seat\":\"node-build-go\",\"started\":\"2026-11-17T10:00:00Z\",\"tests\":{\"unit\":42}}}",
decode: func(b []byte) (any, error) { var v TestRunsDropAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
@@ -15,12 +15,14 @@ import (
const Seat = "mesh-wants"
const (
VerbUpgrade = "upgrade"
VerbBus = "bus"
VerbRevision = "revision"
VerbEntry = "entry"
VerbDifference = "difference"
VerbInput = "input"
VerbUpgrade = "upgrade"
VerbBus = "bus"
VerbRevision = "revision"
VerbEntry = "entry"
VerbDifference = "difference"
VerbInput = "input"
VerbCompositions = "compositions"
VerbCompositionsDrop = "compositions-drop"
)
const (
@@ -44,7 +46,7 @@ const (
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbUpgrade, VerbBus, VerbRevision, VerbEntry, VerbDifference, VerbInput}
return []string{VerbUpgrade, VerbBus, VerbRevision, VerbEntry, VerbDifference, VerbInput, VerbCompositions, VerbCompositionsDrop}
}
// Events is every event published on the seat's subject: a new copy each call.
@@ -830,6 +832,77 @@ type Change struct {
To string `json:"to,omitempty"`
}
// CompositionReader is a composition step reading a composition run: its step, as the runner asked it, with its ask's id (design 47 G §719, A-468).
type CompositionReader struct {
// the watched branch, or the branch of a run on request
Branch string `json:"branch"`
// for a rerun, the caller the runtime proved
By string `json:"by,omitempty"`
// the commit the step runs at
Commit string `json:"commit"`
// the module's build-input fingerprint at the commit
Fingerprint string `json:"fingerprint"`
// the step's ask's id
ID string `json:"id"`
Module string `json:"module"`
// the runner's pipeline key, <branch>.<revision>.<module>, a branch escaped as a key's name is
Pipeline string `json:"pipeline"`
// the step is asked again by the runner's rerun
Rerun bool `json:"rerun,omitempty"`
// the catalog graph revision of the branch the pipeline runs for
Revision int64 `json:"revision,omitempty"`
// the run on request's id: its composition writes no want (ADR 0666 section 18)
Run string `json:"run,omitempty"`
// the source revision of the watched branch; absent for a run on request
Source int64 `json:"source,omitempty"`
Step string `json:"step"`
}
// The values of CompositionReader's step.
const (
CompositionReaderStepComposition = "composition"
)
// CompositionRunProgram is the composer program, chosen once when the run started.
type CompositionRunProgram struct {
Commit string `json:"commit,omitempty"`
Directory string `json:"directory,omitempty"`
// the node-engine fingerprint it was chosen from
Fingerprint string `json:"fingerprint,omitempty"`
Repository string `json:"repository,omitempty"`
}
// CompositionRun is one composition run of a candidate and a machine, a key of the assigner's state composition-runs (design 47 G §719, §728; A-469u).
type CompositionRun struct {
// the id of the build seat's run ask
Ask string `json:"ask,omitempty"`
// the candidate's key: <branch>.<revision>, or run-<id> for a run on request
Candidate string `json:"candidate"`
Ended *time.Time `json:"ended,omitempty"`
// the digest of the kept request
Input string `json:"input,omitempty"`
// the key, <candidate key>.<machine>, each part escaped as a key's name
Key string `json:"key"`
Machine string `json:"machine"`
Outcome string `json:"outcome,omitempty"`
// the composer program, chosen once when the run started
Program *CompositionRunProgram `json:"program,omitempty"`
// the composition steps reading the run
Readers []CompositionReader `json:"readers,omitempty"`
// the outcome's words
Said string `json:"said,omitempty"`
Started *time.Time `json:"started,omitempty"`
// that machine's composer verdict (design 47 G §721)
Verdict map[string]any `json:"verdict,omitempty"`
}
// The values of CompositionRun's outcome.
const (
CompositionRunOutcomePassed = "passed"
CompositionRunOutcomeFailed = "failed"
CompositionRunOutcomeCouldNotRun = "could not run"
)
// DifferenceRefusedItem is a type of the contract.
type DifferenceRefusedItem struct {
Module string `json:"module"`
@@ -907,6 +980,26 @@ type NodeEntryRef struct {
Node string `json:"node"`
}
// SharedAskedBy is the step that asked the run, for a test step reading another's run.
type SharedAskedBy struct {
// its artifact, <module>:<artifact>
Artifact string `json:"artifact"`
// its pipeline's key
Pipeline string `json:"pipeline"`
}
// Shared is a run whose result a step took or waits on, asked once for every step that reads it (design 47 G §729, A-469t): for a composition step one per machine composed, `run` the `composition-runs` key and `ask` its run ask's id; for a test step one with no machine, `run` the `test-runs` key, `ask` its build seat ask's id and `asked-by` the step that asked the run, left out for that step itself.
type Shared struct {
// the id of the run's ask of the build seat
Ask string `json:"ask"`
// the step that asked the run, for a test step reading another's run
AskedBy *SharedAskedBy `json:"asked-by,omitempty"`
// the machine composed, for a composition run
Machine string `json:"machine,omitempty"`
// the run's key: in the assigner's composition-runs, or the runner's test-runs
Run string `json:"run"`
}
// StepEnded is the composition step's end, said by the assigner on the node it runs on (ADR 0666 sections 7, 21): the runner takes it only from that holder's account, naming the ask, the commit and the fingerprint it was asked at.
type StepEnded struct {
// for a rerun, the caller the runtime proved
@@ -924,7 +1017,9 @@ type StepEnded struct {
Pipeline string `json:"pipeline"`
Rerun bool `json:"rerun,omitempty"`
// why it failed or could not run: the two modules owning one path, the part not heard
Said string `json:"said,omitempty"`
Said string `json:"said,omitempty"`
// per machine composed, the composition run the step read, its ask and so where its verdict was taken (design 47 G §723, §729)
Shared []Shared `json:"shared,omitempty"`
Started *time.Time `json:"started,omitempty"`
Step string `json:"step"`
// the layout version
@@ -1114,6 +1209,36 @@ type InputAnswer struct {
Digest string `json:"digest"`
}
// CompositionsInput is what compositions takes.
type CompositionsInput struct {
// the candidate's key
Candidate string `json:"candidate,omitempty"`
Machine string `json:"machine,omitempty"`
}
// CompositionsAnswer is what compositions answers.
type CompositionsAnswer struct {
Fill Fill `json:"fill"`
Runs []CompositionRun `json:"runs"`
}
// CompositionsDropInput is what compositions-drop takes.
type CompositionsDropInput struct {
// the candidate's key
Candidate string `json:"candidate"`
Machine string `json:"machine"`
// why, written with the caller the runtime proves in the hand-act log
Why string `json:"why"`
}
// CompositionsDropAnswer is what compositions-drop answers.
type CompositionsDropAnswer struct {
// the readers it ended
Ended []CompositionReader `json:"ended,omitempty"`
// the entry deleted
Run CompositionRun `json:"run"`
}
// StepAccept is the body of step.
type StepAccept = StepRun
@@ -1197,6 +1322,8 @@ type StepProgressEvent struct {
Asker string `json:"asker"`
At time.Time `json:"at"`
Phase string `json:"phase"`
// the composition runs the step waits on, by machine, each with its ask (design 47 G §723, §729)
Shared []Shared `json:"shared,omitempty"`
}
// The values of StepProgressEvent's phase.
@@ -59,6 +59,10 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v WaitHeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.wait-held$")},
{name: "an outside wait ended by the operator's Go on", subject: "mesh.seat.mesh-wants.event.wait-ended", given: "{\"fingerprint\":\"src2:aaaa\",\"how\":\"go-on\",\"module\":\"nats\",\"node\":\"anchor\",\"on\":\"silent:home-server\",\"owner\":\"mesh-delivery-assigner\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"outside\"}", wire: "{\"fingerprint\":\"src2:aaaa\",\"how\":\"go-on\",\"module\":\"nats\",\"node\":\"anchor\",\"on\":\"silent:home-server\",\"owner\":\"mesh-delivery-assigner\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"outside\"}",
decode: func(b []byte) (any, error) { var v WaitEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.wait-ended$")},
{name: "C1/AC1 a reading composition step ended, naming per machine the run it read and its ask", subject: "mesh.seat.mesh-wants.event.step-ended.laptop", given: "{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d6c\",\"module\":\"nats\",\"node\":\"laptop\",\"outcome\":\"passed\",\"pipeline\":\"main.12.nats\",\"shared\":[{\"ask\":\"r1a2b3\",\"machine\":\"anchor\",\"run\":\"main.12.anchor\"},{\"ask\":\"r4d5e6\",\"machine\":\"home-server\",\"run\":\"main.12.home-server\"}],\"step\":\"composition\",\"v\":1,\"warnings\":[\"anchor holds xclip: xclip and demo both own /etc/x\"]}", wire: "{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d6c\",\"module\":\"nats\",\"node\":\"laptop\",\"outcome\":\"passed\",\"pipeline\":\"main.12.nats\",\"shared\":[{\"ask\":\"r1a2b3\",\"machine\":\"anchor\",\"run\":\"main.12.anchor\"},{\"ask\":\"r4d5e6\",\"machine\":\"home-server\",\"run\":\"main.12.home-server\"}],\"step\":\"composition\",\"v\":1,\"warnings\":[\"anchor holds xclip: xclip and demo both own /etc/x\"]}",
decode: func(b []byte) (any, error) { var v StepEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.step-ended\\.[^.*> ]+$")},
{name: "C1/AC1 a composition step's progress, naming the runs it waits on", subject: "mesh.seat.mesh-wants.event.step-progress.anchor", given: "{\"ask\":\"a1b2\",\"asker\":\"assigner\",\"at\":\"2026-11-17T10:01:00Z\",\"phase\":\"run\",\"shared\":[{\"ask\":\"r1a2b3\",\"machine\":\"anchor\",\"run\":\"main.12.anchor\"}]}", wire: "{\"ask\":\"a1b2\",\"asker\":\"assigner\",\"at\":\"2026-11-17T10:01:00Z\",\"phase\":\"run\",\"shared\":[{\"ask\":\"r1a2b3\",\"machine\":\"anchor\",\"run\":\"main.12.anchor\"}]}",
decode: func(b []byte) (any, error) { var v StepProgressEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.step-progress\\.[^.*> ]+$")},
{name: "a want", subject: "", given: "{\"fp\":\"ab12\",\"rule\":3,\"v\":1}", wire: "{\"fp\":\"ab12\",\"rule\":3,\"v\":1}",
decode: func(b []byte) (any, error) {
var v WantsByWantNodeModuleValue
@@ -141,6 +145,12 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v InputInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "input answers how many chunks carry the exact bytes", subject: "", given: "{\"chunks\":3,\"digest\":\"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"}", wire: "{\"chunks\":3,\"digest\":\"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"}",
decode: func(b []byte) (any, error) { var v InputAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "C1 compositions answers each run with its readers, verdict and the fill", subject: "", given: "{\"fill\":{\"bytes\":4096,\"cap\":16777216,\"store\":\"composition-runs\"},\"runs\":[{\"ask\":\"r1a2b3\",\"candidate\":\"main.12\",\"ended\":\"2026-11-17T10:03:00Z\",\"input\":\"sha256:0123\",\"key\":\"main.12.anchor\",\"machine\":\"anchor\",\"outcome\":\"passed\",\"program\":{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"directory\":\"cmd/mesh-compose\",\"fingerprint\":\"src2:aaaa\",\"repository\":\"novox/mesh-host\"},\"readers\":[{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d6c\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"step\":\"composition\"}],\"started\":\"2026-11-17T10:00:00Z\",\"verdict\":{\"blamed\":[],\"composes\":true}}]}", wire: "{\"fill\":{\"bytes\":4096,\"cap\":16777216,\"store\":\"composition-runs\"},\"runs\":[{\"ask\":\"r1a2b3\",\"candidate\":\"main.12\",\"ended\":\"2026-11-17T10:03:00Z\",\"input\":\"sha256:0123\",\"key\":\"main.12.anchor\",\"machine\":\"anchor\",\"outcome\":\"passed\",\"program\":{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"directory\":\"cmd/mesh-compose\",\"fingerprint\":\"src2:aaaa\",\"repository\":\"novox/mesh-host\"},\"readers\":[{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d6c\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"step\":\"composition\"}],\"started\":\"2026-11-17T10:00:00Z\",\"verdict\":{\"blamed\":[],\"composes\":true}}]}",
decode: func(b []byte) (any, error) { var v CompositionsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "C1 compositions-drop takes a candidate, a machine and why", subject: "", given: "{\"candidate\":\"main.12\",\"machine\":\"anchor\",\"why\":\"its ask never came back\"}", wire: "{\"candidate\":\"main.12\",\"machine\":\"anchor\",\"why\":\"its ask never came back\"}",
decode: func(b []byte) (any, error) { var v CompositionsDropInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "C1 compositions-drop answers the run it deleted and the readers it ended", subject: "", given: "{\"ended\":[{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d6c\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"step\":\"composition\"}],\"run\":{\"ask\":\"r1a2b3\",\"candidate\":\"main.12\",\"ended\":\"2026-11-17T10:03:00Z\",\"input\":\"sha256:0123\",\"key\":\"main.12.anchor\",\"machine\":\"anchor\",\"outcome\":\"passed\",\"program\":{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"directory\":\"cmd/mesh-compose\",\"fingerprint\":\"src2:aaaa\",\"repository\":\"novox/mesh-host\"},\"readers\":[{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d6c\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"step\":\"composition\"}],\"started\":\"2026-11-17T10:00:00Z\",\"verdict\":{\"blamed\":[],\"composes\":true}}}", wire: "{\"ended\":[{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d6c\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"step\":\"composition\"}],\"run\":{\"ask\":\"r1a2b3\",\"candidate\":\"main.12\",\"ended\":\"2026-11-17T10:03:00Z\",\"input\":\"sha256:0123\",\"key\":\"main.12.anchor\",\"machine\":\"anchor\",\"outcome\":\"passed\",\"program\":{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"directory\":\"cmd/mesh-compose\",\"fingerprint\":\"src2:aaaa\",\"repository\":\"novox/mesh-host\"},\"readers\":[{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d6c\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"step\":\"composition\"}],\"started\":\"2026-11-17T10:00:00Z\",\"verdict\":{\"blamed\":[],\"composes\":true}}}",
decode: func(b []byte) (any, error) { var v CompositionsDropAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
@@ -313,5 +313,104 @@
"how": "answered",
"fingerprint": "fp-0123"
}
},
{
"name": "C1/AC2 a test step started reading a test run, naming its run and ask",
"of": "event:step-started",
"subject": "mesh.seat.mesh-pipeline-runner.event.step-started.nats.main.0123456789abcdef0123456789abcdef01234567",
"given": {
"pipeline": "main.12.nats",
"module": "nats",
"branch": "main",
"revision": 12,
"source": 3589,
"commit": "0123456789abcdef0123456789abcdef01234567",
"v": 1,
"fingerprint": "fp-0123",
"result": {
"step": "unit",
"artifact": "nats:tools",
"status": "required",
"outcome": "running",
"fingerprint": "fp-0123",
"seat": "node-build-go",
"shared": [
{
"run": "main.12.unit.d1",
"ask": "t1a2"
}
]
},
"at": "2026-11-17T10:00:00Z"
}
},
{
"name": "C1/AC2 a test step ended with the run another step asked",
"of": "event:step-ended",
"subject": "mesh.seat.mesh-pipeline-runner.event.step-ended.nats.main.0123456789abcdef0123456789abcdef01234567",
"given": {
"pipeline": "main.12.nats",
"module": "nats",
"branch": "main",
"revision": 12,
"source": 3589,
"commit": "0123456789abcdef0123456789abcdef01234567",
"v": 1,
"fingerprint": "fp-0123",
"result": {
"step": "unit",
"artifact": "nats:tools",
"status": "required",
"outcome": "failed",
"fingerprint": "fp-0123",
"seat": "node-build-go",
"node": "anchor",
"tests": {
"unit": 42
},
"shared": [
{
"run": "main.12.unit.d1",
"ask": "t1a2",
"asked-by": {
"pipeline": "main.12.nats",
"artifact": "nats:program"
}
}
]
},
"at": "2026-11-17T10:05:00Z"
}
},
{
"name": "C1 a composition step ended with mesh-wants' runs as they came",
"of": "event:step-ended",
"subject": "mesh.seat.mesh-pipeline-runner.event.step-ended.nats.main.0123456789abcdef0123456789abcdef01234567",
"given": {
"pipeline": "main.12.nats",
"module": "nats",
"branch": "main",
"revision": 12,
"source": 3589,
"commit": "0123456789abcdef0123456789abcdef01234567",
"v": 1,
"fingerprint": "fp-0123",
"result": {
"step": "composition",
"status": "required",
"outcome": "passed",
"fingerprint": "fp-0123",
"seat": "mesh-wants",
"node": "laptop",
"shared": [
{
"machine": "anchor",
"run": "main.12.anchor",
"ask": "r1a2b3"
}
]
},
"at": "2026-11-17T10:05:00Z"
}
}
]
@@ -143,5 +143,154 @@
"cap": 134217728
}
}
},
{
"name": "C1/AC3 stands answers a waiting test step with its ask and the run it waits on",
"of": "verb:stands.answer",
"given": {
"stands": [
{
"pipeline": "main.12.nats",
"module": "nats",
"branch": "main",
"revision": 12,
"source": 3589,
"commit": "0123456789abcdef0123456789abcdef01234567",
"v": 1,
"fingerprint": "fp-0123",
"step": "unit",
"artifact": "nats:tools",
"on": "build node",
"since": "2026-11-17T10:00:00Z",
"ask": "t1a2",
"shared": [
{
"run": "main.12.unit.d1",
"ask": "t1a2"
}
]
}
]
}
},
{
"name": "C1 test-runs answers each run with its packages, readers and the fill",
"of": "verb:test-runs.answer",
"given": {
"runs": [
{
"key": "main.12.unit.d1",
"level": "unit",
"digest": "d1",
"seat": "node-build-go",
"ask": "t1a2",
"node": "anchor",
"started": "2026-11-17T10:00:00Z",
"readers": [
{
"pipeline": "main.12.nats",
"artifact": "nats:program"
},
{
"pipeline": "main.12.nats",
"artifact": "nats:tools"
}
],
"ended": "2026-11-17T10:05:00Z",
"outcome": "failed",
"said": "1 test failed",
"tests": {
"unit": 42
},
"output": "t1a2",
"packages": [
{
"package": "git.novox.be/novox/nats/internal/x",
"digest": "sha256:aa"
}
]
},
{
"key": "main.12.unit.d1",
"level": "unit",
"digest": "d1",
"seat": "node-build-go",
"ask": "t1a2",
"node": "anchor",
"started": "2026-11-17T10:00:00Z",
"readers": [
{
"pipeline": "main.12.nats",
"artifact": "nats:program"
},
{
"pipeline": "main.12.nats",
"artifact": "nats:tools"
}
],
"ended": "2026-11-17T10:05:00Z",
"outcome": "failed",
"said": "1 test failed",
"tests": {
"unit": 42
},
"output": "t1a2",
"gone": "the run's output is gone"
}
],
"fill": {
"store": "test-runs",
"bytes": 2048,
"cap": 16777216
}
}
},
{
"name": "C1 test-runs-drop answers the run it deleted and the readers it ended",
"of": "verb:test-runs-drop.answer",
"given": {
"run": {
"key": "main.12.unit.d1",
"level": "unit",
"digest": "d1",
"seat": "node-build-go",
"ask": "t1a2",
"node": "anchor",
"started": "2026-11-17T10:00:00Z",
"readers": [
{
"pipeline": "main.12.nats",
"artifact": "nats:program"
},
{
"pipeline": "main.12.nats",
"artifact": "nats:tools"
}
],
"ended": "2026-11-17T10:05:00Z",
"outcome": "failed",
"said": "1 test failed",
"tests": {
"unit": 42
},
"output": "t1a2",
"packages": [
{
"package": "git.novox.be/novox/nats/internal/x",
"digest": "sha256:aa"
}
]
},
"ended": [
{
"pipeline": "main.12.nats",
"artifact": "nats:program"
},
{
"pipeline": "main.12.nats",
"artifact": "nats:tools"
}
]
}
}
]
@@ -495,6 +495,93 @@
]
},
"class": "act"
},
{
"name": "test-runs",
"class": "read",
"description": "Each test run the runner keeps (design 47 G §728): its packages read from its output object, ask, node, readers, outcome and counts, and the state's fill against its cap; with candidate, level, digest or module, only those.",
"input": {
"type": "object",
"properties": {
"candidate": {
"type": "string",
"description": "the candidate's key"
},
"level": {
"type": "string",
"enum": [
"lint",
"unit",
"integration"
]
},
"digest": {
"type": "string"
},
"module": {
"type": "string"
}
}
},
"answer": {
"type": "object",
"properties": {
"runs": {
"type": "array",
"items": {
"$ref": "#/defs/TestRun"
}
},
"fill": {
"$ref": "#/defs/Fill"
}
},
"required": [
"runs",
"fill"
]
}
},
{
"name": "test-runs-drop",
"class": "act",
"description": "Drop one test run by hand (design 47 G §728): the act and why are written in the hand-act log first, then the run's ask is dropped, each reader ended could not run naming the drop, and the key deleted with the run's output object.",
"input": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "the run's key in test-runs"
},
"why": {
"type": "string",
"description": "why, written with the caller the runtime proves in the hand-act log"
}
},
"required": [
"key",
"why"
]
},
"answer": {
"type": "object",
"properties": {
"run": {
"$ref": "#/defs/TestRun",
"description": "the entry deleted"
},
"ended": {
"type": "array",
"items": {
"$ref": "#/defs/TestRunReader"
},
"description": "the readers it ended"
}
},
"required": [
"run"
]
}
}
],
"events": [
@@ -887,6 +974,13 @@
"ended": {
"type": "string",
"format": "date-time"
},
"shared": {
"type": "array",
"items": {
"$ref": "#/defs/Shared"
},
"description": "the run the step read or asked for every step that reads it: a composition step's per machine, as mesh-wants' step-ended names them; a test step's one, with asked-by when another step asked it (design 47 G §726, §729; A-468d, A-468e, A-469t)"
}
},
"description": "one step of a pipeline: its status in the policy and its outcome (design 47 *Pipeline steps and the policy*)",
@@ -1494,6 +1588,17 @@
"how": {
"type": "string",
"description": "for its end, how it ended: answered, ran, superseded"
},
"ask": {
"type": "string",
"description": "the step's own ask, where it has one (design 47 G §731)"
},
"shared": {
"type": "array",
"items": {
"$ref": "#/defs/Shared"
},
"description": "the run the step waits on, where the runner knows it: a test step's run key and ask (design 47 G §731, A-469v)"
}
},
"description": "a step's wait, held and ended; a wait on a person is said as waiting on that person, never a stall (ADR 0283)",
@@ -1577,6 +1682,159 @@
"what",
"at"
]
},
"Shared": {
"type": "object",
"description": "a run whose result a step took or waits on, asked once for every step that reads it (design 47 G §729, A-469t): for a composition step one per machine composed, `run` the `composition-runs` key and `ask` its run ask's id; for a test step one with no machine, `run` the `test-runs` key, `ask` its build seat ask's id and `asked-by` the step that asked the run, left out for that step itself",
"properties": {
"machine": {
"type": "string",
"description": "the machine composed, for a composition run"
},
"run": {
"type": "string",
"description": "the run's key: in the assigner's composition-runs, or the runner's test-runs"
},
"ask": {
"type": "string",
"description": "the id of the run's ask of the build seat"
},
"asked-by": {
"type": "object",
"description": "the step that asked the run, for a test step reading another's run",
"properties": {
"pipeline": {
"type": "string",
"description": "its pipeline's key"
},
"artifact": {
"type": "string",
"description": "its artifact, <module>:<artifact>"
}
},
"required": [
"pipeline",
"artifact"
]
}
},
"required": [
"run",
"ask"
]
},
"TestRunReader": {
"type": "object",
"description": "a test step reading a test run (design 47 G §725)",
"properties": {
"pipeline": {
"type": "string",
"description": "its pipeline's key"
},
"artifact": {
"type": "string",
"description": "its artifact, <module>:<artifact>"
}
},
"required": [
"pipeline",
"artifact"
]
},
"TestRunPackage": {
"type": "object",
"description": "one package a test run ran, with its digest (design 47 G §724)",
"properties": {
"package": {
"type": "string"
},
"digest": {
"type": "string"
}
},
"required": [
"package",
"digest"
]
},
"TestRun": {
"type": "object",
"description": "one test run of a candidate, level and tested packages, a key of the runner's state test-runs (design 47 G §725, §728; A-469u)",
"properties": {
"key": {
"type": "string",
"description": "the key, <candidate key>.<level>.<digest>, each part escaped as a key's name"
},
"level": {
"type": "string",
"enum": [
"lint",
"unit",
"integration"
]
},
"digest": {
"type": "string",
"description": "the share digest (design 47 G §724)"
},
"seat": {
"type": "string",
"description": "the build seat asked"
},
"ask": {
"type": "string",
"description": "the id of the build seat's ask"
},
"node": {
"type": "string",
"description": "the node whose holder took the ask"
},
"started": {
"type": "string",
"format": "date-time"
},
"readers": {
"type": "array",
"items": {
"$ref": "#/defs/TestRunReader"
},
"description": "the steps reading the run"
},
"ended": {
"type": "string",
"format": "date-time"
},
"outcome": {
"type": "string"
},
"said": {
"type": "string",
"description": "the outcome's words"
},
"tests": {
"$ref": "#/defs/TestCounts"
},
"output": {
"type": "string",
"description": "the run's output object, by its name in test-runs-objects"
},
"packages": {
"type": "array",
"items": {
"$ref": "#/defs/TestRunPackage"
},
"description": "the packages it ran, read from its output object"
},
"gone": {
"type": "string",
"description": "why the packages are not named: the run's output is gone"
}
},
"required": [
"key",
"level",
"digest"
]
}
}
}
@@ -284,5 +284,54 @@
"since": "2026-11-11T10:00:00Z",
"how": "go-on"
}
},
{
"name": "C1/AC1 a reading composition step ended, naming per machine the run it read and its ask",
"of": "event:step-ended",
"subject": "mesh.seat.mesh-wants.event.step-ended.laptop",
"given": {
"v": 1,
"id": "m2kx9a1b3c4d6c",
"pipeline": "main.12.nats",
"step": "composition",
"module": "nats",
"commit": "0123456789abcdef0123456789abcdef01234567",
"fingerprint": "fp-0123",
"node": "laptop",
"outcome": "passed",
"warnings": [
"anchor holds xclip: xclip and demo both own /etc/x"
],
"shared": [
{
"machine": "anchor",
"run": "main.12.anchor",
"ask": "r1a2b3"
},
{
"machine": "home-server",
"run": "main.12.home-server",
"ask": "r4d5e6"
}
]
}
},
{
"name": "C1/AC1 a composition step's progress, naming the runs it waits on",
"of": "event:step-progress",
"subject": "mesh.seat.mesh-wants.event.step-progress.anchor",
"given": {
"asker": "assigner",
"ask": "a1b2",
"phase": "run",
"at": "2026-11-17T10:01:00Z",
"shared": [
{
"machine": "anchor",
"run": "main.12.anchor",
"ask": "r1a2b3"
}
]
}
}
]
@@ -175,5 +175,109 @@
"chunks": 3,
"digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
},
{
"name": "C1 compositions answers each run with its readers, verdict and the fill",
"of": "verb:compositions.answer",
"given": {
"runs": [
{
"key": "main.12.anchor",
"candidate": "main.12",
"machine": "anchor",
"program": {
"repository": "novox/mesh-host",
"commit": "0123456789abcdef0123456789abcdef01234567",
"directory": "cmd/mesh-compose",
"fingerprint": "src2:aaaa"
},
"input": "sha256:0123",
"ask": "r1a2b3",
"started": "2026-11-17T10:00:00Z",
"readers": [
{
"id": "m2kx9a1b3c4d6c",
"pipeline": "main.12.nats",
"step": "composition",
"module": "nats",
"branch": "main",
"commit": "0123456789abcdef0123456789abcdef01234567",
"revision": 12,
"fingerprint": "fp-0123"
}
],
"ended": "2026-11-17T10:03:00Z",
"outcome": "passed",
"verdict": {
"composes": true,
"blamed": []
}
}
],
"fill": {
"store": "composition-runs",
"bytes": 4096,
"cap": 16777216
}
}
},
{
"name": "C1 compositions-drop takes a candidate, a machine and why",
"of": "verb:compositions-drop.input",
"given": {
"candidate": "main.12",
"machine": "anchor",
"why": "its ask never came back"
}
},
{
"name": "C1 compositions-drop answers the run it deleted and the readers it ended",
"of": "verb:compositions-drop.answer",
"given": {
"run": {
"key": "main.12.anchor",
"candidate": "main.12",
"machine": "anchor",
"program": {
"repository": "novox/mesh-host",
"commit": "0123456789abcdef0123456789abcdef01234567",
"directory": "cmd/mesh-compose",
"fingerprint": "src2:aaaa"
},
"input": "sha256:0123",
"ask": "r1a2b3",
"started": "2026-11-17T10:00:00Z",
"readers": [
{
"id": "m2kx9a1b3c4d6c",
"pipeline": "main.12.nats",
"step": "composition",
"module": "nats",
"branch": "main",
"commit": "0123456789abcdef0123456789abcdef01234567",
"revision": 12,
"fingerprint": "fp-0123"
}
],
"ended": "2026-11-17T10:03:00Z",
"outcome": "passed",
"verdict": {
"composes": true,
"blamed": []
}
},
"ended": [
{
"id": "m2kx9a1b3c4d6c",
"pipeline": "main.12.nats",
"step": "composition",
"module": "nats",
"branch": "main",
"commit": "0123456789abcdef0123456789abcdef01234567",
"revision": 12,
"fingerprint": "fp-0123"
}
]
}
}
]
@@ -202,6 +202,86 @@
]
},
"chunks": true
},
{
"name": "compositions",
"class": "read",
"description": "Each composition run the assigner keeps (design 47 G \u00a7728): its program, input digest, ask, readers, outcome and verdict, and the state's fill against its cap; with candidate or machine, only those.",
"input": {
"type": "object",
"properties": {
"candidate": {
"type": "string",
"description": "the candidate's key"
},
"machine": {
"type": "string"
}
}
},
"answer": {
"type": "object",
"properties": {
"runs": {
"type": "array",
"items": {
"$ref": "#/defs/CompositionRun"
}
},
"fill": {
"$ref": "#/defs/Fill"
}
},
"required": [
"runs",
"fill"
]
}
},
{
"name": "compositions-drop",
"class": "act",
"description": "Drop one composition run by hand (design 47 G \u00a7728): the act and why are written in the hand-act log first, then the run's ask is dropped, each reader ended could not run naming the drop, and the key deleted.",
"input": {
"type": "object",
"properties": {
"candidate": {
"type": "string",
"description": "the candidate's key"
},
"machine": {
"type": "string"
},
"why": {
"type": "string",
"description": "why, written with the caller the runtime proves in the hand-act log"
}
},
"required": [
"candidate",
"machine",
"why"
]
},
"answer": {
"type": "object",
"properties": {
"run": {
"$ref": "#/defs/CompositionRun",
"description": "the entry deleted"
},
"ended": {
"type": "array",
"items": {
"$ref": "#/defs/CompositionReader"
},
"description": "the readers it ended"
}
},
"required": [
"run"
]
}
}
],
"accepts": [
@@ -470,6 +550,13 @@
"at": {
"type": "string",
"format": "date-time"
},
"shared": {
"type": "array",
"items": {
"$ref": "#/defs/Shared"
},
"description": "the composition runs the step waits on, by machine, each with its ask (design 47 G \u00a7723, \u00a7729)"
}
},
"required": [
@@ -1418,6 +1505,13 @@
"ended": {
"type": "string",
"format": "date-time"
},
"shared": {
"type": "array",
"items": {
"$ref": "#/defs/Shared"
},
"description": "per machine composed, the composition run the step read, its ask and so where its verdict was taken (design 47 G \u00a7723, \u00a7729)"
}
},
"required": [
@@ -1472,6 +1566,190 @@
"required": [
"ask"
]
},
"Shared": {
"type": "object",
"description": "a run whose result a step took or waits on, asked once for every step that reads it (design 47 G \u00a7729, A-469t): for a composition step one per machine composed, `run` the `composition-runs` key and `ask` its run ask's id; for a test step one with no machine, `run` the `test-runs` key, `ask` its build seat ask's id and `asked-by` the step that asked the run, left out for that step itself",
"properties": {
"machine": {
"type": "string",
"description": "the machine composed, for a composition run"
},
"run": {
"type": "string",
"description": "the run's key: in the assigner's composition-runs, or the runner's test-runs"
},
"ask": {
"type": "string",
"description": "the id of the run's ask of the build seat"
},
"asked-by": {
"type": "object",
"description": "the step that asked the run, for a test step reading another's run",
"properties": {
"pipeline": {
"type": "string",
"description": "its pipeline's key"
},
"artifact": {
"type": "string",
"description": "its artifact, <module>:<artifact>"
}
},
"required": [
"pipeline",
"artifact"
]
}
},
"required": [
"run",
"ask"
]
},
"CompositionReader": {
"type": "object",
"description": "a composition step reading a composition run: its step, as the runner asked it, with its ask's id (design 47 G \u00a7719, A-468)",
"properties": {
"id": {
"type": "string",
"description": "the step's ask's id"
},
"pipeline": {
"type": "string",
"description": "the runner's pipeline key, <branch>.<revision>.<module>, a branch escaped as a key's name is"
},
"step": {
"type": "string",
"enum": [
"composition"
]
},
"module": {
"type": "string"
},
"branch": {
"type": "string",
"description": "the watched branch, or the branch of a run on request"
},
"commit": {
"type": "string",
"description": "the commit the step runs at"
},
"revision": {
"type": "integer",
"description": "the catalog graph revision of the branch the pipeline runs for"
},
"source": {
"type": "integer",
"description": "the source revision of the watched branch; absent for a run on request"
},
"fingerprint": {
"type": "string",
"description": "the module's build-input fingerprint at the commit"
},
"run": {
"type": "string",
"description": "the run on request's id: its composition writes no want (ADR 0666 section 18)"
},
"rerun": {
"type": "boolean",
"description": "the step is asked again by the runner's rerun"
},
"by": {
"type": "string",
"description": "for a rerun, the caller the runtime proved"
}
},
"required": [
"id",
"pipeline",
"step",
"module",
"branch",
"commit",
"fingerprint"
]
},
"CompositionRun": {
"type": "object",
"description": "one composition run of a candidate and a machine, a key of the assigner's state composition-runs (design 47 G \u00a7719, \u00a7728; A-469u)",
"properties": {
"key": {
"type": "string",
"description": "the key, <candidate key>.<machine>, each part escaped as a key's name"
},
"candidate": {
"type": "string",
"description": "the candidate's key: <branch>.<revision>, or run-<id> for a run on request"
},
"machine": {
"type": "string"
},
"program": {
"type": "object",
"description": "the composer program, chosen once when the run started",
"properties": {
"repository": {
"type": "string"
},
"commit": {
"type": "string"
},
"directory": {
"type": "string"
},
"fingerprint": {
"type": "string",
"description": "the node-engine fingerprint it was chosen from"
}
}
},
"input": {
"type": "string",
"description": "the digest of the kept request"
},
"ask": {
"type": "string",
"description": "the id of the build seat's run ask"
},
"started": {
"type": "string",
"format": "date-time"
},
"readers": {
"type": "array",
"items": {
"$ref": "#/defs/CompositionReader"
},
"description": "the composition steps reading the run"
},
"ended": {
"type": "string",
"format": "date-time"
},
"outcome": {
"type": "string",
"enum": [
"passed",
"failed",
"could not run"
]
},
"said": {
"type": "string",
"description": "the outcome's words"
},
"verdict": {
"type": "object",
"description": "that machine's composer verdict (design 47 G \u00a7721)"
}
},
"required": [
"key",
"candidate",
"machine"
]
}
},
"acts": [
@@ -17,6 +17,8 @@ export declare const verbs: {
readonly accept: "accept";
readonly cancel: "cancel";
readonly askAgain: "ask-again";
readonly testRuns: "test-runs";
readonly testRunsDrop: "test-runs-drop";
};
export declare const events: {
@@ -316,6 +318,26 @@ export interface RunStarted {
"v": number;
}
/** the step that asked the run, for a test step reading another's run */
export interface SharedAskedBy {
/** its artifact, <module>:<artifact> */
"artifact": string;
/** its pipeline's key */
"pipeline": string;
}
/** a run whose result a step took or waits on, asked once for every step that reads it (design 47 G §729, A-469t): for a composition step one per machine composed, `run` the `composition-runs` key and `ask` its run ask's id; for a test step one with no machine, `run` the `test-runs` key, `ask` its build seat ask's id and `asked-by` the step that asked the run, left out for that step itself */
export interface Shared {
/** the id of the run's ask of the build seat */
"ask": string;
/** the step that asked the run, for a test step reading another's run */
"asked-by"?: SharedAskedBy;
/** the machine composed, for a composition run */
"machine"?: string;
/** the run's key: in the assigner's composition-runs, or the runner's test-runs */
"run": string;
}
/** a step's start or end: the step, its status, its outcome, its fingerprint, its test counts, what a carried result was carried from, and for a rerun that it is one and its proved caller; a bypassed step too */
export interface StepEvent {
"at"?: string;
@@ -366,6 +388,8 @@ export interface StepResult {
"rerun"?: boolean;
/** the seat that serves the step, whose holder alone may end it (ADR 0666 section 21) */
"seat"?: string;
/** the run the step read or asked for every step that reads it: a composition step's per machine, as mesh-wants' step-ended names them; a test step's one, with asked-by when another step asked it (design 47 G §726, §729; A-468d, A-468e, A-469t) */
"shared"?: Shared[];
"started"?: string;
/** the step's status in the module's policy */
"status": "required" | "optional" | "bypass";
@@ -381,6 +405,49 @@ export interface TestCounts {
"unit"?: number;
}
/** one test run of a candidate, level and tested packages, a key of the runner's state test-runs (design 47 G §725, §728; A-469u) */
export interface TestRun {
/** the id of the build seat's ask */
"ask"?: string;
/** the share digest (design 47 G §724) */
"digest": string;
"ended"?: string;
/** why the packages are not named: the run's output is gone */
"gone"?: string;
/** the key, <candidate key>.<level>.<digest>, each part escaped as a key's name */
"key": string;
"level": "lint" | "unit" | "integration";
/** the node whose holder took the ask */
"node"?: string;
"outcome"?: string;
/** the run's output object, by its name in test-runs-objects */
"output"?: string;
/** the packages it ran, read from its output object */
"packages"?: TestRunPackage[];
/** the steps reading the run */
"readers"?: TestRunReader[];
/** the outcome's words */
"said"?: string;
/** the build seat asked */
"seat"?: string;
"started"?: string;
"tests"?: TestCounts;
}
/** one package a test run ran, with its digest (design 47 G §724) */
export interface TestRunPackage {
"digest": string;
"package": string;
}
/** a test step reading a test run (design 47 G §725) */
export interface TestRunReader {
/** its artifact, <module>:<artifact> */
"artifact": string;
/** its pipeline's key */
"pipeline": string;
}
/** the toolchain a build was made with: the language, the installed version and the build module's recipe */
export interface ToolchainUsed {
"language": string;
@@ -391,6 +458,8 @@ export interface ToolchainUsed {
/** a step's wait, held and ended; a wait on a person is said as waiting on that person, never a stall (ADR 0283) */
export interface Wait {
"artifact"?: string;
/** the step's own ask, where it has one (design 47 G §731) */
"ask"?: string;
/** the watched branch, or the branch of a run on request */
"branch": string;
/** the commit the module's entry was last changed at */
@@ -410,6 +479,8 @@ export interface Wait {
"revision"?: number;
/** the run on request's id, for a pipeline of a run; such a pipeline delivers nothing */
"run"?: string;
/** the run the step waits on, where the runner knows it: a test step's run key and ask (design 47 G §731, A-469v) */
"shared"?: Shared[];
"since": string;
/** the source revision of the watched branch; the pipeline is keyed by it (ADR 0666 section 9) */
"source"?: number;
@@ -594,6 +665,37 @@ export interface AskAgainAnswer {
"result": StepResult;
}
/** is what test-runs takes. */
export interface TestRunsInput {
/** the candidate's key */
"candidate"?: string;
"digest"?: string;
"level"?: "lint" | "unit" | "integration";
"module"?: string;
}
/** is what test-runs answers. */
export interface TestRunsAnswer {
"fill": Fill;
"runs": TestRun[];
}
/** is what test-runs-drop takes. */
export interface TestRunsDropInput {
/** the run's key in test-runs */
"key": string;
/** why, written with the caller the runtime proves in the hand-act log */
"why": string;
}
/** is what test-runs-drop answers. */
export interface TestRunsDropAnswer {
/** the readers it ended */
"ended"?: TestRunReader[];
/** the entry deleted */
"run": TestRun;
}
/** is the body of the event pipeline-started. */
export type PipelineStartedEvent = PipelineStarted;
@@ -17,6 +17,8 @@ export const verbs = {
accept: "accept",
cancel: "cancel",
askAgain: "ask-again",
testRuns: "test-runs",
testRunsDrop: "test-runs-drop",
};
export const events = {
@@ -11,6 +11,8 @@ export declare const verbs: {
readonly entry: "entry";
readonly difference: "difference";
readonly input: "input";
readonly compositions: "compositions";
readonly compositionsDrop: "compositions-drop";
};
export declare const accepts: {
@@ -258,6 +260,65 @@ export interface Change {
"to"?: string;
}
/** a composition step reading a composition run: its step, as the runner asked it, with its ask's id (design 47 G §719, A-468) */
export interface CompositionReader {
/** the watched branch, or the branch of a run on request */
"branch": string;
/** for a rerun, the caller the runtime proved */
"by"?: string;
/** the commit the step runs at */
"commit": string;
/** the module's build-input fingerprint at the commit */
"fingerprint": string;
/** the step's ask's id */
"id": string;
"module": string;
/** the runner's pipeline key, <branch>.<revision>.<module>, a branch escaped as a key's name is */
"pipeline": string;
/** the step is asked again by the runner's rerun */
"rerun"?: boolean;
/** the catalog graph revision of the branch the pipeline runs for */
"revision"?: number;
/** the run on request's id: its composition writes no want (ADR 0666 section 18) */
"run"?: string;
/** the source revision of the watched branch; absent for a run on request */
"source"?: number;
"step": "composition";
}
/** the composer program, chosen once when the run started */
export interface CompositionRunProgram {
"commit"?: string;
"directory"?: string;
/** the node-engine fingerprint it was chosen from */
"fingerprint"?: string;
"repository"?: string;
}
/** one composition run of a candidate and a machine, a key of the assigner's state composition-runs (design 47 G §719, §728; A-469u) */
export interface CompositionRun {
/** the id of the build seat's run ask */
"ask"?: string;
/** the candidate's key: <branch>.<revision>, or run-<id> for a run on request */
"candidate": string;
"ended"?: string;
/** the digest of the kept request */
"input"?: string;
/** the key, <candidate key>.<machine>, each part escaped as a key's name */
"key": string;
"machine": string;
"outcome"?: "passed" | "failed" | "could not run";
/** the composer program, chosen once when the run started */
"program"?: CompositionRunProgram;
/** the composition steps reading the run */
"readers"?: CompositionReader[];
/** the outcome's words */
"said"?: string;
"started"?: string;
/** that machine's composer verdict (design 47 G §721) */
"verdict"?: Record<string, unknown>;
}
export interface DifferenceRefusedItem {
"module": string;
"why": string;
@@ -333,6 +394,26 @@ export interface NodeEntryRef {
"node": string;
}
/** the step that asked the run, for a test step reading another's run */
export interface SharedAskedBy {
/** its artifact, <module>:<artifact> */
"artifact": string;
/** its pipeline's key */
"pipeline": string;
}
/** a run whose result a step took or waits on, asked once for every step that reads it (design 47 G §729, A-469t): for a composition step one per machine composed, `run` the `composition-runs` key and `ask` its run ask's id; for a test step one with no machine, `run` the `test-runs` key, `ask` its build seat ask's id and `asked-by` the step that asked the run, left out for that step itself */
export interface Shared {
/** the id of the run's ask of the build seat */
"ask": string;
/** the step that asked the run, for a test step reading another's run */
"asked-by"?: SharedAskedBy;
/** the machine composed, for a composition run */
"machine"?: string;
/** the run's key: in the assigner's composition-runs, or the runner's test-runs */
"run": string;
}
/** the composition step's end, said by the assigner on the node it runs on (ADR 0666 sections 7, 21): the runner takes it only from that holder's account, naming the ask, the commit and the fingerprint it was asked at */
export interface StepEnded {
/** for a rerun, the caller the runtime proved */
@@ -351,6 +432,8 @@ export interface StepEnded {
"rerun"?: boolean;
/** why it failed or could not run: the two modules owning one path, the part not heard */
"said"?: string;
/** per machine composed, the composition run the step read, its ask and so where its verdict was taken (design 47 G §723, §729) */
"shared"?: Shared[];
"started"?: string;
"step": "composition";
/** the layout version */
@@ -499,6 +582,36 @@ export interface InputAnswer {
"digest": string;
}
/** is what compositions takes. */
export interface CompositionsInput {
/** the candidate's key */
"candidate"?: string;
"machine"?: string;
}
/** is what compositions answers. */
export interface CompositionsAnswer {
"fill": Fill;
"runs": CompositionRun[];
}
/** is what compositions-drop takes. */
export interface CompositionsDropInput {
/** the candidate's key */
"candidate": string;
"machine": string;
/** why, written with the caller the runtime proves in the hand-act log */
"why": string;
}
/** is what compositions-drop answers. */
export interface CompositionsDropAnswer {
/** the readers it ended */
"ended"?: CompositionReader[];
/** the entry deleted */
"run": CompositionRun;
}
/** is the body of step. */
export type StepAccept = StepRun;
@@ -582,6 +695,8 @@ export interface StepProgressEvent {
"asker": string;
"at": string;
"phase": "fetch" | "build" | "run" | "report";
/** the composition runs the step waits on, by machine, each with its ask (design 47 G §723, §729) */
"shared"?: Shared[];
}
/** is one value of the state wants under the key want.<node>.<module>. */
@@ -11,6 +11,8 @@ export const verbs = {
entry: "entry",
difference: "difference",
input: "input",
compositions: "compositions",
compositionsDrop: "compositions-drop",
};
export const accepts = {