"""Pure transaction-cost analysis: implementation shortfall of a fill vs the arrival (decision) mid, in bps.
Positive = cost (we paid up to buy / sold cheap). Tells us whether execution is eating the alpha."""
from __future__ import annotations


def shortfall_bps(side: str, *, arrival_mid: float, fill_price: float) -> float:
    if fill_price <= 0 or arrival_mid <= 0:
        return 0.0
    raw = (fill_price - arrival_mid) / arrival_mid
    signed = raw if side == "BUY" else -raw
    return signed * 1e4
