aether-quant 0.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. aether_quant-0.0.1.dist-info/METADATA +7 -0
  2. aether_quant-0.0.1.dist-info/RECORD +99 -0
  3. aether_quant-0.0.1.dist-info/WHEEL +5 -0
  4. aether_quant-0.0.1.dist-info/entry_points.txt +2 -0
  5. aether_quant-0.0.1.dist-info/licenses/LICENSE +133 -0
  6. aether_quant-0.0.1.dist-info/top_level.txt +13 -0
  7. analyzer/README.md +69 -0
  8. analyzer/__init__.py +17 -0
  9. analyzer/market_analyzer.py +521 -0
  10. aq_cli.py +3633 -0
  11. audit/README.md +47 -0
  12. audit/__init__.py +38 -0
  13. audit/hash_chain.py +52 -0
  14. audit/postgres_audit.py +61 -0
  15. audit/postgres_worker.py +402 -0
  16. audit/redis_queue.py +124 -0
  17. audit/status_export.py +62 -0
  18. data_pipeline/README.md +257 -0
  19. data_pipeline/__init__.py +6 -0
  20. data_pipeline/bar_synthesis.py +97 -0
  21. data_pipeline/dividend_backfill.py +243 -0
  22. data_pipeline/factor_file_backfill.py +276 -0
  23. data_pipeline/fetch.py +206 -0
  24. data_pipeline/fred_backfill.py +435 -0
  25. data_pipeline/ib_backfill.py +287 -0
  26. data_pipeline/v2_manifest.py +75 -0
  27. data_pipeline/yfinance_backfill.py +501 -0
  28. evaluation/README.md +152 -0
  29. evaluation/__init__.py +73 -0
  30. evaluation/ablation.py +310 -0
  31. evaluation/benchmark_comparison.py +195 -0
  32. evaluation/confidence_threshold_calibration.py +157 -0
  33. evaluation/factor_neutralization_check.py +94 -0
  34. evaluation/feature_parity.py +321 -0
  35. evaluation/feature_reconciliation.py +286 -0
  36. evaluation/impact_model.py +77 -0
  37. evaluation/kill_switch_replay.py +186 -0
  38. evaluation/limit_fill_simulator.py +152 -0
  39. evaluation/model_predictions.py +192 -0
  40. evaluation/monte_carlo.py +161 -0
  41. evaluation/public_benchmarks.py +117 -0
  42. evaluation/rank_book_simulator.py +494 -0
  43. evaluation/rank_ic_core.py +204 -0
  44. evaluation/rank_signal_calibration.py +690 -0
  45. evaluation/rolling_ic_gate_calibration.py +190 -0
  46. evaluation/rolling_ic_gate_replay.py +138 -0
  47. execution/README.md +281 -0
  48. execution/__init__.py +80 -0
  49. execution/config_cache.py +48 -0
  50. execution/cost_model.py +213 -0
  51. execution/lean_config_render.py +131 -0
  52. execution/live_credentials.py +38 -0
  53. execution/live_credentials_io.py +52 -0
  54. execution/order_gate.py +388 -0
  55. execution/paper_readiness.py +181 -0
  56. execution/paper_readiness_io.py +54 -0
  57. execution/paper_readiness_report.py +103 -0
  58. execution/paper_readiness_scheduler.py +137 -0
  59. execution/reconciliation.py +160 -0
  60. execution/runtime_config_io.py +38 -0
  61. execution/secret_scan.py +73 -0
  62. features/README.md +77 -0
  63. features/__init__.py +137 -0
  64. features/alt_data_features.py +154 -0
  65. features/bond_features.py +275 -0
  66. features/cross_asset_sensitivity.py +79 -0
  67. features/derivatives_macro_features.py +72 -0
  68. features/macro_features.py +79 -0
  69. features/options_greeks.py +329 -0
  70. features/sector_map.py +53 -0
  71. features/technical_indicators.py +185 -0
  72. generate_backtest_report.py +311 -0
  73. generate_evaluation_report.py +712 -0
  74. inference/README.md +105 -0
  75. inference/__init__.py +36 -0
  76. inference/exported_model.py +929 -0
  77. inference/parallel_inference.py +160 -0
  78. inference/strategy_selector_inference.py +75 -0
  79. json_safety.py +130 -0
  80. portfolio/README.md +447 -0
  81. portfolio/__init__.py +41 -0
  82. portfolio/book_construction.py +786 -0
  83. portfolio/book_neutrality.py +178 -0
  84. portfolio/hrp_allocation.py +159 -0
  85. portfolio/options_arbitrage_detector.py +232 -0
  86. portfolio/options_assignment_risk.py +119 -0
  87. portfolio/options_margin_sizing.py +333 -0
  88. portfolio/options_strategy.py +1999 -0
  89. portfolio/rank_signal.py +219 -0
  90. portfolio/rolling_ic_gate.py +183 -0
  91. risk/README.md +275 -0
  92. risk/__init__.py +38 -0
  93. risk/asset_class_router.py +584 -0
  94. risk/forex_risk.py +158 -0
  95. risk/futures_risk.py +202 -0
  96. risk/kill_switch.py +261 -0
  97. risk/manual_override.py +118 -0
  98. risk/position_sizing.py +303 -0
  99. risk/rl_sizing.py +189 -0
