VIOLET OA: partial spec for a parallel agent (3 self-contained, new-file-only tasks)

VIOLET_PART_SPEC_OA_TODO.md carves the self-contained pending items from the VIOLET plan so a
separate agent can work without colliding with in-flight files:
  1. Parity-pin tests for sizing.py's hand-replicated arithmetic (regime/ob/strength/dc) vs the
     real NDAlphaEngine methods — test-only.
  2. Multi-exchange OB provider seam (VioletVenueOBProvider scaffold + interface + design note)
     — the BingX/3rd-party swap point, NOT wired live.
  3. Base-fraction sizing study (analysis script + report) — pure read-only analysis, no
     behavior change.
Each task: exact affected (new-only) files, V-TYPES + DARK + never-touch-shared rules, required
tests + pass criteria. Includes an explicit COMMIT/BRANCH policy (own git worktree, or partial
commits with `git commit -- <paths>`) prompted by today's three shared-index collisions.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

prod/docs/VIOLET_PART_SPEC_OA_TODO.md

@@ -0,0 +1,149 @@
+# 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.