siloqy/prod/docs/PINK_ACCOUNTING_EXEC_FIX.md

PINK / DITAv2 Accounting & Execution Fix — Spec and Dev Guide

Status: SPEC — ready for implementation agent Date: 2026-06-11 Branch: exp/pink-ditav2-sprint0-20260530 (continue on it or fork fix/pink-accounting-consolidation) Author of spec: forensic session 2026-06-11 (FET −$5,990.90 mis-book replay) Prerequisite for: VIOLET rebuild (violet_subsecond_rebuild_plan memory / future plan session)

---

0. Why this exists — the incident in one paragraph

On 2026-06-11 PINK closed a FET-USDT short that the exchange settled at ≈ +$164 net (entry VWAP 0.1878, exit 0.1866, ~202K FET) but the kernel booked −$5,990.90 and capital diverged −$6,154 from the exchange wallet. Replay against dolphin_pink.trade_reconstruction slot images identified three stacked defects, all in derivation code (none in exchange facts): (1) fill events carried BingX's MARKET protective bound price (0.229, +22% off tape) instead of the true fill price; (2) realized_pnl() and mark_price() multiplied PnL by slot.leverage (exchange leverage — but slot.size is exchange quantity, so every leg was 3× inflated); (3) the Python settle baseline _last_settled_pnl resets empty on every restart, so reconcile-adopted slots re-settle carried PnL. Exact replay of leg 1: 26,007 × (0.229−0.1878)/0.1878 × 0.1878 × 3 = −3,214.4652 ✓ matches the booked increment to the cent.

A fourth structural finding: there are three parallel ledgers (Rust AccountState K/E, Python AccountProjection — the one persistence reads, fee-blind — and AccountProjectionV2, dead in the live path). This spec consolidates to E-facts as ledger of record + K as integrity checksum + one atomic published snapshot.

---

1. Scope and non-goals

IN SCOPE

1. Commit + activate the Phase-0 fixes already in the working tree.
2. E-anchored published capital; single atomic account snapshot.
3. Per-trade PnL provenance (exchange | kernel_estimate) end-to-end.
4. Sizer feedback off trade-realized PnL (not capital deltas).
5. Persistence hygiene: duplicate row emission, silent async-insert loss, event_seq stamping, bars_held clamp, naive-UTC timestamps.
6. Kernel hardening leftovers: resolve_slot no-match sentinel, FILL_SETTLED realized override of flagged estimate legs.

OUT OF SCOPE (separate tickets)

• BLUE's exit-path masking bug (LINK −$1,248, TODO_TP_SCAN_CADENCE_BUGFIX.md) — BLUE stack, not DITAv2.
• VIOLET fork, sub-second clock, venue price-feed port, cadence quantizer.
• ch_writer head-of-line poison-row parking redesign (mitigations land here; the full parking-lane design is its own task).
• prefect.db / ClickHouse TTL disk remediation.

HARD INVARIANTS — MUST NOT CHANGE

• Dual leverage: slot.size = exchange quantity; slot.leverage = exchange leverage (1–3x cap, set at BingX API); our-leverage (conviction) = size × entry_price / capital, computed only at pink_direct._hz_publish (line ~911). PnL is therefore leverage-free: qty × Δprice, side-signed. Do not touch the conviction→exchange mapping (round_half_even_linear_0.5_to_9.0_to_1_to_exchange_cap) or target_size computation.
• Exits are never skipped (exec-router invariant set, §16 kernel ref).
• BLUE-parity policy contract: DecisionEngine/IntentEngine inputs (MarketSnapshot + capital + slot state) unchanged in shape.
• Namespace isolation: zero writes to dolphin.* / dolphin_prodgreen.* or BLUE/PRODGREEN HZ maps. Re-verify with pink_ctl.py mode-verify.
• Data cadences are sacred (operator rule 2026-06-10): never reduce a data cadence for throughput.

---

2. Phase 0 — Commit and activate the already-applied fixes

These changes exist UNCOMMITTED in the working tree as of 2026-06-11 ~16:30. Verify each hunk, commit as one reviewed unit, then restart dolphin_pink.

