diff --git a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go index 9b5b3f87..96e4131c 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract.go @@ -239,6 +239,42 @@ func DecodePipelinesByBranchSourcePublishedPackageVersionValue(raw []byte) (Pipe return v, nil } +// PipelinesByBranchRunRunKey is the key of one value of the state pipelines under the form ".run.". +func PipelinesByBranchRunRunKey(branch, run string) string { return branch + ".run." + run } + +// ParsePipelinesByBranchRunRunKey reads the parts of a key of the form ".run.", in the order of the form; the last result is false for a key of another form. +func ParsePipelinesByBranchRunRunKey(key string) (string, string, bool) { + rest := key + v0, after0, found0 := strings.Cut(rest, ".run.") + if !found0 || v0 == "" { + return "", "", false + } + rest = after0 + if rest == "" { + return "", "", false + } + v2 := rest + rest = "" + if rest != "" { + return "", "", false + } + return v0, v2, true +} + +// DecodePipelinesByBranchRunRunValue reads one value of the state pipelines under the form ".run.", refusing a field PipelinesByBranchRunRunValue does not know and any text after the value. +func DecodePipelinesByBranchRunRunValue(raw []byte) (PipelinesByBranchRunRunValue, error) { + var v PipelinesByBranchRunRunValue + dec := json.NewDecoder(bytes.NewReader(raw)) + dec.DisallowUnknownFields() + if err := dec.Decode(&v); err != nil { + return v, err + } + if dec.More() { + return v, errors.New("text after the value") + } + return v, nil +} + // QueueByQueueNextKey is the key of one value of the state queue under the form "queue.next". func QueueByQueueNextKey() string { return "queue.next" } @@ -511,7 +547,9 @@ type Mover struct { Fingerprint string `json:"fingerprint"` Module string `json:"module"` // yes when the module is over its test budget (design 47 G section 419) - OverBudget bool `json:"over-budget,omitempty"` + OverBudget bool `json:"over-budget,omitempty"` + // the artifact references, :, of the mover's dependencies whose package-published (and, for a kind-3 edge, whose build step's passed end) was heard at the pipeline's branch and source, written with the pipeline by compare-and-set; absent when none (H-A-84) + Published []string `json:"published,omitempty"` Repository string `json:"repository"` Tests *TestCounts `json:"tests,omitempty"` // the mover's tier in the pipeline's delivery order, from 1 (ADR 0666 section 14; design 47 H §746) @@ -546,7 +584,7 @@ type Pipeline struct { // the modules the pipeline moves, its take-in's entries (design 47 H §746) Movers []Mover `json:"movers"` Outcome string `json:"outcome"` - // the pipeline's key, ., or ..published.. for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747) + // the pipeline's key, ., ..published.. for a pipeline a publish started, or .run. for a run on request; a branch escaped as a key's name is (design 47 H §746, §747; H-A-83) Pipeline string `json:"pipeline"` // for a pipeline a package's publish started, that publish (A-202) Published *Published `json:"published,omitempty"` @@ -1212,6 +1250,9 @@ type PipelinesByBranchSourceValue = Pipeline // PipelinesByBranchSourcePublishedPackageVersionValue is one value of the state pipelines under the key ..published... type PipelinesByBranchSourcePublishedPackageVersionValue = Pipeline +// PipelinesByBranchRunRunValue is one value of the state pipelines under the key .run.. +type PipelinesByBranchRunRunValue = Pipeline + // QueueByQueueNextValue is one value of the state queue under the key queue.next. type QueueByQueueNextValue = int64 diff --git a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract_test.go b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract_test.go index d00cc41c..d4d39dba 100644 --- a/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner/contract_test.go @@ -71,6 +71,12 @@ func TestFixtures(t *testing.T) { err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, + {name: "a run on request's pipeline, its mover waiting with one dependency's publish heard", subject: "", given: "{\"branch\":\"feat-x\",\"end-count\":1,\"ended\":\"2026-11-10T10:20:00Z\",\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"published\":[\"mesh-sdk:go\"],\"repository\":\"mesh-networking\",\"tier\":1}],\"outcome\":\"passed\",\"pipeline\":\"feat-x.run.r42\",\"revision\":12,\"run\":\"r42\",\"source\":3589,\"started\":\"2026-11-10T10:00:00Z\",\"steps\":[{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5e\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"node\":\"anchor\",\"outcome\":\"passed\",\"seat\":\"node-build-go\",\"status\":\"required\",\"step\":\"lint\"},{\"artifact\":\"nats:program\",\"carried-from\":\"main.3588\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"outcome\":\"carried\",\"status\":\"required\",\"step\":\"unit\",\"tests\":{\"unit\":42}},{\"artifact\":\"nats:program\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"failed\",\"seat\":\"node-build-go\",\"status\":\"optional\",\"step\":\"integration\",\"tests\":{\"integration\":3},\"why\":\"TestTheBusWhole failed\"},{\"module\":\"nats\",\"outcome\":\"passed\",\"seat\":\"mesh-wants\",\"status\":\"required\",\"step\":\"composition\"},{\"module\":\"nats\",\"outcome\":\"bypassed\",\"status\":\"bypass\",\"step\":\"review\"},{\"module\":\"nats\",\"outcome\":\"passed\",\"status\":\"required\",\"step\":\"approval\"}],\"v\":1}", wire: "{\"branch\":\"feat-x\",\"end-count\":1,\"ended\":\"2026-11-10T10:20:00Z\",\"movers\":[{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"published\":[\"mesh-sdk:go\"],\"repository\":\"mesh-networking\",\"tier\":1}],\"outcome\":\"passed\",\"pipeline\":\"feat-x.run.r42\",\"revision\":12,\"run\":\"r42\",\"source\":3589,\"started\":\"2026-11-10T10:00:00Z\",\"steps\":[{\"artifact\":\"nats:program\",\"ask\":\"m2kx9a1b3c4d5e\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"node\":\"anchor\",\"outcome\":\"passed\",\"seat\":\"node-build-go\",\"status\":\"required\",\"step\":\"lint\"},{\"artifact\":\"nats:program\",\"carried-from\":\"main.3588\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"outcome\":\"carried\",\"status\":\"required\",\"step\":\"unit\",\"tests\":{\"unit\":42}},{\"artifact\":\"nats:program\",\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"node\":\"home-server\",\"outcome\":\"failed\",\"seat\":\"node-build-go\",\"status\":\"optional\",\"step\":\"integration\",\"tests\":{\"integration\":3},\"why\":\"TestTheBusWhole failed\"},{\"module\":\"nats\",\"outcome\":\"passed\",\"seat\":\"mesh-wants\",\"status\":\"required\",\"step\":\"composition\"},{\"module\":\"nats\",\"outcome\":\"bypassed\",\"status\":\"bypass\",\"step\":\"review\"},{\"module\":\"nats\",\"outcome\":\"passed\",\"status\":\"required\",\"step\":\"approval\"}],\"v\":1}", + decode: func(b []byte) (any, error) { + var v PipelinesByBranchRunRunValue + err := json.Unmarshal(b, &v) + return v, err + }, subjectIs: nil}, {name: "run asks one member at a commit", subject: "", given: "{\"members\":[{\"branch\":\"feature/1966-x\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"module\":\"nats\"}]}", wire: "{\"members\":[{\"branch\":\"feature/1966-x\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"module\":\"nats\"}]}", decode: func(b []byte) (any, error) { var v RunInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "run answers its id and pipelines", subject: "", given: "{\"pipelines\":[\"feature~2f1966-x.0.nats\"],\"run\":\"run-m2kx9a\"}", wire: "{\"pipelines\":[\"feature~2f1966-x.0.nats\"],\"run\":\"run-m2kx9a\"}", diff --git a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/states.json b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/states.json index 4fc96cdc..18285de8 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/states.json +++ b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/fixtures/states.json @@ -214,5 +214,91 @@ } ] } + }, + { + "name": "a run on request's pipeline, its mover waiting with one dependency's publish heard", + "of": "state:pipelines/.run.", + "given": { + "pipeline": "feat-x.run.r42", + "branch": "feat-x", + "revision": 12, + "source": 3589, + "end-count": 1, + "v": 1, + "outcome": "passed", + "steps": [ + { + "step": "lint", + "artifact": "nats:program", + "status": "required", + "outcome": "passed", + "fingerprint": "fp-0123", + "seat": "node-build-go", + "node": "anchor", + "ask": "m2kx9a1b3c4d5e", + "module": "nats" + }, + { + "step": "unit", + "artifact": "nats:program", + "status": "required", + "outcome": "carried", + "fingerprint": "fp-0123", + "carried-from": "main.3588", + "tests": { + "unit": 42 + }, + "module": "nats" + }, + { + "step": "integration", + "artifact": "nats:program", + "status": "optional", + "outcome": "failed", + "why": "TestTheBusWhole failed", + "fingerprint": "fp-0123", + "seat": "node-build-go", + "node": "home-server", + "tests": { + "integration": 3 + }, + "module": "nats" + }, + { + "step": "composition", + "status": "required", + "outcome": "passed", + "seat": "mesh-wants", + "module": "nats" + }, + { + "step": "review", + "status": "bypass", + "outcome": "bypassed", + "module": "nats" + }, + { + "step": "approval", + "status": "required", + "outcome": "passed", + "module": "nats" + } + ], + "started": "2026-11-10T10:00:00Z", + "ended": "2026-11-10T10:20:00Z", + "movers": [ + { + "module": "nats", + "commit": "0123456789abcdef0123456789abcdef01234567", + "fingerprint": "fp-0123", + "repository": "mesh-networking", + "tier": 1, + "published": [ + "mesh-sdk:go" + ] + } + ], + "run": "r42" + } } ] diff --git a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json index cac7dd36..68879ae5 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json +++ b/modules/mesh-delivery-contracts/seats/mesh-pipeline-runner/seat.json @@ -741,6 +741,13 @@ "$ref": "#/defs/Pipeline" }, "description": "a pipeline a package's publish started, its movers the package's kind-1 dependents the publishing pipeline does not move" + }, + { + "key": ".run.", + "value": { + "$ref": "#/defs/Pipeline" + }, + "description": "a run on request's pipeline, one per run, its movers the named commits' modules; it delivers nothing (H-A-83)" } ] }, @@ -1101,7 +1108,7 @@ "properties": { "pipeline": { "type": "string", - "description": "the pipeline's key, ., or ..published.. for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)" + "description": "the pipeline's key, ., ..published.. for a pipeline a publish started, or .run. for a run on request; a branch escaped as a key's name is (design 47 H §746, §747; H-A-83)" }, "branch": { "type": "string", @@ -1781,6 +1788,13 @@ "type": "string", "description": "the version released for the mover in this pipeline (version-released), absent until one is (design 47 H-A-52)" }, + "published": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the artifact references, :, of the mover's dependencies whose package-published (and, for a kind-3 edge, whose build step's passed end) was heard at the pipeline's branch and source, written with the pipeline by compare-and-set; absent when none (H-A-84)" + }, "widens": { "type": "array", "items": { diff --git a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts index 316dcf10..ec8bf096 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.d.ts @@ -105,6 +105,12 @@ export declare function pipelinesByBranchSourcePublishedPackageVersionKey(branch /** The parts of a key of the form "..published..", or undefined for a key of another form. */ export declare function parsePipelinesByBranchSourcePublishedPackageVersionKey(_key: string): { branch: string; source: string; packagePart: string; version: string } | undefined; +/** The key of one value of the state pipelines under the form ".run.". */ +export declare function pipelinesByBranchRunRunKey(branch: string, run: string): string; + +/** The parts of a key of the form ".run.", or undefined for a key of another form. */ +export declare function parsePipelinesByBranchRunRunKey(_key: string): { branch: string; run: string } | undefined; + /** The key of one value of the state queue under the form "queue.next". */ export declare function queueByQueueNextKey(): string; @@ -198,6 +204,8 @@ export interface Mover { "module": string; /** yes when the module is over its test budget (design 47 G section 419) */ "over-budget"?: boolean; + /** the artifact references, :, of the mover's dependencies whose package-published (and, for a kind-3 edge, whose build step's passed end) was heard at the pipeline's branch and source, written with the pipeline by compare-and-set; absent when none (H-A-84) */ + "published"?: string[]; "repository": string; "tests"?: TestCounts; /** the mover's tier in the pipeline's delivery order, from 1 (ADR 0666 section 14; design 47 H §746) */ @@ -232,7 +240,7 @@ export interface Pipeline { /** the modules the pipeline moves, its take-in's entries (design 47 H §746) */ "movers": Mover[]; "outcome": "waiting" | "running" | "passed" | "failed" | "refused" | "superseded" | "cancelled"; - /** the pipeline's key, ., or ..published.. for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747) */ + /** the pipeline's key, ., ..published.. for a pipeline a publish started, or .run. for a run on request; a branch escaped as a key's name is (design 47 H §746, §747; H-A-83) */ "pipeline": string; /** for a pipeline a package's publish started, that publish (A-202) */ "published"?: Published; @@ -752,6 +760,9 @@ export type PipelinesByBranchSourceValue = Pipeline; /** is one value of the state pipelines under the key ..published... */ export type PipelinesByBranchSourcePublishedPackageVersionValue = Pipeline; +/** is one value of the state pipelines under the key .run.. */ +export type PipelinesByBranchRunRunValue = Pipeline; + /** is one value of the state queue under the key queue.next. */ export type QueueByQueueNextValue = number; diff --git a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.js b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.js index 935bf4c9..e8e03364 100644 --- a/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.js +++ b/modules/mesh-delivery-contracts/ts/seats/meshpipelinerunner/index.js @@ -153,6 +153,25 @@ export function parsePipelinesByBranchSourcePublishedPackageVersionKey(_key) { return { branch, source, packagePart, version }; } +/** The key of one value of the state pipelines under the form ".run.". */ +export function pipelinesByBranchRunRunKey(branch, run) { + return branch + ".run." + run; +} + +/** The parts of a key of the form ".run.", or undefined for a key of another form. */ +export function parsePipelinesByBranchRunRunKey(_key) { + let _rest = _key; + const _at0 = _rest.indexOf(".run."); + if (_at0 <= 0) return undefined; + const branch = _rest.slice(0, _at0); + _rest = _rest.slice(_at0 + 5); + if (_rest === "") return undefined; + const run = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { branch, run }; +} + /** The key of one value of the state queue under the form "queue.next". */ export function queueByQueueNextKey() { return "queue.next";