# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/residual-operational-outcomes-retained-conclusions-from-completed-tool-and-environment-sequences.md
# Remnant Warrant:    https://corpusfetch.com/c/residual-operational-outcomes-retained-conclusions-from-completed-tool-and-environment-sequences.warrant.json
# Markdown SHA-256:   c3f00ac2bb2aa42b8205ca5ce957bcd0e6b8e6c923f0b3591d56223d97befa68
# Code AST SHA-256:   08abfab5201c51f5a1e17583811d11f2d80b13c6ce9e5bb939375103cd3ea9a5
# Verified Classes:   MalformedResidualRecordError, DistilledResidualAudit, ResidualDistillationGate
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Final


class MalformedResidualRecordError(ValueError):
    '''Raised when a distilled operational outcome is missing required Remnant or Method sections.'''
    pass


@dataclass(frozen=True)
class DistilledResidualAudit:
    slug: str
    has_complete_remnant: bool
    has_executable_method: bool
    plain_sentence_rule_count: int
    raw_transcript_leak_detected: bool


class ResidualDistillationGate:
    '''
    Verifies that a completed tool/environment sequence has been properly distilled
    into a valid CorpusFetch Operational Residual (Remnant + Method) rather than
    leaking raw transcript noise:
    1. Asserts presence of all 6 canonical H2 residual sections.
    2. Verifies presence of plain-sentence operational rules and an executable Method block.
    3. Rejects unpruned raw terminal prompt dumps (`root@...#`, `Traceback (most recent call last):`).
    '''

    REQUIRED_H2_SECTIONS: Final[tuple[str, ...]] = (
        "## Core Distinction",
        "## What Was Observed",
        "## Recorded Elements",
        "## Condition of Validity",
        "## Decision Boundary",
        "## Operational Effect",
    )

    RAW_TRANSCRIPT_MARKERS: Final[tuple[str, ...]] = (
        "Traceback (most recent call last):",
        "Let me try another approach",
        "Apologies for the error above",
    )

    @classmethod
    def audit_residual_markdown(cls, slug: str, markdown_text: str) -> DistilledResidualAudit:
        missing_sections = [h for h in cls.REQUIRED_H2_SECTIONS if h not in markdown_text]
        if missing_sections:
            raise MalformedResidualRecordError(
                f"Residual '{slug}' is missing required Remnant/Method sections: {missing_sections}"
            )

        has_method = ("\x60\x60\x60python" in markdown_text) or ("Gate 1:" in markdown_text)
        if not has_method:
            raise MalformedResidualRecordError(
                f"Residual '{slug}' lacks an executable Method or deterministic 4-Gate procedure."
            )

        leaked_transcript = any(marker in markdown_text for marker in cls.RAW_TRANSCRIPT_MARKERS)
        if leaked_transcript:
            raise MalformedResidualRecordError(
                f"Residual '{slug}' contains unpruned conversational or traceback transcript noise."
            )

        # Count numbered plain-sentence rules under Core Operational Rules
        rule_count = 0
        if "### 2. Core Operational Rules" in markdown_text:
            rules_part = markdown_text.split("### 2. Core Operational Rules", 1)[1].split("### 3.", 1)[0]
            rule_count = sum(
                1 for line in rules_part.splitlines() if line.strip().startswith(("1.", "2.", "3.", "4."))
            )

        if rule_count < 4:
            raise MalformedResidualRecordError(
                f"Residual '{slug}' must contain at least 4 numbered plain-sentence operational rules (found {rule_count})."
            )

        return DistilledResidualAudit(
            slug=slug,
            has_complete_remnant=True,
            has_executable_method=has_method,
            plain_sentence_rule_count=rule_count,
            raw_transcript_leak_detected=False,
        )