siloqy/prod/docs/VIOLET_PART_SPEC_OA_TODO.md

# VIOLET — partial spec for another agent (OA TODO)

Date: 2026-06-16. Carved from the VIOLET dev plan: the pending items that are
**self-contained** — a separate agent can complete each WITHOUT touching another
agent's in-flight files, with clear tests + pass criteria.

---

## 0. HARD RULES (apply to every task below — non-negotiable)

1. **Never edit shared files.** Forbidden to modify: `prod/nautilus_event_trader.py`,
   `prod/clean_arch/dita_v2/**`, `prod/clean_arch/dita/decision.py`, `nautilus_dolphin/**`,
   `prod/clean_arch/dita_v2/blue_parity.py`, `prod/bingx/leverage.py`. You may READ them.
2. **VIOLET stays DARK** — no orders, no live execution, no VST keys. No starting/stopping
   services. No Hazelcast restart. No PROGREEN.
3. **V-TYPES on all new code** — `StrictModel` / `Annotated[... Field]` / `@typed` (beartype)
   per `prod/clean_arch/violet/domain.py`. No arbitrary magnitude caps; only faithful
   poison-guards (finite / non-negative where BLUE guarantees it).
4. **Each task below is NEW-FILE-ONLY** by design — do NOT modify these in-flight files
   (another agent owns them right now): `live_blue_source.py`, `shadow_live_factors.py`,
   `live_factor_source.py`, `decision_engine.py`, `sizing.py`. Add new modules/tests instead.

## 0a. COMMIT / BRANCH POLICY (read this — three shared-index collisions happened on 2026-06-16)

Multiple agents share ONE working tree + ONE `.git/index` on this box. `git commit` commits
the ENTIRE index, so a concurrent agent's staged files get swept into your commit (one landed
in forbidden `dita_v2/`). Therefore:

1. **Work in your own `git worktree`** if at all possible:
   `git worktree add ../vp-oa -b agent/oa-violet` and do ALL work there. This makes collisions
   impossible. (See `prod/docs/VIOLET_OB_FEED_AND_AGENT_COORDINATION.md` §3.)
2. **If you must share the working tree**, NEVER `git add -A` / `git add .`. Stage your exact
   files, and commit with an explicit pathspec so only your paths are committed:
   `git commit -F msg.txt -- path/to/your_new_file.py path/to/your_test.py`
   Verify after every commit: `git show --stat --format="" HEAD` must list ONLY your files.
3. **One commit per task**, message prefix `VIOLET OA:`; end with the Co-Authored-By trailer.
   Before reporting done: `git diff --name-only HEAD~1` ∌ any forbidden shared path.
4. **Run tests on the prod interpreter**: `/home/dolphin/siloqy_env/bin/python3 -m pytest -q`.
   The mount is CIFS-slow (a 30-test file ≈ 60-150s); that is normal, not a hang. Use
   `git grep` (not recursive `grep -r`/`find`, which time out at ~2min).

---

## TASK 1 — Parity-pin tests for the hand-replicated sizing arithmetic

