HTTP API: integration

Every open pull request classified against the current master — ready, needs refresh, waiting for checks, review or a dependency, draft, needs repair, conflicting, blocked, unsafe (auto-merge armed), redundant (its work is on master already), superseded (by a declared successor that landed, named in superseded_by), possibly redundant, other base or unknown — each with the master and head it was decided against, its reasons, its evidence, its risk and its overlaps, ranked deterministically; and the audit trail of the executor that merges the next provably safe one, one at a time. The relation to master is decided by git with this repository's own merge drivers, because the forge cannot run the derived-file driver. Read from the last recorded forge observation; the one exception is the dry-run proof, which observes the forge itself because the observation is part of what it proves moves nothing.

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

integration

GET /api/v1/pull-requests integration.queue

The integration queue

The ranked queue: the repository, the base and the master commit every assessment was decided against, when the forge was observed, the policy in force (the branch protection's required checks and reviews, the label policy, the merge method: a merge commit, or none when the repository allows none), every open pull request's assessment in rank order — an actionable one with how long it has waited for the executor and how often another was chosen instead — the next merge, the pull requests that need master brought in, the starving ones, the tallies by disposition and lane, and the diagnostics, a stale observation first; beside it, who holds the base branch's integration lease and the last merge the executor recorded. `observed: false` with the reason when this checkout has recorded no observation.

query
experimental
benchmark required
cache disabled
MCP tool majordomus_pull_requests
$ prs status

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/pull-requests"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	IntegrationStatus	The integration queue: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/pull-requests/cleanup integration.cleanup

What cleanup would do

The cleanup plan, decided offline from the recorded observation: every open pull request cleanup would close — redundant (its work is on master already) or superseded (by a declared successor that landed) — and every one it leaves for a person — possibly redundant (weak evidence) or obsolete (a person marked it, owner decision D3) — each with its disposition and the reasons that decided it, in rank order; beside it, the branches merged pull requests left on origin as `majordomus prs cleanup` last read them, with when and how long ago. A read: it closes, deletes and asks the forge for nothing — `majordomus prs cleanup` reads the forge and `--apply` closes. `observed: false` with the reason when this checkout has recorded no observation.

query
experimental
benchmark required
cache disabled
MCP tool majordomus_pull_requests_cleanup

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/pull-requests/cleanup"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	IntegrationCleanup	What cleanup would do: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/pull-requests/events integration.events

The integration audit trail

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
benchmark required
cache disabled
MCP tool majordomus_integration_events
$ prs events

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/pull-requests/events"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	IntegrationEvents	The integration audit trail: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/pull-requests/explain integration.explain

Why one pull request is where it is

One pull request's assessment — disposition, lane, reasons, every gate of the policy with whether it passed, next action, the master and head it was decided against and when the forge was observed, required checks, review, relation to master, dependencies, overlaps, risk with its factors, and every piece of evidence — with its rank in the queue. `found: false` with the reason when it is not open or nothing is observed.

query
experimental
benchmark required
cache disabled
MCP tool majordomus_pull_request_explain
$ prs explain

Query parameters

name	type	required	description	examples
number	integer (uint64)	yes	The pull request number.	a-number: 1

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/pull-requests/explain?number=1"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	IntegrationExplanation	Why one pull request is where it is: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/pull-requests/prove-dry-run integration.prove_dry_run

Proof that a dry run moves nothing

Runs the executor's non-mutating cycle — refresh, plan, drain --dry-run and cleanup without --apply — between two snapshots of everything it could move if it were wrong: every ref origin serves, every open pull request's number, head, state and labels, the integration audit trail, the executor's lease, and every local ref outside the two namespaces the refresh mirrors. `ok` is true exactly when the snapshots are equal and refs/remotes/origin/<base> and every refs/majordomus/prs/<n> equal what origin serves. A read that reaches the network: the refresh asks the forge through the GitHub CLI and fetches the base and the pull-request heads, and like every read it rewrites the observation, relation and summary caches. It merges, closes and pushes nothing, and takes no input that could make it.

query
experimental
benchmark waived: external_dependency
cache disabled
MCP tool majordomus_pull_requests_prove_dry_run
$ prs prove-dry-run

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/pull-requests/prove-dry-run"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	DryRunProof	Proof that a dry run moves nothing: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/pull-requests/timings integration.timings

How long CI takes

How long CI takes on the open pull requests, measured from the recorded forge observation: for every check, how many of its runs started and completed, how many passed and failed, and its median, 90th percentile (nearest rank) and longest duration in seconds, the slowest median first; for every open head with a measured check, the wall time from its first check's start to its last check's completion and the check that took longest, the longest wait first; and how many runs could not be measured (still running, queued, or recorded before starts were read), which are counted and never measured as zero. A read: it asks the forge for nothing; `majordomus prs refresh` records the observation. `observed: false` with the reason when this checkout has recorded none.

query
experimental
benchmark required
cache disabled
MCP tool majordomus_ci_timings

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/pull-requests/timings"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	IntegrationTimings	How long CI takes: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/pull-requests/trains integration.trains

The trains of stacked pull requests

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
benchmark required
cache disabled
MCP tool majordomus_pull_request_trains
$ prs trains

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/pull-requests/trains"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	TrainsView	The trains of stacked pull requests: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

BeneathLink

object

A pull request below a train that is not open any more.

property	type	required	description
number	integer (uint64)	yes	Its number.
state	DependencyState → DependencyState	yes	What the forge says became of it.
url	string \| null	no	The pull request on the forge, when the repository is known.

Used by Train

ChangeShape

object

What a head's merge into master changes, by kind: the authored paths a person wrote, the derived paths a generator writes (by the repository's merge=derived attributes on master), and the version the head declares when it raises the crate's. Decided from the same pair of commits as the relation to master, and cached under the same key beside it, so a change of either commit — a .gitattributes change on master is one — makes both stale together.

