# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-mcp-transport-taint-as-unlaunderable-across-a-tool-call-boundary.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-mcp-transport-taint-as-unlaunderable-across-a-tool-call-boundary.warrant.json
# Markdown SHA-256:   d6f08c6cd4eeaea229de825753303a5021b1b568963994156e1dd52204e9da97
# Code AST SHA-256:   19019a947725dfd8acb7470d27c03f20a972f6161d7bdb48d609be0366456b6e
# Verified Classes:   HopKind, TaintLaunderingError, McpResult
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from dataclasses import dataclass, field
from enum import Enum


class HopKind(Enum):
    FORWARDING = "forwarding"
    RECONSTRUCTING = "reconstructing"
    RETRYING = "retrying"


class TaintLaunderingError(RuntimeError):
    """Raised when a taint label is lost across an MCP transport hop
    and the receiver would otherwise default to 'clean'."""


@dataclass
class McpResult:
    request_id: str
    payload: dict
    taint: list[str] = field(default_factory=list)
    taint_confirmed_by: str | None = None


def classify_path(hops: list[HopKind]) -> bool:
    """Return True iff the path is closed (absent-means-clean is safe)."""
    return all(h is HopKind.FORWARDING for h in hops)


def enforce_taint_at_receiver(
    result: McpResult,
    path: list[HopKind],
    last_confirming_hop: str | None,
) -> McpResult:
    closed = classify_path(path)

    if result.taint:
        # Label survived; trust it only if a hop in the path confirmed it.
        if last_confirming_hop is None:
            raise TaintLaunderingError(
                f"request {result.request_id}: taint label present but no hop "
                f"confirmed provenance; refusing to trust an unconfirmed label"
            )
        return result

    if closed:
        # No label and no reconstruction possible: genuinely clean.
        return result

    # Open path with no label: ambiguous between clean and laundered.
    raise TaintLaunderingError(
        f"request {result.request_id}: taint label absent across an open path "
        f"(hops={[h.value for h in path]}); absence is 'unknown', not 'clean'. "
        f"Quarantine and re-derive taint by content inspection before forwarding."
    )


def relay_tool_result(
    result: McpResult,
    path: list[HopKind],
    last_confirming_hop: str | None,
    content_inspector,
) -> McpResult:
    try:
        return enforce_taint_at_receiver(result, path, last_confirming_hop)
    except TaintLaunderingError:
        # Fail closed: re-derive taint from content rather than trusting absence.
        derived = content_inspector(result.payload)
        if not derived:
            raise TaintLaunderingError(
                f"request {result.request_id}: content inspection returned no "
                f"taint but path is open; cannot establish cleanliness, denying"
            )
        result.taint = derived
        result.taint_confirmed_by = "receiver:content_inspection"
        return result