"""Fail-closed compatibility shim for retired direct firmware access.

Direct controller or microcontroller flashing has no commissioned AINA
artifact, transport, verification, rollback, or recovery contract.  Supported
software updates use the signed transactional OTA integration.  The old names
remain importable solely to fail before any filesystem or hardware activity.
"""

from __future__ import annotations

LEGACY_FIRMWARE_DISABLED_MESSAGE = (
    "Direct firmware access is unavailable: use the commissioned vendor "
    "procedure or signed AINA OTA"
)


class LegacyFirmwareDisabledError(RuntimeError):
    """Raised for every entry point of the retired firmware helper."""


def _disabled(*_args, **_kwargs):
    raise LegacyFirmwareDisabledError(LEGACY_FIRMWARE_DISABLED_MESSAGE)


def flash_firmware(image_path: str) -> None:
    """Reject direct flashing before inspecting or opening ``image_path``."""

    _disabled(image_path)


def get_current_version() -> str:
    """Reject uncommissioned direct controller interrogation."""

    _disabled()
