diff --git a/prod/docs/RECENT_VIOLET_34C_a632c59.md b/prod/docs/RECENT_VIOLET_34C_a632c59.md new file mode 100644 index 0000000..829e491 --- /dev/null +++ b/prod/docs/RECENT_VIOLET_34C_a632c59.md @@ -0,0 +1,165 @@ +# 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 +