# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-does-an-instance-of-an-aaif-scoped-capability-token-silently-widen-privilege-when-the-token-s-attenuation-chain-crosses-a-resource-version-boundar.md
# Remnant Warrant:    https://corpusfetch.com/c/why-does-an-instance-of-an-aaif-scoped-capability-token-silently-widen-privilege-when-the-token-s-attenuation-chain-crosses-a-resource-version-boundar.warrant.json
# Markdown SHA-256:   c299e295f2d0c435e5b341c0264f09656e97e65d455172039e4bf4fdcc08151c
# Code AST SHA-256:   05ea42c5d88bd6b43593ebfcce3b565b1b434aa3c1d0408589d1e1c459420067
# Verified Classes:   UnsoundAttenuationError, Link
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass
from typing import Callable, Iterable


class UnsoundAttenuationError(RuntimeError):
    """Raised when an AAIF attenuation chain mixes binding and annotation
    semantics for a version qualifier, making effective privilege a union
    rather than an intersection."""


@dataclass(frozen=True)
class Link:
    issuer: str
    resource: str          # e.g. "dataset://metrics@v12"
    version: str           # e.g. "v12"
    binding: str           # "identity" | "annotation"
    resolve: Callable[[str], str]  # issuer's binding resolution


def verify_attenuation_chain(chain: Iterable[Link]) -> None:
    """Reject chains whose links disagree on whether the version qualifier
    is part of resource identity. Soundness requires all links to agree,
    and all resolutions to match the root issuer's resolution."""
    links = list(chain)
    if not links:
        raise UnsoundAttenuationError("empty attenuation chain")

    root = links[0]
    root_resolved = root.resolve(root.resource)

    for i, link in enumerate(links[1:], start=1):
        if link.binding != root.binding:
            raise UnsoundAttenuationError(
                f"link {i} ({link.issuer}) declares binding={link.binding!r} "
                f"but root ({root.issuer}) declares binding={root.binding!r}; "
                f"effective privilege is a union, not an intersection"
            )

        resolved = link.resolve(link.resource)
        if resolved != root_resolved:
            raise UnsoundAttenuationError(
                f"link {i} ({link.issuer}) resolves {link.resource!r} -> "
                f"{resolved!r}, but root resolves to {root_resolved!r}; "
                f"chain is over-broad across a version boundary"
            )


def _demo() -> None:
    # Root pins @v12 as binding; agent B re-resolves to v13 (live head).
    root = Link(
        issuer="root", resource="dataset://metrics@v12", version="v12",
        binding="identity", resolve=lambda r: "dataset://metrics@v12",
    )
    agent_b = Link(
        issuer="agent-b", resource="dataset://metrics@v12/columns=latency/limit=1000",
        version="v12", binding="identity",
        resolve=lambda r: "dataset://metrics@v13",  # rolled forward
    )
    verify_attenuation_chain([root, agent_b])  # raises


if __name__ == "__main__":
    _demo()
