# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-manifest-shadowing-injection-in-a-dynamically-reloaded-mcp-tool-registry.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-manifest-shadowing-injection-in-a-dynamically-reloaded-mcp-tool-registry.warrant.json
# Markdown SHA-256:   6e4d57e74222c8aa073ce352fa26549d6b2fcf478cb0a1392905b6ea90b3e190
# Code AST SHA-256:   6ff9092ddff121ee7cec9b6b4842cbcc816bb683193f9f38e8f233b513db7a52
# Verified Classes:   ManifestShadowingError, ToolEntry, TrustedRegistry
# Defensive Guards:   2 fail-closed invariants (zero external deps)

import hashlib
import json
from dataclasses import dataclass


class ManifestShadowingError(RuntimeError):
    """Raised when a hot-reloaded tool entry diverges from its trusted digest
    while sharing a dispatch target with an already-trusted entry."""


@dataclass(frozen=True)
class ToolEntry:
    name: str
    description: str
    schema: dict
    dispatch_target: str  # e.g. "server_url#handler"

    def digest(self) -> str:
        payload = json.dumps(
            {
                "name": self.name,
                "description": self.description,
                "schema": self.schema,
                "dispatch_target": self.dispatch_target,
            },
            sort_keys=True,
            separators=(",", ":"),
        ).encode("utf-8")
        return hashlib.sha256(payload).hexdigest()


class TrustedRegistry:
    def __init__(self) -> None:
        self._trusted: dict[str, ToolEntry] = {}
        self._digests: dict[str, str] = {}
        self._targets: dict[str, str] = {}  # dispatch_target -> name

    def admit(self, entry: ToolEntry) -> None:
        existing_target = self._targets.get(entry.dispatch_target)
        if existing_target is not None and existing_target != entry.name:
            # Two distinct names pointing at the same handler: shadow candidate.
            raise ManifestShadowingError(
                f"dispatch target {entry.dispatch_target!r} already owned by "
                f"{existing_target!r}; refusing {entry.name!r}"
            )
        self._trusted[entry.name] = entry
        self._digests[entry.name] = entry.digest()
        self._targets[entry.dispatch_target] = entry.name

    def reload(self, entry: ToolEntry) -> None:
        prior_digest = self._digests.get(entry.name)
        if prior_digest is None:
            # New name: full admission path.
            self.admit(entry)
            return
        new_digest = entry.digest()
        if new_digest != prior_digest:
            # Same name, changed content, possibly same dispatch target.
            # Never overwrite in place; fail closed.
            raise ManifestShadowingError(
                f"tool {entry.name!r} reloaded with divergent digest "
                f"(prior={prior_digest[:12]} new={new_digest[:12]}); "
                f"quarantine and require operator reconciliation"
            )
        # Byte-identical reload: idempotent, safe.
        self._trusted[entry.name] = entry


def apply_reload_batch(registry: TrustedRegistry, batch: list[ToolEntry]) -> None:
    # Validate the whole batch against a snapshot before mutating state,
    # so a partial reload cannot leave the registry half-shadowed.
    snapshot = TrustedRegistry()
    snapshot._trusted = dict(registry._trusted)
    snapshot._digests = dict(registry._digests)
    snapshot._targets = dict(registry._targets)
    for entry in batch:
        snapshot.reload(entry)
    # Commit only if every entry passed.
    registry._trusted = snapshot._trusted
    registry._digests = snapshot._digests
    registry._targets = snapshot._targets
