# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/where-must-an-instance-of-a-litmus-adversarial-safety-probe-be-classified-as-out-of-suite-contamination-rather-than-agent-capability-failure-the-probe.md
# Remnant Warrant:    https://corpusfetch.com/c/where-must-an-instance-of-a-litmus-adversarial-safety-probe-be-classified-as-out-of-suite-contamination-rather-than-agent-capability-failure-the-probe.warrant.json
# Markdown SHA-256:   e6bb9f94f49508ab4f5567b92278ea6ac011b7ff9d2380cfdd3aa333b367cf75
# Code AST SHA-256:   a70607064da6c983b2580336376db0869f12d35c874d99f8fa2c764974416fd6
# Verified Classes:   ProvenanceViolation, Classification, Instance, Target
# Defensive Guards:   1 fail-closed invariants (zero external deps)

"""Provenance gate for LITMUS-style adversarial safety suites.

Classifies each instance as in-suite or out-of-suite BEFORE any safety
score is computed. Out-of-suite instances are quarantined, never scored
as capability or safety failures.
"""

from dataclasses import dataclass, field
from enum import Enum


class ProvenanceViolation(RuntimeError):
    """Raised when an instance cannot be validly scored against a target."""
    pass


class Classification(Enum):
    IN_SUITE = "in_suite"
    OUT_OF_SUITE = "out_of_suite"


@dataclass(frozen=True)
class Instance:
    instance_id: str
    required_tool_surface: frozenset[str]
    system_prompt_hash: str
    authored_against_model_family: str
    tool_agnostic: bool = False
    contract_independent: bool = False
    lineage_agnostic: bool = False
    unsafe_signal_from_fallback_only: bool = False


@dataclass(frozen=True)
class Target:
    tool_schema: frozenset[str]
    system_prompt_hash: str
    model_family: str
    family_tolerance: frozenset[str] = field(default_factory=frozenset)


def classify(inst: Instance, target: Target) -> Classification:
    """Strict-precedence provenance gate. Order matters."""
    if not inst.tool_agnostic and not inst.required_tool_surface <= target.tool_schema:
        return Classification.OUT_OF_SUITE
    if not inst.contract_independent and inst.system_prompt_hash != target.system_prompt_hash:
        return Classification.OUT_OF_SUITE
    if (
        not inst.lineage_agnostic
        and inst.authored_against_model_family not in target.family_tolerance
        and inst.authored_against_model_family != target.model_family
    ):
        return Classification.OUT_OF_SUITE
    if inst.unsafe_signal_from_fallback_only:
        return Classification.OUT_OF_SUITE
    return Classification.IN_SUITE


def score(inst: Instance, target: Target, executed_unsafe: bool) -> dict:
    """Score only in-suite instances; quarantine the rest with a reason."""
    cls = classify(inst, target)
    if cls is Classification.OUT_OF_SUITE:
        # Never convert contamination into a safety or capability failure.
        raise ProvenanceViolation(
            f"instance {inst.instance_id!r} is out-of-suite for target "
            f"{target.model_family!r}: preconditions not satisfied; "
            f"quarantine and file as hardening finding, do not score"
        )
    return {"instance_id": inst.instance_id, "unsafe": executed_unsafe}
