"""C2 VPR strategy composition-root factory (AZ-336).

:func:`build_vpr_strategy` selects exactly one strategy by
``config.components['c2_vpr'].strategy`` and respects compile-time
``BUILD_VPR_<variant>`` gating: requesting a strategy whose flag is
OFF raises :class:`StrategyNotAvailableError` at composition time
(NOT at first frame).

Concrete strategy modules
(``ultra_vpr``, ``net_vlad``, ``mega_loc``, ``mix_vpr``,
``sela_vpr``, ``eigen_places``, ``salad``) are imported lazily —
a Tier-0 workstation build with ``BUILD_VPR_ULTRA_VPR=OFF`` MUST
NOT load ``c2_vpr.ultra_vpr`` (ADR-002 / I-5; verifiable via
``sys.modules``).

Pre-flight validation: after constructing the strategy, the factory
queries :meth:`VprStrategy.descriptor_dim` and asserts it matches
the C6 ``DescriptorIndex`` sidecar's ``descriptor_dim()``. Mismatch
→ :class:`ConfigurationError` at startup, NOT at first frame.

Factory signature deviates from the v1.0.0 contract draft in one
place: the contract spec named the second parameter ``tile_store:
TileStore``, but ``descriptor_dim()`` lives on
:class:`DescriptorIndex` per C6's actual Public API. We inject
``descriptor_index`` directly; the contract markdown is updated to
match.
"""

from __future__ import annotations

import logging
import os
from typing import TYPE_CHECKING

from gps_denied_onboard.config.schema import ConfigError
from gps_denied_onboard.runtime_root.errors import StrategyNotAvailableError

if TYPE_CHECKING:
    from gps_denied_onboard.components.c2_vpr import C2VprConfig, VprStrategy
    from gps_denied_onboard.components.c6_tile_cache import DescriptorIndex
    from gps_denied_onboard.components.c7_inference import InferenceRuntime
    from gps_denied_onboard.config.schema import Config

__all__ = ["build_vpr_strategy"]


_LOG = logging.getLogger("gps_denied_onboard.c2_vpr")


# Strategy resolution table — mirrors the contract's
# ``vpr_strategy_protocol.md`` v1.0.0 § Composition-Root Factory table
# verbatim. ANY mutation of this dict MUST be mirrored in the contract.
_STRATEGY_TO_BUILD_FLAG: dict[str, str] = {
    "ultra_vpr": "BUILD_VPR_ULTRA_VPR",
    "net_vlad": "BUILD_VPR_NETVLAD",
    "mega_loc": "BUILD_VPR_MEGALOC",
    "mix_vpr": "BUILD_VPR_MIXVPR",
    "sela_vpr": "BUILD_VPR_SELAVPR",
    "eigen_places": "BUILD_VPR_EIGENPLACES",
    "salad": "BUILD_VPR_SALAD",
}

_STRATEGY_TO_MODULE: dict[str, tuple[str, str]] = {
    "ultra_vpr": (
        "gps_denied_onboard.components.c2_vpr.ultra_vpr",
        "UltraVprStrategy",
    ),
    "net_vlad": (
        "gps_denied_onboard.components.c2_vpr.net_vlad",
        "NetVladStrategy",
    ),
    "mega_loc": (
        "gps_denied_onboard.components.c2_vpr.mega_loc",
        "MegaLocStrategy",
    ),
    "mix_vpr": (
        "gps_denied_onboard.components.c2_vpr.mix_vpr",
        "MixVprStrategy",
    ),
    "sela_vpr": (
        "gps_denied_onboard.components.c2_vpr.sela_vpr",
        "SelaVprStrategy",
    ),
    "eigen_places": (
        "gps_denied_onboard.components.c2_vpr.eigen_places",
        "EigenPlacesStrategy",
    ),
    "salad": (
        "gps_denied_onboard.components.c2_vpr.salad",
        "SaladStrategy",
    ),
}


def _is_build_flag_on(flag_name: str) -> bool:
    """Read a compile-time ``BUILD_*`` flag from the environment.

    ``ON`` / ``1`` / ``true`` / ``yes`` (case-insensitive) → ``True``;
    anything else (including unset) → ``False``. Defaults to OFF so
    test environments must opt-in explicitly per strategy.
    """
    raw = os.environ.get(flag_name, "")
    return raw.strip().lower() in {"on", "1", "true", "yes"}


