102: EMC Perps: show liquidation risk and account health

openspec/specs/evelyn-perps-overview/spec.md

@@ -7,15 +7,15 @@ Let the owner inspect Evelyn perpetual positions grouped by wallet and venue in
 ## Requirements
 
 ### Requirement: Perps overview displays a collapsible position hierarchy
-The Perps tab SHALL display Position, Direction, Margin, Collateral, Leverage, Exposure, Value, uPnL and TWAP in that order beneath the visible Perpetual Contracts root. Isolated hierarchy SHALL be wallet → venue → position; each Phoenix Cross account SHALL add a Cross group above its positions. Groups SHALL show applicable totals, leave direction/aggregate ratios and TWAP blank, and be expanded by default.
+The Perps tab SHALL display Position, Risk, Direction, Margin, Collateral, Leverage, Exposure, Value, uPnL and TWAP beneath the visible Perpetual Contracts root. Isolated hierarchy SHALL be wallet → venue → position; each Phoenix Cross account SHALL add a Cross group above its positions. Groups SHALL show applicable totals and risk summaries, leave direction/aggregate ratios and TWAP blank, and be expanded by default.
 
 #### Scenario: Open either environment's Perps tab
 - **WHEN** the owner opens Perps in Production or Test
-- **THEN** all nine columns, root totals and the account-aware hierarchy are available, with horizontal scrolling where required
+- **THEN** all ten columns and the account-aware hierarchy are available with Risk near the position name
 
 #### Scenario: Collapse and expand groups
-- **WHEN** the owner collapses and expands a wallet, venue or Cross account
-- **THEN** descendants hide and return without changing totals
+- **WHEN** the owner collapses a wallet, venue or Cross account
+- **THEN** the group still shows its worst known risk and incomplete-observation counts without changing totals
 
 ### Requirement: Asynchronous polling follows window visibility
 EMC SHALL request the current Perps snapshot from each environment's own service immediately on opening and every three seconds while visible, without blocking the UI thread. UI updates SHALL occur only on the JavaFX thread. Hiding the window SHALL stop polling; reopening SHALL create only one active polling loop and ignore results belonging to an earlier window session. Poll failures SHALL preserve the current view and allow subsequent attempts.
@@ -35,11 +35,12 @@ EMC SHALL request the current Perps snapshot from each environment's own service
 - **AND** a failure reading one service does not prevent attempting the other service
 
 ### Requirement: Polling preserves Perps view state
-The Perps table SHALL retain matching wallet, venue and position identities across snapshots. Repeated unchanged snapshots SHALL leave existing rows, expansion, selection and formatting untouched without flicker. New groups SHALL be expanded by default, and future added or removed positions SHALL be reconciled by identity without resetting retained groups.
+The Perps table SHALL retain matching wallet, venue and position identities across snapshots. Repeated unchanged snapshots SHALL leave retained rows, expansion, selection and formatting untouched except when risk freshness changes, without flicker or table rebuild. New groups SHALL be expanded by default, and added or removed positions SHALL be reconciled by identity without resetting retained groups.
 
 #### Scenario: Poll unchanged positions
 - **WHEN** a user collapses a group or selects a position and repeated snapshots are unchanged
-- **THEN** the same rows remain, with the same expansion and selection and no rebuild or refresh
+- **THEN** the same rows remain with the same expansion and selection
+- **AND** only a changed risk freshness indication requires a row-value update
 
 ### Requirement: Jupiter positions communicate direction and USD size
 Positions SHALL show readable Long/Short direction and Isolated/Cross margin text. USD amounts SHALL use grouping and two decimals; leverage SHALL use a multiplication sign. Signed uPnL SHALL be green for positive, red for negative and neutral for rounded zero without negative zero. Existing faint direction backgrounds SHALL remain; groups SHALL have distinct weight and no direction color. Numeric columns SHALL be right-aligned with useful widths and tooltips.
@@ -107,3 +108,21 @@ TWAP tooltips SHALL show executed/total progress, Estimated completion, total si
 #### Scenario: Missing price or smaller next child
 - **WHEN** the mark price is unavailable or the next child is a smaller rest order
 - **THEN** token amounts remain visible with unknown USD values, or the next size reflects that rest order respectively
+
+### Requirement: Risk cells distinguish distance and account health
+Risk cells SHALL show neutral isolated distance and red reached/crossed boundaries, while Phoenix tiers use their own severity colors. Cross account cells SHALL label MM utilization; their children SHALL indicate Shared scope. Missing risk SHALL be Unknown. Text, indicators and tooltips SHALL explain units, reference/liquidation prices, account scope, thresholds, original observation time and limitations without changing direction backgrounds.
+
+#### Scenario: Safe account without liquidation estimate
+- **WHEN** Phoenix reports a valid Safe account but a nonpositive liquidation-price sentinel
+- **THEN** account health remains available while the position price estimate is unavailable
+
+### Requirement: Risk freshness expires unchanged snapshots
+EMC SHALL mark risk stale after five minutes from its original observation, on read failure or for future timestamps. Existing UI polling SHALL update freshness even when the snapshot is unchanged, without additional venue calls/timers. Old critical states SHALL remain prominent with uncertainty; stale or incomplete noncritical observations SHALL NOT appear fresh green. Reconciliation SHALL preserve row identity, selection, expansion and TWAP state.
+
+#### Scenario: Unchanged successful snapshot grows old
+- **WHEN** time passes the five-minute risk age limit without new data or errors
+- **THEN** existing UI polling changes its freshness indication without resetting the tree
+
+#### Scenario: Retained critical risk
+- **WHEN** a previously critical observation fails to refresh
+- **THEN** its critical state and original time remain visible with stale/retained indication