siloqy/prod/docs/VIOLET_PART_SPEC_OA_TODO_PASS2.md

VIOLET — partial spec for another agent, PASS 2 (OA TODO)

Date: 2026-06-16. Follows VIOLET_PART_SPEC_OA_TODO.md (PASS 1, reported done — pending review). PASS 2 tasks advance the main VIOLET global spec (VIOLET_DEV_SPEC_AND_PLAN.md, the V0→V6 ladder) toward the DARK soak gate and V4 execution, while staying self-contained.

---

0. HARD RULES (identical to PASS 1 — re-read; non-negotiable)

1. Never edit shared files: prod/nautilus_event_trader.py, prod/clean_arch/dita_v2/**, prod/clean_arch/dita/decision.py, nautilus_dolphin/**, blue_parity.py, prod/bingx/leverage.py. READ only.
2. VIOLET stays DARK — no orders, no execution, no VST keys, no service start/stop, no HZ restart, no PROGREEN.
3. V-TYPES on all new code (StrictModel / Annotated[…Field] / @typed); no arbitrary caps, only faithful poison-guards.
4. NEW-FILE-ONLY — do NOT modify these in-flight files (owned by another agent right now): live_blue_source.py, shadow_live_factors.py, live_factor_source.py, live_factors.py, decision_engine.py, sizing.py, shadow_journal.py, prod/clickhouse/violet/22_violet_decisions.sql. You may READ + IMPORT them. Wiring into them is deferred to their owner.

0a. COMMIT / BRANCH POLICY (CRITICAL — 3 shared-index collisions happened 2026-06-16)

The working tree + .git/index are SHARED across agents; git commit commits the whole index, so a concurrent agent's staged files get swept into your commit. THEREFORE:

• Strongly preferred: your own worktree — git worktree add ../vp-oa2 -b agent/oa-violet2.
• Otherwise: never git add -A/git add .; commit with explicit pathspec — git commit -F msg.txt -- <your_new_file> <your_test> — and verify git show --stat --format="" HEAD lists ONLY your files.
• One commit per task, prefix VIOLET OA:, Co-Authored-By trailer. Before "done": git diff --name-only HEAD~1 ∌ any forbidden path.
• Tests on /home/dolphin/siloqy_env/bin/python3 -m pytest -q. CIFS-slow is normal. Use git grep, not recursive grep -r/find.

0b. ClickHouse access (read-only)

http://localhost:8123, user dolphin / key dolphin_ch_2026. VIOLET data in db dolphin_violet; BLUE data in db dolphin. READ ONLY — never write/alter production tables.

---

TASK 4 — Live BLUE↔VIOLET decision parity report (advances V3d → DARK-soak gate)

Spec link. The ladder's V3d step requires proving the shadow DecisionEngine reproduces BLUE's decisions. A SHADOW soak already journaled VIOLET decisions to dolphin_violet.violet_decisions. This task builds the report that compares them to BLUE's recorded decisions — the quantitative gate that makes a longer soak meaningful.

Affected files (NEW only):

• prod/clean_arch/violet/parity_report.py (new)
• prod/clean_arch/violet/test_violet_parity_report.py (new)
• output → prod/VIOLET_dev/reports/violet_parity_<UTC>.{json,md} (generated)

Approach.

• Read VIOLET decisions from dolphin_violet.violet_decisions (asset, side, scan_number, conviction_leverage, notional_fraction, target_exposure, vel_div, ts) and BLUE's recorded decisions from dolphin.trade_events / dolphin.v7_decision_events (inspect their schemas first via DESCRIBE). Align by nearest scan/timestamp + asset.
• Compute: pick-match rate (same asset/side chosen), sizing deltas (VIOLET vs BLUE conviction_leverage / notional — distribution: mean/median/p95 abs err), and a divergence-reason breakdown (no-pick, different-asset, sizing-gap > threshold).
• Pure analysis: NO writes to any production table; emit a JSON + a human-readable MD report.
• V-TYPES the report rows; reject malformed/non-finite rows to a counter (never crash).

Tests / pass criteria.

• A --self-test / unit mode runs the comparison on a SYNTHETIC fixture (hand-built VIOLET + BLUE rows with known overlaps) and asserts the computed pick-match / sizing-delta numbers exactly. No live CH needed for the unit test.
• On the prod host, the script runs end-to-end against live CH and archives a report.
• DONE when: self-test passes, a real report is archived, zero production writes, no edits outside the 2 new files.

---

TASK 5 — Full-DecisionEngine reactor latency gate (advances V0/V3 — budget proof)

Spec link. V0 proved the reactor clock meets the latency budget (reaction p99 < 10ms, jitter p99 < 25ms) with a trivial handler. V3 put the real decision brain online. This gate proves the budget STILL holds when the reactor drives the FULL VioletDecisionEngine.decide(factors=SizingFactors(...)) path (the heavy 5-factor sizing), not a stub — a prerequisite for trusting the sub-second cadence claim.

Affected files (NEW only):

• prod/clean_arch/violet/test_violet_v3_decision_latency_gate.py (new, @pytest.mark.gate)
• output → prod/VIOLET_dev/reports/violet_v3_decision_latency_<UTC>.json (generated)

Approach.

• Reuse V0's PlaneClock / DeadlineScheduler (clock.py) and the storm pattern from test_violet_v0_latency_gate.py / test_violet_v2_exec_gate.py (READ them for the harness).
• Build a warmed VioletDecisionEngine (feed enough synthetic scans to pass the IRP lookback), then in the storm loop call decide(now_ns=…, scan_number=…, capital=…, vel_div=…, factors=SizingFactors(boost=…, beta=…, mc_scale=…, esof_score=…, ob_*=…, dc_status=…, posture=…)) each tick. Measure reaction + jitter percentiles.
• Do NOT modify decision_engine.py; import + drive it.

Tests / pass criteria.

• Gate asserts reaction p99 < 10ms and jitter p99 < 25ms (same budget as V0) over ≥ 200 cycles with the FULL factor path; archive the percentile report.
• DONE when: the gate passes on the prod host, report archived, no edits outside the new file. (If it FAILS, do not loosen the budget — report the regression with numbers; that is a real finding.)

---

TASK 6 — L3 tradeability projector, standalone (advances toward V4 execution)

Spec link. The 3-layer doctrine: L1 pure alpha (done), L2 parity harness (done), L3 tradeability — impose conviction→exchange-leverage + maker policy on the L1 output. The wrapper exists (exchange_leverage.py, bit-identity-gated). This task builds the standalone projector that turns a ShadowDecision into a tradeable projection, WITHOUT wiring it into the journal or any venue (DARK; wiring is the owner's job later).

Affected files (NEW only):

• prod/clean_arch/violet/tradeability.py (new)
• prod/clean_arch/violet/test_violet_tradeability.py (new)

Approach.

• Read exchange_leverage.py (VioletExchangeLeverage, ExchangeLeverageDecision) and decision_engine.py (ShadowDecision) and the margin-study facts (notional = base_fraction × conviction × capital; exchange leverage = map_internal_conviction_to_exchange_leverage, max 3× cubic).
• Define TradeabilityProjection(StrictModel) with: internal_conviction, exchange_leverage (int, ge=1), target_notional, est_margin (= notional / exchange_leverage), maker_policy hint (string, e.g. "maker_both" — read existing ExecutionRouter conventions, do NOT import PINK exec). Define project_tradeability(decision: ShadowDecision, *, capital: float) -> TradeabilityProjection (@typed). NO orders, NO venue calls — pure projection.
• This is L1-output → L3 projection only; it must not change L1 sizing.

Tests / pass criteria.

• Exchange leverage equals exchange_leverage.py's mapping for the decision's conviction_leverage (bit-identical — reuse that wrapper, don't reimplement).
• est_margin = target_notional / exchange_leverage; poison guards reject non-finite/negative.
• Hypothesis property test over conviction ∈ [0.5, 9]: projection finite, exchange_leverage ∈ [1,3], margin ≤ notional.
• pytest -q prod/clean_arch/violet/test_violet_tradeability.py passes; no edits outside the 2 new files.

---

TASK 7 — Deterministic replay + golden gate (advances V3d determinism criterion)

Spec link. V3d also requires DETERMINISM: same recorded scans ⇒ same decisions twice. This hardens soak confidence and catches accidental nondeterminism (dict ordering, RNG, time leakage) in the decision path.

Affected files (NEW only):

• prod/clean_arch/violet/test_violet_replay_determinism_gate.py (new)
• prod/clean_arch/violet/fixtures/replay_scans.json (new, small synthetic scan sequence)

Approach.

• Build a fixed synthetic scan sequence (≥ 60 scans, a few assets incl. one stablecoin to prove the exclusion gate, varied vel_div crossing the entry threshold). Store as the fixture.
• Run it through TWO fresh VioletDecisionEngine instances (with identical fixed SizingFactors) and assert the emitted ShadowDecision sequences are EQUAL field-by-field.
• Add a golden assertion: the decision sequence matches a checked-in expected summary (asset, side, conviction_leverage, scan_number per fired decision) — regenerate-on-purpose only.
• Read decision_engine.py; do not modify it.

Tests / pass criteria.

• Two runs over the fixture produce identical ShadowDecision lists (==).
• The golden summary matches; stablecoin assets never selected.
• pytest -q prod/clean_arch/violet/test_violet_replay_determinism_gate.py passes; no edits outside the 2 new files.

---

Sequencing note

Tasks 4–7 are independent and parallelizable. Recommended priority for advancing the spec: Task 5 (latency budget) → Task 7 (determinism) → Task 4 (parity report) → Task 6 (tradeability) — the first two are gates that must hold before a longer DARK soak; Task 4 makes the soak measurable; Task 6 preps V4. None require the operator's soak/keys greenlight.

Still NOT in scope

DARK soak START (operator-held); V4 live execution (keys-blocked); HZ-bridge refactor (depends on dolphinng5_predict/hzbridge shipping); any edit to the in-flight files in §0 rule 4.