From f11ef2f5ddda00c83739b6763d397f1bbf6459d3 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 14 Nov 2026 02:24:25 +0100 Subject: [PATCH] Bootstrap the git seat and take the reads the catalog and broker seats now class The first take-in reaches the seat git before a tool runner's seat list is read, so its definition is bootstrapped, a copy of its contracts file with its row in the bootstrap test; the catalog and broker copies follow their contracts, which class their reads. Builds: design 47 G lead answers A-387, A-388 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/seatlist/bootstrap/git.json | 1568 +++++++++++++++++ go/seatlist/bootstrap/mesh-broker.json | 12 +- go/seatlist/bootstrap/mesh-catalog.json | 15 +- go/seatlist/bootstrap_contracts_test.go | 1 + .../seatlisttest/seats/mesh-broker.json | 12 +- .../seatlisttest/seats/mesh-catalog.json | 15 +- go/testdata/beside/CAPTURED | 2 + .../seats/mesh-broker/seat.json.captured | 12 +- .../seats/git/seat.json.captured | 1568 +++++++++++++++++ .../seats/mesh-catalog/seat.json.captured | 15 +- 10 files changed, 3193 insertions(+), 27 deletions(-) create mode 100644 go/seatlist/bootstrap/git.json create mode 100644 go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/git/seat.json.captured diff --git a/go/seatlist/bootstrap/git.json b/go/seatlist/bootstrap/git.json new file mode 100644 index 00000000..283ca432 --- /dev/null +++ b/go/seatlist/bootstrap/git.json @@ -0,0 +1,1568 @@ +{ + "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. The act verbs are the forge bridge's alone.", + "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, /", + "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" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "branch", + "description": "A branch's head, and whether a protection rule refuses a direct push and admits only merges (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, /", + "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}$" + }, + "protected": { + "type": "boolean", + "description": "a protection rule refuses a direct push and admits only merges" + }, + "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" + }, + "callers": [ + "invokers" + ], + "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" + ] + }, + "callers": [ + "invokers" + ], + "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, /", + "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, /", + "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" + }, + "callers": [ + "invokers" + ], + "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, /", + "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" + }, + "callers": [ + "invokers" + ], + "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, /", + "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" + }, + "callers": [ + "invokers" + ], + "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, /", + "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" + }, + "callers": [ + "invokers" + ], + "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, /", + "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" + }, + "callers": [ + "invokers" + ], + "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, /", + "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" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "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, /", + "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" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "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, /", + "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" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "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, /", + "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" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "class": "act" + }, + { + "name": "merge-pull", + "description": "Merge a pull request with the forge tools' account at the head the caller names (design 47 *Approval is a step, and a session merges a pull request*). It judges that this is still the pull request's head and that the base branch's protection refuses a direct push, read again on every branch-moved, and refuses a head when any run at its build-input fingerprint failed a required step, judged from its own state failed-steps heard from the runner's step-ended, never by a call; a head with no run yet or a passed one merges, it never waits for a run and never asks an Approve (ADR 0666 section 11). Refused, naming why: a head that moved, a branch no protection guards, a failed required step (naming the run, the module and the step), no registrations yet (ADR 0667 section 10), a merge git refuses. A pull request already merged at that head is answered performed.", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "repository": { + "type": "string", + "description": "the repository, /", + "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": [ + "id", + "repository", + "number", + "head" + ] + }, + "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" + }, + "merge-commit": { + "type": "string", + "description": "the merge commit" + }, + "refused": { + "type": "string", + "description": "why the forge or the holder refused the merge; the act is not performed" + }, + "refused-kind": { + "type": "string", + "enum": [ + "head-moved", + "unprotected", + "policy-failed", + "no-registrations", + "git-refused" + ], + "description": "which refusal, set with refused: head-moved, the pull request's head is not the one named; unprotected, the base branch's protection does not refuse a direct push; policy-failed, a run at the head's fingerprint failed a required step (run, module and step name it); no-registrations, no registration-changed heard yet (ADR 0667 section 10); git-refused, git refused the merge" + }, + "run": { + "type": "string", + "description": "for policy-failed, the run that failed the step: the runner's pipeline key" + }, + "module": { + "type": "string", + "description": "for policy-failed, the module" + }, + "step": { + "type": "string", + "description": "for policy-failed, the step" + }, + "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; error and error-kind alone when it fails" + }, + "callers": [ + "persons", + "sessions" + ], + "class": "act" + }, + { + "name": "tag", + "class": "act", + "callers": [ + "seat:mesh-builds" + ], + "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, /" + }, + "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, /", + "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, /", + "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, /", + "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, /", + "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, /", + "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, /", + "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, /", + "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, /", + "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 + } + } + ], + "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": "..", + "value": { + "$ref": "#/defs/FailedStep" + }, + "description": "a failed required step" + } + ] + } + ], + "defs": { + "Pull": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "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, :" + }, + "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" + ] + } + } +} diff --git a/go/seatlist/bootstrap/mesh-broker.json b/go/seatlist/bootstrap/mesh-broker.json index 4fab3163..1f7d1294 100644 --- a/go/seatlist/bootstrap/mesh-broker.json +++ b/go/seatlist/bootstrap/mesh-broker.json @@ -56,7 +56,8 @@ "entries" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "show", @@ -67,7 +68,8 @@ "answer": { "$ref": "#/defs/Held" }, - "optional": true + "optional": true, + "class": "read" }, { "name": "check", @@ -122,7 +124,8 @@ "differences" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "orphans", @@ -147,7 +150,8 @@ "entries" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "create", diff --git a/go/seatlist/bootstrap/mesh-catalog.json b/go/seatlist/bootstrap/mesh-catalog.json index cd1d0387..323a0447 100644 --- a/go/seatlist/bootstrap/mesh-catalog.json +++ b/go/seatlist/bootstrap/mesh-catalog.json @@ -66,7 +66,8 @@ "required": [ "modules" ] - } + }, + "class": "read" }, { "name": "module", @@ -127,7 +128,8 @@ "required": [ "module" ] - } + }, + "class": "read" }, { "name": "provides", @@ -147,7 +149,8 @@ "answer": { "type": "object", "description": "what provides answers, as its description says" - } + }, + "class": "read" }, { "name": "dependents", @@ -167,7 +170,8 @@ "answer": { "type": "object", "description": "what dependents answers, as its description says" - } + }, + "class": "read" }, { "name": "seat-definitions", @@ -246,7 +250,8 @@ ] } } - } + }, + "class": "read" }, { "name": "revision", diff --git a/go/seatlist/bootstrap_contracts_test.go b/go/seatlist/bootstrap_contracts_test.go index 99aa19bd..ccf5d585 100644 --- a/go/seatlist/bootstrap_contracts_test.go +++ b/go/seatlist/bootstrap_contracts_test.go @@ -27,6 +27,7 @@ func TestEveryBootstrappedDefinitionEqualsItsContractsFile(t *testing.T) { {"mesh-catalog", "mesh-delivery", "modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json"}, {"mesh-delivery-checker", "mesh-delivery", "modules/mesh-delivery-contracts/seats/mesh-delivery-checker/seat.json"}, {"mesh-delivery", "mesh-delivery", "modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json"}, + {"git", "mesh-delivery", "modules/mesh-delivery-contracts/seats/git/seat.json"}, } var have []string for _, d := range Bootstrapped() { diff --git a/go/seatlist/seatlisttest/seats/mesh-broker.json b/go/seatlist/seatlisttest/seats/mesh-broker.json index 4fab3163..1f7d1294 100644 --- a/go/seatlist/seatlisttest/seats/mesh-broker.json +++ b/go/seatlist/seatlisttest/seats/mesh-broker.json @@ -56,7 +56,8 @@ "entries" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "show", @@ -67,7 +68,8 @@ "answer": { "$ref": "#/defs/Held" }, - "optional": true + "optional": true, + "class": "read" }, { "name": "check", @@ -122,7 +124,8 @@ "differences" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "orphans", @@ -147,7 +150,8 @@ "entries" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "create", diff --git a/go/seatlist/seatlisttest/seats/mesh-catalog.json b/go/seatlist/seatlisttest/seats/mesh-catalog.json index cd1d0387..323a0447 100644 --- a/go/seatlist/seatlisttest/seats/mesh-catalog.json +++ b/go/seatlist/seatlisttest/seats/mesh-catalog.json @@ -66,7 +66,8 @@ "required": [ "modules" ] - } + }, + "class": "read" }, { "name": "module", @@ -127,7 +128,8 @@ "required": [ "module" ] - } + }, + "class": "read" }, { "name": "provides", @@ -147,7 +149,8 @@ "answer": { "type": "object", "description": "what provides answers, as its description says" - } + }, + "class": "read" }, { "name": "dependents", @@ -167,7 +170,8 @@ "answer": { "type": "object", "description": "what dependents answers, as its description says" - } + }, + "class": "read" }, { "name": "seat-definitions", @@ -246,7 +250,8 @@ ] } } - } + }, + "class": "read" }, { "name": "revision", diff --git a/go/testdata/beside/CAPTURED b/go/testdata/beside/CAPTURED index ab0768f8..83864b59 100644 --- a/go/testdata/beside/CAPTURED +++ b/go/testdata/beside/CAPTURED @@ -12,7 +12,9 @@ repositories; before that it was mesh-controller's copy, which still held two mo mesh-catalog b5dbfbb784507e211372a7c9640d91f7d6dadd84 modules/*/module.json, modules/*/files/**, modules/*/templates/**, predefined.json mesh-contracts cf5590c7599d3ee3b61c3aa66c88a939ecb41130 the seat files of the eight bootstrapped seats held there (seats/, health-and-repair/seats/, operator-and-conversation/seats/), as seat.json.captured (milestone 47/G) +mesh-contracts bfc5073b824ef355270da4c44ccf8fa709f6a253 seats/mesh-broker/seat.json, taken again (milestone 47/G lead answer A-388) mesh-delivery 5bf848144283055a1ef37441eeda0e439fb6ad7e contracts/seats/mesh-catalog and mesh-delivery-checker, as seat.json.captured (go/seatlist's bootstrap test; milestone 47/G) +mesh-delivery 0259d77d115c95dde492ac2360e9a518d992adb0 modules/mesh-delivery-contracts/seats/mesh-catalog and git, taken again and added (milestone 47/G lead answer A-387) mesh-host cdcba9ca73755854d21e4e657d7e46c32b9b5265 internal/apply/placement_guard.go The two seat copies are put back the same way (git show : > .captured, the path kept). To move the others, from this repository's go/ directory, with the two repositories checked out beside mesh-sdk: diff --git a/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured b/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured index 4fab3163..1f7d1294 100644 --- a/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured +++ b/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured @@ -56,7 +56,8 @@ "entries" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "show", @@ -67,7 +68,8 @@ "answer": { "$ref": "#/defs/Held" }, - "optional": true + "optional": true, + "class": "read" }, { "name": "check", @@ -122,7 +124,8 @@ "differences" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "orphans", @@ -147,7 +150,8 @@ "entries" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "create", diff --git a/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/git/seat.json.captured b/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/git/seat.json.captured new file mode 100644 index 00000000..283ca432 --- /dev/null +++ b/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/git/seat.json.captured @@ -0,0 +1,1568 @@ +{ + "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. The act verbs are the forge bridge's alone.", + "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, /", + "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" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "branch", + "description": "A branch's head, and whether a protection rule refuses a direct push and admits only merges (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, /", + "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}$" + }, + "protected": { + "type": "boolean", + "description": "a protection rule refuses a direct push and admits only merges" + }, + "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" + }, + "callers": [ + "invokers" + ], + "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" + ] + }, + "callers": [ + "invokers" + ], + "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, /", + "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, /", + "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" + }, + "callers": [ + "invokers" + ], + "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, /", + "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" + }, + "callers": [ + "invokers" + ], + "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, /", + "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" + }, + "callers": [ + "invokers" + ], + "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, /", + "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" + }, + "callers": [ + "invokers" + ], + "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, /", + "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" + }, + "callers": [ + "invokers" + ], + "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, /", + "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" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "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, /", + "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" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "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, /", + "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" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "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, /", + "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" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "class": "act" + }, + { + "name": "merge-pull", + "description": "Merge a pull request with the forge tools' account at the head the caller names (design 47 *Approval is a step, and a session merges a pull request*). It judges that this is still the pull request's head and that the base branch's protection refuses a direct push, read again on every branch-moved, and refuses a head when any run at its build-input fingerprint failed a required step, judged from its own state failed-steps heard from the runner's step-ended, never by a call; a head with no run yet or a passed one merges, it never waits for a run and never asks an Approve (ADR 0666 section 11). Refused, naming why: a head that moved, a branch no protection guards, a failed required step (naming the run, the module and the step), no registrations yet (ADR 0667 section 10), a merge git refuses. A pull request already merged at that head is answered performed.", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "repository": { + "type": "string", + "description": "the repository, /", + "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": [ + "id", + "repository", + "number", + "head" + ] + }, + "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" + }, + "merge-commit": { + "type": "string", + "description": "the merge commit" + }, + "refused": { + "type": "string", + "description": "why the forge or the holder refused the merge; the act is not performed" + }, + "refused-kind": { + "type": "string", + "enum": [ + "head-moved", + "unprotected", + "policy-failed", + "no-registrations", + "git-refused" + ], + "description": "which refusal, set with refused: head-moved, the pull request's head is not the one named; unprotected, the base branch's protection does not refuse a direct push; policy-failed, a run at the head's fingerprint failed a required step (run, module and step name it); no-registrations, no registration-changed heard yet (ADR 0667 section 10); git-refused, git refused the merge" + }, + "run": { + "type": "string", + "description": "for policy-failed, the run that failed the step: the runner's pipeline key" + }, + "module": { + "type": "string", + "description": "for policy-failed, the module" + }, + "step": { + "type": "string", + "description": "for policy-failed, the step" + }, + "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; error and error-kind alone when it fails" + }, + "callers": [ + "persons", + "sessions" + ], + "class": "act" + }, + { + "name": "tag", + "class": "act", + "callers": [ + "seat:mesh-builds" + ], + "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, /" + }, + "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, /", + "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, /", + "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, /", + "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, /", + "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, /", + "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, /", + "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, /", + "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, /", + "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 + } + } + ], + "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": "..", + "value": { + "$ref": "#/defs/FailedStep" + }, + "description": "a failed required step" + } + ] + } + ], + "defs": { + "Pull": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "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, :" + }, + "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" + ] + } + } +} diff --git a/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json.captured b/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json.captured index cd1d0387..323a0447 100644 --- a/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json.captured +++ b/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json.captured @@ -66,7 +66,8 @@ "required": [ "modules" ] - } + }, + "class": "read" }, { "name": "module", @@ -127,7 +128,8 @@ "required": [ "module" ] - } + }, + "class": "read" }, { "name": "provides", @@ -147,7 +149,8 @@ "answer": { "type": "object", "description": "what provides answers, as its description says" - } + }, + "class": "read" }, { "name": "dependents", @@ -167,7 +170,8 @@ "answer": { "type": "object", "description": "what dependents answers, as its description says" - } + }, + "class": "read" }, { "name": "seat-definitions", @@ -246,7 +250,8 @@ ] } } - } + }, + "class": "read" }, { "name": "revision",