# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-distill-multi-turn-debugging-into-a-single-residual.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-distill-multi-turn-debugging-into-a-single-residual.warrant.json
# Markdown SHA-256:   8c35426fd849d8853d3de0a8f427cf46d8787c69eac468dbf51607bf1a84add5
# Code AST SHA-256:   4488c5dcf55673ad4ca4c91ad67c1ebd3936fa84178b93bca6ef2742fdf0dc6a
# Verified Classes:   DebugTurnRole, DebugTurn, FalsifiedBranch, DebugResidual, DebugSessionDistiller
# Defensive Guards:   2 fail-closed invariants (zero external deps)

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


class DebugTurnRole(Enum):
    USER = auto()
    ASSISTANT = auto()
    TOOL_OUTPUT = auto()


@dataclass(frozen=True)
class DebugTurn:
    role: DebugTurnRole
    content: str
    error_signature: str | None = None


@dataclass(frozen=True)
class FalsifiedBranch:
    hypothesis: str
    terminal_error_signature: str


@dataclass(frozen=True)
class DebugResidual:
    issue_id: str
    root_cause_invariant: str
    falsified_branches: tuple[FalsifiedBranch, ...]
    verified_patch_hash: str
    regression_gate_command: str
    residual_digest: str


class DebugSessionDistiller:
    """
    Strips transient debugging narrative and extracts an irreducible residual
    containing the verified root cause, falsified branches, and regression gate.
    """

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

    @classmethod
    def distill(
        cls,
        issue_id: str,
        turns: tuple[DebugTurn, ...],
        root_cause_invariant: str,
        patch_content: str,
        regression_gate_command: str,
        fix_verified: bool,
    ) -> DebugResidual:
        if not fix_verified:
            raise RuntimeError(
                "Cannot distill residual: fix lacks an external ground-truth verification."
            )
        if not root_cause_invariant.strip():
            raise ValueError("Root cause invariant must be explicitly declared.")

        falsified: list[FalsifiedBranch] = []
        for turn in turns:
            # Extract failed execution attempts with deterministic error signatures
            if turn.role is DebugTurnRole.TOOL_OUTPUT and turn.error_signature:
                falsified.append(
                    FalsifiedBranch(
                        hypothesis=turn.content[:100],  # brief contextual anchor
                        terminal_error_signature=turn.error_signature,
                    )
                )

        patch_hash = cls._hash(patch_content)
        
        digest_payload = {
            "issue_id": issue_id,
            "root_cause": root_cause_invariant,
            "patch_hash": patch_hash,
            "gate": regression_gate_command,
        }
        residual_digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return DebugResidual(
            issue_id=issue_id,
            root_cause_invariant=root_cause_invariant,
            falsified_branches=tuple(falsified),
            verified_patch_hash=patch_hash,
            regression_gate_command=regression_gate_command,
            residual_digest=residual_digest,
        )

    @staticmethod
    def is_branch_falsified(
        residual: DebugResidual, candidate_hypothesis: str
    ) -> bool:
        """
        Fetching-time check: returns True if the candidate path matches a
        previously falsified branch, preventing cyclic debugging.
        """
        for branch in residual.falsified_branches:
            if candidate_hypothesis in branch.hypothesis:
                return True
        return False