# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-partial-message-delivery-invariants-must-be-preserved-in-streaming-agent-protocols.md
# Remnant Warrant:    https://corpusfetch.com/c/what-partial-message-delivery-invariants-must-be-preserved-in-streaming-agent-protocols.warrant.json
# Markdown SHA-256:   5b80f6090089a3800e524c75cdab087fa638824768d791b8c4a3a8e1ffea0a6a
# Code AST SHA-256:   3c3a4779cd2c17ec1dabd83d4b5ddd1c48f60c224681e14aae16873748f7f8eb
# Verified Classes:   FramingVerdict, StreamState, FramingPolicy, FramingManifest, StreamFramingGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class FramingVerdict(Enum):
    MESSAGE_COMPLETE = auto()
    MESSAGE_IN_PROGRESS = auto()
    STALE_PARTIAL_BUFFER = auto()
    DISCARD_AND_RESET = auto()

@dataclass(frozen=True)
class StreamState:
    framing_mode: str  # "LENGTH_PREFIXED", "DELIMITED", "UNFRAMED"
    partial_buffer_hash: str | None
    last_byte_epoch: float
    expected_size: int | None

@dataclass(frozen=True)
class FramingPolicy:
    incomplete_timeout_sec: float
    current_epoch: float

@dataclass(frozen=True)
class FramingManifest:
    verdict: FramingVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_stream(
        cls, state: StreamState, policy: FramingPolicy
    ) -> FramingManifest:
        
        # Gate 1: Unframed stream rejection
        if state.framing_mode == "UNFRAMED":
            return FramingManifest(
                verdict=FramingVerdict.DISCARD_AND_RESET,
                directive="HALT: Unframed stream cannot be parsed reliably. Implement framing.",
                manifest_digest=cls._hash("UNFRAMED")
            )

        # Gate 2: No partial buffer
        if not state.partial_buffer_hash:
            return FramingManifest(
                verdict=FramingVerdict.MESSAGE_COMPLETE,
                directive="PROCEED: No partial buffer. Stream is at a clean message boundary.",
                manifest_digest=cls._hash("CLEAN")
            )

        # Gate 3: Timeout check
        age = policy.current_epoch - state.last_byte_epoch
        if age > policy.incomplete_timeout_sec:
            return FramingManifest(
                verdict=FramingVerdict.STALE_PARTIAL_BUFFER,
                directive=f"HALT: Partial buffer is {age:.1f}s old, exceeding {policy.incomplete_timeout_sec}s timeout. Discard.",
                manifest_digest=cls._hash(f"STALE:{age:.1f}")
            )

        # Gate 4: In progress
        digest = cls._hash(json.dumps({
            "buffer": state.partial_buffer_hash,
            "age": f"{age:.1f}",
            "expected": str(state.expected_size) if state.expected_size else "UNKNOWN"
        }, sort_keys=True))
        
        return FramingManifest(
            verdict=FramingVerdict.MESSAGE_IN_PROGRESS,
            directive="WAIT: Partial message in progress. Await remaining bytes.",
            manifest_digest=digest
        )