# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-seal-a-session-residual-against-retroactive-state-mutation.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-seal-a-session-residual-against-retroactive-state-mutation.warrant.json
# Markdown SHA-256:   d8707c720e4209902de3db0055037e9331ac3b38c60a19ced9d90e7fc75f63cd
# Code AST SHA-256:   0e07b1f3ad7a091defc16a304275aacf1aa26412382465fecb63faad53c6f1af
# Verified Classes:   VerificationVerdict, ResidualPayload, SealedResidual, ResidualSealer
# Defensive Guards:   2 fail-closed invariants (zero external deps)

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


class VerificationVerdict(Enum):
    VERIFIED_INTACT = auto()
    HASH_MISMATCH = auto()
    LINEAGE_BROKEN = auto()
    SEQUENCE_REPLAYED = auto()


@dataclass(frozen=True)
class ResidualPayload:
    content: str
    session_id: str
    timestamp: float


@dataclass(frozen=True)
class SealedResidual:
    payload: ResidualPayload
    payload_hash: str
    parent_record_hash: str
    monotonic_sequence_number: int
    anchor_signature: str


class ResidualSealer:
    """
    Cryptographically seals a session residual against retroactive mutation
    by binding it to a parent hash, a monotonic sequence, and an external anchor.
    """

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

    @classmethod
    def _compute_anchor(
        cls, payload_hash: str, parent_hash: str, seq: int, secret_key: str
    ) -> str:
        message = f"{payload_hash}:{parent_hash}:{seq}".encode("utf-8")
        return hmac.new(secret_key.encode("utf-8"), message, hashlib.sha256).hexdigest()

    @classmethod
    def seal(
        cls,
        payload: ResidualPayload,
        parent_record_hash: str,
        monotonic_sequence_number: int,
        anchor_secret: str,
    ) -> SealedResidual:
        
        if not parent_record_hash.strip():
            raise ValueError("A parent record hash is required to prevent Rollback Forgery.")
            
        if monotonic_sequence_number < 0:
            raise ValueError("Sequence number must be non-negative.")

        payload_json = json.dumps(
            {
                "content": payload.content, 
                "session_id": payload.session_id, 
                "timestamp": str(payload.timestamp)
            },
            sort_keys=True,
            separators=(",", ":"),
        )
        payload_hash = cls._hash(payload_json)

        anchor_sig = cls._compute_anchor(
            payload_hash, parent_record_hash, monotonic_sequence_number, anchor_secret
        )

        return SealedResidual(
            payload=payload,
            payload_hash=payload_hash,
            parent_record_hash=parent_record_hash,
            monotonic_sequence_number=monotonic_sequence_number,
            anchor_signature=anchor_sig,
        )

    @classmethod
    def verify_lineage(
        cls,
        residual: SealedResidual,
        expected_parent_hash: str,
        expected_sequence: int,
        anchor_secret: str,
    ) -> tuple[VerificationVerdict, str]:
        """
        Fetching-time check: verifies internal integrity, lineage, sequence,
        and the external anchor to detect retroactive tampering.
        """
        
        # Gate 1: Verify payload bytes have not been mutated
        payload_json = json.dumps(
            {
                "content": residual.payload.content, 
                "session_id": residual.payload.session_id, 
                "timestamp": str(residual.payload.timestamp)
            },
            sort_keys=True,
            separators=(",", ":"),
        )
        computed_payload_hash = cls._hash(payload_json)
        
        if computed_payload_hash != residual.payload_hash:
            return VerificationVerdict.HASH_MISMATCH, "Payload bytes do not match the stored hash."

        # Gate 2: Verify lineage (parent hash)
        if residual.parent_record_hash != expected_parent_hash:
            return (
                VerificationVerdict.LINEAGE_BROKEN, 
                f"Expected parent {expected_parent_hash}, got {residual.parent_record_hash}."
            )

        # Gate 3: Verify sequence (replay protection)
        if residual.monotonic_sequence_number != expected_sequence:
            return (
                VerificationVerdict.SEQUENCE_REPLAYED, 
                f"Expected sequence {expected_sequence}, got {residual.monotonic_sequence_number}."
            )

        # Gate 4: Verify external anchor (tamper evidence)
        computed_anchor = cls._compute_anchor(
            residual.payload_hash,
            residual.parent_record_hash,
            residual.monotonic_sequence_number,
            anchor_secret,
        )
        
        if not hmac.compare_digest(computed_anchor, residual.anchor_signature):
            return (
                VerificationVerdict.HASH_MISMATCH, 
                "Anchor signature invalid. Record was tampered or forged."
            )

        return VerificationVerdict.VERIFIED_INTACT, "Lineage and integrity verified."