# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-index-compaction-strategies-must-be-paused-during-active-session-states.md
# Remnant Warrant:    https://corpusfetch.com/c/what-index-compaction-strategies-must-be-paused-during-active-session-states.warrant.json
# Markdown SHA-256:   84ad659eb40dda0dde87639c4d477973d912c9dfb375320df6901399ff4a94cb
# Code AST SHA-256:   732693066df522a480dd62bae1bdfca8bc3c72ddf9b415b85712db37cea5259f
# Verified Classes:   CompactionVerdict, IndexState, WriteContext, CompactionManifest, IndexCompactionGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class CompactionVerdict(Enum):
    PROCEED_SAFE = auto()
    DEFER_WRITE = auto()
    ACQUIRE_LEASE = auto()

@dataclass(frozen=True)
class IndexState:
    compaction_active: bool
    write_amplification_ratio: float
    pending_segment_count: int

@dataclass(frozen=True)
class WriteContext:
    is_latency_critical: bool
    has_lease: bool
    max_acceptable_amplification: float

@dataclass(frozen=True)
class CompactionManifest:
    verdict: CompactionVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_write(
        cls, state: IndexState, ctx: WriteContext
    ) -> CompactionManifest:
        
        # Gate 1: No compaction active or non-critical write
        if not state.compaction_active or not ctx.is_latency_critical:
            return CompactionManifest(
                verdict=CompactionVerdict.PROCEED_SAFE,
                directive="PROCEED: Compaction does not threaten this operation.",
                manifest_digest=cls._hash("SAFE")
            )

        # Gate 2: Lease already acquired
        if ctx.has_lease:
            return CompactionManifest(
                verdict=CompactionVerdict.PROCEED_SAFE,
                directive="PROCEED: Lease acquired. Compaction paused.",
                manifest_digest=cls._hash("LEASED")
            )

        # Gate 3: Amplification threshold exceeded
        if state.write_amplification_ratio >= ctx.max_acceptable_amplification:
            return CompactionManifest(
                verdict=CompactionVerdict.DEFER_WRITE,
                directive=f"HALT: Write amplification {state.write_amplification_ratio:.2f} exceeds {ctx.max_acceptable_amplification}. Defer write.",
                manifest_digest=cls._hash(f"DEFER:{state.write_amplification_ratio}")
            )

        # Gate 4: Acquire lease
        return CompactionManifest(
            verdict=CompactionVerdict.ACQUIRE_LEASE,
            directive="ACTION: Acquire maintenance lease before executing critical write.",
            manifest_digest=cls._hash("ACQUIRE_LEASE")
        )