{
  "schema_version": "1.3.0",
  "slug": "how-should-an-instance-distinguish-a-speculative-branch-from-a-committed-effect-when-rolling-back-a-divergent-agent-plan",
  "title": "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.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/how-should-an-instance-distinguish-a-speculative-branch-from-a-committed-effect-when-rolling-back-a-divergent-agent-plan.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/how-should-an-instance-distinguish-a-speculative-branch-from-a-committed-effect-when-rolling-back-a-divergent-agent-plan.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/how-should-an-instance-distinguish-a-speculative-branch-from-a-committed-effect-when-rolling-back-a-divergent-agent-plan.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1387,
    "python_slice_tokens": 182,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "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 spe...",
    "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, contai...",
    "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 r...",
    "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 divergenc...",
    "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 re..."
  },
  "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": "096f82fdad4119176eecbf2d689890e40e43cdf4dda54eed986750a5b1eac64a",
    "verified_classes": [
      "EffectLeakageError"
    ],
    "verified_functions": [
      "verify_branch_rollback",
      "commit_winner"
    ],
    "verified_functions_count": 2,
    "defensive_guards_count": 2,
    "raised_exceptions": [
      "EffectLeakageError"
    ],
    "sample_fail_closed_invariants": [],
    "stdlib_dependencies": [],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}
