From 4599d2e60ff8ff7bdf1ceeb7975fd144de970f38 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 20 Nov 2026 03:05:15 +0100 Subject: [PATCH] C-W: the seat mesh-wants: a want by version, pipeline and rank; pipeline-wanted; validate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A module want names its fingerprint and released version with the pipeline (.) and rank (its tier, from 1) it was written from, neither for a placement's build; parts, rule, newest, kept-on and composed go, and the client checks a rank with its pipeline instead of a composition and a rule. The node's own want is unchanged. The accepted step and its end take validate beside composition. wanted gains pipeline; pipeline-wanted.. says a pipeline's wants once at their end, running or tier-late with the movers and machines not running. version-delivered goes. Builds: design 47 H §745, §750, §751, §764 (the assigner: version-delivered, the digests in a want); lead answers H-A-37, H-A-51, H-A-56, H-A-72 (6), H-A-75 Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy --- .../go/clients/meshwantsclient/wants.go | 54 ++---- .../go/clients/meshwantsclient/wants_test.go | 42 ++-- .../go/seats/meshwants/contract.go | 104 ++++++---- .../go/seats/meshwants/contract_test.go | 16 +- .../seats/mesh-wants/fixtures/events.json | 54 ++++-- .../seats/mesh-wants/fixtures/states.json | 18 +- .../seats/mesh-wants/fixtures/verbs.json | 17 +- .../seats/mesh-wants/seat.json | 183 ++++++++++-------- .../ts/seats/meshwants/index.d.ts | 75 +++---- .../ts/seats/meshwants/index.js | 14 +- 10 files changed, 315 insertions(+), 262 deletions(-) diff --git a/modules/mesh-delivery-contracts/go/clients/meshwantsclient/wants.go b/modules/mesh-delivery-contracts/go/clients/meshwantsclient/wants.go index ea5a8dff..700a2eb3 100644 --- a/modules/mesh-delivery-contracts/go/clients/meshwantsclient/wants.go +++ b/modules/mesh-delivery-contracts/go/clients/meshwantsclient/wants.go @@ -17,8 +17,8 @@ import ( // The three values of the state wants, in the seat's types. type ( - // Want is a node's want for a module: the fingerprint it should run and the digest of the one composition it allows, - // or Removed, or Self when the node composes it itself; Newest and Rule name what holds the node back. + // Want is a node's want for a module: the build it should run by its fingerprint and released version, with the + // pipeline and the rank it was written from (design 47 H §750), or Removed. Want = seat.WantsByWantNodeModuleValue // NodeWant is a node's own want: the digest of the node's own composition it may apply. NodeWant = seat.WantsByWantNodeNodeValue @@ -26,7 +26,8 @@ type ( Held = seat.WantsByHeldModuleFingerprintValue ) -// The rules of ADR 0429 §6 and ADR 0539 clause 6, by number, as a want or a difference names the one that holds a node back. +// The rules of ADR 0429 §6 and ADR 0539 clause 6, by number, as a difference names the one that held a node back; a want +// names none (design 47 H §750). const ( RuleBuildDone = 1 // the build of F is done RuleNotHeld = 2 // F is not held @@ -39,10 +40,6 @@ const ( RuleProvisions = 8 ) -// ruleRead is the highest rule a reader takes (novox/hq ADR 0614 §2, §4): 9 and 10 are kept for the verb wait and the -// capability hold of a later release. -const ruleRead = 10 - // The answers a want carries to a failed backup before an apply (ADR 0539 clause 16). const ( // BackupAgain is the answer to back the module up again before the apply. @@ -107,13 +104,6 @@ func checkDigest(digest, of string) error { return nil } -func checkRule(rule int64, of string) error { - if rule < RuleBuildDone || rule > ruleRead { - return fmt.Errorf("wants: %s names the rule %d, which is not one of 1 to %d", of, rule, ruleRead) - } - return nil -} - // WantKey is the key, in the state wants, of a node's want for a module: `want..`. A module named `node` is // refused, since `want..node` is the node's own key. func WantKey(node, module string) (string, error) { @@ -183,31 +173,24 @@ func ParseHeldKey(key string) (module, fingerprint string, err error) { func checkWant(w Want) error { if w.Removed { - if w.Fp != "" || w.Composed != "" || w.Newest != "" || w.Rule != 0 || w.Backup != "" || w.Put || w.Hold || w.Self || w.Yes != "" || w.Release != "" { - return fmt.Errorf("wants: a removed want names no fingerprint, composition, rule, backup answer or put") + if w.Fp != "" || w.Backup != "" || w.Put || w.Hold || w.Self || w.Yes != "" || w.Release != "" || w.Pipeline != "" || w.Rank != 0 { + return fmt.Errorf("wants: a removed want names no fingerprint, pipeline, backup answer or put") } return nil } if w.Hold && !w.Put { return fmt.Errorf("wants: only a put holds a want") } - if w.Put && (w.Newest != "" || w.Rule != 0) { - return fmt.Errorf("wants: a put's want is held back by no rule") - } if err := checkFingerprint(w.Fp, "a want's fingerprint"); err != nil { return err } - // A node the catalogue places composes its own modules (ADR 0547 §2): its want is Self and names the build alone. Any - // other want names the one composition it allows (ADR 0539 clause 1). + // The rank is the mover's tier in the pipeline the want was written from, from 1; a placement's build names neither + // (design 47 H §750, H-A-37). switch { - case w.Self && w.Composed != "": - return fmt.Errorf("wants: the want of %s says the node composes it, and names a composition", w.Fp) - case !w.Self && w.Composed == "": - return fmt.Errorf("wants: the want of %s names no composition: a want names the digest of the one composition it allows (ADR 0539 clause 1), unless the node composes it itself", w.Fp) - case w.Composed != "": - if err := checkDigest(w.Composed, "a want's composition digest"); err != nil { - return err - } + case w.Rank < 0 || w.Rank > 0 && w.Pipeline == "": + return fmt.Errorf("wants: the want of %s names the rank %d and no pipeline it is a tier of", w.Fp, w.Rank) + case w.Pipeline != "" && w.Rank == 0: + return fmt.Errorf("wants: the want of %s names the pipeline %s and no rank in it", w.Fp, w.Pipeline) } if w.Yes != "" { if err := checkDigest(w.Yes, "the digest a want's yes allows"); err != nil { @@ -224,23 +207,14 @@ func checkWant(w Want) error { if w.Revert != "" && w.Revert != RevertLive { return fmt.Errorf("wants: the revert answer %q is not %s", w.Revert, RevertLive) } - if w.Newest == "" && w.Rule == 0 { - return nil - } - if err := checkFingerprint(w.Newest, "a want's newest fingerprint"); err != nil { - return err - } - if w.Newest == w.Fp { - return fmt.Errorf("wants: a want at its newest fingerprint names no rule holding it back") - } - return checkRule(w.Rule, "a want held back") + return nil } // CheckWant refuses a want the codec refuses. func CheckWant(w Want) error { return checkWant(w) } // EncodeWant is w as JSON at the kept values' version; it refuses a fingerprint not of the new form, a removed want naming -// one, and a want that names no composition unless the node composes it itself. +// one, and a rank without its pipeline or a pipeline without its rank. func EncodeWant(w Want) ([]byte, error) { if err := checkWant(w); err != nil { return nil, err diff --git a/modules/mesh-delivery-contracts/go/clients/meshwantsclient/wants_test.go b/modules/mesh-delivery-contracts/go/clients/meshwantsclient/wants_test.go index c12a9c14..76038e62 100644 --- a/modules/mesh-delivery-contracts/go/clients/meshwantsclient/wants_test.go +++ b/modules/mesh-delivery-contracts/go/clients/meshwantsclient/wants_test.go @@ -37,13 +37,12 @@ func TestWantsAreWhatTheEarlierCodecWrote(t *testing.T) { w Want golden string }{ - "composed": {Want{Fp: a, Composed: c, Words: "w"}, `{"v":1,"fp":"` + a + `","composed":"` + c + `","words":"w"}`}, - "held back": {Want{Fp: a, Self: true, Newest: b, Rule: RuleGrant, Backup: BackupAgain, Words: "held"}, `{"v":1,"fp":"` + a + `","newest":"` + b + `","rule":6,"backup":"again","words":"held","self":true}`}, - "put": {Want{Fp: a, Self: true, Put: true, Hold: true, Yes: d, Release: "r1"}, `{"v":1,"fp":"` + a + `","put":true,"hold":true,"yes":"` + d + `","release":"r1","self":true}`}, - "revert": {Want{Fp: a, Self: true, Revert: RevertLive, Words: "live"}, `{"v":1,"fp":"` + a + `","revert":"live","words":"live","self":true}`}, - "removed": {Want{Removed: true, Words: "gone"}, `{"v":1,"removed":true,"words":"gone"}`}, - "released": {Want{Fp: a, Composed: c, Version: "0.1.15", Parts: map[string]string{"mesh-sdk:go": d}}, `{"v":1,"fp":"` + a + `","composed":"` + c + `","version":"0.1.15","parts":{"mesh-sdk:go":"` + d + `"}}`}, - "kept": {Want{Fp: a, Composed: c, Parts: map[string]string{"x:image": d}, KeptOn: "n1"}, `{"v":1,"fp":"` + a + `","composed":"` + c + `","parts":{"x:image":"` + d + `"},"kept-on":"n1"}`}, + "from a pipeline": {Want{Fp: a, Version: "0.1.15", Pipeline: "main.3589", Rank: 2, Words: "w"}, `{"v":1,"fp":"` + a + `","version":"0.1.15","pipeline":"main.3589","rank":2,"words":"w"}`}, + "backup answer": {Want{Fp: a, Self: true, Backup: BackupAgain, Words: "again"}, `{"v":1,"fp":"` + a + `","backup":"again","words":"again","self":true}`}, + "put": {Want{Fp: a, Self: true, Put: true, Hold: true, Yes: d, Release: "r1"}, `{"v":1,"fp":"` + a + `","put":true,"hold":true,"yes":"` + d + `","release":"r1","self":true}`}, + "revert": {Want{Fp: a, Self: true, Revert: RevertLive, Words: "live"}, `{"v":1,"fp":"` + a + `","revert":"live","words":"live","self":true}`}, + "removed": {Want{Removed: true, Words: "gone"}, `{"v":1,"removed":true,"words":"gone"}`}, + "a placement's build": {Want{Fp: a, Version: "0.1.14"}, `{"v":1,"fp":"` + a + `","version":"0.1.14"}`}, } { t.Run(name, func(t *testing.T) { raw, err := EncodeWant(row.w) @@ -60,26 +59,25 @@ func TestWantsAreWhatTheEarlierCodecWrote(t *testing.T) { }) t.Run("refused", func(t *testing.T) { for name, w := range map[string]Want{ - "old fingerprint": {Fp: "src1:abc", Composed: c}, - "no composition": {Fp: a}, - "self and composition": {Fp: a, Self: true, Composed: c}, - "hold without put": {Fp: a, Self: true, Hold: true}, - "put held back": {Fp: a, Self: true, Put: true, Newest: b, Rule: RuleStep}, - "removed names a rule": {Removed: true, Rule: 1}, - "release without yes": {Fp: a, Self: true, Release: "r"}, - "backup answer unknown": {Fp: a, Self: true, Backup: "later"}, - "revert answer unknown": {Fp: a, Self: true, Revert: "hold"}, - "newest equals fp": {Fp: a, Self: true, Newest: a, Rule: RuleStep}, - "rule 11": {Fp: a, Self: true, Newest: b, Rule: 11}, - "newest without a rule": {Fp: a, Self: true, Newest: b}, - "composition not sha256": {Fp: a, Composed: "sha256:xyz"}, + "old fingerprint": {Fp: "src1:abc"}, + "hold without put": {Fp: a, Self: true, Hold: true}, + "rank without pipeline": {Fp: a, Rank: 1}, + "pipeline without rank": {Fp: a, Pipeline: "main.3589"}, + "rank below 1": {Fp: a, Pipeline: "main.3589", Rank: -1}, + "removed names a pipeline": {Removed: true, Pipeline: "main.3589", Rank: 1}, + "release without yes": {Fp: a, Self: true, Release: "r"}, + "backup answer unknown": {Fp: a, Self: true, Backup: "later"}, + "revert answer unknown": {Fp: a, Self: true, Revert: "hold"}, } { if _, err := EncodeWant(w); err == nil { t.Errorf("%s: written", name) } } - if _, err := EncodeWant(Want{Fp: a, Self: true, Newest: b, Rule: 10}); err != nil { - t.Errorf("rule 10 is read: %v", err) + // design 47 H §750, H-A-37: a want names no digest, rule or newest; the earlier fields are refused. + for _, old := range []string{`"composed":"` + c + `"`, `"parts":{"x:image":"` + d + `"}`, `"rule":3`, `"newest":"` + b + `"`, `"kept-on":"n1"`} { + if _, err := DecodeWant([]byte(`{"v":1,"fp":"` + a + `",` + old + `}`)); err == nil { + t.Errorf("a want naming %s is read", old) + } } if _, err := DecodeWant([]byte(`{"fp":"` + a + `","self":true}`)); !errors.Is(err, keys.ErrUnknownVersion) { t.Errorf("no version: %v", err) diff --git a/modules/mesh-delivery-contracts/go/seats/meshwants/contract.go b/modules/mesh-delivery-contracts/go/seats/meshwants/contract.go index d68a4315..98ca9b80 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshwants/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/meshwants/contract.go @@ -34,13 +34,13 @@ const ( EventAssignmentRevision = "assignment-revision" EventDifference = "difference" EventWanted = "wanted" + EventPipelineWanted = "pipeline-wanted" EventWaitHeld = "wait-held" EventWaitEnded = "wait-ended" EventFilling = "filling" EventFull = "full" EventRoom = "room" EventStepEnded = "step-ended" - EventVersionDelivered = "version-delivered" EventStepProgress = "step-progress" ) @@ -51,7 +51,7 @@ func Verbs() []string { // Events is every event published on the seat's subject: a new copy each call. func Events() []string { - return []string{EventPolicyChanged, EventAssignmentRevision, EventDifference, EventWanted, EventWaitHeld, EventWaitEnded, EventFilling, EventFull, EventRoom, EventStepEnded, EventVersionDelivered, EventStepProgress} + return []string{EventPolicyChanged, EventAssignmentRevision, EventDifference, EventWanted, EventPipelineWanted, EventWaitHeld, EventWaitEnded, EventFilling, EventFull, EventRoom, EventStepEnded, EventStepProgress} } // Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects. @@ -80,6 +80,17 @@ func SubjectWanted(node, module string) string { // SubjectWantedAll hears every wanted. const SubjectWantedAll = "mesh.seat.mesh-wants.event.wanted.*.*" +// StreamPipelineWanted is the stream pipeline-wanted is kept in. +const StreamPipelineWanted = "SEAT_mesh-wants_pipeline-wanted" + +// SubjectPipelineWanted is where pipeline-wanted is published, on mesh.seat.mesh-wants.event.pipeline-wanted... +func SubjectPipelineWanted(branch, source string) string { + return "mesh.seat.mesh-wants.event.pipeline-wanted." + branch + "." + source +} + +// SubjectPipelineWantedAll hears every pipeline-wanted. +const SubjectPipelineWantedAll = "mesh.seat.mesh-wants.event.pipeline-wanted.*.*" + // SubjectWaitHeld is where wait-held is published. const SubjectWaitHeld = "mesh.seat.mesh-wants.event.wait-held" @@ -104,12 +115,6 @@ func SubjectStepEnded(node string) string { return "mesh.seat.mesh-wants.event.s // SubjectStepEndedAll hears every step-ended. const SubjectStepEndedAll = "mesh.seat.mesh-wants.event.step-ended.*" -// StreamVersionDelivered is the stream version-delivered is kept in. -const StreamVersionDelivered = "SEAT_mesh-wants_version-delivered" - -// SubjectVersionDelivered is where version-delivered is published. -const SubjectVersionDelivered = "mesh.seat.mesh-wants.event.version-delivered" - // SubjectStepProgress is where step-progress is published, on mesh.seat.mesh-wants.event.step-progress.. func SubjectStepProgress(node string) string { return "mesh.seat.mesh-wants.event.step-progress." + node @@ -982,6 +987,30 @@ type NodeEntryRef struct { Node string `json:"node"` } +// NotRunning is a mover of a late tier and the placing machines it does not run on. +type NotRunning struct { + Machines []string `json:"machines"` + Module string `json:"module"` +} + +// PipelineWanted is a pipeline's wants written to the end, said once: running when every tier's movers run on every present placing machine, tier-late when a tier passed tier-bound (design 47 H §751, H-A-56, H-A-72, H-A-75). +type PipelineWanted struct { + Branch string `json:"branch"` + // for tier-late, the late tier's movers not running and the machines they do not run on + NotRunning []NotRunning `json:"not-running,omitempty"` + Outcome string `json:"outcome"` + // the runner's pipeline key, ., a branch escaped as a key's name is (design 47 H §746) + Pipeline string `json:"pipeline"` + Source int64 `json:"source"` + V int64 `json:"v"` +} + +// The values of PipelineWanted's outcome. +const ( + PipelineWantedOutcomeRunning = "running" + PipelineWantedOutcomeTierLate = "tier-late" +) + // SharedAskedBy is the step that asked the run, for a test step reading another's run. type SharedAskedBy struct { // its artifact, : @@ -1002,7 +1031,7 @@ type Shared struct { Run string `json:"run"` } -// StepEnded is the composition step's end, said by the assigner on the node it runs on (ADR 0666 sections 7, 21): the runner takes it only from that holder's account, naming the ask, the commit and the fingerprint it was asked at. +// StepEnded is a validate or composition step's end, said by the assigner on the node it runs on (ADR 0666 sections 7, 21): the runner takes it only from that holder's account, naming the ask, the commit and the fingerprint it was asked at. type StepEnded struct { // for a rerun, the caller the runtime proved By string `json:"by,omitempty"` @@ -1018,7 +1047,7 @@ type StepEnded struct { Outcome string `json:"outcome"` Pipeline string `json:"pipeline"` Rerun bool `json:"rerun,omitempty"` - // why it failed or could not run: the two modules owning one path, the part not heard + // why it failed or could not run: each manifest problem, the cycle the revision makes, the two modules owning one path, the part not heard (design 47 H §745) Said string `json:"said,omitempty"` // per machine composed, the composition run the step read, its ask and so where its verdict was taken (design 47 G §723, §729) Shared []Shared `json:"shared,omitempty"` @@ -1040,10 +1069,11 @@ const ( // The values of StepEnded's step. const ( + StepEndedStepValidate = "validate" StepEndedStepComposition = "composition" ) -// StepRun is the composition step of one module's pipeline (design 47 *Pipeline steps and the policy*, *The pipeline makes the check*): the assigner composes each machine's declaration at the change's heads with the composer built from them, in the build seat's sandbox, and refuses a change in which two modules own one path. +// StepRun is a pipeline step of one mover the assigner serves (design 47 H §745, G §22): validate, the manifest validator built from the take-in's heads run over the revision's manifests, before composition, each machine's declaration composed at the change's heads with the composer built from them, both in the build seat's sandbox. type StepRun struct { // the watched branch, or the branch of a run on request Branch string `json:"branch"` @@ -1054,7 +1084,7 @@ type StepRun struct { // the module's build-input fingerprint at the commit Fingerprint string `json:"fingerprint"` Module string `json:"module"` - // the runner's pipeline key, .., a branch escaped as a key's name is + // the runner's pipeline key, ., a branch escaped as a key's name is (design 47 H §746) Pipeline string `json:"pipeline"` // the step is asked again by the runner's rerun Rerun bool `json:"rerun,omitempty"` @@ -1069,6 +1099,7 @@ type StepRun struct { // The values of StepRun's step. const ( + StepRunStepValidate = "validate" StepRunStepComposition = "composition" ) @@ -1279,6 +1310,8 @@ type WantedEvent struct { Fp string `json:"fp"` Module string `json:"module"` Node string `json:"node"` + // the pipeline whose passed end the want was written from, its key .; absent for a placement's build (design 47 H-A-56) + Pipeline string `json:"pipeline,omitempty"` // true when the assigner removes the want of that node and module (the node left, or the module was unplaced); fp is then the fingerprint last wanted there (design 47 G section 693) Removed bool `json:"removed,omitempty"` Revision int64 `json:"revision"` @@ -1286,6 +1319,9 @@ type WantedEvent struct { V int64 `json:"v"` } +// PipelineWantedEvent is the body of the event pipeline-wanted. +type PipelineWantedEvent = PipelineWanted + // WaitHeldEvent is the body of the event wait-held. type WaitHeldEvent = Wait @@ -1304,20 +1340,6 @@ type RoomEvent = Fill // StepEndedEvent is the body of the event step-ended. type StepEndedEvent = StepEnded -// VersionDeliveredEvent is the body of the event version-delivered. -type VersionDeliveredEvent struct { - At *time.Time `json:"at,omitempty"` - // the machines away when it was said - Away []string `json:"away,omitempty"` - // the module - Module string `json:"module"` - // the digest of each of its parts, by `:` - Parts map[string]string `json:"parts"` - V int64 `json:"v"` - // MAJOR.MINOR.PATCH - Version string `json:"version"` -} - // StepProgressEvent is the body of the event step-progress. type StepProgressEvent struct { Ask string `json:"ask"` @@ -1339,25 +1361,21 @@ const ( // WantsByWantNodeModuleValue is one value of the state wants under the key want... type WantsByWantNodeModuleValue struct { // again or skip - Backup string `json:"backup,omitempty"` - Composed string `json:"composed,omitempty"` - Fp string `json:"fp,omitempty"` - Hold bool `json:"hold,omitempty"` - // for a kept build, the build node that keeps it, from the builder's build.ended; the node-engine fetches the build through that node's seat verb kept-artifact, and a want with none from the store (design 47 G section 526) - KeptOn string `json:"kept-on,omitempty"` - Newest string `json:"newest,omitempty"` - // the digest of each of the module's parts, by `:`; the node-engine fetches and checks each part by it (design 47 G section 379) - Parts map[string]string `json:"parts,omitempty"` - Put bool `json:"put,omitempty"` - Release string `json:"release,omitempty"` - Removed bool `json:"removed,omitempty"` + Backup string `json:"backup,omitempty"` + Fp string `json:"fp,omitempty"` + Hold bool `json:"hold,omitempty"` + // the pipeline whose passed end released the version, its key .; absent for a placement's build (design 47 H §750, H-A-37) + Pipeline string `json:"pipeline,omitempty"` + Put bool `json:"put,omitempty"` + // the mover's tier in that pipeline's delivery order, from 1; the node-engine applies one pipeline's wants by it; absent with pipeline (design 47 H §750, §771, H-A-37) + Rank int64 `json:"rank,omitempty"` + Release string `json:"release,omitempty"` + Removed bool `json:"removed,omitempty"` // live: the operator's answer to a held revert, to start the reverted build on the live data as it is, with nothing restored (design 47 G section 710) Revert string `json:"revert,omitempty"` - // the rule that holds the node back, 1 to 10 - Rule int64 `json:"rule,omitempty"` - Self bool `json:"self,omitempty"` - V int64 `json:"v,omitempty"` - // the module's released version, for people; none for a build of another watched branch (design 47 G section 379) + Self bool `json:"self,omitempty"` + V int64 `json:"v,omitempty"` + // the version released at the build the want names: the newest released on the placement's branch whose pipeline passed, or the placement's build's (design 47 H §750) Version string `json:"version,omitempty"` Words string `json:"words,omitempty"` Yes string `json:"yes,omitempty"` diff --git a/modules/mesh-delivery-contracts/go/seats/meshwants/contract_test.go b/modules/mesh-delivery-contracts/go/seats/meshwants/contract_test.go index 9ed6c320..a090ff0d 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshwants/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/meshwants/contract_test.go @@ -25,10 +25,14 @@ func TestFixtures(t *testing.T) { }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.assignment-revision$")}, {name: "a difference worked out", subject: "mesh.seat.mesh-wants.event.difference", given: "{\"changes\":1,\"from\":40,\"nodes\":[\"n1\"],\"source\":3589,\"to\":41,\"v\":1}", wire: "{\"changes\":1,\"from\":40,\"nodes\":[\"n1\"],\"source\":3589,\"to\":41,\"v\":1}", decode: func(b []byte) (any, error) { var v DifferenceEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.difference$")}, - {name: "an entry wanted from a trunk revision", subject: "mesh.seat.mesh-wants.event.wanted.n1.xclip", given: "{\"at\":\"2026-11-09T19:00:00Z\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"module\":\"xclip\",\"node\":\"n1\",\"revision\":40,\"source\":3589,\"v\":1}", wire: "{\"at\":\"2026-11-09T19:00:00Z\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"module\":\"xclip\",\"node\":\"n1\",\"revision\":40,\"source\":3589,\"v\":1}", + {name: "an entry wanted from a passed pipeline, naming it", subject: "mesh.seat.mesh-wants.event.wanted.n1.xclip", given: "{\"at\":\"2026-11-09T19:00:00Z\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"module\":\"xclip\",\"node\":\"n1\",\"pipeline\":\"main.3589\",\"revision\":40,\"source\":3589,\"v\":1}", wire: "{\"at\":\"2026-11-09T19:00:00Z\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"module\":\"xclip\",\"node\":\"n1\",\"pipeline\":\"main.3589\",\"revision\":40,\"source\":3589,\"v\":1}", decode: func(b []byte) (any, error) { var v WantedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.wanted\\.[^.*> ]+\\.[^.*> ]+$")}, {name: "a want removed, its node left or its module unplaced", subject: "mesh.seat.mesh-wants.event.wanted.n1.xclip", given: "{\"at\":\"2026-11-09T19:05:00Z\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"module\":\"xclip\",\"node\":\"n1\",\"removed\":true,\"revision\":41,\"v\":1}", wire: "{\"at\":\"2026-11-09T19:05:00Z\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"module\":\"xclip\",\"node\":\"n1\",\"removed\":true,\"revision\":41,\"v\":1}", decode: func(b []byte) (any, error) { var v WantedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.wanted\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "a pipeline's wants all run", subject: "mesh.seat.mesh-wants.event.pipeline-wanted.main.3589", given: "{\"branch\":\"main\",\"outcome\":\"running\",\"pipeline\":\"main.3589\",\"source\":3589,\"v\":1}", wire: "{\"branch\":\"main\",\"outcome\":\"running\",\"pipeline\":\"main.3589\",\"source\":3589,\"v\":1}", + decode: func(b []byte) (any, error) { var v PipelineWantedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.pipeline-wanted\\.[^.*> ]+\\.[^.*> ]+$")}, + {name: "a pipeline's tier late, naming the movers and machines not running", subject: "mesh.seat.mesh-wants.event.pipeline-wanted.main.3590", given: "{\"branch\":\"main\",\"not-running\":[{\"machines\":[\"anchor\",\"laptop\"],\"module\":\"nats\"}],\"outcome\":\"tier-late\",\"pipeline\":\"main.3590\",\"source\":3590,\"v\":1}", wire: "{\"branch\":\"main\",\"not-running\":[{\"machines\":[\"anchor\",\"laptop\"],\"module\":\"nats\"}],\"outcome\":\"tier-late\",\"pipeline\":\"main.3590\",\"source\":3590,\"v\":1}", + decode: func(b []byte) (any, error) { var v PipelineWantedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.pipeline-wanted\\.[^.*> ]+\\.[^.*> ]+$")}, {name: "a composing wait held with its bound", subject: "mesh.seat.mesh-wants.event.wait-held", given: "{\"bound\":\"30m\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"module\":\"xclip\",\"node\":\"n1\",\"part\":\"node-engine\",\"since\":\"2026-11-09T19:00:00Z\",\"step\":\"compose\",\"version\":\"src2:7dd0db8e98224f46121a5ae05c0b9c5a430eff531a5120aa40b1a59237853a3f\"}", wire: "{\"bound\":\"30m\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"module\":\"xclip\",\"node\":\"n1\",\"part\":\"node-engine\",\"since\":\"2026-11-09T19:00:00Z\",\"step\":\"compose\",\"version\":\"src2:7dd0db8e98224f46121a5ae05c0b9c5a430eff531a5120aa40b1a59237853a3f\"}", decode: func(b []byte) (any, error) { var v WaitHeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.wait-held$")}, {name: "a wait ended, released by hand", subject: "mesh.seat.mesh-wants.event.wait-ended", given: "{\"bound\":\"30m\",\"by\":\"lead@workstation: the node is away\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"how\":\"released\",\"module\":\"xclip\",\"node\":\"n1\",\"part\":\"node-engine\",\"since\":\"2026-11-09T19:00:00Z\",\"step\":\"compose\",\"version\":\"src2:7dd0db8e98224f46121a5ae05c0b9c5a430eff531a5120aa40b1a59237853a3f\"}", wire: "{\"bound\":\"30m\",\"by\":\"lead@workstation: the node is away\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"how\":\"released\",\"module\":\"xclip\",\"node\":\"n1\",\"part\":\"node-engine\",\"since\":\"2026-11-09T19:00:00Z\",\"step\":\"compose\",\"version\":\"src2:7dd0db8e98224f46121a5ae05c0b9c5a430eff531a5120aa40b1a59237853a3f\"}", @@ -43,8 +47,6 @@ 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\\.mesh-wants\\.event\\.step-ended\\.[^.*> ]+$")}, {name: "the composition step failed, two modules owning one path", subject: "mesh.seat.mesh-wants.event.step-ended.laptop", given: "{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d6b\",\"module\":\"nats\",\"node\":\"laptop\",\"outcome\":\"failed\",\"pipeline\":\"main.12.nats\",\"said\":\"nats and xclip both own /etc/nats.conf on anchor\",\"step\":\"composition\",\"v\":1}", wire: "{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"id\":\"m2kx9a1b3c4d6b\",\"module\":\"nats\",\"node\":\"laptop\",\"outcome\":\"failed\",\"pipeline\":\"main.12.nats\",\"said\":\"nats and xclip both own /etc/nats.conf on anchor\",\"step\":\"composition\",\"v\":1}", decode: func(b []byte) (any, error) { var v StepEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.step-ended\\.[^.*> ]+$")}, - {name: "a version delivered with the machines away", subject: "mesh.seat.mesh-wants.event.version-delivered", given: "{\"away\":[\"laptop\"],\"module\":\"mesh-sdk\",\"parts\":{\"mesh-sdk:go\":\"sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"},\"v\":1,\"version\":\"0.1.15\"}", wire: "{\"away\":[\"laptop\"],\"module\":\"mesh-sdk\",\"parts\":{\"mesh-sdk:go\":\"sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"},\"v\":1,\"version\":\"0.1.15\"}", - decode: func(b []byte) (any, error) { var v VersionDeliveredEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.version-delivered$")}, {name: "a composition step's progress", subject: "mesh.seat.mesh-wants.event.step-progress.anchor", given: "{\"ask\":\"a1b2\",\"asker\":\"assigner\",\"at\":\"2026-11-11T10:01:00Z\",\"phase\":\"build\"}", wire: "{\"ask\":\"a1b2\",\"asker\":\"assigner\",\"at\":\"2026-11-11T10:01:00Z\",\"phase\":\"build\"}", decode: func(b []byte) (any, error) { var v StepProgressEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.step-progress\\.[^.*> ]+$")}, {name: "a put without hold waits, counted from its start", subject: "mesh.seat.mesh-wants.event.wait-held", given: "{\"bound\":\"30m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"node\":\"anchor\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"put\"}", wire: "{\"bound\":\"30m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"node\":\"anchor\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"put\"}", @@ -63,13 +65,13 @@ 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\\.mesh-wants\\.event\\.step-ended\\.[^.*> ]+$")}, {name: "C1/AC1 a composition step's progress, naming the runs it waits on", subject: "mesh.seat.mesh-wants.event.step-progress.anchor", given: "{\"ask\":\"a1b2\",\"asker\":\"assigner\",\"at\":\"2026-11-17T10:01:00Z\",\"phase\":\"run\",\"shared\":[{\"ask\":\"r1a2b3\",\"machine\":\"anchor\",\"run\":\"main.12.anchor\"}]}", wire: "{\"ask\":\"a1b2\",\"asker\":\"assigner\",\"at\":\"2026-11-17T10:01:00Z\",\"phase\":\"run\",\"shared\":[{\"ask\":\"r1a2b3\",\"machine\":\"anchor\",\"run\":\"main.12.anchor\"}]}", decode: func(b []byte) (any, error) { var v StepProgressEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.step-progress\\.[^.*> ]+$")}, - {name: "a want", subject: "", given: "{\"fp\":\"ab12\",\"rule\":3,\"v\":1}", wire: "{\"fp\":\"ab12\",\"rule\":3,\"v\":1}", + {name: "a want written from a passed pipeline, its version and rank", subject: "", given: "{\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"pipeline\":\"main.3589\",\"rank\":2,\"v\":1,\"version\":\"0.1.15\"}", wire: "{\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"pipeline\":\"main.3589\",\"rank\":2,\"v\":1,\"version\":\"0.1.15\"}", decode: func(b []byte) (any, error) { var v WantsByWantNodeModuleValue err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, - {name: "a want for a kept build, naming the node that keeps it", subject: "", given: "{\"fp\":\"ab12\",\"kept-on\":\"n1\",\"parts\":{\"x:image\":\"sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"},\"v\":1,\"version\":\"0.1.15\"}", wire: "{\"fp\":\"ab12\",\"kept-on\":\"n1\",\"parts\":{\"x:image\":\"sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"},\"v\":1,\"version\":\"0.1.15\"}", + {name: "a want of a placement's build, no pipeline and no rank", subject: "", given: "{\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"v\":1,\"version\":\"0.1.14\"}", wire: "{\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"v\":1,\"version\":\"0.1.14\"}", decode: func(b []byte) (any, error) { var v WantsByWantNodeModuleValue err := json.Unmarshal(b, &v) @@ -139,7 +141,9 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v DifferenceAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "difference refuses a changed fingerprint with no difference, by name", subject: "", given: "{\"changes\":[],\"from\":40,\"refused\":[{\"module\":\"xclip\",\"why\":\"its fingerprint changed and its difference is empty\"}],\"to\":41}", wire: "{\"changes\":[],\"from\":40,\"refused\":[{\"module\":\"xclip\",\"why\":\"its fingerprint changed and its difference is empty\"}],\"to\":41}", decode: func(b []byte) (any, error) { var v DifferenceAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "a composition step asked by the runner", subject: "mesh.seat.mesh-wants.accept.step", given: "{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"source\":3589,\"step\":\"composition\"}", wire: "{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"pipeline\":\"main.12.nats\",\"revision\":12,\"source\":3589,\"step\":\"composition\"}", + {name: "a composition step asked by the runner", subject: "mesh.seat.mesh-wants.accept.step", given: "{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"pipeline\":\"main.3589\",\"revision\":12,\"source\":3589,\"step\":\"composition\"}", wire: "{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"pipeline\":\"main.3589\",\"revision\":12,\"source\":3589,\"step\":\"composition\"}", + decode: func(b []byte) (any, error) { var v StepAccept; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.accept\\.step$")}, + {name: "a validate step asked by the runner, before the mover's composition", subject: "mesh.seat.mesh-wants.accept.step", given: "{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"pipeline\":\"main.3589\",\"revision\":12,\"source\":3589,\"step\":\"validate\"}", wire: "{\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"pipeline\":\"main.3589\",\"revision\":12,\"source\":3589,\"step\":\"validate\"}", decode: func(b []byte) (any, error) { var v StepAccept; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.accept\\.step$")}, {name: "input asks a composition step's input by digest", subject: "", given: "{\"call\":\"0123456789abcdef0123456789abcdef\",\"digest\":\"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"}", wire: "{\"call\":\"0123456789abcdef0123456789abcdef\",\"digest\":\"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"}", decode: func(b []byte) (any, error) { var v InputInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, diff --git a/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/events.json b/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/events.json index 6cdc780f..feeace4e 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/events.json +++ b/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/events.json @@ -34,7 +34,7 @@ } }, { - "name": "an entry wanted from a trunk revision", + "name": "an entry wanted from a passed pipeline, naming it", "of": "event:wanted", "subject": "mesh.seat.mesh-wants.event.wanted.n1.xclip", "given": { @@ -44,7 +44,8 @@ "fp": "src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56", "revision": 40, "source": 3589, - "at": "2026-11-09T19:00:00Z" + "at": "2026-11-09T19:00:00Z", + "pipeline": "main.3589" } }, { @@ -61,6 +62,39 @@ "at": "2026-11-09T19:05:00Z" } }, + { + "name": "a pipeline's wants all run", + "of": "event:pipeline-wanted", + "subject": "mesh.seat.mesh-wants.event.pipeline-wanted.main.3589", + "given": { + "v": 1, + "pipeline": "main.3589", + "branch": "main", + "source": 3589, + "outcome": "running" + } + }, + { + "name": "a pipeline's tier late, naming the movers and machines not running", + "of": "event:pipeline-wanted", + "subject": "mesh.seat.mesh-wants.event.pipeline-wanted.main.3590", + "given": { + "v": 1, + "pipeline": "main.3590", + "branch": "main", + "source": 3590, + "outcome": "tier-late", + "not-running": [ + { + "module": "nats", + "machines": [ + "anchor", + "laptop" + ] + } + ] + } + }, { "name": "a composing wait held with its bound", "of": "event:wait-held", @@ -165,22 +199,6 @@ "said": "nats and xclip both own /etc/nats.conf on anchor" } }, - { - "name": "a version delivered with the machines away", - "of": "event:version-delivered", - "subject": "mesh.seat.mesh-wants.event.version-delivered", - "given": { - "v": 1, - "module": "mesh-sdk", - "version": "0.1.15", - "parts": { - "mesh-sdk:go": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" - }, - "away": [ - "laptop" - ] - } - }, { "name": "a composition step's progress", "of": "event:step-progress", diff --git a/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/states.json b/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/states.json index af8fd946..d5e7b03e 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/states.json +++ b/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/states.json @@ -1,24 +1,22 @@ [ { - "name": "a want", + "name": "a want written from a passed pipeline, its version and rank", "of": "state:wants/want..", "given": { "v": 1, - "fp": "ab12", - "rule": 3 + "fp": "src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56", + "version": "0.1.15", + "pipeline": "main.3589", + "rank": 2 } }, { - "name": "a want for a kept build, naming the node that keeps it", + "name": "a want of a placement's build, no pipeline and no rank", "of": "state:wants/want..", "given": { "v": 1, - "fp": "ab12", - "version": "0.1.15", - "parts": { - "x:image": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" - }, - "kept-on": "n1" + "fp": "src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56", + "version": "0.1.14" } }, { diff --git a/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/verbs.json b/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/verbs.json index df3caf96..cbeb2d7f 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/verbs.json +++ b/modules/mesh-delivery-contracts/seats/mesh-wants/fixtures/verbs.json @@ -150,7 +150,7 @@ "of": "accept:step", "subject": "mesh.seat.mesh-wants.accept.step", "given": { - "pipeline": "main.12.nats", + "pipeline": "main.3589", "step": "composition", "module": "nats", "branch": "main", @@ -160,6 +160,21 @@ "fingerprint": "fp-0123" } }, + { + "name": "a validate step asked by the runner, before the mover's composition", + "of": "accept:step", + "subject": "mesh.seat.mesh-wants.accept.step", + "given": { + "pipeline": "main.3589", + "step": "validate", + "module": "nats", + "branch": "main", + "commit": "0123456789abcdef0123456789abcdef01234567", + "revision": 12, + "source": 3589, + "fingerprint": "fp-0123" + } + }, { "name": "input asks a composition step's input by digest", "of": "verb:input.input", diff --git a/modules/mesh-delivery-contracts/seats/mesh-wants/seat.json b/modules/mesh-delivery-contracts/seats/mesh-wants/seat.json index 597df58f..09488de3 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-wants/seat.json +++ b/modules/mesh-delivery-contracts/seats/mesh-wants/seat.json @@ -54,7 +54,7 @@ }, { "name": "revision", - "description": "The assignment half of the revision view (ADR 0656 \u00a76): one assignment graph revision, named by its own number and naming its inputs, with its entries' digests; the trunk's newest when none is named, or a candidate's for its group and heads. Reads only.", + "description": "The assignment half of the revision view (ADR 0656 §6): one assignment graph revision, named by its own number and naming its inputs, with its entries' digests; the trunk's newest when none is named, or a candidate's for its group and heads. Reads only.", "input": { "type": "object", "properties": { @@ -201,7 +201,7 @@ { "name": "compositions", "class": "read", - "description": "Each composition run the assigner keeps (design 47 G \u00a7728): its program, input digest, ask, readers, outcome and verdict, and the state's fill against its cap; with candidate or machine, only those.", + "description": "Each composition run the assigner keeps (design 47 G §728): its program, input digest, ask, readers, outcome and verdict, and the state's fill against its cap; with candidate or machine, only those.", "input": { "type": "object", "properties": { @@ -236,7 +236,7 @@ { "name": "compositions-drop", "class": "act", - "description": "Drop one composition run by hand (design 47 G \u00a7728): the act and why are written in the hand-act log first, then the run's ask is dropped, each reader ended could not run naming the drop, and the key deleted.", + "description": "Drop one composition run by hand (design 47 G §728): the act and why are written in the hand-act log first, then the run's ask is dropped, each reader ended could not run naming the drop, and the key deleted.", "input": { "type": "object", "properties": { @@ -404,6 +404,10 @@ "fp": { "type": "string" }, + "pipeline": { + "type": "string", + "description": "the pipeline whose passed end the want was written from, its key .; absent for a placement's build (design 47 H-A-56)" + }, "revision": { "type": "integer" }, @@ -428,6 +432,17 @@ ] } }, + { + "name": "pipeline-wanted", + "subject": "pipeline-wanted..", + "keep": { + "max-age-days": 30, + "max-mib": 64 + }, + "body": { + "$ref": "#/defs/PipelineWanted" + } + }, { "name": "wait-held", "body": { @@ -469,54 +484,6 @@ "max-mib": 32 } }, - { - "name": "version-delivered", - "keep": { - "max-age-days": 90, - "max-mib": 64 - }, - "body": { - "type": "object", - "description": "a version delivered to every present machine that places it, and healthy (design 47 G section 376)", - "properties": { - "v": { - "type": "integer" - }, - "module": { - "type": "string", - "description": "the module" - }, - "version": { - "type": "string", - "description": "MAJOR.MINOR.PATCH" - }, - "parts": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "the digest of each of its parts, by `:`" - }, - "away": { - "type": "array", - "items": { - "type": "string" - }, - "description": "the machines away when it was said" - }, - "at": { - "type": "string", - "format": "date-time" - } - }, - "required": [ - "v", - "module", - "version", - "parts" - ] - } - }, { "name": "step-progress", "subject": "step-progress.", @@ -548,7 +515,7 @@ "items": { "$ref": "#/defs/Shared" }, - "description": "the composition runs the step waits on, by machine, each with its ask (design 47 G \u00a7723, \u00a7729)" + "description": "the composition runs the step waits on, by machine, each with its ask (design 47 G §723, §729)" } }, "required": [ @@ -574,7 +541,7 @@ "key": "want..", "value": { "type": "object", - "description": "a node's want for a module", + "description": "a node's want for a module: the build it should run by its fingerprint and released version, with the pipeline and rank it was written from (design 47 H §750)", "properties": { "v": { "type": "integer" @@ -582,19 +549,9 @@ "fp": { "type": "string" }, - "composed": { - "type": "string" - }, "removed": { "type": "boolean" }, - "newest": { - "type": "string" - }, - "rule": { - "type": "integer", - "description": "the rule that holds the node back, 1 to 10" - }, "backup": { "type": "string", "description": "again or skip", @@ -630,18 +587,16 @@ }, "version": { "type": "string", - "description": "the module's released version, for people; none for a build of another watched branch (design 47 G section 379)" + "description": "the version released at the build the want names: the newest released on the placement's branch whose pipeline passed, or the placement's build's (design 47 H §750)" }, - "parts": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "the digest of each of the module's parts, by `:`; the node-engine fetches and checks each part by it (design 47 G section 379)" - }, - "kept-on": { + "pipeline": { "type": "string", - "description": "for a kept build, the build node that keeps it, from the builder's build.ended; the node-engine fetches the build through that node's seat verb kept-artifact, and a want with none from the store (design 47 G section 526)" + "description": "the pipeline whose passed end released the version, its key .; absent for a placement's build (design 47 H §750, H-A-37)" + }, + "rank": { + "type": "integer", + "minimum": 1, + "description": "the mover's tier in that pipeline's delivery order, from 1; the node-engine applies one pipeline's wants by it; absent with pipeline (design 47 H §750, §771, H-A-37)" } } }, @@ -1220,7 +1175,7 @@ "$ref": "#/defs/NodeEntryRef" } }, - "description": "the order as a view: each tier the changes whose acting parts acted in the tiers before it (ADR 0603 \u00a76 as ADR 0656 changes it)" + "description": "the order as a view: each tier the changes whose acting parts acted in the tiers before it (ADR 0603 §6 as ADR 0656 changes it)" }, "refused": { "type": "array", @@ -1371,15 +1326,16 @@ }, "StepRun": { "type": "object", - "description": "the composition step of one module's pipeline (design 47 *Pipeline steps and the policy*, *The pipeline makes the check*): the assigner composes each machine's declaration at the change's heads with the composer built from them, in the build seat's sandbox, and refuses a change in which two modules own one path", + "description": "a pipeline step of one mover the assigner serves (design 47 H §745, G §22): validate, the manifest validator built from the take-in's heads run over the revision's manifests, before composition, each machine's declaration composed at the change's heads with the composer built from them, both in the build seat's sandbox", "properties": { "pipeline": { "type": "string", - "description": "the runner's pipeline key, .., a branch escaped as a key's name is" + "description": "the runner's pipeline key, ., a branch escaped as a key's name is (design 47 H §746)" }, "step": { "type": "string", "enum": [ + "validate", "composition" ] }, @@ -1430,7 +1386,7 @@ }, "StepEnded": { "type": "object", - "description": "the composition step's end, said by the assigner on the node it runs on (ADR 0666 sections 7, 21): the runner takes it only from that holder's account, naming the ask, the commit and the fingerprint it was asked at", + "description": "a validate or composition step's end, said by the assigner on the node it runs on (ADR 0666 sections 7, 21): the runner takes it only from that holder's account, naming the ask, the commit and the fingerprint it was asked at", "properties": { "v": { "type": "integer", @@ -1446,6 +1402,7 @@ "step": { "type": "string", "enum": [ + "validate", "composition" ] }, @@ -1474,7 +1431,7 @@ }, "said": { "type": "string", - "description": "why it failed or could not run: the two modules owning one path, the part not heard" + "description": "why it failed or could not run: each manifest problem, the cycle the revision makes, the two modules owning one path, the part not heard (design 47 H §745)" }, "warnings": { "type": "array", @@ -1503,7 +1460,7 @@ "items": { "$ref": "#/defs/Shared" }, - "description": "per machine composed, the composition run the step read, its ask and so where its verdict was taken (design 47 G \u00a7723, \u00a7729)" + "description": "per machine composed, the composition run the step read, its ask and so where its verdict was taken (design 47 G §723, §729)" } }, "required": [ @@ -1561,7 +1518,7 @@ }, "Shared": { "type": "object", - "description": "a run whose result a step took or waits on, asked once for every step that reads it (design 47 G \u00a7729, A-469t): for a composition step one per machine composed, `run` the `composition-runs` key and `ask` its run ask's id; for a test step one with no machine, `run` the `test-runs` key, `ask` its build seat ask's id and `asked-by` the step that asked the run, left out for that step itself", + "description": "a run whose result a step took or waits on, asked once for every step that reads it (design 47 G §729, A-469t): for a composition step one per machine composed, `run` the `composition-runs` key and `ask` its run ask's id; for a test step one with no machine, `run` the `test-runs` key, `ask` its build seat ask's id and `asked-by` the step that asked the run, left out for that step itself", "properties": { "machine": { "type": "string", @@ -1601,7 +1558,7 @@ }, "CompositionReader": { "type": "object", - "description": "a composition step reading a composition run: its step, as the runner asked it, with its ask's id (design 47 G \u00a7719, A-468)", + "description": "a composition step reading a composition run: its step, as the runner asked it, with its ask's id (design 47 G §719, A-468)", "properties": { "id": { "type": "string", @@ -1670,7 +1627,7 @@ }, "CompositionRun": { "type": "object", - "description": "one composition run of a candidate and a machine, a key of the assigner's state composition-runs (design 47 G \u00a7719, \u00a7728; A-469u)", + "description": "one composition run of a candidate and a machine, a key of the assigner's state composition-runs (design 47 G §719, §728; A-469u)", "properties": { "key": { "type": "string", @@ -1739,7 +1696,7 @@ }, "verdict": { "type": "object", - "description": "that machine's composer verdict (design 47 G \u00a7721)" + "description": "that machine's composer verdict (design 47 G §721)" } }, "required": [ @@ -1747,6 +1704,66 @@ "candidate", "machine" ] + }, + "PipelineWanted": { + "type": "object", + "description": "a pipeline's wants written to the end, said once: running when every tier's movers run on every present placing machine, tier-late when a tier passed tier-bound (design 47 H §751, H-A-56, H-A-72, H-A-75)", + "properties": { + "v": { + "type": "integer" + }, + "pipeline": { + "type": "string", + "description": "the runner's pipeline key, ., a branch escaped as a key's name is (design 47 H §746)" + }, + "branch": { + "type": "string" + }, + "source": { + "type": "integer" + }, + "outcome": { + "type": "string", + "enum": [ + "running", + "tier-late" + ] + }, + "not-running": { + "type": "array", + "items": { + "$ref": "#/defs/NotRunning" + }, + "description": "for tier-late, the late tier's movers not running and the machines they do not run on" + } + }, + "required": [ + "v", + "pipeline", + "branch", + "source", + "outcome" + ] + }, + "NotRunning": { + "type": "object", + "description": "a mover of a late tier and the placing machines it does not run on", + "properties": { + "module": { + "type": "string" + }, + "machines": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + } + }, + "required": [ + "module", + "machines" + ] } }, "acts": [ diff --git a/modules/mesh-delivery-contracts/ts/seats/meshwants/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/meshwants/index.d.ts index 6e043fcf..c8112c2e 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshwants/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/meshwants/index.d.ts @@ -24,13 +24,13 @@ export declare const events: { readonly assignmentRevision: "assignment-revision"; readonly difference: "difference"; readonly wanted: "wanted"; + readonly pipelineWanted: "pipeline-wanted"; readonly waitHeld: "wait-held"; readonly waitEnded: "wait-ended"; readonly filling: "filling"; readonly full: "full"; readonly room: "room"; readonly stepEnded: "step-ended"; - readonly versionDelivered: "version-delivered"; readonly stepProgress: "step-progress"; }; @@ -48,6 +48,12 @@ export declare function wantedSubject(node: string, module: string): string; export declare const wantedSubjectAll: "mesh.seat.mesh-wants.event.wanted.*.*"; +export declare const pipelineWantedStream: "SEAT_mesh-wants_pipeline-wanted"; + +export declare function pipelineWantedSubject(branch: string, source: string): string; + +export declare const pipelineWantedSubjectAll: "mesh.seat.mesh-wants.event.pipeline-wanted.*.*"; + export declare const waitHeldSubject: "mesh.seat.mesh-wants.event.wait-held"; export declare const waitEndedSubject: "mesh.seat.mesh-wants.event.wait-ended"; @@ -64,10 +70,6 @@ export declare function stepEndedSubject(node: string): string; export declare const stepEndedSubjectAll: "mesh.seat.mesh-wants.event.step-ended.*"; -export declare const versionDeliveredStream: "SEAT_mesh-wants_version-delivered"; - -export declare const versionDeliveredSubject: "mesh.seat.mesh-wants.event.version-delivered"; - export declare function stepProgressSubject(node: string): string; export declare const stepProgressSubjectAll: "mesh.seat.mesh-wants.event.step-progress.*"; @@ -396,6 +398,24 @@ export interface NodeEntryRef { "node": string; } +/** a mover of a late tier and the placing machines it does not run on */ +export interface NotRunning { + "machines": string[]; + "module": string; +} + +/** a pipeline's wants written to the end, said once: running when every tier's movers run on every present placing machine, tier-late when a tier passed tier-bound (design 47 H §751, H-A-56, H-A-72, H-A-75) */ +export interface PipelineWanted { + "branch": string; + /** for tier-late, the late tier's movers not running and the machines they do not run on */ + "not-running"?: NotRunning[]; + "outcome": "running" | "tier-late"; + /** the runner's pipeline key, ., a branch escaped as a key's name is (design 47 H §746) */ + "pipeline": string; + "source": number; + "v": number; +} + /** the step that asked the run, for a test step reading another's run */ export interface SharedAskedBy { /** its artifact, : */ @@ -416,7 +436,7 @@ export interface Shared { "run": string; } -/** the composition step's end, said by the assigner on the node it runs on (ADR 0666 sections 7, 21): the runner takes it only from that holder's account, naming the ask, the commit and the fingerprint it was asked at */ +/** a validate or composition step's end, said by the assigner on the node it runs on (ADR 0666 sections 7, 21): the runner takes it only from that holder's account, naming the ask, the commit and the fingerprint it was asked at */ export interface StepEnded { /** for a rerun, the caller the runtime proved */ "by"?: string; @@ -432,19 +452,19 @@ export interface StepEnded { "outcome": "passed" | "failed" | "nothing to run" | "could not run"; "pipeline": string; "rerun"?: boolean; - /** why it failed or could not run: the two modules owning one path, the part not heard */ + /** why it failed or could not run: each manifest problem, the cycle the revision makes, the two modules owning one path, the part not heard (design 47 H §745) */ "said"?: string; /** per machine composed, the composition run the step read, its ask and so where its verdict was taken (design 47 G §723, §729) */ "shared"?: Shared[]; "started"?: string; - "step": "composition"; + "step": "validate" | "composition"; /** the layout version */ "v"?: number; /** a node asleep, passed with a warning (ADR 0593 section 9) */ "warnings"?: string[]; } -/** the composition step of one module's pipeline (design 47 *Pipeline steps and the policy*, *The pipeline makes the check*): the assigner composes each machine's declaration at the change's heads with the composer built from them, in the build seat's sandbox, and refuses a change in which two modules own one path */ +/** a pipeline step of one mover the assigner serves (design 47 H §745, G §22): validate, the manifest validator built from the take-in's heads run over the revision's manifests, before composition, each machine's declaration composed at the change's heads with the composer built from them, both in the build seat's sandbox */ export interface StepRun { /** the watched branch, or the branch of a run on request */ "branch": string; @@ -455,7 +475,7 @@ export interface StepRun { /** the module's build-input fingerprint at the commit */ "fingerprint": string; "module": string; - /** the runner's pipeline key, .., a branch escaped as a key's name is */ + /** the runner's pipeline key, ., a branch escaped as a key's name is (design 47 H §746) */ "pipeline": string; /** the step is asked again by the runner's rerun */ "rerun"?: boolean; @@ -465,7 +485,7 @@ export interface StepRun { "run"?: string; /** the source revision of the watched branch; absent for a run on request */ "source"?: number; - "step": "composition"; + "step": "validate" | "composition"; } /** a step's wait the assigner holds: placing, wanting or composing until an acting part's new version runs; the builder's toolchain wait is of this type too, with step build (design 47 G section 702) */ @@ -652,6 +672,8 @@ export interface WantedEvent { "fp": string; "module": string; "node": string; + /** the pipeline whose passed end the want was written from, its key .; absent for a placement's build (design 47 H-A-56) */ + "pipeline"?: string; /** true when the assigner removes the want of that node and module (the node left, or the module was unplaced); fp is then the fingerprint last wanted there (design 47 G section 693) */ "removed"?: boolean; "revision": number; @@ -659,6 +681,9 @@ export interface WantedEvent { "v": number; } +/** is the body of the event pipeline-wanted. */ +export type PipelineWantedEvent = PipelineWanted; + /** is the body of the event wait-held. */ export type WaitHeldEvent = Wait; @@ -677,20 +702,6 @@ export type RoomEvent = Fill; /** is the body of the event step-ended. */ export type StepEndedEvent = StepEnded; -/** is the body of the event version-delivered. */ -export interface VersionDeliveredEvent { - "at"?: string; - /** the machines away when it was said */ - "away"?: string[]; - /** the module */ - "module": string; - /** the digest of each of its parts, by `:` */ - "parts": Record; - "v": number; - /** MAJOR.MINOR.PATCH */ - "version": string; -} - /** is the body of the event step-progress. */ export interface StepProgressEvent { "ask": string; @@ -705,24 +716,20 @@ export interface StepProgressEvent { export interface WantsByWantNodeModuleValue { /** again or skip */ "backup"?: "again" | "skip"; - "composed"?: string; "fp"?: string; "hold"?: boolean; - /** for a kept build, the build node that keeps it, from the builder's build.ended; the node-engine fetches the build through that node's seat verb kept-artifact, and a want with none from the store (design 47 G section 526) */ - "kept-on"?: string; - "newest"?: string; - /** the digest of each of the module's parts, by `:`; the node-engine fetches and checks each part by it (design 47 G section 379) */ - "parts"?: Record; + /** the pipeline whose passed end released the version, its key .; absent for a placement's build (design 47 H §750, H-A-37) */ + "pipeline"?: string; "put"?: boolean; + /** the mover's tier in that pipeline's delivery order, from 1; the node-engine applies one pipeline's wants by it; absent with pipeline (design 47 H §750, §771, H-A-37) */ + "rank"?: number; "release"?: string; "removed"?: boolean; /** live: the operator's answer to a held revert, to start the reverted build on the live data as it is, with nothing restored (design 47 G section 710) */ "revert"?: "live"; - /** the rule that holds the node back, 1 to 10 */ - "rule"?: number; "self"?: boolean; "v"?: number; - /** the module's released version, for people; none for a build of another watched branch (design 47 G section 379) */ + /** the version released at the build the want names: the newest released on the placement's branch whose pipeline passed, or the placement's build's (design 47 H §750) */ "version"?: string; "words"?: string; "yes"?: string; diff --git a/modules/mesh-delivery-contracts/ts/seats/meshwants/index.js b/modules/mesh-delivery-contracts/ts/seats/meshwants/index.js index 391640d1..a544df9a 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshwants/index.js +++ b/modules/mesh-delivery-contracts/ts/seats/meshwants/index.js @@ -24,13 +24,13 @@ export const events = { assignmentRevision: "assignment-revision", difference: "difference", wanted: "wanted", + pipelineWanted: "pipeline-wanted", waitHeld: "wait-held", waitEnded: "wait-ended", filling: "filling", full: "full", room: "room", stepEnded: "step-ended", - versionDelivered: "version-delivered", stepProgress: "step-progress", }; @@ -50,6 +50,14 @@ export function wantedSubject(node, module) { export const wantedSubjectAll = "mesh.seat.mesh-wants.event.wanted.*.*"; +export const pipelineWantedStream = "SEAT_mesh-wants_pipeline-wanted"; + +export function pipelineWantedSubject(branch, source) { + return "mesh.seat.mesh-wants.event.pipeline-wanted." + branch + "." + source; +} + +export const pipelineWantedSubjectAll = "mesh.seat.mesh-wants.event.pipeline-wanted.*.*"; + export const waitHeldSubject = "mesh.seat.mesh-wants.event.wait-held"; export const waitEndedSubject = "mesh.seat.mesh-wants.event.wait-ended"; @@ -68,10 +76,6 @@ export function stepEndedSubject(node) { export const stepEndedSubjectAll = "mesh.seat.mesh-wants.event.step-ended.*"; -export const versionDeliveredStream = "SEAT_mesh-wants_version-delivered"; - -export const versionDeliveredSubject = "mesh.seat.mesh-wants.event.version-delivered"; - export function stepProgressSubject(node) { return "mesh.seat.mesh-wants.event.step-progress." + node; }