# 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