# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-happens-when-an-instance-merges-speculative-agent-branches-whose-tool-effects-alias-on-a-shared-idempotency-key.md
# Remnant Warrant:    https://corpusfetch.com/c/what-happens-when-an-instance-merges-speculative-agent-branches-whose-tool-effects-alias-on-a-shared-idempotency-key.warrant.json
# Markdown SHA-256:   4f052315f9d970da3e04bd8b2acba626bd24743db6c5d3f4b92dcd57d028ec7a
# Code AST SHA-256:   492d74b3559581edfb6dff2d794c7528b185c1beeb5012c3494bb0992271afa7
# Verified Classes:   AliasedEffectConflict, ToolEffect
# Defensive Guards:   1 fail-closed invariants (zero external deps)

import hashlib
from dataclasses import dataclass


class AliasedEffectConflict(RuntimeError):
    """Raised when two branches collide on an idempotency key with divergent payloads."""


@dataclass(frozen=True)
class ToolEffect:
    branch_id: str
    step_seq: int
    idempotency_key: str
    payload: str


def idempotency_key(run_id: str, branch_id: str, step_seq: int, payload: str) -> str:
    # Key must be injective over branch identity AND payload.
    h = hashlib.sha256()
    h.update(f"{run_id}|{branch_id}|{step_seq}|{payload}".encode())
    return h.hexdigest()


def reconcile_effects(effects: list[ToolEffect]) -> list[ToolEffect]:
    """Collapse effects by idempotency key, rejecting aliased-payload collisions."""
    by_key: dict[str, ToolEffect] = {}
    for eff in effects:
        prior = by_key.get(eff.idempotency_key)
        if prior is None:
            by_key[eff.idempotency_key] = eff
            continue
        if prior.payload != eff.payload:
            raise AliasedEffectConflict(
                f"idempotency key {eff.idempotency_key!r} aliased by branches "
                f"{prior.branch_id!r} (payload={prior.payload!r}) and "
                f"{eff.branch_id!r} (payload={eff.payload!r}); "
                f"external effect would silently collapse to one of them"
            )
        # benign deduplication: identical payload, commit once
    return list(by_key.values())


def merge_branches(run_id: str, branch_effects: dict[str, list[tuple[int, str]]]) -> list[ToolEffect]:
    effects: list[ToolEffect] = []
    for branch_id, steps in branch_effects.items():
        for step_seq, payload in steps:
            key = idempotency_key(run_id, branch_id, step_seq, payload)
            effects.append(ToolEffect(branch_id, step_seq, key, payload))
    return reconcile_effects(effects)
