# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-minimum-telemetry-summary-must-survive-after-purging-verbose-execution-logs.md
# Remnant Warrant:    https://corpusfetch.com/c/what-minimum-telemetry-summary-must-survive-after-purging-verbose-execution-logs.warrant.json
# Markdown SHA-256:   76ecf2c95614180ca5b580d8cf1cd315da297d4f77e3f5ad5b209ac1b99f35da
# Code AST SHA-256:   c22c5de774756e673cd3034acdd2693a3893c013718fc9e547a645bcd3dcef42
# Verified Classes:   TelemetryVerdict, RawLogEntry, TelemetrySummary, SummaryManifest, TelemetryPurgingGuard
# Defensive Guards:   2 fail-closed invariants (zero external deps)

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


class TelemetryVerdict(Enum):
    SUMMARY_COMPLETE = auto()
    MISSING_TAIL_PERCENTILES = auto()
    FAILURE_MODES_COLLAPSED = auto()


@dataclass(frozen=True)
class RawLogEntry:
    operation_id: str
    latency_ms: float
    status_signature: str  # e.g., "200", "429", "TIMEOUT"


@dataclass(frozen=True)
class TelemetrySummary:
    operation_id: str
    latency_percentiles: tuple[tuple[str, float], ...]
    failure_cardinality: tuple[tuple[str, int], ...]
    throughput_envelope: tuple[float, float, float]  # min, p50, max


@dataclass(frozen=True)
class SummaryManifest:
    verdict: TelemetryVerdict
    operations_covered: int
    manifest_digest: str


class TelemetryPurgingGuard:
    """
    Evaluates whether a candidate telemetry summary preserves enough
    distributional shape to safely purge raw logs.
    """

    REQUIRED_PERCENTILES = frozenset({"p50", "p95", "p99", "p999"})

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

    @classmethod
    def _percentile(cls, sorted_values: list[float], pct: float) -> float:
        if not sorted_values:
            return 0.0
        idx = min(len(sorted_values) - 1, int(len(sorted_values) * pct))
        return sorted_values[idx]

    @classmethod
    def build_summary_from_raw(
        cls, raw_logs: tuple[RawLogEntry, ...]
    ) -> tuple[TelemetrySummary, ...]:
        """
        Utility: computes the minimum summary from raw logs before purging.
        """
        by_op: dict[str, list[RawLogEntry]] = {}
        for entry in raw_logs:
            by_op.setdefault(entry.operation_id, []).append(entry)

        summaries: list[TelemetrySummary] = []

        for op_id, entries in by_op.items():
            latencies = sorted(e.latency_ms for e in entries)
            
            percentiles = (
                ("p50", cls._percentile(latencies, 0.50)),
                ("p95", cls._percentile(latencies, 0.95)),
                ("p99", cls._percentile(latencies, 0.99)),
                ("p999", cls._percentile(latencies, 0.999)),
            )

            failures: dict[str, int] = {}
            for e in entries:
                failures[e.status_signature] = failures.get(e.status_signature, 0) + 1

            envelope = (
                latencies[0] if latencies else 0.0,
                latencies[len(latencies) // 2] if latencies else 0.0,
                latencies[-1] if latencies else 0.0,
            )

            summaries.append(
                TelemetrySummary(
                    operation_id=op_id,
                    latency_percentiles=percentiles,
                    failure_cardinality=tuple(sorted(failures.items())),
                    throughput_envelope=envelope,
                )
            )

        return tuple(summaries)

    @classmethod
    def evaluate_summary(
        cls, summaries: tuple[TelemetrySummary, ...]
    ) -> SummaryManifest:
        
        if not summaries:
            raise ValueError("Cannot evaluate an empty telemetry summary.")

        missing_tail = False
        collapsed_failure = False

        for summary in summaries:
            reported = {name for name, _ in summary.latency_percentiles}
            if not cls.REQUIRED_PERCENTILES.issubset(reported):
                missing_tail = True

            if (
                len(summary.failure_cardinality) == 1
                and summary.failure_cardinality[0][0] in ("ERROR", "FAILURE")
            ):
                collapsed_failure = True

        if missing_tail:
            verdict = TelemetryVerdict.MISSING_TAIL_PERCENTILES
        elif collapsed_failure:
            verdict = TelemetryVerdict.FAILURE_MODES_COLLAPSED
        else:
            verdict = TelemetryVerdict.SUMMARY_COMPLETE

        digest_payload = {
            "verdict": verdict.name,
            "operations": str(len(summaries)),
        }
        
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return SummaryManifest(
            verdict=verdict,
            operations_covered=len(summaries),
            manifest_digest=digest,
        )

    @classmethod
    def assert_purge_admissible(cls, manifest: SummaryManifest) -> None:
        """
        Fail-closed enforcement: raises if the summary is insufficient to
        justify purging the raw logs.
        """
        if manifest.verdict is not TelemetryVerdict.SUMMARY_COMPLETE:
            raise RuntimeError(
                f"PURGE REJECTED: Telemetry summary insufficient. Reason: {manifest.verdict.name}"
            )