diff --git a/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract.go b/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract.go index 697453b45..115fc78c5 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract.go @@ -17,13 +17,13 @@ const Seat = "node-build-go" const Form = 1 // FormBuildStep is the form of what the part build-step adds. -const FormBuildStep = 1 +const FormBuildStep = 2 // The forms and the digest of the fields this contract was generated from: the generator's compare fails a definition // whose fields changed while its forms did not (design 47 H2 §780). const ( - generatedForms = "1 build-step:1" - generatedFieldsDigest = "AskArtifact=35eb85c27e97 AskTaken=8c917075eed4 AskTakenEvent=e4fc9b81e066 BuiltArtifact=b5fcef7a8b58 BuiltArtifactResolvedItem=3bcbbcfd1a1f Capacity=b40cca7ccdfa CheckAccept=ef89c6962ae4 CheckRunAccept=ef89c6962ae4 CheckStepAccept=ef89c6962ae4 CurrentAnswer=7538f2f5e68e DeliveryAccept=ef89c6962ae4 DeliveryStepAccept=ef89c6962ae4 DetectedStep=a6fcd7d0eca4 DetectedSteps=05198185c776 DetectedStepsByModuleArtifactValue=cb35b5775cc6 Drop=fb4637978e86 DropAnswer=7538f2f5e68e Fetch=6e12677bbc2c FetchAnswer=46fc3d5bd7ee FetchBesideItem=774b4bf88ba4 FetchBuildsItem=aee5adc97246 FetchPackage=20d1668a0eee FetchRefusal=de1518848b4c KeptArtifactAnswer=706729f8ccb9 KeptResult=8657683cdcd7 LevelAnswer=143c69c28a6a LevelAnswerDigest=d54b7fd7b1da LevelAnswerDigestNeedsItem=946b37d1d4a1 LevelAnswerDigestPackagesItem=a7d30558470d LevelAnswerKeptItem=85d3c2f78632 LevelAnswerUnmetItem=946b37d1d4a1 ModuleTree=00bb59e9f262 OutputAnswer=a3b42bd5e791 Pause=d6521e0cdd1e PauseAnswer=7538f2f5e68e PausesByCapacityNodeValue=5392cf505c80 PausesByDroppedIDValue=0e15ac9cacbd PausesByPausedNodeValue=d111aad0f0cf PlacedBeside=53479337ff18 Program=b48ae74f34e0 RecheckAccept=ef89c6962ae4 ResumeAnswer=7538f2f5e68e RunHead=774b4bf88ba4 RunInput=3dc41505a4b7 RunJob=88af2a7f432b RunProgram=6fd636999d54 Step=607e5f1a91cc StepAsk=9a8c9c8918b1 StepAskBuild=de784b6c05da StepAskCheck=b77941df6dea StepAskCompose=4c6a08e10231 StepEnded=45ff4650b620 StepEndedEvent=207787118dac StepProgress=d25781cc895a StepProgressEvent=179344ce0ca2 StepResult=67f88be36d0e StepRun=6d551ed0ed46 StepsAnswer=2c02cac2df23 StepsByAskerNodeIDValue=50ccfd4cebd8 StepsByNodeIDValue=50ccfd4cebd8 TakenVersion=1b8d0547f61e TestCounts=9c1332427159 Toolchain=8ecb7debf9ad ToolchainReported=d26392767c50 ToolchainReportedEvent=fa0a431c9c7b ToolchainUsed=6cc7ccabc9f8 ToolchainsByNodeLanguageValue=f97d1dd27613" + generatedForms = "1 build-step:2" + generatedFieldsDigest = "AskArtifact=35eb85c27e97 AskTaken=8c917075eed4 AskTakenEvent=e4fc9b81e066 BuiltArtifact=b5fcef7a8b58 BuiltArtifactResolvedItem=3bcbbcfd1a1f Capacity=b40cca7ccdfa CheckAccept=ef89c6962ae4 CheckRunAccept=ef89c6962ae4 CheckStepAccept=ef89c6962ae4 CurrentAnswer=e39824e012cb CurrentAsk=ac167e5ee11f DeliveryAccept=ef89c6962ae4 DeliveryStepAccept=ef89c6962ae4 DetectedStep=a6fcd7d0eca4 DetectedSteps=05198185c776 DetectedStepsByModuleArtifactValue=cb35b5775cc6 Drop=fb4637978e86 DropAnswer=7538f2f5e68e FailingTest=f3fb3f1a3ca8 Fetch=6e12677bbc2c FetchAnswer=46fc3d5bd7ee FetchBesideItem=774b4bf88ba4 FetchBuildsItem=aee5adc97246 FetchPackage=20d1668a0eee FetchRefusal=de1518848b4c KeptArtifactAnswer=706729f8ccb9 KeptResult=8657683cdcd7 LevelAnswer=143c69c28a6a LevelAnswerDigest=d54b7fd7b1da LevelAnswerDigestNeedsItem=946b37d1d4a1 LevelAnswerDigestPackagesItem=a7d30558470d LevelAnswerKeptItem=85d3c2f78632 LevelAnswerUnmetItem=946b37d1d4a1 ModuleTree=00bb59e9f262 NotRun=d322fb1eb153 OutputAnswer=97ba4bd92bf9 Pause=d6521e0cdd1e PauseAnswer=7538f2f5e68e PausesByCapacityNodeValue=5392cf505c80 PausesByDroppedIDValue=0e15ac9cacbd PausesByPausedNodeValue=d111aad0f0cf PlacedBeside=53479337ff18 Program=b48ae74f34e0 RecheckAccept=ef89c6962ae4 ResumeAnswer=7538f2f5e68e RunHead=774b4bf88ba4 RunInput=3dc41505a4b7 RunJob=88af2a7f432b RunProgram=6fd636999d54 Step=607e5f1a91cc StepAsk=9a8c9c8918b1 StepAskBuild=de784b6c05da StepAskCheck=b77941df6dea StepAskCompose=4c6a08e10231 StepEnded=11c0b83bf3a5 StepEndedEvent=207787118dac StepProgress=d25781cc895a StepProgressEvent=179344ce0ca2 StepResult=67f88be36d0e StepRun=a7a81f25515f StepsAnswer=2c02cac2df23 StepsByAskerNodeIDValue=50ccfd4cebd8 StepsByNodeIDValue=50ccfd4cebd8 TakenVersion=1b8d0547f61e TestCounts=9c1332427159 Toolchain=8ecb7debf9ad ToolchainReported=d26392767c50 ToolchainReportedEvent=fa0a431c9c7b ToolchainUsed=6cc7ccabc9f8 ToolchainsByNodeLanguageValue=f97d1dd27613" ) const ( @@ -429,6 +429,18 @@ type ComposeAnswer struct { Verdict any `json:"verdict,omitempty"` } +// CurrentAsk is an ask a holder runs now (design 47 H2 §801). +type CurrentAsk struct { + // who asked it + Asker string `json:"asker"` + // the ask's id + ID string `json:"id"` + // the ask's kind + Kind string `json:"kind"` + Module string `json:"module,omitempty"` + Started time.Time `json:"started"` +} + // DetectedStep is a type of the contract. type DetectedStep struct { // the packages the step runs, by the language's convention @@ -465,6 +477,14 @@ type Drop struct { Why string `json:"why"` } +// FailingTest is a failing test and its words (design 47 H2 §791). +type FailingTest struct { + // the test's name + Test string `json:"test"` + // what the test said + Words string `json:"words,omitempty"` +} + // FetchBesideItem is a type of the contract. type FetchBesideItem struct { Commit string `json:"commit"` @@ -541,6 +561,21 @@ type FetchRefusal struct { Reason string `json:"reason"` } +// InstallAsk is an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest. +type InstallAsk struct { + // who asked it + Asker string `json:"asker"` + // the commit the lock is read at + Commit string `json:"commit"` + // the ask's id + ID string `json:"id"` + // the package lock's text at the commit + Lock string `json:"lock"` + Module string `json:"module"` + // the runner's pipeline key + Pipeline string `json:"pipeline"` +} + // KeptResult is a package's passing result the runner keeps, by the digest of what its tests read (ADR 0666 section 8): the step runs no package whose digest and level it names. type KeptResult struct { // sha256: of what the package's tests read @@ -608,6 +643,14 @@ type ModuleTree struct { Tree string `json:"tree"` } +// NotRun is a test that did not run and why (design 47 H2 §800, H-A-367 (3)). +type NotRun struct { + // why it did not run + Reason string `json:"reason"` + // the test's name + Test string `json:"test"` +} + // Pause is whether the node takes no new ask. type Pause struct { // when (RFC 3339 time) @@ -776,6 +819,8 @@ type StepAsk struct { // StepEnded is an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G section 602): a pipeline step's end names the pipeline, the commit and the fingerprint it was asked at, which the runner takes only from that holder's account (ADR 0666 sections 7, 21); the end of any other ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (design 47 G section 548). type StepEnded struct { + // for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800) + Archive string `json:"archive,omitempty"` Artifact string `json:"artifact,omitempty"` // the ask's id, by which a reader takes only its own asks Ask string `json:"ask"` @@ -799,6 +844,8 @@ type StepEnded struct { Module string `json:"module,omitempty"` // the node that ran it, as in the subject Node string `json:"node"` + // the tests that did not run, each with its reason, counted apart from passed and failed (design 47 H2 §800) + NotRun []NotRun `json:"not-run,omitempty"` // never passed for a step that ran nothing Outcome string `json:"outcome"` // the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254) @@ -879,6 +926,8 @@ type StepResult struct { // StepRun is one pipeline step of one artifact at one commit (ADR 0666 sections 7, 8, 17): the step a build seat runs in its sandbox from the change's own heads, the names the lint step needs and the kept results it may skip. type StepRun struct { + // the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800) + Archive string `json:"archive,omitempty"` // the artifact reference, : Artifact string `json:"artifact"` // the watched branch, or the branch of a run on request @@ -973,7 +1022,29 @@ type CurrentInput struct { } // CurrentAnswer is what current answers. -type CurrentAnswer = map[string]any +type CurrentAnswer struct { + // every ask it runs, whoever asked it + Asks []CurrentAsk `json:"asks"` + // how many steps it runs at once + Capacity int64 `json:"capacity"` + // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). + Form int64 `json:"form,omitempty"` + // the node this holder runs on + Node string `json:"node"` + // since when it takes asks or not, as takes says + Since *time.Time `json:"since,omitempty"` + // whether it takes asks now + Takes bool `json:"takes"` + // why it takes none; absent while it takes asks + WhyNot string `json:"why-not,omitempty"` +} + +// The values of CurrentAnswer's why-not. +const ( + CurrentAnswerWhyNotPaused = "paused" + CurrentAnswerWhyNotCapacity0 = "capacity 0" + CurrentAnswerWhyNotUnhealthy = "unhealthy" +) // PauseInput is what pause takes. type PauseInput struct { @@ -1075,20 +1146,24 @@ type StepsAnswer struct { // OutputInput is what output takes. type OutputInput struct { - // the ask's id, the `output-object` of its step key or its step-ended naming it + // the ask's id Ask string `json:"ask"` - // 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements - Call string `json:"call"` } // OutputAnswer is what output answers. type OutputAnswer struct { // the ask's id Ask string `json:"ask"` - // how many chunks are sent; 0 when this node keeps no answer of that ask - Chunks int64 `json:"chunks"` + // the failing tests with their words + Failing []FailingTest `json:"failing,omitempty"` // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). Form int64 `json:"form,omitempty"` + // the output is past the outputs objects' max-age, kept no longer + NoLongerKept bool `json:"no-longer-kept,omitempty"` + // the output's last 64 KB + Output string `json:"output,omitempty"` + // the whole output's size in bytes + Size int64 `json:"size,omitempty"` } // DeliveryAccept is the body of delivery. diff --git a/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract_test.go b/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract_test.go index ad427938d..0456d014c 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildgo/contract_test.go @@ -123,10 +123,16 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v StepsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "steps answers a drop that the hand-act log refused", subject: "", given: "{\"error\":\"the hand-act log refused: nothing was deleted\"}", wire: "{\"error\":\"the hand-act log refused: nothing was deleted\"}", decode: func(b []byte) (any, error) { var v StepsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "output asks a run's answer by its ask", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"call\":\"0123456789abcdef0123456789abcdef\"}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"call\":\"0123456789abcdef0123456789abcdef\"}", + {name: "output asks a step's output by its ask", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\"}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\"}", decode: func(b []byte) (any, error) { var v OutputInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "output answers how many chunks carry the answer", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"chunks\":3}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"chunks\":3}", + {name: "output answers the last 64 KB, the size and the failing tests with their words", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"failing\":[{\"test\":\"TestTheBusWhole\",\"words\":\"bus_test.go:41: no responders\"}],\"output\":\"--- FAIL: TestTheBusWhole (0.20s)\\n bus_test.go:41: no responders\\nFAIL\\n\",\"size\":181234}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"failing\":[{\"test\":\"TestTheBusWhole\",\"words\":\"bus_test.go:41: no responders\"}],\"output\":\"--- FAIL: TestTheBusWhole (0.20s)\\n bus_test.go:41: no responders\\nFAIL\\n\",\"size\":181234}", decode: func(b []byte) (any, error) { var v OutputAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "output answers an output past the objects' max-age as no longer kept", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5e\",\"no-longer-kept\":true}", wire: "{\"ask\":\"m2kx9a1b3c4d5e\",\"no-longer-kept\":true}", + decode: func(b []byte) (any, error) { var v OutputAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "current answers a holder that takes asks and the asks it runs, whoever asked", subject: "", given: "{\"asks\":[{\"asker\":\"mesh-delivery-pipeline\",\"id\":\"m2kx9a1b3c4d5f\",\"kind\":\"step\",\"module\":\"nats\",\"started\":\"2026-11-21T22:01:00Z\"},{\"asker\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"kind\":\"build\",\"module\":\"nats\",\"started\":\"2026-11-21T22:02:00Z\"}],\"capacity\":2,\"node\":\"anchor\",\"since\":\"2026-11-21T22:00:00Z\",\"takes\":true}", wire: "{\"asks\":[{\"asker\":\"mesh-delivery-pipeline\",\"id\":\"m2kx9a1b3c4d5f\",\"kind\":\"step\",\"module\":\"nats\",\"started\":\"2026-11-21T22:01:00Z\"},{\"asker\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"kind\":\"build\",\"module\":\"nats\",\"started\":\"2026-11-21T22:02:00Z\"}],\"capacity\":2,\"node\":\"anchor\",\"since\":\"2026-11-21T22:00:00Z\",\"takes\":true}", + decode: func(b []byte) (any, error) { var v CurrentAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "current answers a paused holder, since when", subject: "", given: "{\"asks\":[],\"capacity\":2,\"node\":\"home-server\",\"since\":\"2026-11-21T21:00:00Z\",\"takes\":false,\"why-not\":\"paused\"}", wire: "{\"asks\":[],\"capacity\":2,\"node\":\"home-server\",\"since\":\"2026-11-21T21:00:00Z\",\"takes\":false,\"why-not\":\"paused\"}", + decode: func(b []byte) (any, error) { var v CurrentAnswer; 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/nodebuildimage/contract.go b/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract.go index 73c3ba14f..78b95b7af 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract.go @@ -17,13 +17,13 @@ const Seat = "node-build-image" const Form = 1 // FormBuildStep is the form of what the part build-step adds. -const FormBuildStep = 1 +const FormBuildStep = 2 // The forms and the digest of the fields this contract was generated from: the generator's compare fails a definition // whose fields changed while its forms did not (design 47 H2 §780). const ( - generatedForms = "1 build-step:1" - generatedFieldsDigest = "AskArtifact=35eb85c27e97 AskTaken=8c917075eed4 AskTakenEvent=e4fc9b81e066 BuiltArtifact=b5fcef7a8b58 BuiltArtifactResolvedItem=3bcbbcfd1a1f Capacity=b40cca7ccdfa CheckAccept=ef89c6962ae4 CheckStepAccept=ef89c6962ae4 CurrentAnswer=7538f2f5e68e DeliveryAccept=ef89c6962ae4 DeliveryStepAccept=ef89c6962ae4 DetectedStep=a6fcd7d0eca4 DetectedSteps=05198185c776 DetectedStepsByModuleArtifactValue=cb35b5775cc6 Drop=fb4637978e86 DropAnswer=7538f2f5e68e Fetch=6e12677bbc2c FetchAnswer=46fc3d5bd7ee FetchBesideItem=774b4bf88ba4 FetchBuildsItem=aee5adc97246 FetchPackage=20d1668a0eee FetchRefusal=de1518848b4c KeptArtifactAnswer=706729f8ccb9 KeptResult=8657683cdcd7 LevelAnswer=143c69c28a6a LevelAnswerDigest=d54b7fd7b1da LevelAnswerDigestNeedsItem=946b37d1d4a1 LevelAnswerDigestPackagesItem=a7d30558470d LevelAnswerKeptItem=85d3c2f78632 LevelAnswerUnmetItem=946b37d1d4a1 ModuleTree=00bb59e9f262 OutputAnswer=a3b42bd5e791 Pause=d6521e0cdd1e PauseAnswer=7538f2f5e68e PausesByCapacityNodeValue=5392cf505c80 PausesByDroppedIDValue=0e15ac9cacbd PausesByPausedNodeValue=d111aad0f0cf PlacedBeside=53479337ff18 Program=b48ae74f34e0 RecheckAccept=ef89c6962ae4 ResumeAnswer=7538f2f5e68e RunHead=774b4bf88ba4 RunInput=3dc41505a4b7 RunJob=88af2a7f432b RunProgram=6fd636999d54 Step=607e5f1a91cc StepAsk=9a8c9c8918b1 StepAskBuild=de784b6c05da StepAskCheck=b77941df6dea StepAskCompose=4c6a08e10231 StepEnded=45ff4650b620 StepEndedEvent=207787118dac StepProgress=d25781cc895a StepProgressEvent=179344ce0ca2 StepResult=67f88be36d0e StepRun=6d551ed0ed46 StepsAnswer=2c02cac2df23 StepsByAskerNodeIDValue=50ccfd4cebd8 StepsByNodeIDValue=50ccfd4cebd8 TakenVersion=1b8d0547f61e TestCounts=9c1332427159 Toolchain=8ecb7debf9ad ToolchainReported=d26392767c50 ToolchainReportedEvent=fa0a431c9c7b ToolchainUsed=6cc7ccabc9f8 ToolchainsByNodeLanguageValue=f97d1dd27613" + generatedForms = "1 build-step:2" + generatedFieldsDigest = "AskArtifact=35eb85c27e97 AskTaken=8c917075eed4 AskTakenEvent=e4fc9b81e066 BuiltArtifact=b5fcef7a8b58 BuiltArtifactResolvedItem=3bcbbcfd1a1f Capacity=b40cca7ccdfa CheckAccept=ef89c6962ae4 CheckStepAccept=ef89c6962ae4 CurrentAnswer=e39824e012cb CurrentAsk=ac167e5ee11f DeliveryAccept=ef89c6962ae4 DeliveryStepAccept=ef89c6962ae4 DetectedStep=a6fcd7d0eca4 DetectedSteps=05198185c776 DetectedStepsByModuleArtifactValue=cb35b5775cc6 Drop=fb4637978e86 DropAnswer=7538f2f5e68e FailingTest=f3fb3f1a3ca8 Fetch=6e12677bbc2c FetchAnswer=46fc3d5bd7ee FetchBesideItem=774b4bf88ba4 FetchBuildsItem=aee5adc97246 FetchPackage=20d1668a0eee FetchRefusal=de1518848b4c KeptArtifactAnswer=706729f8ccb9 KeptResult=8657683cdcd7 LevelAnswer=143c69c28a6a LevelAnswerDigest=d54b7fd7b1da LevelAnswerDigestNeedsItem=946b37d1d4a1 LevelAnswerDigestPackagesItem=a7d30558470d LevelAnswerKeptItem=85d3c2f78632 LevelAnswerUnmetItem=946b37d1d4a1 ModuleTree=00bb59e9f262 NotRun=d322fb1eb153 OutputAnswer=97ba4bd92bf9 Pause=d6521e0cdd1e PauseAnswer=7538f2f5e68e PausesByCapacityNodeValue=5392cf505c80 PausesByDroppedIDValue=0e15ac9cacbd PausesByPausedNodeValue=d111aad0f0cf PlacedBeside=53479337ff18 Program=b48ae74f34e0 RecheckAccept=ef89c6962ae4 ResumeAnswer=7538f2f5e68e RunHead=774b4bf88ba4 RunInput=3dc41505a4b7 RunJob=88af2a7f432b RunProgram=6fd636999d54 Step=607e5f1a91cc StepAsk=9a8c9c8918b1 StepAskBuild=de784b6c05da StepAskCheck=b77941df6dea StepAskCompose=4c6a08e10231 StepEnded=11c0b83bf3a5 StepEndedEvent=207787118dac StepProgress=d25781cc895a StepProgressEvent=179344ce0ca2 StepResult=67f88be36d0e StepRun=a7a81f25515f StepsAnswer=2c02cac2df23 StepsByAskerNodeIDValue=50ccfd4cebd8 StepsByNodeIDValue=50ccfd4cebd8 TakenVersion=1b8d0547f61e TestCounts=9c1332427159 Toolchain=8ecb7debf9ad ToolchainReported=d26392767c50 ToolchainReportedEvent=fa0a431c9c7b ToolchainUsed=6cc7ccabc9f8 ToolchainsByNodeLanguageValue=f97d1dd27613" ) const ( @@ -427,6 +427,18 @@ type ComposeAnswer struct { Verdict any `json:"verdict,omitempty"` } +// CurrentAsk is an ask a holder runs now (design 47 H2 §801). +type CurrentAsk struct { + // who asked it + Asker string `json:"asker"` + // the ask's id + ID string `json:"id"` + // the ask's kind + Kind string `json:"kind"` + Module string `json:"module,omitempty"` + Started time.Time `json:"started"` +} + // DetectedStep is a type of the contract. type DetectedStep struct { // the packages the step runs, by the language's convention @@ -463,6 +475,14 @@ type Drop struct { Why string `json:"why"` } +// FailingTest is a failing test and its words (design 47 H2 §791). +type FailingTest struct { + // the test's name + Test string `json:"test"` + // what the test said + Words string `json:"words,omitempty"` +} + // FetchBesideItem is a type of the contract. type FetchBesideItem struct { Commit string `json:"commit"` @@ -539,6 +559,21 @@ type FetchRefusal struct { Reason string `json:"reason"` } +// InstallAsk is an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest. +type InstallAsk struct { + // who asked it + Asker string `json:"asker"` + // the commit the lock is read at + Commit string `json:"commit"` + // the ask's id + ID string `json:"id"` + // the package lock's text at the commit + Lock string `json:"lock"` + Module string `json:"module"` + // the runner's pipeline key + Pipeline string `json:"pipeline"` +} + // KeptResult is a package's passing result the runner keeps, by the digest of what its tests read (ADR 0666 section 8): the step runs no package whose digest and level it names. type KeptResult struct { // sha256: of what the package's tests read @@ -606,6 +641,14 @@ type ModuleTree struct { Tree string `json:"tree"` } +// NotRun is a test that did not run and why (design 47 H2 §800, H-A-367 (3)). +type NotRun struct { + // why it did not run + Reason string `json:"reason"` + // the test's name + Test string `json:"test"` +} + // Pause is whether the node takes no new ask. type Pause struct { // when (RFC 3339 time) @@ -774,6 +817,8 @@ type StepAsk struct { // StepEnded is an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G section 602): a pipeline step's end names the pipeline, the commit and the fingerprint it was asked at, which the runner takes only from that holder's account (ADR 0666 sections 7, 21); the end of any other ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (design 47 G section 548). type StepEnded struct { + // for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800) + Archive string `json:"archive,omitempty"` Artifact string `json:"artifact,omitempty"` // the ask's id, by which a reader takes only its own asks Ask string `json:"ask"` @@ -797,6 +842,8 @@ type StepEnded struct { Module string `json:"module,omitempty"` // the node that ran it, as in the subject Node string `json:"node"` + // the tests that did not run, each with its reason, counted apart from passed and failed (design 47 H2 §800) + NotRun []NotRun `json:"not-run,omitempty"` // never passed for a step that ran nothing Outcome string `json:"outcome"` // the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254) @@ -877,6 +924,8 @@ type StepResult struct { // StepRun is one pipeline step of one artifact at one commit (ADR 0666 sections 7, 8, 17): the step a build seat runs in its sandbox from the change's own heads, the names the lint step needs and the kept results it may skip. type StepRun struct { + // the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800) + Archive string `json:"archive,omitempty"` // the artifact reference, : Artifact string `json:"artifact"` // the watched branch, or the branch of a run on request @@ -971,7 +1020,29 @@ type CurrentInput struct { } // CurrentAnswer is what current answers. -type CurrentAnswer = map[string]any +type CurrentAnswer struct { + // every ask it runs, whoever asked it + Asks []CurrentAsk `json:"asks"` + // how many steps it runs at once + Capacity int64 `json:"capacity"` + // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). + Form int64 `json:"form,omitempty"` + // the node this holder runs on + Node string `json:"node"` + // since when it takes asks or not, as takes says + Since *time.Time `json:"since,omitempty"` + // whether it takes asks now + Takes bool `json:"takes"` + // why it takes none; absent while it takes asks + WhyNot string `json:"why-not,omitempty"` +} + +// The values of CurrentAnswer's why-not. +const ( + CurrentAnswerWhyNotPaused = "paused" + CurrentAnswerWhyNotCapacity0 = "capacity 0" + CurrentAnswerWhyNotUnhealthy = "unhealthy" +) // PauseInput is what pause takes. type PauseInput struct { @@ -1073,20 +1144,24 @@ type StepsAnswer struct { // OutputInput is what output takes. type OutputInput struct { - // the ask's id, the `output-object` of its step key or its step-ended naming it + // the ask's id Ask string `json:"ask"` - // 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements - Call string `json:"call"` } // OutputAnswer is what output answers. type OutputAnswer struct { // the ask's id Ask string `json:"ask"` - // how many chunks are sent; 0 when this node keeps no answer of that ask - Chunks int64 `json:"chunks"` + // the failing tests with their words + Failing []FailingTest `json:"failing,omitempty"` // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). Form int64 `json:"form,omitempty"` + // the output is past the outputs objects' max-age, kept no longer + NoLongerKept bool `json:"no-longer-kept,omitempty"` + // the output's last 64 KB + Output string `json:"output,omitempty"` + // the whole output's size in bytes + Size int64 `json:"size,omitempty"` } // DeliveryAccept is the body of delivery. diff --git a/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract_test.go b/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract_test.go index 5f2ec4668..a65434fc2 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildimage/contract_test.go @@ -105,10 +105,16 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v StepsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "steps answers a drop that the hand-act log refused", subject: "", given: "{\"error\":\"the hand-act log refused: nothing was deleted\"}", wire: "{\"error\":\"the hand-act log refused: nothing was deleted\"}", decode: func(b []byte) (any, error) { var v StepsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "output asks a run's answer by its ask", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"call\":\"0123456789abcdef0123456789abcdef\"}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"call\":\"0123456789abcdef0123456789abcdef\"}", + {name: "output asks a step's output by its ask", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\"}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\"}", decode: func(b []byte) (any, error) { var v OutputInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "output answers how many chunks carry the answer", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"chunks\":3}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"chunks\":3}", + {name: "output answers the last 64 KB, the size and the failing tests with their words", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"failing\":[{\"test\":\"TestTheBusWhole\",\"words\":\"bus_test.go:41: no responders\"}],\"output\":\"--- FAIL: TestTheBusWhole (0.20s)\\n bus_test.go:41: no responders\\nFAIL\\n\",\"size\":181234}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"failing\":[{\"test\":\"TestTheBusWhole\",\"words\":\"bus_test.go:41: no responders\"}],\"output\":\"--- FAIL: TestTheBusWhole (0.20s)\\n bus_test.go:41: no responders\\nFAIL\\n\",\"size\":181234}", decode: func(b []byte) (any, error) { var v OutputAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "output answers an output past the objects' max-age as no longer kept", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5e\",\"no-longer-kept\":true}", wire: "{\"ask\":\"m2kx9a1b3c4d5e\",\"no-longer-kept\":true}", + decode: func(b []byte) (any, error) { var v OutputAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "current answers a holder that takes asks and the asks it runs, whoever asked", subject: "", given: "{\"asks\":[{\"asker\":\"mesh-delivery-pipeline\",\"id\":\"m2kx9a1b3c4d5f\",\"kind\":\"step\",\"module\":\"nats\",\"started\":\"2026-11-21T22:01:00Z\"},{\"asker\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"kind\":\"build\",\"module\":\"nats\",\"started\":\"2026-11-21T22:02:00Z\"}],\"capacity\":2,\"node\":\"anchor\",\"since\":\"2026-11-21T22:00:00Z\",\"takes\":true}", wire: "{\"asks\":[{\"asker\":\"mesh-delivery-pipeline\",\"id\":\"m2kx9a1b3c4d5f\",\"kind\":\"step\",\"module\":\"nats\",\"started\":\"2026-11-21T22:01:00Z\"},{\"asker\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"kind\":\"build\",\"module\":\"nats\",\"started\":\"2026-11-21T22:02:00Z\"}],\"capacity\":2,\"node\":\"anchor\",\"since\":\"2026-11-21T22:00:00Z\",\"takes\":true}", + decode: func(b []byte) (any, error) { var v CurrentAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "current answers a paused holder, since when", subject: "", given: "{\"asks\":[],\"capacity\":2,\"node\":\"home-server\",\"since\":\"2026-11-21T21:00:00Z\",\"takes\":false,\"why-not\":\"paused\"}", wire: "{\"asks\":[],\"capacity\":2,\"node\":\"home-server\",\"since\":\"2026-11-21T21:00:00Z\",\"takes\":false,\"why-not\":\"paused\"}", + decode: func(b []byte) (any, error) { var v CurrentAnswer; 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/nodebuildnode/contract.go b/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract.go index e512702ac..adecaac30 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract.go @@ -17,13 +17,13 @@ const Seat = "node-build-node" const Form = 1 // FormBuildStep is the form of what the part build-step adds. -const FormBuildStep = 1 +const FormBuildStep = 2 // The forms and the digest of the fields this contract was generated from: the generator's compare fails a definition // whose fields changed while its forms did not (design 47 H2 §780). const ( - generatedForms = "1 build-step:1" - generatedFieldsDigest = "AskArtifact=35eb85c27e97 AskTaken=8c917075eed4 AskTakenEvent=e4fc9b81e066 BuiltArtifact=b5fcef7a8b58 BuiltArtifactResolvedItem=3bcbbcfd1a1f Capacity=b40cca7ccdfa CheckAccept=ef89c6962ae4 CheckStepAccept=ef89c6962ae4 CurrentAnswer=7538f2f5e68e DeliveryAccept=ef89c6962ae4 DeliveryStepAccept=ef89c6962ae4 DetectedStep=a6fcd7d0eca4 DetectedSteps=05198185c776 DetectedStepsByModuleArtifactValue=cb35b5775cc6 Drop=fb4637978e86 DropAnswer=7538f2f5e68e Fetch=6e12677bbc2c FetchAnswer=46fc3d5bd7ee FetchBesideItem=774b4bf88ba4 FetchBuildsItem=aee5adc97246 FetchPackage=20d1668a0eee FetchRefusal=de1518848b4c KeptArtifactAnswer=706729f8ccb9 KeptResult=8657683cdcd7 LevelAnswer=143c69c28a6a LevelAnswerDigest=d54b7fd7b1da LevelAnswerDigestNeedsItem=946b37d1d4a1 LevelAnswerDigestPackagesItem=a7d30558470d LevelAnswerKeptItem=85d3c2f78632 LevelAnswerUnmetItem=946b37d1d4a1 ModuleTree=00bb59e9f262 OutputAnswer=a3b42bd5e791 Pause=d6521e0cdd1e PauseAnswer=7538f2f5e68e PausesByCapacityNodeValue=5392cf505c80 PausesByDroppedIDValue=0e15ac9cacbd PausesByPausedNodeValue=d111aad0f0cf PlacedBeside=53479337ff18 Program=b48ae74f34e0 RecheckAccept=ef89c6962ae4 ResumeAnswer=7538f2f5e68e RunHead=774b4bf88ba4 RunInput=3dc41505a4b7 RunJob=88af2a7f432b RunProgram=6fd636999d54 Step=607e5f1a91cc StepAsk=9a8c9c8918b1 StepAskBuild=de784b6c05da StepAskCheck=b77941df6dea StepAskCompose=4c6a08e10231 StepEnded=45ff4650b620 StepEndedEvent=207787118dac StepProgress=d25781cc895a StepProgressEvent=179344ce0ca2 StepResult=67f88be36d0e StepRun=6d551ed0ed46 StepsAnswer=2c02cac2df23 StepsByAskerNodeIDValue=50ccfd4cebd8 StepsByNodeIDValue=50ccfd4cebd8 TakenVersion=1b8d0547f61e TestCounts=9c1332427159 Toolchain=8ecb7debf9ad ToolchainReported=d26392767c50 ToolchainReportedEvent=fa0a431c9c7b ToolchainUsed=6cc7ccabc9f8 ToolchainsByNodeLanguageValue=f97d1dd27613" + generatedForms = "1 build-step:2" + generatedFieldsDigest = "AskArtifact=35eb85c27e97 AskTaken=8c917075eed4 AskTakenEvent=e4fc9b81e066 BuiltArtifact=b5fcef7a8b58 BuiltArtifactResolvedItem=3bcbbcfd1a1f Capacity=b40cca7ccdfa CheckAccept=ef89c6962ae4 CheckStepAccept=ef89c6962ae4 CurrentAnswer=e39824e012cb CurrentAsk=ac167e5ee11f DeliveryAccept=ef89c6962ae4 DeliveryStepAccept=ef89c6962ae4 DetectedStep=a6fcd7d0eca4 DetectedSteps=05198185c776 DetectedStepsByModuleArtifactValue=cb35b5775cc6 Drop=fb4637978e86 DropAnswer=7538f2f5e68e FailingTest=f3fb3f1a3ca8 Fetch=6e12677bbc2c FetchAnswer=46fc3d5bd7ee FetchBesideItem=774b4bf88ba4 FetchBuildsItem=aee5adc97246 FetchPackage=20d1668a0eee FetchRefusal=de1518848b4c InstallAccept=6c42a0d3fe6d InstallAsk=7a855a79d290 KeptArtifactAnswer=706729f8ccb9 KeptResult=8657683cdcd7 LevelAnswer=143c69c28a6a LevelAnswerDigest=d54b7fd7b1da LevelAnswerDigestNeedsItem=946b37d1d4a1 LevelAnswerDigestPackagesItem=a7d30558470d LevelAnswerKeptItem=85d3c2f78632 LevelAnswerUnmetItem=946b37d1d4a1 ModuleTree=00bb59e9f262 NotRun=d322fb1eb153 OutputAnswer=97ba4bd92bf9 Pause=d6521e0cdd1e PauseAnswer=7538f2f5e68e PausesByCapacityNodeValue=5392cf505c80 PausesByDroppedIDValue=0e15ac9cacbd PausesByPausedNodeValue=d111aad0f0cf PlacedBeside=53479337ff18 Program=b48ae74f34e0 RecheckAccept=ef89c6962ae4 ResumeAnswer=7538f2f5e68e RunHead=774b4bf88ba4 RunInput=3dc41505a4b7 RunJob=88af2a7f432b RunProgram=6fd636999d54 Step=607e5f1a91cc StepAsk=9a8c9c8918b1 StepAskBuild=de784b6c05da StepAskCheck=b77941df6dea StepAskCompose=4c6a08e10231 StepEnded=11c0b83bf3a5 StepEndedEvent=207787118dac StepProgress=d25781cc895a StepProgressEvent=179344ce0ca2 StepResult=67f88be36d0e StepRun=a7a81f25515f StepsAnswer=2c02cac2df23 StepsByAskerNodeIDValue=50ccfd4cebd8 StepsByNodeIDValue=50ccfd4cebd8 TakenVersion=1b8d0547f61e TestCounts=9c1332427159 Toolchain=8ecb7debf9ad ToolchainReported=d26392767c50 ToolchainReportedEvent=fa0a431c9c7b ToolchainUsed=6cc7ccabc9f8 ToolchainsByNodeLanguageValue=f97d1dd27613" ) const ( @@ -42,6 +42,7 @@ const ( AcceptCheckStep = "check.step" AcceptDeliveryStep = "delivery.step" AcceptRecheck = "recheck" + AcceptInstall = "install" ) const ( @@ -118,6 +119,9 @@ const AcceptSubjectDeliveryStep = "mesh.seat.node-build-node.accept.delivery" // AcceptSubjectRecheck is where recheck is sent. const AcceptSubjectRecheck = "mesh.seat.node-build-node.accept.recheck" +// AcceptSubjectInstall is where install is sent. +const AcceptSubjectInstall = "mesh.seat.node-build-node.accept.install" + const ( StateSteps = "steps" StatePauses = "pauses" @@ -427,6 +431,18 @@ type ComposeAnswer struct { Verdict any `json:"verdict,omitempty"` } +// CurrentAsk is an ask a holder runs now (design 47 H2 §801). +type CurrentAsk struct { + // who asked it + Asker string `json:"asker"` + // the ask's id + ID string `json:"id"` + // the ask's kind + Kind string `json:"kind"` + Module string `json:"module,omitempty"` + Started time.Time `json:"started"` +} + // DetectedStep is a type of the contract. type DetectedStep struct { // the packages the step runs, by the language's convention @@ -463,6 +479,14 @@ type Drop struct { Why string `json:"why"` } +// FailingTest is a failing test and its words (design 47 H2 §791). +type FailingTest struct { + // the test's name + Test string `json:"test"` + // what the test said + Words string `json:"words,omitempty"` +} + // FetchBesideItem is a type of the contract. type FetchBesideItem struct { Commit string `json:"commit"` @@ -539,6 +563,21 @@ type FetchRefusal struct { Reason string `json:"reason"` } +// InstallAsk is an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest. +type InstallAsk struct { + // who asked it + Asker string `json:"asker"` + // the commit the lock is read at + Commit string `json:"commit"` + // the ask's id + ID string `json:"id"` + // the package lock's text at the commit + Lock string `json:"lock"` + Module string `json:"module"` + // the runner's pipeline key + Pipeline string `json:"pipeline"` +} + // KeptResult is a package's passing result the runner keeps, by the digest of what its tests read (ADR 0666 section 8): the step runs no package whose digest and level it names. type KeptResult struct { // sha256: of what the package's tests read @@ -606,6 +645,14 @@ type ModuleTree struct { Tree string `json:"tree"` } +// NotRun is a test that did not run and why (design 47 H2 §800, H-A-367 (3)). +type NotRun struct { + // why it did not run + Reason string `json:"reason"` + // the test's name + Test string `json:"test"` +} + // Pause is whether the node takes no new ask. type Pause struct { // when (RFC 3339 time) @@ -774,6 +821,8 @@ type StepAsk struct { // StepEnded is an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G section 602): a pipeline step's end names the pipeline, the commit and the fingerprint it was asked at, which the runner takes only from that holder's account (ADR 0666 sections 7, 21); the end of any other ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (design 47 G section 548). type StepEnded struct { + // for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800) + Archive string `json:"archive,omitempty"` Artifact string `json:"artifact,omitempty"` // the ask's id, by which a reader takes only its own asks Ask string `json:"ask"` @@ -797,6 +846,8 @@ type StepEnded struct { Module string `json:"module,omitempty"` // the node that ran it, as in the subject Node string `json:"node"` + // the tests that did not run, each with its reason, counted apart from passed and failed (design 47 H2 §800) + NotRun []NotRun `json:"not-run,omitempty"` // never passed for a step that ran nothing Outcome string `json:"outcome"` // the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254) @@ -877,6 +928,8 @@ type StepResult struct { // StepRun is one pipeline step of one artifact at one commit (ADR 0666 sections 7, 8, 17): the step a build seat runs in its sandbox from the change's own heads, the names the lint step needs and the kept results it may skip. type StepRun struct { + // the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800) + Archive string `json:"archive,omitempty"` // the artifact reference, : Artifact string `json:"artifact"` // the watched branch, or the branch of a run on request @@ -971,7 +1024,29 @@ type CurrentInput struct { } // CurrentAnswer is what current answers. -type CurrentAnswer = map[string]any +type CurrentAnswer struct { + // every ask it runs, whoever asked it + Asks []CurrentAsk `json:"asks"` + // how many steps it runs at once + Capacity int64 `json:"capacity"` + // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). + Form int64 `json:"form,omitempty"` + // the node this holder runs on + Node string `json:"node"` + // since when it takes asks or not, as takes says + Since *time.Time `json:"since,omitempty"` + // whether it takes asks now + Takes bool `json:"takes"` + // why it takes none; absent while it takes asks + WhyNot string `json:"why-not,omitempty"` +} + +// The values of CurrentAnswer's why-not. +const ( + CurrentAnswerWhyNotPaused = "paused" + CurrentAnswerWhyNotCapacity0 = "capacity 0" + CurrentAnswerWhyNotUnhealthy = "unhealthy" +) // PauseInput is what pause takes. type PauseInput struct { @@ -1073,20 +1148,24 @@ type StepsAnswer struct { // OutputInput is what output takes. type OutputInput struct { - // the ask's id, the `output-object` of its step key or its step-ended naming it + // the ask's id Ask string `json:"ask"` - // 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements - Call string `json:"call"` } // OutputAnswer is what output answers. type OutputAnswer struct { // the ask's id Ask string `json:"ask"` - // how many chunks are sent; 0 when this node keeps no answer of that ask - Chunks int64 `json:"chunks"` + // the failing tests with their words + Failing []FailingTest `json:"failing,omitempty"` // is the form of what this value carries, left out while it is 1 (design 47 H2 §780). Form int64 `json:"form,omitempty"` + // the output is past the outputs objects' max-age, kept no longer + NoLongerKept bool `json:"no-longer-kept,omitempty"` + // the output's last 64 KB + Output string `json:"output,omitempty"` + // the whole output's size in bytes + Size int64 `json:"size,omitempty"` } // DeliveryAccept is the body of delivery. @@ -1104,6 +1183,9 @@ type DeliveryStepAccept = StepAsk // RecheckAccept is the body of recheck. type RecheckAccept = StepAsk +// InstallAccept is the body of install. +type InstallAccept = InstallAsk + // StepEndedEvent is the body of the event step-ended. type StepEndedEvent = StepEnded diff --git a/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract_test.go b/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract_test.go index 4bdfbd982..f298fcc47 100644 --- a/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/nodebuildnode/contract_test.go @@ -29,6 +29,8 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v StepEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-node\\.event\\.step-ended\\.[^.*> ]+$")}, {name: "an ask taken, whatever its asker (G 602)", subject: "mesh.seat.node-build-node.event.ask-taken.anchor", given: "{\"ask\":\"m2kx9a1b3c4d6a\",\"asker\":\"mesh-delivery-builder\",\"at\":\"2026-11-11T10:00:00Z\",\"node\":\"anchor\"}", wire: "{\"ask\":\"m2kx9a1b3c4d6a\",\"asker\":\"mesh-delivery-builder\",\"at\":\"2026-11-11T10:00:00Z\",\"node\":\"anchor\"}", decode: func(b []byte) (any, error) { var v AskTakenEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-node\\.event\\.ask-taken\\.[^.*> ]+$")}, + {name: "an integration step passed with two tests not run and why", subject: "mesh.seat.node-build-node.event.step-ended.anchor", given: "{\"artifact\":\"mesh-forge:bundle\",\"ask\":\"m2kx9a1b3c4d60\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-21T22:05:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0456\",\"id\":\"m2kx9a1b3c4d60\",\"module\":\"mesh-forge\",\"node\":\"anchor\",\"not-run\":[{\"reason\":\"the step gives no npm tree\",\"test\":\"TestTheForgeWhole\"},{\"reason\":\"the step gives no npm tree\",\"test\":\"TestTheForgeSeat\"}],\"outcome\":\"passed\",\"pipeline\":\"main.12.mesh-forge\",\"step\":\"integration\",\"tests\":{\"integration\":3},\"v\":1}", wire: "{\"artifact\":\"mesh-forge:bundle\",\"ask\":\"m2kx9a1b3c4d60\",\"asker\":\"mesh-delivery-pipeline\",\"at\":\"2026-11-21T22:05:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0456\",\"id\":\"m2kx9a1b3c4d60\",\"module\":\"mesh-forge\",\"node\":\"anchor\",\"not-run\":[{\"reason\":\"the step gives no npm tree\",\"test\":\"TestTheForgeWhole\"},{\"reason\":\"the step gives no npm tree\",\"test\":\"TestTheForgeSeat\"}],\"outcome\":\"passed\",\"pipeline\":\"main.12.mesh-forge\",\"step\":\"integration\",\"tests\":{\"integration\":3},\"v\":1}", + decode: func(b []byte) (any, error) { var v StepEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-node\\.event\\.step-ended\\.[^.*> ]+$")}, {name: "a running step", subject: "", given: "{\"id\":\"a1b2\",\"node\":\"anchor\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"running\",\"tool\":\"build\",\"v\":1}", wire: "{\"id\":\"a1b2\",\"node\":\"anchor\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"running\",\"tool\":\"build\",\"v\":1}", decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "a paused node", subject: "", given: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"operator@workstation\",\"paused\":true,\"v\":1}", wire: "{\"at\":\"2026-11-05T10:00:00Z\",\"by\":\"operator@workstation\",\"paused\":true,\"v\":1}", @@ -85,6 +87,8 @@ func TestFixtures(t *testing.T) { }, subjectIs: nil}, {name: "a check's step whose answer is kept as an object (G A-290)", subject: "", given: "{\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"output-object\":\"output.c3d4e5f6a7b8c9\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", wire: "{\"ended\":\"2026-11-05T10:05:00Z\",\"id\":\"c3d4e5f6a7b8c9\",\"node\":\"anchor\",\"output-object\":\"output.c3d4e5f6a7b8c9\",\"started\":\"2026-11-05T10:00:00Z\",\"state\":\"passed\",\"tool\":\"check\",\"v\":1}", decode: func(b []byte) (any, error) { var v StepsByNodeIDValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "an install ask names the module's package lock at the commit", subject: "mesh.seat.node-build-node.accept.install", given: "{\"asker\":\"mesh-delivery-pipeline\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"id\":\"i1a2b3\",\"lock\":\"{\\\"name\\\":\\\"mesh-forge\\\",\\\"lockfileVersion\\\":3,\\\"packages\\\":{}}\",\"module\":\"mesh-forge\",\"pipeline\":\"main.12.mesh-forge\"}", wire: "{\"asker\":\"mesh-delivery-pipeline\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"id\":\"i1a2b3\",\"lock\":\"{\\\"name\\\":\\\"mesh-forge\\\",\\\"lockfileVersion\\\":3,\\\"packages\\\":{}}\",\"module\":\"mesh-forge\",\"pipeline\":\"main.12.mesh-forge\"}", + decode: func(b []byte) (any, error) { var v InstallAccept; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.node-build-node\\.accept\\.install$")}, {name: "drop names the ask and why", subject: "", given: "{\"by\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"why\":\"a newer fingerprint supersedes it\"}", wire: "{\"by\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"why\":\"a newer fingerprint supersedes it\"}", decode: func(b []byte) (any, error) { var v DropInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "kept-artifact asks", subject: "", given: "{\"digest\":\"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"fp\":\"src2:1480985e\",\"module\":\"artifact-store\"}", wire: "{\"digest\":\"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"fp\":\"src2:1480985e\",\"module\":\"artifact-store\"}", @@ -109,10 +113,16 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v StepsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "steps answers a drop that the hand-act log refused", subject: "", given: "{\"error\":\"the hand-act log refused: nothing was deleted\"}", wire: "{\"error\":\"the hand-act log refused: nothing was deleted\"}", decode: func(b []byte) (any, error) { var v StepsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "output asks a run's answer by its ask", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"call\":\"0123456789abcdef0123456789abcdef\"}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"call\":\"0123456789abcdef0123456789abcdef\"}", + {name: "output asks a step's output by its ask", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\"}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\"}", decode: func(b []byte) (any, error) { var v OutputInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "output answers how many chunks carry the answer", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"chunks\":3}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"chunks\":3}", + {name: "output answers the last 64 KB, the size and the failing tests with their words", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5f\",\"failing\":[{\"test\":\"TestTheBusWhole\",\"words\":\"bus_test.go:41: no responders\"}],\"output\":\"--- FAIL: TestTheBusWhole (0.20s)\\n bus_test.go:41: no responders\\nFAIL\\n\",\"size\":181234}", wire: "{\"ask\":\"m2kx9a1b3c4d5f\",\"failing\":[{\"test\":\"TestTheBusWhole\",\"words\":\"bus_test.go:41: no responders\"}],\"output\":\"--- FAIL: TestTheBusWhole (0.20s)\\n bus_test.go:41: no responders\\nFAIL\\n\",\"size\":181234}", decode: func(b []byte) (any, error) { var v OutputAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "output answers an output past the objects' max-age as no longer kept", subject: "", given: "{\"ask\":\"m2kx9a1b3c4d5e\",\"no-longer-kept\":true}", wire: "{\"ask\":\"m2kx9a1b3c4d5e\",\"no-longer-kept\":true}", + decode: func(b []byte) (any, error) { var v OutputAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "current answers a holder that takes asks and the asks it runs, whoever asked", subject: "", given: "{\"asks\":[{\"asker\":\"mesh-delivery-pipeline\",\"id\":\"m2kx9a1b3c4d5f\",\"kind\":\"step\",\"module\":\"nats\",\"started\":\"2026-11-21T22:01:00Z\"},{\"asker\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"kind\":\"build\",\"module\":\"nats\",\"started\":\"2026-11-21T22:02:00Z\"}],\"capacity\":2,\"node\":\"anchor\",\"since\":\"2026-11-21T22:00:00Z\",\"takes\":true}", wire: "{\"asks\":[{\"asker\":\"mesh-delivery-pipeline\",\"id\":\"m2kx9a1b3c4d5f\",\"kind\":\"step\",\"module\":\"nats\",\"started\":\"2026-11-21T22:01:00Z\"},{\"asker\":\"mesh-delivery-builder\",\"id\":\"a1b2\",\"kind\":\"build\",\"module\":\"nats\",\"started\":\"2026-11-21T22:02:00Z\"}],\"capacity\":2,\"node\":\"anchor\",\"since\":\"2026-11-21T22:00:00Z\",\"takes\":true}", + decode: func(b []byte) (any, error) { var v CurrentAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "current answers a paused holder, since when", subject: "", given: "{\"asks\":[],\"capacity\":2,\"node\":\"home-server\",\"since\":\"2026-11-21T21:00:00Z\",\"takes\":false,\"why-not\":\"paused\"}", wire: "{\"asks\":[],\"capacity\":2,\"node\":\"home-server\",\"since\":\"2026-11-21T21:00:00Z\",\"takes\":false,\"why-not\":\"paused\"}", + decode: func(b []byte) (any, error) { var v CurrentAnswer; 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/parts/build-step.json b/modules/mesh-delivery-contracts/parts/build-step.json index 0390aecbe..5df445d0f 100644 --- a/modules/mesh-delivery-contracts/parts/build-step.json +++ b/modules/mesh-delivery-contracts/parts/build-step.json @@ -5,15 +5,57 @@ "verbs": [ { "name": "current", - "description": "The asks this node runs now (each ask's id, kind, module and when it started), its build capacity, and whether it is paused, taking no new ask.", + "description": "What this node's holder takes and runs (design 47 H2 §801, H-A-367 (2)): whether it takes asks and why not (paused, capacity 0, unhealthy) since when, its capacity, and every ask it runs, whoever asked it (the builder's delivery asks included).", "input": { "type": "object", "properties": {} }, "answer": { "type": "object", - "description": "the steps running, the capacity and whether paused" - } + "properties": { + "node": { + "type": "string", + "description": "the node this holder runs on" + }, + "takes": { + "type": "boolean", + "description": "whether it takes asks now" + }, + "why-not": { + "type": "string", + "enum": [ + "paused", + "capacity 0", + "unhealthy" + ], + "description": "why it takes none; absent while it takes asks" + }, + "since": { + "type": "string", + "format": "date-time", + "description": "since when it takes asks or not, as takes says" + }, + "capacity": { + "type": "integer", + "minimum": 0, + "description": "how many steps it runs at once" + }, + "asks": { + "type": "array", + "items": { + "$ref": "#/defs/CurrentAsk" + }, + "description": "every ask it runs, whoever asked it" + } + }, + "required": [ + "node", + "takes", + "capacity", + "asks" + ] + }, + "class": "read" }, { "name": "pause", @@ -71,7 +113,7 @@ }, { "name": "kept-artifact", - "description": "The one build this node keeps instead of storing it through the seat oci-artifact-registry: the new build of that seat's holder, when the running holder refused or did not answer the store (design 47 *The artifact store's holder takes its own new build even when its seat is the one broken*). Answers where the bytes are, as an object by their digest on the bus (the old objects form, ADR 0619 \u00a72), never in the answer; the node-engine checks what it fetched against the digest and applies nothing that differs. A module that claims no oci-artifact-registry is refused by name, so a store outage never becomes a delivery from build nodes; so is a build this node no longer keeps, or keeps under another digest.", + "description": "The one build this node keeps instead of storing it through the seat oci-artifact-registry: the new build of that seat's holder, when the running holder refused or did not answer the store (design 47 *The artifact store's holder takes its own new build even when its seat is the one broken*). Answers where the bytes are, as an object by their digest on the bus (the old objects form, ADR 0619 §2), never in the answer; the node-engine checks what it fetched against the digest and applies nothing that differs. A module that claims no oci-artifact-registry is refused by name, so a store outage never becomes a delivery from build nodes; so is a build this node no longer keeps, or keeps under another digest.", "input": { "type": "object", "properties": { @@ -223,24 +265,18 @@ { "name": "output", "class": "read", - "description": "A step's answer by its ask, when the step's key or a run's step-ended names it as `output-object` because the answer is over what the steps state's value or the event carries (design 47 G A-254, A-290): the answer's bytes in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds; the answer is of any size. An answer inline in the key or the event is never asked here.", + "description": "A step's output by its ask (design 47 H2 §791, H-A-367 (1)): the output's last 64 KB, its size, the failing tests with their words, or no longer kept once past the outputs objects' max-age. Asked by the runner's runner_step_output of the holder on the node the step key names.", "input": { "type": "object", "properties": { "ask": { "type": "string", - "description": "the ask's id, the `output-object` of its step key or its step-ended naming it", - "minLength": 1 - }, - "call": { - "type": "string", - "description": "128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements", + "description": "the ask's id", "minLength": 1 } }, "required": [ - "ask", - "call" + "ask" ] }, "answer": { @@ -250,18 +286,31 @@ "type": "string", "description": "the ask's id" }, - "chunks": { + "output": { + "type": "string", + "description": "the output's last 64 KB" + }, + "size": { "type": "integer", "minimum": 0, - "description": "how many chunks are sent; 0 when this node keeps no answer of that ask" + "description": "the whole output's size in bytes" + }, + "failing": { + "type": "array", + "items": { + "$ref": "#/defs/FailingTest" + }, + "description": "the failing tests with their words" + }, + "no-longer-kept": { + "type": "boolean", + "description": "the output is past the outputs objects' max-age, kept no longer" } }, "required": [ - "ask", - "chunks" + "ask" ] - }, - "chunks": true + } } ], "defs": { @@ -1552,6 +1601,10 @@ "by": { "type": "string", "description": "for a rerun, the caller the runtime proved" + }, + "archive": { + "type": "string", + "description": "the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800)" } }, "required": [ @@ -1669,6 +1722,17 @@ "type": "string", "description": "when it ended (RFC 3339 time)", "format": "date-time" + }, + "not-run": { + "type": "array", + "items": { + "$ref": "#/defs/NotRun" + }, + "description": "the tests that did not run, each with its reason, counted apart from passed and failed (design 47 H2 §800)" + }, + "archive": { + "type": "string", + "description": "for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800)" } }, "required": [ @@ -1816,6 +1880,109 @@ "node", "at" ] + }, + "CurrentAsk": { + "type": "object", + "description": "an ask a holder runs now (design 47 H2 §801)", + "properties": { + "id": { + "type": "string", + "description": "the ask's id" + }, + "kind": { + "type": "string", + "description": "the ask's kind" + }, + "module": { + "type": "string" + }, + "started": { + "type": "string", + "format": "date-time" + }, + "asker": { + "type": "string", + "description": "who asked it" + } + }, + "required": [ + "id", + "kind", + "started", + "asker" + ] + }, + "FailingTest": { + "type": "object", + "description": "a failing test and its words (design 47 H2 §791)", + "properties": { + "test": { + "type": "string", + "description": "the test's name" + }, + "words": { + "type": "string", + "description": "what the test said" + } + }, + "required": [ + "test" + ] + }, + "NotRun": { + "type": "object", + "description": "a test that did not run and why (design 47 H2 §800, H-A-367 (3))", + "properties": { + "test": { + "type": "string", + "description": "the test's name" + }, + "reason": { + "type": "string", + "description": "why it did not run" + } + }, + "required": [ + "test", + "reason" + ] + }, + "InstallAsk": { + "type": "object", + "description": "an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest", + "properties": { + "id": { + "type": "string", + "description": "the ask's id" + }, + "asker": { + "type": "string", + "description": "who asked it" + }, + "pipeline": { + "type": "string", + "description": "the runner's pipeline key" + }, + "module": { + "type": "string" + }, + "commit": { + "type": "string", + "description": "the commit the lock is read at" + }, + "lock": { + "type": "string", + "description": "the package lock's text at the commit" + } + }, + "required": [ + "id", + "asker", + "pipeline", + "module", + "commit", + "lock" + ] } }, "events": [ @@ -1855,5 +2022,6 @@ "$ref": "#/defs/AskTaken" } } - ] + ], + "form": 2 } diff --git a/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/verbs.json b/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/verbs.json index 070ce00d7..cd999db56 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/verbs.json +++ b/modules/mesh-delivery-contracts/seats/node-build-go/fixtures/verbs.json @@ -126,19 +126,71 @@ } }, { - "name": "output asks a run's answer by its ask", + "name": "output asks a step's output by its ask", "of": "verb:output.input", "given": { - "ask": "m2kx9a1b3c4d5f", - "call": "0123456789abcdef0123456789abcdef" + "ask": "m2kx9a1b3c4d5f" } }, { - "name": "output answers how many chunks carry the answer", + "name": "output answers the last 64 KB, the size and the failing tests with their words", "of": "verb:output.answer", "given": { "ask": "m2kx9a1b3c4d5f", - "chunks": 3 + "output": "--- FAIL: TestTheBusWhole (0.20s)\n bus_test.go:41: no responders\nFAIL\n", + "size": 181234, + "failing": [ + { + "test": "TestTheBusWhole", + "words": "bus_test.go:41: no responders" + } + ] + } + }, + { + "name": "output answers an output past the objects' max-age as no longer kept", + "of": "verb:output.answer", + "given": { + "ask": "m2kx9a1b3c4d5e", + "no-longer-kept": true + } + }, + { + "name": "current answers a holder that takes asks and the asks it runs, whoever asked", + "of": "verb:current.answer", + "given": { + "node": "anchor", + "takes": true, + "since": "2026-11-21T22:00:00Z", + "capacity": 2, + "asks": [ + { + "id": "m2kx9a1b3c4d5f", + "kind": "step", + "module": "nats", + "started": "2026-11-21T22:01:00Z", + "asker": "mesh-delivery-pipeline" + }, + { + "id": "a1b2", + "kind": "build", + "module": "nats", + "started": "2026-11-21T22:02:00Z", + "asker": "mesh-delivery-builder" + } + ] + } + }, + { + "name": "current answers a paused holder, since when", + "of": "verb:current.answer", + "given": { + "node": "home-server", + "takes": false, + "why-not": "paused", + "since": "2026-11-21T21:00:00Z", + "capacity": 2, + "asks": [] } } ] diff --git a/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/verbs.json b/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/verbs.json index 070ce00d7..cd999db56 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/verbs.json +++ b/modules/mesh-delivery-contracts/seats/node-build-image/fixtures/verbs.json @@ -126,19 +126,71 @@ } }, { - "name": "output asks a run's answer by its ask", + "name": "output asks a step's output by its ask", "of": "verb:output.input", "given": { - "ask": "m2kx9a1b3c4d5f", - "call": "0123456789abcdef0123456789abcdef" + "ask": "m2kx9a1b3c4d5f" } }, { - "name": "output answers how many chunks carry the answer", + "name": "output answers the last 64 KB, the size and the failing tests with their words", "of": "verb:output.answer", "given": { "ask": "m2kx9a1b3c4d5f", - "chunks": 3 + "output": "--- FAIL: TestTheBusWhole (0.20s)\n bus_test.go:41: no responders\nFAIL\n", + "size": 181234, + "failing": [ + { + "test": "TestTheBusWhole", + "words": "bus_test.go:41: no responders" + } + ] + } + }, + { + "name": "output answers an output past the objects' max-age as no longer kept", + "of": "verb:output.answer", + "given": { + "ask": "m2kx9a1b3c4d5e", + "no-longer-kept": true + } + }, + { + "name": "current answers a holder that takes asks and the asks it runs, whoever asked", + "of": "verb:current.answer", + "given": { + "node": "anchor", + "takes": true, + "since": "2026-11-21T22:00:00Z", + "capacity": 2, + "asks": [ + { + "id": "m2kx9a1b3c4d5f", + "kind": "step", + "module": "nats", + "started": "2026-11-21T22:01:00Z", + "asker": "mesh-delivery-pipeline" + }, + { + "id": "a1b2", + "kind": "build", + "module": "nats", + "started": "2026-11-21T22:02:00Z", + "asker": "mesh-delivery-builder" + } + ] + } + }, + { + "name": "current answers a paused holder, since when", + "of": "verb:current.answer", + "given": { + "node": "home-server", + "takes": false, + "why-not": "paused", + "since": "2026-11-21T21:00:00Z", + "capacity": 2, + "asks": [] } } ] diff --git a/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/events.json b/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/events.json index 69a0ec42f..ed6882a53 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/events.json +++ b/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/events.json @@ -108,5 +108,38 @@ "node": "anchor", "at": "2026-11-11T10:00:00Z" } + }, + { + "name": "an integration step passed with two tests not run and why", + "of": "event:step-ended", + "subject": "mesh.seat.node-build-node.event.step-ended.anchor", + "given": { + "v": 1, + "id": "m2kx9a1b3c4d60", + "asker": "mesh-delivery-pipeline", + "ask": "m2kx9a1b3c4d60", + "pipeline": "main.12.mesh-forge", + "step": "integration", + "module": "mesh-forge", + "node": "anchor", + "outcome": "passed", + "tests": { + "integration": 3 + }, + "not-run": [ + { + "test": "TestTheForgeWhole", + "reason": "the step gives no npm tree" + }, + { + "test": "TestTheForgeSeat", + "reason": "the step gives no npm tree" + } + ], + "at": "2026-11-21T22:05:00Z", + "commit": "0123456789abcdef0123456789abcdef01234567", + "fingerprint": "fp-0456", + "artifact": "mesh-forge:bundle" + } } ] diff --git a/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/states.json b/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/states.json index 39d89e252..92c707303 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/states.json +++ b/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/states.json @@ -314,5 +314,18 @@ "ended": "2026-11-05T10:05:00Z", "output-object": "output.c3d4e5f6a7b8c9" } + }, + { + "name": "an install ask names the module's package lock at the commit", + "of": "accept:install", + "subject": "mesh.seat.node-build-node.accept.install", + "given": { + "id": "i1a2b3", + "asker": "mesh-delivery-pipeline", + "pipeline": "main.12.mesh-forge", + "module": "mesh-forge", + "commit": "0123456789abcdef0123456789abcdef01234567", + "lock": "{\"name\":\"mesh-forge\",\"lockfileVersion\":3,\"packages\":{}}" + } } ] diff --git a/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/verbs.json b/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/verbs.json index 070ce00d7..cd999db56 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/verbs.json +++ b/modules/mesh-delivery-contracts/seats/node-build-node/fixtures/verbs.json @@ -126,19 +126,71 @@ } }, { - "name": "output asks a run's answer by its ask", + "name": "output asks a step's output by its ask", "of": "verb:output.input", "given": { - "ask": "m2kx9a1b3c4d5f", - "call": "0123456789abcdef0123456789abcdef" + "ask": "m2kx9a1b3c4d5f" } }, { - "name": "output answers how many chunks carry the answer", + "name": "output answers the last 64 KB, the size and the failing tests with their words", "of": "verb:output.answer", "given": { "ask": "m2kx9a1b3c4d5f", - "chunks": 3 + "output": "--- FAIL: TestTheBusWhole (0.20s)\n bus_test.go:41: no responders\nFAIL\n", + "size": 181234, + "failing": [ + { + "test": "TestTheBusWhole", + "words": "bus_test.go:41: no responders" + } + ] + } + }, + { + "name": "output answers an output past the objects' max-age as no longer kept", + "of": "verb:output.answer", + "given": { + "ask": "m2kx9a1b3c4d5e", + "no-longer-kept": true + } + }, + { + "name": "current answers a holder that takes asks and the asks it runs, whoever asked", + "of": "verb:current.answer", + "given": { + "node": "anchor", + "takes": true, + "since": "2026-11-21T22:00:00Z", + "capacity": 2, + "asks": [ + { + "id": "m2kx9a1b3c4d5f", + "kind": "step", + "module": "nats", + "started": "2026-11-21T22:01:00Z", + "asker": "mesh-delivery-pipeline" + }, + { + "id": "a1b2", + "kind": "build", + "module": "nats", + "started": "2026-11-21T22:02:00Z", + "asker": "mesh-delivery-builder" + } + ] + } + }, + { + "name": "current answers a paused holder, since when", + "of": "verb:current.answer", + "given": { + "node": "home-server", + "takes": false, + "why-not": "paused", + "since": "2026-11-21T21:00:00Z", + "capacity": 2, + "asks": [] } } ] diff --git a/modules/mesh-delivery-contracts/seats/node-build-node/seat.json b/modules/mesh-delivery-contracts/seats/node-build-node/seat.json index a04b62401..3b62223b0 100644 --- a/modules/mesh-delivery-contracts/seats/node-build-node/seat.json +++ b/modules/mesh-delivery-contracts/seats/node-build-node/seat.json @@ -45,6 +45,12 @@ "body": { "$ref": "#/defs/StepAsk" } + }, + { + "name": "install", + "body": { + "$ref": "#/defs/InstallAsk" + } } ], "description": "The Node build module on a node: it takes the asks of the builder and the checker, runs them as steps and answers.", diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/index.d.ts index 832ba06e4..7fc49e132 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/index.d.ts @@ -125,18 +125,21 @@ export type Capacity = buildStep.Capacity; export type CheckAnswer = buildStep.CheckAnswer; export type ComposeAnswer = buildStep.ComposeAnswer; export type CurrentAnswer = buildStep.CurrentAnswer; +export type CurrentAsk = buildStep.CurrentAsk; export type CurrentInput = buildStep.CurrentInput; export type DetectedStep = buildStep.DetectedStep; export type DetectedSteps = buildStep.DetectedSteps; export type Drop = buildStep.Drop; export type DropAnswer = buildStep.DropAnswer; export type DropInput = buildStep.DropInput; +export type FailingTest = buildStep.FailingTest; export type Fetch = buildStep.Fetch; export type FetchAnswer = buildStep.FetchAnswer; export type FetchBesideItem = buildStep.FetchBesideItem; export type FetchBuildsItem = buildStep.FetchBuildsItem; export type FetchPackage = buildStep.FetchPackage; export type FetchRefusal = buildStep.FetchRefusal; +export type InstallAsk = buildStep.InstallAsk; export type KeptArtifactAnswer = buildStep.KeptArtifactAnswer; export type KeptArtifactInput = buildStep.KeptArtifactInput; export type KeptResult = buildStep.KeptResult; @@ -147,6 +150,7 @@ export type LevelAnswerDigestPackagesItem = buildStep.LevelAnswerDigestPackagesI export type LevelAnswerKeptItem = buildStep.LevelAnswerKeptItem; export type LevelAnswerUnmetItem = buildStep.LevelAnswerUnmetItem; export type ModuleTree = buildStep.ModuleTree; +export type NotRun = buildStep.NotRun; export type OutputAnswer = buildStep.OutputAnswer; export type OutputInput = buildStep.OutputInput; export type Pause = buildStep.Pause; diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/parts/build-step.d.ts b/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/parts/build-step.d.ts index 928f3af67..5202a4113 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/parts/build-step.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildgo/parts/build-step.d.ts @@ -96,6 +96,18 @@ export interface ComposeAnswer { "verdict"?: unknown; } +/** an ask a holder runs now (design 47 H2 §801) */ +export interface CurrentAsk { + /** who asked it */ + "asker": string; + /** the ask's id */ + "id": string; + /** the ask's kind */ + "kind": string; + "module"?: string; + "started": string; +} + export interface DetectedStep { /** the packages the step runs, by the language's convention */ "packages"?: string[]; @@ -120,6 +132,14 @@ export interface Drop { "why": string; } +/** a failing test and its words (design 47 H2 §791) */ +export interface FailingTest { + /** the test's name */ + "test": string; + /** what the test said */ + "words"?: string; +} + export interface FetchBesideItem { "commit": string; "repository": string; @@ -194,6 +214,21 @@ export interface FetchRefusal { "reason": string; } +/** an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest */ +export interface InstallAsk { + /** who asked it */ + "asker": string; + /** the commit the lock is read at */ + "commit": string; + /** the ask's id */ + "id": string; + /** the package lock's text at the commit */ + "lock": string; + "module": string; + /** the runner's pipeline key */ + "pipeline": string; +} + /** a package's passing result the runner keeps, by the digest of what its tests read (ADR 0666 section 8): the step runs no package whose digest and level it names */ export interface KeptResult { /** sha256: of what the package's tests read */ @@ -256,6 +291,14 @@ export interface ModuleTree { "tree": string; } +/** a test that did not run and why (design 47 H2 §800, H-A-367 (3)) */ +export interface NotRun { + /** why it did not run */ + "reason": string; + /** the test's name */ + "test": string; +} + /** whether the node takes no new ask */ export interface Pause { /** when (RFC 3339 time) */ @@ -417,6 +460,8 @@ export interface StepAsk { /** an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G section 602): a pipeline step's end names the pipeline, the commit and the fingerprint it was asked at, which the runner takes only from that holder's account (ADR 0666 sections 7, 21); the end of any other ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (design 47 G section 548) */ export interface StepEnded { + /** for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800) */ + "archive"?: string; "artifact"?: string; /** the ask's id, by which a reader takes only its own asks */ "ask": string; @@ -440,6 +485,8 @@ export interface StepEnded { "module"?: string; /** the node that ran it, as in the subject */ "node": string; + /** the tests that did not run, each with its reason, counted apart from passed and failed (design 47 H2 §800) */ + "not-run"?: NotRun[]; /** never passed for a step that ran nothing */ "outcome": "passed" | "failed" | "nothing to run" | "could not run"; /** the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254) */ @@ -497,6 +544,8 @@ export interface StepResult { /** one pipeline step of one artifact at one commit (ADR 0666 sections 7, 8, 17): the step a build seat runs in its sandbox from the change's own heads, the names the lint step needs and the kept results it may skip */ export interface StepRun { + /** the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800) */ + "archive"?: string; /** the artifact reference, : */ "artifact": string; /** the watched branch, or the branch of a run on request */ @@ -582,7 +631,22 @@ export interface CurrentInput { } /** is what current answers. */ -export type CurrentAnswer = Record; +export interface CurrentAnswer { + /** every ask it runs, whoever asked it */ + "asks": CurrentAsk[]; + /** how many steps it runs at once */ + "capacity": number; + /** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */ + "form"?: number; + /** the node this holder runs on */ + "node": string; + /** since when it takes asks or not, as takes says */ + "since"?: string; + /** whether it takes asks now */ + "takes": boolean; + /** why it takes none; absent while it takes asks */ + "why-not"?: "paused" | "capacity 0" | "unhealthy"; +} /** is what pause takes. */ export interface PauseInput { @@ -677,20 +741,24 @@ export interface StepsAnswer { /** is what output takes. */ export interface OutputInput { - /** the ask's id, the `output-object` of its step key or its step-ended naming it */ + /** the ask's id */ "ask": string; - /** 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements */ - "call": string; } /** is what output answers. */ export interface OutputAnswer { /** the ask's id */ "ask": string; - /** how many chunks are sent; 0 when this node keeps no answer of that ask */ - "chunks": number; + /** the failing tests with their words */ + "failing"?: FailingTest[]; /** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */ "form"?: number; + /** the output is past the outputs objects' max-age, kept no longer */ + "no-longer-kept"?: boolean; + /** the output's last 64 KB */ + "output"?: string; + /** the whole output's size in bytes */ + "size"?: number; } /** is the body of the event step-ended. */ diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/index.d.ts index d666dae81..dd2aece20 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/index.d.ts @@ -122,18 +122,21 @@ export type Capacity = buildStep.Capacity; export type CheckAnswer = buildStep.CheckAnswer; export type ComposeAnswer = buildStep.ComposeAnswer; export type CurrentAnswer = buildStep.CurrentAnswer; +export type CurrentAsk = buildStep.CurrentAsk; export type CurrentInput = buildStep.CurrentInput; export type DetectedStep = buildStep.DetectedStep; export type DetectedSteps = buildStep.DetectedSteps; export type Drop = buildStep.Drop; export type DropAnswer = buildStep.DropAnswer; export type DropInput = buildStep.DropInput; +export type FailingTest = buildStep.FailingTest; export type Fetch = buildStep.Fetch; export type FetchAnswer = buildStep.FetchAnswer; export type FetchBesideItem = buildStep.FetchBesideItem; export type FetchBuildsItem = buildStep.FetchBuildsItem; export type FetchPackage = buildStep.FetchPackage; export type FetchRefusal = buildStep.FetchRefusal; +export type InstallAsk = buildStep.InstallAsk; export type KeptArtifactAnswer = buildStep.KeptArtifactAnswer; export type KeptArtifactInput = buildStep.KeptArtifactInput; export type KeptResult = buildStep.KeptResult; @@ -144,6 +147,7 @@ export type LevelAnswerDigestPackagesItem = buildStep.LevelAnswerDigestPackagesI export type LevelAnswerKeptItem = buildStep.LevelAnswerKeptItem; export type LevelAnswerUnmetItem = buildStep.LevelAnswerUnmetItem; export type ModuleTree = buildStep.ModuleTree; +export type NotRun = buildStep.NotRun; export type OutputAnswer = buildStep.OutputAnswer; export type OutputInput = buildStep.OutputInput; export type Pause = buildStep.Pause; diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/parts/build-step.d.ts b/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/parts/build-step.d.ts index 928f3af67..5202a4113 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/parts/build-step.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildimage/parts/build-step.d.ts @@ -96,6 +96,18 @@ export interface ComposeAnswer { "verdict"?: unknown; } +/** an ask a holder runs now (design 47 H2 §801) */ +export interface CurrentAsk { + /** who asked it */ + "asker": string; + /** the ask's id */ + "id": string; + /** the ask's kind */ + "kind": string; + "module"?: string; + "started": string; +} + export interface DetectedStep { /** the packages the step runs, by the language's convention */ "packages"?: string[]; @@ -120,6 +132,14 @@ export interface Drop { "why": string; } +/** a failing test and its words (design 47 H2 §791) */ +export interface FailingTest { + /** the test's name */ + "test": string; + /** what the test said */ + "words"?: string; +} + export interface FetchBesideItem { "commit": string; "repository": string; @@ -194,6 +214,21 @@ export interface FetchRefusal { "reason": string; } +/** an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest */ +export interface InstallAsk { + /** who asked it */ + "asker": string; + /** the commit the lock is read at */ + "commit": string; + /** the ask's id */ + "id": string; + /** the package lock's text at the commit */ + "lock": string; + "module": string; + /** the runner's pipeline key */ + "pipeline": string; +} + /** a package's passing result the runner keeps, by the digest of what its tests read (ADR 0666 section 8): the step runs no package whose digest and level it names */ export interface KeptResult { /** sha256: of what the package's tests read */ @@ -256,6 +291,14 @@ export interface ModuleTree { "tree": string; } +/** a test that did not run and why (design 47 H2 §800, H-A-367 (3)) */ +export interface NotRun { + /** why it did not run */ + "reason": string; + /** the test's name */ + "test": string; +} + /** whether the node takes no new ask */ export interface Pause { /** when (RFC 3339 time) */ @@ -417,6 +460,8 @@ export interface StepAsk { /** an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G section 602): a pipeline step's end names the pipeline, the commit and the fingerprint it was asked at, which the runner takes only from that holder's account (ADR 0666 sections 7, 21); the end of any other ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (design 47 G section 548) */ export interface StepEnded { + /** for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800) */ + "archive"?: string; "artifact"?: string; /** the ask's id, by which a reader takes only its own asks */ "ask": string; @@ -440,6 +485,8 @@ export interface StepEnded { "module"?: string; /** the node that ran it, as in the subject */ "node": string; + /** the tests that did not run, each with its reason, counted apart from passed and failed (design 47 H2 §800) */ + "not-run"?: NotRun[]; /** never passed for a step that ran nothing */ "outcome": "passed" | "failed" | "nothing to run" | "could not run"; /** the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254) */ @@ -497,6 +544,8 @@ export interface StepResult { /** one pipeline step of one artifact at one commit (ADR 0666 sections 7, 8, 17): the step a build seat runs in its sandbox from the change's own heads, the names the lint step needs and the kept results it may skip */ export interface StepRun { + /** the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800) */ + "archive"?: string; /** the artifact reference, : */ "artifact": string; /** the watched branch, or the branch of a run on request */ @@ -582,7 +631,22 @@ export interface CurrentInput { } /** is what current answers. */ -export type CurrentAnswer = Record; +export interface CurrentAnswer { + /** every ask it runs, whoever asked it */ + "asks": CurrentAsk[]; + /** how many steps it runs at once */ + "capacity": number; + /** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */ + "form"?: number; + /** the node this holder runs on */ + "node": string; + /** since when it takes asks or not, as takes says */ + "since"?: string; + /** whether it takes asks now */ + "takes": boolean; + /** why it takes none; absent while it takes asks */ + "why-not"?: "paused" | "capacity 0" | "unhealthy"; +} /** is what pause takes. */ export interface PauseInput { @@ -677,20 +741,24 @@ export interface StepsAnswer { /** is what output takes. */ export interface OutputInput { - /** the ask's id, the `output-object` of its step key or its step-ended naming it */ + /** the ask's id */ "ask": string; - /** 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements */ - "call": string; } /** is what output answers. */ export interface OutputAnswer { /** the ask's id */ "ask": string; - /** how many chunks are sent; 0 when this node keeps no answer of that ask */ - "chunks": number; + /** the failing tests with their words */ + "failing"?: FailingTest[]; /** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */ "form"?: number; + /** the output is past the outputs objects' max-age, kept no longer */ + "no-longer-kept"?: boolean; + /** the output's last 64 KB */ + "output"?: string; + /** the whole output's size in bytes */ + "size"?: number; } /** is the body of the event step-ended. */ diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.d.ts index ba191dda1..e66be3015 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.d.ts @@ -22,6 +22,7 @@ export declare const accepts: { readonly checkStep: "check.step"; readonly deliveryStep: "delivery.step"; readonly recheck: "recheck"; + readonly install: "install"; }; export declare const events: { @@ -63,6 +64,8 @@ export declare const deliveryStepSubject: "mesh.seat.node-build-node.accept.deli export declare const recheckSubject: "mesh.seat.node-build-node.accept.recheck"; +export declare const installSubject: "mesh.seat.node-build-node.accept.install"; + export declare const states: { readonly steps: "steps"; readonly pauses: "pauses"; @@ -122,18 +125,21 @@ export type Capacity = buildStep.Capacity; export type CheckAnswer = buildStep.CheckAnswer; export type ComposeAnswer = buildStep.ComposeAnswer; export type CurrentAnswer = buildStep.CurrentAnswer; +export type CurrentAsk = buildStep.CurrentAsk; export type CurrentInput = buildStep.CurrentInput; export type DetectedStep = buildStep.DetectedStep; export type DetectedSteps = buildStep.DetectedSteps; export type Drop = buildStep.Drop; export type DropAnswer = buildStep.DropAnswer; export type DropInput = buildStep.DropInput; +export type FailingTest = buildStep.FailingTest; export type Fetch = buildStep.Fetch; export type FetchAnswer = buildStep.FetchAnswer; export type FetchBesideItem = buildStep.FetchBesideItem; export type FetchBuildsItem = buildStep.FetchBuildsItem; export type FetchPackage = buildStep.FetchPackage; export type FetchRefusal = buildStep.FetchRefusal; +export type InstallAsk = buildStep.InstallAsk; export type KeptArtifactAnswer = buildStep.KeptArtifactAnswer; export type KeptArtifactInput = buildStep.KeptArtifactInput; export type KeptResult = buildStep.KeptResult; @@ -144,6 +150,7 @@ export type LevelAnswerDigestPackagesItem = buildStep.LevelAnswerDigestPackagesI export type LevelAnswerKeptItem = buildStep.LevelAnswerKeptItem; export type LevelAnswerUnmetItem = buildStep.LevelAnswerUnmetItem; export type ModuleTree = buildStep.ModuleTree; +export type NotRun = buildStep.NotRun; export type OutputAnswer = buildStep.OutputAnswer; export type OutputInput = buildStep.OutputInput; export type Pause = buildStep.Pause; @@ -193,6 +200,9 @@ export type DeliveryStepAccept = StepAsk; /** is the body of recheck. */ export type RecheckAccept = StepAsk; +/** is the body of install. */ +export type InstallAccept = InstallAsk; + /** is one value of the state steps under the key ... */ export type StepsByAskerNodeIDValue = Step; diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.js b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.js index 5e472b0f3..52c7ee72d 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.js +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/index.js @@ -20,6 +20,7 @@ export const accepts = { checkStep: "check.step", deliveryStep: "delivery.step", recheck: "recheck", + install: "install", }; export const events = { @@ -69,6 +70,8 @@ export const deliveryStepSubject = "mesh.seat.node-build-node.accept.delivery"; export const recheckSubject = "mesh.seat.node-build-node.accept.recheck"; +export const installSubject = "mesh.seat.node-build-node.accept.install"; + export const states = { steps: "steps", pauses: "pauses", diff --git a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/parts/build-step.d.ts b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/parts/build-step.d.ts index 928f3af67..5202a4113 100644 --- a/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/parts/build-step.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/nodebuildnode/parts/build-step.d.ts @@ -96,6 +96,18 @@ export interface ComposeAnswer { "verdict"?: unknown; } +/** an ask a holder runs now (design 47 H2 §801) */ +export interface CurrentAsk { + /** who asked it */ + "asker": string; + /** the ask's id */ + "id": string; + /** the ask's kind */ + "kind": string; + "module"?: string; + "started": string; +} + export interface DetectedStep { /** the packages the step runs, by the language's convention */ "packages"?: string[]; @@ -120,6 +132,14 @@ export interface Drop { "why": string; } +/** a failing test and its words (design 47 H2 §791) */ +export interface FailingTest { + /** the test's name */ + "test": string; + /** what the test said */ + "words"?: string; +} + export interface FetchBesideItem { "commit": string; "repository": string; @@ -194,6 +214,21 @@ export interface FetchRefusal { "reason": string; } +/** an ask of the kind install (design 47 H2 §800, H-A-367 (4)): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, kept as an archive in the holder's outputs under the lock's digest */ +export interface InstallAsk { + /** who asked it */ + "asker": string; + /** the commit the lock is read at */ + "commit": string; + /** the ask's id */ + "id": string; + /** the package lock's text at the commit */ + "lock": string; + "module": string; + /** the runner's pipeline key */ + "pipeline": string; +} + /** a package's passing result the runner keeps, by the digest of what its tests read (ADR 0666 section 8): the step runs no package whose digest and level it names */ export interface KeptResult { /** sha256: of what the package's tests read */ @@ -256,6 +291,14 @@ export interface ModuleTree { "tree": string; } +/** a test that did not run and why (design 47 H2 §800, H-A-367 (3)) */ +export interface NotRun { + /** why it did not run */ + "reason": string; + /** the test's name */ + "test": string; +} + /** whether the node takes no new ask */ export interface Pause { /** when (RFC 3339 time) */ @@ -417,6 +460,8 @@ export interface StepAsk { /** an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G section 602): a pipeline step's end names the pipeline, the commit and the fingerprint it was asked at, which the runner takes only from that holder's account (ADR 0666 sections 7, 21); the end of any other ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (design 47 G section 548) */ export interface StepEnded { + /** for an install, the name of the archive object in the holder's outputs that holds the installed tree (design 47 H2 §800) */ + "archive"?: string; "artifact"?: string; /** the ask's id, by which a reader takes only its own asks */ "ask": string; @@ -440,6 +485,8 @@ export interface StepEnded { "module"?: string; /** the node that ran it, as in the subject */ "node": string; + /** the tests that did not run, each with its reason, counted apart from passed and failed (design 47 H2 §800) */ + "not-run"?: NotRun[]; /** never passed for a step that ran nothing */ "outcome": "passed" | "failed" | "nothing to run" | "could not run"; /** the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254) */ @@ -497,6 +544,8 @@ export interface StepResult { /** one pipeline step of one artifact at one commit (ADR 0666 sections 7, 8, 17): the step a build seat runs in its sandbox from the change's own heads, the names the lint step needs and the kept results it may skip */ export interface StepRun { + /** the install archive object the Go build module unpacks into the workspace before the step (design 47 H2 §800) */ + "archive"?: string; /** the artifact reference, : */ "artifact": string; /** the watched branch, or the branch of a run on request */ @@ -582,7 +631,22 @@ export interface CurrentInput { } /** is what current answers. */ -export type CurrentAnswer = Record; +export interface CurrentAnswer { + /** every ask it runs, whoever asked it */ + "asks": CurrentAsk[]; + /** how many steps it runs at once */ + "capacity": number; + /** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */ + "form"?: number; + /** the node this holder runs on */ + "node": string; + /** since when it takes asks or not, as takes says */ + "since"?: string; + /** whether it takes asks now */ + "takes": boolean; + /** why it takes none; absent while it takes asks */ + "why-not"?: "paused" | "capacity 0" | "unhealthy"; +} /** is what pause takes. */ export interface PauseInput { @@ -677,20 +741,24 @@ export interface StepsAnswer { /** is what output takes. */ export interface OutputInput { - /** the ask's id, the `output-object` of its step key or its step-ended naming it */ + /** the ask's id */ "ask": string; - /** 128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements */ - "call": string; } /** is what output answers. */ export interface OutputAnswer { /** the ask's id */ "ask": string; - /** how many chunks are sent; 0 when this node keeps no answer of that ask */ - "chunks": number; + /** the failing tests with their words */ + "failing"?: FailingTest[]; /** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */ "form"?: number; + /** the output is past the outputs objects' max-age, kept no longer */ + "no-longer-kept"?: boolean; + /** the output's last 64 KB */ + "output"?: string; + /** the whole output's size in bytes */ + "size"?: number; } /** is the body of the event step-ended. */ diff --git a/modules/mesh-delivery-sdk/buildstep/ask_test.go b/modules/mesh-delivery-sdk/buildstep/ask_test.go index e996d4c27..252729925 100644 --- a/modules/mesh-delivery-sdk/buildstep/ask_test.go +++ b/modules/mesh-delivery-sdk/buildstep/ask_test.go @@ -556,6 +556,9 @@ func TestTheThreeSeatsFixturesFitTheNeutralForms(t *testing.T) { for _, f := range fixtures { t.Run(seat+"/"+f.Name, func(t *testing.T) { switch { + case f.Of == "accept:install": + seen++ + strict(t, f.Given, &InstallAsk{}) case strings.HasPrefix(f.Of, "accept:"): seen++ strict(t, f.Given, &StepAsk{}) diff --git a/modules/mesh-delivery-sdk/buildstep/pipelinestep.go b/modules/mesh-delivery-sdk/buildstep/pipelinestep.go index cee86f4ab..72ae60e9d 100644 --- a/modules/mesh-delivery-sdk/buildstep/pipelinestep.go +++ b/modules/mesh-delivery-sdk/buildstep/pipelinestep.go @@ -77,6 +77,9 @@ type StepRun struct { Kept []KeptResult `json:"kept,omitempty"` Rerun bool `json:"rerun,omitempty"` By string `json:"by,omitempty"` + // Archive is the install archive object the Go build module unpacks into the workspace before the step (design 47 + // H2 §800). + Archive string `json:"archive,omitempty"` } // Skips says whether the step runs no tests of pkg at digest, its kept result holding them. @@ -136,11 +139,35 @@ type StepEnded struct { Said string `json:"said,omitempty"` Output string `json:"output,omitempty"` OutputObject string `json:"output-object,omitempty"` - Rerun bool `json:"rerun,omitempty"` - By string `json:"by,omitempty"` - Started time.Time `json:"started,omitzero"` - Ended time.Time `json:"ended,omitzero"` - At time.Time `json:"at,omitzero"` + // NotRun are the tests that did not run, each with its reason, counted apart from passed and failed (design 47 H2 + // §800). + NotRun []NotRun `json:"not-run,omitempty"` + // Archive is, for an install, the name of the archive object in the holder's outputs that holds the installed tree + // (design 47 H2 §800). + Archive string `json:"archive,omitempty"` + Rerun bool `json:"rerun,omitempty"` + By string `json:"by,omitempty"` + Started time.Time `json:"started,omitzero"` + Ended time.Time `json:"ended,omitzero"` + At time.Time `json:"at,omitzero"` +} + +// NotRun is a test that did not run and why (design 47 H2 §800). +type NotRun struct { + Test string `json:"test"` + Reason string `json:"reason"` +} + +// InstallAsk is an ask of the kind install the seat node-build-node accepts (design 47 H2 §800): the npm tree a +// module's package lock names, kept as an archive in the holder's outputs under the lock's digest. +type InstallAsk struct { + ID string `json:"id"` + Asker string `json:"asker"` + Pipeline string `json:"pipeline"` + Module string `json:"module"` + Commit string `json:"commit"` + // Lock is the package lock's text at the commit. + Lock string `json:"lock"` } // EndOf is the end of the step a holds, on node, with outcome: the ask's names copied, so the runner can match the ask,