# VIOLET — Master Dev Spec & Plan

**Authoritative consolidated plan.** Supersedes the scattered plan files
(`~/.claude/plans/harmonic-jumping-plum.md` [V2], `drifting-knitting-zebra.md` [V3]).
Repo cwd `/mnt/dolphinng5_predict` (git root, **no remote — local-only, build on-host**).
Branch `exp/pink-ditav2-sprint0-20260530`. Python `/home/dolphin/siloqy_env/bin/python3`.
Last updated 2026-06-15.

Cross-refs: `VIOLET_V3_FINDINGS.md` (study + 5-factor composition §8b + vision §8c),
`VIOLET_BUILD_SPEC__SIZING_PARITY.md` (+ Annex A dev log), `FROZEN_ALGO_SPEC_GOLD_REFERENCE.md`,
memory `violet_subsecond_rebuild_plan` / `violet_v3_alpha_doctrine` / `blue_margin_envelope_study`.

---

## 1. Mission

Rebuild the DOLPHIN trading system (BLUE's live Alpha Engine) onto a sub-second
event-driven reactor substrate — **bit-for-bit faithful to BLUE's alpha**, but on a
chassis that is type-safe, observable, attributable, and trustworthy (the original's
alpha is fund-grade; its bookkeeping is not). Stage the rebuild V0→V6; each stage is
existing/wrapped code + new wiring, gated.

## 2. Binding doctrine

- **Model BLUE, not PINK.** Reference = BLUE's LIVE Alpha Engine (`prod/nautilus_event_trader.py`
  + `nautilus_dolphin/nautilus_dolphin/nautilus/*`). Behavioural/distributional fidelity.
- **Live BLUE code is the sole doctrine**; where it diverges from any doc/spec, BLUE wins.
  `blue_parity.py` is a PINK-era distillation — reference only, validate don't trust.
- **WRAP, DON'T REIMPLEMENT.** Run BLUE's real kernels; transcribe only trivial deterministic
  arithmetic, and prove it with **Monte-Carlo → bit-identity → upstream** gates.
- **Follow BLUE in all regards** — no filters/hygiene/bounds BLUE lacks (only V-TYPES poison
  rejection: finite + non-negative where BLUE guarantees it).
- **V-TYPES** (`prod/clean_arch/violet/domain.py`): refined types at boundaries, `@typed`
  (beartype), `StrictModel` value objects, reject-at-source. Motivated by the bars_held=-106
  poison incident.
- **Reactor substrate, NOT a scan clone.** BLUE's scan-quantized behaviour is hosted on the
  V0 reactor and quantized at **Q=scan initially**; per-action Q loosenable later (cadence
  control plane). Scan-driven-ness is a quantization setting, not the architecture.
- **Decision layer is slot-independent** — VIOLET decides every scan; the slot only gates
  trades (execution layer). Different layers.
- **DARK until keys** — no orders until operator provisions VST keys; ObserveOnlyVenue guard.

## 3. Stage ladder (V0→V6)

| Stage | Scope | Status |
|---|---|---|
| **V0** | reactor clock + DeadlineScheduler + harness | ✅ shipped (latency gate passed) |
| **V1** | observe-only DARK service + divergence monitor + CH DDLs | ✅ shipped |
| **V2** | ExecDeadlineDriver @100ms TTL + ScriptedVenue + V-TYPES domain | ✅ shipped (gate passed) |
| **V3** | DecisionEngine SHADOW (models BLUE) | ✅ shipped |
| ↳ V3a | alpha_wrappers (selector/sizer/exit-v7) | ✅ |
| ↳ V3b | cadence control plane (per-action Q) | ✅ |
| ↳ V3c | VioletDecisionEngine (reactor-resident shadow) | ✅ |
| ↳ V3d | base-sizer parity gate | ✅ |
| ↳ V3e | shadow journal + DDL + launcher wiring | ✅ |
| ↳ V3.1 | BLUE stablecoin exclusion (parity fix) | ✅ |
| ↳ V3.2 | EsoF size-modulation fold | ✅ |
| ↳ V3.3 | **full sizing parity** (orchestrator wrap-all, 5-factor, bit-identity) | ✅ reviewed+committed |
| **V3.4** | integrate VioletSizer into VioletDecisionEngine (full conviction + breakdown, additive via SizingFactors) | ✅ done (engine-side) |
| **V3.4b** | launcher: source live factors (ACB/EsoF/OB/dc/posture from HZ) → SizingFactors; journal breakdown (DDL) → re-soak DARK | ⏳ NEXT (mine) |
| **V3.5** | L3 exchange-leverage wrapper (conviction→exchange, bit-identity vs leverage.py) | ⏳ parallel-able (see SUB_SPEC) |
| **V4** | execution ON — single asset, conservative caps, VST testnet → mainnet | ⏳ blocked on keys + V3.4/3.5 |
| **V5** | IRP multi-asset + sizer | later |
| **V6** | full bible layers (posture/vol refinements) + sub-second SL guard | later |

## 4. What's shipped — code map (`prod/clean_arch/violet/`)

