Files
mesh-delivery/modules/mesh-delivery-contracts/seats/git/seat.json
T
jschoubben d24d6a0890 C2: a kept call's member names its base branch
So the forge module can say merge-called for what landed after a restart
without reading the forge again, each member of the state calls keeps the
pull request's base, read at judging.

Builds: design 47 H §766; lead answer H-A-71 (2)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 02:51:26 +01:00

1737 lines
51 KiB
JSON

{
"format": 1,
"seat": "git",
"scope": "mesh",
"grain": "whole",
"domain": "Delivery",
"decision": "novox/hq ADR 0111",
"description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 \u00a71, \u00a72). A failed read answers an error, never an empty answer.",
"delivers": "git",
"verbs": [
{
"name": "pull",
"description": "One pull request, by its repository and number or by its merge commit: its number, base, head branch, head, merge commit, author and state; for an open one, also what the forge would merge now (merging). A pull request the forge does not hold answers an error naming it.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "its number"
},
"merge-commit": {
"type": "string",
"description": "instead of the number: the merge commit it made"
}
},
"additionalProperties": false,
"required": [
"repository"
]
},
"answer": {
"type": "object",
"properties": {
"pull": {
"$ref": "#/defs/Pull"
},
"merging": {
"$ref": "#/defs/Merging"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what pull answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "branch",
"description": "A branch's head (design 47 *The seat git*, *Watched branches and the catalog graph per branch*). A branch the forge does not hold answers the error kind not-found.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"branch": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"repository",
"branch"
]
},
"answer": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"branch": {
"type": "string"
},
"head": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what branch answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "open-pulls",
"description": "Every open pull request of every repository, its head and base, the statuses its base's protection requires and those its head has.",
"input": {
"type": "object",
"properties": {},
"additionalProperties": false
},
"answer": {
"type": "object",
"properties": {
"pulls": {
"type": "array",
"items": {
"$ref": "#/defs/OpenPull"
},
"description": "every open pull request; said empty when none is open, so an answer that lacks it is never read as none"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what open-pulls answers; pulls always said, empty when none is open; error and error-kind beside an empty pulls when it fails",
"required": [
"pulls"
]
},
"class": "read"
},
{
"name": "tags",
"description": "A repository's tags, a page at a time, newest first; the page's bound is said, and more when another page exists.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"prefix": {
"type": "string",
"description": "only tags starting with it"
},
"page": {
"type": "integer",
"description": "the page, from 1"
}
},
"additionalProperties": false,
"required": [
"repository"
]
},
"answer": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "the tags of this page"
},
"page": {
"type": "integer",
"description": "the page"
},
"bound": {
"type": "integer",
"description": "how many tags a page holds"
},
"more": {
"type": "boolean",
"description": "another page exists"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what tags answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "trees",
"description": "The trees of one commit: the root tree and the tree of every directory that holds a module.json, by their git hashes; with files, every blob under each named directory; with paths, the object of each named path. A listing the forge cut is refused, never answered in part.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"paths": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "{directory: [path relative to it]}; the root is the empty name"
},
"files": {
"type": "array",
"items": {
"type": "string"
},
"description": "directories whose every blob is answered; the root is the empty name"
}
},
"additionalProperties": false,
"required": [
"repository",
"commit"
]
},
"answer": {
"type": "object",
"properties": {
"commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"root": {
"type": "string",
"description": "the root tree's hash"
},
"trees": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "directory to its tree's hash, the root as the empty name"
},
"files": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"description": "directory to {path: blob id}"
},
"paths": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"description": "directory to {path: object id}"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what trees answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "file",
"description": "One file at one commit, branch or tag, decoded; a file over 512 KiB is refused. An absent file is answered absent only when the forge said so.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"path": {
"type": "string",
"description": "the file's path from the repository's root",
"minLength": 1
},
"ref": {
"type": "string",
"description": "a commit, branch or tag; the default branch when absent"
}
},
"additionalProperties": false,
"required": [
"repository",
"path"
]
},
"answer": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "the path"
},
"ref": {
"type": "string",
"description": "what was read"
},
"blob": {
"type": "string",
"description": "the file's git blob id"
},
"size": {
"type": "integer",
"description": "its size in bytes"
},
"content": {
"type": "string",
"description": "its content"
},
"absent": {
"type": "boolean",
"description": "the forge holds no such file there"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what file answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "contains",
"description": "Whether one commit contains another: an ancestor of it, or the same.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"commit": {
"type": "string",
"description": "the commit asked about",
"minLength": 1
},
"in": {
"type": "string",
"description": "the commit it may be contained in",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"repository",
"commit",
"in"
]
},
"answer": {
"type": "object",
"properties": {
"commit": {
"type": "string",
"description": "the commit"
},
"in": {
"type": "string",
"description": "the other"
},
"contains": {
"type": "boolean",
"description": "in contains commit"
},
"ahead": {
"type": "integer",
"description": "how many commits commit is ahead of in"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what contains answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "statuses",
"description": "The statuses a commit carries, the newest of each context.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
}
},
"additionalProperties": false,
"required": [
"repository",
"commit"
]
},
"answer": {
"type": "object",
"properties": {
"commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"combined": {
"type": "string",
"description": "the forge's combined state"
},
"statuses": {
"type": "array",
"items": {
"$ref": "#/defs/Status"
},
"description": "the newest of each context"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what statuses answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "status",
"description": "Set a commit status. An act: its id is the caller's, and the same id said again sets it again to the same.",
"input": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id",
"minLength": 1
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"context": {
"type": "string",
"description": "the context, such as mesh/check",
"minLength": 1
},
"state": {
"type": "string",
"description": "the state",
"enum": [
"pending",
"success",
"failure",
"error",
"warning"
]
},
"description": {
"type": "string",
"description": "what it says"
},
"target": {
"type": "string",
"description": "the page it links to"
}
},
"additionalProperties": false,
"required": [
"id",
"repository",
"commit",
"context",
"state"
]
},
"answer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id, as the caller gave it"
},
"performed": {
"type": "boolean",
"description": "the forge holds the act now"
},
"held": {
"type": "boolean",
"description": "the id was already held on the pull request or the note, so nothing was done again"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what status answers; error and error-kind alone when it fails"
},
"class": "act"
},
{
"name": "comment",
"description": "Add a comment to a pull request. The comment carries the act's id, and an id the pull request already holds is skipped (held).",
"input": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id",
"minLength": 1
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"text": {
"type": "string",
"description": "the comment, markdown",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"id",
"repository",
"number",
"text"
]
},
"answer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id, as the caller gave it"
},
"performed": {
"type": "boolean",
"description": "the forge holds the act now"
},
"held": {
"type": "boolean",
"description": "the id was already held on the pull request or the note, so nothing was done again"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what comment answers; error and error-kind alone when it fails"
},
"class": "act"
},
{
"name": "view",
"description": "Keep the delivery's one view comment on a pull request: made the first time, edited in place after; it carries the act's id, and an id already held is skipped (held).",
"input": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id",
"minLength": 1
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"text": {
"type": "string",
"description": "the view, markdown",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"id",
"repository",
"number",
"text"
]
},
"answer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id, as the caller gave it"
},
"performed": {
"type": "boolean",
"description": "the forge holds the act now"
},
"held": {
"type": "boolean",
"description": "the id was already held on the pull request or the note, so nothing was done again"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what view answers; error and error-kind alone when it fails"
},
"class": "act"
},
{
"name": "note",
"description": "Append one line to a commit's note under refs/notes/mesh-plan. The line carries the act's id, and an id the note already holds is skipped (held).",
"input": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id",
"minLength": 1
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"line": {
"type": "string",
"description": "the line, one line",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"id",
"repository",
"commit",
"line"
]
},
"answer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id, as the caller gave it"
},
"performed": {
"type": "boolean",
"description": "the forge holds the act now"
},
"held": {
"type": "boolean",
"description": "the id was already held on the pull request or the note, so nothing was done again"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what note answers; error and error-kind alone when it fails"
},
"class": "act"
},
{
"name": "merge-pull",
"description": "Merge one or more pull requests with the forge tools' account, each at the head the caller names: one merge call, a delivery's start and, with two or more members, its group (design 47 H \u00a7734, \u00a7735, \u00a7766; ADR 0682 \u00a71, \u00a72). Every member is judged before any is merged: still the pull request's head, its base a watched branch, no run at the head's build-input fingerprint failed a required step (judged from its own state failed-steps), registrations heard; no branch protection is read. When one member is refused, none is merged. Then it merges them in the order named, writing the call in its state calls before the first merge, and says merge-called once. It answers once, at the call's end, naming the call and each member's outcome; a member already merged is refused already-merged, naming its commit.",
"input": {
"type": "object",
"properties": {
"pulls": {
"type": "array",
"minItems": 1,
"description": "the members, in the order they are merged",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "the head the caller names",
"pattern": "^[0-9a-f]{40}$"
}
},
"additionalProperties": false,
"required": [
"repository",
"number",
"head"
]
}
},
"by": {
"type": "string",
"description": "the caller as who@node, recorded beside the bus account the tool runner proves",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"pulls",
"by"
]
},
"answer": {
"type": "object",
"properties": {
"call": {
"type": "string",
"description": "the merge call, 16 lowercase hex characters made once per call",
"pattern": "^[0-9a-f]{16}$"
},
"members": {
"type": "array",
"description": "each member's outcome, in the order named",
"items": {
"$ref": "#/defs/MemberOutcome"
}
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what merge-pull answers at the call's end; error and error-kind alone when it fails"
},
"class": "act",
"timeout": 120
},
{
"name": "tag",
"class": "act",
"description": "Write the git tag of a released version, go/vMAJOR.MINOR.PATCH, at the commit its build was made from; the builder writes it only on the catalog's version-released (design 47 G section 370). A tag already at that commit is answered performed. An error answer carries error and error-kind.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>"
},
"tag": {
"type": "string",
"description": "the tag"
},
"commit": {
"type": "string",
"description": "the commit it is written at"
}
},
"additionalProperties": false,
"required": [
"repository",
"tag",
"commit"
]
},
"answer": {
"type": "object",
"properties": {
"tag": {
"type": "string",
"description": "the tag, as asked"
},
"performed": {
"type": "boolean",
"description": "the forge holds the tag at that commit now"
},
"error": {
"type": "string",
"description": "why the forge could not write it: set alone with error-kind"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
}
},
"description": "what tag answers; error and error-kind alone when it fails"
}
}
],
"events": [
{
"name": "pull-updated",
"body": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"branch": {
"type": "string",
"description": "its head branch"
},
"head": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"base": {
"type": "string",
"description": "the branch it merges into"
},
"title": {
"type": "string",
"description": "its title"
},
"author": {
"type": "string",
"description": "who opened it"
},
"url": {
"type": "string",
"description": "its page"
},
"base-head": {
"type": "string",
"description": "the base branch's head as the head was announced; absent when it could not be read"
},
"change": {
"$ref": "#/defs/Change"
}
},
"description": "a pull request's new head, announced once per head and trunk commit",
"required": [
"repository",
"number",
"branch",
"head",
"base"
]
}
},
{
"name": "pull-merged",
"body": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"branch": {
"type": "string",
"description": "its head branch"
},
"head": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"base": {
"type": "string",
"description": "the branch it merges into"
},
"title": {
"type": "string",
"description": "its title"
},
"author": {
"type": "string",
"description": "who opened it"
},
"url": {
"type": "string",
"description": "its page"
},
"merge-commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"merged-at": {
"type": "string",
"description": "when",
"format": "date-time"
},
"change": {
"$ref": "#/defs/Change"
},
"head-checks": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "the head's statuses by context, their states; absent when they could not be read"
}
},
"description": "a pull request merged, announced once by its merge commit",
"required": [
"repository",
"number",
"branch",
"head",
"base",
"merge-commit"
]
}
},
{
"name": "pull-closed",
"body": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"branch": {
"type": "string",
"description": "its head branch"
},
"head": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"base": {
"type": "string",
"description": "the branch it merges into"
},
"title": {
"type": "string",
"description": "its title"
},
"author": {
"type": "string",
"description": "who opened it"
},
"url": {
"type": "string",
"description": "its page"
}
},
"description": "a pull request closed without a merge, announced once by its head",
"required": [
"repository",
"number",
"branch",
"head",
"base"
]
}
},
{
"name": "forge-pull",
"body": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "what the forge said: opened, reopened, synchronized, edited, closed, merged"
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "its number"
},
"branch": {
"type": "string",
"description": "its head branch"
},
"head": {
"type": "string",
"description": "its head commit"
},
"base": {
"type": "string",
"description": "its base branch"
},
"author": {
"type": "string",
"description": "who opened it"
},
"merged": {
"type": "boolean",
"description": "merged"
},
"merge-commit": {
"type": "string",
"description": "the merge commit"
},
"sender": {
"type": "string",
"description": "who acted"
}
},
"description": "the forge's own webhook of a pull request, trimmed; never its description",
"required": [
"action",
"repository",
"number"
]
}
},
{
"name": "forge-status",
"body": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"commit": {
"type": "string",
"description": "the commit"
},
"context": {
"type": "string",
"description": "the context"
},
"state": {
"type": "string",
"description": "the state"
},
"description": {
"type": "string",
"description": "what it says"
},
"sender": {
"type": "string",
"description": "who set it"
}
},
"description": "the forge's own webhook of a commit status",
"required": [
"repository",
"commit",
"context",
"state"
]
}
},
{
"name": "forge-delete",
"body": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"ref": {
"type": "string",
"description": "the deleted branch or tag"
},
"ref-type": {
"type": "string",
"description": "branch or tag"
},
"sender": {
"type": "string",
"description": "who deleted it"
}
},
"description": "the forge's own webhook of a deleted branch or tag",
"required": [
"repository",
"ref"
]
}
},
{
"name": "repo-writable",
"body": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"account": {
"type": "string",
"description": "the account that writes it now"
}
},
"description": "a repository the forge's account can write again",
"required": [
"repository",
"account"
]
}
},
{
"name": "branch-moved",
"body": {
"type": "object",
"description": "a branch's new head, by a merge or an admitted push, from the forge's push webhook (design 47 lines 507-512): its hearer takes the head from the forge's own record by the verb branch, never from this body",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"branch": {
"type": "string",
"minLength": 1
},
"head": {
"type": "string",
"description": "the head the webhook said, a commit's full 40-hex sha; read again by branch",
"pattern": "^[0-9a-f]{40}$"
},
"at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"repository",
"branch"
]
},
"keep": {
"max-age-days": 90,
"max-mib": 64
}
},
{
"name": "merge-called",
"subject": "merge-called.<call>",
"body": {
"$ref": "#/bodies/MergeCalled"
},
"keep": {
"max-age-days": 30,
"max-mib": 64
}
}
],
"family": {
"name": "git.events",
"max-age-days": 7
},
"states": [
{
"name": "failed-steps",
"template": "state",
"history": 1,
"description": "each failed required step by module and build-input fingerprint, heard from the runner's step-ended; an entry is deleted once none of its commits is a watched branch's head or the head an open pull request names (design 47 *The runner's kept data*)",
"key-forms": [
{
"key": "<module>.<fingerprint>.<step>",
"value": {
"$ref": "#/defs/FailedStep"
},
"description": "a failed required step"
}
]
},
{
"name": "calls",
"template": "state",
"history": 1,
"description": "every merge call, written before its first merge; one whose merge-called is not said is said at the holder's start; deleted past the stream merge-called's age (design 47 H \u00a7766, H-A-47)",
"key-forms": [
{
"key": "call.<call>",
"value": {
"$ref": "#/defs/Call"
},
"description": "one merge call"
}
]
}
],
"defs": {
"Pull": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"title": {
"type": "string",
"description": "its title"
},
"author": {
"type": "string",
"description": "who opened it, the forge's login"
},
"branch": {
"type": "string",
"description": "its head branch: what a delivery group is named by"
},
"head": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"base": {
"type": "string",
"description": "the branch it merges into"
},
"state": {
"type": "string",
"description": "open, merged or closed",
"enum": [
"open",
"merged",
"closed"
]
},
"merge-commit": {
"type": "string",
"description": "the merge commit, once merged"
},
"merged-at": {
"type": "string",
"description": "when it merged",
"format": "date-time"
},
"url": {
"type": "string",
"description": "its page on the forge"
}
},
"description": "one pull request as the forge holds it; never its description (ADR 0659 \u00a71)",
"required": [
"repository",
"number",
"branch",
"head",
"base",
"state"
]
},
"Merging": {
"type": "object",
"properties": {
"mergeable": {
"type": "boolean",
"description": "the forge's own word on whether it merges into its base now: false while it is in conflict with its base, or while the forge works that out after the base moved"
},
"protected": {
"type": "boolean",
"description": "whether a protection rule guards its base branch"
},
"required": {
"type": "array",
"items": {
"type": "string"
},
"description": "the status contexts the base branch's protection requires; none when it requires none"
},
"writes": {
"type": "boolean",
"description": "whether the forge's merging account may write the repository: false, its statuses and its merge are refused"
}
},
"description": "what the forge would merge now, for an open pull request (issues 1275, 1945; ADR 0441 \u00a71): answered whole or not at all, and a read the forge could not make answers the verb's error, never a guess; absent for a merged or closed one",
"required": [
"mergeable",
"protected",
"required",
"writes"
]
},
"Status": {
"type": "object",
"properties": {
"context": {
"type": "string",
"description": "the status's context, such as mesh/check"
},
"state": {
"type": "string",
"description": "pending, success, failure, error or warning"
},
"description": {
"type": "string",
"description": "what it says"
},
"target": {
"type": "string",
"description": "the page it links to"
},
"at": {
"type": "string",
"description": "when it was set",
"format": "date-time"
},
"by": {
"type": "string",
"description": "who set it"
}
},
"description": "the newest status of one context on a commit",
"required": [
"context",
"state"
]
},
"OpenPull": {
"type": "object",
"properties": {
"pull": {
"$ref": "#/defs/Pull"
},
"required": {
"type": "array",
"items": {
"type": "string"
},
"description": "the contexts the base branch's protection requires; none when it requires none"
},
"checks": {
"type": "object",
"additionalProperties": {
"$ref": "#/defs/Status"
},
"description": "the head's statuses by context, the newest of each"
}
},
"description": "an open pull request, with the statuses its base requires and those its head has",
"required": [
"pull",
"required",
"checks"
]
},
"Change": {
"type": "object",
"properties": {
"paths": {
"type": "array",
"items": {
"type": "string"
},
"description": "the paths it changed"
},
"paths-truncated": {
"type": "boolean",
"description": "the forge cut the list"
},
"removed": {
"type": "array",
"items": {
"type": "string"
},
"description": "which of them it deleted"
},
"module-dirs": {
"type": "array",
"items": {
"type": "string"
},
"description": "the changed directories that hold a module at its head; absent when they could not be read"
}
},
"description": "what a pull request changed",
"required": [
"paths"
]
},
"ErrorKind": {
"type": "string",
"enum": [
"refused",
"not-found",
"failed"
],
"description": "which kind of error, set with error alone: refused, the forge or the holder refused and error says why in the forge's own words; not-found, the forge said that what was asked about (a repository, a commit, a pull request, a branch or a tag) does not exist, so a caller never reads it out of error's words; failed, the forge failed or could not be reached, so the act or read could not be performed"
},
"FailedStep": {
"type": "object",
"description": "a failed required step at a build-input fingerprint, with the commits it was seen at and the run that failed it (design 47 *Judged from its own state, never by a call*); cleared by a later passing rerun of that step whose proved caller is the operator or a healer",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"module": {
"type": "string"
},
"fingerprint": {
"type": "string",
"description": "the build-input fingerprint the step failed at"
},
"step": {
"type": "string"
},
"artifact": {
"type": "string",
"description": "the artifact reference, <module>:<artifact>"
},
"run": {
"type": "string",
"description": "the run that failed it: the runner's pipeline key"
},
"commits": {
"type": "array",
"items": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"description": "every commit it was seen at"
},
"said": {
"type": "string",
"description": "why it failed, as the runner's step-ended said"
},
"at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"module",
"fingerprint",
"step",
"run",
"commits"
]
},
"MemberOutcome": {
"type": "object",
"description": "one member of a merge call and where it stands (design 47 H \u00a7766, H-A-22)",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"state": {
"type": "string",
"enum": [
"judged",
"merged",
"refused"
],
"description": "judged, judged and not merged; merged, with its commit; refused, with why"
},
"commit": {
"type": "string",
"description": "for merged, the merge commit; for a member refused already-merged, its commit",
"pattern": "^[0-9a-f]{40}$"
},
"why": {
"type": "string",
"description": "for refused, why, naming the step for a failed required step"
}
},
"required": [
"repository",
"number",
"state"
]
},
"Call": {
"type": "object",
"description": "one merge call, written before its first merge and updated as each member merges (design 47 H \u00a7766)",
"properties": {
"by": {
"type": "string",
"description": "the caller as who@node"
},
"account": {
"type": "string",
"description": "the bus account the tool runner proved for the call"
},
"at": {
"type": "string",
"format": "date-time"
},
"members": {
"type": "array",
"items": {
"$ref": "#/defs/CallMember"
}
},
"said": {
"type": "boolean",
"description": "merge-called was said for it"
}
},
"required": [
"by",
"account",
"at",
"members",
"said"
]
},
"CallMember": {
"type": "object",
"description": "one member of a kept call",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"branch": {
"type": "string",
"description": "the pull request's base, a watched branch, read at judging"
},
"head": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
},
"state": {
"type": "string",
"enum": [
"judged",
"merged",
"refused"
]
},
"commit": {
"type": "string",
"description": "for merged, the merge commit",
"pattern": "^[0-9a-f]{40}$"
},
"why": {
"type": "string",
"description": "for refused, why"
}
},
"required": [
"repository",
"number",
"branch",
"head",
"state"
]
}
},
"bodies": {
"MergeCalled": {
"type": "object",
"description": "a merge call's members merged or refused, said once by the forge module (design 47 H \u00a7736, \u00a7767)",
"properties": {
"call": {
"type": "string",
"description": "the merge call, 16 lowercase hex characters made once per call",
"pattern": "^[0-9a-f]{16}$"
},
"by": {
"type": "string",
"description": "the caller as who@node"
},
"account": {
"type": "string",
"description": "the bus account the tool runner proved"
},
"at": {
"type": "string",
"format": "date-time",
"description": "the time of the last merge"
},
"members": {
"type": "array",
"description": "one per landed member",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"branch": {
"type": "string",
"description": "the pull request's base, a watched branch"
},
"head": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
},
"commit": {
"type": "string",
"description": "the merge commit the forge records for the pull request",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"repository",
"number",
"branch",
"head",
"commit"
]
}
},
"refused": {
"type": "array",
"description": "one per member not merged after every member was judged (design 47 H \u00a7767)",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"why": {
"type": "string"
}
},
"required": [
"repository",
"number",
"why"
]
}
}
},
"required": [
"call",
"by",
"account",
"at",
"members"
]
}
}
}