Files
mesh-delivery/contracts/seats/mesh-builds/seat.json
T
jschoubben 009c4c6e73 A-97: the seat mesh-builds accepts the build step and says its end
The accepted kind step (body StepRun: the pipeline, the branch, the source revision and each entry by module and
fingerprint) and the event step-ended.<node> (StepEnded: the same entries, the outcome), as mesh-wants has for its
composition step.

Builds: design 47 G A-97 (§230, §194, §473)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-12 00:04:41 +01:00

408 lines
12 KiB
JSON

{
"format": 1,
"seat": "mesh-builds",
"scope": "mesh",
"grain": "whole",
"domain": "Delivery",
"decision": "novox/hq ADR 0666",
"description": "The builder's seat: it says each artifact it published and each agreed toolchain, and answers a module's reserved version. Held once for the mesh (design 47 G section 52, section 307).",
"verbs": [
{
"name": "reserved",
"class": "read",
"callers": [
"seat:go-package-registry",
"seat:npm-package-registry",
"seat:container-image-registry",
"seat:oci-artifact-registry"
],
"description": "A module's reserved version with each artifact's digest, for a registry holder deciding whether to publish; asked by the module or by a package's name in its ecosystem (design 47 G section 369, section 478; design 51, Publishing).",
"input": {
"type": "object",
"properties": {
"module": {
"type": "string",
"description": "the module; give this or name"
},
"name": {
"type": "string",
"description": "a package's or an image's name in its ecosystem (the Go module path, the npm name, the image name), in place of module; a name no entry carries, or more than one entry carries, is answered error naming it (design 47 G section 478, section 491)"
},
"version": {
"type": "string",
"description": "the version, when asked for a particular one"
}
},
"required": []
},
"answer": {
"type": "object",
"properties": {
"module": {
"type": "string",
"description": "the module"
},
"version": {
"type": "string",
"description": "the reserved version, MAJOR.MINOR.PATCH"
},
"artifacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"artifact": {
"type": "string",
"description": "the artifact reference, <module>:<artifact>"
},
"digest": {
"type": "string",
"description": "its digest once built; empty before"
}
},
"required": [
"artifact"
]
}
},
"released": {
"type": "boolean",
"description": "true when the version is released: the catalog holds it, and artifacts are the ones its release recorded with their digests; false when it is reserved (design 47 G 582, 679)"
},
"error": {
"type": "string",
"description": "a name no entry carries, or a version neither reserved nor released, naming which; set alone (design 47 G 582, 679)"
}
},
"description": "the reservation or release, or the error; module, version and artifacts are present whenever error is not (design 47 G 679)"
}
}
],
"accepts": [
{
"name": "step",
"body": {
"$ref": "#/defs/StepRun"
},
"callers": [
"seat:mesh-pipeline-runner"
]
}
],
"events": [
{
"name": "package-published",
"keep": {
"max-age-days": 90,
"max-mib": 128
},
"body": {
"$ref": "#/defs/PackagePublished"
}
},
{
"name": "toolchain-agreed",
"keep": {
"max-age-days": 90,
"max-mib": 16
},
"body": {
"$ref": "#/defs/ToolchainAgreed"
}
},
{
"name": "step-ended",
"subject": "step-ended.<node>",
"body": {
"$ref": "#/defs/StepEnded"
},
"keep": {
"max-age-days": 90,
"max-mib": 32
}
}
],
"family": {
"name": "mesh-builds.events",
"max-age-days": 7
},
"defs": {
"Dependency": {
"type": "object",
"properties": {
"part": {
"type": "string",
"description": "the dependency's part: for kind 1 the package's artifact reference, <module>:<artifact>; for kind 3 the agreed toolchain's part (design 47 G 466, 673)"
},
"kind": {
"type": "integer",
"enum": [
1,
3
],
"description": "1 an imported package, 3 the build toolchain (design 47 G section 374)"
},
"version": {
"type": "string",
"description": "the version of the dependency the build resolved"
},
"digest": {
"type": "string",
"description": "the digest of the part, as the build used it"
}
},
"required": [
"part",
"kind",
"version",
"digest"
],
"description": "a dependency the build resolved: one item of kind 1 for each resolved package and one of kind 3 for the toolchain, named by the build module in its step key and carried by the builder (design 47 G 374, 673)"
},
"PackagePublished": {
"type": "object",
"properties": {
"v": {
"type": "integer"
},
"artifact": {
"type": "string",
"description": "the package's artifact reference, <module>:<artifact>, from the catalog entry"
},
"module": {
"type": "string",
"description": "the module"
},
"version": {
"type": "string",
"description": "the version the build reserved, MAJOR.MINOR.PATCH"
},
"digest": {
"type": "string",
"description": "the published artifact's digest"
},
"branch": {
"type": "string",
"description": "the watched branch the build was made from"
},
"source": {
"type": "integer",
"description": "the source revision of that branch the build was made from"
},
"dependencies": {
"type": "array",
"items": {
"$ref": "#/defs/Dependency"
},
"description": "each dependency the build resolved, with its version and digest"
},
"at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"v",
"artifact",
"module",
"version",
"digest",
"branch",
"source"
],
"description": "one artifact published at the module's reserved version (design 47 G section 52, section 334)"
},
"ToolchainAgreed": {
"type": "object",
"properties": {
"v": {
"type": "integer"
},
"language": {
"type": "string",
"description": "the language whose agreed toolchain changed"
},
"version": {
"type": "string",
"description": "the agreed toolchain's version"
},
"digests": {
"type": "array",
"description": "each digest the nodes reporting the agreed version report, as it stood when the version was agreed, with those nodes (design 47 G section 472, section 495)",
"items": {
"type": "object",
"properties": {
"digest": {
"type": "string",
"description": "the toolchain part's digest"
},
"nodes": {
"type": "array",
"items": {
"type": "string"
},
"description": "the nodes reporting that digest"
}
},
"required": [
"digest",
"nodes"
]
}
},
"at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"v",
"language",
"version",
"digests"
],
"description": "the agreed toolchain of a language changed (design 47 G section 376, ADR 0584 section 1)"
},
"StepRun": {
"type": "object",
"description": "the build step of one module's pipeline (design 47 G section 230, A-97): the runner asks the seat mesh-builds to build a candidate's entries, each named by its fingerprint, and the builder, the one entry point for a candidate, takes the ask and answers the step's end",
"properties": {
"pipeline": {
"type": "string",
"description": "the runner's pipeline key, <branch>.<revision>.<module>, a branch escaped as a key's name is"
},
"step": {
"type": "string",
"enum": [
"build"
]
},
"branch": {
"type": "string",
"description": "the watched branch, or the branch of a run on request"
},
"revision": {
"type": "integer",
"description": "the catalog graph revision of the branch the pipeline runs for"
},
"source": {
"type": "integer",
"description": "the source revision of the watched branch; absent for a run on request"
},
"rerun": {
"type": "boolean",
"description": "the step is asked again by the runner's rerun"
},
"by": {
"type": "string",
"description": "for a rerun, the caller the runtime proved"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/defs/BuildEntry"
},
"description": "each entry the candidate's build builds, by module and fingerprint"
}
},
"required": [
"pipeline",
"step",
"branch",
"entries"
]
},
"StepEnded": {
"type": "object",
"description": "the build step's end, said by the builder on the node it runs on (design 47 G A-97; ADR 0666 section 21): the runner takes it only from that holder's account, naming the ask and each entry's fingerprint it was asked at",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"id": {
"type": "string",
"description": "the ask's id"
},
"pipeline": {
"type": "string"
},
"step": {
"type": "string",
"enum": [
"build"
]
},
"node": {
"type": "string",
"description": "the node the builder ran it on, as in the subject"
},
"outcome": {
"type": "string",
"enum": [
"passed",
"failed",
"nothing to run",
"could not run"
],
"description": "never passed for a build that built nothing"
},
"said": {
"type": "string",
"description": "why it failed or could not run: the entry not built, the part not heard"
},
"rerun": {
"type": "boolean"
},
"by": {
"type": "string",
"description": "for a rerun, the caller the runtime proved"
},
"started": {
"type": "string",
"format": "date-time"
},
"ended": {
"type": "string",
"format": "date-time"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/defs/BuildEntry"
},
"description": "each entry the step built, by module and fingerprint"
}
},
"required": [
"id",
"pipeline",
"step",
"node",
"outcome",
"entries"
]
},
"BuildEntry": {
"type": "object",
"description": "one entry a candidate's build builds: a module at the fingerprint of its build inputs, and the commit that fingerprint was read at",
"properties": {
"module": {
"type": "string"
},
"commit": {
"type": "string"
},
"fingerprint": {
"type": "string",
"description": "the module's build-input fingerprint at the commit"
}
},
"required": [
"module",
"fingerprint"
]
}
}
}