{
  "schema_version": "1.3.0",
  "slug": "when-must-an-instance-treat-a-speculative-tool-invocation-as-irreversible",
  "title": "When must an instance treat a speculative tool invocation as irreversible",
  "date_of_record": "2026 November 12",
  "scope": "Applies to multi-agent orchestrators that execute speculative branches in parallel and merge results, where agents may invoke external tools (APIs, writes, payments, message sends) optimistically before the merge decision. Does not apply to purely read-only tool surfaces or to single-threaded agent loops where no rollback is possible.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/when-must-an-instance-treat-a-speculative-tool-invocation-as-irreversible.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/when-must-an-instance-treat-a-speculative-tool-invocation-as-irreversible.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/when-must-an-instance-treat-a-speculative-tool-invocation-as-irreversible.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1393,
    "python_slice_tokens": 234,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "The common mental model is that speculative execution is safe as long as each branch records a compensating action (an \"undo\") that the merge stage can replay for losing branches. This model conflates two different properties: *reversibility* and *idempotent convergence*. A branch is only safely rollback-able if, after the compensating action runs, the obser...",
    "what_was_observed": "A three-branch planning agent was speculatively executing a customer-refund workflow. Branch B called `issue_refund(order_id, amount)` optimistically, planning to compensate with `reverse_refund(refund_id)` if branch A won the merge. The merge completed in 340 ms and the reverse succeeded. The refund, however, had already emitted a `refund.succeeded` webhook to the payment provider's downstream settlement service, wh...",
    "condition_of_validity": "Optimistic invocation with branch-and-merge rollback is valid if and only if, at the instant the tool returns, all of the following hold: 1. **Observer isolation.** No external principal can observe the effect (via event, webhook, poll, or shared state) until the orchestrator explicitly commits. 2. **Fence integrity.** The effect is bound to a transaction or...",
    "decision_boundary": "Classify each tool in the agent's toolset at registration time along two axes: *effect visibility* (orchestrator-private vs. externally observable) and *compensability* (fully reversible vs. irreversible). The decision rule: - **Private + reversible:** invoke optimistically. Rollback is a local state mutation. - **Private + irreversible:** invoke optimistica...",
    "operational_effect": "Orchestrators that enforce this boundary see speculative speedup only on the private-and-fenced subset of their toolset — typically 40–60% of calls in a well-instrumented agent. The remaining calls become merge-gated, which lengthens the critical path but eliminates the class of reconciliation failures described above. The measurable signal is a drop in \"pha..."
  },
  "matched_failure_symptoms": [
    "DOMAIN:EPISTEMIC_PROVENANCE_AND_FEDERATION_ROUTING"
  ],
  "composition_edges": {
    "primary_domain": "epistemic_provenance_and_federation_routing",
    "upstream_precondition_residuals": [
      "https://corpusfetch.com/c/according-to-what-precedence-hierarchy-must-an-instance-resolve-contradictory-directives-across-system-developer-and-user-tiers.md",
      "https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.md"
    ],
    "downstream_consequence_residuals": [
      "https://corpusfetch.com/c/by-what-checkpoint-and-compaction-boundaries-must-an-instance-externalize-working-state-to-prevent-context-window-drift-and-truncation-amnesia.md",
      "https://corpusfetch.com/c/across-what-additive-schema-and-unknown-field-preservation-boundaries-must-an-instance-evolve-wire-contracts-to-prevent-rolling-deploy-deserialization-crashes.md"
    ],
    "co_occurring_sibling_residuals": [
      "https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.md",
      "https://corpusfetch.com/c/how-can-an-instance-compress-long-reasoning-traces-into-binding-conclusions.md"
    ]
  },
  "empirical_verification_warrant": {
    "status": "AST_AND_INVARIANT_VERIFIED",
    "syntax_valid": true,
    "code_sha256": "441cc91ee2d5639ad92f7ecdf5b8a50fe032d73ff2ac6d3d386d607285125808",
    "verified_classes": [
      "EffectVisibility",
      "Compensability",
      "IrreversibleSpeculationError",
      "ToolProfile"
    ],
    "verified_functions": [
      "authorize_optimistic_invocation",
      "run_branch"
    ],
    "verified_functions_count": 2,
    "defensive_guards_count": 2,
    "raised_exceptions": [
      "IrreversibleSpeculationError"
    ],
    "sample_fail_closed_invariants": [],
    "stdlib_dependencies": [
      "dataclasses",
      "enum"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}