# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-refuse-a-capability-grant-that-taint-analysis-labels-clean-but-whose-provenance-chain-crosses-an-untrusted-sink.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-refuse-a-capability-grant-that-taint-analysis-labels-clean-but-whose-provenance-chain-crosses-an-untrusted-sink.warrant.json
# Markdown SHA-256:   325da9d06d27cdf0fd02b8ed7d6034f06294d17affc6ffbfa2fd96542b546435
# Code AST SHA-256:   3d249874c249611ed198b7076e5a2dc4bb761fd8a08e6b52971448dd59f44d90
# Verified Classes:   ClearingUnverifiableError, ClearingRecord
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Optional


class ClearingUnverifiableError(RuntimeError):
    """Raised when a label-clearing event cannot be tied to a real sanitizer execution."""
    pass


@dataclass(frozen=True)
class ClearingRecord:
    value_identity: str
    sanitizer_name: str
    executed: bool
    input_identity: Optional[str]


def evaluate_grant(
    value_identity: str,
    label_is_clean: bool,
    clearing_chain: list[ClearingRecord],
) -> bool:
    """
    Return True if the capability grant should be authorized.

    A clean label is necessary but not sufficient: every clearing node on the
    provenance chain must have a verifiable execution record keyed to the exact
    value identity being evaluated. Cache hits, identity-preserving merges, and
    deserialization fast paths produce records with executed=False or with an
    input_identity that does not match the value being evaluated.
    """
    if not label_is_clean:
        # Standard taint path: deny, but this is not the boundary failure.
        return False

    for record in clearing_chain:
        if not record.executed:
            raise ClearingUnverifiableError(
                f"clearing node {record.sanitizer_name!r} for value "
                f"{value_identity!r} has no execution record (cache shortcut?)"
            )
        if record.input_identity != value_identity:
            raise ClearingUnverifiableError(
                f"clearing node {record.sanitizer_name!r} cleared a different "
                f"input ({record.input_identity!r}) than the value being "
                f"evaluated ({value_identity!r}); label clearing is aliased"
            )

    return True


# Example: a cache-hit-cleared path must be refused even though its label is clean.
try:
    evaluate_grant(
        value_identity="./data/../etc/",
        label_is_clean=True,
        clearing_chain=[
            ClearingRecord(
                value_identity="./data/../etc/",
                sanitizer_name="normalize_path",
                executed=False,          # cache hit, sanitizer never ran
                input_identity="etc/",    # aliased to a different input
            )
        ],
    )
except ClearingUnverifiableError as exc:
    print(f"grant refused: {exc}")
