siloqy/prod/docs/RECENT_VIOLET_34C_a632c59.md

# RECENT_VIOLET_34C_a632c59

## What This Work Was

This change completed the first V3.4c VIOLET-side mirror for BLUE live-factor
inputs.

The goal was not to modify BLUE. The goal was to make VIOLET read the same live,
published BLUE surfaces and reconstruct the same intermediate factors BLUE would
see, without changing BLUE code, schemas, or state layout.

## Scope

This work stayed inside VIOLET and added a read-only live-source adapter plus
tests:

- `prod/clean_arch/violet/live_blue_source.py`
- `prod/clean_arch/violet/test_violet_live_blue_source.py`

It also reused the existing V3.4b live-factor helpers:

- `prod/clean_arch/violet/live_factor_source.py`
- `prod/clean_arch/violet/live_factors.py`
- `prod/clean_arch/violet/alpha_wrappers.py`

## Why This Was Needed

The earlier V3.4b adapter could source only the BLUE-published pieces that were
already directly available in Hazelcast:

- `posture`
- `esof_score`

The remaining sizing inputs were not flat HZ scalars. They had to be mirrored
from the same BLUE inputs and kernels that generate them:

- `boost` / `beta` from the ACB output
- `mc_scale` from MC-Forewarner status
- `ob_median_imbalance` / `ob_agreement_pct` from live OB data
- `dc_status` from the signal generator

The V3.4c step is the read-only, VIOLET-side reconstruction of those live
factors.

## What Was Added

### 1. Live BLUE source adapter

`live_blue_source.py` now:

- reads `DOLPHIN_STATE_BLUE.latest_nautilus` / `engine_snapshot`
- reads `DOLPHIN_FEATURES.esof_latest` / `esof_advisor_latest`
- reads `DOLPHIN_FEATURES.acb_boost`
- reads `DOLPHIN_FEATURES.mc_forewarner_latest`
- reads live OB shard maps from `DOLPHIN_FEATURES.asset_*_ob`
- reconstructs `dc_status` from the published scan stream

The module stays read-only. It does not write Hazelcast. It does not call BLUE
internals for mutation. It only mirrors what BLUE already published.

### 2. Stateful scan replay for DC

`LiveBlueScanHistory` was added to keep a per-asset price history on the VIOLET
side. This is needed because BLUE’s `dc_status` is derived from the live scan
sequence and a short price history, not from a single HZ scalar.

The adapter now:

- ingests each `latest_eigen_scan`
- keeps the asset histories in memory
- uses BLUE’s own `AlphaSignalGenerator`
- produces the same DC status labels that BLUE would emit

### 3. Read-only OB mirror

`HazelcastOBProvider` was added so VIOLET can feed BLUE’s own
`OBFeatureEngine` from the live `asset_*_ob` entries already published in HZ.

That lets the VIOLET path derive:

- `ob_median_imbalance`
- `ob_agreement_pct`

without inventing a new OB schema or mutating BLUE.

### 4. Asset selection parity

The adapter now uses `VioletAssetSelector` on the replayed scan history so the
selected asset is not guessed from the current scan payload alone.

That matters because the exact factor sequence must track the same information
BLUE would have at that point in the scan stream.

## Exactness Rules Followed

The implementation was kept conservative:

- no BLUE file edits
- no BLUE schema changes
- no new HZ writers
- no invented factor names
- no silent fallback to fake live values when the live source exists

If input is malformed, the adapter rejects or neutralizes it instead of
poisoning the history.

Examples of handled anomalies:

- missing `assets`
- non-finite prices
- negative prices
- malformed JSON payloads
- missing `posture`
- missing `esof` payloads
- broken OB payloads

## Tests Added

The new test file covers three layers:

### Unit tests

- OB shard parsing from HZ payloads
- neutral handling for malformed ACB / ESOF / MC payloads
- scan replay ingestion
- DC preservation for `CONFIRM`
- DC preservation for `SKIP_CONTRADICT`

### Sequence parity tests

The new sequence test walks multiple scan events and checks that VIOLET tracks:

- the BLUE asset selector output
- the BLUE signal-generator `dc_status`

at each step in the replayed scan history.

### End-to-end smoke

A live Hazelcast smoke test reads the current cluster state and verifies the
adapter can build a typed `SizingFactors` object from the live BLUE surfaces.

## Result

The V3.4c mirror now reconstructs the full live factor plane on the VIOLET
side, read-only, with parity-style coverage around the intermediate factor
computation.

## Verification

Commit:

- `a632c59` — `VIOLET V3.4c: read-only BLUE live source parity`

Tests run:

- `prod/clean_arch/violet/test_violet_live_blue_source.py`
- `prod/clean_arch/violet/test_violet_live_factor_source.py`
- `prod/clean_arch/violet/test_violet_live_factors.py`

Observed result:

- V3.4c source tests passed
- existing V3.4b live-factor tests passed