Pull Request

NautilusTrader prioritizes correctness and reliability, please follow existing patterns for validation and testing.

• I have reviewed the CONTRIBUTING.md and followed the established practices

Summary

Summary

• Refined the handling of timers within the BacktestEngine to ensure correct chronological processing when data is exhausted.
• Replaced the previous "jump to end" timer processing logic with a more granular _process_next_timer approach. This allows the engine to correctly handle on-the-fly data loading triggered by timer callbacks (e.g., subscriptions during a backtest).
• Fixed an initialization issue in the main backtest loop where _last_ns was set to 0 instead of the backtest start time.
• Introduced a new suite of unit tests specifically for backtest engine timers, covering various scenarios including interleaved data/timers and chained alerts.

Key changes

Backtest engine refinements

• Modified nautilus_trader/backtest/engine.pyx to implement _process_next_timer, which finds the absolute next timer time across all component clocks and advances to it.
• Updated the main backtest loop to call _process_next_timer when the data stream is empty, ensuring that timers within the backtest range are processed sequentially.
• Corrected the initial state of _last_ns to prevent premature time jumps or incorrect event processing at the start of a backtest.

Testing and examples

• Added tests/unit_tests/backtest/test_engine_timers.py with 7 new test cases to validate timer execution with and without data, chained alerts, and interleaved processing.
• Updated examples/backtest/notebooks/databento_test_order_book_deltas.py to use set_time_alert for more robust testing of order book delta subscriptions.

Test plan

• Ran the new unit tests using uv run --no-sync pytest tests/unit_tests/backtest/test_engine_timers.py.
• Verified that all 7 tests passed, confirming the correct handling of:
  • Timer execution with no data.
  • On-the-fly data loading from timer callbacks.
  • Multiple timers at the same timestamp.
  • Chained timers and alerts.
  • Interleaved data and timer events.

Related Issues/PRs

Type of change

• Bug fix (non-breaking)
• New feature (non-breaking)
• Improvement (non-breaking)
• Breaking change (impacts existing behavior)
• Documentation update
• Maintenance / chore

Breaking change details (if applicable)

Documentation

• Documentation changes follow the style guide (docs/developer_guide/docs.md)

Release notes

• I added a concise entry to RELEASES.md that follows the existing conventions (when applicable)

Testing

Ensure new or changed logic is covered by tests.

• Affected code paths are already covered by the test suite
• I added/updated tests to cover new or changed logic