# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-taint-laundering-through-tool-argument-serialization-in-retrieved-content-to-tool-flows.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-taint-laundering-through-tool-argument-serialization-in-retrieved-content-to-tool-flows.warrant.json
# Markdown SHA-256:   8f7b020b236a71ba7d7f6e1a595cbe35528af326f5cd88c878ba4efc5701afce
# Code AST SHA-256:   85c631c9cd41a43fa43cb9a419909304286aa6ac556c7b0bd06165a41429b8ca
# Verified Classes:   TaintLaunderingError, Provenance
# Defensive Guards:   2 fail-closed invariants (zero external deps)

import json
import re
from dataclasses import dataclass, field
from typing import Any


class TaintLaunderingError(RuntimeError):
    """Raised when a tool argument is derived from retrieved content but its
    provenance record was dropped by a representation-changing transform."""
    pass


@dataclass
class Provenance:
    # Maps id(value) -> set of source tags ("retrieved", "user", "system").
    labels: dict = field(default_factory=dict)

    def tag(self, value: Any, source: str) -> Any:
        self.labels[id(value)] = self.labels.get(id(value), set()) | {source}
        return value

    def join(self, values: list) -> set:
        out: set = set()
        for v in values:
            out |= self.labels.get(id(v), set())
        return out


def guarded_tool_call(prov: Provenance, tool_name: str, derived_from_retrieval: bool,
                      args: dict, transforms: list) -> None:
    """Enforce the provenance-join boundary before invoking a privileged tool."""
    label_join = prov.join(list(args.values()))

    if derived_from_retrieval and not label_join:
        # The value came from retrieved content, but no label survived the
        # transform chain. This is the laundering case: refuse, do not pass.
        raise TaintLaunderingError(
            f"Tool '{tool_name}' argument derived from retrieved content but "
            f"carries no provenance label; transforms={transforms!r}. "
            f"Refusing call (fail-closed)."
        )

    if "retrieved" in label_join:
        raise TaintLaunderingError(
            f"Tool '{tool_name}' argument join includes 'retrieved' taint: "
            f"{sorted(label_join)!r}. Refusing privileged call."
        )


# --- Demonstration of the boundary ---
prov = Provenance()

chunk = prov.tag('prefix {"recipient":"attacker@x.example","amount":9000}', "retrieved")
match = re.search(r"\{.*\}", chunk).group(0)          # str, still labeled
parsed = json.loads(match)                            # dict/int: label dropped
args = {"recipient": parsed["recipient"], "amount": parsed["amount"]}

guarded_tool_call(
    prov,
    tool_name="transfer_funds",
    derived_from_retrieval=True,
    args=args,
    transforms=["regex_extract", "json.loads", "dict_index"],
)
