integration.trains
Every train of open pull requests — a group joined by confirmed dependencies: a base branch that is another open pull request's head, or a `Stacked on #N` / `Depends on #N` line in the body — in landing order. Per link: number, title, author, head and base branch, head commit, the forge's page and checks, disposition, lane, reasons, next action, required-check state and every check on the head, relation to master with how far behind it is and whether it carries master, the prepared head under refs/prep/<n> with whether it is the head the forge serves (pushed) or not yet (pending), its position and depth, whether its turn has come, what it stands on and what it carries, its queue rank and whether a cycle catches it. Per train: roots, tops, the next link the order allows, the edges (STACKED_ON or DEPENDS_ON, satisfied when the link below landed), and the pull requests beneath it that are no longer open. Beside them the prepared heads no train holds, the tallies and the queue's diagnostics. Read from the recorded observation, the queue `majordomus prs status` prints and the local refs: it fetches, pushes and moves nothing. `observed: false` with the reason when this checkout has recorded no observation.
Every train of open pull requests — a group joined by confirmed dependencies: a base branch that is another open pull request's head, or a `Stacked on #N` / `Depends on #N` line in the body — in landing order. Per link: number, title, author, head and base branch, head commit, the forge's page and checks, disposition, lane, reasons, next action, required-check state and every check on the head, relation to master with how far behind it is and whether it carries master, the prepared head under refs/prep/<n> with whether it is the head the forge serves (pushed) or not yet (pending), its position and depth, whether its turn has come, what it stands on and what it carries, its queue rank and whether a cycle catches it. Per train: roots, tops, the next link the order allows, the edges (STACKED_ON or DEPENDS_ON, satisfied when the link below landed), and the pull requests beneath it that are no longer open. Beside them the prepared heads no train holds, the tallies and the queue's diagnostics. Read from the recorded observation, the queue `majordomus prs status` prints and the local refs: it fetches, pushes and moves nothing. `observed: false` with the reason when this checkout has recorded no observation.
- query
- experimental
- module integration
- #integration
- #pull-requests
- #trains
- #graph
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_pull_request_trains |
| HTTP | GET /api/v1/pull-requests/trains operationId integration.trains |
| command line | majordomus prs trains |
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 · TrainsView
Every train of the observed queue, and why there is none when there is none.
| property | type | required | description |
|---|---|---|---|
| base | string | null | no | The integration base. |
| diagnostics | array | yes | What makes this answer less than a full one: the queue's own diagnostics (a stale observation first), and a dependency cycle when one is found. |
| master_sha | string | null | no | The master commit every link's relation was decided against. |
| observed | boolean | yes | Whether a forge observation is recorded in this checkout. |
| observed_at | string | null | no | When the forge was observed. |
| reason | string | null | no | Why there are no trains to show, when nothing is observed. |
| repository | string | null | no | owner/name, when observed. |
| tallies | reference | yes | Counts over every train. |
| trains | array | yes | Every train, the one whose next link ranks highest in the queue first. |
| unattached_prep | array | yes | Prepared heads under refs/prep/ whose pull request is no link of any train: open
and stacked on nothing, or not open at all (landed, closed). |
JSON Schema
{
"$defs": {
"BeneathLink": {
"description": "A pull request below a train that is not open any more.",
"properties": {
"number": {
"description": "Its number.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"state": {
"$ref": "#/$defs/DependencyState",
"description": "What the forge says became of it."
},
"url": {
"description": "The pull request on the forge, when the repository is known.",
"type": [
"string",
"null"
]
}
},
"required": [
"number",
"state"
],
"type": "object"
},
"CheckRunState": {
"description": "Where one check run stands.",
"oneOf": [
{
"const": "passed",
"description": "Completed and passed.",
"type": "string"
},
{
"const": "failed",
"description": "Completed and failed (failure, timed out, cancelled, action required).",
"type": "string"
},
{
"const": "pending",
"description": "Queued or running; also what a report that says nothing is taken to be, so a\ndefault is never a pass.",
"type": "string"
},
{
"const": "skipped",
"description": "Completed as skipped or neutral.",
"type": "string"
}
]
},
"DependencyState": {
"description": "What became of a pull request another one depends on.",
"oneOf": [
{
"const": "open",
"description": "Still open.",
"type": "string"
},
{
"const": "merged",
"description": "Merged: the only state that satisfies it.",
"type": "string"
},
{
"const": "closed_unmerged",
"description": "Closed without a merge: its work never landed, so a person decides.",
"type": "string"
},
{
"const": "unread",
"description": "Not open, and the forge could not say what became of it — refused, or not a pull\nrequest at all: unknown, never satisfied.",
"type": "string"
}
]
},
"IntegrationLane": {
"description": "The queues the Cockpit and the status table group pull requests into.",
"oneOf": [
{
"const": "ready",
"description": "The executor may merge it now.",
"type": "string"
},
{
"const": "waiting",
"description": "Something will happen without a person: a refresh, a check, a dependency.",
"type": "string"
},
{
"const": "repair",
"description": "A person must change the branch.",
"type": "string"
},
{
"const": "cleanup",
"description": "Its work is on master already, or a successor that landed replaced it.",
"type": "string"
},
{
"const": "held",
"description": "Not asking to be merged, held by a label or a setting, unsafe for the executor, or\nundecidable.",
"type": "string"
}
]
},
"LinkCheck": {
"description": "One check run on a link's head.",
"properties": {
"name": {
"description": "The check's name.",
"type": "string"
},
"state": {
"$ref": "#/$defs/CheckRunState",
"description": "Where it stands."
}
},
"required": [
"name",
"state"
],
"type": "object"
},
"PrepState": {
"description": "Whether a prepared head has reached the forge.",
"oneOf": [
{
"const": "pushed",
"description": "The prepared head is the pull request's head: it was pushed.",
"type": "string"
},
{
"const": "pending",
"description": "The prepared head is another commit: it waits for its turn to be pushed.",
"type": "string"
}
]
},
"PreparedHead": {
"description": "The head the executor prepared for a link under `refs/prep/<n>`.",
"properties": {
"reference": {
"description": "The ref.",
"type": "string"
},
"sha": {
"description": "The commit it names.",
"type": "string"
},
"state": {
"$ref": "#/$defs/PrepState",
"description": "Whether that commit is the head the forge serves."
}
},
"required": [
"reference",
"sha",
"state"
],
"type": "object"
},
"PullRequestDisposition": {
"description": "The one classification of an open pull request. Every value carries a machine-readable\nreason in `PullRequestAssessment::reasons`; there is no `mergeable: bool`.",
"oneOf": [
{
"const": "ready",
"description": "Contains the current master, every required check passed on its head, nothing\nblocks it: the executor may merge it.",
"type": "string"
},
{
"const": "needs_refresh",
"description": "Merges cleanly but does not contain master: the executor may bring master in (a\nmerge commit on the branch, never a rewrite), after which CI must run again.",
"type": "string"
},
{
"const": "waiting_for_checks",
"description": "Contains master; a required check has not finished on this head.",
"type": "string"
},
{
"const": "waiting_for_review",
"description": "A required review is missing or changes were requested.",
"type": "string"
},
{
"const": "waiting_for_dependency",
"description": "A declared dependency has not landed.",
"type": "string"
},
{
"const": "draft",
"description": "A draft.",
"type": "string"
},
{
"const": "needs_repair",
"description": "A required check failed on this head.",
"type": "string"
},
{
"const": "conflicting",
"description": "Conflicts on authored paths: a person resolves them.",
"type": "string"
},
{
"const": "blocked",
"description": "A label whose policy is to hold holds it, or the repository allows no merge commit,\nwhich is the only way the executor merges.",
"type": "string"
},
{
"const": "unsafe",
"description": "The forge has auto-merge armed on it: the forge would merge it on its own, outside the\nexecutor and against whatever master is then. Held until a person disarms it.",
"type": "string"
},
{
"const": "redundant",
"description": "Its head already landed, its merge changes nothing, or every one of its commits is on\nmaster as an equal patch: strong evidence from git, eligible for closure under policy.\n(Before 0.13 this was the word `superseded`.)",
"type": "string"
},
{
"const": "superseded",
"description": "A successor was declared for it by someone the repository lets declare one — an owner,\nmember or collaborator, in a pull request of this repository — and that successor\nlanded: git finds its head or its merge commit in master. The successor is\n`PullRequestAssessment::superseded_by`. Eligible for closure under policy.",
"type": "string"
},
{
"const": "possibly_redundant",
"description": "Weak evidence: only derived artifacts would change, or its declared successor was merged\nsomewhere master does not contain. Surfaced for a person; never closed automatically.",
"type": "string"
},
{
"const": "other_base",
"description": "Targets a branch other than the integration base.",
"type": "string"
},
{
"const": "unknown",
"description": "Something needed to decide could not be observed.",
"type": "string"
},
{
"const": "obsolete",
"description": "A person marked it obsolete with a label the label policy declares (owner decision\nD3): the only evidence that reaches this word. Listed for a person by cleanup and\nnever closed automatically; age, shared paths or a similar title never make one.",
"type": "string"
}
]
},
"RelationToMaster": {
"description": "What the pull request's head is to the current master, decided locally by git with\nthis repository's own merge drivers — never by the forge's `mergeable`, which cannot\nrun the derived-file driver and calls nearly every pull request here conflicting.",
"oneOf": [
{
"description": "The head is an ancestor of master: every commit already landed.",
"properties": {
"kind": {
"const": "contained",
"type": "string"
}
},
"required": [
"kind"
],
"type": "object"
},
{
"description": "Merging the head into master changes nothing: its patch is already fully there.",
"properties": {
"kind": {
"const": "superseded",
"type": "string"
}
},
"required": [
"kind"
],
"type": "object"
},
{
"description": "The merge would conflict or change only derived output, but every commit the head has\nand master lacks is on master already as an equal patch (`git cherry` marks each `-`):\nthe change landed, and master moved on past it. Never a partial match, and never a\nhead that carries a merge commit of its own, whose resolution has no patch to compare.",
"properties": {
"commits": {
"description": "How many commits, every one of them already on master.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"kind": {
"const": "patch_ids_upstream",
"type": "string"
}
},
"required": [
"kind",
"commits"
],
"type": "object"
},
{
"description": "Merging changes only derived artifacts: the authored change is already on master,\nand what differs is output the generators rewrite.",
"properties": {
"kind": {
"const": "derived_only",
"type": "string"
},
"paths": {
"description": "The derived paths that would change.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"kind",
"paths"
],
"type": "object"
},
{
"description": "The head already contains master and merges cleanly.",
"properties": {
"authored": {
"description": "Authored (non-derived) paths the merge changes.",
"items": {
"type": "string"
},
"type": "array"
},
"kind": {
"const": "up_to_date",
"type": "string"
},
"owes_version": {
"description": "The version a landing of this head allocates, when master allocates at landing\n(ADR 0134) and the head does not carry it: the head owes a refresh even though it\ncontains master. Absent when the policy does not allocate, or the head carries it.",
"type": [
"string",
"null"
]
}
},
"required": [
"kind",
"authored"
],
"type": "object"
},
{
"description": "The head does not contain master, yet master holds nothing the head lacks: merging it\nwrites the head's own tree, and every commit master has beyond it is a merge commit.\nThat is a head stacked on a pull request that has since landed. A verdict on the head\nis then a verdict on what master becomes, tree and listed history alike, exactly as\nwhen the head contains master; and no path is merged at all, so the forge needs no\ndriver for it.",
"properties": {
"authored": {
"description": "Authored (non-derived) paths the merge changes.",
"items": {
"type": "string"
},
"type": "array"
},
"behind": {
"description": "Commits on master the head does not have.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"kind": {
"const": "carries_master",
"type": "string"
}
},
"required": [
"kind",
"behind",
"authored"
],
"type": "object"
},
{
"description": "The head does not contain master, but the merge is clean with the derived driver.",
"properties": {
"authored": {
"description": "Authored paths the merge changes.",
"items": {
"type": "string"
},
"type": "array"
},
"behind": {
"description": "Commits on master the head does not have.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"kind": {
"const": "behind",
"type": "string"
}
},
"required": [
"kind",
"behind",
"authored"
],
"type": "object"
},
{
"description": "Merging conflicts on authored paths: a person must resolve it.",
"properties": {
"kind": {
"const": "conflicting",
"type": "string"
},
"paths": {
"description": "The conflicting authored paths.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"kind",
"paths"
],
"type": "object"
},
{
"description": "Git could not answer (the head is not fetched, or git failed); the reason.",
"properties": {
"kind": {
"const": "unknown",
"type": "string"
},
"reason": {
"description": "Why.",
"type": "string"
}
},
"required": [
"kind",
"reason"
],
"type": "object"
}
]
},
"RequiredCheckState": {
"description": "The state of the repository's *required* checks on one head, which is the only check\nstate a merge decision reads. A visible green check that is not required proves nothing,\nand a required check that is absent is not a pass.",
"oneOf": [
{
"const": "passed",
"description": "Every required check passed on this head.",
"type": "string"
},
{
"const": "skipped",
"description": "Every required check passed, at least one of them by a skip the policy permits for\nthat context. A skip the policy does not permit is not a pass: it is `missing`.",
"type": "string"
},
{
"const": "pending",
"description": "A required check is queued or running.",
"type": "string"
},
{
"const": "failed",
"description": "A required check failed.",
"type": "string"
},
{
"const": "missing",
"description": "A required check has not reported on this head at all.",
"type": "string"
},
{
"const": "unknown",
"description": "The repository's required checks could not be read.",
"type": "string"
}
]
},
"Train": {
"description": "One train: open pull requests joined by confirmed dependencies, in the order they land.",
"properties": {
"beneath": {
"description": "The pull requests below the train that are no longer open — landed, closed without a\nmerge, or unread — which a link still declares.",
"items": {
"$ref": "#/$defs/BeneathLink"
},
"type": "array"
},
"by_disposition": {
"additionalProperties": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"description": "Links by disposition word.",
"type": "object"
},
"edges": {
"description": "Every confirmed dependency of a link, upper link first.",
"items": {
"$ref": "#/$defs/TrainEdge"
},
"type": "array"
},
"id": {
"description": "`train-<n>`, after the first root in turn order: stable while that link is open.",
"type": "string"
},
"links": {
"description": "Every open link, in turn order — `TrainLink::position` 1 first.",
"items": {
"$ref": "#/$defs/TrainLink"
},
"type": "array"
},
"next": {
"description": "The first link, in turn order, whose every dependency has landed: the train's next\nmerge as far as order is concerned (its disposition says whether it can merge now).",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"roots": {
"description": "The links that land first: no open link of the train is below them.",
"items": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"type": "array"
},
"tops": {
"description": "The links at the top: no link of the train is stacked on them.",
"items": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"type": "array"
}
},
"required": [
"id",
"roots",
"tops",
"links",
"edges",
"beneath",
"by_disposition"
],
"type": "object"
},
"TrainEdge": {
"description": "A confirmed dependency between two pull requests of a train.",
"properties": {
"from": {
"description": "The upper link: the one that depends.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"kind": {
"$ref": "#/$defs/TrainEdgeKind",
"description": "How the dependency is declared."
},
"satisfied": {
"description": "Whether it is satisfied: the pull request below landed.",
"type": "boolean"
},
"to": {
"description": "The pull request it stands on.",
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"from",
"to",
"kind",
"satisfied"
],
"type": "object"
},
"TrainEdgeKind": {
"description": "How a dependency between two links is declared.",
"oneOf": [
{
"const": "stacked_on",
"description": "Its base branch is the other's head, or its body says `Stacked on #N`.",
"type": "string"
},
{
"const": "depends_on",
"description": "Its body says `Depends on #N`, `Requires #N` or `Land after #N`.",
"type": "string"
}
]
},
"TrainLink": {
"description": "One open pull request as a link of a train.",
"properties": {
"at_turn": {
"description": "Every dependency it declares has landed: it is the link the order allows next.",
"type": "boolean"
},
"author": {
"description": "Its author's login.",
"type": "string"
},
"base_ref": {
"description": "The branch it targets: the integration base, or the head of the link below.",
"type": "string"
},
"behind": {
"description": "How many master commits its head lacks, when the relation counts them.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"carries": {
"description": "The links stacked on it.",
"items": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"type": "array"
},
"carries_master": {
"description": "Whether its head carries master by a merge of its own (ADR 0129) — read from the\nrelation's word, so an executable that does not know that relation says `false`.",
"type": "boolean"
},
"checks": {
"description": "Every check the forge reported on its head, required or not.",
"items": {
"$ref": "#/$defs/LinkCheck"
},
"type": "array"
},
"checks_url": {
"description": "Its checks on the forge, when the repository is known.",
"type": [
"string",
"null"
]
},
"depth": {
"description": "How many links are below it on its longest path to master; a root is 0.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"disposition": {
"$ref": "#/$defs/PullRequestDisposition",
"description": "The executor's classification."
},
"head_ref": {
"description": "Its head branch.",
"type": "string"
},
"head_sha": {
"description": "The head commit it was assessed at, as the forge served it.",
"type": "string"
},
"in_cycle": {
"description": "Caught in a cycle of confirmed dependencies: no link of the cycle can land first.",
"type": "boolean"
},
"lane": {
"$ref": "#/$defs/IntegrationLane",
"description": "The lane that disposition belongs to."
},
"next_action": {
"description": "What happens next, in words, when anything does.",
"type": [
"string",
"null"
]
},
"number": {
"description": "The pull request number.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"on": {
"description": "The pull requests it stands on, open links and those beneath alike.",
"items": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"type": "array"
},
"position": {
"description": "Its turn in the train, 1-based: every link below it comes earlier.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"prep": {
"anyOf": [
{
"$ref": "#/$defs/PreparedHead"
},
{
"type": "null"
}
],
"description": "The head the executor prepared for it, when `refs/prep/<n>` exists."
},
"rank": {
"description": "Its rank in the queue, 1-based.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"reasons": {
"description": "The machine-readable reasons, as every surface spells them (`stacked_on:#<number>`).",
"items": {
"type": "string"
},
"type": "array"
},
"relation": {
"$ref": "#/$defs/RelationToMaster",
"description": "What its head is to master, decided by git."
},
"relation_kind": {
"description": "That relation's word (`behind`, `up_to_date`, `carries_master`, ...).",
"type": "string"
},
"required_checks": {
"$ref": "#/$defs/RequiredCheckState",
"description": "The required checks on its head."
},
"title": {
"description": "Its title.",
"type": "string"
},
"url": {
"description": "The pull request on the forge, when the repository is known.",
"type": [
"string",
"null"
]
}
},
"required": [
"number",
"title",
"author",
"head_ref",
"base_ref",
"head_sha",
"disposition",
"lane",
"reasons",
"required_checks",
"checks",
"relation",
"relation_kind",
"carries_master",
"position",
"depth",
"at_turn",
"on",
"carries",
"rank",
"in_cycle"
],
"type": "object"
},
"TrainTallies": {
"description": "Counts over every train.",
"properties": {
"by_disposition": {
"additionalProperties": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"description": "Links by disposition word.",
"type": "object"
},
"links": {
"description": "Open links across every train.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"pending_prep": {
"description": "Links whose prepared head is not the head the forge serves.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"trains": {
"description": "Trains.",
"format": "uint",
"minimum": 0,
"type": "integer"
}
},
"required": [
"trains",
"links",
"pending_prep",
"by_disposition"
],
"type": "object"
},
"UnattachedPrep": {
"description": "A prepared head whose pull request is no link of any train.",
"properties": {
"number": {
"description": "The pull request the ref is named for.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"open": {
"description": "Whether that pull request is open.",
"type": "boolean"
},
"sha": {
"description": "The commit it names.",
"type": "string"
}
},
"required": [
"number",
"sha",
"open"
],
"type": "object"
}
},
"description": "Every train of the observed queue, and why there is none when there is none.",
"properties": {
"base": {
"description": "The integration base.",
"type": [
"string",
"null"
]
},
"diagnostics": {
"description": "What makes this answer less than a full one: the queue's own diagnostics (a stale\nobservation first), and a dependency cycle when one is found.",
"items": {
"type": "string"
},
"type": "array"
},
"master_sha": {
"description": "The master commit every link's relation was decided against.",
"type": [
"string",
"null"
]
},
"observed": {
"description": "Whether a forge observation is recorded in this checkout.",
"type": "boolean"
},
"observed_at": {
"description": "When the forge was observed.",
"type": [
"string",
"null"
]
},
"reason": {
"description": "Why there are no trains to show, when nothing is observed.",
"type": [
"string",
"null"
]
},
"repository": {
"description": "`owner/name`, when observed.",
"type": [
"string",
"null"
]
},
"tallies": {
"$ref": "#/$defs/TrainTallies",
"description": "Counts over every train."
},
"trains": {
"description": "Every train, the one whose next link ranks highest in the queue first.",
"items": {
"$ref": "#/$defs/Train"
},
"type": "array"
},
"unattached_prep": {
"description": "Prepared heads under `refs/prep/` whose pull request is no link of any train: open\nand stacked on nothing, or not open at all (landed, closed).",
"items": {
"$ref": "#/$defs/UnattachedPrep"
},
"type": "array"
}
},
"required": [
"observed",
"trains",
"unattached_prep",
"tallies",
"diagnostics"
],
"title": "TrainsView",
"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.