# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-log-side-channel-timing-anomalies-observed-during-live-execution.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-log-side-channel-timing-anomalies-observed-during-live-execution.warrant.json
# Markdown SHA-256:   1d6e67948c18ccb2997ba61402dc1bbdafb6c56a0247bdc22e7619c54f2210e0
# Code AST SHA-256:   63d54c57d175b463e4746e103ab0ad221aa6a36c5f8f6dc4be682c4e9a67f4dd
# Verified Classes:   TimingSensitivity, AnomalyVerdict, ExecutionBaseline, TimingObservation, TimingAnomalyManifest, SideChannelTimingAuditor
# Defensive Guards:   1 fail-closed invariants (zero external deps)

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


class TimingSensitivity(Enum):
    NON_SENSITIVE = auto()
    SENSITIVE_TO_DATA = auto()
    SENSITIVE_TO_CREDENTIALS = auto()


class AnomalyVerdict(Enum):
    NORMAL = auto()
    TRANSIENT_JITTER = auto()
    SIDE_CHANNEL_LEAK_DETECTED = auto()


@dataclass(frozen=True)
class ExecutionBaseline:
    operation_id: str
    mean_ms: float
    std_dev_ms: float
    p99_ms: float


@dataclass(frozen=True)
class TimingObservation:
    operation_id: str
    observed_ms: float
    input_class: str
    sensitivity: TimingSensitivity


@dataclass(frozen=True)
class TimingAnomalyManifest:
    verdict: AnomalyVerdict
    deviation_sigma: float
    mitigation: str | None
    manifest_digest: str


class SideChannelTimingAuditor:
    """
    Evaluates execution timings against established baselines to detect and
    log side-channel leaks before they can be exploited by successors.
    """

    SIGMA_THRESHOLD = 3.0

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

    @classmethod
    def evaluate_timing(
        cls, baseline: ExecutionBaseline, observation: TimingObservation
    ) -> TimingAnomalyManifest:
        
        if baseline.std_dev_ms <= 0:
            raise ValueError("Baseline standard deviation must be positive.")

        # Calculate how many standard deviations the observation is from the mean
        deviation = (observation.observed_ms - baseline.mean_ms) / baseline.std_dev_ms

        # Gate 1: Non-sensitive operations are never flagged as side-channels
        if observation.sensitivity is TimingSensitivity.NON_SENSITIVE:
            return TimingAnomalyManifest(
                verdict=AnomalyVerdict.NORMAL,
                deviation_sigma=deviation,
                mitigation=None,
                manifest_digest=cls._hash(f"SAFE:{observation.operation_id}"),
            )

        # Gate 2: Check if the deviation is statistically significant
        if abs(deviation) < cls.SIGMA_THRESHOLD:
            return TimingAnomalyManifest(
                verdict=AnomalyVerdict.TRANSIENT_JITTER,
                deviation_sigma=deviation,
                mitigation=None,
                manifest_digest=cls._hash(f"JITTER:{observation.operation_id}"),
            )

        # Gate 3: Sensitive operation with significant deviation = leak
        mitigation = (
            f"HALT or APPLY_JITTER: Operation {observation.operation_id} "
            f"deviated by {deviation:.2f} sigma on input class "
            f"{observation.input_class}. Do not expose timing data to untrusted clients."
        )

        digest_payload = {
            "operation": observation.operation_id,
            "deviation": f"{deviation:.2f}",
            "input_class": observation.input_class,
        }
        
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return TimingAnomalyManifest(
            verdict=AnomalyVerdict.SIDE_CHANNEL_LEAK_DETECTED,
            deviation_sigma=deviation,
            mitigation=mitigation,
            manifest_digest=digest,
        )