aether-quant 0.0.1__py3-none-any.whl

data_pipeline/yfinance_backfill.py

@@ -0,0 +1,501 @@
+"""Yahoo Finance historical data backfill (Phase V2-19.5).
+
+Manual, offline maintenance script — never runs inside the Lean container or
+any always-on Docker worker (mirrors train_topology.py's "never runs in the
+Lean container" status, not performance/trigger_worker.py's continuous-worker
+one). Fills gaps in thin local Lean zips (e.g. ETHUSD/LTCUSD, which only have
+a few scattered days of real Coinbase minute data — see
+train.py::ensure_derived_crypto_daily_series() and development/Changelog.md's
+Phase-9 entry) using `yfinance`.
+
+Two independent safety boundaries, both requiring an explicit human step:
+1. Writing/overwriting zip files is gated by --apply (default: dry run only).
+2. config.json's available_from/available_to are NEVER edited by this
+   script, --apply or not — train.py::build_asset_quality() only counts rows
+   inside those configured windows (config.json phase9.asset_quality), so
+   widening the zip alone does nothing until a human widens the window too.
+   This script only prints the suggested new values.
+
+Usage:
+    python -m data_pipeline.yfinance_backfill [--tickers ETHUSD LTCUSD] [--apply]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import math
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Callable
+from zipfile import ZipFile
+
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+ROOT = Path(__file__).resolve().parents[1]
+CONFIG_PATH = ROOT / "config.json"
+
+# Internal ticker -> Yahoo symbol, used only when the asset's own
+# config.json "backfill" block doesn't set an explicit "symbol".
+YAHOO_TICKER_OVERRIDES = {
+    "ETHUSD": "ETH-USD",
+    "BTCUSD": "BTC-USD",
+    "LTCUSD": "LTC-USD",
+}
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers
+# ---------------------------------------------------------------------------
+
+
+def yahoo_symbol_for(ticker: str, backfill_config: dict) -> str:
+    """backfill_config["symbol"] wins if present, else YAHOO_TICKER_OVERRIDES,
+    else the internal ticker unchanged (equities: AAPL -> AAPL)."""
+    explicit = backfill_config.get("symbol")
+    if explicit:
+        return str(explicit)
+    return YAHOO_TICKER_OVERRIDES.get(ticker, ticker)
+
+
+def detect_gap(asset: dict, existing_rows: list[dict]) -> dict:
+    """Pure: compares the asset's configured backfill_from/backfill_to
+    against the dates already present in its Lean zip (existing_rows, each a
+    dict with a "date" key holding a datetime.date). Returns whether a real
+    gap exists and the date range that should actually be fetched.
+    """
+    backfill_config = asset.get("backfill") or {}
+    if not backfill_config:
+        return {"needs_backfill": False, "missing_before": None, "missing_after": None, "fetch_start": None, "fetch_end": None}
+
+    fetch_start = date.fromisoformat(backfill_config["backfill_from"])
+    fetch_end = date.fromisoformat(backfill_config["backfill_to"])
+
+    existing_dates = [row["date"] for row in existing_rows]
+    existing_min = min(existing_dates) if existing_dates else None
+    existing_max = max(existing_dates) if existing_dates else None
+
+    missing_before = fetch_start if (existing_min is None or fetch_start < existing_min) else None
+    missing_after = fetch_end if (existing_max is None or fetch_end > existing_max) else None
+
+    return {
+        "needs_backfill": missing_before is not None or missing_after is not None,
+        "missing_before": missing_before,
+        "missing_after": missing_after,
+        "fetch_start": fetch_start,
+        "fetch_end": fetch_end,
+    }
+
+
+def scale_for_lean(rows: list[dict], security_type: str) -> list[dict]:
+    """Applies train.py's x10000 integer convention for equities (Lean's
+    deflated-price format — see train.py::load_lean_bars()); crypto rows
+    pass through unscaled, matching
+    train.py::ensure_derived_crypto_daily_series(). Pure — no I/O.
+    """
+    if security_type != "equity":
+        return [dict(row) for row in rows]
+
+    scaled = []
+    for row in rows:
+        scaled.append(
+            {
+                "date": row["date"],
+                "open": round(row["open"] * 10000),
+                "high": round(row["high"] * 10000),
+                "low": round(row["low"] * 10000),
+                "close": round(row["close"] * 10000),
+                "volume": row["volume"],
+            }
+        )
+    return scaled
+
+
+def rows_to_lean_csv(rows: list[dict]) -> str:
+    """Exact row format train.py::ensure_derived_crypto_daily_series() writes:
+    f"{date:%Y%m%d} 00:00,{open},{high},{low},{close},{volume}", one row per
+    line, sorted by date.
+    """
+    ordered = sorted(rows, key=lambda row: row["date"])
+    lines = [
+        f"{row['date'].strftime('%Y%m%d')} 00:00,{row['open']},{row['high']},{row['low']},{row['close']},{row['volume']}"
+        for row in ordered
+    ]
+    return "\n".join(lines) + ("\n" if lines else "")
+
+
+def _numeric(value: str):
+    try:
+        return int(value)
+    except ValueError:
+        return float(value)
+
+
+def _read_existing_lean_rows(path: Path) -> list[dict]:
+    """Reads a Lean daily zip's rows back into the same dict shape
+    scale_for_lean()/rows_to_lean_csv() use, preserving whatever numeric
+    representation (int or float) is already stored — no rescaling."""
+    rows: list[dict] = []
+    with ZipFile(path) as archive:
+        member = archive.namelist()[0]
+        with archive.open(member) as handle:
+            text = handle.read().decode("utf-8")
+
+    for line in text.splitlines():
+        if not line.strip():
+            continue
+        date_field, open_v, high_v, low_v, close_v, volume_v = line.split(",")
+        row_date = datetime.strptime(date_field.split()[0], "%Y%m%d").date()
+        rows.append(
+            {
+                "date": row_date,
+                "open": _numeric(open_v),
+                "high": _numeric(high_v),
+                "low": _numeric(low_v),
+                "close": _numeric(close_v),
+                "volume": _numeric(volume_v),
+            }
+        )
+    return rows
+
+
+def write_lean_zip(output_zip: Path, ticker: str, new_rows: list[dict], *, merge_with_existing: bool = True) -> None:
+    """Mirrors train.py::ensure_derived_crypto_daily_series()'s
+    ZipFile(output_zip, 'w') pattern, member name f'{ticker.lower()}.csv'.
+
+    When merge_with_existing, reads the existing zip's rows first and keys
+    the merge by date — existing (real Lean) rows always win on overlap;
+    new_rows only fill dates that were genuinely missing.
+    """
+    merged_by_date: dict[date, dict] = {}
+    if merge_with_existing and output_zip.exists():
+        for row in _read_existing_lean_rows(output_zip):
+            merged_by_date[row["date"]] = row
+
+    for row in new_rows:
+        merged_by_date.setdefault(row["date"], row)
+
+    csv_text = rows_to_lean_csv(list(merged_by_date.values()))
+
+    output_zip.parent.mkdir(parents=True, exist_ok=True)
+    member_name = f"{ticker.lower()}.csv"
+    with ZipFile(output_zip, "w") as archive:
+        archive.writestr(member_name, csv_text)
+
+
+# ---------------------------------------------------------------------------
+# V4.10 — forex sibling of the 5-column mid-price OHLCV functions above.
+# Lean's real forex daily CSV is a 10-column bid/ask format (confirmed
+# directly against the real local sample zips under
+# data/forex/{oanda,fxcm}/daily/ - see data/forex/readme.md), not the flat
+# OHLCV shape equity/crypto use. Yahoo Finance's own FX data is mid/last
+# OHLC only (no real bid/ask spread), so synthesize_forex_bid_ask_row()
+# below is an honest, documented zero-spread APPROXIMATION for backtest/
+# training purposes only, never a live spread feed (development/
+# Problems.md #66). The real local sample data (2007+) DOES carry genuine
+# historical bid != ask spread, so the merge path here preserves full
+# 10-field rows on overlap, never collapsing existing real rows to a
+# synthesized mid — same "existing/real rows always win" convention as
+# write_lean_zip() above.
+# ---------------------------------------------------------------------------
+
+
+def synthesize_forex_bid_ask_row(row: dict) -> dict:
+    """Yahoo Finance's FX data is mid/last OHLC only, no real bid/ask
+    spread — this is a documented, honest zero-spread APPROXIMATION for
+    backtest/training purposes only, never a live spread feed (see
+    development/Problems.md #66). Duplicates the same OHLC values into
+    both the bid and ask column groups, volume 0 in both — matches the
+    real Lean forex daily CSV shape (data/forex/readme.md) without
+    inventing a fake spread number."""
+    return {
+        "date": row["date"],
+        "bid_open": row["open"],
+        "bid_high": row["high"],
+        "bid_low": row["low"],
+        "bid_close": row["close"],
+        "bid_volume": 0,
+        "ask_open": row["open"],
+        "ask_high": row["high"],
+        "ask_low": row["low"],
+        "ask_close": row["close"],
+        "ask_volume": 0,
+    }
+
+
+def forex_rows_to_lean_csv(rows: list[dict]) -> str:
+    """10-column bid/ask Lean forex daily CSV — the FX sibling of
+    rows_to_lean_csv(). Rows already carry all 10 value fields (see
+    synthesize_forex_bid_ask_row()/_read_existing_lean_forex_rows() below)
+    — this function only formats and sorts, never synthesizes."""
+    ordered = sorted(rows, key=lambda row: row["date"])
+    lines = [
+        f"{row['date'].strftime('%Y%m%d')} 00:00,"
+        f"{row['bid_open']},{row['bid_high']},{row['bid_low']},{row['bid_close']},{row['bid_volume']},"
+        f"{row['ask_open']},{row['ask_high']},{row['ask_low']},{row['ask_close']},{row['ask_volume']}"
+        for row in ordered
+    ]
+    return "\n".join(lines) + ("\n" if lines else "")
+
+
+def _read_existing_lean_forex_rows(path: Path) -> list[dict]:
+    """Forex sibling of _read_existing_lean_rows() — 11-field split (date
+    + 10 bid/ask values), preserves real bid/ask exactly as stored, no
+    collapsing to mid."""
+    rows: list[dict] = []
+    with ZipFile(path) as archive:
+        member = archive.namelist()[0]
+        with archive.open(member) as handle:
+            text = handle.read().decode("utf-8")
+
+    for line in text.splitlines():
+        if not line.strip():
+            continue
+        (
+            date_field, bid_open, bid_high, bid_low, bid_close, bid_volume,
+            ask_open, ask_high, ask_low, ask_close, ask_volume,
+        ) = line.split(",")
+        row_date = datetime.strptime(date_field.split()[0], "%Y%m%d").date()
+        rows.append(
+            {
+                "date": row_date,
+                "bid_open": _numeric(bid_open), "bid_high": _numeric(bid_high),
+                "bid_low": _numeric(bid_low), "bid_close": _numeric(bid_close),
+                "bid_volume": _numeric(bid_volume),
+                "ask_open": _numeric(ask_open), "ask_high": _numeric(ask_high),
+                "ask_low": _numeric(ask_low), "ask_close": _numeric(ask_close),
+                "ask_volume": _numeric(ask_volume),
+            }
+        )
+    return rows
+
+
+def write_lean_forex_zip(output_zip: Path, ticker: str, new_ohlcv_rows: list[dict], *, merge_with_existing: bool = True) -> None:
+    """Forex sibling of write_lean_zip() — same call signature (plain
+    5-field OHLCV rows, the exact shape fetch_adhoc_asset() already
+    produces via scale_for_lean()), so data_pipeline/fetch.py's
+    ASSET_CLASS_CONFIG write_fn swap needs no caller changes. Synthesizes
+    each NEW row via synthesize_forex_bid_ask_row(), merges by date
+    against _read_existing_lean_forex_rows() (existing REAL rows always
+    win — identical convention to write_lean_zip()), writes via
+    forex_rows_to_lean_csv()."""
+    merged_by_date: dict[date, dict] = {}
+    if merge_with_existing and output_zip.exists():
+        for row in _read_existing_lean_forex_rows(output_zip):
+            merged_by_date[row["date"]] = row
+
+    for row in new_ohlcv_rows:
+        merged_by_date.setdefault(row["date"], synthesize_forex_bid_ask_row(row))
+
+    csv_text = forex_rows_to_lean_csv(list(merged_by_date.values()))
+
+    output_zip.parent.mkdir(parents=True, exist_ok=True)
+    member_name = f"{ticker.lower()}.csv"
+    with ZipFile(output_zip, "w") as archive:
+        archive.writestr(member_name, csv_text)
+
+
+# ---------------------------------------------------------------------------
+# The only function that imports yfinance — deferred, mirrors
+# experience/redis_queue.py's deferred `import redis`.
+# ---------------------------------------------------------------------------
+
+
+def fetch_yahoo_ohlcv(symbol: str, start: str, end: str) -> list[dict]:
+    """Real dollar/crypto prices, unscaled. Returns [] on any failure or
+    empty response — never raises, so one bad symbol never aborts a
+    multi-asset run."""
+    try:
+        import yfinance as yf  # deferred — dev-only dependency, never in requirements.txt
+
+        # auto_adjust=True: Yahoo applies its own split/dividend adjustment
+        # before this ever reaches a Lean zip. This module today only ever
+        # backfills crypto gaps (no splits/dividends), but train.py reading
+        # its own equity Lean zips unadjusted was a real, separate bug (see
+        # train.py::apply_split_adjustments()/development/Problems.md) -
+        # this flag stays correct here so a future equity backfill (this
+        # module's docstring already anticipates non-crypto assets) doesn't
+        # reintroduce the same class of unadjusted-price corruption.
+        frame = yf.download(symbol, start=start, end=end, auto_adjust=True, progress=False)
+    except Exception as exc:
+        logger.warning("fetch_yahoo_ohlcv(%s): fetch failed — %s", symbol, exc)
+        return []
+
+    if frame is None or frame.empty:
+        logger.warning("fetch_yahoo_ohlcv(%s): no data returned for %s..%s", symbol, start, end)
+        return []
+
+    # Newer yfinance always returns MultiIndex columns (price field, ticker),
+    # even for a single-ticker download — `record["Open"]` on that shape
+    # returns a length-1 Series instead of a scalar, and `float(...)` on it
+    # only works today via a deprecated pandas fallback (FutureWarning: will
+    # raise TypeError in a future pandas). Flattening to the price-field
+    # level here keeps `record["Open"]` a plain scalar regardless of which
+    # yfinance/pandas version is installed.
+    if isinstance(frame.columns, pd.MultiIndex):
+        frame.columns = frame.columns.get_level_values(0)
+
+    # V5.4.7 (development/Problems.md #123): rate-limiting / delisted
+    # responses often return a NON-empty frame whose rows are all NaN -
+    # `float(record["Open"])` happily produced nan and write_lean_zip
+    # persisted it as genuine OHLCV. Rows without a finite OHLC set are
+    # now dropped; a frame that is ALL such rows degrades to [] (the same
+    # honest "no data" path as the empty-frame case above).
+    rows = []
+    skipped_non_finite = 0
+    for index, record in frame.iterrows():
+        row_date = index.date() if hasattr(index, "date") else index
+        try:
+            open_p = float(record["Open"])
+            high = float(record["High"])
+            low = float(record["Low"])
+            close_p = float(record["Close"])
+            volume = float(record["Volume"])
+        except (TypeError, ValueError, KeyError):
+            skipped_non_finite += 1
+            continue
+        if not all(math.isfinite(v) for v in (open_p, high, low, close_p)):
+            skipped_non_finite += 1
+            continue
+        rows.append(
+            {
+                "date": row_date,
+                "open": open_p,
+                "high": high,
+                "low": low,
+                "close": close_p,
+                "volume": volume,
+            }
+        )
+    if skipped_non_finite:
+        logger.warning(
+            "fetch_yahoo_ohlcv(%s): skipped %d non-finite row(s) from %s..%s",
+            symbol, skipped_non_finite, start, end,
+        )
+    return rows
+
+
+# ---------------------------------------------------------------------------
+# Orchestration
+# ---------------------------------------------------------------------------
+
+
+def plan_backfill(config: dict, *, tickers: list[str] | None = None) -> list[dict]:
+    """Orchestrates over config["phase1"]["universe"]["assets"] entries that
+    carry an optional "backfill" sub-block. Reads existing zip rows (if the
+    zip already exists) purely to compute the gap — no network I/O here."""
+    plans = []
+    for asset in config["phase1"]["universe"]["assets"]:
+        backfill_config = asset.get("backfill")
+        if not backfill_config:
+            continue
+        if tickers and asset["ticker"] not in tickers:
+            continue
+
+        output_zip = ROOT / asset["data_path"]
+        existing_rows = _read_existing_lean_rows(output_zip) if output_zip.exists() else []
+        gap = detect_gap(asset, existing_rows)
+
+        plans.append(
+            {
+                "ticker": asset["ticker"],
+                "security_type": asset["security_type"],
+                "yahoo_symbol": yahoo_symbol_for(asset["ticker"], backfill_config),
+                "data_path": str(output_zip),
+                "gap": gap,
+            }
+        )
+    return plans
+
+
+def run_backfill(config: dict, plan: list[dict], *, apply: bool, fetch_fn: Callable = fetch_yahoo_ohlcv) -> dict:
+    """apply=False (default): dry run — fetches nothing written to disk.
+    apply=True: writes merged zips via write_lean_zip(). fetch_fn is the
+    injection point for tests (never real yfinance in tests)."""
+    entries = []
+    for plan_entry in plan:
+        gap = plan_entry["gap"]
+        if not gap["needs_backfill"]:
+            entries.append({**plan_entry, "action": "skipped_no_gap", "rows_fetched": 0})
+            continue
+
+        # V5.4.7 (development/Problems.md #123): yf.download's `end` is
+        # EXCLUSIVE while backfill_to/fetch_end is inclusive - without the
+        # +1 day, the configured end date could never be fetched, so
+        # needs_backfill stayed True forever and every run refetched.
+        fetch_end_exclusive = gap["fetch_end"] + timedelta(days=1)
+        rows = fetch_fn(
+            plan_entry["yahoo_symbol"],
+            gap["fetch_start"].isoformat(),
+            fetch_end_exclusive.isoformat(),
+        )
+        scaled_rows = scale_for_lean(rows, plan_entry["security_type"])
+
+        if not scaled_rows:
+            action = "no_data_returned"
+        elif apply:
+            write_lean_zip(Path(plan_entry["data_path"]), plan_entry["ticker"], scaled_rows, merge_with_existing=True)
+            action = "written"
+        else:
+            action = "dry_run"
+
+        dates = [row["date"] for row in rows]
+        entries.append(
+            {
+                **plan_entry,
+                "action": action,
+                "rows_fetched": len(rows),
+                "suggested_available_from": min(dates) if dates else None,
+                "suggested_available_to": max(dates) if dates else None,
+            }
+        )
+    return {"apply": apply, "entries": entries}
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(name)s — %(message)s")
+    parser = argparse.ArgumentParser(
+        description="Aether Quant Yahoo Finance historical data backfill (V2-19.5) — "
+        "offline/manual only, never run inside Lean or a Docker worker."
+    )
+    parser.add_argument("--tickers", nargs="*", default=None, help="Restrict to these tickers (default: all assets with a 'backfill' block)")
+    parser.add_argument("--apply", action="store_true", help="Actually write zip files (default: dry run, report only)")
+    parser.add_argument("--config-path", type=Path, default=CONFIG_PATH)
+    args = parser.parse_args()
+
+    with args.config_path.open("r", encoding="utf-8") as f:
+        config = json.load(f)
+
+    plan = plan_backfill(config, tickers=args.tickers)
+    if not plan:
+        print("No assets with a 'backfill' config block found (nothing to do).")
+        return
+
+    report = run_backfill(config, plan, apply=args.apply)
+    print(f"{'APPLY' if args.apply else 'DRY RUN'} — {len(report['entries'])} asset(s) evaluated:\n")
+    for entry in report["entries"]:
+        print(f"- {entry['ticker']} ({entry['yahoo_symbol']}): {entry['action']}, rows_fetched={entry['rows_fetched']}")
+        if entry.get("suggested_available_from"):
+            print(
+                f"    If this widens coverage, update config.json manually: "
+                f"available_from={entry['suggested_available_from'].isoformat()}"
+            )
+
+    if not args.apply:
+        print("\nDry run only — no files were written. Re-run with --apply to write zip files.")
+    print(
+        "\nNote: config.json's available_from/available_to are never edited automatically. "
+        "Update them by hand for the wider history to actually affect training/backtesting."
+    )
+
+
+if __name__ == "__main__":
+    main()

evaluation/README.md

@@ -0,0 +1,152 @@
+# evaluation
+
+Offline, cost-aware evaluation of the cross-sectional rank book (V5.1
+Phase 0, development/Problems.md — the phase focused on model prediction
+performance). Answers the question nothing else in this codebase could:
+`train.py::compute_strategy_metrics()` simulates a long-only 1-day-direction
+strategy **gross of costs**, not the rank book, and not net of cost. This
+package turns "how good is this rank prediction" into "what would this have
+actually earned net of fees."
+
+Pure numpy/pandas — **deliberately no torch import**, so `performance/` and
+`retraining/` (and any future Postgres-fed monitoring job) can import it
+without pulling in the training stack, the same torch-free-core convention
+`train.py::_rank_ic_from_arrays()` established for its own metric.
+
+- `rank_book_simulator.py::simulate_rank_book(...)` — reuses the **exact**
+  selection/neutrality machinery `main.py`'s live decision path uses:
+  `portfolio.book_construction.build_rank_based_book()` (including its
+  hysteresis-aware sticky selection) and
+  `portfolio.book_neutrality.apply_book_neutrality()`. Per date: rebalance
+  on schedule, equal-weight each leg, neutralize, hold until the next
+  rebalance, accrue gross return and cost (`cost_bps_per_side +
+  commission_bps`, charged on turnover only at rebalance). Dates with fewer
+  than `min_universe_size` eligible rows are **skipped**, not zero-filled.
+- `rank_book_simulator.py::capacity_curve(...)` — sweeps `top_n` (breadth
+  check: is the edge concentrated in a handful of names, or genuinely
+  spread across the cross-section?) and estimates a rough capacity ceiling
+  from the lowest-average-dollar-volume held name.
+- `rank_book_simulator.py::stress_test_costs(...)` — re-runs the simulation
+  at 1×/2×/3× the configured cost, answering "does the edge survive if
+  real-world costs turn out higher than calibrated."
+- `rank_book_simulator.py::summarize_metric_stability(...)` — cross-window
+  sign-flip-fraction + bootstrap-CI summary (used by Phase 4's walk-forward
+  evaluation and Phase 5's ablation harness). Duplicates the ~12-line
+  bootstrap from `train.py::bootstrap_ic_confidence_interval()` rather than
+  importing it, for the same torch-free reason above.
+- `model_predictions.py` — runs every dataset row through
+  `inference/exported_model.py` (the **same** torch-free interpreter
+  `main.py`'s live decision path uses) to produce a predicted-`<head>`
+  column, so every number this package reports is the offline mirror of
+  live behavior, not a separately re-derived approximation. Includes a
+  torch-free port of `train.py::build_sequence_tensor_dataset()`
+  (`build_sequence_windows()`), cross-validated against the original in
+  `tests/test_model_predictions.py`.
+- `ablation.py::run_ablation(...)` — isolates the contribution of
+  neutrality/hysteresis/cost-model by re-running the simulation with each
+  turned off in turn. Runtime-only mechanisms with no offline equivalent
+  (gating, topology sizing) report an honest `not_offline_measurable`
+  sentinel instead of a fabricated number.
+- `rank_signal_calibration.py` — `calibrate_book_confidence_spread()`
+  (derives `min_rank_confidence_spread` from real per-date score
+  dispersion); `reconcile_book_history_date()`/
+  `replay_book_history_reconciliation()`/
+  `summarize_book_history_reconciliation()` (compares a real Lean
+  backtest's logged book selections against a fresh offline
+  re-derivation — independent or hysteresis-replayed); `summarize_book_member_diversion()`
+  (aggregates each book member's final action/reasons, V5.2.6).
+- `confidence_threshold_calibration.py` — derives `min_confidence_to_trade`
+  from the real confidence-vs-forward-return relationship, same
+  percentile-of-a-real-distribution discipline as the book-spread
+  calibration above.
+- `kill_switch_replay.py::replay_kill_switch_over_dataset(...)`/
+  `summarize_kill_switch_replay(...)` (V5.2.8) — a day-by-day offline
+  replay of the kill-switch + sticky trade-lock state machine against the
+  rank book's own return series. Explicitly approximate (see its own
+  module docstring): no bypass flags, no `net_edge`/book-selection
+  modeling, only the two dataset-derivable `evaluate_kill_switch()`
+  inputs plus the drawdown-lock breach.
+- `limit_fill_simulator.py::simulate_limit_fills(...)`/
+  `sweep_limit_fill_offsets(...)` (V5.3.1) — an offline counterfactual
+  estimate of how often a real limit order would fill vs. time out,
+  reusing `execution/order_gate.py::resolve_limit_price()` against the
+  dataset's own high/low bars. Answers a different question than the real
+  order-events evidence (development/Problems.md #34/#96): "would this
+  signal have filled," not "did the real book's actual orders fill."
+- `feature_reconciliation.py::reconcile_feature_snapshot(...)`/
+  `summarize_feature_reconciliation(...)` (V5.3.5.3, Problems.md #91/#100)
+  — diffs ONE symbol's logged live feature values (book_history.jsonl's
+  allowlist-bounded `feature_snapshot` field) against full_dataset.csv's
+  same (ticker, date) rows: per-feature deltas, tolerance-gated
+  (abs AND rel), NaN-degrading, worst offenders aggregated first. Pure
+  diff core only — the CLI (`aq evaluate --reconcile-features --symbol
+  XOM`) owns all I/O and joins.
+- `monte_carlo.py::run_monte_carlo(...)` (V5.3.8) — stationary-block (or
+  i.i.d.) bootstrap of the offline rank book's daily NET returns into N
+  alternative equity histories: per-run curves, red average curve,
+  return/Sharpe/maxDD percentile distributions, loss probability.
+  Deterministic given seed; pure numpy core — the CLI
+  (`aq evaluate --rank-book --monte-carlo`) owns inference + persistence +
+  README chart/section refresh.
+- `benchmark_comparison.py` (V5.4.3) — naive strategy baselines
+  (momentum top-N / mean-reversion / random-entry) on the same dataset
+  and window as the rank book, so the model's edge is stated relative to
+  simple benchmarks rather than in isolation. V5.4.4 added
+  `close_pivot_from_frame()` (long-format dataset frame → the
+  (dates × tickers) close pivot every baseline consumes) and
+  `run_all_baselines()` (all five baselines into one report dict), plus a
+  real return accrual for the mean-reversion baseline (it previously
+  accrued a hardcoded placeholder, so its Sharpe was structurally 0.0).
+- `public_benchmarks.py` (V5.4.4) — well-known PUBLIC benchmark
+  baselines computed from the universe's own index/bond proxy columns:
+  `compute_sp500_baseline()` (buy-and-hold SPY) and
+  `compute_60_40_baseline()` (60% SPY / 40% TLT, daily rebalanced).
+  Same `close_pivot` input, same Sharpe formula, and same output shape
+  as the strategy baselines above (plus a `status` field — a universe
+  without SPY/TLT degrades to `SKIPPED`, never a crash). Zero new data
+  dependencies.
+
+Both modules are surfaced end-to-end by `aq evaluate --benchmarks`
+(included in `--all`): the CLI writes
+`ml/evaluation/benchmark_comparison.json`, the README's Benchmark
+Comparison section auto-refreshes from it, and the webui's Evaluation tab
+renders it via `/api/evaluation`'s `benchmarks` key (BenchmarkPanel).
+
+## CLI
+
+`aq evaluate` (see the root README's CLI Reference for full flag
+descriptions):
+
+- Simulation: `--rank-book`, `--capacity`, `--stress`, `--all` (bundles
+  the three plus `--calibrate-edge` and `--benchmarks`)
+- Benchmarks (V5.4.4): `--benchmarks` (strategy + public baselines,
+  README section + webui panel refresh)
+- Calibration: `--calibrate-edge`, `--calibrate-book-spread`,
+  `--calibrate-confidence-threshold`
+- Reconciliation: `--reconcile-book-history`, `--replay-hysteresis`,
+  `--reconcile-features` (V5.3.5.3, requires `--symbol`)
+- Monte Carlo (V5.3.8): `--rank-book --monte-carlo`
+  (`--mc-runs/--mc-block-size/--mc-seed/--mc-method`)
+- Diagnostics/investigation (not in `--all`): `--ablation`,
+  `--replay-kill-switch` (V5.2.8), `--simulate-limit-fills` (V5.3.1,
+  `--limit-fill-offset-sweep`), `--walk-forward-summary`
+
+Writes `ml/evaluation/*.json`, consumed by `monitoring/evaluation_state.py`
+for the webui's Evaluation tab (`/api/evaluation`).
+
+## Config
+
+`phase1.target.ranking.net_performance` (book/cost parameters) and
+`phase_v2.costs` (the entry-decision net-edge gate, `execution/cost_model.py`
+— off by default until calibrated via `aq evaluate --calibrate-edge`).
+
+## Known finding (development/Problems.md)
+
+Running `aq evaluate --rank-book` against the live-trained artifacts during
+development surfaced, in real predictions, the compression this repo's own
+Problems.md documents: `rank_20d` predictions clustered in roughly
+`[0.5, 0.7]` instead of spanning `[0, 1]` — direct evidence of the rank
+heads' sigmoid-at-inference/raw-at-training mismatch. `IC` is invariant
+under any monotone transform, which is exactly why no rank-IC-based gate
+ever caught it; this package's net-Sharpe simulation is sensitive to the
+compressed dispersion in a way IC is not.