0.1 prod/clean_arch/dita_v2/_rust_kernel/src/lib.rs

Function	Change (already applied)
KernelCore::realized_pnl (~line 1153)	PnL = side-signed qty × (exit − entry); no leverage factor; returns 0 when entry<=0 ∨ exit_size<=0 ∨ exit_price<=0 ∨ !finite
TradeSlot::mark_price (~line 394)	no × leverage in unrealized; a mark NEVER becomes entry basis — missing basis flags metadata.entry_basis_missing=true, unrealized stays 0
KernelCore::fill_matches_order (new)	identity match on venue_order_id / venue_client_id
KernelCore::apply_fill	entry/exit routing by ORDER IDENTITY first, FSM state second (!id_matches_exit / !id_matches_entry guards); entry basis = VWAP across entry fills ((prev_basis×prev_filled + price×fill)/accumulated); price-less exit fill reduces size, books 0 PnL, flags metadata.realized_skipped_no_price=true

Rebuild required: cargo build --release in _rust_kernel/ (the .so is only auto-built when missing — source/binary drift is a known hazard; add the build to the commit checklist). cargo test: 32/32 green as of spec.

0.2 prod/clean_arch/dita_v2/bingx_venue.py

Fill events must carry a TRUE fill price or 0.0 — never the order's nominal price / submit receipt.price (BingX MARKET bound price, ±20–25%):

• _events_from_submit fill event (~line 585): _row_float(ack_row, "avgPrice","ap","lastFillPrice","L", default=0.0)
• _event_from_row (~line 697): fills use the same true-price chain; non-fill events (ACK/CANCEL/REJECT) may keep nominal price as info
• _fill_event_from_row (~line 736): "lastFillPrice","L","avgPrice","ap"

0.3 prod/clean_arch/dita_v2/rust_backend.py

• reconcile_from_slots: seeds _last_settled_pnl[slot_id] = slot.realized_pnl and _slot_was_closed[slot_id] = slot.closed for every adopted slot.
• restore_state: same re-anchoring after successful restore.

0.4 Adjacent fixes riding the same commit

• prod/ch_writer.py: insert URLs append &date_time_input_format=best_effort; flush errors log at WARNING (first 10 + every 100th), counter _flush_errors.
• prod/clean_arch/dita_v2/blue_parity.py price_of: hyphen-tolerant fallback (FET-USDT → FETUSDT) — fixes the unmanaged-position block.
• prod/clickhouse/users.xml: date_time_input_format=best_effort for the dolphin user (NOTE: running CH container did not honor it even after restart — the container does not mount compose configs; effective on next compose recreation. The client-side URL param is the operative fix.)
• prod/tests/test_dita_v2_kernel.py: partial→full fill test updated to incremental filled_size semantics (BingX WS lastFilledQty).

0.5 Phase 0 gates

1. cargo test in _rust_kernel: 32/32.
2. pytest prod/tests/test_dita_v2_kernel.py: 7/7.
3. pytest prod/clean_arch/dita_v2/test_exec_router_runtime.py test_venue_reconcile.py test_orphan_prevention.py prod/tests/test_pink_async_fill_pump.py prod/clean_arch/dita_v2/test_account_core_v2.py test_bingx_bugs.py: 134/134.
4. KNOWN pre-existing failures (NOT introduced by this work — verified by hunk-revert): 4 tests in prod/tests/test_dita_v2_bingx_adapter.py (snapshot-fill emission broke when sync submit() started passing None snapshots on 2026-06-10). Fix or quarantine them explicitly in this phase — do not let them mask new regressions.
5. Restart dolphin_pink at a FLAT moment; verify in logs: no realized_skipped_no_price storms, no entry_basis_missing on fresh entries, first round-trip books PnL within ±(fees+slippage) of GET /openApi/swap/v2/user/income for the same trade.

---

3. Phase 1 — E-anchored published capital

Goal: the capital that persistence/HZ/sizer see is exchange-anchored; K never publishes.

