com_r35157_nenjim-hubd-impl_ref/openspec/changes/102-perps-risk-health/design.md

Design

Context

See proposal.md for motivation. Positions/account capital and TWAP already travel through immutable integration DTOs and per-venue retained snapshots. EMC polls these snapshots every three seconds, currently skips equal snapshots and reconciles tree items by identity. Risk cannot use closing Value or undiscounted equity as effective collateral.

Goals / Non-Goals

Goals: Venue-reported risk with original timestamps, shared-account scope, exact arithmetic and honest incomplete/expired summaries.

Non-Goals: A liquidation engine, position management, notifications, faster polling, external writes or a general risk-policy platform.

Decisions

1. The owner explicitly selected neutral isolated price distance with red only at a reached/crossed boundary. Phoenix tiers retain their venue-specific colors. Do not introduce speculative per-market safety thresholds. Never use rounded display numbers for classification.
2. Use five minutes from observation receipt as the maximum age; failures immediately mark retained observations stale. Normal sequential reads across six PROD wallets can approach five minutes, so slow cycles can deliberately produce stale indications. This is a data-quality cutoff, not a claim that prices remain safe for five minutes. Future timestamps are uncertain too. Source/API lag remains an explicit limitation.
3. Extend Jupiter's overview-only DTO with micro-USD reference/liquidation prices and the original response observation time. Preserve signing/alarm readers.
4. Inject the existing SolanaBlockChain into the Phoenix adapter for local PDA derivation only. Use official program EtrnLzgbS7nMMy5fbD42kXiUzGg8XQzJ972Xtk1cjWih, seeds trader, authority bytes, one-byte PDA index and one-byte subaccount. GET TraderView per visible account, validate its authority/account/PDA/subaccount and position identities/quantities. Decode value/decimals exactly, ignore UI strings and normalize nonpositive liquidation prices to unavailable. Reuse already-read Phoenix marks with their receipt times; isolated risk freshness uses the oldest required observation. Account risk uses the self-contained TraderView receipt time. No TWAP account key or signature is needed.
5. Keep distinct Phoenix risk DTOs and Evelyn risk observations. Cross account risk belongs to CrossAccount; Cross positions only refer to that scope in presentation. Exact signed distance, MM utilization and headroom are domain calculations; colors/text belong to EMC. Missing essential fields remain unknown. A valid account tier can exist without an actionable liquidation price.
6. Risk is the second column. A domain helper evaluates each isolated position and each Cross account once, plus unknown/expired venue scopes. Group summaries retain the worst known level, unknown count and stale count, without averaging. Known critical observations remain prominent even if old; incomplete/noncritical summaries are never unconditional green.
7. Re-evaluate risk with the existing UI poll and an injectable Clock, including equal snapshots. On a consumer snapshot-read failure, re-render the retained snapshot with an explicit read-failure flag; do not let a failing getter bypass freshness indefinitely. Reconcile immutable row values only when they differ; do not call table.refresh or replace tree items. This expires unchanged snapshots without a new timer/network loop and preserves selection, expansion and TWAP behavior.
8. A malformed/rejected risk read fails the venue read and preserves its previous complete observation/status. Missing optional metrics or unknown future risk tiers remain explicitly unavailable. Other wallets/venues continue. Existing request pacing, timeout and cooldown apply to the new GETs.

Risks / Trade-offs

• API/mark/state reads are not atomic → validate identity/position size, use oldest required receipt time and explain reference-price lag.
• Extra per-account reads → reuse current pacing; no risk reads for invisible empty isolated accounts; source address derivation is local.
• Nullable/sentinel fields → independent valid metrics survive, missing risk never becomes zero or an all-clear.
• Different venues have different meanings → isolated distance and Cross MM utilization retain distinct labels and definitions.

Migration Plan

No persisted data or owner configuration migration. Wire the existing Solana dependency in NenjimHub, build and verify with temporary fixtures, UI checks and read-only observations. Update existing docs/shared docs and sync affected specs. Leave deployment and the running Hub unchanged.