# In what scenarios must an instance refuse optimistic commit of a speculative branch when tool effects are only partially reversible **Date of Record:** 2026 November 15 **Scope:** Applies to orchestrators that roll out multiple speculative agent branches in parallel and defer side-effect commitment until a winner is selected, where at least one tool in the branch's effect set is non-idempotent or non-compensable. Does not apply to pure-computation branches, to reads, or to effect sets that are fully transactional under a single two-phase protocol. ## Core Distinction The distinction that matters is not "reversible vs. irreversible" but **compensable vs. observable**. A tool effect is compensable if a compensating action restores the pre-state to a degree indistinguishable to every downstream observer. It is merely *reversible* if the system can undo it internally but an external party (a payment network, an email recipient, a third-party webhook consumer, a human who read a notification) has already observed it. Speculative execution is safe under *reversible* effects; it is unsafe under *observable* effects, because rollback cannot retract what an external observer has already acted on. Most rollback implementations conflate the two and treat a successful compensating call as a successful rollback. ## What Was Observed A three-branch speculative rollout committed branch A (which called a payment authorization tool) while branches B and C were still in flight. The orchestrator's optimistic commit was gated on a *divergence check*: if any live branch's tool-effect fingerprint differed from the committed branch's, the commit was to be rolled back. Branch C subsequently produced a divergent effect — a second authorization against the same idempotency key family but a different amount. The rollback executed a void on A's authorization, which the payment network accepted. The void *succeeded*. The orchestrator logged `rollback=ok`. Two problems surfaced downstream. First, the void settled asynchronously and the merchant's fulfillment queue had already captured the authorization, so a shipment was initiated against a voided hold; the compensating transaction was real but the *observation* at the merchant was not. Second, branch C's authorization, issued speculatively after A's commit, was never voided at all — the divergence check only enumerated effects recorded *before* the commit timestamp, and C's effect landed in the window between commit and rollback. The rollback was correct with respect to the set it knew about and wrong with respect to the set that existed. ## Condition of Validity Optimistic commit with rollback-on-divergence is valid only when all three hold: 1. **Effect-set closure.** The set of effects subject to rollback is closed at commit time — no branch can emit a new effect after the commit barrier. This requires a *quiescence barrier*: every live branch must be fenced (its tool-call capability revoked) before the commit is issued, not merely signaled. 2. **Observation ordering.** For every effect in the set, either no external observer can act on it before the compensating action completes, or the compensating action is itself an observable effect that the observer honors (a reversal, not a void). 3. **Compensation idempotency.** The compensating action must be safe to apply more than once, because the rollback path and the divergence detector may both fire. If any of these fails, the branch is not speculatively committable; it must be serialized behind the commit decision, or the effect must be staged behind an outbox that only the winner drains. ## Decision Boundary The boundary is per-effect, not per-branch. Classify each tool in the branch's effect set at plan time: - **Staged / outboxed writes** (internal DB rows behind a commit flag): speculatively committable, rollback is a flag flip. - **Idempotent external writes keyed by a deterministic idempotency key derived from the branch identity**: committable if the key includes the speculation epoch, so a rolled-back branch's retries cannot collide with the winner's. - **Non-idempotent external effects with no reversal primitive** (sending an email, charging a card without a void, publishing to a third-party feed): *not* speculatively committable. Force serialization. - **Effects with a reversal primitive but asynchronous settlement** (auth/void, reserve/release): committable only if the orchestrator blocks the commit decision on settlement confirmation, which usually destroys the latency benefit and means you should serialize anyway. The refusal condition is precise: **refuse optimistic commit when the effect set contains any member that is observable before its compensation settles, or any member whose idempotency key does not encode the speculation epoch.** The first makes rollback untruthful; the second makes it unsafe to retry. ## Operational Effect When the boundary is respected, speculative rollout buys latency only on branches whose effects are staged or epoch-keyed; the orchestrator should route non-compensable tools to a serialized path and accept the latency there rather than discovering the boundary in production. When it is violated, the failure mode is silent: rollback reports success, the ledger balances internally, and the divergence manifests as an external duplicate or an unretracted observation days later, untraceable to the speculative commit because the orchestrator's logs show a clean rollback. Instrument the commit barrier to assert effect-set closure explicitly, and treat any effect emitted after the barrier as a hard fault, not a warning. ```python from dataclasses import dataclass, field from enum import Enum from typing import Iterable class SpeculationBoundaryError(RuntimeError): """Raised when a speculative branch cannot be safely committed or rolled back.""" class EffectClass(Enum): STAGED = "staged" # internal, commit-flag gated EPOCH_KEYED = "epoch_keyed" # external idempotent, key encodes epoch OBSERVABLE_ASYNC = "observable_async" # reversal exists but settles late IRREVERSIBLE = "irreversible" # no compensation primitive @dataclass(frozen=True) class ToolEffect: name: str effect_class: EffectClass idempotency_key: str | None = None speculation_epoch: str | None = None @dataclass class Branch: branch_id: str effects: list[ToolEffect] = field(default_factory=list) fenced: bool = False def assert_committable(branch: Branch, commit_epoch: str) -> None: """Refuse optimistic commit if the branch's effect set violates the boundary.""" if not branch.fenced: raise SpeculationBoundaryError( f"branch {branch.branch_id}: commit attempted before quiescence fence; " "effect set is not closed, late effects can escape rollback" ) for eff in branch.effects: if eff.effect_class is EffectClass.IRREVERSIBLE: raise SpeculationBoundaryError( f"branch {branch.branch_id}: effect {eff.name!r} is irreversible; " "serialize behind the commit decision" ) if eff.effect_class is EffectClass.OBSERVABLE_ASYNC: raise SpeculationBoundaryError( f"branch {branch.branch_id}: effect {eff.name!r} is observable before " "its compensation settles; rollback would be untruthful" ) if eff.effect_class is EffectClass.EPOCH_KEYED: if eff.idempotency_key is None or eff.speculation_epoch != commit_epoch: raise SpeculationBoundaryError( f"branch {branch.branch_id}: effect {eff.name!r} idempotency key " "does not encode the speculation epoch; retry after rollback may " "collide with the winner" ) def optimistic_commit(branch: Branch, commit_epoch: str) -> None: assert_committable(branch, commit_epoch) # commit proceeds; rollback path is now guaranteed truthful and retry-safe ```