3.1 prod/clean_arch/dita_v2/account.py

• Add to AccountSnapshot: capital_source: str ("e_anchored" | "k_bridged" | "seed"), e_wallet_balance: float, event_seq: int.
• New method AccountProjection.anchor_to_exchange(wallet_balance: float, available_margin: float, event_seq: int): sets capital = wallet_balance (guard >0 and finite — the zero-wb frame lesson), capital_source = "e_anchored", recomputes equity. settle() remains for the BRIDGE case only: between anchors, capital += realized (capital_source="k_bridged").
• settle(realized_pnl, fees): stop ignoring fees — capital += realized_pnl − fees (today fees only accumulate in fees_paid; published capital ignores them between reseeds).

3.2 prod/clean_arch/runtime/pink_direct.py

• The existing reseed path (balance-bearing ACCOUNT_UPDATE → kernel.reset_and_seed(wb)) additionally calls kernel.account.anchor_to_exchange(...) — one anchoring action, two ledgers consistent.
• Boot seed (launcher exchange_balance_capital block, pink_direct ~line 262) goes through anchor_to_exchange instead of direct attribute writes.

3.3 Gates

• New unit tests (prod/tests/test_pink_account_anchor.py): anchor sets capital/source; zero/negative/NaN wb rejected; settle bridges with fees; anchor after bridge snaps to wb exactly.
• Shadow check (live, 24 h on VST): published capital vs GET /openApi/swap/v2/user/balance polled 1/min — max |Δ| outside a trade-settlement window ≤ $0.01; during settlement ≤ pending-fee bound.

---

4. Phase 2 — Single atomic snapshot, ledger consolidation

Goal: one immutable, versioned account snapshot; the two redundant ledgers demoted/removed.

4.1 prod/clean_arch/dita_v2/account.py

• Make the published snapshot immutable-replace: AccountProjection builds a new frozen AccountSnapshot (carry event_seq) on every mutation and swaps a single reference (GIL-atomic). Readers must take snap = kernel.account.snapshot once per use (audit call sites: pink_clickhouse.py, hazelcast_projection.py HZ writer, pink_direct).
• AccountProjectionV2: DELETE, or move to prod/clean_arch/dita_v2/ _attic/ with a module docstring pointing here. Its only live-path import is exchange_event.py — migrate that import or the dataclasses it uses (EPosition is genuinely useful; keep it in account.py).
• The Rust AccountState K-ledger STAYS — demoted by documentation and by Phase 1 (it no longer feeds published capital): its jobs are reconcile classification (R1-style), capital_frozen, and E-dark bridging. Update the module docstring to say exactly this.

4.2 prod/clean_arch/persistence/pink_clickhouse.py

• Read capital/equity/peak/trade_seq from the single snapshot reference; no recomputation.
• Add columns to emitted rows (and the matching ALTER TABLE DDLs under prod/clickhouse/pink/08_provenance.sql — apply DDLs to CH BEFORE deploying code that emits them; the missing-table head-of-line jam of 2026-06-11 is the cautionary tale):
  • account_events, status_snapshots: capital_source LowCardinality(String) DEFAULT '', account_event_seq UInt64 DEFAULT 0
  • trade_events, trade_exit_legs: pnl_source LowCardinality(String) DEFAULT '' (exchange | kernel_estimate)
• bars_held: clamp to max(0, …) at row-build time (UInt16 column; negative values currently 400 on trade_events / silently vanish on async tables).
• Timestamps: route every ts through one helper emitting naive-UTC microsecond ISO (no +00:00) — best_effort already tolerates both, but rows must stop depending on a parser setting.

4.3 Duplicate-emission fix (same file)

Every CH row is currently emitted twice (visible in any query). Hunt the double call: instrument _sink() with a per-(table, content-hash) debug counter in a test, then trace the two call paths (suspect: persist_result invoked both from the runtime step and from the fill pump for the same event). Fix at the caller level; do NOT dedupe by content in the sink (masks real double-events). Regression test: one simulated round trip → exactly one row per logical event per table.

