# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/which-invariants-prevent-taint-laundering-through-attenuated-tool-graphs-in-agent-sandboxes.md
# Remnant Warrant:    https://corpusfetch.com/c/which-invariants-prevent-taint-laundering-through-attenuated-tool-graphs-in-agent-sandboxes.warrant.json
# Markdown SHA-256:   9e932f61b38bc812469a9f3966c66a80009b81f0f5445fe66d36fec30cc3d61c
# Code AST SHA-256:   3c86045db7da14a6fafe56aa94c2765259f4a7311fc5642ebf05af7f35f94316
# Verified Classes:   TaintLaunderingError, Capability, Skill
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass, field
from typing import FrozenSet, Mapping


class TaintLaunderingError(RuntimeError):
    """Raised when a sink would receive data whose taint exceeds its requirement
    via a path not captured by the capability graph (e.g., shared scratch)."""


@dataclass(frozen=True)
class Capability:
    resource: str
    rights: FrozenSet[str]


@dataclass
class Skill:
    name: str
    caps: FrozenSet[Capability]
    reads_shared: FrozenSet[str] = field(default_factory=frozenset)
    writes_sink: FrozenSet[str] = field(default_factory=frozenset)


TAINT_ORDER = {"public": 0, "internal": 1, "secret": 2}


def join_taint(labels):
    return max(labels, key=lambda t: TAINT_ORDER[t]) if labels else "public"


def check_closure_taint(
    skills: Mapping[str, Skill],
    shared_writers: Mapping[str, FrozenSet[str]],  # resource -> skill names
    shared_taint: Mapping[str, str],                # resource -> max taint written
    sink_required: Mapping[str, str],               # sink -> required taint
) -> None:
    for skill in skills.values():
        for res in skill.reads_shared:
            writers = shared_writers.get(res, frozenset())
            incoming = join_taint([shared_taint.get(res, "public")] +
                                  [shared_taint.get(r, "public") for r in skill.reads_shared])
            for sink in skill.writes_sink:
                required = sink_required.get(sink, "public")
                if TAINT_ORDER[incoming] > TAINT_ORDER[required]:
                    raise TaintLaunderingError(
                        f"skill {skill.name!r} reads shared {res!r} tainted "
                        f"{incoming!r} (writers={sorted(writers)}) and writes sink "
                        f"{sink!r} requiring only {required!r}; capability attenuation "
                        f"does not bound taint flow across shared state"
                    )


def check_retry_provenance(original_taint: str, retry_taint: str, sink: str) -> None:
    if TAINT_ORDER[retry_taint] < TAINT_ORDER[original_taint]:
        raise TaintLaunderingError(
            f"retry to sink {sink!r} dropped provenance: original={original_taint!r} "
            f"retry={retry_taint!r}; retries must carry forward the original taint join"
        )
