docs: Phase 13.22 + 3 bug fixes in PHASE_HISTORY, S5_4 test fix

PHASE_HISTORY.md: add Phase 13.22 (recursive read_tree), three bug
fix entries (draw_selection_alias, dtype_loss_subframe, draw_index_col).
Update test counts (1521 → 1538), pending items, overview metrics.

CAPABILITY_MATRIX.md: updated from test run (1538 passed).

test_S5_draw_index_col_collision.py: S5_4 uses deterministic fixture
(review P1-1 — random fixture could miss test point).

Author: miranov25

UTILS/dfextensions/AliasDataFrame/docs/CAPABILITY_MATRIX.md

@@ -1,23 +1,23 @@
 # Capability Matrix — AliasDataFrame
 
-**Generated:** 2026-04-12 11:11 UTC
+**Generated:** 2026-04-26 07:48 UTC
 **Phase:** 13.11.B
-**Taxonomy:** 41 features (PHASE_13_11_B approved)
+**Taxonomy:** 44 features (PHASE_13_11_B approved)
 **Generator:** `scripts/generate_capability_matrix.py` v2 (taxonomy-based)
 
 ## Summary
 
 | Status | Count | % |
 |--------|------:|--:|
-| ✅ Verified | 23 | 56% |
-| ☑️ Smoke-only | 14 | 34% |
-| 🧨 Broken | 3 | 7% |
+| ✅ Verified | 26 | 59% |
+| ☑️ Smoke-only | 14 | 31% |
+| 🧨 Broken | 3 | 6% |
 | 📋 Planned | 1 | 2% |
-| **Total features** | **41** | |
-| **Matched tests** | **1525** | |
-| **Invariance tests** | **114** | |
+| **Total features** | **44** | |
+| **Matched tests** | **1536** | |
+| **Invariance tests** | **125** | |
 
-**Unmatched tests:** 42 (not mapped to any feature)
+**Unmatched tests:** 88 (not mapped to any feature)
 
 ## CORE
 
@@ -60,6 +60,9 @@
 | ✅ | **FUNC.polynomial** — PolynomialSpec & register_polynomial_from_subframe | 20 | 20 | 0 | 3 |
 | ✅ | **FUNC.evaluator** — register_evaluator | 24 | 24 | 0 | 3 |
 | ✅ | **FUNC.persistence** — Function persistence through schema | 9 | 9 | 0 | 2 |
+| ✅ | **FUNC.regression_metadata** — Regression metadata registration & update | 4 | 4 | 0 | 4 |
+| ✅ | **FUNC.evaluator_from_metadata** — Bridge: metadata → evaluator binding | 6 | 6 | 0 | 6 |
+| ✅ | **FUNC.regression_persistence** — Regression metadata schema roundtrip | 1 | 1 | 0 | 1 |
 
 ## DRAWING
 
@@ -118,52 +121,52 @@
 ## 🧨 Broken Features — Details
 
 ### COMP.roundtrip
-- ❌ `test_invariance_compression.py::TestInvarianceCompression::test_I4_3_asinh_compression_roundtrip`
 - ❌ `test_invariance_compression.py::TestInvarianceCompression::test_I4_2_scaled_linear_compression_roundtrip`
+- ❌ `test_invariance_compression.py::TestInvarianceCompression::test_I4_3_asinh_compression_roundtrip`
 
 ### BACK.invariance
 - ❌ `test_invariance_backend.py::TestInvarianceBackend::test_I2_6_chained_subframe_expressions_numba_vs_numpy`
 
 ### RDF.export
-- ❌ `test_AliasDataFrameRDF.py::TestTMemFileBranch::test_missing_keys_in_friend`
-- ❌ `test_AliasDataFrameRDF.py::TestRDataFrameFriendAccess::test_composite_index_friend`
 - ❌ `test_AliasDataFrameRDF.py::TestAddDefinesCollision::test_collision_from_friend_tree`
+- ❌ `test_AliasDataFrameRDF.py::TestRDataFrameFriendAccess::test_composite_index_friend`
+- ❌ `test_AliasDataFrameRDF.py::TestTMemFileBranch::test_missing_keys_in_friend`
 
 ## Unmatched Tests
 
