# VIOLET — partial spec for another agent, PASS 5 (OA TODO): MOCK-BINGX EXECUTION STACK

Date: 2026-06-17. Continues PASS 1–4 (same V0→V6 plan, same independent-unit discipline). PASS 5
builds the **mock-BingX execution stack** — the DARK path that lets the ENTIRE order lifecycle
(submit → ack → fill/partial/reject → reconcile → position/PnL) be built and bit-tested with
**zero keys, zero risk**, so that V4-live later becomes "swap the mock adapter for the real BingX
client." This is the largest remaining buildable-while-DARK chunk of the spec.

**Read first:** the V2 execution work already shipped — `prod/clean_arch/violet/scripted_venue.py`,
`exec_driver.py`, `exec_harness.py`, `observe_guard.py`, `synthetic_intents.py`,
`exchange_leverage.py`, and PINK's `prod/clean_arch/runtime/pink_direct.py` +
`prod/clean_arch/exec/` ExecutionRouter (READ for maker/taker policy conventions; do NOT edit).
PASS 5 extends, does not replace, these.

---

## ⚠️ ⚠️ READ THIS FIRST — EXCHANGE "QUIRKS" ARE EXPLICITLY OUT OF SCOPE FOR PASS 5 ⚠️ ⚠️

The mock built here implements BingX's **NORMATIVE / documented** semantics only (clean order
lifecycle, fills, leverage, reduce-only, maker/taker, partials). BingX has a substantial set of
**undocumented / edge "quirks"** that broke PINK in production. They are **NOT to be implemented
or worked around during PASS 5.** Two hard requirements instead:

1. **The mock MUST be structured with explicit INJECTION SEAMS** so each quirk can later be turned
   on (a `QuirkProfile` config + hook points) to test the reconcile/filter logic against it —
   WITHOUT rewriting the mock.
2. **A real-key smoke at the venue boundary remains MANDATORY before V4-live** — a mock can only
   validate logic, never undocumented venue reality.

### Known BingX quirks to ACCOMMODATE-LATER (do NOT implement now; just leave seams + a registry):
Source: memory `project_pink_orphan_fixes`, `ditav2_kernel_audit_20260611`, `incident_*`.
1. **Zero-wallet-balance WS frames** — BingX transiently pushes account/position frames with
   `walletBalance=0`; treating them as truth zeroes capital. (Reconcile must ignore zero-wb / use
   reseed-on-update.) Seam: mock can emit a zero-wb frame on demand.
2. **Ownership / foreign-fill collision** — fills/orders for OTHER subaccounts appear on a shared
   user-data stream (PRODGREEN↔PINK shared-account hazard); must be filtered by ownership. Seam:
   mock can emit a fill tagged with a foreign `ownership_id`.
3. **Bound-price poison** — orders carry a "bound" price; using it for PnL instead of the actual
   fill price poisons accounting. Seam: mock fill carries both bound and fill price; PnL must use
   fill price (Task 23).
4. **×leverage notional** — BingX reports notional/qty with leverage applied; double-applying
   leverage corrupts size. Seam: documented in the Fill→position reducer (Task 23).
5. **Settle / funding desync** — settlement & funding events arrive desynced from fills; capital
   deltas must be `event_seq`-ordered (ties to PASS-4 economics ledger). Seam: mock can interleave
   a settle event out of fill order.
6. **Reduce-only edge** — a reduce-only order that would INCREASE the position is rejected by
   BingX. Implement this ONE as normative (it is documented), but note the partial/zero-qty edge.
7. **setLeverage race** — `setLeverage` is a separate call with its own ack; a race vs the order
   can apply the wrong leverage. Seam: mock `set_leverage` is a distinct, separately-ackable op.
8. **Dead `.pro` TLS WS backup** — the `.pro` WS endpoint TLS can die silently (connection-layer).
   Out of mock scope (connection layer); note for the real-client adapter.

A new file `prod/clean_arch/violet/exec/bingx_quirks.py` holds ONLY a `QuirkProfile`
(StrictModel, all quirks default OFF) + an enum registry of the above — the seam contract. No
quirk LOGIC. Tasks below reference `QuirkProfile` at their hook points but implement none.

---

## 0. HARD RULES (identical to PASS 1–4 — 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.
  (You MAY read `prod/clean_arch/exec/**` + `pink_direct.py` for router/venue conventions; do not edit.)
- **VIOLET DARK** — the mock NEVER touches a real venue, network, or key. No service/HZ control.
- **V-TYPES on all new code**; faithful poison-guards only.
- **NEW-FILE-ONLY** under a NEW package `prod/clean_arch/violet/exec/` (plus extending
  `contracts_v3.py`). Do NOT modify in-flight files (the V3.4 sourcing/engine set, `cadence.py`,
  `clock.py`, `exchange_leverage.py`, `scripted_venue.py`, `exec_driver.py`, `22_violet_decisions.sql`).
  READ + IMPORT them.

