siloqy/prod/docs/VIOLET_DEV_SPEC_AND_PLAN.md

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.