-42 tests not mapped to any feature.
-
-- `test_alias_dataframe.py::TestReadTreeOptimized::test_aliases_preserved`
-- `test_alias_dataframe.py::TestReadTreeOptimized::test_backward_compatibility_no_metadata`
-- `test_alias_dataframe.py::TestReadTreeOptimized::test_basic_read`
-- `test_alias_dataframe.py::TestReadTreeOptimized::test_entry_range_start_stop`
-- `test_alias_dataframe.py::TestReadTreeOptimized::test_entry_range_stop`
-- `test_alias_dataframe.py::TestReadTreeOptimized::test_invalid_tree_raises_error`
-- `test_alias_dataframe.py::TestReadTreeOptimized::test_subframe_loaded`
-- `test_alias_dataframe.py::TestReadTreeOptimized::test_subframe_warning_with_entry_range`
-- `test_alias_dataframe.py::TestReadTreeOptimized::test_threaded_vs_unthreaded_equivalence`
-- `test_alias_dataframe.py::TestReadTreeWithCompression::test_compressed_columns_dtype_restored`
-- `test_alias_dataframe.py::TestReadTreeWithCompression::test_compression_info_preserved`
-- `test_alias_dataframe.py::TestReadTreeWithCompression::test_decompression_alias_works`
-- `test_alias_dataframe.py::TestReadTreeWithCompression::test_entry_range_with_compression`
-- `test_alias_dataframe.py::TestSchemaV2Ordering::test_schema_v2_groups_roundtrip`
-- `test_alias_dataframe.py::TestSchemaV2Ordering::test_schema_v2_groups_simple_lists`
-- `test_alias_dataframe.py::TestSchemaV2Ordering::test_schema_v2_order_agnostic_load`
-- `test_alias_dataframe.py::TestSchemaV2Ordering::test_schema_v2_order_canonical`
-- `test_alias_dataframe.py::TestSchemaV2Ordering::test_schema_v2_order_full`
-- `test_alias_dataframe.py::TestSchemaV2Ordering::test_schema_v2_order_strict_positions`
-- `test_alias_dataframe.py::TestSchemaV2Ordering::test_schema_v2_without_groups`
-- `test_fill_handling.py::TestModeComparison::test_direct_and_safe_give_same_values_when_no_missing`
-- `test_fill_handling.py::TestMultipleSubframes::test_different_fill_per_subframe`
-- `test_fill_handling.py::TestSubframeFillConfig::test_clear_subframe_fill`
-- `test_fill_handling.py::TestSubframeFillConfig::test_clear_subframe_fill_validates_subframe`
-- `test_fill_handling.py::TestSubframeFillConfig::test_set_subframe_fill_partial_override`
-- `test_fill_handling.py::TestSubframeFillConfig::test_set_subframe_fill_rejects_unknown_fill_mode`
-- `test_fill_handling.py::TestSubframeFillConfig::test_set_subframe_fill_stores_config`
-- `test_fill_handling.py::TestSubframeFillConfig::test_set_subframe_fill_unknown_subframe_raises`
-- `test_fill_handling.py::TestSubframeFillConfig::test_subframe_config_overrides_global`
-- `test_fill_handling.py::TestSubframeFillConfig::test_subframe_fill_mode_overrides_global`
-- ... +12 more
+88 tests not mapped to any feature.
+
+- `test_D1_dtype_subframe_join.py::TestDtypeLossSubframeJoin::test_D1_int8_dtype_preserved_through_join`
+- `test_D1_dtype_subframe_join.py::TestDtypeLossSubframeJoin::test_D2_bool_dtype_preserved_through_join`
+- `test_D1_dtype_subframe_join.py::TestDtypeLossSubframeJoin::test_D3_float_dtype_unaffected`
+- `test_D1_dtype_subframe_join.py::TestDtypeLossSubframeJoin::test_D4_no_missing_keys_no_warning`
+- `test_D1_dtype_subframe_join.py::TestDtypeLossSubframeJoin::test_D5_boolean_and_operator_works`
+- `test_E1_export_tree_roundtrip.py::TestExportTreeMetadataRoundtrip::test_E1_1_basic_roundtrip_no_subframes`
+- `test_E1_export_tree_roundtrip.py::TestExportTreeMetadataRoundtrip::test_E1_2_roundtrip_3_subframes`
+- `test_E1_export_tree_roundtrip.py::TestExportTreeMetadataRoundtrip::test_E1_3_roundtrip_production_scale_subframes`
+- `test_E1_export_tree_roundtrip.py::TestExportTreeMetadataRoundtrip::test_E1_4_roundtrip_timing_report`
+- `test_E2_export_tree_fix_a.py::TestE2ExportTreeFixA::test_E2_1_single_tfile_open_per_export`
+- `test_E2_export_tree_fix_a.py::TestE2ExportTreeFixA::test_E2_2_nested_subframe_roundtrip`
+- `test_E2_export_tree_fix_a.py::TestE2ExportTreeFixA::test_E2_3_read_tree_backward_compatibility`
+- `test_E2_export_tree_fix_a.py::TestE2ExportTreeFixA::test_E2_4_standalone_write_metadata_to_root`
+- `test_J1_join_cache.py::TestJ1JoinCacheCorrectness::test_J1_10_dematerialize_drop_keep_mutual_exclusion`
+- `test_J1_join_cache.py::TestJ1JoinCacheCorrectness::test_J1_1_cached_equals_uncached`
+- `test_J1_join_cache.py::TestJ1JoinCacheCorrectness::test_J1_2_cache_survives_materialize_aliases`
+- `test_J1_join_cache.py::TestJ1JoinCacheCorrectness::test_J1_3_cache_invalidates_on_register_subframe`
+- `test_J1_join_cache.py::TestJ1JoinCacheCorrectness::test_J1_4_cache_invalidates_on_subframe_data_change`
+- `test_J1_join_cache.py::TestJ1JoinCacheCorrectness::test_J1_5_multi_subframe_pipeline`
+- `test_J1_join_cache.py::TestJ1JoinCacheCorrectness::test_J1_6_dematerialize_drop_and_recover`
+- `test_J1_join_cache.py::TestJ1JoinCacheCorrectness::test_J1_7_dematerialize_keep`
+- `test_J1_join_cache.py::TestJ1JoinCacheCorrectness::test_J1_8_dematerialize_all`
+- `test_J1_join_cache.py::TestJ1JoinCacheCorrectness::test_J1_9_dematerialize_ignores_raw_columns`
+- `test_J1_join_cache.py::TestJ2JoinCachePerformance::test_J2_1_cache_hit_count_across_materialize_calls`
+- `test_K1_vector_draw_kwarg_diagnostic.py::TestK1VectorDrawKwargDiagnostic::test_K1_1_draw_accepts_all_documented_kwargs`
+- `test_K1_vector_draw_kwarg_diagnostic.py::TestK1VectorDrawKwargDiagnostic::test_K1_2_draw_forwards_kwargs_to_dfdraw`
+- `test_K1_vector_draw_kwarg_diagnostic.py::TestK1VectorDrawKwargDiagnostic::test_K1_3_draw_batch_forwards_batch_kwargs`
+- `test_K1_vector_draw_kwarg_diagnostic.py::TestK1VectorDrawKwargDiagnostic::test_K1_4_draw_figures_forwards_figure_kwargs`
+- `test_K1_vector_draw_kwarg_diagnostic.py::TestK1VectorDrawKwargDiagnostic::test_K1_5_vector_expression_each_call_gets_full_kwargs`
+- `test_K2_vector_draw_end_to_end.py::TestK2VectorDrawEndToEnd::test_K2_1_scalar_groupby_baseline`
+- ... +58 more
 
 ---
 *Generated from pytest JSON + feature_taxonomy.py (v2 taxonomy-based).*