## 0a. COMMIT / BRANCH POLICY (3 shared-index collisions on 2026-06-16 — non-negotiable)
Own `git worktree` (`git worktree add ../vp-oa5 -b agent/oa-violet5`) strongly preferred. Else
never `git add -A`; `git commit -F msg -- <files>` with explicit pathspec; verify
`git show --stat --format="" HEAD` lists ONLY your files. One commit/task, prefix `VIOLET OA:`,
Co-Authored-By trailer. Tests on `/home/dolphin/siloqy_env/bin/python3`. `git grep` only.

---

## I. SHARED INTERFACE EXTENSIONS (add to `contracts_v3.py`; never fork a parallel type)
Reuse PASS-3/4 types (`VenueTick`, `OpenPositionView`, `ExitDecision`, `ExecIntent`,
`CapitalState`). ADD the execution vocabulary (all `StrictModel` / `Annotated` V-TYPES):
1. **`OrderType`** = Literal["MAKER","TAKER"]; **`OrderSide`** = Literal["BUY","SELL"];
   **`OrderStatus`** = Literal["NEW","ACK","PARTIALLY_FILLED","FILLED","CANCELED","REJECTED"].
2. **`Order`** — `client_order_id: str`, `asset: Symbol`, `side: OrderSide`, `qty: Qty`,
   `price: Px` (limit; maker), `order_type: OrderType`, `reduce_only: bool`,
   `leverage: Annotated[int, Field(ge=1)]`, `ts_ns: MonoNs`.
3. **`OrderAck`** — `client_order_id: str`, `venue_order_id: str`, `status: OrderStatus`,
   `ts_ns: MonoNs`, `reject_reason: str = ""`.