`clock.py` (V0) · `harness.py` (V0) · `domain.py` (V-TYPES) · `divergence.py` (V1) ·
`observe_guard.py` (V1) · `cadence.py` (V3b) · `alpha_wrappers.py` (V3a: VioletBetSizer/
VioletAssetSelector/VioletExitEngine) · `decision_engine.py` (V3c: VioletDecisionEngine
+ STABLECOIN_SYMBOLS) · `parity_harness.py` (V3d) · `shadow_journal.py` (V3e) ·
`modulation.py` (V3.2: VioletSizeModulation EsoF fold) · `sizing.py` (V3.3: **VioletSizer**
— the full 5-factor conviction). DDLs in `prod/clickhouse/violet/`. Launcher
`prod/launch_dolphin_violet.py`. Tests: `test_violet_*.py` (V0–V3.3, incl. bit-identity gates).

## 5. The full sizing composition (authoritative)

BLUE's conviction = five multipliers on the base cubic, composed in `esf_alpha_orchestrator`
`:600-619` (see `VIOLET_V3_FINDINGS.md §8b`). `VioletSizer.compose` reproduces it bit-for-bit:
```
raw = base_leverage × dc_lev_mult × regime_size_mult[ACB_boost×(1+β·s³)×mc_scale] × market_ob_mult × esof_mult
clamped_max = min(base_max(8) × regime × ob × esof, abs_max(9)); STALKER → min(·,2.0)
leverage = max(min_leverage, min(raw, clamped_max));  notional = capital × fraction × leverage
```
Verified: 1e6 MC + 200k extreme + real-`_try_entry` bit-identity (0 mismatches). Operator's
two recalled "factors aside ACBv6" = `dc_lev_mult` (DC boost) + `market_ob_mult` (OB consensus).

## 6. Immediate next (V3.4 — mine) + parallelizable (V3.5 — agent)

**V3.4 (I take this):** integrate `VioletSizer` (V3.3) into `VioletDecisionEngine` (V3c) so
the shadow journal records the FULL conviction (currently base-only). Wire the live factor
inputs: ACB boost/beta (`AdaptiveCircuitBreaker.get_dynamic_boost_from_hz`), mc_scale,
esof_score, OB market consensus, dc_status, posture — sourced alongside the scan in the
launcher's shadow path. Extend `shadow_journal` / `violet_decisions` DDL with the breakdown.
Re-soak DARK, compare full-conviction shadow vs BLUE trades.

**V3.5 (PARALLEL — independent agent):** L3 exchange-leverage wrapper — isolated, additive,
bit-identity-gated against `prod/bingx/leverage.py`. Full sub-spec:
`VIOLET_SUB_SPEC__L3_EXCHANGE_LEVERAGE.md`. No overlap with V3.4 (different file/concern).

## 7. Long-horizon (post-V4, after live testnet→mainnet)

Vision in `VIOLET_V3_FINDINGS.md §8c`: pure-dataflow-DAG → compile (separation-of-concerns
AND FPGA-purity, bridged by bit-identity); VIBRISS millions-of-instances banditry; **LONG
alpha** as a new pure lane; **DISTRACK** (memory-constant streaming distributions — the
state-side enabler) sequenced AFTER VIOLET trades live.

## 8. Open TODOs (memory `violet_v3_alpha_doctrine`)

(a) review `FLAT_VEL_DIV_BUGFIX_CRITICAL.md` + the out-of-range-vel_div-signal research doc;
(b) **fix Argos** (MCP disconnected all session — Grep/Read fallback in use);
(c) DISTRACK (after live); plus the V3.3-review minor: `size()` recomputes clamp/raw outside
`compose()` (DRY — could drift); episode-collapse trade-granularity comparison (when VIOLET
has exec facilities); base-fraction sizing study (`VIOLET_STUDY_SPEC__BASE_FRACTION_SIZING.md`).

## 9. Operational notes

- **Soak control:** `supervisorctl -c prod/supervisor/dolphin-supervisord.conf {start|stop} dolphin_violet`.
  Stop is graceful (stopwaitsecs=30, stopasgroup). Shadow on via `DOLPHIN_VIOLET_DECISION_SHADOW=1`
  in the conf env (currently set; soaker STOPPED 2026-06-15 per hygiene). **Leave no soaker
  running unattended — bring down gracefully.**
- **ClickHouse:** `http://localhost:8123`, user `dolphin` / key `dolphin_ch_2026`. BLUE data
  in db `dolphin` (trade_events, eigen_scans, maras_fingerprint, exf_data, v7_decision_events);
  VIOLET in db `dolphin_violet`.
- **Eigenvalues data** (for live ACB): `/mnt/dolphin_training/data/eigenvalues` (auto-resolved).
- **Gate reports:** `prod/VIOLET_dev/reports/`.
- **Shared files — NEVER edit:** `prod/nautilus_event_trader.py`, `prod/clean_arch/dita_v2/*`,
  `prod/clean_arch/dita/decision.py`, `nautilus_dolphin/**`, `blue_parity.py`. Mechanical
  per-commit check: `git diff --cached --name-only` ∌ those.