UTILS/dfextensions/AliasDataFrame/docs/PHASE_HISTORY.md

@@ -42,8 +42,8 @@ AliasDataFrame is a high-performance data analysis framework for particle physic
 
 **Key Metrics:**
 - Performance: 60-770x speedups achieved; production pipeline 2× faster (1452s → 722s)
-- Test Coverage: 1521 tests passing, 125 invariance tests
-- Lines of Code: ~12,800 (AliasDataFrame.py)
+- Test Coverage: 1538 tests passing, 125 invariance tests
+- Lines of Code: ~12,930 (AliasDataFrame.py)
 - Features: 44 in taxonomy (26 verified, 14 smoke-only, 3 broken, 1 planned)
 
 **Development Team:**
@@ -234,8 +234,66 @@ Mode #11 discipline).
 
 ---
 
+### Phase 13.22.ADF: Recursive Subframe Loading in read_tree
+**Dates**: 2026-04-19  
+**Status**: ✅ Merged  
+**Commit**: `cf62cf33`
+
+**Fix**: One-line change — `read_tree` line 5298 `load_subframes=False` → `True`. `export_tree` already writes nested subframes recursively (Phase 13.20). `read_tree` now loads them recursively too.
+
+**Result**: E2_2 (nested subframe roundtrip) changed from FAILING to PASSING. 1523 passed (+2).
+
+**Out of scope**: Multi-level dotted expression resolution (`Outer.Inner.val`) — deferred to Phase 13.23.ADF proposal. Metadata skip (A3) — reverted, needs minimal-UserInfo approach.
+
+**Test results**: 1523 passed, 6F+1E pre-existing.
+
+---
+
 ## Bug Fixes
 
