feat: order-book microstructure indicators (part 1 of 4) (#112)

* feat(core): add microstructure input types (OrderBook, Trade, TradeQuote)

New non-OHLCV value types for the order-book / trade-flow indicator family:
Level, OrderBook (sorted, uncrossed depth snapshot), Side, Trade (with
aggressor side), and TradeQuote (trade paired with prevailing mid). Each has a
validating constructor plus a new_unchecked hot-path constructor, with full
unit coverage. Adds InvalidOrderBook / InvalidTrade error variants.

* feat(core): add 5 order-book microstructure indicators

OrderBookImbalanceTop1/TopN/Full (signed depth imbalance), Microprice
(size-weighted fair value), and QuotedSpread (top-of-book spread in bps). All
consume the OrderBook snapshot type, emit f64, are stateless and ready after
the first snapshot, with full unit coverage. Registers a new Microstructure
family in the taxonomy.

* feat(bindings): expose order-book microstructure indicators

Python, Node, and WASM bindings for OrderBookImbalanceTop1/TopN/Full,
Microprice and QuotedSpread. Each takes a depth snapshot via four equal-length
(bid_px, bid_sz, ask_px, ask_sz) arrays. Python and Node expose a batch over a
list of snapshots; WASM exposes per-snapshot update (the streaming model that
fits a browser book feed). Regenerates node index.d.ts/.js and registers the
new InvalidOrderBook/InvalidTrade arms in the Python error mapping.

* test(bindings,fuzz): cover order-book microstructure indicators

Python: smoke, reference values, streaming-vs-batch, lifecycle/repr and input
validation (mismatched lengths, crossed book, misordered levels, zero levels)
for all five order-book indicators. Node: reference values, streaming-vs-batch,
and rejection cases. Adds an indicator_update_orderbook fuzz target driving
every order-book indicator over arbitrary (incl. degenerate) snapshots.

* bench(microstructure): synthetic order-book benchmarks

Add a bench_orderbook_input harness and synthesise a five-level book around
each candle close (no order-book dataset ships with the repo). Benches the
cheapest (top-of-book imbalance) and most-expensive (full-depth imbalance) plus
microprice, matching the curated cheapest/expensive-per-family approach.

* docs: add Microstructure family + bump indicator counter to 224

README gains the Microstructure family row (order-book imbalance, microprice,
quoted spread) and the indicator counter goes 219 -> 224 across seventeen
families; CHANGELOG records the new order-book indicators and value types.

bindings/python/tests/test_input_validation.py

@@ -166,3 +166,28 @@ def test_family_10_ehlers_rejects_invalid_parameters():
         ta.MAMA(0.05, 0.5)
     with pytest.raises(ValueError):
         ta.EmpiricalModeDecomposition(20, 0.0)
+
+
+def test_orderbook_topn_zero_levels_raises():
+    with pytest.raises(ValueError):
+        ta.OrderBookImbalanceTopN(0)
+
+
+def test_orderbook_unequal_price_size_lengths_raise():
+    # bid_px has 2 entries but bid_sz has 1 -> mismatched -> ValueError.
+    with pytest.raises(ValueError):
+        ta.OrderBookImbalanceTop1().update([100.0, 99.0], [1.0], [101.0], [1.0])
+    with pytest.raises(ValueError):
+        ta.Microprice().update([100.0], [1.0], [101.0, 102.0], [1.0])
+
+
+def test_orderbook_crossed_book_raises():
+    # best_bid (102) >= best_ask (101) is a crossed book -> rejected.
+    with pytest.raises(ValueError):
+        ta.QuotedSpread().update([102.0], [1.0], [101.0], [1.0])
+
+
+def test_orderbook_misordered_levels_raise():
+    # Bids must be strictly descending in price.
+    with pytest.raises(ValueError):
+        ta.OrderBookImbalanceFull().update([99.0, 100.0], [1.0, 1.0], [101.0], [1.0])

bindings/python/tests/test_known_values.py

@@ -847,3 +847,26 @@ def test_doji_signed_dragonfly_gravestone_neutral():
     assert d.update((10.0, 12.0, 8.0, 10.0, 1.0, 2)) == pytest.approx(0.0)
     # A large body is not a doji at all -> 0 regardless of position.
     assert d.update((10.0, 12.0, 10.0, 12.0, 1.0, 3)) == pytest.approx(0.0)
+
+
+def test_orderbook_imbalance_reference_values():
+    # Top-1: (3 - 1) / (3 + 1) = 0.5.
+    assert ta.OrderBookImbalanceTop1().update([100.0], [3.0], [101.0], [1.0]) == pytest.approx(0.5)
+    # Top-2: bidDepth 3, askDepth 2 -> (3 - 2) / 5 = 0.2.
+    topn = ta.OrderBookImbalanceTopN(2)
+    assert topn.update([100.0, 99.0], [2.0, 1.0], [101.0, 102.0], [1.0, 1.0]) == pytest.approx(0.2)
+    # Full: bidDepth 1, askDepth 3 -> (1 - 3) / 4 = -0.5.
+    full = ta.OrderBookImbalanceFull()
+    assert full.update([100.0], [1.0], [101.0, 102.0], [2.0, 1.0]) == pytest.approx(-0.5)
+
+
+def test_microprice_reference_value():
+    # (100*3 + 101*1) / (1 + 3) = 401 / 4 = 100.25 — heavy ask pulls toward bid.
+    mp = ta.Microprice()
+    assert mp.update([100.0], [1.0], [101.0], [3.0]) == pytest.approx(100.25)
+
+
+def test_quoted_spread_reference_value():
+    # spread 1.0, mid 100.5 -> 1 / 100.5 * 10_000 ≈ 99.5025 bps.
+    qs = ta.QuotedSpread()
+    assert qs.update([100.0], [1.0], [101.0], [1.0]) == pytest.approx(99.50248756, abs=1e-6)

bindings/python/tests/test_lifecycle.py

@@ -129,3 +129,24 @@ def test_ehlers_indicators_lifecycle():
         assert ind.is_ready()
         ind.reset()
         assert not ind.is_ready()
+
+
+def test_orderbook_lifecycle():
+    snapshot = ([100.0], [1.0], [101.0], [1.0])
+    for ind in [
+        ta.OrderBookImbalanceTop1(),
+        ta.OrderBookImbalanceTopN(3),
+        ta.OrderBookImbalanceFull(),
+        ta.Microprice(),
+        ta.QuotedSpread(),
+    ]:
+        assert ind.warmup_period() == 1
+        assert not ind.is_ready()
+        ind.update(*snapshot)
+        assert ind.is_ready()
+        ind.reset()
+        assert not ind.is_ready()
+
+
+def test_orderbook_topn_repr():
+    assert repr(ta.OrderBookImbalanceTopN(5)) == "OrderBookImbalanceTopN(levels=5)"

bindings/python/tests/test_new_indicators.py

@@ -1863,3 +1863,38 @@ def test_new_indicators_expose_lifecycle():
         assert ind.warmup_period() >= 1
         ind.reset()
         assert ind.is_ready() is False
+
+
+def _orderbook_snapshots(n: int) -> list:
+    """A deterministic varying sequence of order-book snapshots."""
+    snaps = []
+    for i in range(n):
+        bid_sz = 1.0 + (i % 5)
+        ask_sz = 1.0 + ((i + 2) % 4)
+        snaps.append(
+            (
+                [100.0, 99.0],
+                [bid_sz, 1.0],
+                [101.0, 102.0],
+                [ask_sz, 1.0],
+            )
+        )
+    return snaps
+
+
+def test_orderbook_indicators_streaming_equals_batch():
+    snaps = _orderbook_snapshots(40)
+    for make in (
+        ta.OrderBookImbalanceTop1,
+        lambda: ta.OrderBookImbalanceTopN(2),
+        ta.OrderBookImbalanceFull,
+        ta.Microprice,
+        ta.QuotedSpread,
+    ):
+        batch = make().batch(snaps)
+        streamer = make()
+        streamed = np.array(
+            [streamer.update(*snap) for snap in snaps], dtype=np.float64
+        )
+        assert batch.shape == (len(snaps),)
+        assert _eq_nan(batch, streamed)

bindings/python/tests/test_smoke.py

@@ -97,3 +97,25 @@ def test_ehlers_super_smoother_batch_shape(sine_prices):
 def test_mama_batch_shape(sine_prices):
     out = ta.MAMA().batch(sine_prices)
     assert out.shape == (sine_prices.size, 2)
+
+
+def test_orderbook_indicators_construct_and_emit():
+    # All five order-book indicators accept a four-array snapshot and emit a float.
+    snapshot = ([100.0, 99.0], [2.0, 1.0], [101.0, 102.0], [1.0, 1.0])
+    indicators = [
+        ta.OrderBookImbalanceTop1(),
+        ta.OrderBookImbalanceTopN(2),
+        ta.OrderBookImbalanceFull(),
+        ta.Microprice(),
+        ta.QuotedSpread(),
+    ]
+    for ind in indicators:
+        out = ind.update(*snapshot)
+        assert isinstance(out, float)
+
+
+def test_orderbook_batch_returns_one_value_per_snapshot():
+    snapshots = [([100.0], [3.0], [101.0], [1.0])] * 5
+    out = ta.OrderBookImbalanceTop1().batch(snapshots)
+    assert out.shape == (5,)
+    assert out.dtype == np.float64

bindings/python/tests/test_streaming_vs_batch.py

@@ -201,3 +201,19 @@ def test_opening_range_streaming_matches_batch(ohlc_series):
         rows.append([math.nan, math.nan, math.nan] if out is None else list(out))
     streamed = np.array(rows, dtype=np.float64)
     assert _equal_with_nan(batch, streamed)
+
+
+def test_orderbook_streaming_matches_batch():
+    snaps = [
+        (
+            [100.0, 99.0],
+            [1.0 + (i % 5), 1.0],
+            [101.0, 102.0],
+            [1.0 + ((i + 1) % 3), 1.0],
+        )
+        for i in range(30)
+    ]
+    batch = ta.Microprice().batch(snaps)
+    streamer = ta.Microprice()
+    streamed = np.array([streamer.update(*snap) for snap in snaps], dtype=np.float64)
+    assert _equal_with_nan(batch, streamed)