**Why.** `prod/clean_arch/violet/sizing.py` hand-transcribes BLUE arithmetic from
`esf_alpha_orchestrator.py` (regime_size_mult :898-909, market_ob_mult :587-595,
strength_cubic :872-885, the 5-factor compose :600-619). The `@gate` Monte-Carlo proves the
COMPOSED leverage bit-identical, but there is no PER-FORMULA pin that fails loudly if BLUE
changes one factor's formula. This task adds those pins. See
`prod/docs/VIOLET_BLUE_PARITY_STRUCTURAL_DIVERGENCE.md` (mitigation #1).

**Affected files (NEW only):**
- `prod/clean_arch/violet/test_violet_sizing_parity_pin.py` (new)

**Approach.**
- Import BLUE's real `NDAlphaEngine` from `nautilus_dolphin.nautilus.esf_alpha_orchestrator`
  (READ-only use; construct a minimal instance with default ENGINE_KWARGS-equivalent params).
- For a sampled grid of inputs (vel_div ∈ [-0.06, 0], boost ∈ [1,3], beta ∈ {0.2,0.8},
  mc_scale ∈ {0.5,1.0}, ob (median_imbalance, agreement_pct) over a grid, dc_status ∈
  {NONE,CONFIRM}, posture ∈ {APEX,STALKER}), drive BLUE's engine to compute each intermediate
  (`_day_*` state → `_update_regime_size_mult`; the OB block; `_strength_cubic`) and assert
  VIOLET's `VioletSizer.regime_size_mult / market_ob_mult / strength_cubic / dc_lev_mult`
  return the EXACT same float (`==`, not approx — these are deterministic).
- If a BLUE method is not callable in isolation (needs engine state), set the minimal `_day_*`
  attributes directly and call the method; document any state you had to set.

**Tests / pass criteria.**
- New test file: every parametrized case asserts exact equality VIOLET-replica == BLUE-method.
- `pytest -q prod/clean_arch/violet/test_violet_sizing_parity_pin.py` → all pass.
- The existing `@gate` composition test still passes (don't change sizing.py).
- DONE when: ≥ 200 grid points per formula, zero mismatches, no edits outside the new test file.

---

## TASK 2 — Multi-exchange OB provider seam (scaffold + interface, NOT wired live)

**Why.** VIOLET currently reads BLUE's extant Binance-reference OB via `HZOBProvider`. The spec
requires being able to run a SEPARATE OB stream later (BingX testnet / 3rd-party venues have
genuinely different order books). The `OBProvider` behind `OBFeatureEngine` is the swap seam.
This task defines + tests that seam as a new module, WITHOUT wiring it into the live path
(wiring is owned by the in-flight `live_blue_source` / `shadow_live_factors`).

**Affected files (NEW only):**
- `prod/clean_arch/violet/venue_ob_provider.py` (new)
- `prod/clean_arch/violet/test_violet_venue_ob_provider.py` (new)
- `prod/docs/VIOLET_SPEC__MULTI_EXCHANGE_OB_SEAM.md` (new short design note)

**Approach.**
- Read `nautilus_dolphin/nautilus_dolphin/nautilus/ob_provider.py` (the `OBProvider` ABC +
  `OBSnapshot`) and `hz_ob_provider.py` (BLUE's reference impl) to learn the exact interface
  (`get_snapshot`, `get_assets`, `get_all_timestamps`, `get_snapshot_count`, snapshot fields:
  bid/ask notional+depth arrays of length 5, timestamp, asset).
- Define `VioletVenueOBProvider(OBProvider)` — a venue-agnostic provider that takes a normalized
  tick source (NOT a live WS yet; accept an injected callable / in-memory buffer). Produce
  `OBSnapshot`s with the SAME shape BLUE expects so it drops into `OBFeatureEngine` unchanged.
- Include a `MockTickVenueOBProvider` for tests (deterministic snapshots). Do NOT open any real
  exchange connection. V-TYPES on the normalized tick (5-level arrays non-negative, finite).
- Design note documents: the seam, how a future BingX WS adapter plugs in, and that wiring into
  `_source_ob_market` is deferred to the owner of `live_blue_source.py`.

**Tests / pass criteria.**
- `VioletVenueOBProvider` conforms to `OBProvider` (all abstract methods implemented; an
  `OBFeatureEngine(provider)` can `step_live` + `get_market` over mock snapshots without error).
- Poison rejection: negative/NaN depths or wrong-length arrays are rejected at construction.
- `pytest -q prod/clean_arch/violet/test_violet_venue_ob_provider.py` → all pass.
- DONE when: the provider drives a real `OBFeatureEngine` to a finite `get_market` result in a
  test, no live connections, no edits outside the 3 new files.

---

## TASK 3 — Base-fraction sizing study (analysis + report; no production code change)

**Why.** The base sizing fraction (0.20) is a champion constant; a study was specced but not
run (`prod/docs/VIOLET_STUDY_SPEC__BASE_FRACTION_SIZING.md` — READ it first; it is the
authority for scope/method). This is a pure analysis task producing a report — zero behavior
change — so it is fully parallelizable.

**Affected files (NEW only):**
- `prod/VIOLET_dev/studies/base_fraction_study.py` (new analysis script)
- `prod/VIOLET_dev/reports/base_fraction_study_<UTC>.md` or `.json` (new report output)

**Approach.**
- Follow the existing study spec exactly. Use recorded data only (CH `dolphin_violet` /
  `dolphin` read-only via `http://localhost:8123`, user `dolphin` / key `dolphin_ch_2026`).
  Do NOT write to any production table. Do NOT change `sizing.py` / `decision_engine.py`.
- Compute the requested sensitivity (PnL / drawdown / capital-utilization vs base_fraction over
  the spec's grid), honoring the leverage caps (base_max=8, abs_max=9) and the margin-study
  findings (notional = 0.20 × conviction × capital today).
- Output a report with the recommended base_fraction + evidence; flag any caveats. Recommend,
  do NOT apply.

**Tests / pass criteria.**
- The script runs end-to-end on the prod host and writes a report to `prod/VIOLET_dev/reports/`.
- A small `pytest` (or `--self-test` mode) validates the core computation on a synthetic fixture
  (deterministic input → known output), so the math is checkable without live data.
- DONE when: report archived + self-test passes + no production table writes + no code-behavior
  change.

---

## What is intentionally NOT in this spec (do not start these)

- **DARK soak start** — HELD for the operator's explicit word.
- **V4 live execution** — blocked on VST keys; operator-gated.
- **HZ Bridge refactor** (`TODO_HZBRIDGE`) — depends on `dolphinng5_predict/hzbridge` shipping
  (owned by another agent); not self-contained yet.
- **Edits to `live_blue_source.py` / `shadow_live_factors.py` / `sizing.py` / `decision_engine.py`**
  — in-flight; coordinate before touching.