VIOLET: master dev spec & plan + parallel L3 exchange-leverage sub-spec
VIOLET_DEV_SPEC_AND_PLAN.md: authoritative consolidated plan (mission, doctrine, V0->V6 ladder w/ status, code map, full sizing composition, next steps, vision, TODOs, operational notes). Supersedes scattered plan files. VIOLET_SUB_SPEC__L3_EXCHANGE_LEVERAGE.md: self-contained parallel-developable unit (V3.5) for an independent agent — wrap prod/bingx/leverage.py conviction->exchange mapping, V-TYPES + bit-identity gate, full file paths/tests/gates/acceptance. Zero overlap with V3.4 (DecisionEngine<->Sizing integration, lead-owned). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Codex
128
prod/docs/VIOLET_DEV_SPEC_AND_PLAN.md
Normal file
128
prod/docs/VIOLET_DEV_SPEC_AND_PLAN.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# 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** | wire VioletSizer into VioletDecisionEngine (full conviction in shadow) | ⏳ 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.
|
||||
Reference in New Issue
Block a user