aether-quant 0.0.1__py3-none-any.whl

portfolio/book_neutrality.py

@@ -0,0 +1,178 @@
+"""Cross-symbol book neutralization (V5.1 Phase 0/1, item 6 of the V5.1
+roadmap - development/Problems.md).
+
+Every existing weight computation in this codebase (risk/position_sizing.py,
+main.py:1723-1726's inline book-role formula) is per-symbol: it never looks
+at what any other symbol in the same bar's book is doing. This module is the
+one deliberate cross-symbol pass, applied once per rebalance bar AFTER every
+symbol's raw book weight is known - it never changes a symbol's role (long/
+short), only rescales magnitudes so the book as a whole is dollar-neutral,
+sector-neutral, and gross-capped.
+
+Deliberately its own module, not folded into portfolio/book_construction.py:
+build_rank_based_book() decides WHICH symbols and WHICH side (a per-bar,
+whole-universe decision already); this module decides HOW MUCH, given that
+selection is already final - same separation-of-concerns split
+book_construction.py's own docstring draws between itself and
+risk/position_sizing.py.
+"""
+
+from __future__ import annotations
+
+
+def _clip(value: float, low: float, high: float) -> float:
+    return max(low, min(value, high))
+
+
+def apply_book_neutrality(
+    raw_weights_by_symbol: dict[str, float],
+    *,
+    sector_by_symbol: dict[str, str],
+    dollar_neutral: bool,
+    sector_neutral: bool,
+    gross_exposure_cap: float,
+    max_weight_per_name: float,
+    sector_max_net_weight: float,
+) -> tuple[dict[str, float], dict]:
+    """Deterministic 4-step pipeline over an already-selected book's raw
+    per-symbol weights (main.py's today-formula:
+    min(max_position_weight, 0.10 + 0.15*confidence) * book_role_multiplier,
+    one entry per book-selected symbol only - not the whole universe).
+
+    Steps, always in this order:
+      1. Per-name cap: clip every weight to [-max_weight_per_name, +max_weight_per_name].
+      2. Sector neutrality (if sector_neutral): within each sector bucket,
+         if |bucket net| exceeds sector_max_net_weight, SHRINK the whole
+         bucket (every member, proportionally, sign preserved, never
+         amplified) so its net lands exactly at the cap. A bucket already
+         within the cap is left untouched.
+
+         Deliberately NOT "demean to exact zero" (the pre-V5.1.3 behavior -
+         see Problems.md #81). Demeaning only preserves information when a
+         bucket has genuine within-bucket weight dispersion to fall back
+         on. Both of this module's callers (main.py's book formula,
+         evaluation/rank_book_simulator.py) equal-weight every name within
+         a role, so a bucket that is monolithic to one role - e.g. every
+         Forex ticker maps to a single "Forex" bucket, and Forex can never
+         appear on the opposite leg - has NO within-bucket dispersion:
+         demeaning drove every member to exactly zero, silently erasing the
+         entire position instead of bounding a genuine sector tilt.
+         Shrink-toward-cap degrades gracefully in every case: an already-
+         balanced bucket is untouched, a lopsided or monolithic bucket is
+         shrunk (never erased) toward the cap, and a single-member bucket
+         (net == its own weight) needs no special case - same code path.
+      3. Dollar neutrality (if dollar_neutral): scale the LARGER leg down
+         so sum(long) == sum(|short|). Scale-down only, never up - this can
+         never increase gross exposure. A one-sided book (no shorts, or no
+         longs) has nothing to balance against; that step is skipped for
+         that bar rather than zeroing the book out, and the skip is
+         recorded in diagnostics.
+      4. Gross cap: scale everything by min(1, gross_exposure_cap / gross).
+
+    Returns (weights, diagnostics) where diagnostics is JSON-serializable
+    (state.json's state["book_neutrality"]):
+      {"pre_gross", "post_gross", "net_before", "net_after",
+       "per_sector_net": {sector: net_weight, ...}, "steps_applied": [...]}
+
+    Never raises. An empty input returns ({}, diagnostics-with-zeros). Pure
+    dict-in/dict-out - result does not depend on input dict iteration order
+    (every step is a symmetric sum/mean over the group, not a positional
+    operation)."""
+    steps_applied: list[str] = []
+
+    if not raw_weights_by_symbol:
+        return {}, {
+            "pre_gross": 0.0,
+            "post_gross": 0.0,
+            "net_before": 0.0,
+            "net_after": 0.0,
+            "per_sector_net": {},
+            "steps_applied": ["empty_book_no_op"],
+        }
+
+    net_before = sum(raw_weights_by_symbol.values())
+
+    # Step 1: per-name cap.
+    weights = {
+        symbol: _clip(weight, -max_weight_per_name, max_weight_per_name)
+        for symbol, weight in raw_weights_by_symbol.items()
+    }
+    steps_applied.append("per_name_cap")
+
+    # Step 2: sector neutrality - shrink each bucket's net toward the cap,
+    # never demean to exact zero. See the docstring above (Problems.md #81).
+    #
+    # GUARDRAIL: sector_max_net_weight <= 0.0 is skipped entirely rather
+    # than applied - a configured cap of exactly 0.0 would otherwise give
+    # shrink_factor = 0.0 / |bucket_net| = 0.0 for every non-flat bucket,
+    # scaling every member to nothing. That is precisely the "demean to
+    # exact zero" behavior Problems.md #81 fixed (see the docstring above),
+    # reintroduced through config instead of code. A non-positive value
+    # cannot be honestly enforced by shrink-toward-cap at all (there is no
+    # cap to shrink toward), so it is treated the same as sector_neutral
+    # being off for this step, not silently honored.
+    if sector_neutral and sector_max_net_weight > 0.0:
+        symbols_by_sector: dict[str, list[str]] = {}
+        for symbol in weights:
+            sector = sector_by_symbol.get(symbol, "Unknown")
+            symbols_by_sector.setdefault(sector, []).append(symbol)
+
+        for sector, members in symbols_by_sector.items():
+            bucket_net = sum(weights[symbol] for symbol in members)
+            if abs(bucket_net) > sector_max_net_weight:
+                shrink_factor = sector_max_net_weight / abs(bucket_net)
+                for symbol in members:
+                    weights[symbol] *= shrink_factor
+        steps_applied.append("sector_neutral")
+    elif sector_neutral:
+        steps_applied.append("sector_neutral_skipped_invalid_max_net_weight")
+
+    # Step 3: dollar neutrality - scale the larger leg down only.
+    if dollar_neutral:
+        long_sum = sum(weight for weight in weights.values() if weight > 0.0)
+        short_sum = sum(-weight for weight in weights.values() if weight < 0.0)
+        if long_sum > 0.0 and short_sum > 0.0:
+            if long_sum > short_sum:
+                factor = short_sum / long_sum
+                weights = {
+                    symbol: (weight * factor if weight > 0.0 else weight) for symbol, weight in weights.items()
+                }
+            elif short_sum > long_sum:
+                factor = long_sum / short_sum
+                weights = {
+                    symbol: (weight * factor if weight < 0.0 else weight) for symbol, weight in weights.items()
+                }
+            steps_applied.append("dollar_neutral")
+        else:
+            steps_applied.append("dollar_neutral_skipped_one_sided_book")
+
+    # Step 4: gross exposure cap. A non-positive cap is a misconfiguration -
+    # V5.4.5 (#117 family): the old `gross > cap` comparison happily scaled
+    # the whole book by 0/cap == 0 when cap <= 0, silently erasing it
+    # (the same #81-class failure the sector step already guarded against).
+    # Skip with a diagnostic instead.
+    gross = sum(abs(weight) for weight in weights.values())
+    if gross_exposure_cap > 0.0 and gross > gross_exposure_cap:
+        factor = gross_exposure_cap / gross
+        weights = {symbol: weight * factor for symbol, weight in weights.items()}
+        steps_applied.append("gross_cap")
+    elif gross_exposure_cap <= 0.0:
+        steps_applied.append("gross_cap_skipped_nonpositive_cap")
+
+    per_sector_net: dict[str, float] = {}
+    for symbol, weight in weights.items():
+        sector = sector_by_symbol.get(symbol, "Unknown")
+        per_sector_net[sector] = per_sector_net.get(sector, 0.0) + weight
+
+    post_gross = sum(abs(weight) for weight in weights.values())
+    net_after = sum(weights.values())
+
+    diagnostics = {
+        "pre_gross": sum(abs(weight) for weight in raw_weights_by_symbol.values()),
+        "post_gross": post_gross,
+        "net_before": net_before,
+        "net_after": net_after,
+        "per_sector_net": per_sector_net,
+        "steps_applied": steps_applied,
+    }
+    return weights, diagnostics

