Files
mesh-sdk/go/seatlist/bootstrap/mesh-delivery.json
T
2026-11-20 02:50:53 +01:00

686 lines
20 KiB
JSON

{
"format": 1,
"seat": "mesh-delivery",
"scope": "mesh",
"grain": "whole",
"domain": "Delivery",
"decision": "novox/hq ADR 0239",
"description": "The delivery gate: reads and steers deliveries, merges and the checks that decide them; the merge is made on the operator's Approve once both checks passed.",
"verbs": [
{
"name": "deliveries",
"description": "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group.",
"input": {
"properties": {
"all": {
"description": "\"true\": the final ones of the last thirty days too",
"enum": [
"true",
"false"
],
"type": "string"
},
"group": {
"description": "a group's id (its branch name)",
"type": "string"
},
"repository": {
"description": "owner/repository",
"type": "string"
},
"state": {
"description": "one state, e.g. delivering or held",
"type": "string"
}
},
"type": "object"
},
"answer": {
"type": "object",
"description": "what deliveries answers, as its description says"
},
"class": "read"
},
{
"name": "show",
"description": "One delivery or group whole: its delivery plan (what it builds, what each machine receives, what is not an ordinary send), every transition with when and why, the machine steps of its walk, its group and its order.",
"input": {
"properties": {
"id": {
"description": "a delivery's id, or a group's",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"answer": {
"type": "object",
"description": "what show answers, as its description says"
},
"class": "read"
},
{
"name": "source",
"description": "One watched branch's source revision (design 47 *Watched branches and the catalog graph per branch*: source.<branch> in place of source.main): The source revision the gate holds: every repository it names, its trunk branch and that trunk's head as the gate merged or seeded it, and the merge call that moved it last. Read, never written: the node-engines read it to call a reverted build's catch-up tool once per repository, never the gate's state (design 47). Given no branch it answers branches alone, the branch of each source key the gate keeps; given a branch, that branch's source revision (design 47 G section 690).",
"input": {
"type": "object",
"properties": {
"branch": {
"type": "string",
"description": "the watched branch, escaped as a key name is; absent: the answer is the list of the branches the gate keeps a source revision of (design 47 G section 690)"
}
}
},
"answer": {
"type": "object",
"properties": {
"revision": {
"type": "integer",
"description": "the source revision's number on the bus; 0 before the first"
},
"call": {
"type": "string",
"description": "the merge call that moved the source revision last; absent before the first"
},
"repositories": {
"type": "array",
"items": {
"$ref": "#/defs/SourceHead"
},
"description": "every repository the source revision names, by name"
},
"error": {
"type": "string",
"description": "why it could not be read"
},
"branch": {
"type": "string",
"description": "the watched branch the source revision is of"
},
"branches": {
"type": "array",
"items": {
"type": "string"
},
"description": "given no branch: the branch name of each source.<branch> key the gate keeps, which every reader of the catalog half follows before the first registrations (design 47 G section 614, section 690)"
}
}
},
"class": "read"
},
{
"name": "stalled",
"description": "Every delivery held past its state's bound, with the transition the table lets healer H2 take for it, or none.",
"input": {
"properties": {},
"type": "object"
},
"answer": {
"type": "object",
"description": "what stalled answers, as its description says"
},
"class": "read"
},
{
"name": "recovery",
"class": "act",
"description": "Mark a merge its author names a recovery: the commit and why; the delivery record is marked recovery with the caller the runtime proves, and recovery-merged is said (design 47 G section 305).",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>"
},
"commit": {
"type": "string",
"description": "the merge commit"
},
"why": {
"type": "string",
"description": "why the merge is a recovery"
}
},
"required": [
"repository",
"commit",
"why"
]
},
"answer": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository"
},
"commit": {
"type": "string",
"description": "the merge commit"
},
"recovery": {
"type": "boolean"
},
"by": {
"type": "string",
"description": "the caller the runtime proved"
}
},
"required": [
"commit",
"recovery"
]
}
}
],
"family": {
"name": "mesh-delivery.events",
"max-age-days": 7
},
"events": [
{
"name": "owed",
"subject": "owed.<repository>.<number>",
"keep": {
"max-age-days": 7,
"max-mib": 64
},
"body": {
"$ref": "#/defs/Owed"
}
},
{
"name": "record-opened",
"body": {
"type": "object",
"description": "a delivery record opened for one source revision of a merge call (design 47 H \u00a7737)",
"properties": {
"record": {
"type": "string",
"description": "the record's id"
},
"milestone": {
"type": "string",
"description": "its milestone, <branch>.<source>"
},
"branch": {
"type": "string",
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the source revision"
},
"call": {
"type": "string",
"description": "the merge call"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when"
}
},
"required": [
"record",
"milestone",
"branch",
"source",
"call"
]
},
"subject": "record-opened.<call>"
},
{
"name": "record-ended",
"body": {
"type": "object",
"description": "a delivery record ended: every present node runs its entries",
"properties": {
"record": {
"type": "string",
"description": "the record's id"
},
"milestone": {
"type": "string",
"description": "its milestone, <branch>.<source>"
},
"branch": {
"type": "string",
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the source revision"
},
"call": {
"type": "string",
"description": "the merge call"
},
"away": {
"type": "array",
"items": {
"type": "object",
"properties": {
"node": {
"type": "string",
"description": "a node away"
},
"since": {
"type": "string",
"format": "date-time",
"description": "since when"
}
},
"required": [
"node"
]
},
"description": "the nodes away, each with since when; it ends without them"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when"
}
},
"required": [
"record",
"milestone",
"branch",
"source",
"call"
]
}
},
{
"name": "filling",
"body": {
"$ref": "#/defs/Fill"
}
},
{
"name": "full",
"body": {
"$ref": "#/defs/Fill"
}
},
{
"name": "room",
"body": {
"$ref": "#/defs/Fill"
}
},
{
"name": "source-moved",
"subject": "source-moved.<branch>.<source>",
"body": {
"type": "object",
"description": "a source revision of a watched branch, named once per merge call (design 47 H \u00a7737)",
"properties": {
"v": {
"type": "integer"
},
"branch": {
"type": "string"
},
"source": {
"type": "integer",
"description": "the source revision, numbered by the gate alone"
},
"call": {
"type": "string",
"description": "the merge call that moved it"
},
"start": {
"type": "boolean",
"description": "true only for a branch's first revision (design 47 H \u00a7768)"
},
"heads": {
"type": "array",
"description": "the repositories it moved",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"commit": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"repository",
"commit"
]
}
}
},
"required": [
"v",
"branch",
"source",
"call",
"start",
"heads"
]
},
"keep": {
"max-age-days": 30,
"max-mib": 64
}
},
{
"name": "recovery-merged",
"body": {
"type": "object",
"description": "a merge named a recovery, which the teller passes on to every channel (design 47 G section 305)",
"properties": {
"v": {
"type": "integer"
},
"repository": {
"type": "string",
"description": "the repository"
},
"module": {
"type": "string",
"description": "the module the merge changed, from the delivery record"
},
"branch": {
"type": "string",
"description": "the watched branch the merge moved"
},
"commit": {
"type": "string",
"description": "the merge commit"
},
"why": {
"type": "string",
"description": "why"
},
"by": {
"type": "string",
"description": "the caller the runtime proved"
},
"at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"v",
"repository",
"commit",
"why"
]
}
}
],
"states": [
{
"name": "source",
"template": "state",
"key-forms": [
{
"key": "<branch>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"heads": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "repository to the merged head, a full commit"
},
"source": {
"type": "integer",
"description": "the branch's source revision, one above its newest"
},
"call": {
"type": "string",
"description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H \u00a7737, H-A-33)"
}
},
"required": [
"source",
"call",
"heads"
],
"description": "every repository's merged head; its revision is the mesh's source revision"
},
"description": "one key per watched branch, written by the holder alone by compare-and-set; deleted when the last registration watching the branch unwatches it"
}
],
"description": "the mesh's source revision",
"history": 64
},
{
"name": "owed",
"template": "state",
"key-forms": [
{
"key": "<repository>.<number>.<head>.<act>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"act": {
"type": "string",
"description": "status=<context>, view, note or comment.<seq>"
},
"context": {
"type": "string"
},
"target": {
"type": "string"
},
"state": {
"type": "string"
},
"text": {
"type": "string"
},
"ref": {
"type": "string"
}
},
"required": [
"act"
],
"description": "one act owed to the forge, written by its owner and done by the forge bridge"
},
"description": "one act owed to the forge"
}
],
"description": "the acts the gate owes the forge",
"history": 5
},
{
"name": "heads",
"template": "state",
"history": 1,
"description": "each head the forge bridge's head-moved said that source.<branch> does not name for that repository; deleted when source.<branch> names it (design 47 H \u00a7740)",
"key-forms": [
{
"key": "<repository>.<branch>",
"value": {
"type": "object",
"properties": {
"head": {
"type": "string",
"description": "the head head-moved said",
"pattern": "^[0-9a-f]{40}$"
},
"since": {
"type": "string",
"format": "date-time",
"description": "when it was first heard"
}
},
"required": [
"head",
"since"
],
"description": "an untaken head"
},
"description": "one repository on one watched branch"
}
]
}
],
"defs": {
"Owed": {
"type": "object",
"description": "one act the gate owes the forge, said once under its id and safe to repeat at the forge (design 47 *What the gate owes the forge*); the forge bridge performs it through the seat git's verb of the same act",
"properties": {
"id": {
"type": "string",
"description": "the act's id, the same each time it is said again; a comment and a note line carry it, so the forge holds it once"
},
"act": {
"type": "string",
"enum": [
"merge",
"status",
"view",
"comment",
"note"
],
"description": "the act: merge (the seat git's merge-pull), status, view, comment or note"
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "the pull request's head the act is for",
"pattern": "^[0-9a-f]{40}$"
},
"group": {
"type": "string",
"description": "the delivery group the pull request is a member of, for a merge"
},
"ask": {
"type": "string",
"description": "the operator's ask that approved the heads, for a merge"
},
"commit": {
"type": "string",
"description": "the commit a status or a note line is on; the head when absent",
"pattern": "^[0-9a-f]{40}$"
},
"context": {
"type": "string",
"description": "a status: its context, such as mesh/merge-gate"
},
"state": {
"type": "string",
"description": "a status: its state, pending, success, failure or error"
},
"description": {
"type": "string",
"description": "a status: what it says"
},
"target": {
"type": "string",
"description": "a status: the page it links to"
},
"text": {
"type": "string",
"description": "a comment or the view: the text, markdown"
},
"line": {
"type": "string",
"description": "a note line: the one line"
},
"said": {
"type": "string",
"format": "date-time",
"description": "when the gate first said it"
}
},
"required": [
"id",
"act",
"repository",
"number",
"head"
]
},
"Fill": {
"type": "object",
"description": "the delivery records' ledger's fill against its cap",
"properties": {
"store": {
"type": "string",
"description": "the kept data, by its name in the holder's manifest"
},
"bytes": {
"type": "integer"
},
"cap": {
"type": "integer",
"description": "bytes"
},
"refused": {
"type": "string",
"description": "what full refuses, such as the next record"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when"
}
},
"required": [
"store",
"bytes",
"cap"
]
},
"SourceHead": {
"type": "object",
"description": "one repository of the source revision: its trunk branch and that trunk's head",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>"
},
"trunk": {
"type": "string",
"description": "its trunk branch, such as main"
},
"head": {
"type": "string",
"description": "the trunk's head the source revision names",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"repository",
"trunk",
"head"
]
}
}
}