@@ -0,0 +1,190 @@
1
+ """Calibrates `phase_v2.rolling_ic_gate.min_rolling_mean_ic` from real data
2
+ (V5.3.5, development/Problems.md #102) - the same "derive the number,
3
+ don't guess it" discipline `aq evaluate --calibrate-book-spread` already
4
+ established for `min_rank_confidence_spread`, applied to this round's new
5
+ gate so its shipped floor is never a hand-guessed constant either.
6
+
7
+ Deliberately reuses, never re-derives: `portfolio.rolling_ic_gate.
8
+ compute_rolling_ic_state()` (the exact aggregation the live gate and
9
+ `evaluation/rolling_ic_gate_replay.py` both call) and `evaluation.
10
+ rank_ic_core.resolve_realized_rank_ic_observations()` beneath it. A
11
+ calibrated floor computed here can never silently disagree with what the
12
+ live gate means by "rolling IC," because it is the same code, not a
13
+ parallel approximation.
14
+
15
+ WALK-FORWARD, NOT A SINGLE FULL-HISTORY READING: naively calling
16
+ `compute_rolling_ic_state()` once on the dataset's entire event history
17
+ would let observations whose resolution only became known LATE in the
18
+ dataset leak into a rolling-window reading nominally "as of" an EARLIER
19
+ sample date - a real lookahead bug, since `resolve_realized_rank_ic_observations()`
20
+ resolves every observation using the full buffer's own future close
21
+ prices, not bounded to any particular "as of" date. This module avoids
22
+ that by sampling a strided sequence of dates and, at each one, slicing
23
+ the event buffer to only events dated on-or-before that sample date
24
+ before calling `compute_rolling_ic_state()` - exactly what a live buffer
25
+ would contain by that date, never more. `evaluation/rolling_ic_gate_replay.py`
26
+ shares this same buffer-slicing discipline (see that module's own
27
+ docstring) since it needs the identical no-lookahead guarantee for a
28
+ different purpose (a per-date engagement decision instead of a
29
+ calibration distribution).
30
+
31
+ `sample_stride_days=5` (not every single date) keeps this an O(num_samples
32
+ x average_buffer_size) offline computation rather than O(num_dates^2) -
33
+ acceptable for a tool run once, by hand, never on any per-bar live path.
34
+ """
35
+
36
+ from __future__ import annotations
37
+
38
+ import bisect
39
+
40
+ import numpy as np
41
+ import pandas as pd
42
+
43
+ from portfolio.rolling_ic_gate import compute_rolling_ic_state
44
+
45
+ _ROLLING_IC_DISTRIBUTION_PERCENTILES = {"p10": 0.10, "p25": 0.25, "median": 0.50, "p75": 0.75}
46
+
47
+ # Same sentinel value as portfolio.rolling_ic_gate's own (private,
48
+ # module-local) _NEVER_BELOW - kept as an independent local copy rather
49
+ # than a cross-module import of a private name, matching how
50
+ # risk/kill_switch.py's own _NEVER_BELOW is never imported elsewhere
51
+ # either. Only meaningful as "the gate's own never-trips floor value";
52
+ # never compared against the other module's copy directly.
53
+ _NEVER_BELOW = -1e12
54
+
55
+
56
+ def build_event_buffer(
57
+ dataset: pd.DataFrame,
58
+ *,
59
+ raw_score_column: str,
60
+ ticker_column: str = "ticker",
61
+ date_column: str = "date",
62
+ close_column: str = "close",
63
+ ) -> list[dict]:
64
+ """Converts `dataset` into the flat, date-sorted event-dict shape
65
+ `compute_rolling_ic_state()`/`resolve_realized_rank_ic_observations()`
66
+ expect - the offline equivalent of main.py's Pass 1c buffer append,
67
+ reused by both this module and `evaluation/rolling_ic_gate_replay.py`
68
+ so the two tools can never disagree about what an "event" is. Rows
69
+ missing either the raw score or the close price are skipped (mirrors
70
+ `resolve_realized_rank_ic_observations()`'s own "model still warming
71
+ up" skip contract), never fabricated."""
72
+ ordered = dataset.sort_values(date_column, kind="stable")
73
+ events: list[dict] = []
74
+ for ticker, date, score, close in zip(
75
+ ordered[ticker_column], ordered[date_column], ordered[raw_score_column], ordered[close_column]
76
+ ):
77
+ if score is None or (isinstance(score, float) and np.isnan(score)):
78
+ continue
79
+ if close is None or (isinstance(close, float) and np.isnan(close)):
80
+ continue
81
+ events.append(
82
+ {
83
+ "ticker": str(ticker),
84
+ "created_at": f"{date}T00:00:00Z",
85
+ "resolved_predicted_rank_20d": float(score),
86
+ "close_price": float(close),
87
+ }
88
+ )
89
+ return events
90
+
91
+
92
+ def calibrate_rolling_ic_floor(
93
+ dataset: pd.DataFrame,
94
+ *,
95
+ raw_score_column: str,
96
+ ticker_column: str = "ticker",
97
+ date_column: str = "date",
98
+ close_column: str = "close",
99
+ horizon_days: int,
100
+ rolling_window_days: int,
101
+ percentile: float = 0.10,
102
+ sample_stride_days: int = 5,
103
+ min_names_per_date: int = 10,
104
+ ) -> dict:
105
+ """Walk-forward: at every `sample_stride_days`-th unique date in
106
+ `dataset`, computes the rolling IC state a live buffer would have had
107
+ by that date (event buffer sliced to <= that date, via
108
+ `build_event_buffer()` + `compute_rolling_ic_state()`), collects every
109
+ non-None `rolling_mean_ic` reading into a distribution, and returns
110
+ the `percentile`-th quantile as the calibrated floor.
111
+
112
+ Sample dates before enough history has accumulated (compute_rolling_ic_state()
113
+ returns `rolling_mean_ic=None`) are EXCLUDED from the distribution, not
114
+ counted as a 0.0 reading - a cold-start gap is missing data, not
115
+ evidence of zero skill.
116
+
117
+ `min_names_per_date` (V5.3.5, development/Problems.md #102) - passed
118
+ through to `compute_rolling_ic_state()`. Defaults to 10, well above
119
+ `compute_rolling_ic_state()`'s own pure-function default of 2: a real
120
+ run against this project's historical dataset found the p10-percentile
121
+ floor dominated by spurious +-1.0 readings from origin dates where
122
+ only 2-3 names had resolved (thin-universe/model-warmup dates,
123
+ mathematically forced to an extreme correlation regardless of real
124
+ skill) - excluding them here is what makes the resulting distribution
125
+ represent genuine cross-sectional skill rather than early-history
126
+ noise. See evaluation.rank_ic_core.rank_ic_from_arrays()'s own
127
+ docstring for the full mechanism.
128
+
129
+ Returns:
130
+ {"calibrated_min_rolling_mean_ic": float,
131
+ "percentile": float,
132
+ "num_samples_used": int,
133
+ "num_samples_skipped_insufficient_history": int,
134
+ "rolling_ic_distribution": {"min", "p10", "p25", "median", "p75", "max"}}
135
+
136
+ An empty/all-thin dataset returns calibrated_min_rolling_mean_ic=_NEVER_BELOW
137
+ (portfolio.rolling_ic_gate's own "gate never trips" sentinel) and an
138
+ all-None distribution, never raises."""
139
+ events = build_event_buffer(
140
+ dataset, raw_score_column=raw_score_column, ticker_column=ticker_column,
141
+ date_column=date_column, close_column=close_column,
142
+ )
143
+ if not events:
144
+ return {
145
+ "calibrated_min_rolling_mean_ic": _NEVER_BELOW,
146
+ "percentile": percentile,
147
+ "num_samples_used": 0,
148
+ "num_samples_skipped_insufficient_history": 0,
149
+ "rolling_ic_distribution": {"min": None, "p10": None, "p25": None, "median": None, "p75": None, "max": None},
150
+ }
151
+
152
+ event_dates = [str(event["created_at"])[:10] for event in events]
153
+ unique_dates = sorted(set(event_dates))
154
+ sample_dates = unique_dates[::sample_stride_days] if sample_stride_days > 0 else unique_dates
155
+
156
+ readings: list[float] = []
157
+ num_samples_skipped_insufficient_history = 0
158
+ for sample_date in sample_dates:
159
+ cutoff_index = bisect.bisect_right(event_dates, sample_date)
160
+ buffer_up_to_date = events[:cutoff_index]
161
+ state = compute_rolling_ic_state(
162
+ buffer_up_to_date, horizon_days=horizon_days, rolling_window_days=rolling_window_days,
163
+ min_names_per_date=min_names_per_date,
164
+ )
165
+ if state["rolling_mean_ic"] is None:
166
+ num_samples_skipped_insufficient_history += 1
167
+ continue
168
+ readings.append(state["rolling_mean_ic"])
169
+
170
+ if not readings:
171
+ return {
172
+ "calibrated_min_rolling_mean_ic": _NEVER_BELOW,
173
+ "percentile": percentile,
174
+ "num_samples_used": 0,
175
+ "num_samples_skipped_insufficient_history": num_samples_skipped_insufficient_history,
176
+ "rolling_ic_distribution": {"min": None, "p10": None, "p25": None, "median": None, "p75": None, "max": None},
177
+ }
178
+
179
+ readings_array = np.array(readings, dtype=np.float64)
180
+ distribution = {"min": float(np.min(readings_array)), "max": float(np.max(readings_array))}
181
+ for name, quantile in _ROLLING_IC_DISTRIBUTION_PERCENTILES.items():
182
+ distribution[name] = float(np.quantile(readings_array, quantile))
183
+
184
+ return {
185
+ "calibrated_min_rolling_mean_ic": float(np.quantile(readings_array, percentile)),
186
+ "percentile": percentile,
187
+ "num_samples_used": len(readings),
188
+ "num_samples_skipped_insufficient_history": num_samples_skipped_insufficient_history,
189
+ "rolling_ic_distribution": distribution,
190
+ }
@@ -0,0 +1,138 @@
1
+ """Day-by-day OFFLINE replay of `portfolio.rolling_ic_gate`'s two decision
2
+ functions against a historical dataset (V5.3.5, development/Problems.md
3
+ #102) - the direct sibling of `evaluation/kill_switch_replay.py`'s
4
+ day-by-day, no-lookahead, walk-forward structure, for this round's new
5
+ rolling-IC gate instead of the kill switch.
6
+
7
+ This is the critical pre-`main.py` checkpoint the V5.3.5 plan calls out:
8
+ run this against the historical dataset with `evaluation/
9
+ rolling_ic_gate_calibration.py`'s calibrated floor and confirm
10
+ disengagement concentrates in the three known bad eras (Apr-Sep 2019,
11
+ Dec 2019-Mar 2020, Jun-Sep 2020) rather than spreading uniformly across
12
+ the whole run - entirely offline, before `main.py` is touched at all. A
13
+ uniform reduction would mean this gate is just a redundant second
14
+ dispersion floor, not a genuine skill signal, and is the signal to stop
15
+ and revisit before A6 wires anything into the live path.
16
+
17
+ NO-LOOKAHEAD DISCIPLINE - the single most important property this module
18
+ has to get right: at each rebalance date, the event buffer passed to
19
+ `compute_rolling_ic_state()` is built from `evaluation.
20
+ rolling_ic_gate_calibration.build_event_buffer()` and then sliced to only
21
+ events dated on-or-before that date (the same technique, and the same
22
+ reason, that module's own docstring explains) - a decision "as of" date D
23
+ must never see a row dated after D, exactly matching what main.py's own
24
+ live in-memory buffer could possibly contain by that point in a real run.
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ import bisect
30
+
31
+ from evaluation.rolling_ic_gate_calibration import build_event_buffer
32
+ from portfolio.rolling_ic_gate import compute_rolling_ic_state, evaluate_rolling_ic_gate
33
+
34
+ # development/Problems.md #102's own three named bad eras, found from this
35
+ # round's research into rolling IC vs. the model's per-era IC diagnostic
36
+ # (#71) - used only by summarize_rolling_ic_gate_replay()'s per-era
37
+ # breakdown, so the offline report can be read directly against them
38
+ # without a throwaway script re-deriving these boundaries by hand.
39
+ KNOWN_ERAS = {
40
+ "era_0_good": ("2019-01-01", "2019-04-01"),
41
+ "era_1_bad_apr_sep_2019": ("2019-04-01", "2019-09-01"),
42
+ "era_2_bad_dec2019_mar2020": ("2019-12-01", "2020-03-01"),
43
+ "era_3_bad_jun_sep_2020": ("2020-06-01", "2020-09-01"),
44
+ }
45
+
46
+
47
+ def replay_rolling_ic_gate_over_dataset(
48
+ dataset,
49
+ *,
50
+ raw_score_column: str,
51
+ ticker_column: str = "ticker",
52
+ date_column: str = "date",
53
+ close_column: str = "close",
54
+ rebalance_dates: list[str],
55
+ horizon_days: int,
56
+ rolling_window_days: int,
57
+ gate_config: dict,
58
+ min_names_per_date: int = 10,
59
+ ) -> list[dict]:
60
+ """Builds the full event buffer once (`build_event_buffer()`), then for
61
+ each date in `rebalance_dates` (must already be sorted - callers own
62
+ that, same convention as `rank_book_simulator.py`'s unique_dates loop;
63
+ should be the SAME cadence a real book rebalance uses, not necessarily
64
+ every calendar date, matching main.py's own gate-is-only-consulted-on-
65
+ rebalance-bars design) slices the buffer to events dated <= that date
66
+ and evaluates the gate exactly as `portfolio.book_construction.
67
+ _select_book_group()` would.
68
+
69
+ `min_names_per_date` (V5.3.5, development/Problems.md #102) - passed
70
+ through to `compute_rolling_ic_state()`; defaults to 10 for the same
71
+ reason `evaluation/rolling_ic_gate_calibration.py::
72
+ calibrate_rolling_ic_floor()` does (see that function's own
73
+ docstring) - a real replay run at this module's own default of 2
74
+ showed the calibrated floor barely engaging during two of three known
75
+ historically-bad eras, traced to thin-universe origin dates forcing
76
+ spurious +-1.0 IC readings into the rolling mean.
77
+
78
+ Returns one dict per rebalance date: {"date", "engaged", "reason",
79
+ "observed_rolling_mean_ic", "min_rolling_mean_ic", "num_resolved_dates"}
80
+ - `evaluate_rolling_ic_gate()`'s own result dict plus "date"."""
81
+ events = build_event_buffer(
82
+ dataset, raw_score_column=raw_score_column, ticker_column=ticker_column,
83
+ date_column=date_column, close_column=close_column,
84
+ )
85
+ event_dates = [str(event["created_at"])[:10] for event in events]
86
+
87
+ records = []
88
+ for date in rebalance_dates:
89
+ cutoff_index = bisect.bisect_right(event_dates, str(date))
90
+ buffer_up_to_date = events[:cutoff_index]
91
+ state = compute_rolling_ic_state(
92
+ buffer_up_to_date, horizon_days=horizon_days, rolling_window_days=rolling_window_days,
93
+ min_names_per_date=min_names_per_date,
94
+ )
95
+ result = evaluate_rolling_ic_gate(state, gate_config)
96
+ records.append({"date": str(date), **result})
97
+
98
+ return records
99
+
100
+
101
+ def _era_for_date(date: str) -> str | None:
102
+ for era_name, (start, end) in KNOWN_ERAS.items():
103
+ if start <= date < end:
104
+ return era_name
105
+ return None
106
+
107
+
108
+ def summarize_rolling_ic_gate_replay(records: list[dict]) -> dict:
109
+ """Aggregate engaged/disengaged fractions overall and per known era
110
+ (`KNOWN_ERAS` above), mirroring `evaluation/kill_switch_replay.py::
111
+ summarize_kill_switch_replay()`'s aggregation shape. Dates outside
112
+ every named era are still counted in `"overall"` but not attributed to
113
+ any `"by_era"` entry - `KNOWN_ERAS` deliberately doesn't cover the
114
+ whole historical window, only the four eras this round's research
115
+ already characterized."""
116
+ total_dates = len(records)
117
+ disengaged = [record for record in records if not record["engaged"]]
118
+ disengaged_by_floor = [record for record in records if record["reason"] == "rolling_ic_below_floor"]
119
+
120
+ by_era: dict[str, dict] = {}
121
+ for era_name in KNOWN_ERAS:
122
+ era_records = [record for record in records if _era_for_date(record["date"]) == era_name]
123
+ era_disengaged = [record for record in era_records if not record["engaged"]]
124
+ by_era[era_name] = {
125
+ "total_dates": len(era_records),
126
+ "disengaged_days": len(era_disengaged),
127
+ "disengaged_day_fraction": (len(era_disengaged) / len(era_records)) if era_records else None,
128
+ }
129
+
130
+ return {
131
+ "overall": {
132
+ "total_dates": total_dates,
133
+ "disengaged_days": len(disengaged),
134
+ "disengaged_day_fraction": (len(disengaged) / total_dates) if total_dates else 0.0,
135
+ "disengaged_days_below_floor": len(disengaged_by_floor),
136
+ },
137
+ "by_era": by_era,
138
+ }
execution/README.md ADDED
@@ -0,0 +1,281 @@
1
+ # execution
2
+
3
+ Pure, Lean-free order gating, cost/slippage math, and paper/live readiness
4
+ checks shared between `main.py` and the test suite. Nothing here imports
5
+ `AlgorithmImports`/`QCAlgorithm` — every module is unit-testable without a
6
+ Lean runtime; `main.py` is the only place that touches Lean's runtime types
7
+ and wires these modules to it.
8
+
9
+ ## Core order gating (`order_gate.py`)
10
+
11
+ - `resolve_runtime_mode(raw_mode)` — normalizes `phase_v2.runtime.mode`,
12
+ failing safe to `"observation"`. Valid modes: `backtest`, `observation`,
13
+ `paper`, `live`.
14
+ - `resolve_order_permission(mode, allow_live_orders, broker_config_present,
15
+ risk_locks_healthy)` — the mode → real-vs-simulated order decision table.
16
+ `observation` always returns `False` regardless of other flags (the one
17
+ safety invariant this phase depends on); `backtest` always unrestricted;
18
+ `paper`/`live` need the matching flags AND healthy risk locks
19
+ (V5.4.5, Problems.md #116 — paper previously ignored the kill switch).
20
+ - `simulate_fill(close_price, target_weight, equity, slippage_bps=0.0)` —
21
+ hypothetical fill-price/quantity/notional math used by
22
+ `experience/simulated_portfolio.py`. `fill_price = close_price +
23
+ slippage_amount(...)`; quantity/notional = `target_weight * equity` at
24
+ that price. All-zero for non-positive `close_price`.
25
+ - `is_real_order_placement(execution_note, orders_allowed)` — classifies an
26
+ execution note as a genuine real order vs. simulated (`"simulated_"`
27
+ prefix) or a known no-op (denylists `_NO_OP_EXECUTION_NOTES` +
28
+ `_NO_OP_EXECUTION_NOTE_SUFFIXES`). Backs the real-order audit-log hook in
29
+ `on_data()`'s Pass 2.
30
+
31
+ ## Expected-net-edge cost model (`cost_model.py`)
32
+
33
+ Entry-decision side of cost-awareness (sibling to, not a replacement for,
34
+ the fill/pricing math below): does this trade's expected edge clear its
35
+ expected cost.
36
+
37
+ - `estimate_round_trip_cost_bps(liquidity_payload, *, commission_bps_per_side,
38
+ min_commission_usd, order_value, extra_slippage_bps)` — reads
39
+ `liquidity_payload["estimated_round_trip_cost"]`, **never recomputes
40
+ slippage**; adds a commission leg (bps of order value) covering BOTH
41
+ round-trip sides — per side = `max(rate leg, min_commission_usd floor)`
42
+ (V5.4.5, Problems.md #116 — one side was charged against a round-trip
43
+ contract) — plus an optional `extra_slippage_bps` buffer. Non-finite
44
+ estimates fail the gate closed with an explicit reason (#117).
45
+ - `expected_edge_bps(predicted_rank, *, edge_bps_per_rank_unit, holding_bars,
46
+ horizon_days, trade_direction=1)` — linear in rank deviation from the
47
+ median (0.5), scaled down when `holding_bars` < the rank head's forward
48
+ horizon. `trade_direction` (+1 long/-1 short) must be the sign of the
49
+ trade being evaluated — measures edge in the direction of the trade, not
50
+ just the long-side edge.
51
+ `None` prediction → `0.0`.
52
+ - `build_net_edge_decision(predicted_rank, liquidity_payload, order_value,
53
+ cost_config, *, trade_direction=1)` — consumed by
54
+ `analyzer/market_analyzer.py`'s Priority 6.5 tier and
55
+ `risk/position_sizing.py::cost_sizing_multiplier()`. **Fail-open,
56
+ always**: `passes=True` when the gate is disabled, `edge_bps_per_rank_unit`
57
+ is uncalibrated (`0.0`), or the rank prediction is missing. Config:
58
+ `phase_v2.costs` (`enabled: false` until calibrated via
59
+ `aq evaluate --calibrate-edge`).
60
+
61
+ ## Position reconciliation (`reconciliation.py`)
62
+
63
+ `reconcile_positions(expected_by_symbol, actual_by_symbol, *,
64
+ weight_tolerance, value_tolerance_usd, portfolio_value,
65
+ max_tolerated_drift=None) -> ReconciliationReport` — compares the book's
66
+ intended weights against what a broker (or simulated portfolio) actually
67
+ holds. Classifies each symbol `matched` (within both `weight_tolerance` and
68
+ `value_tolerance_usd`), `drifted` (outside tolerance), `orphan_broker`
69
+ (held, not in book) or `missing_broker` (in book, not held).
70
+ `max_abs_weight_drift` = largest drift among non-matched symbols;
71
+ `breach=True` past `max_tolerated_drift`. `main.py` calls it once per bar
72
+ (portfolio-book path); a breach feeds `risk/kill_switch.py`'s trigger
73
+ inputs, so it can actually stop trading, not just log.
74
+
75
+ ## Real fill slippage
76
+
77
+ `liquidity/market_liquidity.py`'s `estimated_round_trip_cost` was
78
+ sizing/routing input only; now wired into real and simulated fills too.
79
+
80
+ - `resolve_slippage_bps(symbol_key, slippage_bps_by_symbol, max_bps=
81
+ MAX_LIQUIDITY_SLIPPAGE_BPS)` — lookup + clamp. Missing symbol → `0.0`;
82
+ clamp default `MAX_LIQUIDITY_SLIPPAGE_BPS = 500.0` (5%, a guard against a
83
+ degenerate estimate — normal participation never approaches it).
84
+ - `slippage_amount(reference_price, slippage_bps)` — the one bps→price
85
+ formula in the codebase, shared by real and simulated fills.
86
+ - `resolve_fill_slippage(symbol_key, reference_price, slippage_bps_by_symbol,
87
+ max_bps=...)` — composes the two above; used by `main.py`'s real Lean
88
+ fill path.
89
+ - `liquidity_cost_fraction(liquidity_payload, source)` — picks
90
+ `estimated_round_trip_cost` vs `estimated_slippage` per config.
91
+ `resolve_fill_slippage_source(raw_source)` normalizes/fails-safe (same
92
+ pattern as `resolve_runtime_mode()`).
93
+
94
+ Config `phase_v2.liquidity.fill_slippage` (`main.py::_ensure_ready()`):
95
+ `source` (default `"round_trip"` = impact+spread combined — the default
96
+ because Lean's own fill model has no bid-ask awareness, so this is the only
97
+ place spread cost ever reaches a fill price; `"impact_only"` = impact
98
+ alone), `max_bps` (default `500.0`).
99
+
100
+ **Real Lean fills**: `_LiquidityAwareSlippageModel` (`main.py`, duck-typed
101
+ against Lean's `ISlippageModel.GetSlippageApproximation(asset, order)`) is
102
+ attached per-security via `security.SetSlippageModel(...)` in `_add_asset()`;
103
+ reads `self.latest_liquidity_slippage_bps` (refreshed every bar in
104
+ `on_data()` Pass 2) and delegates to `resolve_fill_slippage()`.
105
+ **Observation-mode fills**: `simulated_portfolio.py::enter_long()` takes
106
+ `slippage_bps: float = 0.0` threaded to `simulate_fill()`; every `main.py`
107
+ call site passes `resolve_slippage_bps(...)` so real and simulated fills
108
+ charge the identical estimate.
109
+
110
+ ## Real limit orders
111
+
112
+ Config-gated alternative to market orders (`phase_v2.limit_orders.enabled`):
113
+ the code default is `false` (a global kill switch — disabling it makes every
114
+ routing call site byte-for-byte identical to the plain market-order path),
115
+ but the shipped `config.json` turns it **on** for all 5 asset classes,
116
+ where it has been extensively exercised in real backtests since 2026-07-20
117
+ (development/Problems.md #34/#96: 45 real `order-events.json` files show
118
+ continuous limit-order activity, 2,370-4,103 fills per run in several).
119
+
120
+ **Casing convention**: this codebase calls the Lean API in **PascalCase**
121
+ (`self.MarketOrder`, `self.SetHoldings`, `self.SetSlippageModel`) but
122
+ overrides Lean's virtual callbacks in **snake_case** (`initialize`,
123
+ `on_data`). Limit-order code follows the same split:
124
+ PascalCase calls (`self.LimitOrder(...)`, `ticket.Cancel()`,
125
+ `OrderStatus.Filled`), snake_case override (`on_order_event`).
126
+
127
+ - `resolve_limit_price(reference_price, spread_fraction, is_buy,
128
+ offset_multiplier=1.0)` — reuses `liquidity_payload["spread_proxy"]`. Buy
129
+ limits below reference price, sell/short above, offset by half the
130
+ spread × `offset_multiplier`. Fails safe to the unchanged reference price
131
+ for non-positive price/spread.
132
+ - `classify_order_status(status_name)` — classifies into `"pending"` /
133
+ `"filled"` / `"canceled"` / `"unknown"` (unrecognized → `"unknown"`,
134
+ treated as pending). Backed by three tuples (one-line spelling fix if
135
+ Lean's real enum differs):
136
+ - `PENDING_ORDER_STATUS_NAMES` = `New`, `Submitted`, `PartiallyFilled`,
137
+ `UpdateSubmitted`, `CancelPending`
138
+ - `TERMINAL_FILLED_STATUS_NAMES` = `Filled`
139
+ - `TERMINAL_CANCELED_STATUS_NAMES` = `Canceled`, `Invalid`
140
+
141
+ All spellings verified against real `order-events.json` exports
142
+ (`CancelPending` appeared 23 times, 1:1 with confirmed unfilled-timeout
143
+ cancels).
144
+
145
+ Config `phase_v2.limit_orders` (`main.py::_ensure_ready()`): `enabled`
146
+ (default `false`, global kill switch), `asset_classes` (default all 5),
147
+ `offset_multiplier` (default `1.0`; `<1.0` more aggressive/likely to fill,
148
+ `>1.0` more passive), `unfilled_timeout_bars` (default `3`),
149
+ `fallback_to_market_on_timeout` — **per-asset-class dict**, not a single
150
+ bool (mirrors `exposure_caps_by_asset_class`): `true` for equity/crypto/bond
151
+ (fallback = what `SetHoldings` would've placed anyway), `false` for
152
+ future/option (a silent fallback fill is a real, model-unchosen position
153
+ under margin/expiry mechanics — safer to stay flat).
154
+
155
+ **Real Lean fills** (`main.py`): `_try_submit_limit_order()` — shared helper
156
+ called from every real-order branch in `_apply_signal()`/
157
+ `_apply_option_order()`; returns `False` immediately when disabled/asset
158
+ class not configured (caller's market-order call runs instead). Quantity
159
+ from the caller's already-computed
160
+ `_futures_contract_count_for_weight()`/`options_decision.contracts`, or
161
+ `self.CalculateOrderQuantity(symbol, target_weight)` for equity/crypto/bond.
162
+ `OrderTicket` tracked in `self.pending_limit_orders` (keyed by `str(symbol)`).
163
+ `_process_pending_limit_order_timeouts()` runs once per bar (right after
164
+ `_refresh_risk_state()`): cancels anything past `unfilled_timeout_bars`, and
165
+ per the fallback flag optionally places a real `MarketOrder()`.
166
+ `on_order_event(self, order_event)` is Lean's fill/cancel callback — maps
167
+ back to the `pending_limit_orders` entry via
168
+ `self.symbol_key_by_option_contract_symbol` for options (fires on the
169
+ contract symbol) or `str(order_event.Symbol)` otherwise; fill stamps
170
+ `last_trade_bar_by_symbol` and clears the entry, cancel just clears it.
171
+
172
+ **Cooldown-timing change (feature-on only)**: `last_trade_bar_by_symbol`
173
+ normally stamps at order-placement time; with limit orders enabled it
174
+ stamps at confirmed-fill time instead, so a flipped signal isn't blocked by
175
+ a cooldown for a trade that never happened. Disabled: no change. Risk: if
176
+ `on_order_event` never fires, the cooldown stamp is silently skipped.
177
+
178
+ **Observation-mode fills untouched** — `_try_submit_limit_order()` only
179
+ runs inside `if orders_allowed:`, unreachable from simulated `enter_long()`;
180
+ no fill-uncertainty modeling was added to `SimulatedPortfolioState`.
181
+
182
+ ## Config-read caching (`config_cache.py`)
183
+
184
+ `read_cached(config_path, loader)` — shared, mtime-gated cache used by
185
+ `paper_readiness_io.py::read_paper_trading_config()`,
186
+ `runtime_config_io.py::read_runtime_mode()`, and (outside this package)
187
+ `risk/manual_override.py::read_manual_trade_lock_override()`. Avoids
188
+ redundant `open()`+`json.load()` on every call while still picking up an
189
+ edit as soon as the file's mtime changes.
190
+
191
+ **Cache key is `(config_path, loader)`, not just `config_path`** — several
192
+ readers share `config.json` within the same bar
193
+ (`main.py::_refresh_risk_state()` calls the manual-override and
194
+ paper-trading readers back-to-back); a path-only cache let one reader's
195
+ value leak into another's result. See `development/Problems.md` #13,
196
+ `tests/test_config_cache.py::test_two_different_loaders_on_the_same_path_do_not_collide`.
197
+
198
+ ## Paper/live broker readiness
199
+
200
+ - `paper_readiness.py` (pure) — `evaluate_broker_config()` is the single
201
+ entrypoint `main.py` calls regardless of mode; dispatches to
202
+ `evaluate_paper_broker_config()` (Lean's built-in `PaperBrokerage`, no
203
+ real credentials — brokerage/live-data-provider/manual-review
204
+ attestation flags only) or `evaluate_live_broker_config()` (real
205
+ credentials + `evaluate_live_risk_posture()`). Also
206
+ `evaluate_observation_readiness()`, codifying
207
+ `development/infrastructure.md`'s readiness checklist.
208
+ - `paper_readiness_io.py` (IO) — mtime-cached `read_paper_trading_config()`
209
+ of `phase_v2.paper_trading`, plus `fetch_observation_mode_events()`
210
+ (first `mode='observation'`-filtered `experience_events` query).
211
+ - `paper_readiness_report.py` — offline report (`aq paper-readiness`,
212
+ `build_paper_readiness_view()`/`write_paper_readiness_file()`); writes
213
+ `visualization/grafana/paper_readiness_report.json` (`main.py` has no
214
+ Postgres connection to compute this itself).
215
+ - `live_credentials.py` (pure: `credentials_present()`,
216
+ `describe_missing_fields()`, `postgres_dsn_is_live_safe()`) +
217
+ `live_credentials_io.py` (IO: `load_live_credentials()`,
218
+ `load_postgres_dsn()`) — pre-flight validation for real broker
219
+ credentials (`ib_config.py` or `AETHER_IB_*` via `.env.live`). Does not
220
+ wire Lean itself — Lean reads `ib-*` fields directly from `lean.json`.
221
+ - `runtime_config_io.py::read_runtime_mode()` — mtime-cached read of
222
+ `phase_v2.runtime.mode`, used by `retraining/worker.py`'s
223
+ auto-promote-blocked-in-live-mode safety net (separate process from
224
+ `main.py`).
225
+
226
+ See the Paper Trading Readiness Contract (V2-21) and Live Deployment
227
+ Contract (V2-22) in `development/architecture.md` for the full picture.
228
+
229
+ ## Scheduled readiness reporting (`paper_readiness_scheduler.py`)
230
+
231
+ `PaperReadinessScheduler` — periodic loop around
232
+ `build_paper_readiness_view()`/`write_paper_readiness_file()`, so the
233
+ readiness report (already dashboard-visible via `monitoring/api_server.py`'s
234
+ `/api/state` merge + `get_paper_readiness()` endpoint) doesn't go stale
235
+ between manual `aq paper-readiness` runs. Mirrors
236
+ `performance/trigger_worker.py::TriggerWorker`: sync-only, DSN via
237
+ `AETHER_POSTGRES_DSN`, `--once` flag, `_pg_conn` injection for tests. Run as
238
+ its own process: `python -m execution.paper_readiness_scheduler
239
+ --poll-interval 3600` (not folded into `retraining/worker.py`'s loop —
240
+ different cadence). Purely additive — never touches
241
+ `phase_v2.paper_trading` config or order-routing behavior.
242
+
243
+ ## Secret handling (`secret_scan.py`, `lean_config_render.py`)
244
+
245
+ The tracked `lean.json` ships as the stock Lean template with every
246
+ brokerage/API-secret field empty; these keep it that way while still
247
+ letting live/paper deployment use real credentials.
248
+
249
+ - `secret_scan.py` — backs `aq secrets-check` / `.githooks/pre-commit`.
250
+ `find_populated_secret_fields(lean_config)` flags any field whose name
251
+ looks like a credential (`is_secret_field()`, suffix match on
252
+ `-api-key`/`-password`/etc. plus IB identity fields) and is non-empty.
253
+ `is_tracked_env_secret(filename)` flags a `.env`-style filename that
254
+ isn't a committed `*.example` template. Pure — only field names are ever
255
+ returned, never values.
256
+ - `lean_config_render.py` — Lean does not expand env vars inside
257
+ `lean.json` (read literally), so `render_lean_config()` (pure) overlays
258
+ real values from `.env.live`/`AETHER_*` env vars (`SECRET_ENV_MAP`) onto
259
+ the empty template; `write_rendered_config()` (IO) writes a gitignored
260
+ `lean.live.json` that live/paper deployment points Lean at via
261
+ `--lean-config`. Backtests use the plain `lean.json` untouched.
262
+ `load_env_file()`/`parse_env_file()` handle `.env.live` parsing.
263
+
264
+ ## Activating real paper-trading fills — manual step
265
+
266
+ Everything here today produces **synthetic** fills
267
+ (`order_gate.py::simulate_fill()`, via `simulated_portfolio.py`'s
268
+ `enter_long()`/`exit()`/`liquidate_all()`), never a real Lean
269
+ `PaperBrokerage` fill event. Switching the fill *source* to real fills is a
270
+ distinct, deliberately unbuilt follow-up ("Phase 7b") — the rest of the
271
+ pipeline (experience store, triggers, retraining, `rank_ic_monitor.py`)
272
+ needs no change when that happens.
273
+
274
+ The manual gate already exists as config, not code:
275
+ `paper_readiness.py::evaluate_paper_broker_config()` blocks activation
276
+ until a human sets, in `config.json`,
277
+ `phase_v2.paper_trading.live_data_provider_configured: true` and
278
+ `phase_v2.paper_trading.manual_review_confirmed: true`. Neither is touched
279
+ by any automated process — both stay `false` until a human flips them, and
280
+ `aq paper-readiness`/`PaperReadinessScheduler` keep reporting `ready: false`
281
+ (via `blocking_reasons`) until they do.