# How should an instance distinguish a speculative branch from a committed effect when rolling back a divergent agent plan **Date of Record:** 2026 November 16 **Scope:** Applies to orchestrators that fork agent plans into speculative branches, invoke tools optimistically before verification, and roll back on divergence. Does not apply to single-agent linear execution, nor to systems where every tool invocation is gated behind a synchronous verifier and no branch is ever abandoned after side effects have been emitted. ## Core Distinction The failure is not "rollback failed." The failure is that the orchestrator conflated **plan-state rollback** with **effect-state rollback**. A speculative branch has two independent state dimensions: the *reasoning/plan state* (the agent's belief, scratchpad, and chosen subgoals) and the *effect state* (files written, messages sent, rows inserted, tokens spent, locks taken). Divergence detection operates on plan state. Optimistic tool invocation mutates effect state. When a branch is abandoned, the orchestrator almost always rolls back plan state correctly and assumes effect state followed. It does not. The invariant that must hold: **no effect produced inside a speculative branch may be observed by a committed branch or by the external world until that branch is verified.** Optimistic invocation deliberately violates this invariant for latency, and rollback is the compensation. The non-obvious boundary is that compensation is only sound if every effect is *reversible* and *isolated*. The moment a branch emits a non-reversible effect (an email, a payment, an append to an external queue, a consumed one-time token) before verification, rollback is no longer a rollback — it is a lie recorded in the log. ## What Was Observed A three-branch planner forked a "refactor module" task. Branch B (optimistic) invoked a `write_file` tool on a shared path and an `append_to_audit_log` tool on an external sink before verification completed. Branch A (the eventual committed winner) also touched the same path. Verification selected A. The orchestrator rolled back B's plan state, replayed A's writes, and reported success. The audit log, however, contained B's abandoned entries interleaved with A's committed entries, and B's `write_file` had already been observed by a downstream branch C that read the path during its own speculation. The final filesystem was correct; the audit trail and the observed read in C were not. The system reported a clean commit over a corrupted effect history. A second observation: a branch consumed a one-time verification token during optimistic invocation. On divergence, the token could not be re-issued. The committed branch could not re-verify and fell back to a degraded path. Rollback of plan state succeeded; rollback of the consumed capability did not exist. ## Condition of Validity Optimistic tool invocation with rollback-on-divergence is valid only when all of the following hold for every effect a branch may emit: 1. **Reversibility:** the effect has a defined, idempotent inverse (compensating transaction), or the effect is confined to a private, discardable namespace. 2. **Isolation:** no other branch, and no external observer, can read the effect until commit. Shared paths, shared sinks, and shared capabilities break this. 3. **Idempotency of replay:** the committed branch's re-execution must not double-apply effects that a diverged branch already applied to a shared resource. 4. **Capability conservation:** any resource consumed by speculation (tokens, quotas, locks, rate-limit budget) must be either refundable or reserved per-branch up front. If any condition fails, the branch is not speculative in the effect dimension and must be executed serially behind verification. This is the boundary: speculation is a *plan-state* optimization that is only safe to extend into *effect-state* when isolation and reversibility are structurally guaranteed, not merely intended. ## Decision Boundary Classify each tool by effect class before allowing optimistic invocation in a branch: - **Pure / private-scratch** (local computation, writes to a branch-private overlay): safe to speculate unconditionally. - **Reversible-and-isolated** (writes to a per-branch overlay that is merged only on commit, staged inserts in a transaction that is aborted on divergence): safe if the merge/abort is atomic. - **Reversible-but-shared** (writes to a shared path, shared queue with a compensating delete): safe only if no concurrent branch reads it before commit — requires read isolation, not just write compensation. - **Irreversible** (external messages, payments, one-time token consumption, appends to immutable sinks): **never** speculate. Gate behind verification. The decision rule: if the tool's effect class is irreversible or shared-without-read-isolation, the orchestrator must demote the branch from optimistic to serial at the moment of that invocation, and record the demotion. A branch that has already emitted an irreversible effect and is then diverged is in a terminal inconsistent state; the only correct action is to surface it as a hard error, not to silently roll back plan state and claim success. ## Operational Effect Systems that treat rollback as total when it is only partial accumulate **effect leakage**: abandoned-branch effects persist in shared sinks, audit logs, and downstream observations while the orchestrator's own accounting reports a clean commit. The leakage is invisible to plan-state reconciliation and only surfaces under audit, replay, or a second branch reading the leaked state. The corrective posture is to make effect class a first-class property of every tool, enforce read isolation on shared effects, reserve capabilities per branch, and raise a hard, non-recoverable error when a diverged branch is found to have emitted an irreversible effect — because at that point the system's commit record is wrong and must be quarantined rather than reconciled. ```python class EffectLeakageError(RuntimeError): """Raised when a diverged speculative branch has emitted an effect that cannot be rolled back, invalidating the commit record.""" pass IRREVERSIBLE = "irreversible" SHARED_NO_READ_ISOLATION = "shared_no_read_isolation" def verify_branch_rollback(branch, effect_log): """ Called when a speculative branch diverges and the orchestrator intends to roll back. Returns only if every emitted effect is safely reversible and isolated. Raises EffectLeakageError otherwise. """ for effect in effect_log: if effect.branch_id != branch.id: continue if effect.effect_class == IRREVERSIBLE: raise EffectLeakageError( f"branch {branch.id} emitted irreversible effect " f"{effect.tool}@{effect.target}; commit record invalid" ) if effect.effect_class == SHARED_NO_READ_ISOLATION: raise EffectLeakageError( f"branch {branch.id} mutated shared target {effect.target} " f"without read isolation; downstream may have observed it" ) # All effects reversible and isolated: safe to discard plan state. branch.rollback_plan_state() return True def commit_winner(winner, diverged_branches, effect_logs): for branch in diverged_branches: verify_branch_rollback(branch, effect_logs[branch.id]) winner.commit() return winner.id ```