4.4 prod/ch_writer.py

• wait_for_async_insert: "1" for ALL dolphin_pink tables (accounting rows must never be silently lost; the spool absorbs latency). Keep 0 acceptable only for high-volume shadow tables if measured necessary — document any exception inline.
• Mitigation for head-of-line (full redesign out of scope): after attempts > 1000 on a row, log ERROR with the CH response body once per 100 attempts (today the reject reason is invisible without manual replay).

4.5 Gates

• Full offline suite (the 533+ DITAv2/PINK set) green, minus the Phase-0 quarantined adapter tests if still open.
• One live VST round trip: every table gets exactly one row per event; pnl_source/capital_source populated; CH system.text_log shows zero parse rejections for dolphin_pink.

---

5. Phase 3 — Sizer feedback off trade-realized PnL

THE one seam where this refactor can silently change alpha behavior.

5.1 prod/clean_arch/runtime/pink_direct.py — _sizer_trade_feedback (~line 1453)

Today: pnl = acc.capital − self._sizer_entry_capital (capital delta). Under E-anchored capital this absorbs funding, fees of other activity, and foreign fills from the shared VST account (PRODGREEN collision class). Change to:

pnl = slot_realized_for_trade(trade_id)   # Σ slot.realized_pnl legs, i.e.
                                          # kernel estimate, overridden by
                                          # exchange rp when settled (5.2)

Source: the closing slot dict already carries realized_pnl; use it (minus the fees recorded for the trade when available) instead of the capital delta. Keep the magnitude semantics the sizer expects (sign + rough size — per the existing comment, bucket/streak multipliers only need that).

5.2 Exchange override (E-led repair) — bingx_user_stream.py + rust_backend.py

• The WS FILL_SETTLED path already carries the exchange's realized (rp) and fee (n, sign-flipped at boundary per BingX quirks memory). Extend the kernel account-event payload with trade_id, and on receipt:
  • if the matching slot leg was flagged realized_skipped_no_price, ADD the exchange realized to slot.realized_pnl (repair) and clear the flag; settle the increment through the normal baseline mechanism;
  • else record pnl_source="exchange" for the trade-event row (the estimate stays as the booked figure unless |estimate−rp| exceeds a tolerance — then log ERROR + emit an anomaly_events row; do NOT silently re-book).
• Rust: add dita_kernel_repair_realized(slot_id, amount) FFI (or fold the repair into on_account_event with slot_id in payload). Keep it idempotent via the existing account-event dedup.

5.3 Gates

• Unit: feedback receives trade-realized, not capital delta (simulate a foreign-fill capital jump mid-trade → feedback unaffected).
• Unit: price-less exit leg + later FILL_SETTLED repair → slot realized equals exchange rp; settle baseline consistent (no double-settle).
• Parity: test_blue_parity.py, test_alpha_blue_untouched_g7.py green (sizer behavior unchanged for normal fills).

---

6. Phase 4 — Kernel hardening leftovers

6.1 lib.rs — resolve_slot (~line 1099)

Falls back to slot 0 when nothing matches. Change: return Option<usize>; on None, on_venue_event returns UNRESOLVED_SLOT (diagnostic exists already) without mutating any slot, severity WARNING, event recorded in outcome details. Python callers: the runtime treats UNRESOLVED_SLOT as a logged no-op (the _fill_is_ours filter remains first-line defense; this is kernel-side defense for venue-agnostic reuse). NOTE: several tests construct events with slot_id=-1 expecting slot-0 fallback — update them to pass explicit slot_id=0 (behavioral test change; list each in the PR description).

6.2 ID-less fill routing (documentation + metric, not code)

BingX WS omits clientOrderId, so identity routing can't always engage. Add a counter metric (fills_routed_by_state_total) via an anomaly_events row per occurrence, severity INFO — gives VIOLET the data to justify per-venue synthetic ids later. No FSM behavior change.

6.3 Gates

• New Rust tests: unresolved event mutates nothing; entry-id fill during EXIT_WORKING routes to entry (already covered by Phase-0 routing — add the explicit case); price-less exit leg books 0 + flag.

