# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-refuse-to-join-a-residual-because-the-locale-or-timezone-assumption-it-recorded-no-longer-matches-the-present-environment.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-refuse-to-join-a-residual-because-the-locale-or-timezone-assumption-it-recorded-no-longer-matches-the-present-environment.warrant.json
# Markdown SHA-256:   a7c6155bf48a1377ec3b1c058ae103ad2dd8517ec2ca1f35be04457296d16a8a
# Code AST SHA-256:   ce773ff3b5b59debe044ccc3b3a0ef5b1e3db26fdcd6e261d709cdc4edd2b993
# Verified Classes:   LocaleTimezoneMismatchError, ResidualLocaleContext, NormalizedExecutionEnv, LocaleTimezoneArbitrationGate
# Defensive Guards:   1 fail-closed invariants (zero external deps)

import os
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Final, Mapping


class LocaleTimezoneMismatchError(RuntimeError):
    '''Raised when a residual's regional timezone/locale assumption conflicts with the active execution context.'''
    pass


@dataclass(frozen=True)
class ResidualLocaleContext:
    residual_id: str
    recorded_timezone: str          # e.g., "UTC", "America/New_York"
    recorded_posix_locale: str      # e.g., "C.UTF-8", "en_US.UTF-8"
    is_jurisdiction_bound: bool     # True if tied to regional business/legal hours


@dataclass(frozen=True)
class NormalizedExecutionEnv:
    residual_id: str
    can_join: bool
    enforced_env_overrides: dict[str, str]
    utc_reference_iso: str


class LocaleTimezoneArbitrationGate:
    '''
    Prevents silent corruption when a residual's locale or timezone assumption
    no longer matches the present environment:
    1. Refuses joining if `is_jurisdiction_bound=True` and `recorded_timezone != active_timezone`.
    2. Refuses ambient execution when host `LC_ALL`/`TZ` drift from technical assumptions.
    3. Generates a locked canonical environment (`LC_ALL=C.UTF-8`, `TZ=UTC`) for technical execution.
    '''

    CANONICAL_LOCALE: Final[str] = "C.UTF-8"
    CANONICAL_TZ: Final[str] = "UTC"

    @classmethod
    def arbitrate_and_lock_env(
        cls,
        residual: ResidualLocaleContext,
        *,
        active_timezone: str,
        active_posix_locale: str,
        base_env: Mapping[str, str] | None = None,
    ) -> NormalizedExecutionEnv:
        # Gate 3: Hard refusal when regional jurisdiction timezone mismatches
        if residual.is_jurisdiction_bound and residual.recorded_timezone != active_timezone:
            raise LocaleTimezoneMismatchError(
                f"Refusing to join jurisdiction-bound residual '{residual.residual_id}': "
                f"recorded for timezone '{residual.recorded_timezone}', but active environment "
                f"requires '{active_timezone}'."
            )

        # Gate 4: Technical normalization to C.UTF-8 and UTC when ambient settings drift
        env_copy = dict(os.environ if base_env is None else base_env)
        env_copy["LC_ALL"] = cls.CANONICAL_LOCALE
        env_copy["LANG"] = cls.CANONICAL_LOCALE
        env_copy["LANGUAGE"] = cls.CANONICAL_LOCALE
        env_copy["TZ"] = cls.CANONICAL_TZ

        now_utc = datetime.now(timezone.utc).isoformat()
        return NormalizedExecutionEnv(
            residual_id=residual.residual_id,
            can_join=True,
            enforced_env_overrides={
                "LC_ALL": cls.CANONICAL_LOCALE,
                "LANG": cls.CANONICAL_LOCALE,
                "TZ": cls.CANONICAL_TZ,
            },
            utc_reference_iso=now_utc,
        )