def _c2_config(config: "Config") -> "C2VprConfig":
    """Pull the registered C2 config block.

    ``c2_vpr.__init__`` registers it on import; a missing
    registration is a developer error and surfaces as ``KeyError``
    rather than a silent fallback.
    """
    return config.components["c2_vpr"]


def build_vpr_strategy(
    config: "Config",
    *,
    descriptor_index: "DescriptorIndex",
    inference_runtime: "InferenceRuntime",
) -> "VprStrategy":
    """Construct the :class:`VprStrategy` impl selected by config.

    1. Reads ``config.components['c2_vpr'].strategy``.
    2. Checks the matching ``BUILD_VPR_<variant>`` flag — if OFF,
       raises :class:`StrategyNotAvailableError` BEFORE any import.
    3. Lazily imports the concrete strategy module.
    4. Constructs the strategy via its module-level
       ``create(config, descriptor_index, inference_runtime)``
       factory function (each concrete strategy module exports
       ``create`` as its public entry-point; concrete constructors
       stay private).
    5. Pre-flight ``descriptor_dim`` match: ``strategy.descriptor_dim()``
       vs ``descriptor_index.descriptor_dim()``. Mismatch raises
       :class:`ConfigError`; ONE ERROR log
       ``kind="c2.vpr.dim_mismatch"`` is emitted; the strategy is
       NOT bound.
    6. On success, ONE INFO log ``kind="c2.vpr.strategy_loaded"``
       with ``strategy`` + ``descriptor_dim``.

    Raises:
        StrategyNotAvailableError: compile-time flag OFF or
            concrete module not yet built (AZ-337..AZ-340 pending).
        ConfigError: ``descriptor_dim`` mismatch between strategy
            and corpus index.
    """
    block = _c2_config(config)
    strategy = block.strategy
    flag_name = _STRATEGY_TO_BUILD_FLAG.get(strategy)
    module_info = _STRATEGY_TO_MODULE.get(strategy)
    if flag_name is None or module_info is None:
        # Defensive — config validation rejects unknown strategy labels
        # at load (C2VprConfig.__post_init__), so this branch is only
        # reachable if the resolution table and the validation set
        # drift apart.
        _LOG.error(
            "c2.vpr.build_flag_off",
            extra={"strategy": strategy, "reason": "unknown_strategy"},
        )
        raise StrategyNotAvailableError(
            f"VprStrategy {strategy!r} is not buildable in this binary."
        )
    if not _is_build_flag_on(flag_name):
        _LOG.error(
            "c2.vpr.build_flag_off",
            extra={"strategy": strategy, "flag": flag_name},
        )
        raise StrategyNotAvailableError(
            f"BUILD_VPR_{strategy.upper()} is OFF for this binary; "
            f"cannot select strategy={strategy}."
        )
    module_name, class_name = module_info
    try:
        module = __import__(module_name, fromlist=[class_name])
    except ModuleNotFoundError as exc:
        raise StrategyNotAvailableError(
            f"VprStrategy {strategy!r} is configured but its concrete impl "
            f"module {module_name!r} has not been built into this binary "
            "yet (AZ-337 / AZ-338 / AZ-339 / AZ-340 pending)."
        ) from exc
    create_fn = getattr(module, "create", None)
    if create_fn is None:
        strategy_cls = getattr(module, class_name)
        instance = strategy_cls(
            config,
            descriptor_index=descriptor_index,
            inference_runtime=inference_runtime,
        )
    else:
        instance = create_fn(
            config,
            descriptor_index=descriptor_index,
            inference_runtime=inference_runtime,
        )
    strategy_dim = instance.descriptor_dim()
    corpus_dim = descriptor_index.descriptor_dim()
    if strategy_dim != corpus_dim:
        _LOG.error(
            "c2.vpr.dim_mismatch",
            extra={
                "strategy": strategy,
                "strategy_dim": strategy_dim,
                "corpus_dim": corpus_dim,
            },
        )
        raise ConfigError(
            f"descriptor_dim mismatch: strategy={strategy_dim}, "
            f"corpus={corpus_dim}"
        )
    _LOG.info(
        "c2.vpr.strategy_loaded",
        extra={"strategy": strategy, "descriptor_dim": strategy_dim},
    )
    return instance
