# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-refuse-to-issue-an-aaif-verifiable-credential-despite-a-valid-signature-from-the-requesting-principal.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-refuse-to-issue-an-aaif-verifiable-credential-despite-a-valid-signature-from-the-requesting-principal.warrant.json
# Markdown SHA-256:   7ebf2cfb7d27ab93f7e581251dd64ab4600270226b30bcc5f0952b282d4b5728
# Code AST SHA-256:   7081f629bf5c084b9e2692e07e331ed6b3fffd9c87b28ceff2df576d0d5732a0
# Verified Classes:   AAIFIssuanceRefused, Grant, CredentialRequest
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import FrozenSet


class AAIFIssuanceRefused(RuntimeError):
    """Raised when a signed credential request exceeds the principal's grant."""
    pass


@dataclass(frozen=True)
class Grant:
    subject_pattern: str
    claim_namespace: FrozenSet[str]
    audience: FrozenSet[str]


@dataclass(frozen=True)
class CredentialRequest:
    principal: str
    subject: str
    claims: dict
    audience: FrozenSet[str]
    signature_valid: bool


def issue_credential(req: CredentialRequest, grant: Grant) -> dict:
    if not req.signature_valid:
        raise AAIFIssuanceRefused(
            f"signature invalid for principal {req.principal!r}"
        )

    requested_keys = frozenset(req.claims.keys())
    uncovered = requested_keys - grant.claim_namespace
    if uncovered:
        raise AAIFIssuanceRefused(
            f"principal {req.principal!r} requested claims outside grant "
            f"namespace: {sorted(uncovered)}; grant covers "
            f"{sorted(grant.claim_namespace)}"
        )

    if "*" in req.audience and "*" not in grant.audience:
        raise AAIFIssuanceRefused(
            f"principal {req.principal!r} requested wildcard audience "
            f"without grant authorization; grant audience is "
            f"{sorted(grant.audience)}"
        )

    if not req.audience <= grant.audience:
        raise AAIFIssuanceRefused(
            f"requested audience {sorted(req.audience)} not subset of "
            f"grant audience {sorted(grant.audience)}"
        )

    return {
        "subject": req.subject,
        "claims": dict(req.claims),
        "audience": sorted(req.audience),
        "issued_by": req.principal,
    }
