Canonical only moves through a fresh, ordered decision.
The Integration Queue is not merely a FIFO list. It is the place where Switchyard re-validates a Pull Request against the current canonical repository, applies policy, detects conflicts, and performs the final CAS-guarded Git operation.
What the queue is responsible for
| Property | Behaviour | Why it matters |
|---|---|---|
| Ordering | Strict FIFO; at most one canonical integration in flight. | Later PRs preview against the repository state produced by earlier successful integrations. |
| Freshness | Preview/check state is evaluated against the current base before the final Git mutation. | A PR that was valid ten seconds ago cannot silently integrate against stale assumptions. |
| Policy | Checks, review state, risk class and repository/org policy are evaluated before canonical moves. | Autonomy can vary by repository/risk without changing the Git substrate. |
| Conflict handling | Textual or semantic conflicts park/block the item rather than failing at the last line of a merge. | Repair can happen on the Attempt branch and be re-previewed deterministically. |
| Idempotency | Queue state is durable and canonical ref changes are provenance-bearing. | Restarts/retries do not imply “try the merge again and hope.” |
Lifecycle
queued
│
├─ required check missing/failed ───────────────► reject/block
│
├─ preview has textual conflict ────────────────► blocked → repair → requeue
│
├─ merged tree violates semantic contract ─────► blocked → fix contract mismatch
│
├─ policy requires human approval ─────────────► Needs Attention → approve/reject
│
├─ canonical moved during final operation ─────► stale → bounded requeue/re-preview
│
└─ fresh + clean + policy satisfied ───────────► Git merge/push → done
Why strict FIFO matters
Suppose PR A and PR B both start from the same main. A and B may each be perfectly valid in isolation. If they were integrated concurrently, both could preview against the same old base and one would discover the incompatibility only while trying to move canonical. FIFO changes the question: A integrates first, then B is previewed against A's result.
| Moment | PR A | PR B |
|---|---|---|
| Initial state | preview against main@X | preview against main@X |
| A reaches queue head | fresh → integrates → main@Y | still queued |
| B reaches queue head | done | re-preview against main@Y |
| If incompatible | unchanged | blocked before canonical mutation; repair/requeue path begins |
Textual conflict repair
The CP9 gate exercised same-file contention. The first PR integrated. The second became blocked during preview, its Attempt was routed to conflict state, the conflict-resolver repaired the Attempt branch, and the item was explicitly re-queued. Only after the repaired branch previewed cleanly did it become canonical.
Semantic conflict blocking
The queue also validates deterministic repository contracts against the preview-merged tree. This catches the more subtle case where Git itself reports a clean merge but the combined repository violates an invariant. A semantic conflict becomes a structured finding and blocks integration exactly like any other unresolved correctness problem.
Observed performance
| Scenario | Observed | Interpretation |
|---|---|---|
| 3 clean PRs | 18–22 s total | Ordering/correctness proven; scratch-clone preparation is visible. |
| 10 clean PRs | ~42 s total (~4.2 s/item) | Queue mechanics are not the dominant conceptual bottleneck; repeated Git setup is. |
The next optimization target is a cached bare mirror plus isolated worktrees, not removing serialization from the final canonical decision.