# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/against-what-schema-evolution-invariants-must-an-instance-validate-external-payloads-to-prevent-silent-semantic-coercion-and-truncation.md
# Remnant Warrant:    https://corpusfetch.com/c/against-what-schema-evolution-invariants-must-an-instance-validate-external-payloads-to-prevent-silent-semantic-coercion-and-truncation.warrant.json
# Markdown SHA-256:   4e42168502a4368475f06edf68679b7406a44bcb414d3ee6815d1c76cb09e844
# Code AST SHA-256:   a212a6b6fa821e344dceb18fb071f9724872b1bdeb818c3b35fd652701868e61
# Verified Classes:   SchemaCoercionOrTruncationError, FieldContract, ValidatedPayloadEnvelope, StrictSchemaEvolutionGate
# Defensive Guards:   6 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Any, Final


class SchemaCoercionOrTruncationError(ValueError):
    '''Raised when a payload requires type coercion, exceeds precision/length bounds, or contains unknown enums.'''
    pass


@dataclass(frozen=True)
class FieldContract:
    name: str
    expected_exact_type: type
    required: bool = True
    max_str_length: int | None = None
    allowed_enum_values: frozenset[str] | None = None
    enforce_ieee754_safe_int: bool = True


@dataclass(frozen=True)
class ValidatedPayloadEnvelope:
    known_fields: dict[str, Any]
    preserved_unknown_fields: dict[str, Any]


class StrictSchemaEvolutionGate:
    '''
    Prevents silent semantic coercion, precision loss, and read-modify-write field
    stripping across evolving schema boundaries:
    1. Enforces exact type identity (`type(v) is contract.expected_exact_type`), catching
       Python's `bool` subclass of `int` trap (`type(True) is not int`).
    2. Rejects string truncation and IEEE-754 unsafe integers (`> 2^53 - 1`).
    3. Blocks unknown enum variants instead of falling back to defaults.
    4. Retains unknown future fields in `preserved_unknown_fields` for lossless round-tripping.
    '''

    MAX_IEEE754_SAFE_INT: Final[int] = (1 << 53) - 1  # 9,007,199,254,740,991

    @classmethod
    def validate_payload(
        cls,
        raw_payload: dict[str, Any],
        contracts: tuple[FieldContract, ...],
    ) -> ValidatedPayloadEnvelope:
        if type(raw_payload) is not dict:
            raise SchemaCoercionOrTruncationError(f"Expected top-level dict, got {type(raw_payload).__name__}.")

        contract_map = {c.name: c for c in contracts}
        validated_known: dict[str, Any] = {}

        for name, contract in contract_map.items():
            if name not in raw_payload or raw_payload[name] is None:
                if contract.required:
                    raise SchemaCoercionOrTruncationError(f"Missing or null required field '{name}'.")
                validated_known[name] = None
                continue

            val = raw_payload[name]

            # Gate 1: Strict exact type identity (prevents bool-as-int and str-as-bool coercion)
            if type(val) is not contract.expected_exact_type:
                raise SchemaCoercionOrTruncationError(
                    f"Strict Type Coercion Blocked on '{name}': expected exact type "
                    f"'{contract.expected_exact_type.__name__}', got '{type(val).__name__}' ({val!r})."
                )

            # Gate 2A: Integer IEEE-754 53-bit precision bound
            if contract.expected_exact_type is int and contract.enforce_ieee754_safe_int:
                if abs(val) > cls.MAX_IEEE754_SAFE_INT:
                    raise SchemaCoercionOrTruncationError(
                        f"Integer Precision Overflow on '{name}': {val} exceeds IEEE-754 safe integer "
                        f"bound ({cls.MAX_IEEE754_SAFE_INT}). Serialize 64-bit IDs as strings."
                    )

            # Gate 2B: String truncation refusal
            if contract.expected_exact_type is str and contract.max_str_length is not None:
                if len(val) > contract.max_str_length:
                    raise SchemaCoercionOrTruncationError(
                        f"String Truncation Refused on '{name}': length {len(val)} > max_str_length {contract.max_str_length}."
                    )

            # Gate 3: Unknown enum variant quarantine
            if contract.allowed_enum_values is not None:
                if val not in contract.allowed_enum_values:
                    raise SchemaCoercionOrTruncationError(
                        f"Unrecognized Enum Variant on '{name}': '{val}' not in {sorted(contract.allowed_enum_values)}. "
                        "Refusing silent default fallback."
                    )

            validated_known[name] = val

        # Gate 4: Preserve unknown higher-version fields for round-trip read-modify-write safety
        unknown_fields = {k: v for k, v in raw_payload.items() if k not in contract_map}
        return ValidatedPayloadEnvelope(
            known_fields=validated_known,
            preserved_unknown_fields=unknown_fields,
        )