feat: Neural Trader — dynamic market graphs with MinCut coherence gating #245
Description
Overview
Implement the Neural Trader system as described in ADR-085: a six-layer pipeline that treats the limit order book as a dynamic heterogeneous typed graph with proof-gated mutation.
Architecture
L1 Ingest → L2 Graph → L3 GNN+Attention → L4 Memory → L5 Coherence → L6 Policy
| Layer | Crate | Status | Description |
|---|---|---|---|
| L1 | neural-trader-core |
✅ PR #244 | Market event types, ingest traits, graph schema (7 event types, 10 node kinds, 12 edge kinds, 17 property keys) |
| L2 | neural-trader-graph |
🔲 Planned | Dynamic heterogeneous typed graph construction |
| L3 | neural-trader-gnn |
🔲 Planned | GNN embeddings + multi-head temporal attention |
| L4 | neural-trader-replay |
✅ PR #244 | Reservoir store with gated writes, 7 segment classifications, witness receipts |
| L5 | neural-trader-coherence |
✅ PR #244 | MinCut coherence gate, CUSUM drift detection, tiered permissions, proof-gated mutation |
| L6 | neural-trader-policy |
🔲 Planned | Policy actuation with position sizing |
| WASM | neural-trader-wasm |
✅ Done | Browser bindings — 8 classes, 6 enums, BigInt-safe serialization |
| — | neural-trader-backtest |
🔲 Planned | Historical replay and PnL tracking |
| — | neural-trader-risk |
🔲 Planned | VaR, drawdown limits, exposure caps |
| — | neural-trader-feed |
🔲 Planned | WebSocket/FIX market data adapters |
| — | neural-trader-cli |
🔲 Planned | CLI for backtesting and live trading |
Implemented Capabilities
neural-trader-core
- MarketEvent envelope: event_id, nanosecond timestamps, venue/symbol, 7 event types, side, fixed-point price/qty, order/participant hashes, flags, sequence
- Graph Schema: 10 node kinds (Symbol, Venue, PriceLevel, Order, Trade, Event, Participant, TimeBucket, Regime, StrategyState) × 12 edge kinds × 17 property keys
- GraphDelta: diff type for graph projection (nodes added, edges added, properties updated)
- StateWindow: sliding window for embedding pipelines
- Traits:
EventIngestor,GraphUpdater,Embedder
neural-trader-coherence
- ThresholdGate: regime-adaptive coherence gate with 4 tiered permissions (retrieve > write/act > learn)
- CUSUM drift detection: blocks mutations when cumulative sum exceeds threshold (default 4.5)
- Regime-adaptive floors: Calm=12, Normal=9, Volatile=6 — configurable per deployment
- Boundary stability: requires N consecutive stable windows before allowing writes (default 8)
- Drift margin: learning requires drift < 50% of max (stricter than write/act)
- VerifiedToken: proof token minted when coherence + policy approve
- WitnessReceipt: immutable audit record (timestamp, model ID, input hash, coherence hash, policy hash, action, token ID, state hash)
- WitnessLogger trait for pluggable audit backends
neural-trader-replay
- ReplaySegment: sealed window with events, embeddings, labels, coherence stats, lineage, witness hash
- 7 segment kinds: HighUncertainty, LargeImpact, RegimeTransition, StructuralAnomaly, RareQueuePattern, HeadDisagreement, Routine
- CoherenceStats + SegmentLineage: metadata for provenance tracking
- ReservoirStore: bounded VecDeque-backed memory with O(1) eviction, gated by
CoherenceDecision.allow_write - MemoryQuery: retrieve by symbol, embedding, regime, limit
- InMemoryReceiptLog: append-only witness logger for testing
neural-trader-wasm (@ruvector/neural-trader-wasm v0.1.1)
- 8 classes: MarketEventWasm, GraphDeltaWasm, GateConfigWasm, GateContextWasm, ThresholdGateWasm, CoherenceDecisionWasm, ReplaySegmentWasm, ReservoirStoreWasm
- 6 enums: EventTypeWasm(7), SideWasm(2), RegimeLabelWasm(3), SegmentKindWasm(7), NodeKindWasm(10), EdgeKindWasm(12), PropertyKeyWasm(17)
- BigInt-safe serialization via
serialize_large_number_types_as_bigints(no u64 precision loss on nanosecond timestamps) - Security hardened: non-ASCII hex rejection, 0x prefix support, zero-size store guard
- 172 KB WASM binary, 43 Node.js integration tests, Docker test runner
- ADR-086 documents type mapping and build workarounds
Key Design Decisions
- MinCut coherence gate: Tiered permissions (retrieve > write/act > learn) prevent the system from learning during volatile regimes
- CUSUM drift detection: Monitors parameter drift and blocks mutations when drift exceeds threshold
- Reservoir sampling: Bounded replay buffer with proof-gated writes — only stores experiences that pass the coherence gate
- Witness receipts: Every gated write produces a cryptographic receipt for audit trails
- BigInt timestamps: WASM bindings use BigInt-aware serialization to preserve nanosecond precision across the JS boundary
Test Summary
| Suite | Tests | Status |
|---|---|---|
| neural-trader-core | 2 | ✅ Pass |
| neural-trader-coherence | 7 | ✅ Pass |
| neural-trader-replay | 3 | ✅ Pass |
| neural-trader-wasm (Rust) | 10 | ✅ Pass |
| neural-trader-wasm (Node.js) | 43 | ✅ Pass |
| Total | 65 | ✅ All pass |
Current State
4 crates implemented with 65 passing tests (22 Rust + 43 Node.js). WASM published to npm as @ruvector/neural-trader-wasm@0.1.1.
Follow-up Work
- L2: Graph construction from order book snapshots
- L3: GNN embeddings with RuVector's existing attention crates
- L6: Policy actuation with Kelly criterion position sizing
- Backtest harness with historical LOB data
- Integration with
ruvector-graph-transformerfor graph attention - WebSocket/FIX feed adapter for live market data
- PostgreSQL integration via
ruvector-postgresSQL functions - Streaming sketch memory (Count-Min, Top-K, delta histograms)
- Cognitum edge deployment (deterministic coherence gate kernel)