mesh-delivery-contracts: mesh-catalog serves the verb seat-definitions; every definition names its glossary domain, Delivery (ADR 0636 §1, §5; issue 1966)

2026-11-05 14:34:05 +01:00
parent cf9c736061
commit 830e265bd0
15 changed files with 168 additions and 5 deletions
@@ -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"`
@@ -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": [
@@ -3,6 +3,7 @@
  "seat": "git",
  "scope": "mesh",
  "grain": "seat-list",
+  "domain": "Delivery",
  "decision": "novox/hq ADR 0111",
  "delivers": "git"
 }
@@ -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",
@@ -3,5 +3,6 @@
  "seat": "mesh-artifact-store",
  "scope": "mesh",
  "grain": "seat-list",
+  "domain": "Delivery",
  "decision": "novox/hq ADR 0075"
 }
@@ -3,6 +3,7 @@
  "seat": "mesh-artifact-sweep",
  "scope": "mesh",
  "grain": "seat-list",
+  "domain": "Delivery",
  "decision": "novox/hq ADR 0571",
  "verbs": [
    {
@@ -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).",
@@ -3,6 +3,7 @@
  "seat": "mesh-delivery-checker",
  "scope": "mesh",
  "grain": "whole",
+  "domain": "Delivery",
  "decision": "novox/hq ADR 0547",
  "verbs": [
    {
@@ -3,6 +3,7 @@
  "seat": "mesh-delivery",
  "scope": "mesh",
  "grain": "whole",
+  "domain": "Delivery",
  "decision": "novox/hq ADR 0239",
  "verbs": [
    {
@@ -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,
@@ -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,
@@ -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,
@@ -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",
@@ -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": [
@@ -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<string, unknown>;

+/** 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<string, unknown>;
+  "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;