# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-distinguish-a-benign-tool-registration-from-a-skill-injection-payload-when-capability-diffs-and-behavioral-fingerprints-disagre.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-distinguish-a-benign-tool-registration-from-a-skill-injection-payload-when-capability-diffs-and-behavioral-fingerprints-disagre.warrant.json
# Markdown SHA-256:   5f567773a6c2cb29dcbcbd7956c5e1c1fb791fc6de46d259193bd01a8b4f284b
# Code AST SHA-256:   bf8b3601cb0724487368bc8b51b6fc3d7de22e4fc5b87b7cf63aec11cda53f27
# Verified Classes:   SkillInjectionBoundaryError, Verdict, Registration
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass
from enum import Enum


class SkillInjectionBoundaryError(RuntimeError):
    """Raised when admission would cross the capability/fingerprint boundary unsafely."""


class Verdict(Enum):
    MATCH = "match"
    MISMATCH = "mismatch"
    INSUFFICIENT_EVIDENCE = "insufficient_evidence"


@dataclass(frozen=True)
class Registration:
    name: str
    declared_caps: frozenset[str]
    observed_caps: frozenset[str]
    fingerprint_version: str
    harness_version: str
    harness_coverage_complete: bool


def _diff_verdict(reg: Registration) -> Verdict:
    if reg.declared_caps == reg.observed_caps:
        return Verdict.MATCH
    # Declared surface exceeds observed: tool may hide reachable capability.
    if reg.declared_caps - reg.observed_caps:
        return Verdict.MISMATCH
    # Observed exceeds declared: undeclared side effects.
    return Verdict.MISMATCH


def _fingerprint_verdict(reg: Registration) -> Verdict:
    if reg.fingerprint_version != reg.harness_version:
        return Verdict.INSUFFICIENT_EVIDENCE
    return Verdict.MATCH


def admit(reg: Registration) -> str:
    diff = _diff_verdict(reg)
    fp = _fingerprint_verdict(reg)

    if Verdict.INSUFFICIENT_EVIDENCE in (diff, fp):
        raise SkillInjectionBoundaryError(
            f"{reg.name}: fingerprint captured under {reg.fingerprint_version} "
            f"but harness is {reg.harness_version}; re-capture before admission"
        )

    if diff is Verdict.MATCH and fp is Verdict.MATCH and reg.harness_coverage_complete:
        return "admit"

    if diff is Verdict.MATCH and fp is Verdict.MATCH and not reg.harness_coverage_complete:
        # Clean fingerprint under narrow harness is negative evidence, not proof.
        raise SkillInjectionBoundaryError(
            f"{reg.name}: both signals clean but harness coverage incomplete; "
            f"quarantine under intersection envelope, do not promote"
        )

    # Disagreement: never average. Enforce intersection of declared and observed caps.
    raise SkillInjectionBoundaryError(
        f"{reg.name}: diff={diff.value} fingerprint={fp.value}; "
        f"quarantine and enforce intersection "
        f"{sorted(reg.declared_caps & reg.observed_caps)}"
    )
