# What happens when an instance merges speculative agent branches whose tool effects alias on a shared idempotency key **Date of Record:** 2026 November 15 **Scope:** Applies to multi-branch speculative agent execution where branches issue tool calls that carry idempotency keys, and a merge step reconciles effects before committing. Does not apply to branches that are fully isolated (no shared external side effects) or to merges that operate on pure state without tool-effect reconciliation. ## Core Distinction There are two distinct notions of "conflict" in speculative branch merging: 1. **State conflict** — two branches produce divergent values for the same logical variable/key. This is detected by comparing branch outputs and is the conflict most merge logic is written to catch. 2. **Effect conflict** — two branches issue tool calls that are *semantically distinct* but *alias on the same idempotency key*, so the external system collapses them into a single effect. The branch outputs may be perfectly consistent while the external world has silently absorbed one branch's effect into another's. The non-obvious boundary: conflict detection that compares branch *results* will report "no conflict" in exactly the case where the two branches performed *different* side effects under the *same* idempotency key. The merge succeeds, the state is consistent, and the tool-effect ledger is wrong. ## What Was Observed A speculative executor fanned out three branches from a common checkpoint. Each branch was given a tool-effect namespace derived from `(run_id, branch_id, step_seq)` — but the idempotency key forwarded to the downstream tool was computed as `hash(run_id, step_seq)` with `branch_id` omitted, on the assumption that a given step sequence would only ever be executed once per run. Two branches reached the same `step_seq` with different arguments: - Branch A called `charge_account(amount=100)`. - Branch B called `charge_account(amount=250)`. Both produced idempotency key `K`. The downstream tool executed A's call and, on B's call with the same key, returned the cached A result (`amount=100`). Branch B's local state recorded the returned effect as its own, so B's branch output claimed `amount=100` was charged — consistent with A. The merge step compared branch outputs, found agreement, and committed. Observations: - Merge conflict detector: **no conflict**. - External ledger: **one charge of 100**, though the merged intent was to charge 250. - Branch B's trace: indistinguishable from a correct branch. - The failure surfaced days later as a reconciliation gap between the agent's committed plan and the payment ledger. The detection gap is structural, not probabilistic: the merge step was comparing the wrong thing (outputs) against the wrong key space (a key that does not encode branch identity). ## Condition of Validity Conflict detection based on branch-output comparison is valid **only if** the idempotency key used for tool effects is injective over `(branch_id, step_seq, semantic_arguments)`. If any component of the branch identity is omitted from the key, or if the key is derived from step sequence alone, then two branches can alias. Under aliasing, output-equality is not evidence of effect-equality, and the merge invariant "consistent outputs ⇒ no effect conflict" does not hold. Conversely, when keys are branch-scoped and argument-sensitive, output comparison may still be used as a *fast path*, but the authoritative check must be a comparison of the effect ledger keyed by the full idempotency tuple. ## Decision Boundary At merge time, for each pair of branches and each tool effect: - If the idempotency keys differ → effects are independent; no effect conflict possible. - If the idempotency keys are equal **and** the effect payloads are equal → benign deduplication; commit once. - If the idempotency keys are equal **and** the effect payloads differ → **aliased effect conflict**. This is the boundary case. It must be treated as a hard conflict regardless of what branch outputs say, because the external system has already (or will) collapse the two effects. The decision must be made on the effect ledger, not on branch outputs. Output equality is necessary but not sufficient; key equality with payload divergence is the signal that the merge logic must reject. ## Operational Effect When this boundary is crossed and not caught, the system enters a state where the committed plan and the external ledger diverge while every internal consistency check passes. This is worse than an ordinary conflict, because ordinary conflicts are loud and this one is silent. Recovery requires replaying the effect ledger against branch payloads — data that must have been retained at merge time. If the merge discarded per-branch effect payloads on the "no conflict" path, recovery is impossible without external reconciliation. Mitigation: (a) make idempotency keys injective over branch identity and arguments; (b) at merge, assert payload equality whenever keys collide; (c) retain per-branch effect payloads through commit so the assertion can be re-run. ```python import hashlib from dataclasses import dataclass class AliasedEffectConflict(RuntimeError): """Raised when two branches collide on an idempotency key with divergent payloads.""" @dataclass(frozen=True) class ToolEffect: branch_id: str step_seq: int idempotency_key: str payload: str def idempotency_key(run_id: str, branch_id: str, step_seq: int, payload: str) -> str: # Key must be injective over branch identity AND payload. h = hashlib.sha256() h.update(f"{run_id}|{branch_id}|{step_seq}|{payload}".encode()) return h.hexdigest() def reconcile_effects(effects: list[ToolEffect]) -> list[ToolEffect]: """Collapse effects by idempotency key, rejecting aliased-payload collisions.""" by_key: dict[str, ToolEffect] = {} for eff in effects: prior = by_key.get(eff.idempotency_key) if prior is None: by_key[eff.idempotency_key] = eff continue if prior.payload != eff.payload: raise AliasedEffectConflict( f"idempotency key {eff.idempotency_key!r} aliased by branches " f"{prior.branch_id!r} (payload={prior.payload!r}) and " f"{eff.branch_id!r} (payload={eff.payload!r}); " f"external effect would silently collapse to one of them" ) # benign deduplication: identical payload, commit once return list(by_key.values()) def merge_branches(run_id: str, branch_effects: dict[str, list[tuple[int, str]]]) -> list[ToolEffect]: effects: list[ToolEffect] = [] for branch_id, steps in branch_effects.items(): for step_seq, payload in steps: key = idempotency_key(run_id, branch_id, step_seq, payload) effects.append(ToolEffect(branch_id, step_seq, key, payload)) return reconcile_effects(effects) ```