A snapshot: read at commit 707a04c7ce8 on 2026-10-18T00:06:01Z by majordomus 0.29.0. Nothing on this page is read again. See it live

integration.events

The integration audit trail

What it is

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.

Descriptor

Canonical id: integration.events
Module: integration
Kind: query
Stability: experimental
Provenance: declared
Source: apps/majordomus-cli/src/capability/builtin/integration.rs
Cache: disabled
Benchmark: required
Tags: integrationpull-requestsaudit

Run

query

A query. It reads and changes nothing.

Projections

Interface	As	Where
MCP tool	`majordomus_integration_events`	-
MCP resource	not exposed	-
HTTP	`GET /api/v1/pull-requests/events`	Swagger
Command line	`majordomus prs events`	-

Schemas

Input · Empty

{
  "type": "object",
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty"
}

Output · IntegrationEvents

{
  "type": "object",
  "properties": {
    "events": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/IntegrationEvent"
      },
      "description": "Every recorded integration action, oldest first."
    }
  },
  "required": [
    "events"
  ],
  "description": "The audit trail.",
  "title": "IntegrationEvents",
  "$defs": {
    "IntegrationEvent": {
      "type": "object",
      "properties": {
        "at": {
          "type": "string",
          "description": "When, RFC 3339."
        },
        "actor": {
          "type": "string",
          "description": "Who: the git identity, the process and the machine."
        },
        "action": {
          "$ref": "#/$defs/IntegrationAction",
          "description": "What (`IntegrationAction`)."
        },
        "pr": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint64",
          "minimum": 0,
          "description": "The pull request, when one."
        },
        "master_before": {
          "type": [
            "string",
            "null"
          ],
          "description": "Master before."
        },
        "head_sha": {
          "type": [
            "string",
            "null"
          ],
          "description": "The head acted on."
        },
        "master_after": {
          "type": [
            "string",
            "null"
          ],
          "description": "Master after."
        },
        "reasons": {
          "type": "array",
          "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"
          },
          "description": "The decision's reasons; a code an older executor wrote reads back verbatim."
        },
        "detail": {
          "type": "string",
          "description": "What happened, for a person."
        },
        "passed_over": {
          "type": "array",
          "items": {
            "type": "integer",
            "format": "uint64",
            "minimum": 0
          },
          "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`)."
        },
        "head_after": {
          "type": [
            "string",
            "null"
          ],
          "description": "On `refreshed`: the head the executor pushed. The refresh pipeline waits only for\nthe checks of a head named here."
        },
        "evidence": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/IntegrationEvidence"
          },
          "description": "On `merge_attempted`, `merge_succeeded`, `refresh_selected` and the closures:\nthe assessment's evidence the act was decided on."
        },
        "class": {
          "anyOf": [
            {
              "$ref": "#/$defs/FailureClass"
            },
            {
              "type": "null"
            }
          ],
          "description": "On a failure: its class, once one is decided."
        },
        "merge_commit": {
          "type": [
            "string",
            "null"
          ],
          "description": "On `merge_succeeded`: the merge commit, once it is read."
        }
      },
      "required": [
        "at",
        "actor",
        "action",
        "reasons",
        "detail"
      ],
      "description": "One entry of the audit trail."
    },
    "IntegrationAction": {
      "oneOf": [
        {
          "type": "string",
          "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`)."
        }
      ],
      "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."
    },
    "IntegrationEvidence": {
      "type": "object",
      "properties": {
        "kind": {
          "$ref": "#/$defs/EvidenceKind",
          "description": "What kind of fact."
        },
        "status": {
          "type": "string",
          "description": "What it said, as a word."
        },
        "detail": {
          "type": "string",
          "description": "The detail a person reads."
        },
        "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."
        }
      },
      "required": [
        "kind",
        "status",
        "detail"
      ],
      "description": "One piece of evidence behind a disposition: what was read, where, and what it said."
    },
    "EvidenceKind": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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."
    },
    "EvidenceSource": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "observed_at": {
              "type": "string",
              "description": "When the forge was observed, RFC 3339."
            },
            "kind": {
              "type": "string",
              "const": "forge"
            }
          },
          "required": [
            "kind",
            "observed_at"
          ],
          "description": "The forge observation, at its moment."
        },
        {
          "type": "object",
          "properties": {
            "master_sha": {
              "type": "string",
              "description": "The master commit."
            },
            "head_sha": {
              "type": "string",
              "description": "The head commit."
            },
            "kind": {
              "type": "string",
              "const": "git"
            }
          },
          "required": [
            "kind",
            "master_sha",
            "head_sha"
          ],
          "description": "Git, on this pair of commits."
        }
      ],
      "description": "Where a piece of evidence was read."
    },
    "FailureClass": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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."
    }
  }
}

Examples

These are the capability's own benchmark cases: the same inputs the benchmark runs and the OpenAPI document shows.

default

{}