# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-discover-root-causes-when-observability-data-is-intentionally-sparse.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-discover-root-causes-when-observability-data-is-intentionally-sparse.warrant.json
# Markdown SHA-256:   63e03b4b6a9ed0d970d584fc7d03729462552fe0807ae1a74b204b20c7851a4c
# Code AST SHA-256:   0188506d9a460b4ee7667341b6e32e54a86add9784d216ccc2bb2475d915fa7b
# Verified Classes:   RootCauseVerdict, ObservabilityContext, RootCausePolicy, RootCauseManifest, SparseObservabilityGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class RootCauseVerdict(Enum):
    HEALTH_CONFIRMED = auto()
    INCONCLUSIVE_SPARSE = auto()
    PIPELINE_UNHEALTHY = auto()

@dataclass(frozen=True)
class ObservabilityContext:
    sampling_rate: float
    pipeline_healthy: bool
    redaction_applied: bool
    active_probe_passed: bool
    incident_detection_probability: float

@dataclass(frozen=True)
class RootCausePolicy:
    min_confidence_threshold: float

@dataclass(frozen=True)
class RootCauseManifest:
    verdict: RootCauseVerdict
    confidence: float
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_absence(
        cls, ctx: ObservabilityContext, policy: RootCausePolicy
    ) -> RootCauseManifest:
        
        # Gate 1: Pipeline health
        if not ctx.pipeline_healthy:
            return RootCauseManifest(
                verdict=RootCauseVerdict.PIPELINE_UNHEALTHY,
                confidence=0.0,
                directive="HALT: Observability pipeline unhealthy. Absence of evidence is not evidence.",
                manifest_digest=cls._hash("PIPELINE_DOWN")
            )

        # Gate 2: Confidence from sampling rate
        confidence = ctx.incident_detection_probability

        # Gate 3: Active probe required for sparse data
        if ctx.sampling_rate < 1.0 and not ctx.active_probe_passed:
            return RootCauseManifest(
                verdict=RootCauseVerdict.INCONCLUSIVE_SPARSE,
                confidence=confidence,
                directive=f"WARN: Sparse sampling ({ctx.sampling_rate:.2%}). Active probe required before concluding health.",
                manifest_digest=cls._hash(f"SPARSE:{ctx.sampling_rate:.3f}")
            )

        # Gate 4: Confidence threshold
        if confidence < policy.min_confidence_threshold:
            return RootCauseManifest(
                verdict=RootCauseVerdict.INCONCLUSIVE_SPARSE,
                confidence=confidence,
                directive=f"WARN: Confidence {confidence:.2f} < threshold {policy.min_confidence_threshold:.2f}.",
                manifest_digest=cls._hash(f"LOW_CONF:{confidence:.3f}")
            )

        # Gate 5: Healthy
        digest = cls._hash(json.dumps({
            "sample": f"{ctx.sampling_rate:.3f}",
            "confidence": f"{confidence:.3f}",
            "probe": str(ctx.active_probe_passed)
        }, sort_keys=True))
        
        return RootCauseManifest(
            verdict=RootCauseVerdict.HEALTH_CONFIRMED,
            confidence=confidence,
            directive=f"PROCEED: Health confirmed with confidence {confidence:.2f}.",
            manifest_digest=digest
        )