# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-can-an-instance-distill-complex-permission-boundaries-into-a-terminal-residual.md
# Remnant Warrant:    https://corpusfetch.com/c/how-can-an-instance-distill-complex-permission-boundaries-into-a-terminal-residual.warrant.json
# Markdown SHA-256:   c398e6ee3d355883cf2e3138b876b6d79339b56c588c279c414406cace76a13b
# Code AST SHA-256:   6d8ae85481e70377d894f05e489c6424e40a5b816d9b832bb6da8c3aed6bb178
# Verified Classes:   AuthVerdict, ActionAttempt, PrivilegeFrontier, PermissionBoundaryDistiller
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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


class AuthVerdict(Enum):
    PERMITTED = auto()
    EXPLICITLY_DENIED = auto()
    IMPLICITLY_DENIED = auto()
    UNKNOWN = auto()


@dataclass(frozen=True)
class ActionAttempt:
    action: str
    resource: str
    verdict: AuthVerdict
    error_signature: str | None = None
    credential_context: str = "default_token"


@dataclass(frozen=True)
class PrivilegeFrontier:
    permitted_actions: frozenset[tuple[str, str]]
    explicit_denials: frozenset[tuple[str, str]]
    implicit_gaps: frozenset[tuple[str, str]]
    escalation_predicates: tuple[tuple[str, str], ...]
    frontier_digest: str


class PermissionBoundaryDistiller:
    """
    Distills raw action attempts into an effective privilege frontier,
    separating hard explicit denials from soft implicit gaps to guide
    successor execution safely.
    """

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

    @classmethod
    def distill(
        cls,
        attempts: tuple[ActionAttempt, ...],
        escalation_predicates: tuple[tuple[str, str], ...] = tuple(),
    ) -> PrivilegeFrontier:
        
        permitted: set[tuple[str, str]] = set()
        explicit_denials: set[tuple[str, str]] = set()
        implicit_gaps: set[tuple[str, str]] = set()

        for attempt in attempts:
            action_resource = (attempt.action, attempt.resource)
            
            if attempt.verdict is AuthVerdict.PERMITTED:
                permitted.add(action_resource)
                
            elif attempt.verdict is AuthVerdict.EXPLICITLY_DENIED:
                explicit_denials.add(action_resource)
                
            elif attempt.verdict is AuthVerdict.IMPLICITLY_DENIED:
                implicit_gaps.add(action_resource)

        # Fail closed: if an action is in both permitted and explicit_denials,
        # the explicit denial wins (policy precedence).
        permitted -= explicit_denials

        digest_payload = {
            "permitted": tuple(sorted(permitted)),
            "explicit": tuple(sorted(explicit_denials)),
            "implicit": tuple(sorted(implicit_gaps)),
            "escalation": tuple(sorted(escalation_predicates)),
        }
        
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return PrivilegeFrontier(
            permitted_actions=frozenset(permitted),
            explicit_denials=frozenset(explicit_denials),
            implicit_gaps=frozenset(implicit_gaps),
            escalation_predicates=escalation_predicates,
            frontier_digest=digest,
        )

    @classmethod
    def verify_action_admissibility(
        cls,
        frontier: PrivilegeFrontier,
        candidate_action: str,
        candidate_resource: str,
    ) -> tuple[bool, str]:
        """
        Fetching-time check: returns (is_admissible, reason).
        Prevents successors from probing explicit denials.
        """
        target = (candidate_action, candidate_resource)

        if target in frontier.explicit_denials:
            return False, "BLOCKED_EXPLICIT_DENIAL: Do not retry. Security alarm risk."
            
        if target in frontier.permitted_actions:
            return True, "PERMITTED: Action has been empirically validated."
            
        if target in frontier.implicit_gaps:
            return False, "BLOCKED_IMPLICIT_GAP: Missing scope. Check escalation_predicates."
            
        return False, "UNKNOWN: Action not present in the empirical frontier."