Phase 2: realized volatility, volume and VWAP metrics

[1816x]

Summary

Phase 2 of the roadmap: extend the engine beyond order-flow imbalance to a full set of
per-window microstructure metrics, persisted to a single table and served through the API,
all covered by tests against hand-computed known data.

What changed

Engine (Rust) — ofi.rs → metrics.rs

• OfiBucket → MetricsBucket, now carrying trade_count, vwap and realized_volatility
  alongside buy/sell volume.
• A single time-ordered windowing pass computes every metric.
• Realized volatility is continuous across window boundaries: the log return between two
  consecutive trades is attributed to the later trade's window. This means per-window
  variances sum to the whole tape's realized variance, and a single-tick window still records
  its move away from the previous trade.
• Storage writes one wide metrics row per (bucket_start_ns, window_ns), idempotent on rerun.

Backtest (Python / FastAPI)

• A shared _query_metrics helper reads the unified metrics table.
• /metrics/ofi keeps its Phase 1 response contract.
• New /metrics/volatility (realized volatility + trade count) and /metrics/volume
  (buy/sell/total volume + VWAP) endpoints.

Docs

• Roadmap Phase 2 checked off, curl examples for the new endpoints, and design-decision
  entries for the unified table, continuous realized volatility and VWAP.

Design decisions

• Unified metrics table instead of one table per metric — every metric shares the same
  window key and is produced in one pass, so a wide row is the natural shape.
• Continuous cross-window realized volatility — resetting returns at each window edge would
  silently discard boundary moves and understate volatility.
• VWAP folded into the same pass — needs only the running Σ price·size already touched
  per tick.

Verification

• Engine: cargo fmt --check, cargo clippy --all-targets -- -D warnings, cargo test — 10/10.
• Backtest: ruff check, ruff format --check, pytest — 15/15.
• End-to-end on the synthetic tape: 5000 ticks → 501 buckets. Across all rows,
  total_volume == buy_volume + sell_volume, no negative volatility, ofi ∈ [-1, 1], and VWAP
  within the tape's price range. All three endpoints return 200 with the expected columns.

---

Generated by Claude Code