# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-treat-a-tool-result-as-tainted-multi-hop-provenance-collapse-at-the-label-join-boundary.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-treat-a-tool-result-as-tainted-multi-hop-provenance-collapse-at-the-label-join-boundary.warrant.json
# Markdown SHA-256:   97be2bc39c6b5b1ddae60c97263bccc59c5844b29802a74d9673ce5bc7735941
# Code AST SHA-256:   6807cd0fe6a19fed1bfa9e3039b6674192405fe5bd11996a4b0fe3abf0273be2
# Verified Classes:   ProvenanceCollapseError, Tainted
# Defensive Guards:   5 fail-closed invariants (zero external deps)

from dataclasses import dataclass, field
from typing import Optional


class ProvenanceCollapseError(RuntimeError):
    """Raised when a derived value's label is less tainted than its inputs."""


@dataclass(frozen=True)
class Tainted:
    value: object
    taint: str  # "none" | "external" | "derived:<src>" | "unknown"

    def __post_init__(self):
        if self.taint not in ("none", "unknown") and not self.taint.startswith(("external", "derived:")):
            raise ProvenanceCollapseError(f"unrecognized taint label: {self.taint!r}")


def join_taint(*labels: str) -> str:
    if any(l == "unknown" for l in labels):
        return "unknown"
    if any(l.startswith("external") for l in labels):
        return "external"
    derived = [l for l in labels if l.startswith("derived:")]
    if derived:
        return derived[0]
    return "none"


def merge_fields(*fields: Tainted) -> Tainted:
    """Join operation. Result MUST be at least as tainted as the most tainted input."""
    result_taint = join_taint(*(f.taint for f in fields))
    merged = {f.value: f.taint for f in fields}  # illustrative merge
    out = Tainted(value=merged, taint=result_taint)
    # Invariant check: never let a join promote to a cleaner label.
    for f in fields:
        if f.taint.startswith("external") and not out.taint.startswith("external"):
            raise ProvenanceCollapseError(
                f"join promoted external operand to {out.taint!r}"
            )
    return out


def render_template(template: str, parts: dict[str, Tainted]) -> Tainted:
    """Template render is a join. It must NOT reset taint to 'none'."""
    joined = merge_fields(*parts.values())
    rendered = template.format(**{k: v.value for k, v in parts.items()})
    return Tainted(value=rendered, taint=joined.taint)


def send_to_sink(payload: Tainted, principal: Optional[str] = None) -> None:
    """Side-effecting sink. Tainted payloads require explicit declassification."""
    if payload.taint == "unknown":
        raise ProvenanceCollapseError(
            "refusing to send payload with unknown provenance to a side-effecting sink"
        )
    if payload.taint != "none" and principal is None:
        raise ProvenanceCollapseError(
            f"refusing to send tainted payload (taint={payload.taint!r}) "
            "to sink without explicit declassification principal"
        )
    # ... perform side effect ...


def declassify(payload: Tainted, *, by: str, reason: str) -> Tainted:
    if not by or not reason:
        raise ProvenanceCollapseError("declassification requires principal and reason")
    # Declassification is logged and explicit; it does not silently rewrite history.
    return Tainted(value=payload.value, taint="none")