Module queue 

Queue-as-bot v0 (DECISIONS.md D21, queue stage): speculative merge trains, checked either by the host forge’s CI or by our own (D18).

v0 is verdict-only: it builds a train commit (base tip + each open PR merged in submission order, conflicts excluded), gets a verdict on it, then reports a per-PR verdict as a commit status. It never moves the protected branch on its own — landing the train is a separate, explicitly requested step.

The check signal has two shapes. The forge one publishes the train as the choir/train branch and polls the forge’s check API, which means the speculative merge of every open PR is pushed to a public remote and tested by someone else’s runners. run_train_ci is the other: it hands the train to a choir_queue::executor::CiExecutor, so the same train is checked here, on a provider we chose, and nothing speculative leaves the machine.

Everything in this module is local git; the forge API glue lives in crate::github so the train mechanics stay testable offline.

Structs

DifferentialOutcome

Structured advisory result returned by the separately built D23 runner.

DifferentialSession

Three revision worktrees whose lifetime is a whole calibration run rather than a single observation.

QueuedRound

Result of one queued round.

Train

Result of building one speculative train.

TrainEntry

One PR’s fate in a train build.

TrainReport

What one train verdict means for the PRs riding it.

Enums

DifferentialVerdict

Closed set of D23 classifications accepted from the runner.

PrOutcome

One pull request’s fate in a queued round.

Constants

SPECIMEN_REPRODUCTION_RUNS

Reproduction runs a harvest adds after a first interaction_failure verdict, so a specimen records six runs in total — the bar specimen #1 (rust-lang/log 11eda98d, reproduced 6/6) set for calling a flag a semantic conflict rather than a flake.

Functions

already_in

Whether every commit of head is already contained in upstream by patch identity. git cherry marks a commit - when an equivalent change (same git patch-id --stable) is upstream, + when it is not; no + lines — including the empty output of a plain ancestor — means there is nothing left to merge.

build_train

Builds a speculative train in repo (a non-bare clone whose worktree this function owns): detaches at base, then merges each (id, head) in order with --no-ff. A conflicting PR is excluded (merge aborted) and the train continues without it.

harvestable_merges

Two-parent merge commits along repo’s first-parent history, newest first: the population choir-bridge harvest replays (D27).

land

Lands a green train: pushes tip to branch on the remote at url WITHOUT force, so git’s fast-forward rule is the race guard — if the branch moved since the train was built, the push is rejected and the caller should rebuild on the next round.

merge_changes_only_inert_paths

Whether every file this merge changed, against either parent, is inert by path_is_inert.

observed_merges

Merge commits already recorded in state_dir’s observation ledger, keyed by the ledger row’s revisions.merged oid.

parse_merge_list

Parses git log --format="%H %P" output into the ids of commits with exactly two parents, preserving order.

parse_observed_merges

Parses observation-ledger lines into the set of merged-revision oids.

path_is_inert

Whether a path cannot change what a build-and-test command observes.

pr_report

Reads one change’s outcome as the status its pull request gets.

record_population_restrictions

Records, beside the ledger, every way a harvest narrowed the population it walked: the merges excluded as inert, and the consecutive-inconclusive run that stopped the walk early.

revert_train

Reverts a landed train (D23 auto-revert arm): reverts each of the train’s merge commits (base..tip, first-parent, newest first) on top of tip, then pushes the result to branch WITHOUT force — if the branch moved past tip since landing, the push is rejected and a human decides. Returns the new branch tip. The reverted tree is byte-identical to base’s tree; history keeps the full record.

run_differential

Builds isolated worktrees for a speculative merge’s two parents and the merge itself, then invokes the explicit choir-differential runner.

run_differential_in

Runs one observation in an already-open session’s three worktrees.

run_queue

Runs one speculative round through the D5 merge queue.

run_train_ci

Checks one train commit with a CiExecutor instead of asking the host forge (D18).

run_train_differentials

Runs the advisory detector for every merge commit in a train, preserving train order and returning operational errors per entry instead of turning them into a landing decision.

train_report

Reads a train’s verdict as the report its PRs get (D18, D49).

train_unavailable

The report for a train we could not get a verdict on at all.

write_specimen

Packages a flagged merge and its reproduction runs as a corpus specimen under state_dir/specimens/<merge>.json (D27).