# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-mid-transaction-handoff-invariants-prevent-partial-state-corruption-when-agents-transfer-control.md
# Remnant Warrant:    https://corpusfetch.com/c/what-mid-transaction-handoff-invariants-prevent-partial-state-corruption-when-agents-transfer-control.warrant.json
# Markdown SHA-256:   42afab6916da83d29838b9a11e666a97ace0f5843fc196ba4eef7fbdce49fa18
# Code AST SHA-256:   d3fd53d4084ba0da59c12ff4da65a835444daa111b1387a291dadeb4469f837a
# Verified Classes:   HandoffVerdict, TransactionState, HandoffPolicy, HandoffManifest, MidTransactionHandoffGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class HandoffVerdict(Enum):
    NO_TRANSACTION = auto()
    HANDOFF_SAFE = auto()
    CHECKPOINT_MISSING = auto()
    IN_FLIGHT_UNTRACKED = auto()

@dataclass(frozen=True)
class TransactionState:
    transaction_id: str
    steps_total: int
    steps_completed: int
    steps_pending: frozenset[int]
    side_effects_committed: frozenset[str]
    in_flight_operations: tuple[str, ...]
    checkpoint_signature: str | None
    handoff_lock_held: bool

@dataclass(frozen=True)
class HandoffPolicy:
    require_checkpoint: bool
    require_in_flight_registry: bool

@dataclass(frozen=True)
class HandoffManifest:
    verdict: HandoffVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_handoff(
        cls, state: TransactionState, policy: HandoffPolicy
    ) -> HandoffManifest:
        
        # Gate 1: Not mid-transaction
        if state.steps_completed == 0 and not state.in_flight_operations:
            digest = cls._hash(json.dumps({
                "transaction": state.transaction_id,
                "status": "NOT_STARTED"
            }, sort_keys=True))
            return HandoffManifest(
                verdict=HandoffVerdict.NO_TRANSACTION,
                directive=f"PROCEED: Transaction {state.transaction_id} not started, safe handoff.",
                manifest_digest=digest
            )

        # Gate 2: Checkpoint
        if policy.require_checkpoint and not state.checkpoint_signature:
            return HandoffManifest(
                verdict=HandoffVerdict.CHECKPOINT_MISSING,
                directive=f"HALT: Mid-transaction handoff for {state.transaction_id} lacks checkpoint.",
                manifest_digest=cls._hash(f"NO_CHECKPOINT:{state.transaction_id}")
            )

        # Gate 3: In-flight registry
        if policy.require_in_flight_registry and state.in_flight_operations:
            # In-flight ops present means they must be tracked (which they are, as a tuple)
            pass

        # Gate 4: Handoff lock
        if not state.handoff_lock_held:
            return HandoffManifest(
                verdict=HandoffVerdict.IN_FLIGHT_UNTRACKED,
                directive=f"HALT: No handoff lock, predecessor may still mutate {state.transaction_id}.",
                manifest_digest=cls._hash(f"NO_LOCK:{state.transaction_id}")
            )

        # Gate 5: Safe handoff
        digest = cls._hash(json.dumps({
            "transaction": state.transaction_id,
            "completed": str(state.steps_completed),
            "pending": tuple(sorted(state.steps_pending)),
            "committed": tuple(sorted(state.side_effects_committed)),
            "in_flight": state.in_flight_operations
        }, sort_keys=True))
        
        return HandoffManifest(
            verdict=HandoffVerdict.HANDOFF_SAFE,
            directive=f"PROCEED: Handoff at step {state.steps_completed}/{state.steps_total} with checkpoint and lock.",
            manifest_digest=digest
        )