# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/where-must-an-instance-of-taint-aware-tool-routing-enforce-the-quarantine-boundary-between-untrusted-retrieved-content-and-privileged-tool-invocation.md
# Remnant Warrant:    https://corpusfetch.com/c/where-must-an-instance-of-taint-aware-tool-routing-enforce-the-quarantine-boundary-between-untrusted-retrieved-content-and-privileged-tool-invocation.warrant.json
# Markdown SHA-256:   2eb68725a30cb8c8dfa73179040b912ecb73f00a7cb54042d4a42a39cc17c793
# Code AST SHA-256:   6155914e2d13cea502d2906bb0414014500d5bf144b78dbc062bb3081ce2afea
# Verified Classes:   EffectClass, TrustClass, QuarantineViolation, Segment, Invocation, ProvenanceGraph
# Defensive Guards:   5 fail-closed invariants (zero external deps)

from dataclasses import dataclass, field
from enum import IntEnum
from typing import Dict, List


class EffectClass(IntEnum):
    READ_ONLY = 0
    REVERSIBLE_WRITE = 1
    IRREVERSIBLE_EXTERNAL = 2


class TrustClass(IntEnum):
    UNTRUSTED = 0
    DERIVED = 1
    TRUSTED = 2


class QuarantineViolation(RuntimeError):
    """Raised when an assembled tool invocation exceeds the trust ceiling."""


@dataclass
class Segment:
    seg_id: str
    trust: TrustClass


@dataclass
class Invocation:
    tool: str
    effect: EffectClass
    # slot name -> list of segment ids contributing bytes to that slot
    slot_provenance: Dict[str, List[str]] = field(default_factory=dict)


class ProvenanceGraph:
    def __init__(self) -> None:
        self._trust: Dict[str, TrustClass] = {}

    def register(self, seg: Segment) -> None:
        self._trust[seg.seg_id] = seg.trust

    def launder(self, dst: str, srcs: List[str]) -> None:
        # scratchpad write: dst inherits the *minimum* trust of its sources
        if not srcs:
            raise QuarantineViolation(f"no provenance edges for {dst}")
        self._trust[dst] = min(self._trust[s] for s in srcs)

    def trust_of(self, seg_id: str) -> TrustClass:
        # fail-closed: unknown segment is maximally untrusted
        return self._trust.get(seg_id, TrustClass.UNTRUSTED)


CEILING = EffectClass.REVERSIBLE_WRITE


def enforce(inv: Invocation, graph: ProvenanceGraph) -> None:
    if not inv.slot_provenance:
        raise QuarantineViolation(f"{inv.tool}: invocation has no provenance")
    lowest = TrustClass.TRUSTED
    for slot, seg_ids in inv.slot_provenance.items():
        if not seg_ids:
            raise QuarantineViolation(f"{inv.tool}: slot {slot} unprovenanced")
        for sid in seg_ids:
            lowest = min(lowest, graph.trust_of(sid))
    # lattice join: effect escalates with lowest contributing trust
    if inv.effect == EffectClass.IRREVERSIBLE_EXTERNAL and lowest < TrustClass.TRUSTED:
        raise QuarantineViolation(
            f"{inv.tool}: irreversible effect with {lowest.name} content"
        )
    if inv.effect > CEILING and lowest < TrustClass.DERIVED:
        raise QuarantineViolation(
            f"{inv.tool}: effect {inv.effect.name} exceeds ceiling for {lowest.name}"
        )