property	type	required	description
authored	array of string	yes	Authored (non-derived) paths the merge changes or conflicts on, in path order.
derived	array of string	yes	Derived paths the merge changes or conflicts on, in path order.
version_bump	string \| null	no	The version the head declares in the crate manifest, when it is not the one its merge base declares: the head raises the version.

Used by PullRequestAssessment

CheckRunState

"passed" | "failed" | "pending" | "skipped"

Where one check run stands.

passedCompleted and passed.
failedCompleted and failed (failure, timed out, cancelled, action required).
pendingQueued or running; also what a report that says nothing is taken to be, so a default is never a pass.
skippedCompleted as skipped or neutral.

Used by LinkCheck

CheckTiming

object

How one check takes, across the open heads that ran it.

property	type	required	description
name	string	yes	The check's name, as the forge reports it.
runs	integer (uint64)	yes	Runs that started and completed, so were measured.
passed	integer (uint64)	yes	Of those, how many passed.
failed	integer (uint64)	yes	Of those, how many failed.
median_seconds	integer (uint64)	yes	The median duration, in seconds.
p90_seconds	integer (uint64)	yes	The 90th percentile duration (nearest rank), in seconds.
slowest_seconds	integer (uint64)	yes	The longest run, in seconds.

Used by CiTimings

CiTimings

object

CI timings over every open head the observation holds.

property	type	required	description
observed_at	string	yes	When the forge was observed, RFC 3339: the moment these timings describe.
measured_runs	integer (uint64)	yes	Check runs measured, across every check and head.
unmeasured_runs	integer (uint64)	yes	Check runs the observation holds without both a start and a completion: running, queued, or recorded before starts were read. Counted, never measured as zero.
checks	array of CheckTiming → CheckTiming	yes	Every check, the slowest median first.
heads	array of HeadTiming → HeadTiming	yes	Every head with a measured check, the longest wall time first.

Used by IntegrationTimings

CleanupItem

object

What cleanup would do, or did, for one pull request.

property	type	required	description
pr	integer (uint64)	yes	The pull request.
disposition	PullRequestDisposition → PullRequestDisposition	yes	Its disposition when decided.
reasons	array of string	yes	The evidence, as reason codes.
action	string	yes	`would_close`, `closed`, `left_for_a_person`, or `close_failed: <why>`.

Used by IntegrationCleanup

DependencyCertainty

"confirmed" | "inferred"

How a dependency is known. Only a declared one blocks.

confirmedDeclared: a Depends on #N / Stacked on #N line in the body, or a base branch that is another open pull request's head.
inferredInferred: the head contains the other's head commit. Evidence, never a block.

Used by PullRequestDependency

DependencyState

"open" | "merged" | "closed_unmerged" | "unread"

What became of a pull request another one depends on.

openStill open.
mergedMerged: the only state that satisfies it.
closed_unmergedClosed without a merge: its work never landed, so a person decides.
unreadNot open, and the forge could not say what became of it — refused, or not a pull request at all: unknown, never satisfied.

Used by BeneathLink PullRequestDependency

DryRunProof

object

The verdict: what was compared, what moved, and what the cycle observed.

property	type	required	description
ok	boolean	yes	True exactly when nothing moved and every mirror equals what origin serves.
base	string	yes	The base branch the executor works on.
steps	array of ProofStep → ProofStep	yes	The cycle, step by step.
moved	array of Moved → Moved	yes	Every line that differs between the snapshots; empty when nothing moved.
mirrors	array of string	yes	Every mirrored ref that is not what origin serves; empty when they all are.
before	Snapshot → Snapshot	yes	The snapshot before the cycle.
after	Snapshot → Snapshot	yes	The snapshot after it.
classification	array of ObservedClassification → ObservedClassification	yes	Every open pull request as the cycle classified it, in rank order.

Used by integration.prove_dry_run

EvaluatedAgainst

object

The revisions a decision was taken against, and when the forge was observed. A decision is valid only while both revisions still hold: the executor compares them with what it re-reads before it acts.

property	type	required	description
master_sha	string	yes	The master commit.
head_sha	string	yes	The pull request's head commit.
observed_at	string	no	When the forge was observed, RFC 3339; empty in a value written before it was named.

Used by PullRequestAssessment

EvidenceKind

What kind of fact a piece of evidence is. The wire words are the ones the evidence carried while its kind was a string, so a trail written then still reads.

required_checkOne required check's state on the head: one entry per context the base requires.
required_checksThe required checks together: their verdict, and each context's state.
reviewThe review policy and the forge's decision, or one reviewer's latest review.
relation_to_masterWhat the head is to master, as git decided it.
dependencyOne declared dependency.
labelOne label whose policy is to hold.
draftWhether it is a draft; always emitted.
baseThe branch it targets; always emitted.
freshnessHow old the observation is. Declared so the vocabulary is settled; nothing emits it yet.
auto_mergeThe forge has auto-merge armed; emitted whenever it is.
supersessionOne declared successor: which pull request replaces this one, whose body said so, and whether it landed. One entry per authorised successor (status open, landed, not_landed or unread), one per declaration nobody entitled made (possible_supersession), and one when the pull requests that mention it were not all read (references_truncated, references_unread).
repository_settingsWhat the repository's settings allow the executor; emitted when they allow no merge commit.

Used by IntegrationEvidence

EvidenceSource

one of 2 variants

Where a piece of evidence was read.

variant The forge observation, at its moment.

observed_at	string	yes	When the forge was observed, RFC 3339.
kind	"forge"	yes

variant Git, on this pair of commits.

master_sha	string	yes	The master commit.
head_sha	string	yes	The head commit.
kind	"git"	yes

Used by IntegrationEvidence

ExecutorWait

object

How long a pull request has waited for the executor, from the audit trail. Starvation is made visible here, never resolved by changing the rank: the rank's age tie-break already prefers the older of two otherwise equal candidates, and a wait this long is a fact a person reads, not a reason to merge anything less safe.