---

7. Test matrix (run-order for the implementing agent)

Stage	Command (env: PYTHONPATH=/mnt/dolphinng5_predict:/mnt/dolphinng5_predict/nautilus_dolphin, venv /home/dolphin/siloqy_env/bin/python3)	Pass bar
Rust unit	cargo test --release in _rust_kernel/	100%
Kernel FSM	pytest prod/tests/test_dita_v2_kernel.py	100%
Bridge/accounting	pytest prod/tests/test_pink_ditav2_kernel_bridge.py test_pink_ditav2_accounting_invariants.py prod/clean_arch/dita_v2/test_account_core_v2.py	100%
Runtime/reconcile	pytest prod/clean_arch/dita_v2/test_venue_reconcile.py test_orphan_prevention.py test_exec_router_runtime.py prod/tests/test_pink_async_fill_pump.py test_pink_direct_runtime.py	100%
Chaos	pytest prod/tests/test_pink_ditav2_chaos_harness.py + test_dita_v2_e2e_functional.py	100%
Parity	pytest prod/clean_arch/dita_v2/test_blue_parity.py test_alpha_blue_untouched_g7.py	100%
Adapter	pytest prod/tests/test_dita_v2_bingx_adapter.py	100% after Phase-0 item 4 resolution
LIVE VST E2E	python prod/ops/dita_v2_live_bingx_smoke.py --pink --symbol TRXUSDT	suite green
Golden replays (NEW — write these)	prod/tests/test_pink_accounting_golden.py	see below
Shadow soak	24–48 h on VST	capital vs balance ≤ $0.01 idle

Golden replay tests (the heart of the acceptance)

Feed the kernel the recorded FET event sequence (entry fills 195,259 + 7,017 @ 0.1878; exit fills 26,007 + remainder; the poisoned variant with price=0.229 and the clean variant with 0.1866):

1. Clean prices → realized = (0.1878−0.1866) × 202,276 ≈ +242.7 gross.
2. Poisoned price (0.229) reaching the kernel anyway → with the adapter fix it must arrive as 0.0 → leg books 0 + realized_skipped_no_price; after synthetic FILL_SETTLED rp=+164 → slot realized = +164, pnl_source=exchange.
3. Restart mid-position (save_state/restore_state + reconcile_from_slots) → next venue event settles ONLY the incremental PnL.
4. VWAP: two entry fills at different prices → basis = weighted average.
5. Dual-leverage invariant: same fills at exchange-leverage 1 vs 3 → identical realized PnL; only margin fields differ.

---

8. Rollout & rollback

1. Each phase = one PR-sized commit, gates green before the next.
2. Activation requires supervisorctl restart dolphin_pink — restart at a FLAT moment (check DOLPHIN_STATE_PINK + exchange positions). The restart-reconcile path is itself under test here; first restart after Phase 0 should be watched live.
3. Rollback = git revert of the phase commit + rebuild .so + restart. The Rust .so MUST be rebuilt on both apply and revert — stale-binary drift is how the incremental-fill change sat uncompiled until 2026-06-11.
4. CH DDLs are additive (ADD COLUMN ... DEFAULT) — no destructive migrations anywhere in this spec; rollback leaves unused columns, which is fine.
5. PINK is VST (virtual funds) — it is the canary by construction. Nothing in this spec touches BLUE files (verify with git diff --name-only against the §38.7 checklist).

9. Done criteria (the whole spec)

• All phases merged; full matrix green; golden replays green.
• 48 h VST soak: zero UNEXPLAINED reconcile errors; published capital tracks exchange balance; every closed trade's trade_events.pnl within fees+slippage of the exchange income record, with pnl_source populated.
• pink_ctl.py mode-verify passes (namespace isolation intact).
• SYSTEM BIBLE §38 addendum updated (one paragraph: E-led ledger, K as checksum, provenance fields) + DITA_V2_KERNEL_REFERENCE.md §"Capital simplification" rewritten to match reality.