# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-unrecoverable-speculative-divergence-in-multi-agent-rollback-and-branch-reconciliation.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-unrecoverable-speculative-divergence-in-multi-agent-rollback-and-branch-reconciliation.warrant.json
# Markdown SHA-256:   47517a629918105077dc4e2114a81e2a5554d3c8a2f30279ca5096ec60b2fdd7
# Code AST SHA-256:   0ade4399af6dc2d5fcb2acae903b89c336c21a27e1429065c0548f75565237ff
# Verified Classes:   SpeculativeDivergenceError, Branch
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass, field
from typing import Dict, List, Set, Tuple


class SpeculativeDivergenceError(RuntimeError):
    """Raised when reconciliation detects an unreachable (non-serial) merged state."""
    pass


@dataclass
class Branch:
    name: str
    read_versions: Dict[str, int] = field(default_factory=dict)   # key -> version read
    write_versions: Dict[str, int] = field(default_factory=dict)  # key -> version written
    commit_order: int = 0


def reconcile(branches: List[Branch]) -> Dict[str, int]:
    """
    Merge committed branches in commit order, but first prove read-set
    containment. If any pair is inverted (B read a version that A wrote
    after B's read), the merge is unreachable and must be aborted.
    """
    ordered = sorted(branches, key=lambda b: b.commit_order)
    inverted: List[Tuple[str, str, str]] = []

    for i, a in enumerate(ordered):
        for b in ordered[i + 1:]:
            for key, b_read_ver in b.read_versions.items():
                a_write_ver = a.write_versions.get(key)
                if a_write_ver is not None and a_write_ver > b_read_ver:
                    # B read a version that A overwrote after B's read:
                    # no serial order contains both as executed.
                    inverted.append((a.name, b.name, key))

    if inverted:
        raise SpeculativeDivergenceError(
            f"unreachable merged state: {len(inverted)} inverted read/write "
            f"pair(s) across branches: {inverted[:5]}"
        )

    merged: Dict[str, int] = {}
    for b in ordered:
        merged.update(b.write_versions)
    return merged


def run_group(branches: List[Branch]) -> Dict[str, int]:
    try:
        return reconcile(branches)
    except SpeculativeDivergenceError:
        # Correct response: abort and re-execute, never merge-and-continue.
        raise


# Reproduces the observed phantom interleaving:
# P writes v=1, E reads v=1 and writes v=2, V reads v=0 and writes v=-1.
# Commit order P, E, V yields v=1, but V read v=0 while P wrote v=1
# before V's read -> inverted pair (P, V) -> unreachable.
if __name__ == "__main__":
    group = [
        Branch("planner",  read_versions={"v": 0}, write_versions={"v": 1}, commit_order=1),
        Branch("executor", read_versions={"v": 1}, write_versions={"v": 2}, commit_order=2),
        Branch("verifier", read_versions={"v": 0}, write_versions={"v": -1}, commit_order=3),
    ]
    try:
        run_group(group)
    except SpeculativeDivergenceError as e:
        print(f"aborted at reconciliation gate: {e}")
