aether-quant 0.0.1__py3-none-any.whl

execution/order_gate.py

@@ -0,0 +1,388 @@
+"""Pure, Lean-free order gating for Phase V2-15 (Observation Mode).
+
+No imports from AlgorithmImports/QCAlgorithm live here on purpose: this
+module owns the mode -> real-vs-simulated order decision table and must be
+unit-testable without a Lean runtime on sys.path.
+"""
+
+from __future__ import annotations
+
+import math
+
+VALID_MODES = ("backtest", "observation", "paper", "live")
+DEFAULT_FALLBACK_MODE = "observation"
+
+# Default ceiling on the per-fill slippage resolve_fill_slippage() will
+# ever apply, regardless of what liquidity/market_liquidity.py's
+# estimated_round_trip_cost computes. 500bps (5%) is far above anything the
+# estimator produces under normal participation (build_liquidity_decision()
+# already blocks orders at 5% participation, long before slippage_factor's
+# default 0.1 multiplier could get anywhere near this), so this only ever
+# binds as a guard against a degenerate estimate (e.g. a volatility spike on
+# a razor-thin bar) corrupting a fill price - never a normal-path limiter.
+# Overridable via phase_v2.liquidity.fill_slippage.max_bps (main.py reads
+# it in _ensure_ready() and passes it into every call below) - this
+# constant is only the fallback when that key is absent from config.json.
+MAX_LIQUIDITY_SLIPPAGE_BPS = 500.0
+
+# phase_v2.liquidity.fill_slippage.source: which LiquidityDecision field
+# main.py converts into fill-slippage bps. "round_trip" (default, see
+# execution/README.md's "Real fill slippage" section for the rationale) =
+# estimated_round_trip_cost (price impact + bid-ask spread combined).
+# "impact_only" = estimated_slippage alone, for isolating/excluding the
+# spread-crossing component.
+VALID_FILL_SLIPPAGE_SOURCES = ("round_trip", "impact_only")
+DEFAULT_FILL_SLIPPAGE_SOURCE = "round_trip"
+
+
+def resolve_runtime_mode(raw_mode: str | None) -> str:
+    """Normalize a config-supplied mode value, failing safe to observation."""
+    if isinstance(raw_mode, str) and raw_mode in VALID_MODES:
+        return raw_mode
+    return DEFAULT_FALLBACK_MODE
+
+
+def resolve_order_permission(
+    mode: str,
+    allow_live_orders: bool,
+    broker_config_present: bool,
+    risk_locks_healthy: bool,
+) -> tuple[bool, str]:
+    """Decide whether a real broker order may be placed in the given mode.
+
+    observation always returns False regardless of the other flags - this is
+    the single safety invariant the whole phase depends on.
+    """
+    if mode == "backtest":
+        return True, "backtest_unrestricted"
+
+    if mode == "observation":
+        return False, "observation_mode_no_real_orders"
+
+    if mode == "paper":
+        if allow_live_orders and broker_config_present and risk_locks_healthy:
+            return True, "paper_orders_enabled"
+        if allow_live_orders and broker_config_present:
+            # V5.4.5 (development/Problems.md #116): paper previously
+            # ignored risk_locks_healthy entirely - a tripped kill switch /
+            # drawdown lock / manual lock could not stop real broker orders
+            # in the one mode that actually reaches a brokerage besides
+            # live. Same enforcement point as live below.
+            return False, "paper_orders_blocked_risk_lock"
+        return False, "paper_orders_blocked_missing_flag_or_broker_config"
+
+    if mode == "live":
+        if allow_live_orders and broker_config_present and risk_locks_healthy:
+            return True, "live_orders_enabled"
+        return False, "live_orders_blocked_missing_flag_or_broker_config_or_risk_lock"
+
+    return False, "unknown_mode_defaults_to_no_orders"
+
+
+def slippage_amount(reference_price: float, slippage_bps: float) -> float:
+    """Absolute per-unit price slippage for a given bps estimate.
+
+    Shared by main.py's Lean SlippageModel (real backtest/live fills, wired
+    via security.SetSlippageModel()) and simulate_fill() below
+    (observation-mode simulated fills), so both paths apply the exact same
+    bps -> price-impact math instead of two independently-drifting
+    formulas. Returns 0.0 for a non-positive or non-finite price/bps -
+    slippage is never negative (never improves the fill price), and a NaN
+    estimate must never reach a fill price (V5.4.5, Problems.md #117:
+    `nan <= 0` is False, so the old guard let NaN straight into
+    `price * nan`).
+    """
+    if (
+        not math.isfinite(reference_price)
+        or not math.isfinite(slippage_bps)
+        or reference_price <= 0
+        or slippage_bps <= 0
+    ):
+        return 0.0
+    return float(reference_price) * (float(slippage_bps) / 10_000.0)
+
+
+def resolve_fill_slippage_source(raw_source: str | None) -> str:
+    """Normalize a phase_v2.liquidity.fill_slippage.source config value,
+    failing safe to DEFAULT_FILL_SLIPPAGE_SOURCE for anything unset/unknown
+    - same fail-safe-normalize convention as resolve_runtime_mode() above.
+    """
+    if isinstance(raw_source, str) and raw_source in VALID_FILL_SLIPPAGE_SOURCES:
+        return raw_source
+    return DEFAULT_FILL_SLIPPAGE_SOURCE
+
+
+def liquidity_cost_fraction(liquidity_payload: dict, source: str) -> float:
+    """Pick which liquidity/market_liquidity.py::LiquidityDecision field
+    (already a fraction, e.g. 0.001 = 10bps) feeds the fill-slippage
+    estimate, per resolve_fill_slippage_source()'s normalized source.
+    Missing/malformed field -> 0.0, never raises.
+    """
+    key = "estimated_slippage" if source == "impact_only" else "estimated_round_trip_cost"
+    return float(liquidity_payload.get(key, 0.0) or 0.0)
+
+
+def resolve_slippage_bps(
+    symbol_key: str,
+    slippage_bps_by_symbol: dict,
+    max_bps: float = MAX_LIQUIDITY_SLIPPAGE_BPS,
+) -> float:
+    """Pure lookup + clamp: how many bps of slippage to charge symbol_key,
+    given the per-symbol bps dict main.py refreshes every bar in
+    on_data()'s Pass 2 (liquidity_cost_fraction()'s selected field,
+    converted to bps). Shared by resolve_fill_slippage() below (real Lean
+    fills) and main.py's observation-mode
+    SimulatedPortfolioState.enter_long() call sites, so both paths apply
+    the identical clamp.
+
+    Missing symbol -> 0.0 bps (no liquidity estimate computed yet, e.g. an
+    order placed before Pass 2 has run for it once). Clamped to max_bps
+    (phase_v2.liquidity.fill_slippage.max_bps, defaulting to
+    MAX_LIQUIDITY_SLIPPAGE_BPS) as a guard against a degenerate estimate
+    corrupting a fill price. Non-finite estimates degrade to 0.0 (V5.4.5,
+    Problems.md #117) - max/min pass NaN through untouched, so the clamp
+    alone would not.
+    """
+    raw = slippage_bps_by_symbol.get(symbol_key, 0.0) or 0.0
+    try:
+        bps = float(raw)
+    except (TypeError, ValueError):
+        return 0.0
+    if not math.isfinite(bps):
+        return 0.0
+    return min(max(bps, 0.0), float(max_bps))
+
+
+def resolve_fill_slippage(
+    symbol_key: str,
+    reference_price: float,
+    slippage_bps_by_symbol: dict,
+    max_bps: float = MAX_LIQUIDITY_SLIPPAGE_BPS,
+) -> float:
+    """Pure lookup + clamp + apply, used by main.py's real Lean
+    SlippageModel (_LiquidityAwareSlippageModel.GetSlippageApproximation)
+    to turn the per-symbol bps dict into an absolute fill-price delta."""
+    return slippage_amount(reference_price, resolve_slippage_bps(symbol_key, slippage_bps_by_symbol, max_bps))
+
+
+def simulate_fill(
+    close_price: float,
+    target_weight: float,
+    equity: float,
+    slippage_bps: float = 0.0,
+) -> dict:
+    """Pure hypothetical fill-price/quantity/notional math.
+
+    Quantity/notional are purely a function of the target portfolio weight,
+    current equity, and fill price - the same math applies whether the
+    caller is entering, exiting (target_weight=0.0), or liquidating.
+    """
+    if close_price <= 0:
+        return {"fill_price": 0.0, "notional": 0.0, "quantity": 0.0}
+
+    fill_price = close_price + slippage_amount(close_price, slippage_bps)
+    notional = target_weight * equity
+    quantity = notional / fill_price
+
+    return {
+        "fill_price": fill_price,
+        "notional": notional,
+        "quantity": quantity,
+    }
+
+
+def resolve_limit_price(
+    reference_price: float,
+    spread_fraction: float,
+    is_buy: bool,
+    offset_multiplier: float = 1.0,
+) -> float:
+    """Pure limit-price placement for main.py's real limit orders
+    (execution/risk realism pass, part 2).
+
+    Offsets reference_price by half of spread_fraction (already a
+    fraction, e.g. 0.001 = 10bps - the same unit family
+    liquidity_cost_fraction() above consumes) times offset_multiplier
+    (phase_v2.limit_orders.offset_multiplier). Halving matches the
+    standard "bid = mid - spread/2, ask = mid + spread/2" convention -
+    spread_fraction is a round-trip/full-spread estimate
+    (liquidity/market_liquidity.py's spread_proxy), a single-sided limit
+    order should only cross half of it.
+
+    A buy limit sits BELOW reference_price (never overpay above the last
+    close); a sell/short limit sits ABOVE it (never undersell below the
+    last close). offset_multiplier > 1.0 places a more passive (further
+    from reference, lower fill probability, more price improvement if
+    filled) limit; < 1.0 places a more aggressive one (closer to/crossing
+    reference, higher fill probability, less improvement).
+
+    Returns reference_price unchanged whenever reference_price or
+    spread_fraction is non-positive - never returns a non-positive or
+    crossed-through price, matching slippage_amount()'s fail-safe-to-
+    neutral convention above.
+    """
+    if reference_price <= 0 or spread_fraction <= 0:
+        return float(reference_price)
+    offset = float(reference_price) * (float(spread_fraction) / 2.0) * float(offset_multiplier)
+    return reference_price - offset if is_buy else reference_price + offset
+
+
+# Pure classification of a Lean OrderStatus enum member's name (or
+# str(status)) into "pending" / "filled" / "canceled" / "unknown" -
+# isolates the one place this pass has to guess at Lean's real OrderStatus
+# spelling (see execution/README.md's "Real limit orders" section for the
+# full casing-risk writeup) into a single small function, so a casing fix
+# is a one-line change here rather than a hunt through main.py's
+# on_order_event()/_process_pending_limit_order_timeouts().
+#
+# V5.2.8 (development/Problems.md #34) - "CancelPending" added after
+# scanning 33 real order-events.json files across backtests/2026-07-*/
+# and backtests/2026-08-*/: Lean's real OrderStatus.CancelPending appears
+# 23 times (e.g. backtests/2026-08-11_09-56-24, paired 1:1 with 23
+# "canceled" records - a genuine unfilled-timeout cancel lifecycle,
+# directly confirmed on individual records, e.g. HYG qty 15 @
+# limitPrice=54.30, fillQuantity=0.0). Previously fell through to
+# "unknown", which every caller already treats identically to "pending" -
+# so this is a precision/self-documentation fix, not a behavior change.
+# PartiallyFilled has never once appeared across those 33 files - a real,
+# permanent, still-unexercised-in-practice caveat, not a gap to close here.
+PENDING_ORDER_STATUS_NAMES = ("New", "Submitted", "PartiallyFilled", "UpdateSubmitted", "CancelPending")
+TERMINAL_FILLED_STATUS_NAMES = ("Filled",)
+TERMINAL_CANCELED_STATUS_NAMES = ("Canceled", "Invalid")
+
+
+def classify_order_status(status_name: str) -> str:
+    """Pure string classification, never raises on an unrecognized value -
+    returns "unknown" instead, which callers treat as still-pending
+    (conservative: never mistakes an unrecognized status for a fill)."""
+    if status_name in TERMINAL_FILLED_STATUS_NAMES:
+        return "filled"
+    if status_name in TERMINAL_CANCELED_STATUS_NAMES:
+        return "canceled"
+    if status_name in PENDING_ORDER_STATUS_NAMES:
+        return "pending"
+    return "unknown"
+
+
+# V5.3.1 (development/Problems.md #34/#96) - main.py's on_order_event()/
+# _process_pending_limit_order_timeouts() cannot themselves be unit-tested
+# (main.py imports QCAlgorithm from AlgorithmImports, which only resolves
+# inside a real Lean process - confirmed: `python -c "import main"` raises
+# NameError outside one). These two functions are a pure restatement of
+# those methods' decision logic, extracted so classify_order_status("Partially
+# Filled") == "pending" (already tested above) has a testable path all the
+# way through to "does the pending-order record correctly stay open, and
+# does a subsequent timeout fall back for only the REMAINING quantity" -
+# not just proven at the classification step. main.py calls these two
+# functions instead of inlining the equivalent branches.
+
+
+def should_clear_pending_limit_order(status: str, all_legs_filled: bool) -> bool:
+    """Mirrors on_order_event()'s clearing decision: a tracked pending-
+    limit-order record should be POPPED (stop tracking it) only when it's
+    genuinely resolved - "filled" (and only once every leg of a multi-leg
+    combo has filled, not on the first leg alone) or "canceled". Every
+    other status - "pending", "unknown", and critically "PartiallyFilled"
+    (which classify_order_status() maps to "pending") - returns False, so
+    a partial fill leaves the record tracked for
+    resolve_limit_order_timeout_action() to eventually resolve, exactly as
+    main.py's own on_order_event() docstring already documents.
+
+    `all_legs_filled` is irrelevant (never even inspected) unless
+    status == "filled" - a "canceled" leg always clears regardless of the
+    other legs' state, matching main.py's existing elif branch."""
+    if status == "filled":
+        return all_legs_filled
+    return status == "canceled"
+
+
+def resolve_limit_order_timeout_action(
+    status: str,
+    quantity_remaining: float,
+    fallback_enabled: bool,
+) -> dict:
+    """Mirrors _process_pending_limit_order_timeouts()'s per-leg branch
+    once a tracked order has sat unfilled for
+    phase_v2.limit_orders.unfilled_timeout_bars bars: an already-resolved
+    leg ("filled"/"canceled" - main.py's own comment: resolved by
+    on_order_event() this bar or an earlier one) needs no action here.
+    Any other status - "pending", "unknown", or "PartiallyFilled" (which
+    classify_order_status() maps to "pending") - gets canceled, with a
+    market-order fallback for exactly `quantity_remaining` (never the
+    order's original size, which this function deliberately never
+    receives - a partial fill's leftover quantity is structurally the
+    only number that can ever be returned here) when fallback_enabled and
+    there IS a nonzero remainder.
+
+    Returns {"should_cancel": bool, "fallback_market_quantity": float | None}.
+    """
+    if status in ("filled", "canceled"):
+        return {"should_cancel": False, "fallback_market_quantity": None}
+    fallback_market_quantity = quantity_remaining if (fallback_enabled and quantity_remaining != 0) else None
+    return {"should_cancel": True, "fallback_market_quantity": fallback_market_quantity}
+
+
+# Pure classification of main.py::_apply_signal()/_apply_option_order()'s
+# execution_note return strings into "was a REAL order actually placed" -
+# used by the audit-log hook (development/Problems.md #42) at its single
+# call site in on_data()'s Pass 2 loop, rather than scattering a push call
+# across every one of _apply_signal()'s many branches/asset-class routings
+# (equity/futures/option x buy/sell/short, each with its own f-string
+# execution_note). An explicit denylist, not a broader heuristic, so a new
+# no-op reason added to main.py in the future fails safe (gets audited as
+# "real" and is easy to notice/fix) rather than silently never being
+# audited if it happened to match a loose pattern.
+_NO_OP_EXECUTION_NOTES = frozenset(
+    {
+        "kept_long",
+        "kept_short",
+        "already_flat",
+        "cooldown_active",
+        "no_action",
+        "max_active_positions_reached",
+        "futures_zero_contract_count",
+        "options_no_usable_contract",
+        "options_multi_leg_no_usable_legs",
+        # V4.3.0 - allow adding to an existing position (development/
+        # Changelog.md). Plain constants only, never f-strings - this
+        # denylist is exact-string matching, and an f-string note would
+        # silently misclassify as a REAL placement, the wrong-direction
+        # failure mode this module's own docstring warns about.
+        "kept_long_futures",
+        "kept_short_futures",
+        "futures_zero_delta_kept",
+        "options_kept",
+        "options_contract_drifted_kept",
+        "options_multi_leg_kept",
+        "options_multi_leg_mismatch_kept",
+        # V4.4 - architecturally-sound options (development/Problems.md):
+        # single-leg/spread scale-down replaced "options_zero_or_negative_
+        # delta_kept"/"options_spread_shrink_unsupported" (both retired -
+        # a negative delta is now a REAL reduce order, never a no-op) with
+        # a delta==0-only no-op; the multi-position book adds two more.
+        "options_zero_delta_kept",
+        "options_at_position_cap_kept",
+        "options_held_contract_not_in_chain_kept",
+        # V4.5 (full OptionStrategies coverage, §9.1): the at-cap re-price
+        # search is scoped to records sharing this bar's strategy_name -
+        # when no held record is a comparable shape, there's nothing
+        # sensible to re-price, a distinct no-op from every "kept" reason
+        # above (renamed from V4.4's "spread"-suffixed strings - "spread"
+        # retired as a record kind, folded into "multi_leg", see main.py).
+        "options_no_comparable_position_to_reprice_kept",
+    }
+)
+_NO_OP_EXECUTION_NOTE_SUFFIXES = ("_exposure_cap_reached",)
+
+
+def is_real_order_placement(execution_note: str, orders_allowed: bool) -> bool:
+    """True only for a genuinely-placed real order - never a simulated/
+    observation-mode fill (execution_note prefixed "simulated_") and never
+    one of the known no-op/blocked outcomes above."""
+    if not orders_allowed or execution_note.startswith("simulated_"):
+        return False
+    if execution_note in _NO_OP_EXECUTION_NOTES:
+        return False
+    if execution_note.endswith(_NO_OP_EXECUTION_NOTE_SUFFIXES):
+        return False
+    return True

