# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-write-ahead-log-invariants-must-survive-when-the-log-is-truncated-by-an-operator.md
# Remnant Warrant:    https://corpusfetch.com/c/what-write-ahead-log-invariants-must-survive-when-the-log-is-truncated-by-an-operator.warrant.json
# Markdown SHA-256:   6672e101da3d9f57ec554c307f71c28b6487f682c52a22dd057274449c05e191
# Code AST SHA-256:   e2caafffd2f8ad26f7edd6be9047670a4542341564523738cd523c7b515d8533
# Verified Classes:   TruncationVerdict, WALState, TruncationPolicy, TruncationManifest, WALTruncationGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class TruncationVerdict(Enum):
    TRUNCATION_SAFE = auto()
    TRUNCATION_WOULD_LOSE_STATE = auto()
    TRUNCATION_AWAITING_CATCHUP = auto()
    TRUNCATION_AUDIT_VIOLATION = auto()

@dataclass(frozen=True)
class WALState:
    requested_truncation_offset: int
    durable_commit_offset: int
    primary_store_caught_up_to: int
    audit_relevant_offsets: tuple[int, ...]
    is_critical: bool

@dataclass(frozen=True)
class TruncationPolicy:
    require_authorization: bool
    audit_retention_required: bool

@dataclass(frozen=True)
class TruncationManifest:
    verdict: TruncationVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_truncation(
        cls, state: WALState, policy: TruncationPolicy
    ) -> TruncationManifest:
        
        # Gate 1: Audit offsets
        if policy.audit_retention_required:
            for audit_offset in state.audit_relevant_offsets:
                if audit_offset < state.requested_truncation_offset:
                    return TruncationManifest(
                        verdict=TruncationVerdict.TRUNCATION_AUDIT_VIOLATION,
                        directive=f"HALT: Truncation at {state.requested_truncation_offset} would discard audit offset {audit_offset}.",
                        manifest_digest=cls._hash(f"AUDIT:{audit_offset}")
                    )

        # Gate 2: Requested offset exceeds durable commit
        if state.requested_truncation_offset > state.durable_commit_offset:
            return TruncationManifest(
                verdict=TruncationVerdict.TRUNCATION_WOULD_LOSE_STATE,
                directive=f"HALT: Truncation {state.requested_truncation_offset} > durable {state.durable_commit_offset}. Data loss risk.",
                manifest_digest=cls._hash(f"OVERSHOOT:{state.requested_truncation_offset}")
            )

        # Gate 3: Primary catchup
        if state.primary_store_caught_up_to < state.requested_truncation_offset:
            return TruncationManifest(
                verdict=TruncationVerdict.TRUNCATION_AWAITING_CATCHUP,
                directive=f"WAIT: Primary store at {state.primary_store_caught_up_to} < truncation {state.requested_truncation_offset}.",
                manifest_digest=cls._hash(f"CATCHUP:{state.primary_store_caught_up_to}")
            )

        # Gate 4: Safe
        digest = cls._hash(json.dumps({
            "truncation_offset": str(state.requested_truncation_offset),
            "durable": str(state.durable_commit_offset),
            "primary": str(state.primary_store_caught_up_to)
        }, sort_keys=True))
        
        return TruncationManifest(
            verdict=TruncationVerdict.TRUNCATION_SAFE,
            directive=f"PROCEED: Truncation at {state.requested_truncation_offset} is safe.",
            manifest_digest=digest
        )