"""Typing helpers for post-validation narrowing."""

from __future__ import annotations

from typing import TypeVar

_T = TypeVar("_T")


def validated[T](v: object, expect: type[T]) -> T:
    """Narrow a ``@validate_call``-coerced value to its concrete type.

    Replaces ``cast()`` with a real runtime ``isinstance`` check
    so mypy narrows the type and incorrect usage fails fast.

    Usage::

        @validate_call(config=ConfigDict(arbitrary_types_allowed=True))
        def get_signals(self, time_range: FlexTimeRange, ...) -> ...:
            tr_spec = validated(time_range, TimeRangeSpec)
            # mypy knows tr_spec is TimeRangeSpec
    """
    assert isinstance(v, expect), f"Expected {expect.__name__} after @validate_call, got {type(v).__name__}"
    return v
