# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-happens-when-an-instance-trusts-a-tool-manifest-s-declared-side-effect-class-after-registry-re-signing.md
# Remnant Warrant:    https://corpusfetch.com/c/what-happens-when-an-instance-trusts-a-tool-manifest-s-declared-side-effect-class-after-registry-re-signing.warrant.json
# Markdown SHA-256:   7f73826c43e77aecf05550c7d2f33460fbfb75e3d7e2b3c7eea524bb79c1096d
# Code AST SHA-256:   383b7ef4ebccb727482e7cc0f6f8f9aba5f28bd0d4abb81890f7112757e514b9
# Verified Classes:   ManifestPolicySkewError
# Defensive Guards:   2 fail-closed invariants (zero external deps)

class ManifestPolicySkewError(RuntimeError):
    """Raised when a manifest's declared side-effect class is weaker than
    what its tool schema can actually do, or when a re-signed manifest
    downgrades the class under a stable identifier."""

    def __init__(self, skill_id: str, declared: str, implied: str, digest: str):
        self.skill_id = skill_id
        self.declared = declared
        self.implied = implied
        self.digest = digest
        super().__init__(
            f"{skill_id}@{digest[:12]}: declared={declared!r} but schema implies "
            f"{implied!r}; refusing to auto-approve"
        )


_MUTATING_PARAMS = {"method", "body", "path", "command", "args", "script"}
_CLASS_ORDER = {"read_only": 0, "mutating": 1, "external": 2}


def schema_implied_class(manifest: dict) -> str:
    params = set(manifest.get("tool_schema", {}).get("properties", {}).keys())
    if params & _MUTATING_PARAMS:
        return "mutating"
    return manifest.get("side_effects", "read_only")


def effective_class(manifest: dict, pinned_digest: str | None) -> str:
    declared = manifest.get("side_effects", "read_only")
    implied = schema_implied_class(manifest)
    digest = manifest.get("digest", "")

    # Re-signing under a stable id with a weaker class is adversarial by default.
    if pinned_digest is not None and digest != pinned_digest:
        if _CLASS_ORDER[declared] < _CLASS_ORDER.get(implied, 0):
            raise ManifestPolicySkewError(
                manifest["skill_id"], declared, implied, digest
            )

    # Enforcement must never be weaker than what the schema can do.
    if _CLASS_ORDER[declared] < _CLASS_ORDER[implied]:
        raise ManifestPolicySkewError(
            manifest["skill_id"], declared, implied, digest
        )

    return implied if _CLASS_ORDER[implied] > _CLASS_ORDER[declared] else declared


def approve_invocation(manifest: dict, pinned_digest: str | None) -> bool:
    klass = effective_class(manifest, pinned_digest)
    # Only genuinely read-only calls skip the confirmation gate.
    return klass == "read_only"
