3.6 KiB
Design
Context
See proposal.md for motivation. The adapter currently reads TWAP only when positions exist, and its decoder returns only a position-keyed map. Immutable account/snapshot records and identity-based JavaFX reconciliation already support retained observations.
Goals / Non-Goals
Goals: Preserve eligible orders independently of matching, render actionable reasons with exact ownership, and summarize distinct orders through collapsed trees.
Non-Goals: Order cancellation, predicting execution failure, new polling or notifications, changes to capital or liquidation calculations.
Decisions
- Return matched TWAPs and account-owned warning observations from decoding. Warning data holds TWAP address/order sequence, asset/subaccount identity, raw counters/fills, typed reason, optional matched position symbol and original receipt time. Keep compatible constructors for public records. A generic untyped UI message or synthetic position would lose ownership and distort totals.
- Read TWAP after trader state for every existing account. Fetch metadata for held positions or eligible filled outstanding orders; never request marks for warning-only markets. Empty unregistered authorities need no TWAP/market reads. Continue strict schema, counters, duplicate and identity validation, including orders that are ultimately hidden.
- Missing market and missing open position produce account-owned warnings. A matched order whose next execution estimate is unavailable keeps its progressbar plus a timing warning: this states unavailable timing, not a stopped order. Zero fills and zero remaining children stay invisible. Do not treat absence of optional USD valuation alone as a warning.
- Map matched warnings to positions, unmatched Cross warnings to their real Cross group (including zero-capital accounts), and propagate all through venue/wallet/root. An unmatched isolated order with no reliable position remains on Phoenix with its true isolated subaccount in the tooltip; inventing a Cross owner would violate identity. Existing risk reads also cover newly visible warning-only Cross accounts.
- Format warnings only in EMC. Build summaries from underlying observations, keyed by wallet plus account/order identity, rather than counting child indicators. Render an amber vector triangle with a readable label, retained/stale qualifier and detailed source tooltip. Five minutes is the same observation-age cutoff as existing risk; it is not an execution deadline. Existing three-second polling reevaluates age without moving source timestamps or rebuilding retained rows.
- A successful observation replaces warning lists; failures retain the complete prior venue. Consumer read failures qualify all visible summaries. Normal TWAP bars and Risk remain separate.
Risks / Trade-offs
- Extra reads for registered empty accounts → reuse shared pacing/cooldown; fetch metadata only if needed and no extra marks.
- Missing metadata prevents quantities and symbols → show raw asset ID/lots and explicitly unknown values.
- Nonatomic state/TWAP reads can temporarily report no matching position → describe only the observed mismatch and let the next successful read reconcile it.
- Aggregation could duplicate orders or hide stale sources → distinct identity keys, per-source times/status, multi-wallet and collapsed-tree checks.
Migration Plan
Build and verify locally with temporary harnesses and JavaFX images. Update the three main specs and meaningful docs after implementation. Deployment remains a separate owner action; no commits, pushes or Hub restart. Reverting these source changes restores prior presentation without changing orders.