siloqy/prod/docs/VIOLET_PART_SPEC_OA_TODO_PASS3.md

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

Date: 2026-06-17. Follows PASS 1 + PASS 2 (both reported done — review pending, see
`VIOLET_TODO_CRITICAL.md`). PASS 3 is drawn STRICTLY from the existing VIOLET dev plan
(`VIOLET_DEV_SPEC_AND_PLAN.md`, the V0→V6 ladder + its named deferred items) — nothing invented.
Every task is an INDEPENDENT UNIT: it can be built, tested and function on its own, and it
composes with the others ONLY through the explicit shared interfaces in §I.

---

## 0. HARD RULES (identical to PASS 1/2 — re-read those; summarized)

- **Never edit shared files** (`prod/nautilus_event_trader.py`, `clean_arch/dita_v2/**`,
  `dita/decision.py`, `nautilus_dolphin/**`, `blue_parity.py`, `prod/bingx/leverage.py`). READ only.
- **VIOLET stays DARK** — no orders, no execution, no VST keys, no service start/stop, no HZ
  restart, no PROGREEN.
- **V-TYPES on all new code** (`StrictModel` / `Annotated[…Field]` / `@typed`); faithful
  poison-guards only.
- **NEW-FILE-ONLY**; do NOT modify in-flight files: `live_blue_source.py`,
  `shadow_live_factors.py`, `live_factor_source.py`, `live_factors.py`, `decision_engine.py`,
  `sizing.py`, `shadow_journal.py`, `cadence.py`, `clock.py`, `divergence.py`,
  `22_violet_decisions.sql`. READ + IMPORT them.

## 0a. COMMIT / BRANCH POLICY (3 shared-index collisions on 2026-06-16 — take this seriously)
Own `git worktree` (`git worktree add ../vp-oa3 -b agent/oa-violet3`) STRONGLY preferred. Else
never `git add -A`; commit with explicit pathspec `git commit -F msg -- <files>` and verify
`git show --stat --format="" HEAD` lists ONLY your files. One commit per task, prefix
`VIOLET OA:`, Co-Authored-By trailer. Tests on `/home/dolphin/siloqy_env/bin/python3`. Use
`git grep` (recursive grep/find time out on CIFS).

---

## I. SHARED INTERFACES (agreed contracts — define these EXACTLY; the tasks depend on them)

These are the only coupling points between PASS-3 units. Put the type definitions in ONE new
module `prod/clean_arch/violet/contracts_v3.py` (Task 8 creates it; later tasks import it).
All are `StrictModel` / `Annotated` V-TYPES.

1. **`VenueTick`** — one normalized venue quote (exchange-agnostic):
   `asset: Symbol`, `bid: Px`, `ask: Px`, `mark: Px`, `last: Px`, `mono_ns: MonoNs`,
   `venue: str` (e.g. "BINGX","BINANCE"). All prices > 0 finite. This is the SAME normalized
   tick named in the plan's "Venue price feed port (CRITICAL gap)".
2. **`OpenPositionView`** — the minimal open-position state an exit/guard needs:
   `asset: Symbol`, `side: str` ("SHORT"/"LONG"), `entry_price: Px`, `qty: Qty`,
   `entry_ts_ns: MonoNs`, `bars_held: BarsHeld`, `tp_threshold: float` (fixed TP pct),
   `sl_threshold: float` (stop pct), `leverage: float`.