execution/paper_readiness.py

@@ -0,0 +1,181 @@
+"""Pure, Lean-free paper/live broker-readiness gating (Phase V2-21/V2-22).
+
+`execution/order_gate.py::resolve_order_permission()` already implements the
+correct mode -> real-vs-simulated decision table, but the `broker_config_present`
+flag it depends on used to be `bool(self.paper_brokerage)` in `main.py` - a
+string that is never empty by construction, so the check was a no-op. This
+module is what actually decides whether that flag should be True, for both
+`paper` mode (Lean's built-in PaperBrokerage, no real credentials needed) and
+`live` mode (V2-22, real broker credentials).
+
+No imports from AlgorithmImports/QCAlgorithm/psycopg live here on purpose -
+see execution/paper_readiness_io.py for the IO layer that feeds these
+functions, and execution/paper_readiness_report.py for the offline report
+that additionally evaluates observation-mode readiness.
+"""
+
+from __future__ import annotations
+
+_PAPER_REASON_ALL_CONFIRMED = "paper_broker_config_confirmed"
+_PAPER_REASON_MISSING_BROKERAGE = "paper_broker_config_missing_brokerage"
+_PAPER_REASON_MISSING_DATA_PROVIDER = "paper_broker_config_missing_live_data_provider"
+_PAPER_REASON_MISSING_MANUAL_REVIEW = "paper_broker_config_missing_manual_review"
+
+_LIVE_REASON_ALL_CONFIRMED = "live_broker_config_confirmed"
+_LIVE_REASON_PAPER_NOT_READY = "live_broker_config_paper_corridor_not_ready"
+_LIVE_REASON_MISSING_CREDENTIALS = "live_broker_config_missing_credentials"
+_LIVE_REASON_RISK_POSTURE_UNSAFE = "live_broker_config_risk_posture_unsafe"
+_LIVE_REASON_UNSAFE_DB_PASSWORD = "live_broker_config_unsafe_db_password"
+
+
+def evaluate_paper_broker_config(paper_trading_config: dict) -> tuple[bool, str]:
+    """mode='paper' gate. All three must be true:
+    - brokerage is a non-empty known value
+    - live_data_provider_configured (human-set attestation - a live market
+      data feed is required for Lean's live-paper environment even though
+      PaperBrokerage itself needs no broker credentials)
+    - manual_review_confirmed (human-set attestation, replaces the old
+      phase6.paper_trading.ready_for_live_paper stub)
+    """
+    if not str(paper_trading_config.get("brokerage", "")).strip():
+        return False, _PAPER_REASON_MISSING_BROKERAGE
+    if not bool(paper_trading_config.get("live_data_provider_configured", False)):
+        return False, _PAPER_REASON_MISSING_DATA_PROVIDER
+    if not bool(paper_trading_config.get("manual_review_confirmed", False)):
+        return False, _PAPER_REASON_MISSING_MANUAL_REVIEW
+    return True, _PAPER_REASON_ALL_CONFIRMED
+
+
+def evaluate_live_risk_posture(risk_config: dict, live_config: dict) -> tuple[bool, str]:
+    """Sanity ceiling for mode='live' - not a redesign of the drawdown
+    circuit breaker, just a guard against live mode running with an
+    accidentally-loose (or disabled) risk config that was fine for
+    paper/observation but is unacceptable once real capital is at risk."""
+    max_daily_drawdown_pct = float(risk_config.get("max_daily_drawdown_pct", 1.0))
+    max_total_drawdown_pct = float(risk_config.get("max_total_drawdown_pct", 1.0))
+    liquidate_on_risk_breach = bool(risk_config.get("liquidate_on_risk_breach", False))
+
+    allowed_daily = float(live_config.get("max_allowed_daily_drawdown_pct", 0.0))
+    allowed_total = float(live_config.get("max_allowed_total_drawdown_pct", 0.0))
+
+    if not liquidate_on_risk_breach:
+        return False, _LIVE_REASON_RISK_POSTURE_UNSAFE
+    if max_daily_drawdown_pct > allowed_daily:
+        return False, _LIVE_REASON_RISK_POSTURE_UNSAFE
+    if max_total_drawdown_pct > allowed_total:
+        return False, _LIVE_REASON_RISK_POSTURE_UNSAFE
+    return True, _LIVE_REASON_ALL_CONFIRMED
+
+
+def evaluate_live_broker_config(
+    paper_trading_config: dict,
+    live_credentials_present: bool,
+    risk_config: dict | None = None,
+    live_config: dict | None = None,
+    postgres_dsn: str | None = None,
+) -> tuple[bool, str]:
+    """mode='live' gate (V2-22). You cannot go straight to live without a
+    validated paper corridor - the paper check must also pass - AND real
+    broker credentials must be present AND (if risk/live config supplied)
+    the live risk posture must be safe AND (if a Postgres DSN is supplied) it
+    must not still use the published dev-default password.
+
+    `postgres_dsn` is optional and defaults to None (unchecked) so existing
+    callers/tests are unaffected; main.py threads the real DSN through so a
+    live run against the public default password fails closed."""
+    paper_ready, paper_reason = evaluate_paper_broker_config(paper_trading_config)
+    if not paper_ready:
+        return False, _LIVE_REASON_PAPER_NOT_READY
+
+    if not live_credentials_present:
+        return False, _LIVE_REASON_MISSING_CREDENTIALS
+
+    if postgres_dsn is not None:
+        from execution.live_credentials import postgres_dsn_is_live_safe
+
+        if not postgres_dsn_is_live_safe(postgres_dsn):
+            return False, _LIVE_REASON_UNSAFE_DB_PASSWORD
+
+    if risk_config is not None and live_config is not None:
+        risk_ok, _ = evaluate_live_risk_posture(risk_config, live_config)
+        if not risk_ok:
+            return False, _LIVE_REASON_RISK_POSTURE_UNSAFE
+
+    return True, _LIVE_REASON_ALL_CONFIRMED
+
+
+def evaluate_broker_config(
+    mode: str,
+    paper_trading_config: dict,
+    live_credentials_present: bool = False,
+    risk_config: dict | None = None,
+    live_config: dict | None = None,
+    postgres_dsn: str | None = None,
+) -> tuple[bool, str]:
+    """Single entrypoint main.py._order_permission() calls regardless of
+    mode - dispatches to the two functions above. Any mode other than
+    'live' (including 'backtest'/'observation', where the result is unused
+    since resolve_order_permission() never consults broker_config_present
+    for those modes) goes through the paper path."""
+    if mode == "live":
+        return evaluate_live_broker_config(
+            paper_trading_config,
+            live_credentials_present,
+            risk_config,
+            live_config,
+            postgres_dsn,
+        )
+    return evaluate_paper_broker_config(paper_trading_config)
+
+
+def evaluate_observation_readiness(summary: dict, thresholds: dict) -> dict:
+    """Turns 4 of the 5 bullets in development/infrastructure.md's "Bereit
+    fuer Paper Trading?" checklist into code, given an already-computed
+    observation summary (experience.observation_metrics.compute_observation_summary()
+    output) and threshold config. The 5th bullet (manual review of trade
+    history for plausible entry/exit prices) is deliberately NOT automated -
+    it stays a human judgment call, surfaced via paper_trading_config's
+    manual_review_confirmed flag (see evaluate_paper_broker_config above).
+    """
+    min_observations = int(thresholds.get("min_observations", 500))
+    min_simulated_sharpe = float(thresholds.get("min_simulated_sharpe", 0.3))
+    max_simulated_drawdown_floor = float(thresholds.get("max_simulated_drawdown_floor", -0.15))
+    max_single_rejection_reason_share = float(thresholds.get("max_single_rejection_reason_share", 0.5))
+
+    count_observations = int(summary.get("count_observations", 0))
+    simulated_sharpe = float(summary.get("simulated_sharpe", 0.0))
+    simulated_max_drawdown = float(summary.get("simulated_max_drawdown", 0.0))
+    rejected_by_reason = summary.get("rejected_by_reason") or {}
+    total_rejections = sum(rejected_by_reason.values())
+    top_rejection_share = (max(rejected_by_reason.values()) / total_rejections) if total_rejections > 0 else 0.0
+
+    checks = {
+        "observation_count": {
+            "pass": count_observations >= min_observations,
+            "value": count_observations,
+            "threshold": min_observations,
+        },
+        "simulated_sharpe": {
+            "pass": simulated_sharpe >= min_simulated_sharpe,
+            "value": simulated_sharpe,
+            "threshold": min_simulated_sharpe,
+        },
+        "simulated_max_drawdown": {
+            "pass": simulated_max_drawdown >= max_simulated_drawdown_floor,
+            "value": simulated_max_drawdown,
+            "threshold": max_simulated_drawdown_floor,
+        },
+        "dominant_rejection_reason": {
+            "pass": top_rejection_share <= max_single_rejection_reason_share,
+            "value": top_rejection_share,
+            "threshold": max_single_rejection_reason_share,
+        },
+    }
+
+    blocking_reasons = [name for name, check in checks.items() if not check["pass"]]
+
+    return {
+        "ready": len(blocking_reasons) == 0,
+        "checks": checks,
+        "blocking_reasons": blocking_reasons,
+    }

