fix: anchor drawdowns at high-water marks

src/ml4t/diagnostic/__init__.py

@@ -31,7 +31,7 @@
 exported in __all__. Breaking changes will only occur in major version bumps.
 """
 
-__version__ = "0.1.0b24"
+__version__ = "0.1.0b25"
 
 # Sub-modules for advanced usage
 from . import (

src/ml4t/diagnostic/evaluation/portfolio_analysis/analysis.py

@@ -570,10 +570,11 @@ def _identify_drawdown_periods(
         valley_depth = 0.0
 
         for i, dd in enumerate(underwater):
-            if dd < -threshold and not in_drawdown:
+            if not in_drawdown and dd >= 0:
+                peak_idx = i
+            elif dd < -threshold and not in_drawdown:
                 # Start of drawdown
                 in_drawdown = True
-                peak_idx = i - 1 if i > 0 else 0
                 valley_idx = i
                 valley_depth = dd
             elif in_drawdown:
@@ -593,6 +594,7 @@ def _identify_drawdown_periods(
                     )
                     periods.append(period)
                     in_drawdown = False
+                    peak_idx = i
 
         # Handle ongoing drawdown
         if in_drawdown:

tests/test_evaluation/test_portfolio_analysis.py

@@ -783,6 +783,21 @@ def test_compute_drawdown_analysis(self, portfolio_analysis):
         assert result.max_drawdown <= 0
         assert result.num_drawdowns >= 0
 
+    def test_drawdown_peak_precedes_threshold_crossing(self):
+        """Drawdown periods start at the actual high-water mark."""
+        returns = np.array([0.0, -0.005, -0.010, -0.010, 0.031])
+        dates = pl.date_range(pl.date(2026, 1, 1), pl.date(2026, 1, 5), eager=True)
+
+        result = PortfolioAnalysis(returns=returns, dates=dates).compute_drawdown_analysis(
+            threshold=0.01
+        )
+
+        period = result.top_drawdowns[0]
+        assert period.peak_date == dates[0]
+        assert period.valley_date == dates[3]
+        assert period.recovery_date == dates[4]
+        assert period.duration_days == 3
+
     def test_drawdown_caching(self, portfolio_analysis):
         """Test that drawdown results are cached."""
         result1 = portfolio_analysis.compute_drawdown_analysis()