4. **`Fill`** — `venue_order_id: str`, `asset: Symbol`, `side: OrderSide`, `fill_qty: Qty`,
   `fill_price: Px`, `bound_price: Px` (quirk #3 seam — carry it, never use it for PnL),
   `fee: float (ge=0)`, `is_maker: bool`, `ownership_id: str` (quirk #2 seam),
   `event_seq: Seq`, `ts_ns: MonoNs`.
5. **`PositionDelta`** — `asset: Symbol`, `qty_delta: float`, `realized_pnl_delta: float`,
   `fee: float (ge=0)`, `event_seq: Seq` — the unit that feeds PASS-4 `EconomicsLedger`.

If a task needs another field, ADD it here and note it.

---

## TASK 20 — Execution contracts + QuirkProfile seam registry
**Why.** The shared execution vocabulary + the quirk-seam contract everything else depends on.
**Affected files (NEW):** extend `prod/clean_arch/violet/contracts_v3.py` (the §I types);
`prod/clean_arch/violet/exec/__init__.py`; `prod/clean_arch/violet/exec/bingx_quirks.py`
(`QuirkProfile` StrictModel, all flags default False + the quirk enum registry — NO logic);
`prod/clean_arch/violet/exec/test_violet_exec_contracts.py`.
**Pass criteria.** All types construct + poison-reject (negative qty, non-finite price, etc.);
`QuirkProfile()` defaults every quirk OFF; the enum lists exactly the 8 quirks above. No logic in
`bingx_quirks.py`. No edits outside the new/extended files.

## TASK 21 — Mock BingX order FSM
**Why.** The deterministic order lifecycle state machine — the heart of the mock.
**Affected files (NEW):** `prod/clean_arch/violet/exec/order_fsm.py`,
`prod/clean_arch/violet/exec/test_violet_order_fsm.py`.
**Interface/approach.** `OrderFSM` holds per-order state; legal transitions only:
NEW→ACK→{PARTIALLY_FILLED*→FILLED | CANCELED | REJECTED}. `submit(order)->OrderAck`,
`apply_fill(venue_order_id, fill_qty, fill_price)->(OrderStatus, Fill)`, `cancel(...)`. Illegal
transitions raise/reject (never silently). Reduce-only that would increase position → REJECTED
(quirk #6, normative). Partial fills accumulate; FILLED only when cumulative == order qty.
Monotonic `event_seq`. Pure/in-memory; deterministic (no wall clock — caller passes ts_ns).
**Pass criteria.** Full-fill, multi-partial→fill, cancel-after-partial, reject (reduce-only
increase), illegal-transition rejection; Hypothesis: cumulative fill ≤ order qty always; event_seq
strictly increasing. No edits outside the 2 files.

## TASK 22 — Mock BingX venue adapter (port-conformant, quirk-seamed)
**Why.** The venue itself: a `MockBingxVenue` implementing the execution-venue port so the router
/ driver can drive it exactly like the real one — but deterministic + DARK.
**Affected files (NEW):** `prod/clean_arch/violet/exec/mock_bingx_venue.py`,
`prod/clean_arch/violet/exec/test_violet_mock_bingx_venue.py`.
**Interface/approach.** Define `ExecutionVenuePort` (ABC) if one isn't already agreed: `set_leverage(asset,
lev)->OrderAck` (quirk #7 seam — separate ackable op), `submit(order)->OrderAck`,
`cancel(client_order_id)->OrderAck`, `poll_fills()->list[Fill]`, `close()`. Implement
`MockBingxVenue(fill_model, quirks: QuirkProfile = QuirkProfile())` over `OrderFSM`. Fill model is
INJECTABLE (`ScriptedFillModel` for tests: immediate full / N-partials / reject / maker-vs-taker).
Maker orders fill at limit price; taker at a provided reference (VenueTick.ask/bid). Fee = maker vs
taker rate (read the router's rate conventions; pass rates in, don't hardcode a venue-specific
number). **Quirk hooks present but inert:** when `quirks.zero_wb`/`foreign_fill`/`settle_desync`
are False (default) behave normatively; the hook points exist for a later quirk-injection pass.
**Pass criteria.** A `ScriptedFillModel` drives submit→ack→fill→FILLED; partial sequence;
reject; maker vs taker fill price + fee differ correctly; `set_leverage` acks independently;
with default `QuirkProfile()` NO quirk behaviour occurs. No live network. No edits outside the 2 files.

## TASK 23 — Fill → position/PnL reducer (fill-price PnL, ×leverage-aware)
**Why.** Turn `Fill`s into `PositionDelta`s correctly — the accounting seam where bound-price
poison (#3) and ×leverage (#4) would bite. Feeds PASS-4 `EconomicsLedger`.
**Affected files (NEW):** `prod/clean_arch/violet/exec/fill_reducer.py`,
`prod/clean_arch/violet/exec/test_violet_fill_reducer.py`.
**Interface/approach.** `apply_fill(pos: OpenPositionView | None, fill: Fill) ->
(OpenPositionView, PositionDelta)`. **PnL uses `fill.fill_price` ONLY — never `bound_price`**
(assert/comment quirk #3). Notional/qty handled WITHOUT double-applying leverage (quirk #4 —
document the convention explicitly). Realized PnL on reducing fills = signed (entry−fill)×qty for
SHORT, etc.; fees subtracted; `event_seq` carried through. Pure function.
**Pass criteria.** Open, add, partial-reduce, full-close produce correct qty + realized PnL +
fee; a test asserts that a fill with `bound_price != fill_price` yields PnL from `fill_price`;
Hypothesis: qty ≥ 0; realized PnL finite. No edits outside the 2 files.

## TASK 24 — Mock execution integration harness (router + driver + venue, DARK storm)
**Why.** Prove the whole stack composes: `ExecIntent` (PASS-4 Task 17) → router/maker-policy →
`ExecDeadlineDriver` (V2) → `MockBingxVenue` → `Fill` → `fill_reducer` → `PositionDelta` →
`EconomicsLedger` (PASS-4 Task 16). The end-to-end DARK proof.
**Affected files (NEW):** `prod/clean_arch/violet/exec/mock_exec_harness.py`,
`prod/clean_arch/violet/exec/test_violet_mock_exec_scenarios.py`, gate report →
`prod/VIOLET_dev/reports/violet_mock_exec_<UTC>.json`.
**Interface/approach.** Wire the components (READ `exec_harness.py`/`exec_driver.py` for the V2
storm pattern; reuse, don't fork). Run a seeded scenario matrix: clean entry→fill→exit; partial
fills; cancel/requote on TTL; reject; maker_both policy. Assert: every order reaches a terminal
state, capital == anchor + Σ deltas (ledger), NO order ever leaves the mock (DARK guard), and the
run is deterministic (same seed ⇒ same fills/deltas twice).
**Pass criteria (`@pytest.mark.gate`).** ≥ 8 scenarios green; determinism proven; ObserveOnly/DARK
guard asserts zero real-venue calls; report archived. No edits outside the new files.

---

## Composition map
```
contracts_v3 (+Order/OrderAck/Fill/OrderStatus/PositionDelta) + exec/bingx_quirks(QuirkProfile)
   20 contracts + quirk seams
   21 order_fsm                → legal lifecycle, partials, reject
   22 mock_bingx_venue(fsm, fill_model, quirks=OFF) → OrderAck + Fill stream   (quirk hooks inert)
   23 fill_reducer(pos, fill)  → (OpenPositionView, PositionDelta)             (fill-price PnL)
   24 mock_exec_harness: ExecIntent → router/driver → 22 → 23 → PASS-4 EconomicsLedger  (DARK E2E)
```
Integration into the live reactor + the real BingX client swap is the OWNER's job later. The
quirk-injection pass (turning `QuirkProfile` flags ON to test reconcile/filter logic) and the
mandatory real-key boundary smoke are SEPARATE, LATER work — NOT PASS 5.

## Recommended order
**20 (contracts+quirk seams) → 21 (FSM) → 23 (fill reducer) → 22 (venue) → 24 (harness/gate)**.

## Still NOT in scope (operator/owner only, or a later pass)
- **Quirk LOGIC / reconcile-against-quirks** — later quirk-injection pass (seams only here).
- **Real BingX client + real-key smoke** — mandatory before V4-live; operator-gated.
- **DARK soak start; HZ-bridge refactor; VIBRISS; the V3.4c parity root-cause (CRITICAL #1).**
- Any edit to the in-flight files / shared files in §0.