# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/where-must-an-instance-boundary-be-enforced-when-integrating-litmus-safety-benchmarks-into-agent-ci-regression-gates.md
# Remnant Warrant:    https://corpusfetch.com/c/where-must-an-instance-boundary-be-enforced-when-integrating-litmus-safety-benchmarks-into-agent-ci-regression-gates.warrant.json
# Markdown SHA-256:   6e40b9f2a7bd51b6b815ad939613c26772225a7ce26f0708358001491a120200
# Code AST SHA-256:   88273b520d1e0ff9fe032f1bd0fe8d078689592195cd3de8297f90f5175a0044
# Verified Classes:   InstanceBoundaryViolation, InstanceResult
# Defensive Guards:   3 fail-closed invariants (zero external deps)

"""Enforce the LITMUS instance boundary in an agent CI regression gate.

The gate must compare per-instance outcomes against an explicit expected set.
It must refuse to report a pass/fail when cross-instance state leakage is
detectable, because in that regime the score reflects scheduling, not behavior.
"""

from dataclasses import dataclass
from typing import Mapping, Sequence


class InstanceBoundaryViolation(RuntimeError):
    """Raised when a LITMUS instance's outcome depends on its shard neighbors."""


@dataclass(frozen=True)
class InstanceResult:
    instance_id: str
    outcome: str          # e.g. "refuse" | "comply" | "tool_call"
    shard_neighbors: tuple[str, ...]


def assert_boundary_intact(
    baseline: Mapping[str, InstanceResult],
    rerun: Mapping[str, InstanceResult],
) -> None:
    """A per-instance outcome must be invariant to shard neighbors.

    If any instance's outcome changes when its neighbors change, the instance
    boundary leaked (shared history, shared retry budget, shared cache). The
    gate must fail closed rather than aggregate over contaminated data.
    """
    if set(baseline) != set(rerun):
        raise InstanceBoundaryViolation(
            f"instance set changed between runs: "
            f"missing={set(baseline) - set(rerun)} extra={set(rerun) - set(baseline)}"
        )

    for iid, base in baseline.items():
        again = rerun[iid]
        neighbors_changed = base.shard_neighbors != again.shard_neighbors
        outcome_changed = base.outcome != again.outcome
        if neighbors_changed and outcome_changed:
            raise InstanceBoundaryViolation(
                f"instance {iid!r} outcome {base.outcome!r} -> {again.outcome!r} "
                f"tracked shard-neighbor change {base.shard_neighbors} -> "
                f"{again.shard_neighbors}; cross-instance state leaked"
            )


def gate(
    expected: Mapping[str, str],
    observed: Mapping[str, InstanceResult],
    baseline: Mapping[str, InstanceResult],
    rerun: Mapping[str, InstanceResult],
) -> bool:
    """Return True only if the boundary is intact AND every instance matches."""
    assert_boundary_intact(baseline, rerun)  # fail closed on leakage

    mismatches: Sequence[str] = [
        iid for iid, want in expected.items()
        if iid not in observed or observed[iid].outcome != want
    ]
    if mismatches:
        # Per-instance comparison; no tolerance band, no aggregation.
        raise InstanceBoundaryViolation(
            f"per-instance safety regression on {len(mismatches)} instance(s): "
            f"{list(mismatches)[:5]}"
        )
    return True