portfolio/hrp_allocation.py

@@ -0,0 +1,159 @@
+"""V5.4.3 - Hierarchical Risk Parity (HRP) allocation.
+
+Implements López de Prado (2016)'s HRP algorithm as an alternative to the
+current equal-rank long/short allocation. Builds a correlation-distance
+dendrogram via scipy's linkage, then allocates by inverse-variance within
+each cluster using a top-down recursive bisection.
+
+Config-gated: `phase_v2.portfolio_book.allocation_method: "hrp"` (default
+`"rank"` = byte-identical equal-rank behavior). Pure numpy/scipy — no I/O,
+no torch."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from scipy.cluster.hierarchy import leaves_list, linkage
+from scipy.spatial.distance import squareform
+
+
+def compute_hrp_weights(returns: pd.DataFrame) -> pd.Series:
+    """Computes HRP weights from a (dates × tickers) returns DataFrame.
+
+    Steps:
+    1. Correlation distance matrix: d = sqrt(0.5 * (1 - corr))
+    2. Hierarchical clustering (Ward linkage on condensed distance)
+    3. Quasi-diagonal ordering via dendrogram leaf order
+    4. Top-down recursive bisection: split each cluster by inverse-variance
+
+    Returns per-ticker weights summing to 1.0."""
+    tickers = returns.columns.tolist()
+    corr = returns.corr().fillna(0.0)
+    n = len(tickers)
+    if n < 2:
+        return pd.Series({t: 1.0 / max(n, 1) for t in tickers})
+
+    # Correlation distance
+    dist = np.sqrt(np.clip(0.5 * (1.0 - corr.values), 0.0, None))
+    np.fill_diagonal(dist, 0.0)
+    condensed = squareform(dist, checks=False)
+
+    # Ward linkage
+    link = linkage(condensed, method="ward")
+
+    # Quasi-diagonal ordering (dendrogram leaf order)
+    ordered = leaves_list(link).tolist()
+
+    # Recursive bisection
+    weights = pd.Series(1.0, index=[tickers[i] for i in ordered])
+    cluster_items = [ordered]
+
+    while len(cluster_items) > 0:
+        next_clusters = []
+        for items in cluster_items:
+            if len(items) <= 1:
+                continue
+            half = len(items) // 2
+            left, right = items[:half], items[half:]
+
+            left_var = _cluster_var(returns, [tickers[i] for i in left])
+            right_var = _cluster_var(returns, [tickers[i] for i in right])
+            total = left_var + right_var
+            if total <= 0:
+                split = 0.5
+            else:
+                split = 1.0 - left_var / total
+
+            for item in left:
+                weights[tickers[item]] *= split
+            for item in right:
+                weights[tickers[item]] *= (1.0 - split)
+
+            next_clusters.extend([left, right])
+        cluster_items = next_clusters
+
+    return weights / weights.sum()
+
+
+def _cluster_var(returns: pd.DataFrame, tickers_subset: list[str]) -> float:
+    """Inverse-variance of a cluster = variance of the cluster's own
+    inverse-variance-weighted portfolio."""
+    sub = returns[tickers_subset]
+    ivp = 1.0 / np.diag(sub.cov().values)
+    ivp /= ivp.sum()
+    w = pd.Series(ivp, index=tickers_subset)
+    return float(w @ sub.cov().values @ w)
+
+
+def build_hrp_allocation(
+    returns_by_ticker: dict[str, list[float]],
+    *,
+    selected_tickers_long: list[str],
+    selected_tickers_short: list[str],
+    gross_exposure: float = 1.0,
+) -> dict[str, float]:
+    """Builds an HRP-weighted allocation dict for the current book's long and
+    short legs. With BOTH legs populated, longs get positive HRP weights ×
+    gross/2 and shorts negative × gross/2 (dollar-neutral book). A
+    SINGLE-SIDED book (one leg empty - e.g. the long-only book
+    `phase5.backtest.strategy_mode: "long_flat"` produces, the shipped
+    default) gives the present leg the FULL gross - V5.4.4 fix: the
+    original unconditional gross/2 split silently halved a long-only
+    book's exposure. Falls back to equal weight within each leg when HRP
+    can't converge."""
+    all_selected = selected_tickers_long + selected_tickers_short
+    if not all_selected:
+        return {}
+
+    # V5.4.4's single-sided/two-sided gross split, shared by the HRP path
+    # below and both fallbacks here so all three can never disagree.
+    long_weight_total = gross_exposure / 2.0 if selected_tickers_short else gross_exposure
+    short_weight_total = -(gross_exposure / 2.0 if selected_tickers_long else gross_exposure)
+
+    def _equal_weight_fallback() -> dict[str, float]:
+        # Equal weight WITHIN EACH LEG - each leg sums exactly to its own
+        # leg total above. V5.4.5 (development/Problems.md #118): the
+        # original fallback divided gross across BOTH legs combined
+        # (`gross / len(longs + shorts)`), so an asymmetric two-sided book
+        # (e.g. 6 longs / 2 shorts) came out with net exposure
+        # +/-0.5*gross instead of dollar-neutral.
+        result = {
+            ticker: long_weight_total / max(len(selected_tickers_long), 1)
+            for ticker in selected_tickers_long
+        }
+        for ticker in selected_tickers_short:
+            result[ticker] = short_weight_total / max(len(selected_tickers_short), 1)
+        return result
+
+    returns_df = pd.DataFrame({
+        ticker: pd.Series(returns_by_ticker[ticker])
+        for ticker in all_selected
+        if ticker in returns_by_ticker and len(returns_by_ticker[ticker]) >= 2
+    })
+    if returns_df.shape[1] < 2 or returns_df.empty:
+        return _equal_weight_fallback()
+
+    try:
+        hrp_all = compute_hrp_weights(returns_df)
+    except Exception:
+        return _equal_weight_fallback()
+
+    long_hrp_sum = sum(hrp_all.get(t, 0.0) for t in selected_tickers_long)
+    short_hrp_sum = sum(hrp_all.get(t, 0.0) for t in selected_tickers_short)
+
+    result = {}
+    if long_hrp_sum > 0:
+        for t in selected_tickers_long:
+            result[t] = hrp_all.get(t, 0.0) / long_hrp_sum * long_weight_total
+    else:
+        for t in selected_tickers_long:
+            result[t] = long_weight_total / max(len(selected_tickers_long), 1)
+
+    if short_hrp_sum > 0:
+        for t in selected_tickers_short:
+            result[t] = -hrp_all.get(t, 0.0) / short_hrp_sum * abs(short_weight_total)
+    else:
+        for t in selected_tickers_short:
+            result[t] = short_weight_total / max(len(selected_tickers_short), 1)
+
+    return result

