# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-invariants-must-survive-when-a-delegated-sub-agent-is-recalled-mid-execution.md
# Remnant Warrant:    https://corpusfetch.com/c/what-invariants-must-survive-when-a-delegated-sub-agent-is-recalled-mid-execution.warrant.json
# Markdown SHA-256:   74b8975bd5ecd1ebae4b9bd10ca9aaa53265aa4626602f8f247ac02c30262c70
# Code AST SHA-256:   6231de863b45d7036773c66cced9558b9ce740b340c615d16d7b65fb59fcf1ae
# Verified Classes:   RecallVerdict, RecallState, RecallPolicy, RecallManifest, SubAgentRecallGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class RecallVerdict(Enum):
    RECALL_ACTIVE = auto()
    RECALL_INFLIGHT_ACTIONS_PENDING = auto()
    RECALL_COMPLETION_GRACE_EXPIRED = auto()
    RECALL_NO_SIDE_EFFECTS_SAFE = auto()

@dataclass(frozen=True)
class RecallState:
    subagent_id: str
    recall_intent_sequence: int
    recall_intent_epoch: float
    in_flight_actions: tuple[str, ...]
    completion_grace_remaining_sec: float
    no_side_effects_receipt: str | None
    current_epoch: float

@dataclass(frozen=True)
class RecallPolicy:
    max_grace_sec: float

@dataclass(frozen=True)
class RecallManifest:
    verdict: RecallVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_recall(
        cls, state: RecallState, policy: RecallPolicy
    ) -> RecallManifest:
        
        # Gate 1: No side effects receipt
        if state.no_side_effects_receipt and not state.in_flight_actions:
            digest = cls._hash(json.dumps({
                "subagent": state.subagent_id,
                "sequence": str(state.recall_intent_sequence),
                "receipt": state.no_side_effects_receipt
            }, sort_keys=True))
            return RecallManifest(
                verdict=RecallVerdict.RECALL_NO_SIDE_EFFECTS_SAFE,
                directive="PROCEED: No side effects, recall safe to complete.",
                manifest_digest=digest
            )

        # Gate 2: In-flight actions
        if state.in_flight_actions:
            if state.completion_grace_remaining_sec > 0:
                return RecallManifest(
                    verdict=RecallVerdict.RECALL_INFLIGHT_ACTIONS_PENDING,
                    directive=f"WAIT: {len(state.in_flight_actions)} actions in flight. {state.completion_grace_remaining_sec:.0f}s grace remaining.",
                    manifest_digest=cls._hash(f"IN_FLIGHT:{len(state.in_flight_actions)}")
                )
            return RecallManifest(
                verdict=RecallVerdict.RECALL_COMPLETION_GRACE_EXPIRED,
                directive=f"HALT: Grace expired with {len(state.in_flight_actions)} actions possibly still completing. Reconcile.",
                manifest_digest=cls._hash(f"GRACE_EXPIRED:{len(state.in_flight_actions)}")
            )

        # Gate 3: Grace exceeded max
        if state.completion_grace_remaining_sec > policy.max_grace_sec:
            return RecallManifest(
                verdict=RecallVerdict.RECALL_INFLIGHT_ACTIONS_PENDING,
                directive=f"HALT: Declared grace {state.completion_grace_remaining_sec:.0f}s > max {policy.max_grace_sec:.0f}s.",
                manifest_digest=cls._hash(f"GRACE_TOO_LONG:{state.completion_grace_remaining_sec:.0f}")
            )

        # Gate 4: Active
        digest = cls._hash(json.dumps({
            "subagent": state.subagent_id,
            "sequence": str(state.recall_intent_sequence),
            "epoch": f"{state.recall_intent_epoch:.0f}"
        }, sort_keys=True))
        
        return RecallManifest(
            verdict=RecallVerdict.RECALL_ACTIVE,
            directive="PROCEED: Recall active, no side effects detected.",
            manifest_digest=digest
        )