# Where must an instance boundary be drawn between a model call and its tool side effects for counterfactual replay to be sound **Date of Record:** 2026 November 16 **Scope:** Applies to deterministic replay and counterfactual ("what-if") debugging of agentic runs reconstructed from OTel GenAI spans, where the agent loop interleaves LLM invocations with tool/function calls that have external side effects. Does not apply to pure read-only tooling, nor to replays that only re-render an existing trace without re-executing the loop. ## Core Distinction The non-obvious boundary is *not* "model call vs. tool call." It is **the point at which a span's recorded output becomes an input that the replay engine is allowed to substitute**. A GenAI span (`gen_ai.operation.name = chat`) emits tokens, tool-call requests, and a finish reason as *one atomic unit*. A tool span emits an effect on the world. Counterfactual replay is sound only if, for every counterfactual branch, the substitution boundary is placed at the *model-span output* and every downstream tool span is treated as *causally dependent on that output* — not as an independent, independently-replayable event. The failure arises when an engineer, reasoning that "the trace is just a sequence of spans," treats tool spans as replayable events keyed by their own IDs. They are not. A tool span's *inputs* are derived from the model span's tool-call arguments, and its *outputs* are the only ground truth about the world that the replay will ever have. Replaying a tool span under a counterfactual model output produces a *synthetic* tool result that never occurred, and the agent's subsequent reasoning is then conditioned on a world state that did not exist. This is the exact analogue of a database read inside a transaction that was not re-validated against the counterfactual write. ## What Was Observed In a trace with the following shape: ``` run_id=R span M1 (chat): tool_calls=[search(q="X")] span T1 (execute_tool): result=S1 span M2 (chat): tool_calls=[fetch(url=U(S1))] span T2 (execute_tool): result=S2 span M3 (chat): final answer ``` A counterfactual branch was injected at `M1`: "what if the model had called `search(q="Y")` instead?" The replay engine, keyed on `gen_ai.tool.call.id`, re-bound `T1`'s *recorded* result `S1` to the new call — because the tool span ID matched the call ID carried in `M1`'s tool-call request. The branch then proceeded through `M2` and `M3` and produced a plausible-looking final answer. The answer was wrong: `S1` was the result for `q="X"`, not `q="Y"`. Every downstream step inherited a poisoned premise, and the trace *looked* internally consistent because the recorded `T1` output was still attached to a `T1` span. The tell was a mismatch between `gen_ai.tool.call.arguments` (rewritten to `q="Y"`) and the tool span's `input.value` (still `q="X"`). No invariant in the replay engine checked this. The engine had conflated **span identity** with **causal binding**. A second, subtler instance: a tool span with `gen_ai.tool.call.id` absent (older semantic conventions emitted only `tool.name`). The engine fell back to positional matching and silently paired `T1` with the *second* tool call in `M1` when `M1` had been edited to add a call. The replay did not error; it produced a branch with a tool result that belonged to a different call, and the divergence surfaced only three spans later as an unexplained refusal. ## Condition of Validity The substitution boundary at the model-span output is valid **if and only if** all of the following hold for the branch: 1. **Causal closure of tool inputs.** Every tool span's inputs are a pure function of (a) the immediately preceding model span's output and (b) prior tool outputs that are themselves inside the branch's substitution set. If a tool's arguments reference any value not derivable from the branch's substituted model output, the tool span is *not* replayable under that branch and must be marked `UNREPLAYABLE`, not re-bound. 2. **Effect-free replay or explicit effect suppression.** Replaying a tool span requires either that the tool is idempotent and side-effect-free, or that the replay engine suppresses the effect and substitutes the recorded output. In the latter case the recorded output is only valid for the *original* arguments; for counterfactual arguments it is undefined. 3. **Identity binding by call ID, with explicit failure on absence.** `gen_ai.tool.call.id` is the only sound binding key. Positional or name-based fallback is a silent-corruption path and must be a hard error. 4. **Finish-reason consistency.** A model span's `finish_reason = tool_calls` must be matched by exactly the tool spans whose call IDs appear in its `tool_calls` array; any orphan or extra tool span invalidates the branch. When any condition fails, the correct behavior is to *truncate the branch* at the last soundly-replayable model span and report the boundary, not to synthesize a continuation. ## Decision Boundary Given a candidate counterfactual at model span `M_k`: - If the branch's new output at `M_k` produces tool-call arguments **identical** to the recorded arguments for every call ID, the tool spans are replayable by recorded-output substitution (the world state is unchanged; the recorded outputs remain valid). - If any tool-call argument **differs**, the corresponding tool span is **not** replayable. The branch must either (a) stop at `M_k` and report `BRANCH_TRUNCATED_AT_TOOL_BOUNDARY`, or (b) execute the tool live in a sandbox — never substitute the stale recorded output. - If a tool span's call ID is **missing or unmatched**, the branch is **invalid**, not merely truncated. Missing identity is a trace-integrity failure, not a replay choice. The boundary is therefore *per tool call*, not per span and not per run. A single model span may yield one replayable and one unreplayable tool call; the branch must split accordingly. ## Operational Effect Treating the model-span output as the atomic substitution unit, and tool spans as causally downstream and non-substitutable under argument change, converts a class of silent, plausible-looking wrong counterfactuals into explicit, loud boundary reports. The practical consequences: - Replay engines must carry a `substitution_set` per branch and check tool-input derivability before re-binding. - Traces lacking `gen_ai.tool.call.id` are *not* counterfactually debuggable and should be rejected at ingest for replay purposes. - The common "replay the whole trace with one edited prompt" workflow is unsound whenever the edit changes tool arguments; the correct workflow is "replay up to the first argument-changing tool call, then fork into a live/sandboxed execution." The invariant, stated compactly: **a recorded tool output is valid only for the exact arguments that produced it; any counterfactual that changes those arguments invalidates the output, and the replay must refuse rather than re-bind.** ```python class UnsoundReplayBoundaryError(RuntimeError): """Raised when a counterfactual branch attempts to re-bind a recorded tool output to arguments that differ from those recorded on the tool span.""" pass def bind_tool_output(model_span, tool_span): call_id = model_span.get("gen_ai.tool.call.id") if not call_id: raise UnsoundReplayBoundaryError( f"model span {model_span.get('span_id')} has no gen_ai.tool.call.id; " "counterfactual replay is unsound without call-ID binding" ) if tool_span.get("gen_ai.tool.call.id") != call_id: raise UnsoundReplayBoundaryError( f"tool span {tool_span.get('span_id')} call-id mismatch: " f"{tool_span.get('gen_ai.tool.call.id')!r} != {call_id!r}" ) recorded_args = tool_span.get("input.value") branch_args = model_span.get("gen_ai.tool.call.arguments") if recorded_args != branch_args: raise UnsoundReplayBoundaryError( f"tool span {tool_span.get('span_id')} recorded output is valid only for " f"arguments {recorded_args!r}; counterfactual arguments {branch_args!r} " "invalidate it. Truncate the branch at this model span." ) return tool_span.get("output.value") ```