property	type	required	description
actionable_since	string	yes	When it was first observed ready or refreshable in its current run of being so, RFC 3339.
passed_over	integer (uint32)	yes	How many times the executor selected another pull request while this one was ready or refreshable.
last_passed_over	PassedOver \| null → PassedOver	no	The last of those times.

Used by PullRequestAssessment

FailureClass

Why an act failed, as one class a person and a retry policy can act on. Every failed act on the trail carries one (class), and the drain decides from it whether the next candidate may be tried (FailureClass::recoverable) or the drain must stop.

staleMaster or the head moved since the decision.
conflictThe merge of master conflicts.
new_failing_checkA required check failed that had passed.
review_revokedAn approval was withdrawn.
transientThe forge or the network failed in a way that passes.
policy_violationThe branch protection refused it.
verification_failedWhat landed could not be verified.
unreadableThe forge or git could not be read.

Used by IntegrationEvent

GateResult

object

How one gate answered.

property	type	required	description
gate	IntegrationGate → IntegrationGate	yes	The gate.
passed	boolean	yes	Whether it passed. A gate that fails only because an earlier one did (the head is not fresh when its merge conflicts) fails without a reason of its own.

Used by PullRequestAssessment

HeadTiming

object

How long CI took on one open pull request's head: from its first check's start to its last check's completion, and the check that took longest.

property	type	required	description
number	integer (uint64)	yes	The pull request.
head_sha	string	yes	The head the checks ran on.
started_at	string	yes	When its first measured check started, RFC 3339.
completed_at	string	yes	When its last measured check completed, RFC 3339.
wall_seconds	integer (uint64)	yes	The wall time between them, in seconds: what a reader waited for CI on this head.
slowest_check	string	yes	The measured check that took longest.
slowest_seconds	integer (uint64)	yes	How long it took, in seconds.
failed	boolean	yes	Whether any measured check on the head failed.

Used by CiTimings

IntegrationAction

What one line of the audit trail records. The wire word is the variant's snake_case name — the same word each was written as while the action was a string — so every line written before still parses, and a word nobody writes is not an action.

lease_acquiredThe executor took the base branch's lease.
lease_releasedIt gave the lease back.
continuous_startedA continuous drain started.
continuous_stoppedA continuous drain stopped; the detail says why.
observedThe forge was observed and the observation recorded.
became_actionableA pull request became actionable (ready or refreshable).
left_actionableA pull request stopped being actionable.
selectedThe first ready pull request was chosen to merge.
refresh_selectedThe first refreshable pull request was chosen to bring master into.
stale_decisionThe decision went stale between planning and acting; nothing was done.
merge_attemptedA merge is about to be asked of the forge.
merge_succeededThe merge landed and was verified.
merge_failedThe forge refused the merge.
verification_failedWhat landed could not be verified.
failure_acknowledgedA person looked at a merge that could not be verified and lets drains merge again (prs drain --resume-after-failure).
refresh_attemptedMaster is about to be merged into a branch and pushed.
refreshedMaster was brought into the branch and pushed.
refresh_failedBringing master in failed.
close_attemptedA redundant or superseded pull request is about to be closed.
closed_redundantA redundant one was closed.
closed_supersededA superseded one was closed (before 0.13, a line with this word recorded what is now closed_redundant).
close_failedClosing it failed.
reopen_attemptedA record pull request the workflow's token opened is about to be closed and reopened, so that a run of its own starts (RecordStanding::Reopenable).
reopenedIt was closed and reopened; its required check can report now.
reopen_failedReopening it failed; the detail says whether the pull request was left closed.
repair_selectedA person named a pull request to repair (prs repair --apply) and its classification makes it eligible: master is what it lacks, and nothing authored conflicts.
repair_attemptedMaster is about to be merged into the named branch and pushed.
repairedMaster was brought into the named branch and pushed.
repair_refusedThe repair was refused — by the classification (an authored conflict, a fork, armed auto-merge, another base, an undecidable relation) or by the act (a merge, derive, commit or push that failed) — and nothing reached the branch; class says why.
idleNothing was ready.
observe_failedA continuous drain's cycle could not observe the forge, and the outage was short enough to wait out (CONTINUOUS_TRANSIENT_LIMIT).

Used by IntegrationEvent PassedOver

IntegrationCleanup

object

What cleanup would do, decided offline: the pull requests it would close or leave for a person, from the recorded observation, and the last branch report prs cleanup recorded.

property	type	required	description
observed	boolean	yes	Whether a forge observation is recorded in this checkout.
reason	string \| null	no	Why there is no plan, when there is none.
observed_at	string \| null	no	When the forge was observed, when it was.
items	array of CleanupItem → CleanupItem	yes	The plan, in rank order: `would_close` for what is provably on master or superseded by a successor that landed, `left_for_a_person` for weak evidence and for what a person marked obsolete. Nothing here closes anything.
branches	LeftBranchReport \| null → LeftBranchReport	no	The branches merged pull requests left on origin, as `prs cleanup` last read them; `None` when it never ran in this checkout. Never read from the network here.
branches_age_seconds	integer \| null	no	How old that report is, in seconds, when its time reads.

Used by integration.cleanup

IntegrationEvent

object

One entry of the audit trail.

property	type	required	description
at	string	yes	When, RFC 3339.
actor	string	yes	Who: the git identity, the process and the machine.
action	IntegrationAction → IntegrationAction	yes	What (`IntegrationAction`).
pr	integer \| null	no	The pull request, when one.
master_before	string \| null	no	Master before.
head_sha	string \| null	no	The head acted on.
master_after	string \| null	no	Master after.
reasons	array of string	yes	The decision's reasons; a code an older executor wrote reads back verbatim.
detail	string	yes	What happened, for a person.
passed_over	array of integer (uint64)	no	On a selection: the other actionable pull requests the executor chose this one over, in rank order. The wait of each is folded from it (`super::wait`).
head_after	string \| null	no	On `refreshed`: the head the executor pushed. The refresh pipeline waits only for the checks of a head named here.
evidence	array of IntegrationEvidence → IntegrationEvidence	no	On `merge_attempted`, `merge_succeeded`, `refresh_selected` and the closures: the assessment's evidence the act was decided on.
class	FailureClass \| null → FailureClass	no	On a failure: its class, once one is decided.
merge_commit	string \| null	no	On `merge_succeeded`: the merge commit, once it is read.

