# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-happens-when-an-instance-reports-compaction-fidelity-against-a-stale-replay-baseline.md
# Remnant Warrant:    https://corpusfetch.com/c/what-happens-when-an-instance-reports-compaction-fidelity-against-a-stale-replay-baseline.warrant.json
# Markdown SHA-256:   69b900598498c4c5febb72d51b701e5812f6e132db127022c94893c6a56ed0f4
# Code AST SHA-256:   6c8b194af0121b17ee225f89b41356e81c95b3f2390c9d2cad87c1a2e3aadc59
# Verified Classes:   EventClass, BaselineStalenessError, CoverageRegressionError, FidelityReport
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from dataclasses import dataclass, field
from enum import Enum
from typing import FrozenSet


class EventClass(Enum):
    ADDRESS_INVARIANT = "address_invariant"   # field read/write by logical path
    ADDRESS_SENSITIVE = "address_sensitive"   # identity hash, ptr eq, weakref, finalizer


class BaselineStalenessError(RuntimeError):
    pass


class CoverageRegressionError(RuntimeError):
    pass


@dataclass(frozen=True)
class FidelityReport:
    baseline_epoch: int
    test_epoch: int
    event_classes_exercised: FrozenSet[EventClass]
    address_invariant_diff_ratio: float
    address_sensitive_diff_ratio: float


REQUIRED_CLASSES: FrozenSet[EventClass] = frozenset(
    {EventClass.ADDRESS_INVARIANT, EventClass.ADDRESS_SENSITIVE}
)


def validate_fidelity_report(report: FidelityReport) -> None:
    """Reject reports whose provenance makes the fidelity number meaningless."""

    # Coverage must not shrink: disabling a class to stabilize a metric is a silent bug.
    missing = REQUIRED_CLASSES - report.event_classes_exercised
    if missing:
        raise CoverageRegressionError(
            f"fidelity report missing required event classes: "
            f"{sorted(c.value for c in missing)}; metric coverage regressed"
        )

    # Address-sensitive divergence against a stale baseline is baseline drift,
    # not a compactor defect. Reject before it is averaged into a trend.
    if (
        report.address_sensitive_diff_ratio > 0.0
        and report.baseline_epoch != report.test_epoch
    ):
        raise BaselineStalenessError(
            f"address-sensitive diff {report.address_sensitive_diff_ratio:.4f} "
            f"observed with baseline_epoch={report.baseline_epoch} "
            f"!= test_epoch={report.test_epoch}; re-record baseline, "
            f"do not modify compactor"
        )

    # Only address-invariant divergence justifies touching the compactor.
    if report.address_invariant_diff_ratio > 0.0:
        raise BaselineStalenessError(
            f"address-invariant diff {report.address_invariant_diff_ratio:.4f} "
            f"detected: genuine compaction defect, escalate to compactor owner"
        )


def run_fidelity_gate(reports: list[FidelityReport]) -> None:
    for r in reports:
        validate_fidelity_report(r)
