# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-reference-semantics-invariants-prevent-agents-from-treating-recents-and-stales-inconsistently.md
# Remnant Warrant:    https://corpusfetch.com/c/what-reference-semantics-invariants-prevent-agents-from-treating-recents-and-stales-inconsistently.warrant.json
# Markdown SHA-256:   0d7ee410ed859fda5b208a20f950372dd946cefebecaea1b46b9c5ceadd22cba
# Code AST SHA-256:   e5f1b5b919efbffd0613d8b278be09ea21a61f3b95a314e0fc280f3b68e277f4
# Verified Classes:   FreshnessVerdict, AgentFreshnessPolicy, MeshFreshness, FreshnessPolicy, FreshnessManifest, FreshnessSemanticsGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class FreshnessVerdict(Enum):
    POLICY_ALIGNED = auto()
    LEGITIMATE_OVERRIDE = auto()
    UNAUTHORIZED_DIVERGENCE = auto()
    NO_MESH_POLICY = auto()

@dataclass(frozen=True)
class AgentFreshnessPolicy:
    agent_id: str
    freshness_threshold_sec: float
    override_receipt: str | None

@dataclass(frozen=True)
class MeshFreshness:
    mesh_policy_threshold_sec: float | None
    agents: tuple[AgentFreshnessPolicy, ...]
    current_epoch: float
    reference_issue_epoch: float

@dataclass(frozen=True)
class FreshnessPolicy:
    require_mesh_policy: bool

@dataclass(frozen=True)
class FreshnessManifest:
    verdict: FreshnessVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_mesh(
        cls, mesh: MeshFreshness, policy: FreshnessPolicy
    ) -> FreshnessManifest:
        
        # Gate 1: No mesh policy
        if mesh.mesh_policy_threshold_sec is None:
            if policy.require_mesh_policy:
                return FreshnessManifest(
                    verdict=FreshnessVerdict.NO_MESH_POLICY,
                    directive=f"HALT: Mesh lacks freshness policy. Divergence inevitable.",
                    manifest_digest=cls._hash("NO_POLICY")
                )
            digest = cls._hash(json.dumps({
                "agents": str(len(mesh.agents)),
                "status": "NO_POLICY"
            }, sort_keys=True))
            return FreshnessManifest(
                verdict=FreshnessVerdict.POLICY_ALIGNED,
                directive=f"PROCEED: No mesh policy, individual agents operate independently.",
                manifest_digest=digest
            )

        # Gate 2: Compute reference age
        age = mesh.current_epoch - mesh.reference_issue_epoch

        # Gate 3: Check each agent's verdict for consistency
        mesh_fresh = age <= mesh.mesh_policy_threshold_sec
        for agent in mesh.agents:
            agent_fresh = age <= agent.freshness_threshold_sec

            # Agent agrees with mesh
            if agent_fresh == mesh_fresh:
                continue

            # Agent disagrees, check for legitimate override
            if agent.override_receipt:
                continue

            # Agent disagrees without authorization
            return FreshnessManifest(
                verdict=FreshnessVerdict.UNAUTHORIZED_DIVERGENCE,
                directive=f"HALT: Agent {agent.agent_id} verdict ({agent_fresh}) diverges from mesh ({mesh_fresh}) without override.",
                manifest_digest=cls._hash(f"DIVERGENCE:{agent.agent_id}")
            )

        # Gate 4: All aligned or legitimately overridden
        digest = cls._hash(json.dumps({
            "reference_age": f"{age:.1f}",
            "mesh_threshold": f"{mesh.mesh_policy_threshold_sec:.1f}",
            "mesh_fresh": str(mesh_fresh),
            "agents": str(len(mesh.agents))
        }, sort_keys=True))
        
        return FreshnessManifest(
            verdict=FreshnessVerdict.POLICY_ALIGNED,
            directive=f"PROCEED: {len(mesh.agents)} agents aligned (age {age:.1f}s, mesh threshold {mesh.mesh_policy_threshold_sec:.1f}s).",
            manifest_digest=digest
        )