integration.events
Every action the repository's executors recorded, from any of its worktrees, oldest first: the lease taken and given back, observations, selections, stale decisions, each act's attempt before it and its outcome after — merges with the master before and after, refusals, refreshes, verification failures and closures — each with a typed action, its actor, the pull request, the head, the decision's reasons and, on an act, the evidence it was decided on. The trail is one file under the common git directory, so every worktree reads the same one.
Every action the repository's executors recorded, from any of its worktrees, oldest first: the lease taken and given back, observations, selections, stale decisions, each act's attempt before it and its outcome after — merges with the master before and after, refusals, refreshes, verification failures and closures — each with a typed action, its actor, the pull request, the head, the decision's reasons and, on an act, the evidence it was decided on. The trail is one file under the common git directory, so every worktree reads the same one.
- query
- experimental
- module integration
- #integration
- #pull-requests
- #audit
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_integration_events |
| HTTP | GET /api/v1/pull-requests/events operationId integration.events |
| command line | majordomus prs events |
Schemas
The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.
input · Empty
No input.
No properties: the capability takes no input.
JSON Schema
{
"additionalProperties": false,
"description": "No input.",
"title": "Empty",
"type": "object"
}output · IntegrationEvents
The audit trail.
| property | type | required | description |
|---|---|---|---|
| events | array | yes | Every recorded integration action, oldest first. |
JSON Schema
{
"$defs": {
"EvidenceKind": {
"description": "What kind of fact a piece of evidence is. The wire words are the ones the evidence carried\nwhile its kind was a string, so a trail written then still reads.",
"oneOf": [
{
"const": "required_check",
"description": "One required check's state on the head: one entry per context the base requires.",
"type": "string"
},
{
"const": "required_checks",
"description": "The required checks together: their verdict, and each context's state.",
"type": "string"
},
{
"const": "review",
"description": "The review policy and the forge's decision, or one reviewer's latest review.",
"type": "string"
},
{
"const": "relation_to_master",
"description": "What the head is to master, as git decided it.",
"type": "string"
},
{
"const": "dependency",
"description": "One declared dependency.",
"type": "string"
},
{
"const": "label",
"description": "One label whose policy is to hold.",
"type": "string"
},
{
"const": "draft",
"description": "Whether it is a draft; always emitted.",
"type": "string"
},
{
"const": "base",
"description": "The branch it targets; always emitted.",
"type": "string"
},
{
"const": "freshness",
"description": "How old the observation is. Declared so the vocabulary is settled; nothing emits it yet.",
"type": "string"
},
{
"const": "auto_merge",
"description": "The forge has auto-merge armed; emitted whenever it is.",
"type": "string"
},
{
"const": "supersession",
"description": "One declared successor: which pull request replaces this one, whose body said so, and\nwhether it landed. One entry per authorised successor (status `open`, `landed`,\n`not_landed` or `unread`), one per declaration nobody entitled made\n(`possible_supersession`), and one when the pull requests that mention it were not all\nread (`references_truncated`, `references_unread`).",
"type": "string"
},
{
"const": "repository_settings",
"description": "What the repository's settings allow the executor; emitted when they allow no merge\ncommit.",
"type": "string"
}
]
},
"EvidenceSource": {
"description": "Where a piece of evidence was read.",
"oneOf": [
{
"description": "The forge observation, at its moment.",
"properties": {
"kind": {
"const": "forge",
"type": "string"
},
"observed_at": {
"description": "When the forge was observed, RFC 3339.",
"type": "string"
}
},
"required": [
"kind",
"observed_at"
],
"type": "object"
},
{
"description": "Git, on this pair of commits.",
"properties": {
"head_sha": {
"description": "The head commit.",
"type": "string"
},
"kind": {
"const": "git",
"type": "string"
},
"master_sha": {
"description": "The master commit.",
"type": "string"
}
},
"required": [
"kind",
"master_sha",
"head_sha"
],
"type": "object"
}
]
},
"FailureClass": {
"description": "Why an act failed, as one class a person and a retry policy can act on. Every failed act\non the trail carries one (`class`), and the drain decides from it whether the next\ncandidate may be tried (`FailureClass::recoverable`) or the drain must stop.",
"oneOf": [
{
"const": "stale",
"description": "Master or the head moved since the decision.",
"type": "string"
},
{
"const": "conflict",
"description": "The merge of master conflicts.",
"type": "string"
},
{
"const": "new_failing_check",
"description": "A required check failed that had passed.",
"type": "string"
},
{
"const": "review_revoked",
"description": "An approval was withdrawn.",
"type": "string"
},
{
"const": "transient",
"description": "The forge or the network failed in a way that passes.",
"type": "string"
},
{
"const": "policy_violation",
"description": "The branch protection refused it.",
"type": "string"
},
{
"const": "verification_failed",
"description": "What landed could not be verified.",
"type": "string"
},
{
"const": "unreadable",
"description": "The forge or git could not be read.",
"type": "string"
}
]
},
"IntegrationAction": {
"description": "What one line of the audit trail records. The wire word is the variant's `snake_case`\nname — the same word each was written as while the action was a string — so every line\nwritten before still parses, and a word nobody writes is not an action.",
"oneOf": [
{
"const": "lease_acquired",
"description": "The executor took the base branch's lease.",
"type": "string"
},
{
"const": "lease_released",
"description": "It gave the lease back.",
"type": "string"
},
{
"const": "continuous_started",
"description": "A continuous drain started.",
"type": "string"
},
{
"const": "continuous_stopped",
"description": "A continuous drain stopped; the detail says why.",
"type": "string"
},
{
"const": "observed",
"description": "The forge was observed and the observation recorded.",
"type": "string"
},
{
"const": "became_actionable",
"description": "A pull request became actionable (ready or refreshable).",
"type": "string"
},
{
"const": "left_actionable",
"description": "A pull request stopped being actionable.",
"type": "string"
},
{
"const": "selected",
"description": "The first ready pull request was chosen to merge.",
"type": "string"
},
{
"const": "refresh_selected",
"description": "The first refreshable pull request was chosen to bring master into.",
"type": "string"
},
{
"const": "stale_decision",
"description": "The decision went stale between planning and acting; nothing was done.",
"type": "string"
},
{
"const": "merge_attempted",
"description": "A merge is about to be asked of the forge.",
"type": "string"
},
{
"const": "merge_succeeded",
"description": "The merge landed and was verified.",
"type": "string"
},
{
"const": "merge_failed",
"description": "The forge refused the merge.",
"type": "string"
},
{
"const": "verification_failed",
"description": "What landed could not be verified.",
"type": "string"
},
{
"const": "failure_acknowledged",
"description": "A person looked at a merge that could not be verified and lets drains merge again\n(`prs drain --resume-after-failure`).",
"type": "string"
},
{
"const": "refresh_attempted",
"description": "Master is about to be merged into a branch and pushed.",
"type": "string"
},
{
"const": "refreshed",
"description": "Master was brought into the branch and pushed.",
"type": "string"
},
{
"const": "refresh_failed",
"description": "Bringing master in failed.",
"type": "string"
},
{
"const": "close_attempted",
"description": "A redundant or superseded pull request is about to be closed.",
"type": "string"
},
{
"const": "closed_redundant",
"description": "A redundant one was closed.",
"type": "string"
},
{
"const": "closed_superseded",
"description": "A superseded one was closed (before 0.13, a line with this word recorded what is now\n`closed_redundant`).",
"type": "string"
},
{
"const": "close_failed",
"description": "Closing it failed.",
"type": "string"
},
{
"const": "reopen_attempted",
"description": "A record pull request the workflow's token opened is about to be closed and reopened,\nso that a run of its own starts (`RecordStanding::Reopenable`).",
"type": "string"
},
{
"const": "reopened",
"description": "It was closed and reopened; its required check can report now.",
"type": "string"
},
{
"const": "reopen_failed",
"description": "Reopening it failed; the detail says whether the pull request was left closed.",
"type": "string"
},
{
"const": "repair_selected",
"description": "A person named a pull request to repair (`prs repair --apply`) and its classification\nmakes it eligible: master is what it lacks, and nothing authored conflicts.",
"type": "string"
},
{
"const": "repair_attempted",
"description": "Master is about to be merged into the named branch and pushed.",
"type": "string"
},
{
"const": "repaired",
"description": "Master was brought into the named branch and pushed.",
"type": "string"
},
{
"const": "repair_refused",
"description": "The repair was refused — by the classification (an authored conflict, a fork, armed\nauto-merge, another base, an undecidable relation) or by the act (a merge, derive,\ncommit or push that failed) — and nothing reached the branch; `class` says why.",
"type": "string"
},
{
"const": "idle",
"description": "Nothing was ready.",
"type": "string"
},
{
"const": "observe_failed",
"description": "A continuous drain's cycle could not observe the forge, and the outage was short\nenough to wait out (`CONTINUOUS_TRANSIENT_LIMIT`).",
"type": "string"
}
]
},
"IntegrationEvent": {
"description": "One entry of the audit trail.",
"properties": {
"action": {
"$ref": "#/$defs/IntegrationAction",
"description": "What (`IntegrationAction`)."
},
"actor": {
"description": "Who: the git identity, the process and the machine.",
"type": "string"
},
"at": {
"description": "When, RFC 3339.",
"type": "string"
},
"class": {
"anyOf": [
{
"$ref": "#/$defs/FailureClass"
},
{
"type": "null"
}
],
"description": "On a failure: its class, once one is decided."
},
"detail": {
"description": "What happened, for a person.",
"type": "string"
},
"evidence": {
"description": "On `merge_attempted`, `merge_succeeded`, `refresh_selected` and the closures:\nthe assessment's evidence the act was decided on.",
"items": {
"$ref": "#/$defs/IntegrationEvidence"
},
"type": "array"
},
"head_after": {
"description": "On `refreshed`: the head the executor pushed. The refresh pipeline waits only for\nthe checks of a head named here.",
"type": [
"string",
"null"
]
},
"head_sha": {
"description": "The head acted on.",
"type": [
"string",
"null"
]
},
"master_after": {
"description": "Master after.",
"type": [
"string",
"null"
]
},
"master_before": {
"description": "Master before.",
"type": [
"string",
"null"
]
},
"merge_commit": {
"description": "On `merge_succeeded`: the merge commit, once it is read.",
"type": [
"string",
"null"
]
},
"passed_over": {
"description": "On a selection: the other actionable pull requests the executor chose this one over,\nin rank order. The wait of each is folded from it (`super::wait`).",
"items": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"type": "array"
},
"pr": {
"description": "The pull request, when one.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"reasons": {
"description": "The decision's reasons; a code an older executor wrote reads back verbatim.",
"items": {
"description": "A reason code, `code` or `code:payload`, one of: `stacked_on:#N`, `base_is:BRANCH`, `draft`, `label:NAME`, `auto_merge_armed`, `merge_commit_not_allowed`, `superseded_by:#N`, `successor_open:#N`, `successor_not_landed:#N`, `successor_unread:#N`, `head_reachable_from_master`, `merge_changes_nothing`, `patch_ids_upstream`, `only_derived_artifacts_differ`, `relation_unknown:WHY`, `conflicts_on:COUNT`, `depends_on:#N`, `review:STATE`, `review_policy_unread`, `required_check_failed`, `behind_master:COMMITS`, `fork_head`, `version_unallocated:VERSION`, `required_checks:STATE`, `no_required_checks`, `required_checks_unread`, `contains_master`, `carries_master`, `required_checks_passed`, `required_checks_skipped`, `executor_merge_refused:HEAD`, `executor_refresh_failed:MASTER`, `label_obsolete:NAME`, `dependency_cycle:#N`, `dependency_closed_unmerged:#N`, `dependency_unread:#N`, `declarations_unread`. A code outside this list (an older trail's) is carried verbatim.",
"type": "string"
},
"type": "array"
}
},
"required": [
"at",
"actor",
"action",
"reasons",
"detail"
],
"type": "object"
},
"IntegrationEvidence": {
"description": "One piece of evidence behind a disposition: what was read, where, and what it said.",
"properties": {
"detail": {
"description": "The detail a person reads.",
"type": "string"
},
"kind": {
"$ref": "#/$defs/EvidenceKind",
"description": "What kind of fact."
},
"source": {
"anyOf": [
{
"$ref": "#/$defs/EvidenceSource"
},
{
"type": "null"
}
],
"description": "Where it was read. Every assessment names it; a trail line written before evidence\ncarried it has none."
},
"status": {
"description": "What it said, as a word.",
"type": "string"
}
},
"required": [
"kind",
"status",
"detail"
],
"type": "object"
}
},
"description": "The audit trail.",
"properties": {
"events": {
"description": "Every recorded integration action, oldest first.",
"items": {
"$ref": "#/$defs/IntegrationEvent"
},
"type": "array"
}
},
"required": [
"events"
],
"title": "IntegrationEvents",
"type": "object"
}Policies
- benchmark
- required — a target on every transport the exposure declares; the cases are the input type's
- cache
- disabled — every call runs the handler
Benchmark targets
Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.