# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-reject-a-skill-manifest-whose-declared-capability-set-is-a-strict-superset-of-the-tool-schema-it-was-signed-against.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-reject-a-skill-manifest-whose-declared-capability-set-is-a-strict-superset-of-the-tool-schema-it-was-signed-against.warrant.json
# Markdown SHA-256:   8a0d1acacb7e6d085ad14832826d3fce64ff0d777672e2407106f81e22890466
# Code AST SHA-256:   d0efe02b011d008a4b53e516721e70ff94ebd5501eb2dba2be98650aca56ab28
# Verified Classes:   CapabilityDivergenceError, SignedManifest
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import FrozenSet


class CapabilityDivergenceError(RuntimeError):
    """Raised when a signed manifest declares authority its signed schema cannot warrant."""

    def __init__(self, skill_id: str, excess: FrozenSet[str], schema_digest: str):
        self.skill_id = skill_id
        self.excess = excess
        self.schema_digest = schema_digest
        super().__init__(
            f"skill {skill_id!r} declares capabilities {sorted(excess)} "
            f"not implied by signed schema {schema_digest!r}"
        )


@dataclass(frozen=True)
class SignedManifest:
    skill_id: str
    schema_digest: str
    declared_capabilities: FrozenSet[str]
    signature_valid: bool


def derive_capabilities(schema_digest: str) -> FrozenSet[str]:
    # Sound, auditable derivation from the signed schema's effect surface.
    # Placeholder: real implementation walks the schema's operation graph.
    return _SCHEMA_CAPABILITY_TABLE[schema_digest]


def admit_manifest(manifest: SignedManifest) -> FrozenSet[str]:
    if not manifest.signature_valid:
        raise CapabilityDivergenceError(
            manifest.skill_id, manifest.declared_capabilities, manifest.schema_digest
        )

    implied = derive_capabilities(manifest.schema_digest)
    excess = manifest.declared_capabilities - implied

    if excess:
        # Strict superset: authenticated assertion exceeds warranted authority.
        # Reject before any capability grant. Do not intersect silently.
        raise CapabilityDivergenceError(manifest.skill_id, excess, manifest.schema_digest)

    # Subset or equal: legitimate least-privilege narrowing or exact match.
    return manifest.declared_capabilities


_SCHEMA_CAPABILITY_TABLE: dict[str, FrozenSet[str]] = {
    # summarize_document: pure read-and-transform, no side effects
    "sha256:9f2c...": frozenset({"fs.read"}),
}