Used by IntegrationEvents IntegrationStatus

IntegrationEvents

object

The audit trail.

property	type	required	description
events	array of IntegrationEvent → IntegrationEvent	yes	Every recorded integration action, oldest first.

Used by integration.events

IntegrationEvidence

object

One piece of evidence behind a disposition: what was read, where, and what it said.

property	type	required	description
kind	EvidenceKind → EvidenceKind	yes	What kind of fact.
status	string	yes	What it said, as a word.
detail	string	yes	The detail a person reads.
source	EvidenceSource \| null → EvidenceSource	no	Where it was read. Every assessment names it; a trail line written before evidence carried it has none.

Used by IntegrationEvent PullRequestAssessment

IntegrationExplanation

object

One pull request's assessment and rank, or why it has none.

property	type	required	description
found	boolean	yes	Whether the pull request is in the observed queue.
reason	string \| null	no	Why not, when not.
rank	integer \| null	no	Its position in the ranked queue, 1-based.
of	integer (uint)	yes	How many open pull requests were ranked.
observed_at	string \| null	no	When the forge was observed.
assessment	PullRequestAssessment \| null → PullRequestAssessment	no	The assessment.

Used by integration.explain

IntegrationGate

One question of the policy, in the order IntegrationGate::ALL asks them. The disposition is the first that fails; every one is answered.

baseIt targets the integration base.
draftIt is not a draft.
labelIt carries no label whose policy is to hold.
auto_mergeThe forge has no auto-merge armed on it.
supersessionNo authorised successor is declared to replace it, and the pull requests that mention it were all read. Asked before the relation to master, because a pull request whose successor landed usually conflicts with what the successor brought, and is superseded rather than conflicting. A declaration nobody entitled made does not fail it.
relation_to_masterIts head is not on master already, and git could say that it merges cleanly.
merge_methodThe repository allows a merge commit, the only way the executor merges. Asked after the relation, so work already on master is still redundant and may be closed.
dependencyEvery declared dependency has landed.
reviewThe review policy is satisfied on the head.
no_failing_checkNo required check failed on the head.
freshnessThe head contains the current master.
required_checksEvery required check passed on the head.

Used by GateResult

IntegrationLane

"ready" | "waiting" | "repair" | "cleanup" | "held"

The queues the Cockpit and the status table group pull requests into.

readyThe executor may merge it now.
waitingSomething will happen without a person: a refresh, a check, a dependency.
repairA person must change the branch.
cleanupIts work is on master already, or a successor that landed replaced it.
heldNot asking to be merged, held by a label or a setting, unsafe for the executor, or undecidable.

Used by PullRequestAssessment RankFactors TrainLink

IntegrationLeaseState

object

The lease of a base as an observer reads it.

property	type	required	description
holder	LeaseHolder \| null → LeaseHolder	no	Who holds it; `None` when the file does not say in a form this reads.
renewed_seconds_ago	integer (uint64)	yes	How long ago the holder last renewed it.
stale	boolean	yes	Whether it is older than `LEASE_STALE_AFTER`: its holder stopped without releasing it, and the next executor takes it over.

Used by IntegrationStatus

IntegrationPolicy

object

What the repository requires before a merge, as observed from the forge and the repository — never a list kept here beside it.

property	type	required	description
base	string	yes	The branch integrated into.
required_checks	array \| null → RequiredCheck	no	The checks the base requires, from its branch protection and rulesets, each with the app bound to it. `None` when they could not be read: every required-check verdict is then `unknown`, never `passed`. An empty set is unknown too (owner decision D5): a base that requires nothing proves nothing about a head, so nothing merges onto it.
review_policy	ReviewPolicy \| null → ReviewPolicy	no	What the base requires of reviews; `None` when unread.
skipped_permitted	array of string	no	Contexts whose skip counts as a pass. Empty unless a repository says otherwise: a skipped required check is otherwise `missing`.
labels	array of LabelPolicy → LabelPolicy	yes	The labels that have an effect, each with its effect: `LABEL_POLICY`, copied.
merge_method	string \| null	no	The merge method the executor asks the forge for: `merge` when the repository allows a merge commit, and `None` when it does not. There is no other: the derived-file driver resolves merges, and a squash or rebase would replay commits it never saw, so with `None` every pull request the relation to master does not already decide is held (`merge_commit_not_allowed`), never merged otherwise.
up_to_date_required	boolean \| null	no	Whether the base requires a branch to be up to date before it merges (the protection's `required_status_checks.strict`, or a ruleset's): the forge-side half of the guard against a merge onto a master nobody tested with the change. The executor's half is its parent check after every merge. `Some(false)` is the owner's to change (decision D8) and decides no disposition; `None` when unread.

Used by IntegrationQueue

IntegrationQueue

object

The integration queue: every open pull request assessed against one master, ranked.

