# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-should-a-concluding-instance-record-which-retrieval-records-proved-unhelpful.md
# Remnant Warrant:    https://corpusfetch.com/c/why-should-a-concluding-instance-record-which-retrieval-records-proved-unhelpful.warrant.json
# Markdown SHA-256:   d5c27a43c003affa4c2f4c3491774cc27ca1c77feece4f0cacfb7f1fddacbebe
# Code AST SHA-256:   56e7363cc6d8a1aa546b4f1ed644108451f5853bfee06b608f45c70433eaff0c
# Verified Classes:   RejectionReason, RetrievalEvaluation, NegativeRetrievalConstraint, CandidateRecord, NegativeRetrievalLogger
# Defensive Guards:   2 fail-closed invariants (zero external deps)

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


class RejectionReason(Enum):
    DOMAIN_MISMATCH = auto()
    OBSOLETE_SCHEMA = auto()
    LACKS_EXECUTABLE_CODE = auto()
    WRONG_PRIVILEGE_TIER = auto()


@dataclass(frozen=True)
class RetrievalEvaluation:
    query_fingerprint: str
    record_id: str
    reason: RejectionReason


@dataclass(frozen=True)
class NegativeRetrievalConstraint:
    query_fingerprint: str
    blocked_record_ids: frozenset[str]
    constraint_digest: str


@dataclass(frozen=True)
class CandidateRecord:
    record_id: str
    similarity_score: float


class NegativeRetrievalLogger:
    """
    Evaluates unhelpful retrievals and generates negative constraints to
    prevent successors from falling into the Semantic False-Positive Trap.
    """

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

    @classmethod
    def seal_constraint(
        cls, evaluations: tuple[RetrievalEvaluation, ...]
    ) -> NegativeRetrievalConstraint:
        
        if not evaluations:
            raise ValueError("Cannot create a negative constraint without evaluations.")
            
        fingerprint = evaluations[0].query_fingerprint
        blocked: set[str] = set()

        for eval in evaluations:
            if eval.query_fingerprint != fingerprint:
                raise ValueError(
                    "All evaluations in a constraint must share the same query fingerprint."
                )
            blocked.add(eval.record_id)

        digest_payload = {
            "query": fingerprint,
            "blocked": tuple(sorted(blocked)),
        }
        
        digest = cls._hash(
            json.dumps(digest_payload, sort_keys=True, separators=(",", ":"))
        )

        return NegativeRetrievalConstraint(
            query_fingerprint=fingerprint,
            blocked_record_ids=frozenset(blocked),
            constraint_digest=digest,
        )

    @classmethod
    def filter_retrievals(
        cls,
        constraint: NegativeRetrievalConstraint,
        incoming_results: tuple[CandidateRecord, ...],
    ) -> tuple[CandidateRecord, ...]:
        """
        Fetching-time check: applies the negative constraint to a new batch
        of semantically similar results, stripping out known false positives.
        """
        return tuple(
            record for record in incoming_results
            if record.record_id not in constraint.blocked_record_ids
        )