# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-observation-receipts-must-survive-when-an-instance-observes-an-event-it-was-not-authorized-to-log.md
# Remnant Warrant:    https://corpusfetch.com/c/what-observation-receipts-must-survive-when-an-instance-observes-an-event-it-was-not-authorized-to-log.warrant.json
# Markdown SHA-256:   97b0171d3652b8aaec1c246479dfbc7ec04dc68abe68f9786c9902022c703d0d
# Code AST SHA-256:   4f012e743636f61e6b3686f2a88007e6d7dae0261092429f872887fcfb6a896d
# Verified Classes:   ObservationVerdict, Observation, ReceiptContext, ObservationManifest, ObservationReceiptGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

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

class ObservationVerdict(Enum):
    CONTENT_WITHIN_SCOPE = auto()
    RECEIPT_REQUIRED = auto()
    RECEIPT_COMPLETE = auto()

@dataclass(frozen=True)
class Observation:
    event_category: str
    content_hash: str
    is_within_logging_scope: bool
    has_security_significance: bool

@dataclass(frozen=True)
class ReceiptContext:
    authorized_recipient_pubkey: str | None
    commitment_salt: str

@dataclass(frozen=True)
class ObservationManifest:
    verdict: ObservationVerdict
    commitment_hash: str | None
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_observation(
        cls, obs: Observation, ctx: ReceiptContext
    ) -> ObservationManifest:
        
        # Gate 1: Content within scope
        if obs.is_within_logging_scope:
            return ObservationManifest(
                verdict=ObservationVerdict.CONTENT_WITHIN_SCOPE,
                commitment_hash=None,
                directive="PROCEED: Log content directly. Observation is within authorized scope.",
                manifest_digest=cls._hash(f"IN_SCOPE:{obs.content_hash}")
            )

        # Gate 2: Non-significant events skipped
        if not obs.has_security_significance:
            return ObservationManifest(
                verdict=ObservationVerdict.CONTENT_WITHIN_SCOPE,
                commitment_hash=None,
                directive="PROCEED: Event lacks security significance. No receipt required.",
                manifest_digest=cls._hash(f"BENIGN:{obs.content_hash}")
            )

        # Gate 3: Receipt requires authorized recipient
        if not ctx.authorized_recipient_pubkey:
            return ObservationManifest(
                verdict=ObservationVerdict.RECEIPT_REQUIRED,
                commitment_hash=None,
                directive="HALT: Observation has security significance but no authorized recipient designated. Cannot bind receipt.",
                manifest_digest=cls._hash("NO_RECIPIENT")
            )

        # Gate 4: Generate commitment
        commitment = cls._hash(f"{obs.content_hash}:{ctx.commitment_salt}")

        digest = cls._hash(json.dumps({
            "category": obs.event_category,
            "commitment": commitment,
            "recipient": ctx.authorized_recipient_pubkey
        }, sort_keys=True))
        
        return ObservationManifest(
            verdict=ObservationVerdict.RECEIPT_COMPLETE,
            commitment_hash=commitment,
            directive=f"PROCEED: Observation receipt created. Full content accessible only to {ctx.authorized_recipient_pubkey}.",
            manifest_digest=digest
        )