siloqy/prod/docs/VIOLET_SPEC__MULTI_EXCHANGE_OB_SEAM.md

VIOLET Multi-Exchange OB Seam

Date: 2026-06-16

Scope

This note describes the new read-only OB provider seam added on the VIOLET side:

• prod/clean_arch/violet/venue_ob_provider.py
• prod/clean_arch/violet/test_violet_venue_ob_provider.py

The seam exists so VIOLET can later consume a venue-specific OB feed without changing BLUE or wiring any live exchange connection into the current shadow path.

What the seam does

• normalizes venue ticks into BLUE-shaped OBSnapshot records
• keeps the provider read-only and in-memory
• validates poison values at ingress with V-TYPES
• supports either an injected callable tick source or a preloaded buffer
• exposes the exact OBProvider interface that OBFeatureEngine expects

What it does not do

• no live BingX connection
• no Hazelcast writes
• no BLUE code changes
• no live wiring into live_blue_source.py or shadow_live_factors.py

Future adapter shape

A venue-specific live adapter can later be layered on top of this seam by feeding VenueOBTick records into VioletVenueOBProvider.refresh() from any normalized feed source. The only contract is the canonical OBSnapshot shape that OBFeatureEngine already consumes.

Validation

The companion test file checks:

• VioletVenueOBProvider implements the OBProvider surface
• malformed values are rejected at construction
• OBFeatureEngine(provider) can run step_live() and read back finite OB features
• the callable-source path loads as expected