execution/paper_readiness_io.py

@@ -0,0 +1,54 @@
+"""IO layer for paper/live broker readiness (Phase V2-21/V2-22).
+
+Mirrors risk/manual_override.py's read pattern: a single-key, mtime-gated
+config.json reader (see execution/config_cache.py) so a long-running
+paper/live process can pick up a config edit at the next session rollover
+without a restart. Also provides the one new Postgres query
+paper_readiness_report.py needs - observation-mode experience_events, which
+performance/postgres_triggers.py's existing fetch_recent_events()/
+fetch_events_since() don't filter by mode.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from execution.config_cache import read_cached
+
+_PHASE_V2_KEY = "phase_v2"
+_PAPER_TRADING_KEY = "paper_trading"
+
+
+def read_paper_trading_config(config_path: Path) -> dict:
+    """Mtime-gated read of phase_v2.paper_trading. Returns {} if the file or
+    key is absent - never raises."""
+    return read_cached(config_path, _read_paper_trading_config_uncached)
+
+
+def _read_paper_trading_config_uncached(config_path: Path) -> dict:
+    if not config_path.exists():
+        return {}
+    with config_path.open("r", encoding="utf-8") as f:
+        config = json.load(f)
+    value = config.get(_PHASE_V2_KEY, {}).get(_PAPER_TRADING_KEY, {})
+    return value if isinstance(value, dict) else {}
+
+
+def fetch_observation_mode_events(conn, limit: int = 10_000, since: datetime | None = None) -> list[dict]:
+    """Fetch experience_events payloads logged in mode='observation', oldest
+    first - feeds evaluate_observation_readiness() via
+    experience.observation_metrics.compute_observation_summary()."""
+    if since is None:
+        since = datetime.fromtimestamp(0, tz=timezone.utc)
+
+    with conn.cursor() as cur:
+        cur.execute(
+            "SELECT payload FROM experience_events WHERE mode = %(mode)s AND created_at > %(since)s "
+            "ORDER BY created_at ASC LIMIT %(limit)s;",
+            {"mode": "observation", "since": since, "limit": limit},
+        )
+        rows = cur.fetchall()
+
+    return [json.loads(row[0]) if isinstance(row[0], str) else row[0] for row in rows]