aether-quant 0.0.1__py3-none-any.whl

risk/forex_risk.py

@@ -0,0 +1,158 @@
+"""Forex position sizing - leverage-utilization-targeted, the FX sibling
+of risk/futures_risk.py's margin-utilization-targeted model (not the
+volatility-of-notional model risk/position_sizing.py uses for equity/
+crypto/bond).
+
+Forex trades in whole LOTS (this module follows futures' own "whole
+units, never fractional weights" convention for consistency, rather than
+supporting fractional/micro lots), and the real constraint is how much of
+the account's margin a position consumes at the pair's max leverage - the
+same "budget, not volatility" shape risk/futures_risk.py already
+established for futures, adapted to lot_size/leverage_max/margin_pct
+instead of a fixed per-contract multiplier/margin (forex margin scales
+with the pair's CURRENT price, unlike futures' fixed initial_margin_usd
+per contract - "one lot" is a fixed base-currency notional, not a fixed
+dollar margin).
+
+V4.6 (development/Problems.md, Roadmap "Assets") - code-complete,
+IB/Lean-backtest-unverified, the exact same status futures/options
+shipped with: main.py::_add_asset() wires self.add_forex(), but zero
+forex tickers are configured in phase1.universe.assets and
+phase_v2.forex_risk.enabled defaults False.
+
+Confirmed via direct Lean source inspection that Forex is fully
+first-class in this Lean version (SecurityType.Forex,
+Common/Securities/Forex/Forex.cs, real pip-size/lot-size symbol
+properties) - unlike individual bonds (see features/bond_features.py's
+own module docstring), there is no native-support question here."""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_PAIR_SPECS_PATH = Path(__file__).resolve().parents[1] / "data" / "reference" / "forex_pair_specs.json"
+
+
+@dataclass(frozen=True)
+class ForexSizingDecision:
+    lot_count: int
+    notional_value: float
+    margin_required: float
+    margin_utilization: float
+    target_weight: float
+    base_target_weight: float
+    confidence_multiplier: float
+    max_leverage_utilization: float
+    sizing_reason: str
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def load_forex_pair_specs(path: Path = DEFAULT_PAIR_SPECS_PATH) -> dict:
+    """Defensive load - returns {} (not a raised exception) on a missing or
+    unparseable specs file, same convention as
+    risk/futures_risk.py::load_futures_contract_specs(). A missing spec
+    for a given pair means build_forex_position_sizing() can't size it -
+    callers must treat that as "no position", not a crash."""
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            data = json.load(handle)
+    except (OSError, json.JSONDecodeError) as exc:
+        logger.warning("load_forex_pair_specs(%s): unreadable — %s", path, exc)
+        return {}
+    return {key: value for key, value in data.items() if not key.startswith("_")}
+
+
+def build_forex_position_sizing(
+    base_target_weight: float,
+    confidence: float,
+    price: float,
+    pair_spec: dict | None,
+    portfolio_value: float,
+    target_leverage_utilization: float = 0.20,
+    max_leverage_utilization: float = 0.40,
+) -> ForexSizingDecision:
+    """Leverage-utilization-targeted sizing: computes the max lots
+    affordable at max_leverage_utilization (the hard ceiling), then scales
+    toward target_leverage_utilization by confidence using the same
+    "0.5 + 0.5*confidence" shape as
+    risk/futures_risk.py::build_futures_position_sizing()'s
+    confidence_multiplier, and floors to an integer lot_count.
+
+    Per-lot margin is `lot_size * price * margin_pct` (equivalently
+    `lot_size * price / leverage_max`, since margin_pct and leverage_max
+    are reciprocals by construction in forex_pair_specs.json).
+
+    target_weight is a DERIVED reconciliation value for downstream
+    weight-based consumers (exposure caps) - lot_count is the source of
+    truth and is what main.py::_apply_signal() actually executes via
+    MarketOrder(), never fed back into SetHoldings().
+
+    Returns an all-zero decision (lot_count=0) when pair_spec is
+    missing/empty, confidence is 0, base_target_weight is 0, or
+    portfolio_value/price/lot_size/margin_pct are non-positive - never
+    raises, matching risk/futures_risk.py's "no active signal -> zero
+    position" convention."""
+    confidence = max(0.0, min(float(confidence), 1.0))
+    base_target_weight = float(base_target_weight)
+    portfolio_value = max(float(portfolio_value), 0.0)
+    price = max(float(price), 0.0)
+    max_leverage_utilization = max(float(max_leverage_utilization), 0.0)
+    target_leverage_utilization = max(0.0, min(float(target_leverage_utilization), max_leverage_utilization))
+
+    pair_spec = pair_spec or {}
+    lot_size = float(pair_spec.get("lot_size", 0.0))
+    margin_pct = float(pair_spec.get("margin_pct", 0.0))
+
+    if (
+        base_target_weight == 0.0
+        or confidence == 0.0
+        or portfolio_value <= 0.0
+        or price <= 0.0
+        or lot_size <= 0.0
+        or margin_pct <= 0.0
+    ):
+        return ForexSizingDecision(
+            lot_count=0,
+            notional_value=0.0,
+            margin_required=0.0,
+            margin_utilization=0.0,
+            target_weight=0.0,
+            base_target_weight=base_target_weight,
+            confidence_multiplier=0.0,
+            max_leverage_utilization=max_leverage_utilization,
+            sizing_reason="no_active_signal_or_missing_pair_spec",
+        )
+
+    margin_per_lot = lot_size * price * margin_pct
+    confidence_multiplier = 0.5 + 0.5 * confidence
+    max_lots_affordable = int(portfolio_value * max_leverage_utilization // margin_per_lot)
+    lots_at_target = int(portfolio_value * target_leverage_utilization // margin_per_lot)
+    lot_count = min(int(lots_at_target * confidence_multiplier), max_lots_affordable)
+    lot_count = max(lot_count, 0)
+
+    direction = 1.0 if base_target_weight >= 0.0 else -1.0
+    notional_value = lot_count * lot_size * price
+    margin_required = lot_count * margin_per_lot
+    margin_utilization = margin_required / portfolio_value if portfolio_value > 0.0 else 0.0
+    target_weight = direction * (notional_value / portfolio_value) if portfolio_value > 0.0 else 0.0
+
+    sizing_reason = "no_active_signal_or_missing_pair_spec" if lot_count == 0 else "leverage_utilization_scaled_sizing"
+
+    return ForexSizingDecision(
+        lot_count=int(direction) * lot_count,
+        notional_value=notional_value,
+        margin_required=margin_required,
+        margin_utilization=margin_utilization,
+        target_weight=target_weight,
+        base_target_weight=base_target_weight,
+        confidence_multiplier=confidence_multiplier,
+        max_leverage_utilization=max_leverage_utilization,
+        sizing_reason=sizing_reason,
+    )

risk/futures_risk.py

@@ -0,0 +1,202 @@
+"""Futures position sizing - margin-utilization-targeted, not the
+volatility-of-notional model risk/position_sizing.py uses for equity/crypto/
+bond.
+
+Margin, contract count, and mark-to-market are fundamentally different from
+a portfolio-weight-scaled sizing model: Lean trades futures in whole
+contracts (not fractional weights), and the real constraint is how much of
+the account's margin budget a position consumes, not how much daily-return
+volatility it contributes. This module is deliberately separate from
+risk/position_sizing.py rather than a new branch inside it - see
+risk/asset_class_router.py for how its FuturesSizingDecision output gets
+adapted onto the shared PositionSizingDecision shape everything downstream
+(portfolio/book_construction.py, liquidity, analyzer, _apply_signal())
+consumes.
+
+Continuous-futures rollover/mark-to-market itself is NOT reimplemented here
+- that's entirely delegated to Lean's native add_future() + continuous-
+contract SetFilter() mapping (main.py::_add_asset()). rollover_due() below
+is a diagnostic/logging signal only, never a trade trigger - a second,
+hand-rolled rollover state machine racing against Lean's own would be a bug
+class, not a feature.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import asdict, dataclass
+from datetime import date
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_CONTRACT_SPECS_PATH = Path(__file__).resolve().parents[1] / "data" / "reference" / "futures_contract_specs.json"
+
+
+@dataclass(frozen=True)
+class FuturesSizingDecision:
+    contract_count: int
+    notional_value: float
+    margin_required: float
+    margin_utilization: float
+    target_weight: float
+    base_target_weight: float
+    confidence_multiplier: float
+    max_margin_utilization: float
+    sizing_reason: str
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def load_futures_contract_specs(path: Path = DEFAULT_CONTRACT_SPECS_PATH) -> dict:
+    """Defensive load - returns {} (not a raised exception) on a missing or
+    unparseable specs file, same convention as train.py::load_sector_mapping().
+    A missing spec for a given ticker means build_futures_position_sizing()
+    can't size it - callers must treat that as "no position", not a crash."""
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            data = json.load(handle)
+    except (OSError, json.JSONDecodeError) as exc:
+        logger.warning("load_futures_contract_specs(%s): unreadable — %s", path, exc)
+        return {}
+    return {key: value for key, value in data.items() if not key.startswith("_")}
+
+
+def build_futures_position_sizing(
+    base_target_weight: float,
+    confidence: float,
+    price: float,
+    contract_spec: dict | None,
+    portfolio_value: float,
+    target_margin_utilization: float = 0.20,
+    max_margin_utilization: float = 0.40,
+) -> FuturesSizingDecision:
+    """Margin-utilization-targeted sizing: computes the max contracts
+    affordable at max_margin_utilization (the hard ceiling), then scales
+    toward target_margin_utilization by confidence using the same
+    "0.5 + 0.5*confidence" shape as
+    risk/position_sizing.py::build_dynamic_position_sizing()'s
+    confidence_multiplier, and floors to an integer contract_count (Lean
+    trades futures in whole contracts, never fractional weights).
+
+    target_weight is a DERIVED reconciliation value for downstream weight-
+    based consumers (exposure caps, book construction) - contract_count is
+    the source of truth and is what main.py::_apply_signal() actually
+    executes via MarketOrder(), never fed back into SetHoldings().
+
+    Returns an all-zero decision (contract_count=0) when contract_spec is
+    missing/empty, confidence is 0, base_target_weight is 0, or
+    portfolio_value/price/multiplier/margin are non-positive - never
+    raises, matching risk/position_sizing.py's "no active signal -> zero
+    weight" convention."""
+    confidence = max(0.0, min(float(confidence), 1.0))
+    base_target_weight = float(base_target_weight)
+    portfolio_value = max(float(portfolio_value), 0.0)
+    price = max(float(price), 0.0)
+    max_margin_utilization = max(float(max_margin_utilization), 0.0)
+    target_margin_utilization = max(0.0, min(float(target_margin_utilization), max_margin_utilization))
+
+    contract_spec = contract_spec or {}
+    multiplier = float(contract_spec.get("multiplier", 0.0))
+    margin_per_contract = float(contract_spec.get("initial_margin_usd", 0.0))
+
+    if (
+        base_target_weight == 0.0
+        or confidence == 0.0
+        or portfolio_value <= 0.0
+        or price <= 0.0
+        or multiplier <= 0.0
+        or margin_per_contract <= 0.0
+    ):
+        return FuturesSizingDecision(
+            contract_count=0,
+            notional_value=0.0,
+            margin_required=0.0,
+            margin_utilization=0.0,
+            target_weight=0.0,
+            base_target_weight=base_target_weight,
+            confidence_multiplier=0.0,
+            max_margin_utilization=max_margin_utilization,
+            sizing_reason="no_active_signal_or_missing_contract_spec",
+        )
+
+    confidence_multiplier = 0.5 + 0.5 * confidence
+    max_contracts_affordable = int(portfolio_value * max_margin_utilization // margin_per_contract)
+    contracts_at_target = int(portfolio_value * target_margin_utilization // margin_per_contract)
+    contract_count = min(int(contracts_at_target * confidence_multiplier), max_contracts_affordable)
+    contract_count = max(contract_count, 0)
+
+    direction = 1.0 if base_target_weight >= 0.0 else -1.0
+    notional_value = contract_count * multiplier * price
+    margin_required = contract_count * margin_per_contract
+    margin_utilization = margin_required / portfolio_value if portfolio_value > 0.0 else 0.0
+    target_weight = direction * (notional_value / portfolio_value) if portfolio_value > 0.0 else 0.0
+
+    sizing_reason = "no_active_signal_or_missing_contract_spec" if contract_count == 0 else "margin_utilization_scaled_sizing"
+
+    return FuturesSizingDecision(
+        contract_count=int(direction) * contract_count,
+        notional_value=notional_value,
+        margin_required=margin_required,
+        margin_utilization=margin_utilization,
+        target_weight=target_weight,
+        base_target_weight=base_target_weight,
+        confidence_multiplier=confidence_multiplier,
+        max_margin_utilization=max_margin_utilization,
+        sizing_reason=sizing_reason,
+    )
+
+
+def resolve_futures_margin_source(raw_value: str) -> str:
+    """Validates phase_v2.futures_risk.margin_source - "static" (default,
+    the offline data/reference/futures_contract_specs.json file) or
+    "live" (Lean's own IB-calibrated BuyingPowerModel, resolved once per
+    security at add-time and queried per sizing call - see main.py::
+    _resolve_futures_contract_spec()). "live" here means Lean's own
+    LOCAL margin-model calculation (InteractiveBrokersBrokerageModel's
+    bundled margin rules), never a live network round-trip to IB's
+    servers - that would be far too slow inside on_data() and is not
+    what this option does. Any unrecognized value (a config typo) falls
+    back to "static" rather than raising - never crashes the algorithm
+    over a bad string."""
+    normalized = str(raw_value).strip().lower()
+    return normalized if normalized in ("static", "live") else "static"
+
+
+def build_live_contract_spec(
+    multiplier: float,
+    initial_margin_usd: float,
+    description: str = "",
+    exchange: str = "",
+) -> dict:
+    """Constructs a contract_spec dict in the exact shape
+    build_futures_position_sizing() already consumes (same keys
+    load_futures_contract_specs() produces from the static JSON file),
+    from live values main.py resolves via Lean's own
+    Security.SymbolProperties/BuyingPowerModel. Pure - no Lean coupling
+    itself; only main.py's caller touches self.Securities. description/
+    exchange default to "" (informational only, never read by
+    build_futures_position_sizing()'s own sizing math) since Lean's
+    BuyingPowerModel query has no equivalent of either - callers
+    typically pass the static spec's own values through for display
+    continuity when a live spec replaces it."""
+    return {
+        "description": description,
+        "multiplier": float(multiplier),
+        "initial_margin_usd": float(initial_margin_usd),
+        "exchange": exchange,
+    }
+
+
+def rollover_due(current_date: date, contract_expiry_date: date | None, rollover_days_before_expiry: int = 5) -> bool:
+    """Pure date comparison - a diagnostic/logging signal only. Actual
+    contract rollover is entirely delegated to Lean's native add_future() +
+    continuous-contract SetFilter() mapping (main.py::_add_asset()); this
+    function must never itself trigger a trade. Returns False when
+    contract_expiry_date is unknown (e.g. Lean's continuous-contract
+    subscription hasn't surfaced the mapped contract's expiry yet)."""
+    if contract_expiry_date is None:
+        return False
+    return (contract_expiry_date - current_date).days <= rollover_days_before_expiry

risk/kill_switch.py

@@ -0,0 +1,261 @@
+"""V5.1 Phase 6 (production safety): the automatic, per-bar circuit
+breaker. Deliberately trips the EXISTING trade-lock machinery (main.py's
+self.trade_lock_active/self.trade_lock_reason, already consumed by
+execution/order_gate.py::resolve_order_permission()'s risk_locks_healthy
+input, analyzer/market_analyzer.py's Priority 1 reduce_risk check, state.json,
+and the audit log) rather than adding a second, parallel lock - a second
+lock would create two sources of truth that can disagree, and `aq
+trade-lock --off`/`--auto` would no longer be a complete story.
+
+Pure, deterministic, cheap: evaluate_kill_switch() does only dict/threshold
+comparisons over ALREADY-COMPUTED inputs (a rolling per-bar return history,
+a drawdown-velocity figure, etc. - all assembled by main.py once per bar
+from state it already tracks) - no I/O, no per-bar work heavier than a
+handful of float comparisons, respecting main.py's per-bar latency budget
+the same way every other pure risk/analyzer module in this codebase does.
+
+GUARDRAIL - fail-open at two levels, matching execution/cost_model.py::
+build_net_edge_decision()'s own contract:
+  1. config["enabled"] is False (the function-level default) -> never trips,
+     full no-op, regardless of any other input.
+  2. Even when enabled, each INDIVIDUAL condition's own threshold defaults
+     to a value that condition can never cross - so enabling the kill
+     switch with only some thresholds configured only activates those
+     specific checks, never accidentally activates an unconfigured one.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import asdict, dataclass, field
+
+# Deliberately extreme "this condition can never fire" sentinels - not 0.0
+# or None, which would either behave surprisingly (0.0 is a real threshold
+# some configs might genuinely want) or require every comparison below to
+# be null-guarded twice. A value this far outside any plausible input
+# reliably degrades a single unconfigured condition to a no-op without
+# touching the others.
+_NEVER_BELOW = -1e12
+_NEVER_ABOVE = 1e12
+
+
+@dataclass(frozen=True)
+class KillSwitchDecision:
+    tripped: bool
+    severity: str
+    triggers: list[str] = field(default_factory=list)
+    reason: str = ""
+    recommended_action: str = "none"
+    observed: dict = field(default_factory=dict)
+    thresholds: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def _finite_or_none(value) -> float | None:
+    """V5.4.5 (development/Problems.md #117): normalizes a runtime metric to
+    a finite float or None. The individual trigger guards below only check
+    `is not None` before a one-sided comparison - and every one of those
+    comparisons is False for NaN (`nan < floor` / `nan > cap`), so a NaN
+    metric silently skipped its own condition while the switch appeared
+    armed. NaN now degrades exactly like the documented None path."""
+    if value is None:
+        return None
+    try:
+        as_float = float(value)
+    except (TypeError, ValueError):
+        return None
+    return as_float if math.isfinite(as_float) else None
+
+
+def _rolling_sharpe(
+    returns: list[float], trading_days_per_year: int = 252, min_return_std_floor: float = 0.0
+) -> float | None:
+    """None (never 0.0) when there are fewer than 2 observations - the
+    caller must be able to tell "not enough data yet" apart from
+    "genuinely zero Sharpe" (a std of exactly 0.0 with >=2 observations IS
+    reported as 0.0, same convention evaluation/rank_book_simulator.py::
+    _annualized_sharpe() already uses).
+
+    GUARDRAIL (Problems.md - a sticky kill-switch trip from a numerically
+    meaningless reading): std <= max(0.0, min_return_std_floor) also
+    returns a clean 0.0 - widening the exact-zero guard above into a
+    near-zero guard. mean/std*sqrt(trading_days_per_year) is numerically
+    explosive whenever std is small but nonzero: a return window that's
+    mostly flat/cash (e.g. a mostly-uninvested portfolio) with just a
+    couple of small real values mixed in can swing to wildly extreme
+    Sharpe readings - both directions - purely from which few nonzero
+    values happen to still be inside the window, not from genuine risk-
+    adjusted performance. Reproduced directly against a real backtest's
+    equity curve: a near-flat window produced Sharpe swings of +2.25 and
+    -2.28 bar-to-bar from noise alone. min_return_std_floor=0.0 (default)
+    reproduces today's exact behavior for any caller that doesn't pass it."""
+    if len(returns) < 2:
+        return None
+    # V5.4.5 (Problems.md #117): one non-finite return poisons mean/std into
+    # NaN, which then silently skipped the Sharpe comparison downstream.
+    # A window containing any non-finite value is not a readable window -
+    # degrade to None (the documented "insufficient data" path).
+    if any(not math.isfinite(float(value)) for value in returns):
+        return None
+    mean = sum(returns) / len(returns)
+    variance = sum((value - mean) ** 2 for value in returns) / (len(returns) - 1)
+    std = math.sqrt(variance)
+    if std <= max(0.0, min_return_std_floor):
+        return 0.0
+    sharpe = (mean / std) * math.sqrt(trading_days_per_year)
+    return sharpe if math.isfinite(sharpe) else None
+
+
+def evaluate_kill_switch(runtime_metrics: dict, config: dict) -> KillSwitchDecision:
+    """Evaluated once per bar by main.py, fed a `runtime_metrics` dict it
+    assembles from state it already tracks:
+      - "recent_bar_returns": list[float] - a rolling per-bar portfolio
+        return history (main.py's own bounded deque), used to compute a
+        rolling Sharpe over the trailing `evaluation_bars` window.
+      - "drawdown_velocity_pct_per_bar": float | None - this bar's total
+        drawdown minus the previous bar's (a one-bar rate of change, not
+        an average - a single sharp bar is exactly what this exists to
+        catch quickly).
+      - "live_rank_ic": float | None - the most recent rank-IC-decay
+        trigger's metric_value, if the LATEST entry in
+        visualization/grafana/retraining_status.json's last_trigger
+        happens to be a rank_ic_decay_trigger (main.py never opens its own
+        Postgres connection - this is the same "read a locally-cached file
+        a separate Postgres-connected worker refreshes" pattern
+        read_manual_trade_lock_override()/load_cached_fred_series() already
+        use). None whenever the latest trigger isn't rank-IC-shaped, not
+        just when the file is missing - a stale/wrong-shaped signal must
+        never be treated as a real reading.
+      - "consecutive_losses": int | None - main.py's own realized-trade
+        streak counter.
+      - "slippage_divergence_bps": float | None - realized-vs-expected
+        round-trip cost divergence from the most recent fill(s)
+        (execution/cost_model.py's expected estimate vs. the actual fill
+        price main.py's OnOrderEvent observes). None until at least one
+        fill has been observed this session.
+      - "model_age_days": float | None - age of the active model artifact
+        on disk.
+      - "reconciliation_breach": bool - True when execution/reconciliation.py::
+        reconcile_positions()'s max_abs_weight_drift exceeded
+        phase_v2.reconciliation.max_tolerated_drift this bar (Step 6.2)
+        and phase_v2.reconciliation.trips_kill_switch is true - reconciliation
+        failures trip the switch rather than being logged and ignored.
+
+    Any key's value being None simply skips that one condition (never
+    raises, never counts as a trip) - a bar where a given signal isn't
+    available yet degrades that ONE condition, not the whole switch."""
+    if not bool(config.get("enabled", False)):
+        return KillSwitchDecision(tripped=False, severity="none", reason="kill_switch_disabled")
+
+    evaluation_bars = int(config.get("evaluation_bars", 60))
+    # GUARDRAIL (Problems.md - kill switch tripped on bar 2-3 of every
+    # run): evaluation_bars was previously used ONLY as a slice bound
+    # ([-evaluation_bars:]), never as a minimum-sample requirement, so
+    # _rolling_sharpe() happily annualized a 2-observation mean/std by
+    # sqrt(252) into an absurd magnitude and tripped the switch almost
+    # immediately. min_bars_for_sharpe defaults to evaluation_bars itself
+    # (the value's own documented intent - "the trailing window size") and
+    # gates whether the rolling-Sharpe trigger is evaluated AT ALL this
+    # bar, not just how much history it's computed over.
+    min_bars_for_sharpe = int(config.get("min_bars_for_sharpe", evaluation_bars))
+    # GUARDRAIL (Problems.md - a real backtest's kill switch stuck sticky
+    # on a spurious trip) - independent of min_bars_for_sharpe above:
+    # count and variance are orthogonal failure modes. A window with
+    # plenty of samples that are almost all exactly zero (e.g. a mostly-
+    # cash portfolio) clears the count floor fine but is still numerically
+    # degenerate for mean/std - see _rolling_sharpe()'s own docstring.
+    # Default 0.0005 (std*sqrt(252) ~= 1% annualized) - below this, daily
+    # returns are behaviorally indistinguishable from sitting in cash, far
+    # more likely a near-zero-return artifact than a real low-vol edge.
+    min_return_std_for_sharpe = float(config.get("min_return_std_for_sharpe", 0.0005))
+    min_rolling_sharpe = float(config.get("min_rolling_sharpe", _NEVER_BELOW))
+    max_drawdown_velocity_pct_per_bar = float(config.get("max_drawdown_velocity_pct_per_bar", _NEVER_ABOVE))
+    min_live_rank_ic = float(config.get("min_live_rank_ic", _NEVER_BELOW))
+    max_consecutive_losses = float(config.get("max_consecutive_losses", _NEVER_ABOVE))
+    max_slippage_divergence_bps = float(config.get("max_slippage_divergence_bps", _NEVER_ABOVE))
+    max_model_age_days = float(config.get("max_model_age_days", _NEVER_ABOVE))
+
+    triggers: list[str] = []
+    observed: dict = {}
+
+    # evaluation_bars <= 0 previously meant "use the entire history" via
+    # Python's own `[-0:]` == `[0:]` slice semantics - not a real window,
+    # and not what a misconfigured 0/negative value should do. Treat it as
+    # no window at all (insufficient data, trigger never evaluated) rather
+    # than silently falling back to unbounded history.
+    all_returns = list(runtime_metrics.get("recent_bar_returns") or [])
+    recent_returns = all_returns[-evaluation_bars:] if evaluation_bars > 0 else []
+    observed["rolling_sharpe_num_bars"] = len(recent_returns)
+    rolling_sharpe = (
+        _rolling_sharpe(recent_returns, min_return_std_floor=min_return_std_for_sharpe)
+        if len(recent_returns) >= min_bars_for_sharpe
+        else None
+    )
+    observed["rolling_sharpe"] = rolling_sharpe
+    if rolling_sharpe is not None and rolling_sharpe < min_rolling_sharpe:
+        triggers.append("rolling_sharpe_below_floor")
+
+    drawdown_velocity = _finite_or_none(runtime_metrics.get("drawdown_velocity_pct_per_bar"))
+    observed["drawdown_velocity_pct_per_bar"] = drawdown_velocity
+    if drawdown_velocity is not None and drawdown_velocity > max_drawdown_velocity_pct_per_bar:
+        triggers.append("drawdown_velocity_above_cap")
+
+    live_rank_ic = _finite_or_none(runtime_metrics.get("live_rank_ic"))
+    observed["live_rank_ic"] = live_rank_ic
+    if live_rank_ic is not None and live_rank_ic < min_live_rank_ic:
+        triggers.append("live_rank_ic_below_floor")
+
+    consecutive_losses = _finite_or_none(runtime_metrics.get("consecutive_losses"))
+    observed["consecutive_losses"] = consecutive_losses
+    if consecutive_losses is not None and consecutive_losses > max_consecutive_losses:
+        triggers.append("consecutive_losses_above_cap")
+
+    slippage_divergence_bps = _finite_or_none(runtime_metrics.get("slippage_divergence_bps"))
+    observed["slippage_divergence_bps"] = slippage_divergence_bps
+    if slippage_divergence_bps is not None and slippage_divergence_bps > max_slippage_divergence_bps:
+        triggers.append("slippage_divergence_above_cap")
+
+    model_age_days = _finite_or_none(runtime_metrics.get("model_age_days"))
+    observed["model_age_days"] = model_age_days
+    if model_age_days is not None and model_age_days > max_model_age_days:
+        triggers.append("model_age_above_cap")
+
+    if bool(runtime_metrics.get("reconciliation_breach", False)):
+        triggers.append("reconciliation_breach")
+        observed["reconciliation_breach"] = True
+
+    thresholds = {
+        "evaluation_bars": evaluation_bars,
+        "min_bars_for_sharpe": min_bars_for_sharpe,
+        "min_return_std_for_sharpe": min_return_std_for_sharpe,
+        "min_rolling_sharpe": min_rolling_sharpe,
+        "max_drawdown_velocity_pct_per_bar": max_drawdown_velocity_pct_per_bar,
+        "min_live_rank_ic": min_live_rank_ic,
+        "max_consecutive_losses": max_consecutive_losses,
+        "max_slippage_divergence_bps": max_slippage_divergence_bps,
+        "max_model_age_days": max_model_age_days,
+    }
+
+    if not triggers:
+        return KillSwitchDecision(
+            tripped=False,
+            severity="none",
+            triggers=[],
+            reason="all_checks_within_thresholds",
+            recommended_action="none",
+            observed=observed,
+            thresholds=thresholds,
+        )
+
+    severity = "critical" if len(triggers) > 1 else "warning"
+    return KillSwitchDecision(
+        tripped=True,
+        severity=severity,
+        triggers=triggers,
+        reason=f"kill_switch_{'_and_'.join(triggers)}",
+        recommended_action=str(config.get("action", "trade_lock")),
+        observed=observed,
+        thresholds=thresholds,
+    )