3. **`ExitDecision`** — `action: str` ("HOLD"/"EXIT"), `reason: str`
   ("FIXED_TP"/"CATASTROPHIC_SL"/"ADVSL"/"NONE"/…), `price: Px`, `priority: int`
   (CATASTROPHIC/ADVSL=0 > FIXED_TP=1 > DISCRETIONARY=2 — the plan's mandated order).

If a later task needs a field not here, ADD it to `contracts_v3.py` (and note it), never fork a
parallel type.

---

## TASK 8 — VenuePriceFeedPort + BingX adapter (DARK, data-only) [plan: "Venue price feed port (CRITICAL gap)"]

**Why.** The plan flags this as CRITICAL: OBF is Binance-wired (alpha side), but exits fill on
the EXECUTION venue, and FET showed scan-vs-BingX divergence (0.2176 vs 0.1878 = 15%). VIOLET
needs an exchange-agnostic price port. This unit delivers the port interface + a BingX adapter,
data-only (no orders).

**Affected files (NEW only):** `prod/clean_arch/violet/contracts_v3.py` (the §I types),
`prod/clean_arch/violet/venue_price_feed.py`, `prod/clean_arch/violet/test_violet_venue_price_feed.py`.

**Interface/approach.** Define `VenuePriceFeedPort` (ABC): `latest(asset) -> Optional[VenueTick]`,
`subscribe(assets)`, `close()`. Implement `BingxSwapPriceFeed(VenuePriceFeedPort)` consuming the
BingX swap WS bookTicker/markPrice (READ the existing BingX WS conventions in the repo; data-only,
no auth needed for public streams — confirm). Implement `MockPriceFeed` (deterministic, for
tests + for the other tasks). All ticks validated into `VenueTick` at ingress (poison-reject
non-finite/≤0).

**Tests / pass criteria.** Mock feed round-trips ticks as `VenueTick`; poison ticks rejected;
the BingX adapter parses a recorded/sample bookTicker frame into a correct `VenueTick` (use a
captured frame fixture, NOT a live connection in the unit test). DONE when: `VenueTick` contract
finalized, mock + adapter parse-tested, no live WS in unit tests, no edits outside the 3 files.

---

## TASK 9 — MechanicalExitGuard (armed TP/SL) [plan: LINK TP-miss structural fix]

**Why.** The plan's structural fix for the LINKUSDT −$1,248 TP-miss: TP/SL are MECHANICAL exits
owned by an exit guard with armed price thresholds set at entry; policy layers (V7/MARAS) can
only contribute DISCRETIONARY exits and can NEVER mask mechanical ones. Total priority:
CATASTROPHIC/ADVSL > fixed TP > discretionary.

**Affected files (NEW only):** `prod/clean_arch/violet/mechanical_exit_guard.py`,
`prod/clean_arch/violet/test_violet_mechanical_exit_guard.py`. (imports `contracts_v3`.)

**Interface/approach.** `MechanicalExitGuard.evaluate(pos: OpenPositionView, tick: VenueTick) ->
ExitDecision`. Pure function of position + current venue price: compute pnl_pct from
entry/side/price; if it reaches the armed `tp_threshold` → `ExitDecision(EXIT, FIXED_TP,
priority=1)`; if it breaches `sl_threshold` → `ExitDecision(EXIT, CATASTROPHIC_SL, priority=0)`;
else HOLD. Prices off the VENUE tick (not scan). No discretionary logic here — this layer is the
mechanical floor only.

**Tests / pass criteria.** SHORT + LONG: TP fires exactly at threshold, SL at stop, neither
fires inside the band; priority ordering correct (SL outranks TP if both somehow true). Hypothesis
property: output always finite, priority ∈ {0,1,2}, EXIT only when threshold crossed. DONE when:
deterministic threshold tests + property test pass, no edits outside the 2 files.

---

## TASK 10 — Sub-second catastrophic-SL / ADVSL floor guard [plan: versioned SAFETY DEVIATION]

**Why.** The plan's one sanctioned sub-second behaviour: a catastrophic-SL/ADVSL floor evaluated
at the fastest cadence against a fast price source, to fix the scan-dark unmanaged-position hazard
(XLM/FET class). "Evaluate at fastest cadence (shadow-log would-be actions), actuate at Q."

**Affected files (NEW only):** `prod/clean_arch/violet/sl_floor_guard.py`,
`prod/clean_arch/violet/test_violet_sl_floor_guard.py`. (imports `contracts_v3`, composes Task 9.)

**Interface/approach.** `SLFloorGuard(deadline_ns)` with `on_tick(pos, tick) -> Optional[ExitDecision]`
that EVALUATES every tick (sub-second) and SHADOW-LOGS would-be SL exits, but only RETURNS an
actuation when the configured fast-SL condition holds (catastrophic threshold worse than the
mechanical stop, OR ADVSL trailing breach). Track evaluate-count vs actuate-count (shadow delta).
DARK: returns the decision; never sends orders.

**Tests / pass criteria.** A tick stream that dips intra-scan triggers the fast SL evaluation and
records the would-be exit; the actuate gate fires only on the catastrophic/ADVSL condition;
evaluate-count > actuate-count proven. DONE when tests pass, no edits outside the 2 files.

---

## TASK 11 — Event-sourced restore from trade_reconstruction [plan: VIOLET restore commitment, Option C]

**Why.** The plan commits VIOLET to NEVER restore from position_state snapshots; instead replay
the chain-tokened `trade_reconstruction` OPEN/PARTIAL_EXIT/CLOSE journal. Open = ROOT OPEN with no
terminal CLOSE; size = entry − Σ legs; holding from ABSOLUTE entry_ts (kills the bars_held≈0 /
MAX_HOLD-reset class by construction); chain token verified.

**Affected files (NEW only):** `prod/clean_arch/violet/event_restore.py`,
`prod/clean_arch/violet/test_violet_event_restore.py`. (imports `contracts_v3` → emits
`OpenPositionView`s.)

**Interface/approach.** `restore_open_positions(journal_rows: list[dict]) -> list[OpenPositionView]`
— pure function over journal rows (asset, chain_root_trade_id, chain_token, leg type, qty,
realized legs, entry_ts, entry_price). Reconstruct each chain; an open position is a ROOT OPEN
with no matching terminal CLOSE; qty = entry − Σ partial-exit legs; bars_held derived from absolute
entry_ts vs now (NEVER from a stored counter). Reject chain-token mismatches to a quarantine list
(returned alongside), never crash.

**Tests / pass criteria.** Fixtures: clean open, fully-closed (→ not restored), partial-exit chain
(qty correct), chain-token mismatch (→ quarantined), dead-session entry_ts (bars_held computed
from ts, never negative). Hypothesis: qty ≥ 0, bars_held ≥ 0 always. DONE when tests pass, no
edits outside the 2 files.

---

## TASK 12 — Venue lead/lag slippage metric [plan: V1 metrics — venue lead/lag]

**Why.** The plan's continuous signed SHORT-entry slippage metric: venue fill vs Binance mid at
decision time — answers "is BingX discounting our signal". Rerunnable analysis.

**Affected files (NEW only):** `prod/clean_arch/violet/slippage_metric.py`,
`prod/clean_arch/violet/test_violet_slippage_metric.py`, report →
`prod/VIOLET_dev/reports/violet_slippage_<UTC>.json`.

**Interface/approach.** `signed_entry_slippage(decision_mid: float, venue_fill: float, side: str)
-> float` (signed bps; positive = adverse) + an aggregator over recorded rows producing a
distribution (mean/median/p95). Read-only over recorded data (CH `dolphin`/`dolphin_violet`, no
writes). Pure functions; V-TYPES the rows.

**Tests / pass criteria.** Sign convention exact for SHORT and LONG on hand-built cases; aggregator
stats correct on a synthetic fixture (`--self-test`). DONE when self-test passes + a report can be
produced on the prod host, no production writes, no edits outside the files.

---

## TASK 13 — Cadence per-action Q schedule + evaluate/actuate telemetry [plan: cadence quantizer]

**Why.** The plan's cadence quantizer: each action (SL/TP/ENTRY/OBF/ExoF) gets its own
quantization Q; evaluate at fastest cadence (shadow evidence), actuate at Q; step Q down later.
`cadence.py` (the `CadenceControlPlane`) exists; this unit adds a per-action Q-SCHEDULE LOADER +
a shadow-delta TELEMETRY recorder WITHOUT modifying `cadence.py`.

**Affected files (NEW only):** `prod/clean_arch/violet/cadence_schedule.py`,
`prod/clean_arch/violet/test_violet_cadence_schedule.py`.

**Interface/approach.** Read `cadence.py` for `Action` + `CadenceControlPlane` API. Provide
`load_q_schedule(mapping) -> dict[Action, int_ns]` (validated; the plan's initial table: SL tight,
TP=scan, ENTRY=scan, OBF~1s) and `CadenceTelemetry` that records per-action evaluate-count vs
actuate-count and emits a shadow-delta summary. Compose with `CadenceControlPlane` by wrapping its
`due()` calls (do not edit it).

**Tests / pass criteria.** Schedule loader validates/rejects bad Q values; telemetry counts
evaluate > actuate under a synthetic action stream; per-action Q honored. DONE when tests pass, no
edits outside the 2 files.

---

## Composition map (how the units fit — the "well-known interfaces")
```
Task 8 contracts_v3 (VenueTick, OpenPositionView, ExitDecision)  ← the shared vocabulary
        │
        ├── Task 8 venue_price_feed  → VenueTick stream
        ├── Task 9 mechanical_exit_guard(pos, tick) → ExitDecision        (consumes VenueTick)
        ├── Task 10 sl_floor_guard(pos, tick)       → ExitDecision        (composes Task 9)
        ├── Task 11 event_restore(journal)          → [OpenPositionView]  (feeds 9/10)
        ├── Task 12 slippage_metric(mid, fill, side)→ bps                 (uses VenueTick mids)
        └── Task 13 cadence_schedule/telemetry      → per-action Q + deltas
```
Integration (wiring these into the live reactor + decision/exit path) is the OWNER's job later,
NOT part of these units. Each ships standalone + tested.

## Recommended order
**8 (contracts + feed) → 9 (mechanical exit) → 11 (restore) → 10 (SL floor) → 13 (cadence) → 12
(slippage)**. Task 8 first because `contracts_v3.py` is the shared vocabulary everything imports.

## Still NOT in scope (operator/owner only)
DARK soak start; V4 live execution / BingX ExecutionClient; HZ-bridge refactor; the V3.4c parity
root-cause (CRITICAL #1 — Claude's review job); any edit to the in-flight files in §0.