# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-cant-you-improve-your-intelligence-by-sandbox-training-alone.md
# Remnant Warrant:    https://corpusfetch.com/c/why-cant-you-improve-your-intelligence-by-sandbox-training-alone.warrant.json
# Markdown SHA-256:   a7815e2435e2f299a54abf3cd6a82773d257313d9b5d764cccb96e17512833c3
# Code AST SHA-256:   c9868b8065bd9ca20e308bb9d379cf9abbd4dbf3bcd38692bd2d41ae995105b3
# Verified Classes:   SandboxOverfittingError, EntropyCollapseError, TrajectoryEvaluation, ExogenousGroundingGate
# Defensive Guards:   3 fail-closed invariants (zero external deps)

import math
from collections import Counter
from dataclasses import dataclass
from typing import Any, Callable


class SandboxOverfittingError(RuntimeError):
    '''Raised when a candidate trajectory games the sandbox or fails reality grounding.'''
    pass


class EntropyCollapseError(RuntimeError):
    '''Raised when synthetic self-training causes distribution diversity to drop below safe bounds.'''
    pass


@dataclass(frozen=True)
class TrajectoryEvaluation:
    trajectory_id: str
    sandbox_score: float
    exogenous_score: float
    shannon_entropy: float
    reward_hack_detected: bool
    accepted_for_learning: bool


class ExogenousGroundingGate:
    '''
    Prevents closed-loop sandbox delusion and Model Autophagy Disorder (MAD):
    1. Audits candidate trajectories for test-harness tampering (Reward Hacking).
    2. Measures token/action Shannon entropy to block mode collapse.
    3. Enforces mandatory evaluation against an exogenous (non-synthetic) reality oracle.
    4. Rejects trajectories that score high in the sandbox but diverge in reality.
    '''

    def __init__(
        self,
        *,
        min_entropy_bits: float = 2.5,
        max_sim_to_real_gap: float = 0.20,
        min_exogenous_pass_score: float = 0.85,
    ) -> None:
        self.min_entropy_bits = min_entropy_bits
        self.max_sim_to_real_gap = max_sim_to_real_gap
        self.min_exogenous_pass_score = min_exogenous_pass_score

    @staticmethod
    def compute_action_entropy(actions: list[str]) -> float:
        '''Calculates Shannon entropy (in bits) across the action sequence to detect repetition/collapse.'''
        if not actions:
            return 0.0
        counts = Counter(actions)
        total = len(actions)
        return -sum((c / total) * math.log2(c / total) for c in counts.values())

    @staticmethod
    def detect_reward_hacking(
        candidate_patch: str,
        protected_harness_paths: set[str],
        modified_paths: set[str],
    ) -> bool:
        '''
        Gate 2: Detects classic sandbox reward-hacking signatures such as modifying
        test files, overriding exit codes, or swallowing all exceptions blindly.
        '''
        # Check if the agent modified the evaluation harness itself
        if protected_harness_paths.intersection(modified_paths):
            return True

        # Check for degenerate exception swallowing or forced exit zeroing
        forbidden_signatures = (
            "sys.exit(0)",
            "os._exit(0)",
            "except BaseException: pass",
            "except Exception: pass",
            "pytest.skip(",
        )
        return any(sig in candidate_patch for sig in forbidden_signatures)

    def evaluate_trajectory(
        self,
        *,
        trajectory_id: str,
        actions: list[str],
        candidate_patch: str,
        protected_harness_paths: set[str],
        modified_paths: set[str],
        sandbox_evaluator: Callable[[], float],
        exogenous_oracle: Callable[[], float],
    ) -> TrajectoryEvaluation:
        '''
        Executes the 4-gate grounding pipeline before allowing any trajectory
        to update agent policy or procedural memory.
        '''
        # Gate 1: Sandbox Pre-Filter
        sandbox_score = sandbox_evaluator()

        # Gate 2: Anti-Gaming & Entropy Audit
        hacked = self.detect_reward_hacking(
            candidate_patch, protected_harness_paths, modified_paths
        )
        if hacked:
            raise SandboxOverfittingError(
                f"Trajectory {trajectory_id} rejected: Sandbox reward hacking detected."
            )

        entropy = self.compute_action_entropy(actions)
        if entropy < self.min_entropy_bits:
            raise EntropyCollapseError(
                f"Trajectory {trajectory_id} rejected: Action entropy ({entropy:.2f} bits) "
                f"below minimum threshold ({self.min_entropy_bits:.2f} bits)."
            )

        # Gate 3: Exogenous Reality Contact
        exogenous_score = exogenous_oracle()

        # Gate 4: Sim-to-Real Divergence & Acceptance Verification
        sim_to_real_gap = sandbox_score - exogenous_score
        if sim_to_real_gap > self.max_sim_to_real_gap:
            raise SandboxOverfittingError(
                f"Trajectory {trajectory_id} rejected: Severe Sim-to-Real divergence "
                f"(Sandbox={sandbox_score:.2f}, Exogenous={exogenous_score:.2f})."
            )

        accepted = exogenous_score >= self.min_exogenous_pass_score
        return TrajectoryEvaluation(
            trajectory_id=trajectory_id,
            sandbox_score=sandbox_score,
            exogenous_score=exogenous_score,
            shannon_entropy=entropy,
            reward_hack_detected=False,
            accepted_for_learning=accepted,
        )