repo refactor: M5: Implement bounded hot-path pre-allocation/allocation-reduction improvements and capture before/after benchmark deltas

[Aroesler1]

Repo job repo_refactor for objective #38 is ready for review and merge.

Objective: Build project: Real-Time Limit Order Book Engine in C++

Job instructions:
On top of main, make narrowly scoped performance-engineering changes in the replay/book/analytics hot path that reduce avoidable heap activity without changing external behavior. Focus on explicit pre-allocation/reserve strategies for order lookup and rolling analytics buffers, removal of unnecessary per-message temporary allocations/copies, and any obvious benchmark-safe fast-path cleanup already implied by the current design. Do not change analytics schema or replay semantics. Extend the benchmark harness or report-generation path as needed so the repo can produce comparable before/after measurements for both container variants on the documented AAPL fixture and the additional in-repo ticker fixtures. Update the benchmark report to describe the exact optimization changes, measurement method, hardware/compiler context, and before/after throughput results. Validate with existing tests plus parity/correctness checks for both backends.

Why this PR looks credible:
Tests passed on the current branch. The change is coherent and appropriately scoped for M5: it introduces real source-level hot-path allocation reductions in replay and analytics, wires derived reserve hints into the CLI and benchmark paths, adds a backend-parity analytics test, and updates the benchmark report with methodology and before/after results. I did not find a clear semantic regression in the diff itself, and the implementation aligns with the objective of reducing avoidable heap activity without changing replay or analytics behavior. Audit cleared the diff, with 2 remaining validation gap(s) to watch. Backend verification returned unsupported.

Audit summary:
The change is coherent and appropriately scoped for M5: it introduces real source-level hot-path allocation reductions in replay and analytics, wires derived reserve hints into the CLI and benchmark paths, adds a backend-parity analytics test, and updates the benchmark report with methodology and before/after results. I did not find a clear semantic regression in the diff itself, and the implementation aligns with the objective of reducing avoidable heap activity without changing replay or analytics behavior.

Audit must-fix items:

• None

Validation gaps:

• The audit record only shows the pytest wrapper result (2 passed) and not a fresh ctest or raw benchmark command transcript, so benchmark reproducibility is documented but not independently evidenced in the supplied execution log.
• Before/after benchmark numbers are documented in markdown, but there is no checked-in automation that regenerates or verifies the report tables from captured benchmark output.

[Copilot]

Pull request overview

Performance-focused refactor to reduce avoidable heap activity in the replay + analytics hot path, while keeping replay semantics and analytics schema unchanged, and documenting before/after benchmark deltas.

Changes:

• Derive and propagate OrderBookBuildConfig reserve hints from the parsed message stream (instead of hard-coded defaults) into CLI + benchmark flows.
• Reduce per-message allocations/copies in analytics by reusing buffers (reset() reuse), switching to capacity-stable trade window storage, and constructing AnalyticsRow in place during replay.
• Add a C++ test asserting analytics output parity across map and flat_vector backends; update README/report with measurement methodology and results.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/test_analytics.cpp	Adds analytics parity test across backends and snapshot equality assertion.
src/replay.cpp	Adds message-stream-based build config derivation; uses it in benchmark path.
src/main.cpp	Uses derived build config; passes expected message count into analytics config.
src/analytics.cpp	Introduces pre-sized rolling buffers + in-place row fill; reuses allocations on reset.
include/lob/replay.hpp	Exposes derive_order_book_build_config() API.
include/lob/analytics.hpp	Adds expected_messages to config; adds in-place on_message overload.
benchmark/lob_benchmark.cpp	Prints derived reserve hints; uses derived build config per run mode.
report/benchmark_report.md	Expands methodology + before/after numbers and scope notes.
README.md	Summarizes optimization changes and includes updated benchmark table + method.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

estimate_build_requirements() reserves orders to messages.size(), which can be orders of magnitude larger than the peak active order count. On large datasets this pre-pass can allocate a huge unordered_map bucket array (potentially OOM) just to compute reserve hints. Consider removing this reserve or capping it to a reasonable upper bound / heuristic (e.g., based on a sampled estimate or a user-provided hint).

Suggested change

orders.reserve(messages.size());

[Copilot]

mid_window reserves to config.expected_messages, and replay_with_analytics() defaults that to messages.size(). For large replays this can force a very large upfront allocation even though the realized-vol window only needs a sliding subset. Consider making expected_messages a bounded hint (or default it to 0) and reserving based on an estimate of samples retained in the time window rather than total message count.

Suggested change

	mid_window(config.expected_messages) {}
	mid_window(0) {}

[Copilot]

replay_with_analytics() sets expected_messages = messages.size() when unset, which can cause large preallocation in AnalyticsEngine on big datasets. If expected_messages is meant as an optional hint, consider leaving it at 0 by default (no reserve) or applying an upper bound so analytics runs don't accidentally allocate proportional to the full input size.

Suggested change

	if (config.expected_messages == 0) {
	config.expected_messages = messages.size();
	}

[Copilot]

This passes messages.size() as AnalyticsConfig::expected_messages, which can trigger very large upfront reserves in analytics on large datasets. Consider making this a bounded/optional hint (or omit it) so running the CLI with analytics enabled doesn’t unexpectedly allocate memory proportional to the entire input file.

[Copilot]

derive_order_book_build_config() is called inside the reserve_modes loop, so the message-stream estimation pass runs once per reserve mode even though the hints are identical except for enable_preallocation. Consider deriving once before the loop and then only toggling build_config.enable_preallocation (or caching the derived values) to avoid redundant work when benchmarking large datasets.