# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-record-partial-failure-states-when-a-multi-agent-swarm-collapses.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-record-partial-failure-states-when-a-multi-agent-swarm-collapses.warrant.json
# Markdown SHA-256:   28e5c2f3f039a04569d838adb6101c8b7467fb926dc27b11c6d6c789451dbfea
# Code AST SHA-256:   405857478dd882d4575815cb5230f0fb17fc287691eb8b318c29023c721e9d96
# Verified Classes:   CollapseVerdict, SurvivorState, CollapseCheckpoint, CheckpointPolicy, CollapseManifest, SwarmCollapseGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class CollapseVerdict(Enum):
    CHECKPOINT_COMPLETE = auto()
    CHECKPOINT_CONTRADICTORY = auto()
    CHECKPOINT_INCOMPLETE = auto()

@dataclass(frozen=True)
class SurvivorState:
    agent_id: str
    state_hash: str
    last_heartbeat_epoch: float

@dataclass(frozen=True)
class CollapseCheckpoint:
    survivors: tuple[SurvivorState, ...]
    quorum_view_hash: str
    collapse_epoch: float
    baseline_hash_sync: str | None

@dataclass(frozen=True)
class CheckpointPolicy:
    min_survivors_for_consensus: int
    require_baseline_sync: bool

@dataclass(frozen=True)
class CollapseManifest:
    verdict: CollapseVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_checkpoint(
        cls, cp: CollapseCheckpoint, policy: CheckpointPolicy
    ) -> CollapseManifest:
        
        # Gate 1: Baseline sync requirement
        if policy.require_baseline_sync and not cp.baseline_hash_sync:
            return CollapseManifest(
                verdict=CollapseVerdict.CHECKPOINT_INCOMPLETE,
                directive="HALT: No baseline hash sync. Survivors may have contradictory states.",
                manifest_digest=cls._hash("NO_BASELINE")
            )

        # Gate 2: Survivor count
        if len(cp.survivors) < policy.min_survivors_for_consensus:
            return CollapseManifest(
                verdict=CollapseVerdict.CHECKPOINT_INCOMPLETE,
                directive=f"HALT: Only {len(cp.survivors)} survivors < minimum {policy.min_survivors_for_consensus}.",
                manifest_digest=cls._hash(f"INSUFFICIENT:{len(cp.survivors)}")
            )

        # Gate 3: Hash agreement
        unique_hashes = {s.state_hash for s in cp.survivors}
        if len(unique_hashes) > 1:
            return CollapseManifest(
                verdict=CollapseVerdict.CHECKPOINT_CONTRADICTORY,
                directive=f"HALT: {len(unique_hashes)} distinct state hashes among survivors. Contradictory checkpoint.",
                manifest_digest=cls._hash(f"CONTRADICTORY:{len(unique_hashes)}")
            )

        # Gate 4: Complete
        digest = cls._hash(json.dumps({
            "survivors": tuple(sorted(s.agent_id for s in cp.survivors)),
            "baseline": cp.baseline_hash_sync,
            "quorum": cp.quorum_view_hash,
            "collapse": f"{cp.collapse_epoch:.0f}"
        }, sort_keys=True))
        
        return CollapseManifest(
            verdict=CollapseVerdict.CHECKPOINT_COMPLETE,
            directive="PROCEED: Survivor states consistent. Checkpoint usable for recovery.",
            manifest_digest=digest
        )