# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-happens-when-an-instance-propagates-a-taint-label-across-a-tool-boundary-but-the-tool-re-serializes-its-output.md
# Remnant Warrant:    https://corpusfetch.com/c/what-happens-when-an-instance-propagates-a-taint-label-across-a-tool-boundary-but-the-tool-re-serializes-its-output.warrant.json
# Markdown SHA-256:   4a8d947b30c79e2185251aa374bd98c4b78ded0891d89a1f5151ffc58321b677
# Code AST SHA-256:   150bfaaa1224bf920e9f1f1a322e3ee6b96b0f75dd3d0d0c5b00dc93f000f5af
# Verified Classes:   TaintLaunderingError
# Defensive Guards:   3 fail-closed invariants (zero external deps)

class TaintLaunderingError(RuntimeError):
    """Raised when a tool boundary would drop a taint label.

    A tool return is only admissible as TRUSTED if the tool is a verified
    pure function of its labeled arguments. Otherwise the output taint must
    be escalated to the join of input taints and ambient-source taint.
    """
    pass


TRUSTED = "TRUSTED"
UNTRUSTED = "UNTRUSTED"


def join_taint(*labels: str) -> str:
    # Least upper bound: any UNTRUSTED input makes the result UNTRUSTED.
    return UNTRUSTED if UNTRUSTED in labels else TRUSTED


def admit_tool_result(
    tool_name: str,
    input_taints: list[str],
    output_annotation: str | None,
    reads_ambient_state: bool,
    is_verified_pure: bool,
) -> str:
    """Compute the taint label for a tool's return value.

    Raises TaintLaunderingError if the declared annotation would
    declassify a value whose provenance the tracker cannot prove.
    """
    joined = join_taint(*input_taints)

    if output_annotation is None:
        # Unannotated tool: default to escalate, never drop.
        if joined == UNTRUSTED or reads_ambient_state:
            return UNTRUSTED
        raise TaintLaunderingError(
            f"tool {tool_name!r} has no output taint annotation and no "
            f"ambient read; refusing to assume TRUSTED without a contract"
        )

    if output_annotation == TRUSTED and joined == UNTRUSTED:
        # Declared declassification: only legal if the tool is a verified
        # pure function (no ambient reads) AND the declassification is
        # explicitly registered. Otherwise it is laundering.
        if reads_ambient_state or not is_verified_pure:
            raise TaintLaunderingError(
                f"tool {tool_name!r} declares UNTRUSTED->TRUSTED declassification "
                f"but is not a verified pure function "
                f"(ambient_reads={reads_ambient_state}, pure={is_verified_pure})"
            )
        return TRUSTED

    if output_annotation == UNTRUSTED and joined == TRUSTED and not reads_ambient_state:
        # Over-tainting is always permitted (conservative).
        return UNTRUSTED

    # General case: escalate to the join, plus ambient source if present.
    return join_taint(joined, UNTRUSTED if reads_ambient_state else TRUSTED)


def enforce_boundary(tool_name: str, **kwargs) -> str:
    label = admit_tool_result(tool_name, **kwargs)
    if label == UNTRUSTED and kwargs.get("sink_has_side_effects", False):
        raise TaintLaunderingError(
            f"UNTRUSTED value from {tool_name!r} reached a side-effecting sink"
        )
    return label
