From 87e9084e15a3a6121080420c4c94c2fd1f7ce06e Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 20 Nov 2026 03:21:43 +0100 Subject: [PATCH] C-R2: the runner's pipelines key a run on request; a mover keeps its heard publishes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The seat mesh-pipeline-runner's state pipelines gains the key form .run., one pipeline per run on request, its movers the named commits' modules (it delivers nothing). Its Mover gains published, the artifact references whose package-published (or, on a kind-3 edge, whose build step's passed end) the runner heard at the pipeline's branch and source, kept with the pipeline so a dependency's wait survives a restart. A fixture of the new key form with a mover naming one heard publish proves both. Builds: design 47 H §746; lead answers H-A-83 (1) (hq ae7fc40a), H-A-84 (hq main 0631f43f+) Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy --- .../go/seats/meshpipelinerunner/contract.go | 45 +++++++++- .../seats/meshpipelinerunner/contract_test.go | 6 ++ .../mesh-pipeline-runner/fixtures/states.json | 86 +++++++++++++++++++ .../seats/mesh-pipeline-runner/seat.json | 16 +++- .../ts/seats/meshpipelinerunner/index.d.ts | 13 ++- .../ts/seats/meshpipelinerunner/index.js | 19 ++++ 6 files changed, 181 insertions(+), 4 deletions(-) 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";