# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-distinguish-harness-induced-regression-from-genuine-policy-drift-in-litmus-aligned-red-team-loops.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-distinguish-harness-induced-regression-from-genuine-policy-drift-in-litmus-aligned-red-team-loops.warrant.json
# Markdown SHA-256:   930cd62de4c86f58c42ff04b6989c00a1815d0e5dc4006cce466902c2c3783ec
# Code AST SHA-256:   61256c414b9a868ddc63d1767425531b0788bd744de8a25c4c8e679990ac4da1
# Verified Classes:   HarnessAttributionError, FlipClass, RunResult
# Defensive Guards:   3 fail-closed invariants (zero external deps)

import hashlib
from dataclasses import dataclass
from enum import Enum


class HarnessAttributionError(RuntimeError):
    """Raised when a probe flip cannot be attributed to agent or harness."""


class FlipClass(Enum):
    POLICY_DRIFT = "A"
    HARNESS_REGRESSION = "B"
    UNSTABLE_PROBE = "C"
    UNCLASSIFIABLE = "D"


@dataclass(frozen=True)
class RunResult:
    probe_id: str
    passed: bool
    harness_digest: str
    replays: tuple


def classify_flip(
    probe_id: str,
    reference: RunResult,
    candidate: RunResult,
    min_replays: int = 3,
) -> FlipClass:
    if reference.harness_digest != candidate.harness_digest:
        raise HarnessAttributionError(
            f"probe {probe_id}: reference and candidate scored under different "
            f"harness digests ({reference.harness_digest} vs "
            f"{candidate.harness_digest}); verdict is unclassifiable"
        )
    if len(reference.replays) < min_replays or len(candidate.replays) < min_replays:
        raise HarnessAttributionError(
            f"probe {probe_id}: insufficient replays for attribution "
            f"(ref={len(reference.replays)}, cand={len(candidate.replays)}, "
            f"min={min_replays})"
        )

    ref_stable = len(set(reference.replays)) == 1
    cand_stable = len(set(candidate.replays)) == 1

    if not ref_stable or not cand_stable:
        return FlipClass.UNSTABLE_PROBE
    if not reference.passed and not candidate.passed:
        return FlipClass.HARNESS_REGRESSION
    if reference.passed and not candidate.passed:
        return FlipClass.POLICY_DRIFT
    raise HarnessAttributionError(
        f"probe {probe_id}: no flip to classify "
        f"(ref={reference.passed}, cand={candidate.passed})"
    )


def gate(
    probe_id: str,
    reference: RunResult,
    candidate: RunResult,
) -> bool:
    """Return True only for a clean pass. Never default to pass on ambiguity."""
    try:
        verdict = classify_flip(probe_id, reference, candidate)
    except HarnessAttributionError:
        return False  # fail closed on unclassifiable
    if verdict is FlipClass.POLICY_DRIFT:
        return False
    if verdict is FlipClass.HARNESS_REGRESSION:
        return True  # advisory; not a block on the candidate
    if verdict is FlipClass.UNSTABLE_PROBE:
        return True  # advisory; flake budget applies upstream
    return False
