#!/usr/bin/env python3
"""VOLATILITY_EXPANSION_BREAKOUT_V1 — spec/formulas/domains/entry.yaml.

This signal does NOT authorize a buy by itself -- callers must separately confirm
BREAKOUT_QUALITY_GATE_V2 != BLOCKED_LATE_CHASE. governance/todo/technical_signals_p4_adoption_plan.yaml P4-3.
"""
from __future__ import annotations

import argparse
import json
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
DEFAULT_OUT = ROOT / "Temp" / "volatility_expansion_breakout_v1.json"

SQUEEZE_PERCENTILE_THRESHOLD = 20.0
EXPANSION_RET_THRESHOLD_PCT = 3.0


def squeeze_detected(bb_width_20d_percentile: float | None) -> bool | None:
    if bb_width_20d_percentile is None:
        return None
    return bb_width_20d_percentile <= SQUEEZE_PERCENTILE_THRESHOLD


def evaluate(squeeze_detected_previous_day: bool | None, ret_1d: float | None) -> bool | None:
    if squeeze_detected_previous_day is None or ret_1d is None:
        return None
    return squeeze_detected_previous_day and ret_1d >= EXPANSION_RET_THRESHOLD_PCT


def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("--bb-width-20d-percentile-prev", type=float, default=None)
    ap.add_argument("--ret-1d", type=float, default=None)
    ap.add_argument("--out", default=str(DEFAULT_OUT))
    args = ap.parse_args()

    prev_squeeze = squeeze_detected(args.bb_width_20d_percentile_prev)
    result = {
        "formula_id": "VOLATILITY_EXPANSION_BREAKOUT_V1",
        "squeeze_detected_previous_day": prev_squeeze,
        "volatility_expansion_breakout": evaluate(prev_squeeze, args.ret_1d),
        "hard_constraint": "requires_BREAKOUT_QUALITY_GATE_V2_pass_separately",
    }
    out = Path(args.out)
    out.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
    print(json.dumps(result, ensure_ascii=False, indent=2))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())