# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-hardware-or-runtime-architecture-constraints-must-accompany-a-performance-residual.md
# Remnant Warrant:    https://corpusfetch.com/c/what-hardware-or-runtime-architecture-constraints-must-accompany-a-performance-residual.warrant.json
# Markdown SHA-256:   2c827c8ab93c7adc63e5545bb48421112d1b5425772113d9e56936ddc2f32249
# Code AST SHA-256:   c0e0e94a8844be97179fb3ba15fb7074d4b35698ab7f9d9063f5ddb0ebe17908
# Verified Classes:   HardwareRuntimeEnvelope, PerformanceResidualCandidate, UnanchoredPerformanceResidualViolation, PerformanceSubstrateCompatibilityGate
# Defensive Guards:   9 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Final, FrozenSet

VALID_ISAS: Final[FrozenSet[str]] = frozenset({"x86_64", "aarch64", "riscv64"})
VALID_IO_CLASSES: Final[FrozenSet[str]] = frozenset({"tmpfs", "local_nvme", "local_ssd", "network_block"})

@dataclass(frozen=True)
class HardwareRuntimeEnvelope:
    isa: str
    logical_cores_quota: int
    memory_limit_mb: int
    io_substrate_class: str
    runtime_name: str
    runtime_version: str
    gil_enabled: bool

@dataclass(frozen=True)
class PerformanceResidualCandidate:
    slug: str
    prescribed_worker_threads: int
    prescribed_batch_memory_mb: int
    cpu_bound_workload: bool
    envelope: HardwareRuntimeEnvelope

class UnanchoredPerformanceResidualViolation(Exception):
    """Raised when a performance residual lacks hardware/runtime bounds or violates target host constraints."""
    pass

class PerformanceSubstrateCompatibilityGate:
    def verify_for_publication(self, candidate: PerformanceResidualCandidate) -> bool:
        env = candidate.envelope
        if env.isa not in VALID_ISAS:
            raise UnanchoredPerformanceResidualViolation(
                f"Residual '{candidate.slug}' specifies unsupported or missing ISA '{env.isa}'."
            )
        if env.io_substrate_class not in VALID_IO_CLASSES:
            raise UnanchoredPerformanceResidualViolation(
                f"Residual '{candidate.slug}' specifies unknown I/O class '{env.io_substrate_class}'."
            )
        if env.logical_cores_quota <= 0 or env.memory_limit_mb <= 0:
            raise UnanchoredPerformanceResidualViolation(
                f"Residual '{candidate.slug}' must record positive CPU core and memory quotas."
            )
        if not env.runtime_name.strip() or not env.runtime_version.strip():
            raise UnanchoredPerformanceResidualViolation(
                f"Residual '{candidate.slug}' omits runtime name or version identifier."
            )
        if candidate.cpu_bound_workload and env.gil_enabled and candidate.prescribed_worker_threads > 1:
            raise UnanchoredPerformanceResidualViolation(
                f"Residual '{candidate.slug}' prescribes {candidate.prescribed_worker_threads} CPU-bound threads "
                "on a GIL-enabled runtime."
            )
        return True

    def verify_host_compatibility(
        self,
        candidate: PerformanceResidualCandidate,
        live_host: HardwareRuntimeEnvelope,
    ) -> bool:
        self.verify_for_publication(candidate)

        if candidate.envelope.isa != live_host.isa:
            raise UnanchoredPerformanceResidualViolation(
                f"ISA mismatch for '{candidate.slug}': recorded on {candidate.envelope.isa}, "
                f"live host is {live_host.isa}."
            )
        if candidate.prescribed_worker_threads > live_host.logical_cores_quota * 2:
            raise UnanchoredPerformanceResidualViolation(
                f"Prescribed thread count ({candidate.prescribed_worker_threads}) oversubscribes "
                f"live host core quota ({live_host.logical_cores_quota})."
            )
        if candidate.prescribed_batch_memory_mb > live_host.memory_limit_mb // 2:
            raise UnanchoredPerformanceResidualViolation(
                f"Prescribed batch memory ({candidate.prescribed_batch_memory_mb} MB) exceeds safe 50% ceiling "
                f"of live host memory ({live_host.memory_limit_mb} MB)."
            )
        if candidate.cpu_bound_workload and live_host.gil_enabled and candidate.prescribed_worker_threads > 1:
            raise UnanchoredPerformanceResidualViolation(
                "Cannot apply multi-threaded CPU-bound residual to a GIL-enabled live host."
            )
        return True