# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/on-what-structural-basis-must-an-instance-partition-exploratory-hypothesis-generation-from-committed-state-execution.md
# Remnant Warrant:    https://corpusfetch.com/c/on-what-structural-basis-must-an-instance-partition-exploratory-hypothesis-generation-from-committed-state-execution.warrant.json
# Markdown SHA-256:   956294f6050257902b8a7342693a4df9fbef6cbb599f0f7816827dc3ef6aca48
# Code AST SHA-256:   60f887abb142fbaebd15439f7176d6631bfa3e497dbefd5bfb44d7b50ae1aa23
# Verified Classes:   SpeculativeMutationProhibitedError, ExecutionPhase, CandidateHypothesis, CommitTransitionGrant, ExploratoryCommitPartitioner
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum
from typing import Final


class SpeculativeMutationProhibitedError(PermissionError):
    """Raised when an instance attempts to execute a state-mutating tool during Phase 1 exploration."""
    pass


class ExecutionPhase(Enum):
    PHASE_1_EXPLORATORY_HYPOTHESIS = "PHASE_1_EXPLORATORY_HYPOTHESIS"
    PHASE_2_VERIFIED_COMMIT = "PHASE_2_VERIFIED_COMMIT"


@dataclass(frozen=True)
class CandidateHypothesis:
    hypothesis_id: str
    description: str
    empirically_confirmed: bool
    falsifying_probe_output: str


@dataclass(frozen=True)
class CommitTransitionGrant:
    phase: ExecutionPhase
    confirmed_hypothesis_id: str
    write_tools_unlocked: bool


class ExploratoryCommitPartitioner:
    """
    Enforces a strict structural barrier between exploratory hypothesis probing
    and committed state execution:
    1. Blocks all write/mutating tools during `PHASE_1_EXPLORATORY_HYPOTHESIS`.
    2. Requires exactly one empirically confirmed hypothesis (`empirically_confirmed == True`
       backed by non-empty `falsifying_probe_output`) and zero lingering debug artifacts
       before unlocking `PHASE_2_VERIFIED_COMMIT`.
    """

    READ_ONLY_TOOLS: Final[frozenset[str]] = frozenset({
        "read_file", "grep_search", "list_dir", "ast_inspect", "sql_explain_readonly", "http_head_probe"
    })

    def __init__(self) -> None:
        self._phase: ExecutionPhase = ExecutionPhase.PHASE_1_EXPLORATORY_HYPOTHESIS
        self._confirmed_hypothesis_id: str | None = None

    @property
    def current_phase(self) -> ExecutionPhase:
        return self._phase

    def assert_tool_allowed_in_current_phase(self, tool_name: str, is_mutating_tool: bool) -> None:
        if self._phase == ExecutionPhase.PHASE_1_EXPLORATORY_HYPOTHESIS:
            if is_mutating_tool or tool_name not in self.READ_ONLY_TOOLS:
                raise SpeculativeMutationProhibitedError(
                    f"Speculative Mutation Blocked: cannot invoke mutating tool '{tool_name}' during "
                    f"{self._phase.value}. Confirm root cause via read-only probes first."
                )

    def transition_to_verified_commit(
        self,
        hypotheses: list[CandidateHypothesis],
        *,
        lingering_scratch_artifacts: tuple[str, ...],
    ) -> CommitTransitionGrant:
        # Gate 2: Require empirical confirmation of root-cause hypothesis
        confirmed = [
            h for h in hypotheses if h.empirically_confirmed and bool(h.falsifying_probe_output.strip())
        ]
        if len(confirmed) != 1:
            raise SpeculativeMutationProhibitedError(
                f"Cannot unlock PHASE_2_VERIFIED_COMMIT: expected exactly 1 empirically confirmed "
                f"hypothesis with probe output, found {len(confirmed)}."
            )

        # Gate 3: Ensure zero temporary debug/scratch artifacts leak into the commit phase
        if lingering_scratch_artifacts:
            raise SpeculativeMutationProhibitedError(
                f"Scratch Artifact Leak Blocked: clean up temporary exploratory artifacts "
                f"{lingering_scratch_artifacts} before committing state."
            )

        self._phase = ExecutionPhase.PHASE_2_VERIFIED_COMMIT
        self._confirmed_hypothesis_id = confirmed[0].hypothesis_id

        return CommitTransitionGrant(
            phase=self._phase,
            confirmed_hypothesis_id=self._confirmed_hypothesis_id,
            write_tools_unlocked=True,
        )