mesh-contracts/seats/mesh-delivery/seat.json

{
  "format": 1,
  "seat": "mesh-delivery",
  "scope": "mesh",
  "grain": "seat-list",
  "decision": "novox/hq ADR 0239",
  "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"
      }
    },
    {
      "name": "times",
      "description": "Removed in R6 (ADR 0539): refused by name, naming its replacement: the delivery view (nox-delivery): each machine's want and have, and since when",
      "optional": true,
      "input": {
        "properties": {},
        "type": "object"
      }
    },
    {
      "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"
      }
    },
    {
      "name": "groups",
      "description": "Every delivery group: its members in order, why each pair is ordered (declared, built by, version skew, engine before controller, by name), its composed check and its state, derived from its members.",
      "input": {
        "properties": {
          "all": {
            "description": "\"true\": the groups that ended too",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    {
      "name": "what-if",
      "description": "Removed in R6 (ADR 0539): refused by name, naming its replacement: the merge check's composition, which composes every machine a change touches",
      "optional": true,
      "input": {
        "properties": {},
        "type": "object"
      }
    },
    {
      "name": "checks",
      "description": "What the mesh's checks said of a pull request's head or of one commit: each of the commit's mesh statuses (mesh/check, the one a main requires from R4e, hq's mesh/repo-check, mesh/delivery, …) with its state, description and when it was set; the merge check's full verdict as the controller said it — each layer's summary, the machine that ran it, when, its build id and its report; and whether the branch's protection would let it merge, every required status being success.",
      "optional": true,
      "input": {
        "properties": {
          "commit": {
            "description": "a commit's sha, or the start of one, instead of a pull request",
            "type": "string"
          },
          "number": {
            "description": "a pull request's number: its head is read",
            "type": "string"
          },
          "repository": {
            "description": "owner/repository",
            "type": "string"
          }
        },
        "required": [
          "repository"
        ],
        "type": "object"
      }
    },
    {
      "name": "table",
      "description": "The state table every delivery runs by: each transition with its guard, each state's bound and what healer H2 may do once it has passed; and the machine steps' table.",
      "input": {
        "properties": {},
        "type": "object"
      }
    },
    {
      "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"
      }
    },
    {
      "name": "recheck",
      "description": "Check a rejected or ready delivery again: it goes back to proposed and the controller is asked for its check. With why.",
      "input": {
        "properties": {
          "id": {
            "description": "the delivery's id",
            "type": "string"
          },
          "why": {
            "description": "why, kept with the transition",
            "type": "string"
          }
        },
        "required": [
          "id",
          "why"
        ],
        "type": "object"
      }
    },
    {
      "name": "release",
      "description": "Removed in R6 (ADR 0539): refused by name, naming its replacement: the assigner's asks (hold, restore, backup, record), answered on the phone or in the delivery view",
      "optional": true,
      "input": {
        "properties": {},
        "type": "object"
      }
    },
    {
      "name": "stop",
      "description": "Removed in R6 (ADR 0539): refused by name, naming its replacement: a bad fingerprint is held and its canary set back by the assigner (ADR 0429 §6, ADR 0539 clause 18)",
      "optional": true,
      "input": {
        "properties": {},
        "type": "object"
      }
    },
    {
      "name": "close",
      "description": "Healer H2's verb: take the one transition the table names for a delivery held past its bound. Refused for any other.",
      "input": {
        "properties": {
          "id": {
            "description": "the delivery's id",
            "type": "string"
          },
          "why": {
            "description": "the condition it answers",
            "type": "string"
          }
        },
        "required": [
          "id",
          "why"
        ],
        "type": "object"
      }
    },
    {
      "name": "retire-history",
      "description": "Removed in R6 (ADR 0539): refused by name, naming its replacement: nothing to retire: the gate keeps no delivery after its merge",
      "optional": true,
      "input": {
        "properties": {},
        "type": "object"
      }
    },
    {
      "name": "settle",
      "description": "Ask the operator to settle deliveries held because their merge reached the trunk without a passing check: one ask on the operator's channel for all of them, as an Approve is asked. The verb moves nothing; on the operator's answer each goes to merged, and whether it is on the machines is derived as for any merge (novox/hq ADR 0556). Refused for a delivery not held, or held for another reason, naming why.",
      "optional": true,
      "input": {
        "additionalProperties": false,
        "properties": {
          "ids": {
            "description": "the held deliveries' ids (owner/repository@commit)",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "type": "array"
          },
          "why": {
            "description": "why they may be settled, shown to the operator",
            "type": "string"
          }
        },
        "required": [
          "ids",
          "why"
        ],
        "type": "object"
      }
    }
  ]
}