"""Archived causal helper for the rejected 2026-07-21 Hold1V1 experiment."""

from __future__ import annotations

import pandas as pd


def hold1_confirmed(
    *, candidate: pd.Series, close: pd.Series, boundary: pd.Series,
    volume: pd.Series, side: str,
) -> pd.Series:
    if side not in {"long", "short"}:
        raise ValueError("side must be 'long' or 'short'")
    if not (candidate.index.equals(close.index) and close.index.equals(boundary.index)):
        raise ValueError("candidate, close, and boundary indexes must match")
    if not close.index.equals(volume.index):
        raise ValueError("close and volume indexes must match")
    prior_candidate = candidate.fillna(0).astype(bool).shift(1, fill_value=False)
    frozen_boundary = boundary.shift(1)
    held = close.gt(frozen_boundary) if side == "long" else close.lt(frozen_boundary)
    return (prior_candidate & held & volume.gt(0)).fillna(False)