+### BUG_AliasDataFrame_20260420_draw_selection_alias
+**Dates**: 2026-04-20  
+**Status**: ✅ Fixed  
+**Commit**: `6f93e2d1`
+
+**Problem**: `draw_batch()` and `draw_figures()` do not pass `selection` or `weights` to `_parse_expr_aliases()`. Aliases used only in selections (e.g., `isNotEdge`) are never auto-materialized. `pandas.eval` fails with `name 'isNotEdge' is not defined`.
+
+**Root cause**: Two call sites pass `(expr, group_by, color)` but omit `selection=` and `weights=`. `draw()` was correct (already passes all params).
+
+**Fix**: 2 lines per method — pass `selection` and `weights`.
+
+**Tests**: S1 (xfail — draw lazy=False limitation), S1b, S2, S3, S4.
+
+**Discovered**: Production QA (`makeIterationFit123_QA`) on gr17.
+
+### BUG_AliasDataFrame_20260424_dtype_loss_subframe_join
+**Dates**: 2026-04-24  
+**Status**: ✅ Fixed  
+**Commit**: `bfb4d22f`
+
+**Problem**: Aliases declared with integer/bool dtype lose their dtype through subframe joins. The join produces NaN for missing keys; pandas raises `IntCastingNaNError` on `.astype(int8)`; the cast fails silently; result stays float32. Downstream bool operators (`isPrimITS & isNotEdge`) fail.
+
+**Root cause**: Three `.astype()` calls caught only `AttributeError`, not `IntCastingNaNError`.
+
+**Fix**: New `_safe_dtype_cast()` helper fills NaN with 0 (int) or False (bool) before casting, with `RuntimeWarning`. Replaces all 3 raw `.astype()` calls.
+
+**Tests**: D1-D5 (int8, bool, float unaffected, no-NaN no-warning, bool & bool production pattern).
+
+### BUG_AliasDataFrame_20260426_draw_index_col_collision
+**Dates**: 2026-04-26  
+**Status**: ✅ Fixed  
+**Commit**: `d3188527`
+
+**Problem**: `adf.draw('Sub.col:Sub.index_col')` raises `KeyError` when the plotted column is also one of the subframe's `index_columns`. The draw resolver selects the column twice via `sf.df[index_cols + [col_name]]`, then `.rename()` renames both copies (pandas rename is name-based), destroying the join key.
+
+**Root cause**: No guard for `col_name in index_cols` in two draw resolvers.
+
+**Fix**: 5 lines per resolver — guard `col_name in index_cols`, copy + add instead of select + rename. Two locations: `draw()` and `draw_figures()`. `draw_batch()` uses direct index lookup — not affected.
+
+**Tests**: S5_1-S5_6 (index col on x/y axis, selection, correctness, draw_figures, both axes as index cols).
+
+**Discovered**: O2DistAI Phase 0.3 (`makeTrackPairGB` QA plots).
+
 ### BUG_AliasDataFrame_20260324_draw_subframe_resolution
 **Dates**: 2026-03-25  
 **Status**: ✅ Fixed
@@ -680,21 +738,27 @@ Remaining overhead is Python/Pandas framework cost.
 | 13.19.ADF.FIX1 | 8 (K1+K2) | 1499 |
 | 13.20.ADF | 8 (E1+E2) | 1510 |
 | 13.21.ADF | 11 (J1+J2) | 1521 |
+| 13.22.ADF | 0 (E2_2 fixed) | 1523 |
+| BUG draw_selection_alias | 5 (S1-S4) | 1528 |
+| BUG dtype_loss_subframe | 5 (D1-D5) | 1533 |
+| BUG draw_index_col | 6 (S5_1-S5_6) | 1538 |
 
 ---
 
 ## Pending Items
 
 - [x] ~~CAPABILITY_MATRIX.md creation~~ (Phase 13.11)
 - [x] ~~PHASE_BEGIN_AliasDataFrame tag~~ (Phase 13.20 close)
