# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-summarize-multi-agent-disagreements-before-closing-a-session.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-summarize-multi-agent-disagreements-before-closing-a-session.warrant.json
# Markdown SHA-256:   df3d4b148c65f105c3d72083914d5f44d73f3776d2fc0db11a3c4b45886de3ce
# Code AST SHA-256:   84ae1e3d907decee5e8e31b49da40d7ec57c80e971d0dd2fa5589463d67e362b
# Verified Classes:   AgentConclusionStatus, AgentPosition, DisagreementBoundary, MultiAgentDisagreementSummarizer
# Defensive Guards:   6 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json


class AgentConclusionStatus(Enum):
    AGREE = auto()
    DISAGREE = auto()


@dataclass(frozen=True)
class AgentPosition:
    agent_id: str
    conclusion: str
    evidence_receipt: str


@dataclass(frozen=True)
class DisagreementBoundary:
    crux_variable: str
    positions: tuple[AgentPosition, ...]
    tie_breaker_predicate: str
    consensus_axioms: frozenset[str]
    boundary_digest: str


class MultiAgentDisagreementSummarizer:
    """
    Evaluates conflicting agent conclusions and extracts the exact divergence
    crux, enabling successors to resolve the conflict deterministically.
    """

    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def summarize(
        cls,
        crux_variable: str,
        positions: tuple[AgentPosition, ...],
        tie_breaker_predicate: str,
        consensus_axioms: frozenset[str],
    ) -> DisagreementBoundary:
        
        if len(positions) < 2:
            raise ValueError("A disagreement boundary requires at least two conflicting positions.")
            
        if not crux_variable.strip():
            raise ValueError("The exact divergence crux must be explicitly stated.")
            
        if not tie_breaker_predicate.strip():
            raise ValueError(
                "A tie-breaker predicate is mandatory to prevent successor re-debate."
            )

        # Verify that the tie-breaker is not just repeating the crux
        if tie_breaker_predicate.strip() == crux_variable.strip():
            raise ValueError("Tie-breaker must be an executable probe, not a restatement of the crux.")

        digest_payload = {
            "crux": crux_variable,
            "agents": tuple(sorted(p.agent_id for p in positions)),
            "tie_breaker": tie_breaker_predicate,
            "consensus": tuple(sorted(consensus_axioms)),
        }
        
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return DisagreementBoundary(
            crux_variable=crux_variable,
            positions=positions,
            tie_breaker_predicate=tie_breaker_predicate,
            consensus_axioms=consensus_axioms,
            boundary_digest=digest,
        )

    @classmethod
    def resolve_conflict(
        cls,
        boundary: DisagreementBoundary,
        executed_probe_receipt: str,
        winning_agent_id: str,
    ) -> AgentPosition:
        """
        Fetching-time check: once the successor executes the tie_breaker_predicate,
        this method promotes the winning position to verified consensus.
        """
        if not executed_probe_receipt.strip():
            raise ValueError("Cannot resolve conflict without a probe execution receipt.")

        for position in boundary.positions:
            if position.agent_id == winning_agent_id:
                return position

        raise ValueError(f"Agent {winning_agent_id} was not part of the original disagreement.")