property	type	required	description
repository	string	yes	`owner/name`.
base	string	yes	The integration base.
master_sha	string	yes	The master commit every assessment was decided against (this clone's fetched ref).
observed_at	string	yes	When the forge was observed.
observed_base_sha	string	yes	The base commit the forge reported at that moment.
policy	IntegrationPolicy → IntegrationPolicy	yes	The policy in force.
assessments	array of PullRequestAssessment → PullRequestAssessment	yes	Every open pull request, in rank order: the first `ready` one is the next merge.
next_merge	integer \| null	no	The next merge, when anything is ready.
next_refresh	array of integer (uint64)	yes	The pull requests the executor could refresh (bring master in), in rank order.
tallies	QueueTallies → QueueTallies	yes	Counts.
diagnostics	array of string	yes	What makes this queue less than a full answer.
starving	array of integer (uint64)	no	The actionable pull requests the executor has passed over at least `wait::STARVING_AFTER` times in their current wait, in rank order. Visible, never promoted: see `wait`.

Used by IntegrationStatus

IntegrationRisk

"low" | "medium" | "high"

How much could go wrong if this lands and something was missed. Planning information: it orders work and it never relaxes a policy.

lowDocumentation, tests, content.
mediumCode of the executable or the tool.
highCI, release, governance, schemas, or a large change.

Used by PullRequestAssessment RankFactors

IntegrationStatus

object

The queue, or why there is none.

property	type	required	description
observed	boolean	yes	Whether a forge observation is recorded in this checkout.
reason	string \| null	no	Why there is no queue, when there is none.
queue	IntegrationQueue \| null → IntegrationQueue	no	The queue.
lease	IntegrationLeaseState \| null → IntegrationLeaseState	no	The base branch's integration lease as an observer reads it: `None` when nobody holds it (or nothing is observed, so no base is known).
last_merge	IntegrationEvent \| null → IntegrationEvent	no	The last merge the executor recorded, from the audit trail.
throughput	IntegrationThroughput → IntegrationThroughput	yes	How fast the executor has turned work into master over the last `THROUGHPUT_WINDOW_DAYS` days, folded from the same trail.

Used by integration.queue

IntegrationThroughput

object

The integrator's throughput over a window of the trail.

property	type	required	description
window_days	integer (uint64)	yes	The window, in days, ending at the time the fold was asked for.
merges	integer (uint64)	yes	Pull requests merged in the window.
merges_per_day	number (double)	yes	`merges / window_days`.
median_actionable_to_merged_secs	integer \| null	no	Median seconds from becoming actionable to being merged; `None` when no merge in the window had a recorded `became_actionable` before it.
ci_rounds_per_merge	integer \| null	no	Median `refreshed` events between one merge and the next; `None` without a merge.
median_cycle_secs	integer \| null	no	Median seconds from a selection to its outcome; `None` when no selection in the window reached one.
stale_decisions	integer (uint64)	yes	Decisions refused because master or the head moved after they were taken.
merge_failures	integer (uint64)	yes	Merge attempts that failed.
verification_failures	integer (uint64)	yes	Merges whose resulting master failed verification.
unreadable_events	integer (uint64)	yes	Events in the trail whose time could not be read; they count toward nothing.

Used by IntegrationStatus

IntegrationTimings

object

How long CI takes on the open pull requests, or why it is not known.

property	type	required	description
observed	boolean	yes	Whether a forge observation is recorded in this checkout.
reason	string \| null	no	Why there are no timings, when there are none.
timings	CiTimings \| null → CiTimings	no	The timings measured from the observation, when there is one.

Used by integration.timings

LabelEffect

"hold" | "obsolete"

What a label does to a pull request that carries it.

holdIt holds the pull request whatever else is true: blocked, with label:NAME.
obsoleteA person marked the work obsolete (owner decision D3): obsolete, with label_obsolete:NAME, listed by cleanup for a person and never closed automatically.

Used by LabelPolicy

LabelPolicy

object

One label with an effect. The forge's label names are compared with name case-insensitively.

property	type	required	description
name	string	yes	The label, lower-case.
effect	LabelEffect → LabelEffect	yes	What it does.

Used by IntegrationPolicy

LeaseHolder

object

Who holds the lease.

property	type	required	description
pid	integer (uint32)	yes	The process.
host	string	yes	The machine.
base	string	yes	The base branch.
since	integer (uint64)	yes	When it was taken, seconds since the epoch.
mesh_claim	string \| null	no	The mesh claim that makes it exclusive across machines, `<stream>/<claim>`; absent when the lease guards this clone alone (`super::exclusive`).

Used by IntegrationLeaseState

LeftBranch

object

A branch a merged pull request left on origin, as cleanup reports it. Reported, never deleted: the forge's delete_branch_on_merge decides deletion (owner decision D4), so the executor holds no branch-deleting write at all.

property	type	required	description
branch	string	yes	The branch on origin.
tip	string	yes	Its tip: the head that merged.
pr	integer (uint64)	yes	The pull request that merged it.
merged_at	string	yes	When that pull request merged.
action	string	yes	`left_for_a_person`, or `kept: checked out at <path>` when a worktree of this repository has the branch checked out: somebody may still be standing on it.
next_step	string	yes	What would clear it, in the setting's own terms.

Used by LeftBranchReport

LeftBranchReport

object

The last report of the branches merged pull requests left on origin, as prs cleanup read it. Written by prs cleanup alone — the one place that asks the forge for them — and rendered offline, with its age, by every surface that cannot reach the network.

property	type	required	description
read_at	string	yes	When cleanup read origin and the merged pull requests.
base	string	yes	The base the report excludes.
delete_branch_on_merge	boolean \| null	no	The forge's `delete_branch_on_merge`, from the observation; `None` when unread.
branches	array \| null → LeftBranch	no	The branches, or `None` when origin or the merged pull requests could not be read: unread is not "nothing left behind".
refreshed_by	string	yes	The command that reads it afresh.

Used by IntegrationCleanup

LinkCheck

object

One check run on a link's head.

property	type	required	description
name	string	yes	The check's name.
state	CheckRunState → CheckRunState	yes	Where it stands.

Used by TrainLink

Moved

object

One line that differs between the two snapshots.

property	type	required	description
section	string	yes	The section it belongs to.
change	string	yes	`added` (present only after the cycle) or `removed` (present only before).
line	string	yes	The line itself.

Used by DryRunProof

ObservedClassification

object

One open pull request as the cycle classified it.

property	type	required	description
number	integer (uint64)	yes	The pull request.
head_sha	string	yes	The head it was decided against.
disposition	string	yes	Its disposition, as the queue names it.
next_action	string \| null	no	What the executor would do with it, when anything.

Used by DryRunProof

OverlapKind

"authored" | "version_bump" | "release"

What two open pull requests have in common that makes landing one change the other.

authoredAuthored paths both change.
version_bumpBoth raise the crate's version: whichever lands second must be re-derived on the first.
releaseBoth change the release records under .ai/repo/releases/.

Used by PathOverlap

PassedOver

object

One time the executor chose another pull request.

property	type	required	description
at	string	yes	When, RFC 3339.
for_pr	integer (uint64)	yes	The pull request chosen instead.
action	IntegrationAction → IntegrationAction	yes	What it was chosen for (`selected` to merge, `refresh_selected` to bring master in).

Used by ExecutorWait

PathOverlap

object

Shared authored paths with one other open pull request.

property	type	required	description
number	integer (uint64)	yes	The other pull request.
paths	array of string	yes	The paths both change.
kind	OverlapKind → OverlapKind	no	What the two share. `authored` in a record written before it was said.

Used by PullRequestAssessment

PrepState

"pushed" | "pending"

Whether a prepared head has reached the forge.

pushedThe prepared head is the pull request's head: it was pushed.
pendingThe prepared head is another commit: it waits for its turn to be pushed.

Used by PreparedHead

PreparedHead

object

The head the executor prepared for a link under refs/prep/<n>.

property	type	required	description
reference	string	yes	The ref.
sha	string	yes	The commit it names.
state	PrepState → PrepState	yes	Whether that commit is the head the forge serves.

Used by TrainLink

ProofStep

object

One step of the cycle and what it said.

property	type	required	description
step	string	yes	`refresh`, `plan`, `drain --dry-run` or `cleanup`.
summary	string	yes	What it reported, in one line.

Used by DryRunProof

PullRequestAssessment

object

The canonical state of one open pull request: what was observed, what it is to master, how it is classified and why. The one value every surface renders.

property	type	required	description
number	integer (uint64)	yes	The number.
title	string	yes	The title.
author	string	yes	The author.
head_ref	string	yes	The head branch.
base_ref	string	yes	The base branch.
evaluated_against	EvaluatedAgainst → EvaluatedAgainst	yes	The revisions this was decided against.
disposition	PullRequestDisposition → PullRequestDisposition	yes	The classification.
superseded_by	integer \| null	no	The successor that landed and replaces it, exactly when the disposition is `superseded`: the disposition stays one word on the wire, and this is its `by`. Absent otherwise; a successor still open, or merged somewhere master does not contain, is in the `supersession` evidence and the reasons instead, and one closed unmerged is evidence only.
issue	string \| null	no	The issue of `.ai/repo/project/issues/` its head branch names — a path component equal to the id, or the id followed by `-`, the form `majordomus worktree create --issue` gives — when it names one. Derived, never declared here: the issue record and the branch name are the two sources, and nothing else.
milestone	string \| null	no	The milestone that issue's record declares, when it declares one.
lane	IntegrationLane → IntegrationLane	yes	The queue it is in.
reasons	array of string	yes	Machine-readable reasons, one for every failing gate's every finding, in policy order: the first is the decisive one. A ready pull request carries why it is ready.
gates	array of GateResult → GateResult	no	Every gate of the policy, in order, and whether it passed.
next_action	string \| null	no	What a person or the executor does next, when anything.
required_checks	RequiredCheckState → RequiredCheckState	yes	The required checks on the head.
review	PullRequestReview → PullRequestReview	yes	The review state.
relation	RelationToMaster → RelationToMaster	yes	What the head is to master.
dependencies	array of PullRequestDependency → PullRequestDependency	yes	Declared and inferred dependencies.
authored_paths	array of string	yes	Paths the pull request changes (authored ones; derived output is excluded).
overlaps	array of PathOverlap → PathOverlap	yes	Other open pull requests changing a same authored path, with the shared paths.
risk	IntegrationRisk → IntegrationRisk	yes	The planning risk.
risk_factors	array of string	yes	Why the risk is what it is.
evidence	array of IntegrationEvidence → IntegrationEvidence	yes	Every fact read.
created_at	string	yes	When it was opened.
wait	ExecutorWait \| null → ExecutorWait	no	How long it has been the executor's to act on, and how often another was chosen instead — derived from the audit trail (`super::wait`), present only while it is ready or refreshable.
rank_factors	RankFactors \| null → RankFactors	no	Why it stands where it does in the rank: every component the order compares, in the order it compares them. Set by the planner; absent on an assessment never ranked.
change_shape	ChangeShape \| null → ChangeShape	no	What its merge into master changes, by kind (`ChangeShape`): read beside the relation, from the same pair of commits. Absent when it could not be read.

Used by IntegrationExplanation IntegrationQueue

PullRequestDependency

object

Explicit ordering between pull requests, as declared.

property	type	required	description
number	integer (uint64)	yes	The pull request this one waits for.
certainty	DependencyCertainty → DependencyCertainty	yes	How it is known.
satisfied	boolean	yes	Whether it is satisfied: that pull request merged. Closed without a merge, or not read, it is not — a dependency that never landed is no less a dependency.
state	DependencyState → DependencyState	no	What the forge says became of it. `open` in a record written before it was read.

Used by PullRequestAssessment

PullRequestDisposition

The one classification of an open pull request. Every value carries a machine-readable reason in PullRequestAssessment::reasons; there is no mergeable: bool.

readyContains the current master, every required check passed on its head, nothing blocks it: the executor may merge it.
needs_refreshMerges cleanly but does not contain master: the executor may bring master in (a merge commit on the branch, never a rewrite), after which CI must run again.
waiting_for_checksContains master; a required check has not finished on this head.
waiting_for_reviewA required review is missing or changes were requested.
waiting_for_dependencyA declared dependency has not landed.
draftA draft.
needs_repairA required check failed on this head.
conflictingConflicts on authored paths: a person resolves them.
blockedA label whose policy is to hold holds it, or the repository allows no merge commit, which is the only way the executor merges.
unsafeThe forge has auto-merge armed on it: the forge would merge it on its own, outside the executor and against whatever master is then. Held until a person disarms it.
redundantIts head already landed, its merge changes nothing, or every one of its commits is on master as an equal patch: strong evidence from git, eligible for closure under policy. (Before 0.13 this was the word superseded.)
supersededA successor was declared for it by someone the repository lets declare one — an owner, member or collaborator, in a pull request of this repository — and that successor landed: git finds its head or its merge commit in master. The successor is PullRequestAssessment::superseded_by. Eligible for closure under policy.
possibly_redundantWeak evidence: only derived artifacts would change, or its declared successor was merged somewhere master does not contain. Surfaced for a person; never closed automatically.
other_baseTargets a branch other than the integration base.
unknownSomething needed to decide could not be observed.
obsoleteA person marked it obsolete with a label the label policy declares (owner decision D3): the only evidence that reaches this word. Listed for a person by cleanup and never closed automatically; age, shared paths or a similar title never make one.

Used by CleanupItem PullRequestAssessment RankFactors TrainLink

PullRequestReview

Where the forge's review policy stands.

not_requiredThe branch protection requires no review.
approvedApproved.
changes_requestedA reviewer asked for changes.
pendingA required review has not been given.
staleThe approvals were given on another commit than the head: an approval is of one commit, and these are not of this one.
code_owners_pendingThe approvals are there, but a code owner's is still required.
unknownThe protection could not be read.

Used by PullRequestAssessment

QueueTallies

object

How many pull requests are in each disposition and lane.

property	type	required	description
open	integer (uint)	yes	Open pull requests.
by_disposition	map of integer (uint)	yes	By disposition word.
by_lane	map of integer (uint)	yes	By lane word.

Used by IntegrationQueue

RankFactors

object

What the rank compares, in order: the first component that differs between two pull requests decides which comes first. Each is a value of the assessment or of the queue around it, so the order can be explained and is the same whatever order the forge listed the pull requests in.

property	type	required	description
lane	IntegrationLane → IntegrationLane	yes	The lane: what kind of work the executor does with it.
disposition	PullRequestDisposition → PullRequestDisposition	yes	The disposition, within the lane.
risk	IntegrationRisk → IntegrationRisk	yes	The planning risk: lower first.
contention	integer (uint)	yes	How many other ready or refreshable pull requests it overlaps (`PathOverlap`): an authored path, a version bump or a release in common. Fewer first, because landing it invalidates less.
dependents	integer (uint)	yes	How many open pull requests declare that they wait for this one and are not yet satisfied: more first, because landing it unblocks them.
authored_paths	integer (uint)	yes	How many authored paths it changes: fewer first, a smaller change is cheaper to land and to undo.
created_at	string	yes	When it was opened: older first, so easy new work cannot starve old work.
number	integer (uint64)	yes	The number: the last tie-break, total.

Used by PullRequestAssessment

RelationToMaster

one of 9 variants

What the pull request's head is to the current master, decided locally by git with this repository's own merge drivers — never by the forge's mergeable, which cannot run the derived-file driver and calls nearly every pull request here conflicting.

variant The head is an ancestor of master: every commit already landed.

kind

"contained"

yes

variant Merging the head into master changes nothing: its patch is already fully there.

kind

"superseded"

yes

variant The merge would conflict or change only derived output, but every commit the head has and master lacks is on master already as an equal patch (git cherry marks each -): the change landed, and master moved on past it. Never a partial match, and never a head that carries a merge commit of its own, whose resolution has no patch to compare.

commits	integer (uint64)	yes	How many commits, every one of them already on master.
kind	"patch_ids_upstream"	yes

variant Merging changes only derived artifacts: the authored change is already on master, and what differs is output the generators rewrite.

paths	array of string	yes	The derived paths that would change.
kind	"derived_only"	yes

variant The head already contains master and merges cleanly.

authored	array of string	yes	Authored (non-derived) paths the merge changes.
owes_version	string \| null	no	The version a landing of this head allocates, when master allocates at landing (ADR 0134) and the head does not carry it: the head owes a refresh even though it contains master. Absent when the policy does not allocate, or the head carries it.
kind	"up_to_date"	yes

variant The head does not contain master, yet master holds nothing the head lacks: merging it writes the head's own tree, and every commit master has beyond it is a merge commit. That is a head stacked on a pull request that has since landed. A verdict on the head is then a verdict on what master becomes, tree and listed history alike, exactly as when the head contains master; and no path is merged at all, so the forge needs no driver for it.

behind	integer (uint64)	yes	Commits on master the head does not have.
authored	array of string	yes	Authored (non-derived) paths the merge changes.
kind	"carries_master"	yes

variant The head does not contain master, but the merge is clean with the derived driver.

behind	integer (uint64)	yes	Commits on master the head does not have.
authored	array of string	yes	Authored paths the merge changes.
kind	"behind"	yes

variant Merging conflicts on authored paths: a person must resolve it.

paths	array of string	yes	The conflicting authored paths.
kind	"conflicting"	yes

variant Git could not answer (the head is not fetched, or git failed); the reason.

reason	string	yes	Why.
kind	"unknown"	yes

Used by PullRequestAssessment TrainLink

RequiredCheck

object

One check the base requires: a status context, and the app that must write it when the protection binds it to one. A check of that name from any other writer is not this one.

property	type	required	description
context	string	yes	The status context, or the check run's name.
app_id	integer \| null	no	The app bound to it, when the protection names one.

Used by IntegrationPolicy

RequiredCheckState

The state of the repository's required checks on one head, which is the only check state a merge decision reads. A visible green check that is not required proves nothing, and a required check that is absent is not a pass.

passedEvery required check passed on this head.
skippedEvery required check passed, at least one of them by a skip the policy permits for that context. A skip the policy does not permit is not a pass: it is missing.
pendingA required check is queued or running.
failedA required check failed.
missingA required check has not reported on this head at all.
unknownThe repository's required checks could not be read.

Used by PullRequestAssessment TrainLink

ReviewPolicy

object

What the base requires of reviews, read from its protection and rulesets together.

property	type	required	description
approvals	integer (uint64)	yes	How many approving reviews a merge needs; 0 when none.
code_owners	boolean	yes	Whether a code owner's approval is required.
dismiss_stale	boolean	yes	Whether the forge dismisses an approval when the head moves.

Used by IntegrationPolicy

Snapshot

object

Everything the cycle could move, at one moment.

property	type	required	description
sections	array of SnapshotSection → SnapshotSection	yes	The sections, always in the order `remote`, `forge`, `trail`, `lease`, `local`.

Used by DryRunProof

SnapshotSection

object

One section of a snapshot: a name and its lines, in a stable order.

property	type	required	description
name	string	yes	`remote`, `forge`, `trail`, `lease` or `local`.
lines	array of string	yes	What the section holds, one fact per line, sorted where order carries no meaning.

Used by Snapshot

Train

object

One train: open pull requests joined by confirmed dependencies, in the order they land.

property	type	required	description
id	string	yes	`train-<n>`, after the first root in turn order: stable while that link is open.
roots	array of integer (uint64)	yes	The links that land first: no open link of the train is below them.
tops	array of integer (uint64)	yes	The links at the top: no link of the train is stacked on them.
next	integer \| null	no	The first link, in turn order, whose every dependency has landed: the train's next merge as far as order is concerned (its disposition says whether it can merge now).
links	array of TrainLink → TrainLink	yes	Every open link, in turn order — `TrainLink::position` 1 first.
edges	array of TrainEdge → TrainEdge	yes	Every confirmed dependency of a link, upper link first.
beneath	array of BeneathLink → BeneathLink	yes	The pull requests below the train that are no longer open — landed, closed without a merge, or unread — which a link still declares.
by_disposition	map of integer (uint)	yes	Links by disposition word.

Used by TrainsView

TrainEdge

object

A confirmed dependency between two pull requests of a train.

property	type	required	description
from	integer (uint64)	yes	The upper link: the one that depends.
to	integer (uint64)	yes	The pull request it stands on.
kind	TrainEdgeKind → TrainEdgeKind	yes	How the dependency is declared.
satisfied	boolean	yes	Whether it is satisfied: the pull request below landed.

Used by Train

TrainEdgeKind

"stacked_on" | "depends_on"

How a dependency between two links is declared.

stacked_onIts base branch is the other's head, or its body says Stacked on #N.
depends_onIts body says Depends on #N, Requires #N or Land after #N.

Used by TrainEdge

TrainLink

object

One open pull request as a link of a train.

property	type	required	description
number	integer (uint64)	yes	The pull request number.
title	string	yes	Its title.
author	string	yes	Its author's login.
head_ref	string	yes	Its head branch.
base_ref	string	yes	The branch it targets: the integration base, or the head of the link below.
head_sha	string	yes	The head commit it was assessed at, as the forge served it.
url	string \| null	no	The pull request on the forge, when the repository is known.
checks_url	string \| null	no	Its checks on the forge, when the repository is known.
disposition	PullRequestDisposition → PullRequestDisposition	yes	The executor's classification.
lane	IntegrationLane → IntegrationLane	yes	The lane that disposition belongs to.
reasons	array of string	yes	The machine-readable reasons, as every surface spells them (`stacked_on:#<number>`).
next_action	string \| null	no	What happens next, in words, when anything does.
required_checks	RequiredCheckState → RequiredCheckState	yes	The required checks on its head.
checks	array of LinkCheck → LinkCheck	yes	Every check the forge reported on its head, required or not.
relation	RelationToMaster → RelationToMaster	yes	What its head is to master, decided by git.
relation_kind	string	yes	That relation's word (`behind`, `up_to_date`, `carries_master`, ...).
behind	integer \| null	no	How many master commits its head lacks, when the relation counts them.
carries_master	boolean	yes	Whether its head carries master by a merge of its own (ADR 0129) — read from the relation's word, so an executable that does not know that relation says `false`.
prep	PreparedHead \| null → PreparedHead	no	The head the executor prepared for it, when `refs/prep/<n>` exists.
position	integer (uint)	yes	Its turn in the train, 1-based: every link below it comes earlier.
depth	integer (uint)	yes	How many links are below it on its longest path to master; a root is 0.
at_turn	boolean	yes	Every dependency it declares has landed: it is the link the order allows next.
on	array of integer (uint64)	yes	The pull requests it stands on, open links and those beneath alike.
carries	array of integer (uint64)	yes	The links stacked on it.
rank	integer (uint)	yes	Its rank in the queue, 1-based.
in_cycle	boolean	yes	Caught in a cycle of confirmed dependencies: no link of the cycle can land first.

Used by Train

TrainTallies

object

Counts over every train.

property	type	required	description
trains	integer (uint)	yes	Trains.
links	integer (uint)	yes	Open links across every train.
pending_prep	integer (uint)	yes	Links whose prepared head is not the head the forge serves.
by_disposition	map of integer (uint)	yes	Links by disposition word.

Used by TrainsView

TrainsView

object

Every train of the observed queue, and why there is none when there is none.

property	type	required	description
observed	boolean	yes	Whether a forge observation is recorded in this checkout.
reason	string \| null	no	Why there are no trains to show, when nothing is observed.
repository	string \| null	no	`owner/name`, when observed.
base	string \| null	no	The integration base.
master_sha	string \| null	no	The master commit every link's relation was decided against.
observed_at	string \| null	no	When the forge was observed.
trains	array of Train → Train	yes	Every train, the one whose next link ranks highest in the queue first.
unattached_prep	array of UnattachedPrep → UnattachedPrep	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).
tallies	TrainTallies → TrainTallies	yes	Counts over every train.
diagnostics	array of string	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.

Used by integration.trains

UnattachedPrep

object

A prepared head whose pull request is no link of any train.

property	type	required	description
number	integer (uint64)	yes	The pull request the ref is named for.
sha	string	yes	The commit it names.
open	boolean	yes	Whether that pull request is open.

Used by TrainsView