# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-consensus-barrier-signatures-must-be-recorded-when-a-multi-agent-commit-cannot-be-guaranteed.md
# Remnant Warrant:    https://corpusfetch.com/c/what-consensus-barrier-signatures-must-be-recorded-when-a-multi-agent-commit-cannot-be-guaranteed.warrant.json
# Markdown SHA-256:   5b1dfaa1e8ad6e23728ca3d87876f6035b01c1ed511172016b9603f13f1091ff
# Code AST SHA-256:   7031639744c9914227ea0ce28dc04c7acfcbcb2eeb9092e8fdc2ceb07521f13e
# Verified Classes:   BarrierStatus, ReconciliationVerdict, ParticipantAck, ConsensusBarrier, BarrierManifest, ConsensusBarrierGuard
# Defensive Guards:   1 fail-closed invariants (zero external deps)

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

class BarrierStatus(Enum):
    ACKNOWLEDGED = auto()
    REJECTED = auto()
    TIMEOUT = auto()
    LATE_ACKNOWLEDGED = auto()

class ReconciliationVerdict(Enum):
    FULL_COMMIT_SUCCESS = auto()
    SAFE_ROLL_FORWARD = auto()
    SAFE_ROLL_BACKWARD = auto()
    ESCALATE_REQUIRES_HUMAN = auto()
    PHANTOM_LATE_ACK = auto()

@dataclass(frozen=True)
class ParticipantAck:
    participant_id: str
    status: BarrierStatus
    ack_epoch: float
    compensating_succeeded: bool | None

@dataclass(frozen=True)
class ConsensusBarrier:
    commit_epoch_signature: float
    participants: tuple[ParticipantAck, ...]
    require_full_commit: bool

@dataclass(frozen=True)
class BarrierManifest:
    verdict: ReconciliationVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_barrier(
        cls, barrier: ConsensusBarrier
    ) -> BarrierManifest:
        
        if not barrier.participants:
            raise ValueError("Barrier must have participants.")

        acks = [p for p in barrier.participants if p.status == BarrierStatus.ACKNOWLEDGED]
        rejects = [p for p in barrier.participants if p.status == BarrierStatus.REJECTED]
        timeouts = [p for p in barrier.participants if p.status == BarrierStatus.TIMEOUT]
        late_acks = [p for p in barrier.participants if p.status == BarrierStatus.LATE_ACKNOWLEDGED]

        # Gate 1: Full commit
        if len(acks) == len(barrier.participants):
            digest = cls._hash(json.dumps({
                "participants": str(len(barrier.participants)),
                "status": "FULL"
            }, sort_keys=True))
            return BarrierManifest(
                verdict=ReconciliationVerdict.FULL_COMMIT_SUCCESS,
                directive="PROCEED: All participants acknowledged commit.",
                manifest_digest=digest
            )

        # Gate 2: Late acknowledgment (phantom state)
        if late_acks:
            return BarrierManifest(
                verdict=ReconciliationVerdict.PHANTOM_LATE_ACK,
                directive=f"HALT: Late acknowledgments from {[p.participant_id for p in late_acks]}. Phantom state present.",
                manifest_digest=cls._hash(f"LATE:{len(late_acks)}")
            )

        # Gate 3: Rejects present (safe rollback)
        if rejects:
            all_rolled_back = all(
                p.compensating_succeeded for p in acks if p.compensating_succeeded is not None
            )
            if not all_rolled_back:
                return BarrierManifest(
                    verdict=ReconciliationVerdict.ESCALATE_REQUIRES_HUMAN,
                    directive=f"HALT: {len(rejects)} participants rejected. Rollback incomplete on acks.",
                    manifest_digest=cls._hash(f"PARTIAL_ROLLBACK:{len(rejects)}")
                )
            return BarrierManifest(
                verdict=ReconciliationVerdict.SAFE_ROLL_BACKWARD,
                directive=f"PROCEED: {len(rejects)} rejects. Roll back {len(acks)} acknowledgments.",
                manifest_digest=cls._hash(f"ROLLBACK:{len(rejects)}")
            )

        # Gate 4: Timeouts (safe roll forward or escalate)
        if timeouts and barrier.require_full_commit:
            return BarrierManifest(
                verdict=ReconciliationVerdict.ESCALATE_REQUIRES_HUMAN,
                directive=f"HALT: {len(timeouts)} timeouts with full-commit required.",
                manifest_digest=cls._hash(f"TIMEOUT:{len(timeouts)}")
            )

        if timeouts:
            return BarrierManifest(
                verdict=ReconciliationVerdict.SAFE_ROLL_FORWARD,
                directive=f"PROCEED: {len(timeouts)} timeouts. Roll forward {len(acks)} acks.",
                manifest_digest=cls._hash(f"ROLL_FORWARD:{len(timeouts)}")
            )

        # Gate 5: Unknown state
        return BarrierManifest(
            verdict=ReconciliationVerdict.ESCALATE_REQUIRES_HUMAN,
            directive="HALT: Barrier state unclear. Escalate.",
            manifest_digest=cls._hash("UNKNOWN")
        )