From 830e265bd06343dd5e78b82ca511605c9f8366fc Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 5 Nov 2026 14:34:05 +0100 Subject: [PATCH] =?UTF-8?q?mesh-delivery-contracts:=20mesh-catalog=20serve?= =?UTF-8?q?s=20the=20verb=20seat-definitions;=20every=20definition=20names?= =?UTF-8?q?=20its=20glossary=20domain,=20Delivery=20(ADR=200636=20=C2=A71,?= =?UTF-8?q?=20=C2=A75;=20issue=201966)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- contracts/go/seats/meshcatalog/contract.go | 46 +++++++++-- .../seats/container-image-registry/seat.json | 1 + contracts/seats/git/seat.json | 1 + contracts/seats/go-package-registry/seat.json | 1 + contracts/seats/mesh-artifact-store/seat.json | 1 + contracts/seats/mesh-artifact-sweep/seat.json | 1 + contracts/seats/mesh-catalog/seat.json | 81 +++++++++++++++++++ .../seats/mesh-delivery-checker/seat.json | 1 + contracts/seats/mesh-delivery/seat.json | 1 + contracts/seats/node-build-go/seat.json | 1 + contracts/seats/node-build-image/seat.json | 1 + contracts/seats/node-build-node/seat.json | 1 + .../seats/npm-package-registry/seat.json | 1 + .../seats/oci-artifact-registry/seat.json | 1 + contracts/ts/seats/meshcatalog/src/index.ts | 34 ++++++++ 15 files changed, 168 insertions(+), 5 deletions(-) diff --git a/contracts/go/seats/meshcatalog/contract.go b/contracts/go/seats/meshcatalog/contract.go index aeecc413..243a0d33 100644 --- a/contracts/go/seats/meshcatalog/contract.go +++ b/contracts/go/seats/meshcatalog/contract.go @@ -14,10 +14,11 @@ import ( const Seat = "mesh-catalog" const ( - VerbModules = "modules" - VerbModule = "module" - VerbProvides = "provides" - VerbDependents = "dependents" + VerbModules = "modules" + VerbModule = "module" + VerbProvides = "provides" + VerbDependents = "dependents" + VerbSeatDefinitions = "seat-definitions" ) const ( @@ -27,7 +28,7 @@ const ( // Verbs is every verb the seat serves, in its definition's order: a new copy each call. func Verbs() []string { - return []string{VerbModules, VerbModule, VerbProvides, VerbDependents} + return []string{VerbModules, VerbModule, VerbProvides, VerbDependents, VerbSeatDefinitions} } // Events is every event published on the seat's subject: a new copy each call. @@ -343,6 +344,41 @@ type DependentsInput struct { // DependentsAnswer is what dependents answers. type DependentsAnswer = map[string]any +// SeatDefinitionsInput is what seat-definitions takes. +type SeatDefinitionsInput struct { + // the seat's name; none lists every trunk seat + Seat string `json:"seat,omitempty"` +} + +// SeatDefinitionsAnswerEntry is a type of the contract. +type SeatDefinitionsAnswerEntry struct { + // the definition, resolved with the parts it includes + Definition map[string]any `json:"definition,omitempty"` + Digest string `json:"digest"` + Seat string `json:"seat"` + // trunk + Source string `json:"source"` + // why the definition could not be read, when it could not + Unparsed string `json:"unparsed,omitempty"` +} + +// SeatDefinitionsAnswerSeatsItem is a type of the contract. +type SeatDefinitionsAnswerSeatsItem struct { + Digest string `json:"digest"` + Seat string `json:"seat"` + // trunk + Source string `json:"source"` +} + +// SeatDefinitionsAnswer is what seat-definitions answers. +type SeatDefinitionsAnswer struct { + Entry *SeatDefinitionsAnswerEntry `json:"entry,omitempty"` + Found bool `json:"found,omitempty"` + Revision int64 `json:"revision,omitempty"` + Seat string `json:"seat,omitempty"` + Seats []SeatDefinitionsAnswerSeatsItem `json:"seats,omitempty"` +} + // SeatDefinitionChangedEvent is the body of the event seat-definition-changed. type SeatDefinitionChangedEvent struct { Digest string `json:"digest"` diff --git a/contracts/seats/container-image-registry/seat.json b/contracts/seats/container-image-registry/seat.json index 9f95f1e4..bc116b4b 100644 --- a/contracts/seats/container-image-registry/seat.json +++ b/contracts/seats/container-image-registry/seat.json @@ -3,6 +3,7 @@ "seat": "container-image-registry", "scope": "mesh", "grain": "whole", + "domain": "Delivery", "decision": "novox/hq ADR 0605", "description": "The mesh's container images, in the one artifact store: the OCI distribution protocol's read side, an image's tags and mirroring an outside image.", "includes": [ diff --git a/contracts/seats/git/seat.json b/contracts/seats/git/seat.json index 836285ab..b7c55a10 100644 --- a/contracts/seats/git/seat.json +++ b/contracts/seats/git/seat.json @@ -3,6 +3,7 @@ "seat": "git", "scope": "mesh", "grain": "seat-list", + "domain": "Delivery", "decision": "novox/hq ADR 0111", "delivers": "git" } diff --git a/contracts/seats/go-package-registry/seat.json b/contracts/seats/go-package-registry/seat.json index edf39986..9d426368 100644 --- a/contracts/seats/go-package-registry/seat.json +++ b/contracts/seats/go-package-registry/seat.json @@ -3,6 +3,7 @@ "seat": "go-package-registry", "scope": "mesh", "grain": "whole", + "domain": "Delivery", "decision": "novox/hq ADR 0605", "description": "The mesh's Go modules: Go's module proxy protocol's read side, and publishing over the bus.", "delivers": "go-package-registry", diff --git a/contracts/seats/mesh-artifact-store/seat.json b/contracts/seats/mesh-artifact-store/seat.json index 84c8a57e..d82ab333 100644 --- a/contracts/seats/mesh-artifact-store/seat.json +++ b/contracts/seats/mesh-artifact-store/seat.json @@ -3,5 +3,6 @@ "seat": "mesh-artifact-store", "scope": "mesh", "grain": "seat-list", + "domain": "Delivery", "decision": "novox/hq ADR 0075" } diff --git a/contracts/seats/mesh-artifact-sweep/seat.json b/contracts/seats/mesh-artifact-sweep/seat.json index 602a5f8d..2e5b673d 100644 --- a/contracts/seats/mesh-artifact-sweep/seat.json +++ b/contracts/seats/mesh-artifact-sweep/seat.json @@ -3,6 +3,7 @@ "seat": "mesh-artifact-sweep", "scope": "mesh", "grain": "seat-list", + "domain": "Delivery", "decision": "novox/hq ADR 0571", "verbs": [ { diff --git a/contracts/seats/mesh-catalog/seat.json b/contracts/seats/mesh-catalog/seat.json index 92a8307e..d036149a 100644 --- a/contracts/seats/mesh-catalog/seat.json +++ b/contracts/seats/mesh-catalog/seat.json @@ -3,6 +3,7 @@ "seat": "mesh-catalog", "scope": "mesh", "grain": "whole", + "domain": "Delivery", "decision": "novox/hq ADR 0604", "verbs": [ { @@ -80,6 +81,86 @@ "type": "object", "description": "what dependents answers, as its description says" } + }, + { + "name": "seat-definitions", + "description": "The seat list (ADR 0636 §4): with no seat, every trunk seat with its digest and the revision of the list; with a seat, that trunk definition resolved with the parts it includes. Reads only.", + "optional": true, + "input": { + "properties": { + "seat": { + "description": "the seat's name; none lists every trunk seat", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "type": "object", + "description": "with no seat: the revision of the list and every trunk seat with its digest; with a seat: whether it was found and its entry, the definition resolved", + "properties": { + "revision": { + "type": "integer" + }, + "seats": { + "type": "array", + "items": { + "type": "object", + "properties": { + "seat": { + "type": "string" + }, + "source": { + "type": "string", + "description": "trunk" + }, + "digest": { + "type": "string" + } + }, + "required": [ + "seat", + "source", + "digest" + ] + } + }, + "seat": { + "type": "string" + }, + "found": { + "type": "boolean" + }, + "entry": { + "type": "object", + "properties": { + "seat": { + "type": "string" + }, + "source": { + "type": "string", + "description": "trunk" + }, + "digest": { + "type": "string" + }, + "definition": { + "type": "object", + "description": "the definition, resolved with the parts it includes" + }, + "unparsed": { + "type": "string", + "description": "why the definition could not be read, when it could not" + } + }, + "required": [ + "seat", + "source", + "digest" + ] + } + } + } } ], "description": "The catalog of the mesh: every module the trunk holds with its manifest, fingerprint and verdict, the packages published, and the seat list (ADR 0636 §1, §4).", diff --git a/contracts/seats/mesh-delivery-checker/seat.json b/contracts/seats/mesh-delivery-checker/seat.json index 2aaba6bf..0a9220d3 100644 --- a/contracts/seats/mesh-delivery-checker/seat.json +++ b/contracts/seats/mesh-delivery-checker/seat.json @@ -3,6 +3,7 @@ "seat": "mesh-delivery-checker", "scope": "mesh", "grain": "whole", + "domain": "Delivery", "decision": "novox/hq ADR 0547", "verbs": [ { diff --git a/contracts/seats/mesh-delivery/seat.json b/contracts/seats/mesh-delivery/seat.json index bc08d0ff..8365118a 100644 --- a/contracts/seats/mesh-delivery/seat.json +++ b/contracts/seats/mesh-delivery/seat.json @@ -3,6 +3,7 @@ "seat": "mesh-delivery", "scope": "mesh", "grain": "whole", + "domain": "Delivery", "decision": "novox/hq ADR 0239", "verbs": [ { diff --git a/contracts/seats/node-build-go/seat.json b/contracts/seats/node-build-go/seat.json index ff273bdb..a810a6bb 100644 --- a/contracts/seats/node-build-go/seat.json +++ b/contracts/seats/node-build-go/seat.json @@ -3,6 +3,7 @@ "seat": "node-build-go", "scope": "node", "grain": "whole", + "domain": "Delivery", "decision": "novox/hq ADR 0525, ADR 0536, ADR 0553", "pulled-by-kind": true, "yields": true, diff --git a/contracts/seats/node-build-image/seat.json b/contracts/seats/node-build-image/seat.json index f0ca605b..037a8907 100644 --- a/contracts/seats/node-build-image/seat.json +++ b/contracts/seats/node-build-image/seat.json @@ -3,6 +3,7 @@ "seat": "node-build-image", "scope": "node", "grain": "whole", + "domain": "Delivery", "decision": "novox/hq ADR 0525, ADR 0536, ADR 0553", "pulled-by-kind": true, "yields": true, diff --git a/contracts/seats/node-build-node/seat.json b/contracts/seats/node-build-node/seat.json index 34ee7310..6fce1468 100644 --- a/contracts/seats/node-build-node/seat.json +++ b/contracts/seats/node-build-node/seat.json @@ -3,6 +3,7 @@ "seat": "node-build-node", "scope": "node", "grain": "whole", + "domain": "Delivery", "decision": "novox/hq ADR 0525, ADR 0536, ADR 0553", "pulled-by-kind": true, "yields": true, diff --git a/contracts/seats/npm-package-registry/seat.json b/contracts/seats/npm-package-registry/seat.json index 61f77c32..ae2ab3db 100644 --- a/contracts/seats/npm-package-registry/seat.json +++ b/contracts/seats/npm-package-registry/seat.json @@ -3,6 +3,7 @@ "seat": "npm-package-registry", "scope": "mesh", "grain": "whole", + "domain": "Delivery", "decision": "novox/hq ADR 0109", "description": "The mesh's npm packages: the npm registry protocol's read side, and publishing over the bus.", "delivers": "npm-package-registry", diff --git a/contracts/seats/oci-artifact-registry/seat.json b/contracts/seats/oci-artifact-registry/seat.json index ae30e92c..ee6f5bf7 100644 --- a/contracts/seats/oci-artifact-registry/seat.json +++ b/contracts/seats/oci-artifact-registry/seat.json @@ -3,6 +3,7 @@ "seat": "oci-artifact-registry", "scope": "mesh", "grain": "whole", + "domain": "Delivery", "decision": "novox/hq ADR 0605", "description": "The mesh's bundles and archives, by digest, in the one artifact store: the OCI distribution protocol's read side.", "includes": [ diff --git a/contracts/ts/seats/meshcatalog/src/index.ts b/contracts/ts/seats/meshcatalog/src/index.ts index 10a89abb..91fdcf23 100644 --- a/contracts/ts/seats/meshcatalog/src/index.ts +++ b/contracts/ts/seats/meshcatalog/src/index.ts @@ -9,6 +9,7 @@ export const verbs = { module: "module", provides: "provides", dependents: "dependents", + seatDefinitions: "seat-definitions", } as const; export const events = { @@ -189,6 +190,39 @@ export interface DependentsInput { /** is what dependents answers. */ export type DependentsAnswer = Record; +/** is what seat-definitions takes. */ +export interface SeatDefinitionsInput { + /** the seat's name; none lists every trunk seat */ + "seat"?: string; +} + +export interface SeatDefinitionsAnswerEntry { + /** the definition, resolved with the parts it includes */ + "definition"?: Record; + "digest": string; + "seat": string; + /** trunk */ + "source": string; + /** why the definition could not be read, when it could not */ + "unparsed"?: string; +} + +export interface SeatDefinitionsAnswerSeatsItem { + "digest": string; + "seat": string; + /** trunk */ + "source": string; +} + +/** is what seat-definitions answers. */ +export interface SeatDefinitionsAnswer { + "entry"?: SeatDefinitionsAnswerEntry; + "found"?: boolean; + "revision"?: number; + "seat"?: string; + "seats"?: SeatDefinitionsAnswerSeatsItem[]; +} + /** is the body of the event seat-definition-changed. */ export interface SeatDefinitionChangedEvent { "digest": string;