"""
GAS_THIN_ADAPTER_POLICY_V1 — Phase 2: Python stubs for unmapped GAS forbidden functions.
spec/39_gas_thin_adapter_policy.yaml 참조.

NEEDS_STUB 목록 (audit 결과에서 Python harness 직접 대응 없는 3개):
  - runRouteFlow_        (gdf_03_portfolio_gates.gs)  [stop_loss]
  - calcExportGate_      (gdf_04_execution_quality.gs) [unknown]
  - buildWatchLedger_    (gdf_04_execution_quality.gs) [stop_loss, take_profit]
"""
from __future__ import annotations

from typing import Any


def stub_run_route_flow(
    route_map: dict[str, Any],
    stop_prices: dict[str, float],
    current_prices: dict[str, float],
) -> dict[str, Any]:
    """라우트 플로우 실행 — GAS runRouteFlow_ 의 Python stub.

    GAS 원본: gdf_03_portfolio_gates.gs / runRouteFlow_  [stop_loss]
    책임 분류: FORBIDDEN (stop_loss 결정 포함)

    Phase 3 (thin_adapter) 완료 전까지 GAS는 이 함수를 직접 호출하지 않아야 한다.
    Python 엔진은 inject_computed_harness.calc_stop_breach_alerts + cash_recovery 조합으로
    라우트 플로우를 처리한다.
    """
    raise NotImplementedError(
        "stub_run_route_flow: GAS_THIN_ADAPTER_POLICY_V1 Phase 3(thin_adapter) 완료 후 구현 예정. "
        "Python 엔진: inject_computed_harness.calc_stop_breach_alerts + cash_recovery 참고."
    )


def stub_calc_export_gate(
    harness: dict[str, Any],
    export_policy: dict[str, Any] | None = None,
) -> dict[str, bool]:
    """Export 게이트 계산 — GAS calcExportGate_ 의 Python stub.

    GAS 원본: gdf_04_execution_quality.gs / calcExportGate_  [unknown]
    책임 분류: FORBIDDEN (unknown — export 조건 결정 로직 포함 가능)

    Phase 3 (thin_adapter) 완료 전까지 GAS는 이 함수를 직접 호출하지 않아야 한다.
    Python 엔진은 run_release_dag_v3.py 의 gate 평가 로직이 동등 기능을 담당한다.
    """
    raise NotImplementedError(
        "stub_calc_export_gate: GAS_THIN_ADAPTER_POLICY_V1 Phase 3(thin_adapter) 완료 후 구현 예정. "
        "Python 엔진: run_release_dag_v3.py gate 평가 참고."
    )


def stub_build_watch_ledger(
    holdings: list[dict[str, Any]],
    stop_prices: dict[str, float],
    tp_prices: dict[str, float],
    current_prices: dict[str, float],
) -> list[dict[str, Any]]:
    """관찰 원장 조립 — GAS buildWatchLedger_ 의 Python stub.

    GAS 원본: gdf_04_execution_quality.gs / buildWatchLedger_  [stop_loss, take_profit]
    책임 분류: FORBIDDEN (stop_loss + take_profit 결정 포함)

    Phase 3 (thin_adapter) 완료 전까지 GAS는 이 함수를 직접 호출하지 않아야 한다.
    Python 엔진은 compute_formula_outputs.compute_stop_price_core +
    compute_tp_validity 조합으로 동등 기능을 담당한다.
    """
    raise NotImplementedError(
        "stub_build_watch_ledger: GAS_THIN_ADAPTER_POLICY_V1 Phase 3(thin_adapter) 완료 후 구현 예정. "
        "Python 엔진: compute_stop_price_core + compute_tp_validity 참고."
    )