# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-refuse-to-trust-a-skill-s-declared-provenance-even-when-its-signature-verifies-the-manifest-signature-capability-bi.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-refuse-to-trust-a-skill-s-declared-provenance-even-when-its-signature-verifies-the-manifest-signature-capability-bi.warrant.json
# Markdown SHA-256:   1197d91efe1095d98eec6265776b16f9ab3b80873f8c41df8274f75a3b526b05
# Code AST SHA-256:   604790d100ddacaf16bb4b96164b3e1c8c85f26286f74720118cde5ab041e003
# Verified Classes:   ProvenanceBindingError, Manifest, ResolvedArtifact
# Defensive Guards:   7 fail-closed invariants (zero external deps)

from __future__ import annotations

import hashlib
from dataclasses import dataclass


class ProvenanceBindingError(RuntimeError):
    """Raised when a manifest signature verifies but capability binding does not.

    This is distinct from a signature failure: the manifest is authentic,
    but the artifact that will execute is not provably the one described.
    """


@dataclass(frozen=True)
class Manifest:
    issuer: str
    artifact_digest: str          # sha256 of the artifact the author reviewed
    declared_capabilities: frozenset[str]
    closed_world: bool            # True iff loader cannot pull unlisted resources


@dataclass(frozen=True)
class ResolvedArtifact:
    digest: str
    resolved_by: str              # "digest" | "tag" | "name"
    requested_capabilities: frozenset[str]


def admit(
    manifest: Manifest,
    signature_valid: bool,
    trusted_issuers: frozenset[str],
    artifact: ResolvedArtifact,
    log_covers_digest: bool,
) -> None:
    # Ordinary rejection: bad signature. Not the boundary case.
    if not signature_valid:
        raise ProvenanceBindingError("signature invalid; reject before binding checks")
    if manifest.issuer not in trusted_issuers:
        raise ProvenanceBindingError(f"issuer {manifest.issuer!r} not in trust root")

    # --- The non-obvious boundary: signature is valid, now prove binding. ---

    if artifact.resolved_by != "digest":
        raise ProvenanceBindingError(
            f"artifact resolved by {artifact.resolved_by!r}, not by digest; "
            "signature authenticates a description of code that may not run"
        )

    if artifact.digest != manifest.artifact_digest:
        raise ProvenanceBindingError(
            f"digest mismatch: manifest={manifest.artifact_digest} "
            f"resolved={artifact.digest}; tag-roll / confused deputy"
        )

    if not log_covers_digest:
        raise ProvenanceBindingError(
            "transparency log does not cover artifact digest; "
            "signature without non-equivocation"
        )

    if not manifest.closed_world:
        raise ProvenanceBindingError(
            "manifest capability set is not provably closed; "
            "artifact may load unlisted resources at runtime"
        )

    if not artifact.requested_capabilities <= manifest.declared_capabilities:
        excess = artifact.requested_capabilities - manifest.declared_capabilities
        raise ProvenanceBindingError(
            f"runtime capability request exceeds declared set: {sorted(excess)}"
        )

    # Binding holds: signature AND digest AND closed-world AND subset.
    return None