Expand description
L2 speculative merge queue (DECISIONS.md D5).
Dependent speculative pipeline: changes are tested in parallel against the speculative future state produced by everything queued ahead of them, “exactly as if they had been tested one at a time.” Window sizing follows a TCP-flow-control-inspired algorithm: start at 20, +1 per successful merge, halved per failure.
Conflict policy (DECISIONS.md): a change whose merge conflicts is evicted as a first-class conflict for its author to resolve; it is never silently resolved and never blocks the changes behind it, which are retested against a speculative state without it.
CI runs behind executor::CiExecutor (the CI executor seam, D18).
A verdict is four cases rather than a bool, because the queue’s
response to a test failure and to a provider fault must differ: only
executor::Verdict::Failed ejects a change, and ejection takes
everything that transitively depends on it. Tests use
executor::Synthetic; local::LocalRunner runs real
subprocesses; production wires the spindle/Firecracker executor.
§Where this sits
docs/architecture.md is the map of the whole workspace.
This crate is L2, the speculative merge queue (D5).
It builds on choir_hash, choir_merge, choir_oplog, choir_sequencer, choir_store and choir_view.
Modules§
- blast
- Blast radius: how far a change can reach (D23, the unbuilt half).
- conform
- The D18 executor conformance suite, runnable against a helper this repository cannot build.
- corpus
- Base-rate measurement over a real repository’s history (D23).
- differential
- Executable merged-vs-both-parents differential testing (D23).
- differential_
ledger - Durable, advisory calibration receipts for D23 differential runs.
- envelope
- What precision a detector can reach at our prevalence (D23).
- executor
- The CI executor seam (D18): what runs a candidate merge, and what it is allowed to say about the result.
- git
- The git speculator (D5): the second implementation of
Speculator, and the one a production caller wants. - identity
- Stable change identity across rebase: a change is
identified by the hash of its position-independent content — the
normalized diff from
choir_merge::normalized_diff— so the same logical edit authored against different bases (before and after the train rewrote the tip under it) carries the same identity. The queue uses it to recognize a resubmission of an already-landed change and refuse it instead of re-merging or duplicating it. - landing
- How a landing is written into the log (D68).
- local
- The local subprocess executor: the second implementation of the D18 seam, and the one that ships with it.
- memory
- Resolution memory keyed by the conflict triple (rerere-shaped; DECISIONS.md D15: metadata on existing shapes, never a new merge substrate).
- remote
- An executor that is not in this process (D18).
- speculate
- The speculation seam (D5): what it means to put one change on top of another.
- worktree
- An executor that materializes what it is asked about (D18).
Structs§
- Change
- A change submitted to the queue: a full-file edit carrying its own base.
- Check
Reporter - How the queue writes what CI found into the log (D49).
- JobTemplate
- How the queue turns a speculative state into a
executor::Job. - Merge
Queue - Single-shard speculative merge queue over one file.
- Queue
Report - Outcome of draining a queue.
Enums§
- Rejection
- Why a change left the queue without merging.
Constants§
- DEFAULT_
WINDOW - Default speculation window: both the initial size and the ceiling growth may not pass (a documented default).
Functions§
- run_
batch - Convenience: drain
changesthrough a fresh queue + sequencer and return the report plus the sequencer’s op count (which must equal merged count).
Type Aliases§
- Seal
- Turns a report op into the payload and signature a log will accept.