From 28a2b90b1d1bc252531f47287687737b52380ca9 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 17 Jun 2026 10:26:15 +0200 Subject: [PATCH] =?UTF-8?q?VIOLET=20OA:=20partial=20spec=20PASS=205=20?= =?UTF-8?q?=E2=80=94=20mock-BingX=20execution=20stack=20(quirks=20seam-onl?= =?UTF-8?q?y,=20deferred)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit VIOLET_PART_SPEC_OA_TODO_PASS5.md — the DARK mock-BingX execution stack so the full order lifecycle is buildable/testable with zero keys/risk (V4-live later = swap mock for real client). Five independent units extending contracts_v3 (Order/OrderAck/Fill/OrderStatus/PositionDelta): 20. Execution contracts + QuirkProfile seam registry (no quirk logic). 21. Mock BingX order FSM (legal lifecycle, partials, reject, reduce-only-increase rejection). 22. Mock BingX venue adapter (port-conformant, injectable fill model, quirk hooks INERT by default). 23. Fill→position/PnL reducer (PnL from fill_price ONLY; ×leverage-aware) → PositionDelta. 24. DARK E2E gate: ExecIntent → router/driver → mock venue → fill reducer → PASS-4 ledger. CRITICAL per operator: a prominent ⚠️ section makes explicit that BingX "quirks" (zero-wb WS frames, ownership/foreign-fill collision, bound-price poison, ×leverage notional, settle desync, reduce-only edge, setLeverage race, dead .pro TLS) are EXPLICITLY OUT OF SCOPE for PASS 5 — the mock carries injection SEAMS (QuirkProfile, default OFF) to accommodate them LATER, and a real-key boundary smoke remains MANDATORY before V4-live. Quirks sourced from PINK orphan/reconcile + DITAv2 audit memory. Standing ready to write PASS 6–9 (exec internals/reconcile, V5 selection+slots, V6 bible consumers, economics/observability). Added PASS 5 to the review queue in VIOLET_TODO_CRITICAL.md. Co-Authored-By: Claude Opus 4.8 --- prod/docs/VIOLET_PART_SPEC_OA_TODO_PASS5.md | 192 ++++++++++++++++++++ prod/docs/VIOLET_TODO_CRITICAL.md | 5 + 2 files changed, 197 insertions(+) create mode 100644 prod/docs/VIOLET_PART_SPEC_OA_TODO_PASS5.md diff --git a/prod/docs/VIOLET_PART_SPEC_OA_TODO_PASS5.md b/prod/docs/VIOLET_PART_SPEC_OA_TODO_PASS5.md new file mode 100644 index 00000000..9a251460 --- /dev/null +++ b/prod/docs/VIOLET_PART_SPEC_OA_TODO_PASS5.md @@ -0,0 +1,192 @@ +# 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 -- ` 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_.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. diff --git a/prod/docs/VIOLET_TODO_CRITICAL.md b/prod/docs/VIOLET_TODO_CRITICAL.md index a27c310e..5d6f0379 100644 --- a/prod/docs/VIOLET_TODO_CRITICAL.md +++ b/prod/docs/VIOLET_TODO_CRITICAL.md @@ -59,6 +59,11 @@ exits / SL floor / event-restore / slippage / cadence; review when done. **PASS 4**: `VIOLET_PART_SPEC_OA_TODO_PASS4.md` (issued 2026-06-17) — vol gate / V7 exit wrapper / economics ledger / exec-intent / alpha data feed / time exits; review when done. +**PASS 5**: `VIOLET_PART_SPEC_OA_TODO_PASS5.md` (issued 2026-06-17) — MOCK-BINGX execution stack +(exec contracts + QuirkProfile seams / order FSM / mock venue / fill reducer / DARK E2E gate). +NOTE: BingX "quirks" are SEAM-ONLY here (default OFF) — a later quirk-injection pass + a mandatory +real-key boundary smoke are required before V4-live; review when done. + **Action:** review each pass for correctness, BLUE-algo compliance, V-TYPES, no-shared-edits, real (non-vacuous) tests. **Owner: Claude (me), later.**