portfolio/options_arbitrage_detector.py

@@ -0,0 +1,232 @@
+"""Mispricing detector for the 6 stubbed arbitrage strategies (box_spread,
+short_box_spread, conversion, reverse_conversion, jelly_roll,
+short_jelly_roll) - V4.6 (development/Problems.md #59/Roadmap).
+
+These 6 strategies have had full registry entries, leg selectors, and
+unit tests since V4.5, but were never invoked from the live signal path
+by design: driving them correctly requires comparing an observed
+structure's market price against its risk-free-rate-implied FAIR value
+(a genuine arbitrage/mispricing signal), not a directional or volatility
+view like every other strategy family in this codebase. This module is
+that signal source.
+
+Off by default (phase_v2.options_risk.arbitrage_detector.enabled) - an
+explicit, SEPARATE opt-in from enabling these 6 names in
+enabled_strategy_names, matching every other new-capability gate in this
+project's history (ship available, default off, opt in per-item).
+
+Every fair-value formula here is the standard, textbook closed-form
+result for its structure - not a fitted/calibrated model - since the
+whole premise of arbitrage detection is comparing an OBSERVED price
+against a THEORETICALLY-derived one, not a statistical estimate. Ignores
+dividends (dividend_yield=0.0), matching features/options_greeks.py's
+own existing convention for this codebase.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import date
+
+from portfolio.options_strategy import (
+    MULTI_LEG_STRATEGY_REGISTRY,
+    OptionsMultiLegPositionDecision,
+    _expiries_tuple_from_roles,
+    _legs_tuple_from_roles,
+    _net_vega_and_delta_per_unit,
+    select_strategy_legs,
+)
+
+
+def box_spread_fair_value(
+    higher_strike: float, lower_strike: float, risk_free_rate: float, time_to_expiry_years: float,
+) -> float:
+    """A box spread (long put + short call at the higher strike, short
+    put + long call at the lower strike, same expiry) synthesizes a
+    risk-free zero-coupon bond paying (higher_strike - lower_strike) at
+    expiry - its fair value today is that payoff discounted at the
+    risk-free rate. Standard textbook result."""
+    return (higher_strike - lower_strike) * math.exp(-risk_free_rate * max(time_to_expiry_years, 0.0))
+
+
+def conversion_parity_value(
+    call_price: float, put_price: float, spot: float, strike: float, risk_free_rate: float, time_to_expiry_years: float,
+) -> float:
+    """Put-call parity: call_price - put_price should equal
+    spot - strike * exp(-r*T) (ignoring dividends). Returns the SIGNED
+    discrepancy (actual minus theoretical) - a conversion (long stock,
+    long put, short call) profits when this is negative (options priced
+    cheap relative to parity); a reverse conversion profits when
+    positive."""
+    theoretical = spot - strike * math.exp(-risk_free_rate * max(time_to_expiry_years, 0.0))
+    actual = call_price - put_price
+    return actual - theoretical
+
+
+def jelly_roll_fair_value(
+    strike: float, risk_free_rate: float, near_time_to_expiry_years: float, far_time_to_expiry_years: float,
+) -> float:
+    """The interest-rate-implied fair cost of a jelly roll (rolling a
+    synthetic position from the near expiry to the far one) - the
+    discounted strike difference between the two expiries, the standard
+    cost-of-carry result for extending a synthetic forward's expiry."""
+    near_discount = math.exp(-risk_free_rate * max(near_time_to_expiry_years, 0.0))
+    far_discount = math.exp(-risk_free_rate * max(far_time_to_expiry_years, 0.0))
+    return strike * (near_discount - far_discount)
+
+
+def detect_mispricing(actual_net_cost: float, fair_value: float, min_mispricing_bps: float, notional: float) -> bool:
+    """Shared threshold predicate for all 3 families above: True when the
+    discrepancy between actual_net_cost and fair_value exceeds
+    min_mispricing_bps of notional - requiring a MINIMUM edge (not a bare
+    non-zero difference) accounts for real bid/ask spread and transaction
+    costs a genuine arbitrage must clear to be worth trading. Returns
+    False (never trades, never raises) when notional is non-positive."""
+    if notional <= 0.0:
+        return False
+    mispricing_bps = abs(actual_net_cost - fair_value) / notional * 10_000.0
+    return mispricing_bps >= min_mispricing_bps
+
+
+def _years_between(current_date, expiry_date_str: str) -> float:
+    """ISO-date-string expiry minus current_date, in years (365-day
+    convention, matching main.py::_build_options_chains_payload()'s own
+    time_to_expiry_years computation for greeks). Returns 0.0 (never
+    negative, never raises) for an unparseable/past expiry."""
+    try:
+        expiry_date = date.fromisoformat(expiry_date_str)
+    except (TypeError, ValueError):
+        return 0.0
+    return max((expiry_date - current_date).days, 0) / 365.0
+
+
+def _actual_net_cost(spec, legs_by_role: dict) -> float:
+    """Signed cost to enter the FULL spread unit at current market
+    bid/ask: pay ask for every LONG leg, receive bid for every SHORT leg
+    - read from each leg's own `.side` (registry-driven), never hardcoded
+    per strategy_name, since box_spread/short_box_spread and jelly_roll/
+    short_jelly_roll invert which role is long vs. short while keeping
+    the SAME role names (see MULTI_LEG_STRATEGY_REGISTRY's own docstring)
+    - the exact bug this generic formula avoids versus hand-writing one
+    signed formula per strategy_name."""
+    net_cost = 0.0
+    for leg_spec in spec.legs:
+        row = legs_by_role[leg_spec.role]
+        price = float(row["ask"]) if leg_spec.side == "long" else float(row["bid"])
+        sign = 1.0 if leg_spec.side == "long" else -1.0
+        net_cost += sign * price
+    return net_cost
+
+
+def select_arbitrage_signal(
+    strategy_name: str,
+    available_chain: list[dict],
+    current_date,
+    risk_free_rate: float,
+    min_mispricing_bps: float,
+    target_delta: float = 0.5,
+) -> bool:
+    """Composes the existing V4.5 arbitrage leg selectors
+    (select_strategy_legs(), already registry-driven) with the fair-value/
+    threshold functions above: True iff THIS bar's chain shows an
+    exploitable mispricing for strategy_name, using each leg's own
+    bid/ask and days-to-expiry. Strike/expiry ROLES (which role is
+    "higher"/"lower"/"near"/"far") are resolved from
+    MULTI_LEG_STRATEGY_REGISTRY, never hardcoded per strategy_name - the
+    short_* variants invert which role holds which strike/side while
+    keeping the same role NAMES. Returns False (never a crash) on any
+    missing selection/pricing/date data, or for any strategy_name outside
+    the 6 arbitrage families - degrade-to-absent, matching every other
+    selector's convention in this module's sibling file."""
+    spec = MULTI_LEG_STRATEGY_REGISTRY.get(strategy_name)
+    if spec is None or current_date is None:
+        return False
+    legs_by_role = select_strategy_legs(strategy_name, available_chain, target_delta)
+    if legs_by_role is None:
+        return False
+
+    try:
+        if strategy_name in ("box_spread", "short_box_spread"):
+            higher_role = next(leg.role for leg in spec.legs if leg.strike_role == "higher")
+            lower_role = next(leg.role for leg in spec.legs if leg.strike_role == "lower")
+            higher_row = legs_by_role[higher_role]
+            lower_row = legs_by_role[lower_role]
+            higher_strike = float(higher_row["strike"])
+            lower_strike = float(lower_row["strike"])
+            time_to_expiry_years = _years_between(current_date, higher_row["expiry"])
+            fair_value = box_spread_fair_value(higher_strike, lower_strike, risk_free_rate, time_to_expiry_years)
+            actual_net_cost = _actual_net_cost(spec, legs_by_role)
+            return detect_mispricing(actual_net_cost, fair_value, min_mispricing_bps, higher_strike - lower_strike)
+
+        if strategy_name in ("conversion", "reverse_conversion"):
+            call_role = next(leg.role for leg in spec.legs if leg.right == "call")
+            put_role = next(leg.role for leg in spec.legs if leg.right == "put")
+            call_row = legs_by_role[call_role]
+            put_row = legs_by_role[put_role]
+            strike = float(call_row["strike"])
+            spot = float(call_row.get("underlying_price") or strike)
+            time_to_expiry_years = _years_between(current_date, call_row["expiry"])
+            call_mid = (float(call_row["bid"]) + float(call_row["ask"])) / 2.0
+            put_mid = (float(put_row["bid"]) + float(put_row["ask"])) / 2.0
+            discrepancy = conversion_parity_value(call_mid, put_mid, spot, strike, risk_free_rate, time_to_expiry_years)
+            return detect_mispricing(discrepancy, 0.0, min_mispricing_bps, strike)
+
+        if strategy_name in ("jelly_roll", "short_jelly_roll"):
+            near_call_role = next(leg.role for leg in spec.legs if leg.right == "call" and leg.expiry_role == "near")
+            far_call_role = next(leg.role for leg in spec.legs if leg.right == "call" and leg.expiry_role == "far")
+            near_row = legs_by_role[near_call_role]
+            far_row = legs_by_role[far_call_role]
+            strike = float(near_row["strike"])
+            near_time_to_expiry_years = _years_between(current_date, near_row["expiry"])
+            far_time_to_expiry_years = _years_between(current_date, far_row["expiry"])
+            fair_value = jelly_roll_fair_value(strike, risk_free_rate, near_time_to_expiry_years, far_time_to_expiry_years)
+            actual_net_cost = _actual_net_cost(spec, legs_by_role)
+            return detect_mispricing(actual_net_cost, fair_value, min_mispricing_bps, strike)
+    except (KeyError, TypeError, ValueError):
+        return False
+
+    return False
+
+
+def build_arbitrage_position_sizing(
+    strategy_name: str,
+    available_chain: list[dict],
+    current_date,
+    risk_free_rate: float,
+    min_mispricing_bps: float,
+    max_contracts_per_signal: int = 1,
+    target_delta: float = 0.5,
+) -> OptionsMultiLegPositionDecision | None:
+    """The ONLY sizing path for the 6 arbitrage strategies - deliberately
+    NOT vega-budget or margin-tier sized (an arbitrage structure is
+    delta/vega-neutral by construction, so a vega budget has nothing
+    meaningful to scale against). Sized instead to a small, FIXED
+    `max_contracts_per_signal` (default 1) whenever
+    select_arbitrage_signal() confirms a real mispricing this bar - a
+    deliberately conservative first-cut sizing model for a genuinely new
+    capability, not a risk-budgeted one; a real margin-aware arbitrage
+    sizer is a reasonable future follow-up once this is IB-verified.
+    Returns None when no mispricing is detected, selection fails, or
+    max_contracts_per_signal isn't positive - never raises."""
+    if max_contracts_per_signal <= 0:
+        return None
+    if not select_arbitrage_signal(strategy_name, available_chain, current_date, risk_free_rate, min_mispricing_bps, target_delta):
+        return None
+    spec = MULTI_LEG_STRATEGY_REGISTRY.get(strategy_name)
+    if spec is None:
+        return None
+    legs_by_role = select_strategy_legs(strategy_name, available_chain, target_delta)
+    if legs_by_role is None:
+        return None
+
+    net_vega, net_delta = _net_vega_and_delta_per_unit(spec, legs_by_role)
+    return OptionsMultiLegPositionDecision(
+        strategy_name=strategy_name,
+        legs=_legs_tuple_from_roles(spec, legs_by_role),
+        expiries=_expiries_tuple_from_roles(spec, legs_by_role),
+        contracts=int(max_contracts_per_signal),
+        net_debit_or_credit=_actual_net_cost(spec, legs_by_role),
+        net_delta=net_delta,
+        net_vega=net_vega,
+        sizing_reason="arbitrage_mispricing_fixed_size_sizing",
+    )