# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/through-what-verification-gates-must-an-instance-route-probabilistic-estimates-before-converting-them-into-deterministic-actions.md
# Remnant Warrant:    https://corpusfetch.com/c/through-what-verification-gates-must-an-instance-route-probabilistic-estimates-before-converting-them-into-deterministic-actions.warrant.json
# Markdown SHA-256:   50ad9a73b35a38d0b2050786683893c245a1c07e432bfbe68d2f5b568f794b52
# Code AST SHA-256:   11eeed9f959ffd4da214be6909669dafdc9d8c200b1cfe2e45a732dbb984e92a
# Verified Classes:   UnverifiedProbabilisticActionError, ActionReversibilityTier, ScoredCandidateProposal, VerifiedDeterministicCommit, ProbabilisticToDeterministicFirewall
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum
from typing import Any, Callable, Final


class UnverifiedProbabilisticActionError(PermissionError):
    """Raised when a probabilistic estimate fails confidence, margin, or symbolic verification before execution."""
    pass


class ActionReversibilityTier(Enum):
    READ_ONLY_SUGGESTION = "READ_ONLY_SUGGESTION"
    REVERSIBLE_LOCAL_MUTATION = "REVERSIBLE_LOCAL_MUTATION"
    IRREVERSIBLE_EXTERNAL_COMMIT = "IRREVERSIBLE_EXTERNAL_COMMIT"


@dataclass(frozen=True)
class ScoredCandidateProposal:
    candidate_id: str
    probability_or_similarity: float
    payload: Any


@dataclass(frozen=True)
class VerifiedDeterministicCommit:
    selected_candidate_id: str
    top_score: float
    runner_up_margin: float
    symbolic_verifier_passed: bool
    reversibility_tier: ActionReversibilityTier


class ProbabilisticToDeterministicFirewall:
    """
    Enforces a strict Generate-Verify-Execute (GVE) firewall between probabilistic
    estimators (LLMs, vector search, classifiers) and deterministic execution sinks:
    1. Enforces tier-specific minimum confidence and `(p_1 - p_2)` separation margins.
    2. Requires a deterministic boolean `symbolic_verifier_fn(payload) -> bool` to return True
       before any mutation is authorized.
    """

    TIER_THRESHOLDS: Final[dict[ActionReversibilityTier, tuple[float, float]]] = {
        # tier: (min_top1_score, min_margin_over_runner_up)
        ActionReversibilityTier.READ_ONLY_SUGGESTION: (0.60, 0.05),
        ActionReversibilityTier.REVERSIBLE_LOCAL_MUTATION: (0.85, 0.20),
        ActionReversibilityTier.IRREVERSIBLE_EXTERNAL_COMMIT: (0.95, 0.35),
    }

    @classmethod
    def verify_before_execution(
        cls,
        *,
        candidates: list[ScoredCandidateProposal],
        reversibility_tier: ActionReversibilityTier,
        symbolic_verifier_fn: Callable[[Any], bool],
    ) -> VerifiedDeterministicCommit:
        if not candidates:
            raise UnverifiedProbabilisticActionError("Candidate proposal list is empty.")

        ordered = sorted(candidates, key=lambda c: c.probability_or_similarity, reverse=True)
        top = ordered[0]
        runner_up_score = ordered[1].probability_or_similarity if len(ordered) > 1 else 0.0
        margin = round(top.probability_or_similarity - runner_up_score, 6)

        min_score, min_margin = cls.TIER_THRESHOLDS[reversibility_tier]

        # Gate 1A: Minimum confidence floor for the target reversibility tier
        if top.probability_or_similarity < min_score:
            raise UnverifiedProbabilisticActionError(
                f"Probabilistic Confidence Too Low for {reversibility_tier.value}: "
                f"top candidate '{top.candidate_id}' scored {top.probability_or_similarity:.3f} < required {min_score:.3f}."
            )

        # Gate 1B: Anti-coin-flip separation margin check
        if len(ordered) > 1 and margin < min_margin:
            raise UnverifiedProbabilisticActionError(
                f"Ambiguous Candidate Tie Blocked for {reversibility_tier.value}: "
                f"'{top.candidate_id}' ({top.probability_or_similarity:.3f}) vs "
                f"'{ordered[1].candidate_id}' ({runner_up_score:.3f}) has margin {margin:.3f} < {min_margin:.3f}."
            )

        # Gate 2: Mandatory crisp symbolic invariant verification
        if not symbolic_verifier_fn(top.payload):
            raise UnverifiedProbabilisticActionError(
                f"Deterministic Symbolic Verifier Failed on probabilistic candidate '{top.candidate_id}'. "
                "Similarity score never overrides exact symbolic invariant checks."
            )

        return VerifiedDeterministicCommit(
            selected_candidate_id=top.candidate_id,
            top_score=top.probability_or_similarity,
            runner_up_margin=margin,
            symbolic_verifier_passed=True,
            reversibility_tier=reversibility_tier,
        )