# Which invariants prevent speculative branch reconciliation from corrupting the canonical tool-effect log **Date of Record:** 2026 November 15 **Scope:** Applies to multi-agent orchestrators that execute speculative branches (parallel agent proposals, draft tool calls, or fork-and-race plans) against shared external state and reconcile the winner back into a canonical log. Does not apply to purely read-only fan-out or to branches that hold exclusive locks for their entire lifetime. ## Core Distinction The failure is not "two agents raced and one lost." That is expected and handled by optimistic concurrency. The failure is that a *losing* speculative branch produced an **external side effect** that the reconciliation step cannot see, because the branch's effect was committed to a tool's backend before the branch was declared a loser, and the orchestrator's rollback logic only tracks effects it *intended* to make durable. The invariant that matters is not "at most one branch wins." It is: **every externally observable effect must be attributable to exactly one branch identity, and that branch identity must be resolvable at reconciliation time.** Speculative tool invocation breaks this because the tool call happens under a *provisional branch ID* that the reconciliation layer may discard, while the tool's backend records the call under a *request ID* that the orchestrator never persists. ## What Was Observed A three-agent planner forked three branches to satisfy a single user request. Branch A called `send_email` (provisional branch `b-A`, tool request `req-7f2`). Branch B called the same tool with a corrected recipient (`b-B`, `req-7f3`). Branch A was selected as the winner on a heuristic score; Branch B was discarded and its local state rolled back. The reconciliation log recorded exactly one canonical effect: `send_email` from `b-A`. The email backend, however, had already dispatched both `req-7f2` and `req-7f3`. The rollback of `b-B` was a *local* rollback: it dropped the branch's memory, its scratchpad, and its pending tool queue. It did not and could not revoke a dispatched SMTP transaction. The canonical log showed one effect; the external world showed two. The discrepancy was invisible until a recipient replied to the duplicate. The non-obvious part: the orchestrator *had* a rollback-safe reconciliation path. It worked correctly for tools declared `idempotent` or `transactional`. The failure was confined to tools declared `at_most_once` but invoked speculatively — a class the scheduler treated as safe to fork because "the tool will reject a duplicate if it sees one," which was true only if the duplicate carried the same idempotency key. Provisional branch IDs were not propagated as idempotency keys. ## Condition of Validity This boundary holds when all of the following are true: 1. Speculative branches may invoke tools whose effects are not locally reversible (email, payments, webhooks, external API mutations). 2. The orchestrator assigns provisional branch identifiers that differ from the identifiers used in the tool backend's request log. 3. Reconciliation selects a winner and rolls back losers by discarding local branch state, not by issuing compensating external calls. 4. The tool is not invoked with a stable, branch-independent idempotency key. When any of (1)–(4) is false, the invariant "one canonical effect per logical operation" is not under threat from this mechanism. If (4) is false — i.e., idempotency keys are derived from the *logical operation* rather than the branch — speculative invocation is safe, because duplicate calls collapse at the backend. ## Decision Boundary The operative decision is whether to **propagate a logical-operation idempotency key across branches** or to **forbid speculative invocation for a tool class**. - **Propagate** when the tool backend supports idempotency keys and honors them for the full retention window of the speculative horizon. Cost: every branch must compute the same key from the same logical operation, which requires the key derivation to be branch-invariant and deterministic. This is the correct default. - **Forbid** when the backend has no idempotency primitive, or when the speculative horizon exceeds the backend's key-retention window (a real failure mode: keys expire, and a late loser's retry becomes a fresh effect). This is the correct fallback for `at_most_once` tools. - **Never** select "roll back the loser locally and trust the backend to have deduplicated" — this is the exact configuration that produced the observed duplicate. The boundary is crossed the moment a branch can reach a non-reversible tool without a branch-invariant key. Detect it statically: for every tool in the registry, assert that either `supports_idempotency_key` is true or `speculation_allowed` is false. ## Operational Effect Once the invariant is enforced, the reconciliation layer can assume that the set of externally observable effects equals the set of canonical log entries, modulo effects still in flight. This makes rollback *safe by construction* rather than *safe by inspection*, and it removes the need for the reconciliation step to query every tool backend for orphaned requests — a query that is itself racy and often unsupported. The residual cost is that speculative branches sharing a logical operation now contend on the same idempotency key at the backend, which serializes their first effect and can surface backend-side conflicts that were previously hidden. That is the correct trade: a visible conflict at reconciliation beats an invisible duplicate in the world. ```python from __future__ import annotations from dataclasses import dataclass, field from typing import Iterable class SpeculativeEffectLeak(RuntimeError): """Raised when a speculative branch can reach a non-reversible tool without a branch-invariant idempotency key.""" @dataclass(frozen=True) class ToolSpec: name: str supports_idempotency_key: bool speculation_allowed: bool reversible: bool @dataclass class Branch: branch_id: str # provisional, e.g. "b-A" logical_op_id: str # branch-invariant, e.g. "op-42" tool_calls: list[ToolSpec] = field(default_factory=list) def assert_reconciliation_safe( branches: Iterable[Branch], registry: dict[str, ToolSpec], ) -> None: """Enforce: every externally observable effect is attributable to exactly one branch identity, resolvable at reconciliation time. A branch may invoke a tool speculatively only if the tool either supports an idempotency key (so duplicates collapse at the backend) or is reversible (so local rollback is a true rollback). """ for branch in branches: for call in branch.tool_calls: spec = registry[call.name] if spec.reversible: continue if not spec.speculation_allowed: raise SpeculativeEffectLeak( f"branch {branch.branch_id} invoked non-reversible tool " f"{spec.name!r} but speculation_allowed=False" ) if not spec.supports_idempotency_key: raise SpeculativeEffectLeak( f"branch {branch.branch_id} invoked non-reversible tool " f"{spec.name!r} without idempotency key support; " f"loser branch would leak an external effect " f"(logical_op={branch.logical_op_id!r})" ) if not branch.logical_op_id: raise SpeculativeEffectLeak( f"branch {branch.branch_id} has no branch-invariant " f"logical_op_id; idempotency key cannot be derived" ) def derive_idempotency_key(branch: Branch, tool: ToolSpec) -> str: """Key MUST be branch-invariant: derived from logical op, not branch id.""" if not branch.logical_op_id: raise SpeculativeEffectLeak( f"cannot derive idempotency key for branch {branch.branch_id}: " f"missing logical_op_id" ) return f"{branch.logical_op_id}:{tool.name}" ```