diff --git a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go index f1cbb799..9962fb6f 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go @@ -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, : + 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, .., 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, : + 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 diff --git a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract_test.go b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract_test.go index 726e8dcd..b5ec6e57 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract_test.go @@ -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)) diff --git a/modules/mesh-delivery-contracts/go/seats/meshwants/contract.go b/modules/mesh-delivery-contracts/go/seats/meshwants/contract.go index 8f07d5d1..9b1bbdc4 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshwants/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/meshwants/contract.go @@ -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, .., 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: ., or run- 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, ., 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, : + 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. diff --git a/modules/mesh-delivery-contracts/go/seats/meshwants/contract_test.go b/modules/mesh-delivery-contracts/go/seats/meshwants/contract_test.go index f27c6e8d..9ed6c320 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshwants/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/meshwants/contract_test.go @@ -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)) diff --git a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/events.json b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/events.json index 48448ab1..205105e4 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/events.json +++ b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/events.json @@ -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" + } } ] diff --git a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/verbs.json b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/verbs.json index 7a961ae5..656d12bf 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/verbs.json +++ b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/verbs.json @@ -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" + } + ] + } } ] diff --git a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json index 41b0d914..67dcaba9 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json +++ b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json @@ -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, :" + } + }, + "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, :" + } + }, + "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, .., 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" + ] } } } diff --git a/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/events.json b/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/events.json index 17d815d2..6cdc780f 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/events.json +++ b/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/events.json @@ -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" + } + ] + } } ] diff --git a/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/verbs.json b/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/verbs.json index 37bf95d6..df3caf96 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/verbs.json +++ b/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/verbs.json @@ -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" + } + ] + } } ] diff --git a/modules/mesh-delivery-contracts/seats/mesh-wants/seat.json b/modules/mesh-delivery-contracts/seats/mesh-wants/seat.json index aaedee33..ece6bb41 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-wants/seat.json +++ b/modules/mesh-delivery-contracts/seats/mesh-wants/seat.json @@ -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, :" + } + }, + "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, .., 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, ., each part escaped as a key's name" + }, + "candidate": { + "type": "string", + "description": "the candidate's key: ., or run- 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": [ diff --git a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts index 5f8b49b3..e0b467c5 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts @@ -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, : */ + "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, .., 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, : */ + "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; diff --git a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.js b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.js index e797aedb..ac1575aa 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.js +++ b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.js @@ -17,6 +17,8 @@ export const verbs = { accept: "accept", cancel: "cancel", askAgain: "ask-again", + testRuns: "test-runs", + testRunsDrop: "test-runs-drop", }; export const events = { diff --git a/modules/mesh-delivery-contracts/ts/seats/meshwants/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/meshwants/index.d.ts index 93d69098..bfd117e4 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshwants/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/meshwants/index.d.ts @@ -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, .., 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: ., or run- for a run on request */ + "candidate": string; + "ended"?: string; + /** the digest of the kept request */ + "input"?: string; + /** the key, ., 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; +} + 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, : */ + "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... */ diff --git a/modules/mesh-delivery-contracts/ts/seats/meshwants/index.js b/modules/mesh-delivery-contracts/ts/seats/meshwants/index.js index d997b68c..391640d1 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshwants/index.js +++ b/modules/mesh-delivery-contracts/ts/seats/meshwants/index.js @@ -11,6 +11,8 @@ export const verbs = { entry: "entry", difference: "difference", input: "input", + compositions: "compositions", + compositionsDrop: "compositions-drop", }; export const accepts = {