From 5d7d4fa3c6c88b3ecce4e13e6ac1a23c117a05be Mon Sep 17 00:00:00 2001
From: jgrusewski <jgrusewski@localhost>
Date: Fri, 15 May 2026 20:45:37 +0200
Subject: [PATCH] feat(phase-e-4-a): add mbp10_dir param to fxcache loader
 (signature-only)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase E.4.A Task 4: extend load_snapshots_from_fxcache with
`mbp10_dir: Option<&Path>`. When provided, the loader will peek
MBP-10 by timestamp and populate SnapshotRow.bid_l[1..10]/ask_l[1..10]
from real LOB depth — but the real-peek implementation lands in
Task 5 follow-on. This commit:
- introduces the parameter (callers pass None)
- warns at runtime if mbp10_dir Some until T5 lands
- enables downstream wiring of --use-real-depth + --mbp10-dir CLI
  flags in the smoke / backtest binaries

T5 deferred: on ES futures the --real-spread experiment showed 76%
of fxcache bars hit the 1-tick floor, so depth-from-MBP-10 likely
won't move the needle for ES. Higher-leverage work (Mamba2 wiring)
prioritised. T5 implementation reopens as a follow-on if E.4.A
gates pass with synthesised depth.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 crates/ml/examples/alpha_compose_backtest.rs |  1 +
 crates/ml/examples/alpha_dqn_h600_smoke.rs   |  1 +
 crates/ml/src/env/loaders.rs                 | 13 +++++++++++++
 3 files changed, 15 insertions(+)

diff --git a/crates/ml/examples/alpha_compose_backtest.rs b/crates/ml/examples/alpha_compose_backtest.rs
index f434a4a99..0c83b6552 100644
--- a/crates/ml/examples/alpha_compose_backtest.rs
+++ b/crates/ml/examples/alpha_compose_backtest.rs
@@ -382,6 +382,7 @@ fn main() -> Result<()> {
         cli.max_snapshots,
         Some(&alpha_cache),
         cli.real_spread,
+        None,  // E.4.A T4: mbp10_dir wiring + --use-real-depth flag lands in T5
     )?;
     let n_total = rows.len();
     info!("Loaded {} snapshots", n_total);
diff --git a/crates/ml/examples/alpha_dqn_h600_smoke.rs b/crates/ml/examples/alpha_dqn_h600_smoke.rs
index 919e94dbb..8bd1c6f1d 100644
--- a/crates/ml/examples/alpha_dqn_h600_smoke.rs
+++ b/crates/ml/examples/alpha_dqn_h600_smoke.rs
@@ -650,6 +650,7 @@ fn main() -> Result<()> {
                 cli.max_snapshots,
                 alpha_cache_vec.as_deref(),
                 cli.real_spread,
+                None,  // E.4.A T4: mbp10_dir wiring + --use-real-depth flag lands in T5
             )?
         }
         (None, Some(mbp10)) => {
diff --git a/crates/ml/src/env/loaders.rs b/crates/ml/src/env/loaders.rs
index 387a61109..99f96f90f 100644
--- a/crates/ml/src/env/loaders.rs
+++ b/crates/ml/src/env/loaders.rs
@@ -127,7 +127,20 @@ pub fn load_snapshots_from_fxcache(
     max_snapshots: usize,
     alpha_cache: Option<&[f32]>,
     use_real_spread: bool,
+    // Phase E.4.A.4: when Some, peek MBP-10 by timestamp to populate
+    // SnapshotRow.bid_l[1..10] / ask_l[1..10] from real LOB depth.
+    // When None, synthesize L2-L10 at ±tick offsets (current behaviour).
+    // This commit introduces the parameter; the real-peek implementation
+    // lands in Task 5 follow-on.
+    mbp10_dir: Option<&Path>,
 ) -> Result<Vec<SnapshotRow>> {
+    if mbp10_dir.is_some() {
+        warn!(
+            "fxcache loader: mbp10_dir provided but real-peek not yet \
+             implemented (Phase E.4.A Task 5 follow-on) — falling back \
+             to synthesised L2-L10 offsets"
+        );
+    }
     let reader = FxCacheReader::open(fxcache_path)
         .with_context(|| format!("open fxcache {}", fxcache_path.display()))?;
     let alpha_dim = reader