+- [x] ~~`read_tree` recursive subframe loading~~ (Phase 13.22)
+- [ ] Phase 13.23.ADF — Multi-level dotted expression resolution (v1.2 approved)
 - [ ] A2 — LZ4 default compression (one-line + compat test, ~15-20s savings)
-- [ ] A3 — Batch metadata serialization (~20-30s savings)
-- [ ] `read_tree` recursive subframe loading (line 5172 `load_subframes=False` → `True`)
+- [ ] A3 — Batch metadata serialization (~50-55s savings, needs minimal-UserInfo approach)
 - [ ] GB tuple support for `linear_columns` (PolynomialSpec production blocker)
 - [ ] Technical Summary v1.6 full public API documentation (~90 methods)
 - [ ] P1 tests: I2_6, I4_2, I4_3 fixes
 - [ ] Fix `register_subframe_lazy()` bug (BUG_AliasDataFrame_20260116)
 - [ ] Axis title lookup for subframe columns (`Sub_dy` vs `Side.dy`)
+- [ ] draw() lazy=False doesn't materialize selection aliases (S1 xfail)
 
 ---
 

UTILS/dfextensions/AliasDataFrame/tests/test_S5_draw_index_col_collision.py

@@ -89,29 +89,37 @@ def test_S5_4_draw_values_match_subframe(self):
         """
         S5_4: values in drawn profile match manual subframe lookup.
         Not just no-crash — correctness check.
+        Uses deterministic fixture to guarantee test point exists.
         """
-        adf = _build_adf_with_index_col_subframe()
-        sf = adf.get_subframe('Stats')
-
-        # Materialize the subframe column via draw's lazy path
-        adf.materialize_aliases()  # ensure all aliases materialized
-
-        # The draw resolver creates Stats_dy_median on df_subset via merge.
-        # We verify the merge is correct by checking a few values manually.
-        # Pick sec=5, tgl=10 — look up dy_median from subframe
-        mask_main = (adf.df['sec'] == 5) & (adf.df['tgl'] == 10)
-        mask_sub = (sf.df['sec'] == 5) & (sf.df['tgl'] == 10)
-
-        if mask_main.any() and mask_sub.any():
-            expected = sf.df.loc[mask_sub, 'dy_median'].iloc[0]
-            # Use _prepare_subframe_joins to get the joined column
-            adf.add_alias('test_val', 'Stats.dy_median', dtype=np.float32)
-            adf.materialize_aliases(names=['test_val'])
-            actual = adf.df.loc[mask_main, 'test_val'].iloc[0]
-            np.testing.assert_allclose(
-                actual, expected, rtol=1e-5,
-                err_msg="S5_4: joined value doesn't match subframe lookup"
-            )
+        # Deterministic: every (sec, tgl) combination present
+        main_df = pd.DataFrame({
+            'sec': np.array([0, 1, 2, 0, 1, 2], dtype=np.int8),
+            'tgl': np.array([0, 0, 0, 1, 1, 1], dtype=np.int8),
+            'x': np.array([1, 2, 3, 4, 5, 6], dtype=np.float32),
+        })
+        sub_df = pd.DataFrame({
+            'sec': np.array([0, 1, 2, 0, 1, 2], dtype=np.int8),
+            'tgl': np.array([0, 0, 0, 1, 1, 1], dtype=np.int8),
+            'dy_median': np.array([10, 20, 30, 40, 50, 60], dtype=np.float32),
+        })
+
+        adf = AliasDataFrame(main_df)
+        sf = AliasDataFrame(sub_df)
+        adf.register_subframe('Stats', sf, index_columns=['sec', 'tgl'])
+
+        adf.add_alias('test_val', 'Stats.dy_median', dtype=np.float32)
+        adf.materialize_aliases(names=['test_val'])
+
+        # sec=1, tgl=0 → dy_median=20
+        mask = (adf.df['sec'] == 1) & (adf.df['tgl'] == 0)
+        assert mask.any(), "fixture must contain test point"
+        actual = adf.df.loc[mask, 'test_val'].iloc[0]
+        assert actual == 20.0, f"S5_4: expected 20.0, got {actual}"
+
+        # sec=2, tgl=1 → dy_median=60
+        mask2 = (adf.df['sec'] == 2) & (adf.df['tgl'] == 1)
+        actual2 = adf.df.loc[mask2, 'test_val'].iloc[0]
+        assert actual2 == 60.0, f"S5_4: expected 60.0, got {actual2}"
 
     def test_S5_5_draw_figures_index_col(self):
         """