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

{
  "format": 1,
  "seat": "mesh-delivery-checker",
  "scope": "mesh",
  "grain": "whole",
  "decision": "novox/hq ADR 0547",
  "verbs": [
    {
      "name": "try",
      "description": "Try a pushed head before its pull request is opened: the checker judges it as it judges a pull request's head, merged onto its trunk's head, its unit and integration levels through the build modules, and owes the forge nothing. Answers the try's id at once; try-read reads where it stands. A try of the same head that waits or runs is the answer to a second ask; at most 4 wait or run at once, mesh-wide.",
      "optional": true,
      "replaces": [
        "sh merge-check.sh",
        "docker run postgres"
      ],
      "input": {
        "properties": {
          "head": {
            "description": "the full commit to try, 40 or 64 hex digits",
            "type": "string"
          },
          "level": {
            "description": "unit or integration: only this level; both when absent",
            "type": "string"
          },
          "repository": {
            "description": "<owner>/<name>",
            "type": "string"
          },
          "tests": {
            "description": "a go test -run pattern: only those tests run, and nothing is kept",
            "type": "string"
          },
          "trunk": {
            "description": "the trunk commit to merge it onto, or the trunk's branch for its head now; the trunk's head when absent",
            "type": "string"
          }
        },
        "required": [
          "repository",
          "head"
        ],
        "type": "object"
      },
      "answer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "the try's id"
          },
          "state": {
            "type": "string",
            "description": "its state"
          }
        },
        "required": [
          "id"
        ]
      }
    },
    {
      "name": "try-read",
      "description": "Where a try stands, as stored: queued, running, or its end (pass, fail, or error when it could not run), with what was said of it, the head and the trunk commit it was merged onto, the time it took and what failed first. Read-only.",
      "optional": true,
      "input": {
        "properties": {
          "id": {
            "description": "the try's id, try-<digits>",
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "type": "object"
      },
      "answer": {
        "type": "object",
        "description": "the try: its state, its steps and its verdict when it has one"
      }
    },
    {
      "name": "try-end",
      "description": "End a try that waits or runs, as error, by hand: say why (kept in what it says). Its place among the tries is free at once and the next try of its head asks anew with a new id. A try that ended already is refused.",
      "optional": true,
      "input": {
        "properties": {
          "id": {
            "description": "the try's id, try-<digits>",
            "type": "string"
          },
          "why": {
            "description": "why it is ended, in words",
            "type": "string"
          }
        },
        "required": [
          "id",
          "why"
        ],
        "type": "object"
      },
      "answer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "the try"
          },
          "ended": {
            "type": "boolean",
            "description": "it is ended"
          }
        },
        "required": [
          "id",
          "ended"
        ]
      }
    }
  ],
  "description": "The merge check's tries: start one, read one, end one. The checker's own events stay under its own subjects (ADR 0620 §2).",
  "holder-events": [
    {
      "name": "verdict",
      "subject": "mesh.mod.<holder>.event.verdict",
      "family": "checker.asks",
      "body": {
        "type": "object",
        "properties": {
          "repository": {
            "type": "string",
            "description": "owner/repo"
          },
          "pull": {
            "type": "integer",
            "description": "the pull request's number, for a pull request's check"
          },
          "head": {
            "type": "string",
            "description": "the commit checked"
          },
          "verdict": {
            "type": "string",
            "description": "pass or fail"
          },
          "out-of-step": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "the generated files out of step with their seat definitions, each path (design 26)"
          }
        },
        "required": [
          "repository",
          "head",
          "verdict"
        ]
      }
    },
    {
      "name": "tag-wanted",
      "subject": "mesh.mod.<holder>.event.tag-wanted",
      "family": "checker.asks",
      "body": {
        "type": "object",
        "properties": {
          "repository": {
            "type": "string",
            "description": "owner/repo"
          },
          "pull": {
            "type": "integer",
            "description": "the pull request"
          },
          "head": {
            "type": "string",
            "description": "its head"
          },
          "branch": {
            "type": "string",
            "description": "the pull request's branch: its tag is removed when the branch ends"
          },
          "module": {
            "type": "string",
            "description": "the group member"
          },
          "package": {
            "type": "string",
            "description": "the package it declares"
          },
          "tag": {
            "type": "string",
            "description": "the tag wanted"
          }
        },
        "required": [
          "repository",
          "head",
          "branch",
          "module",
          "package"
        ]
      }
    },
    {
      "name": "preview.written",
      "subject": "mesh.mod.<holder>.event.preview.written",
      "family": "checks"
    }
  ]
}