# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/which-cryptographic-watermarks-must-be-embedded-in-event-streams-to-prove-end-to-end-processing-integrity.md
# Remnant Warrant:    https://corpusfetch.com/c/which-cryptographic-watermarks-must-be-embedded-in-event-streams-to-prove-end-to-end-processing-integrity.warrant.json
# Markdown SHA-256:   82b460f5d8bb715b8134099cac1c25229cfbe8fa90817b303cc8ffe9201ce338
# Code AST SHA-256:   2c8c06a30fd250768ed4acf79f9cddd9296592db4919c22d268e8e5be9334172
# Verified Classes:   StreamVerdict, StreamEvent, ProcessingContext, StreamManifest, StreamIntegrityGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class StreamVerdict(Enum):
    VERIFIED_INTEGRITY = auto()
    TAMPERED = auto()
    REPLAY_DETECTED = auto()

@dataclass(frozen=True)
class StreamEvent:
    payload: str
    producer_hmac: str
    sequence_epoch: int

@dataclass(frozen=True)
class ProcessingContext:
    shared_secret: str
    last_seen_epoch: int

@dataclass(frozen=True)
class StreamManifest:
    verdict: StreamVerdict
    chaining_hash: str | None
    manifest_digest: str

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

    @classmethod
    def _compute_hmac(cls, payload: str, epoch: int, secret: str) -> str:
        msg = f"{payload}:{epoch}".encode("utf-8")
        return hmac.new(secret.encode("utf-8"), msg, hashlib.sha256).hexdigest()

    @classmethod
    def evaluate_stream_event(
        cls, event: StreamEvent, ctx: ProcessingContext
    ) -> StreamManifest:
        
        # Gate 1: Replay protection
        if event.sequence_epoch <= ctx.last_seen_epoch:
            return StreamManifest(
                verdict=StreamVerdict.REPLAY_DETECTED,
                chaining_hash=None,
                manifest_digest=cls._hash(f"REPLAY:{event.sequence_epoch}")
            )

        # Gate 2: HMAC validation
        expected_hmac = cls._compute_hmac(event.payload, event.sequence_epoch, ctx.shared_secret)
        
        if not hmac.compare_digest(expected_hmac, event.producer_hmac):
            return StreamManifest(
                verdict=StreamVerdict.TAMPERED,
                chaining_hash=None,
                manifest_digest=cls._hash(f"TAMPERED:{event.sequence_epoch}")
            )

        # Gate 3: Generate chaining hash
        chaining_hash = cls._hash(json.dumps({
            "in_hmac": event.producer_hmac,
            "epoch": str(event.sequence_epoch),
            "payload_hash": cls._hash(event.payload)
        }, sort_keys=True))
        
        return StreamManifest(
            verdict=StreamVerdict.VERIFIED_INTEGRITY,
            chaining_hash=chaining_hash,
            manifest_digest=cls._hash(f"VALID:{event.sequence_epoch}")
        )