feat(microstructure): trade-sign autocorrelation, PIN, Hasbrouck information share (B15) (#212)

## B15 Microstructure — three new indicators (485 → 488)

| Indicator | Input | Output | Notes |
|-----------|-------|--------|-------|
| `TradeSignAutocorrelation` | `Trade` | `f64` ∈ [-1,1] | lag-1 autocorrelation of the signed aggressor (order-flow persistence) |
| `Pin` | `Trade` | `f64` ∈ [0,1] | probability of informed trading from rolling buy/sell imbalance (EKOP single-window estimator); `name()` = `"PIN"` |
| `HasbrouckInformationShare` | `(f64, f64)` | `f64` ∈ [0,1] | variance-ratio proxy for each venue's share of price discovery |

### Wiring
- Core structs + full unit tests (every branch).
- Hand-written Python/Node/WASM bindings for the two `Trade`-input indicators (precedent `TradeImbalance`); `node_pair_indicator!` / `wasm_pair_indicator!` macro bindings + hand Python pyclass for the pairwise Hasbrouck (precedent `RollingCorrelation`).
- Fuzz drives added to `indicator_update_trade.rs` and `indicator_update_pair.rs`.
- Dedicated Python + Node streaming-vs-batch and reference tests; Hasbrouck in the `PAIR` registry.
- README counter (3 spots) + `docs/README.md` + `FAMILIES` assert bumped to 488.

### Verify (all green, local)
- `cargo test -p wickra-core --lib`: 3991 passed
- `cargo test -p wickra-core --doc`: 438 passed
- `cargo clippy --workspace --all-targets --all-features -- -D warnings`: clean
- node: 561 passed · pytest: 926 passed

bindings/node/__tests__/indicators.test.js

@@ -667,6 +667,7 @@ const pairFactories = {
   GrangerCausality: () => new wickra.GrangerCausality(60, 1),
   SpreadAr1Coefficient: () => new wickra.SpreadAr1Coefficient(40),
   KendallTau: () => new wickra.KendallTau(20),
+  HasbrouckInformationShare: () => new wickra.HasbrouckInformationShare(2),
 };
 
 for (const [name, make] of Object.entries(pairFactories)) {
@@ -1270,7 +1271,7 @@ test('vpin / amihud / roll reference + streaming matches batch', () => {
   const price = Array.from({ length: n }, (_, i) => 100 + Math.sin(i * 0.25) * 4);
   const size = Array.from({ length: n }, (_, i) => 1 + (i % 5));
   const isBuy = Array.from({ length: n }, (_, i) => i % 2 === 0);
-  for (const make of [() => new wickra.Vpin(8, 5), () => new wickra.AmihudIlliquidity(14), () => new wickra.RollMeasure(14)]) {
+  for (const make of [() => new wickra.Vpin(8, 5), () => new wickra.AmihudIlliquidity(14), () => new wickra.RollMeasure(14), () => new wickra.TradeSignAutocorrelation(10), () => new wickra.Pin(10)]) {
     const batch = make().batch(price, size, isBuy);
     const streamer = make();
     assert.equal(batch.length, n);
@@ -1279,6 +1280,16 @@ test('vpin / amihud / roll reference + streaming matches batch', () => {
       assert.ok((Number.isNaN(batch[i]) && s === null) || Math.abs(s - batch[i]) < 1e-9, `mismatch at ${i}`);
     }
   }
+  // Trade-sign autocorrelation: alternating signs -> -1, all buys -> +1.
+  let tsac = null;
+  const tsacInd = new wickra.TradeSignAutocorrelation(10);
+  for (let i = 0; i < 20; i++) tsac = tsacInd.update(100, 1, i % 2 === 0);
+  assert.ok(Math.abs(tsac - -1.0) < 1e-12);
+  // PIN: one-sided flow -> 1, balanced flow -> 0.
+  let pin = null;
+  const pinInd = new wickra.Pin(10);
+  for (let i = 0; i < 20; i++) pin = pinInd.update(100, 1, true);
+  assert.ok(Math.abs(pin - 1.0) < 1e-12);
 });
 
 test('price-impact indicators reference values', () => {

bindings/node/index.d.ts

@@ -1449,6 +1449,19 @@ export declare class BetaNeutralSpread {
   isReady(): boolean
   warmupPeriod(): number
 }
+export type HasbrouckInformationShareNode = HasbrouckInformationShare
+export declare class HasbrouckInformationShare {
+  constructor(period: number)
+  update(x: number, y: number): number | null
+  /**
+   * Batch over two equally-sized arrays. Returns a length-`n` array
+   * with `NaN` for warmup positions.
+   */
+  batch(x: Array<number>, y: Array<number>): Array<number>
+  reset(): void
+  isReady(): boolean
+  warmupPeriod(): number
+}
 export type PairSpreadZScoreNode = PairSpreadZScore
 /**
  * Pair spread z-score: two ctor params (`betaPeriod`, `zPeriod`), one `(a, b)`
@@ -4333,6 +4346,24 @@ export declare class TradeImbalance {
   isReady(): boolean
   warmupPeriod(): number
 }
+export type TradeSignAutocorrelationNode = TradeSignAutocorrelation
+export declare class TradeSignAutocorrelation {
+  constructor(period: number)
+  update(price: number, size: number, isBuy: boolean): number | null
+  batch(price: Array<number>, size: Array<number>, isBuy: Array<boolean>): Array<number>
+  reset(): void
+  isReady(): boolean
+  warmupPeriod(): number
+}
+export type PinNode = Pin
+export declare class Pin {
+  constructor(window: number)
+  update(price: number, size: number, isBuy: boolean): number | null
+  batch(price: Array<number>, size: Array<number>, isBuy: Array<boolean>): Array<number>
+  reset(): void
+  isReady(): boolean
+  warmupPeriod(): number
+}
 export type OrderFlowImbalanceNode = OrderFlowImbalance
 export declare class OrderFlowImbalance {
   constructor(period: number)

bindings/node/src/lib.rs

@@ -884,6 +884,11 @@ node_pair_indicator!(
     "BetaNeutralSpread",
     wc::BetaNeutralSpread
 );
+node_pair_indicator!(
+    HasbrouckInformationShareNode,
+    "HasbrouckInformationShare",
+    wc::HasbrouckInformationShare
+);
 
 // ============================== PairSpreadZScore ==============================
 
@@ -13739,6 +13744,108 @@ impl TradeImbalanceNode {
     }
 }
 
+// Trade-sign autocorrelation carries a `period` parameter, so it is hand-written.
+#[napi(js_name = "TradeSignAutocorrelation")]
+pub struct TradeSignAutocorrelationNode {
+    inner: wc::TradeSignAutocorrelation,
+}
+
+#[napi]
+impl TradeSignAutocorrelationNode {
+    #[napi(constructor)]
+    pub fn new(period: u32) -> napi::Result<Self> {
+        Ok(Self {
+            inner: wc::TradeSignAutocorrelation::new(period as usize).map_err(map_err)?,
+        })
+    }
+    #[napi]
+    pub fn update(&mut self, price: f64, size: f64, is_buy: bool) -> napi::Result<Option<f64>> {
+        Ok(self.inner.update(build_trade(price, size, is_buy)?))
+    }
+    #[napi]
+    pub fn batch(
+        &mut self,
+        price: Vec<f64>,
+        size: Vec<f64>,
+        is_buy: Vec<bool>,
+    ) -> napi::Result<Vec<f64>> {
+        if price.len() != size.len() || size.len() != is_buy.len() {
+            return Err(NapiError::from_reason(
+                "price, size, is_buy must be equal length".to_string(),
+            ));
+        }
+        let mut out = Vec::with_capacity(price.len());
+        for i in 0..price.len() {
+            let trade = build_trade(price[i], size[i], is_buy[i])?;
+            out.push(self.inner.update(trade).unwrap_or(f64::NAN));
+        }
+        Ok(out)
+    }
+    #[napi]
+    pub fn reset(&mut self) {
+        self.inner.reset();
+    }
+    #[napi(js_name = "isReady")]
+    pub fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    #[napi(js_name = "warmupPeriod")]
+    pub fn warmup_period(&self) -> u32 {
+        self.inner.warmup_period() as u32
+    }
+}
+
+// PIN carries a `window` parameter, so it is hand-written.
+#[napi(js_name = "Pin")]
+pub struct PinNode {
+    inner: wc::Pin,
+}
+
+#[napi]
+impl PinNode {
+    #[napi(constructor)]
+    pub fn new(window: u32) -> napi::Result<Self> {
+        Ok(Self {
+            inner: wc::Pin::new(window as usize).map_err(map_err)?,
+        })
+    }
+    #[napi]
+    pub fn update(&mut self, price: f64, size: f64, is_buy: bool) -> napi::Result<Option<f64>> {
+        Ok(self.inner.update(build_trade(price, size, is_buy)?))
+    }
+    #[napi]
+    pub fn batch(
+        &mut self,
+        price: Vec<f64>,
+        size: Vec<f64>,
+        is_buy: Vec<bool>,
+    ) -> napi::Result<Vec<f64>> {
+        if price.len() != size.len() || size.len() != is_buy.len() {
+            return Err(NapiError::from_reason(
+                "price, size, is_buy must be equal length".to_string(),
+            ));
+        }
+        let mut out = Vec::with_capacity(price.len());
+        for i in 0..price.len() {
+            let trade = build_trade(price[i], size[i], is_buy[i])?;
+            out.push(self.inner.update(trade).unwrap_or(f64::NAN));
+        }
+        Ok(out)
+    }
+    #[napi]
+    pub fn reset(&mut self) {
+        self.inner.reset();
+    }
+    #[napi(js_name = "isReady")]
+    pub fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    #[napi(js_name = "warmupPeriod")]
+    pub fn warmup_period(&self) -> u32 {
+        self.inner.warmup_period() as u32
+    }
+}
+
 // Order Flow Imbalance: order-book input with a `period` parameter.
 #[napi(js_name = "OrderFlowImbalance")]
 pub struct OrderFlowImbalanceNode {

bindings/python/python/wickra/__init__.py

@@ -464,6 +464,8 @@ from ._wickra import (
     QuotedSpread,
     DepthSlope,
     # Microstructure: trade flow
+    Pin,
+    TradeSignAutocorrelation,
     RollMeasure,
     AmihudIlliquidity,
     Vpin,
@@ -471,6 +473,7 @@ from ._wickra import (
     CumulativeVolumeDelta,
     TradeImbalance,
     # Microstructure: price impact
+    HasbrouckInformationShare,
     EffectiveSpread,
     RealizedSpread,
     KylesLambda,
@@ -979,6 +982,8 @@ __all__ = [
     "QuotedSpread",
     "DepthSlope",
     # Microstructure: trade flow
+    "Pin",
+    "TradeSignAutocorrelation",
     "RollMeasure",
     "AmihudIlliquidity",
     "Vpin",
@@ -986,6 +991,7 @@ __all__ = [
     "CumulativeVolumeDelta",
     "TradeImbalance",
     # Microstructure: price impact
+    "HasbrouckInformationShare",
     "EffectiveSpread",
     "RealizedSpread",
     "KylesLambda",

bindings/python/src/lib.rs

@@ -16980,6 +16980,70 @@ impl PyRollingCorrelation {
     }
 }
 
+// ========================= HasbrouckInformationShare =========================
+
+#[pyclass(
+    name = "HasbrouckInformationShare",
+    module = "wickra._wickra",
+    skip_from_py_object
+)]
+#[derive(Clone)]
+struct PyHasbrouckInformationShare {
+    inner: wc::HasbrouckInformationShare,
+}
+
+#[pymethods]
+impl PyHasbrouckInformationShare {
+    #[new]
+    #[pyo3(signature = (period=20))]
+    fn new(period: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::HasbrouckInformationShare::new(period).map_err(map_err)?,
+        })
+    }
+    fn update(&mut self, a: f64, b: f64) -> Option<f64> {
+        self.inner.update((a, b))
+    }
+    /// Batch over two equally-sized numpy arrays: `a` and `b`.
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        a: PyReadonlyArray1<'py, f64>,
+        b: PyReadonlyArray1<'py, f64>,
+    ) -> PyResult<Bound<'py, PyArray1<f64>>> {
+        let xs = a
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        let ys = b
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        if xs.len() != ys.len() {
+            return Err(PyValueError::new_err("a and b must be equal length"));
+        }
+        let mut out = Vec::with_capacity(xs.len());
+        for i in 0..xs.len() {
+            out.push(self.inner.update((xs[i], ys[i])).unwrap_or(f64::NAN));
+        }
+        Ok(out.into_pyarray(py))
+    }
+    #[getter]
+    fn period(&self) -> usize {
+        self.inner.period()
+    }
+    fn reset(&mut self) {
+        self.inner.reset();
+    }
+    fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    fn warmup_period(&self) -> usize {
+        self.inner.warmup_period()
+    }
+    fn __repr__(&self) -> String {
+        format!("HasbrouckInformationShare(period={})", self.inner.period())
+    }
+}
+
 // ============================== RollingCovariance ==============================
 
 #[pyclass(
@@ -18652,6 +18716,112 @@ impl PyTradeImbalance {
     }
 }
 
+// Trade-sign autocorrelation carries a `period` parameter, so it is hand-written.
+#[pyclass(
+    name = "TradeSignAutocorrelation",
+    module = "wickra._wickra",
+    skip_from_py_object
+)]
+#[derive(Clone)]
+struct PyTradeSignAutocorrelation {
+    inner: wc::TradeSignAutocorrelation,
+}
+
+#[pymethods]
+impl PyTradeSignAutocorrelation {
+    #[new]
+    fn new(period: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::TradeSignAutocorrelation::new(period).map_err(map_err)?,
+        })
+    }
+    fn update(&mut self, price: f64, size: f64, is_buy: bool) -> PyResult<Option<f64>> {
+        Ok(self.inner.update(build_trade(price, size, is_buy)?))
+    }
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        price: Vec<f64>,
+        size: Vec<f64>,
+        is_buy: Vec<bool>,
+    ) -> PyResult<Bound<'py, PyArray1<f64>>> {
+        if price.len() != size.len() || size.len() != is_buy.len() {
+            return Err(PyValueError::new_err(
+                "price, size, is_buy must be equal length",
+            ));
+        }
+        let mut out = Vec::with_capacity(price.len());
+        for i in 0..price.len() {
+            let trade = build_trade(price[i], size[i], is_buy[i])?;
+            out.push(self.inner.update(trade).unwrap_or(f64::NAN));
+        }
+        Ok(out.into_pyarray(py))
+    }
+    fn reset(&mut self) {
+        self.inner.reset();
+    }
+    fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    fn warmup_period(&self) -> usize {
+        self.inner.warmup_period()
+    }
+    fn __repr__(&self) -> String {
+        format!("TradeSignAutocorrelation(period={})", self.inner.period())
+    }
+}
+
+// PIN carries a `window` parameter, so it is hand-written.
+#[pyclass(name = "Pin", module = "wickra._wickra", skip_from_py_object)]
+#[derive(Clone)]
+struct PyPin {
+    inner: wc::Pin,
+}
+
+#[pymethods]
+impl PyPin {
+    #[new]
+    fn new(window: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::Pin::new(window).map_err(map_err)?,
+        })
+    }
+    fn update(&mut self, price: f64, size: f64, is_buy: bool) -> PyResult<Option<f64>> {
+        Ok(self.inner.update(build_trade(price, size, is_buy)?))
+    }
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        price: Vec<f64>,
+        size: Vec<f64>,
+        is_buy: Vec<bool>,
+    ) -> PyResult<Bound<'py, PyArray1<f64>>> {
+        if price.len() != size.len() || size.len() != is_buy.len() {
+            return Err(PyValueError::new_err(
+                "price, size, is_buy must be equal length",
+            ));
+        }
+        let mut out = Vec::with_capacity(price.len());
+        for i in 0..price.len() {
+            let trade = build_trade(price[i], size[i], is_buy[i])?;
+            out.push(self.inner.update(trade).unwrap_or(f64::NAN));
+        }
+        Ok(out.into_pyarray(py))
+    }
+    fn reset(&mut self) {
+        self.inner.reset();
+    }
+    fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    fn warmup_period(&self) -> usize {
+        self.inner.warmup_period()
+    }
+    fn __repr__(&self) -> String {
+        format!("Pin(window={})", self.inner.window())
+    }
+}
+
 // Order Flow Imbalance carries a `period` parameter and an order-book input,
 // so it is hand-written.
 #[pyclass(
@@ -24743,6 +24913,7 @@ fn _wickra(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<PyCointegration>()?;
     m.add_class::<PyRelativeStrengthAB>()?;
     m.add_class::<PyRollingCorrelation>()?;
+    m.add_class::<PyHasbrouckInformationShare>()?;
     m.add_class::<PyRollingCovariance>()?;
     m.add_class::<PyOuHalfLife>()?;
     m.add_class::<PySpreadHurst>()?;
@@ -24833,6 +25004,8 @@ fn _wickra(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<PySignedVolume>()?;
     m.add_class::<PyCumulativeVolumeDelta>()?;
     m.add_class::<PyTradeImbalance>()?;
+    m.add_class::<PyTradeSignAutocorrelation>()?;
+    m.add_class::<PyPin>()?;
     m.add_class::<PyOrderFlowImbalance>()?;
     m.add_class::<PyVpin>()?;
     m.add_class::<PyAmihudIlliquidity>()?;

bindings/python/tests/test_new_indicators.py

@@ -217,6 +217,7 @@ def test_scalar_streaming_matches_batch(cls, args, sine_prices):
 # --- Two-series (asset, benchmark) indicators -----------------------------
 
 PAIR = [
+    (ta.HasbrouckInformationShare, (2,)),
     (ta.KendallTau, (20,)),
     (ta.SpreadAr1Coefficient, (40,)),
     (ta.GrangerCausality, (60, 1)),
@@ -3323,6 +3324,13 @@ def test_tower_top_bottom_reference():
     assert t.update((110.0, 110.1, 99.9, 100.0, 1.0, 2)) == pytest.approx(-1.0)
 
 
+
+def test_hasbrouck_information_share_reference():
+    t = ta.HasbrouckInformationShare(2)
+    assert t.update(7.0, 9.0) is None
+    assert t.update(7.0, 9.0) is None
+    assert t.update(7.0, 9.0) == pytest.approx(0.5)
+
 # --- Lifecycle ------------------------------------------------------------
 
 
@@ -3663,6 +3671,8 @@ def test_tradeflow_indicators_streaming_equals_batch():
         lambda: ta.Vpin(8.0, 5),
         lambda: ta.AmihudIlliquidity(14),
         lambda: ta.RollMeasure(14),
+        lambda: ta.TradeSignAutocorrelation(10),
+        lambda: ta.Pin(10),
     ):
         batch = make().batch(price, size, is_buy)
         streamer = make()
@@ -3674,6 +3684,34 @@ def test_tradeflow_indicators_streaming_equals_batch():
         assert _eq_nan(batch, streamed)
 
 
+def test_trade_sign_autocorrelation_reference():
+    # Perfectly alternating aggressor signs -> lag-1 autocorrelation -1.
+    t = ta.TradeSignAutocorrelation(10)
+    last = None
+    for i in range(20):
+        last = t.update(100.0, 1.0, i % 2 == 0)
+    assert last == pytest.approx(-1.0)
+    # All buys -> perfectly persistent flow -> +1.
+    t2 = ta.TradeSignAutocorrelation(10)
+    for _ in range(20):
+        last2 = t2.update(100.0, 1.0, True)
+    assert last2 == pytest.approx(1.0)
+
+
+def test_pin_reference():
+    # One-sided flow (all buys) -> maximally informed -> PIN 1.
+    p = ta.Pin(10)
+    last = None
+    for _ in range(20):
+        last = p.update(100.0, 1.0, True)
+    assert last == pytest.approx(1.0)
+    # Balanced flow -> uninformed -> PIN 0.
+    p2 = ta.Pin(10)
+    for i in range(20):
+        last2 = p2.update(100.0, 1.0, i % 2 == 0)
+    assert last2 == pytest.approx(0.0)
+
+
 def test_price_impact_indicators_streaming_equals_batch():
     n = 40
     mid = np.array([100.0 + 0.5 * math.sin(i * 0.4) for i in range(n)], dtype=np.float64)

bindings/wasm/src/lib.rs

@@ -563,6 +563,11 @@ wasm_pair_indicator!(
     "BetaNeutralSpread",
     wc::BetaNeutralSpread
 );
+wasm_pair_indicator!(
+    WasmHasbrouckInformationShare,
+    "HasbrouckInformationShare",
+    wc::HasbrouckInformationShare
+);
 
 // ---------- PairSpreadZScore (two params) ----------
 
@@ -9279,6 +9284,66 @@ impl WasmTradeImbalance {
     }
 }
 
+// Trade-sign autocorrelation carries a `period` parameter, so it is hand-written.
+#[wasm_bindgen(js_name = TradeSignAutocorrelation)]
+pub struct WasmTradeSignAutocorrelation {
+    inner: wc::TradeSignAutocorrelation,
+}
+
+#[wasm_bindgen(js_class = TradeSignAutocorrelation)]
+impl WasmTradeSignAutocorrelation {
+    #[wasm_bindgen(constructor)]
+    pub fn new(period: usize) -> Result<WasmTradeSignAutocorrelation, JsError> {
+        Ok(Self {
+            inner: wc::TradeSignAutocorrelation::new(period).map_err(map_err)?,
+        })
+    }
+    pub fn update(&mut self, price: f64, size: f64, is_buy: bool) -> Result<Option<f64>, JsError> {
+        Ok(self.inner.update(build_trade(price, size, is_buy)?))
+    }
+    pub fn reset(&mut self) {
+        self.inner.reset();
+    }
+    #[wasm_bindgen(js_name = isReady)]
+    pub fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    #[wasm_bindgen(js_name = warmupPeriod)]
+    pub fn warmup_period(&self) -> usize {
+        self.inner.warmup_period()
+    }
+}
+
+// PIN carries a `window` parameter, so it is hand-written.
+#[wasm_bindgen(js_name = Pin)]
+pub struct WasmPin {
+    inner: wc::Pin,
+}
+
+#[wasm_bindgen(js_class = Pin)]
+impl WasmPin {
+    #[wasm_bindgen(constructor)]
+    pub fn new(window: usize) -> Result<WasmPin, JsError> {
+        Ok(Self {
+            inner: wc::Pin::new(window).map_err(map_err)?,
+        })
+    }
+    pub fn update(&mut self, price: f64, size: f64, is_buy: bool) -> Result<Option<f64>, JsError> {
+        Ok(self.inner.update(build_trade(price, size, is_buy)?))
+    }
+    pub fn reset(&mut self) {
+        self.inner.reset();
+    }
+    #[wasm_bindgen(js_name = isReady)]
+    pub fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    #[wasm_bindgen(js_name = warmupPeriod)]
+    pub fn warmup_period(&self) -> usize {
+        self.inner.warmup_period()
+    }
+}
+
 // Order Flow Imbalance: order-book input with a `period` parameter.
 #[wasm_bindgen(js_name = OrderFlowImbalance)]
 pub struct WasmOrderFlowImbalance {