103: EMC Perps: propagate Phoenix TWAP warnings through the tree to Perpetual Contracts

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

@@ -7,7 +7,7 @@ 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, 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.
+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 blank, show TWAP warnings when applicable, and be expanded by default.
 
 #### Scenario: Open either environment's Perps tab
 - **WHEN** the owner opens Perps in Production or Test
@@ -35,12 +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 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.
+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 or TWAP-warning 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** only a changed risk freshness indication requires a row-value update
+- **AND** only a changed risk or TWAP-warning 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.
@@ -70,10 +70,10 @@ Tooltips SHALL explain isolated collateral, exposure-based leverage, collateral-
 - **AND** no position-only metric is labeled account utilization
 
 ### Requirement: Venue visibility follows available child rows
-EMC SHALL hide venue rows with neither positions nor Cross accounts and show them when children reappear. Funded empty Cross accounts SHALL keep their venue visible. Hidden venues SHALL remain in snapshots and totals, with read status available in wallet tooltips. Unknown scopes SHALL NOT become zero totals; failed reads SHALL preserve last-success totals. Wallet rows and the root SHALL remain visible.
+EMC SHALL hide venue rows with neither positions, Cross accounts nor TWAP warnings and show them when children reappear. Funded empty Cross accounts and accounts with eligible TWAP warnings SHALL keep their venue visible. Unmatched isolated warnings SHALL remain on the venue with true subaccount identity, never on an invented Cross parent. Hidden venues SHALL remain in snapshots and totals, with read status available in wallet tooltips. Unknown scopes SHALL NOT become zero totals; failed reads SHALL preserve last-success totals. Wallet rows and the root SHALL remain visible.
 
 #### Scenario: Empty venue
-- **WHEN** Jupiter or Phoenix has no positions and no Cross accounts
+- **WHEN** Jupiter or Phoenix has no positions, Cross accounts or TWAP warnings
 - **THEN** its heading is absent from that wallet's displayed children
 - **AND** a successful empty scope still contributes zero to totals
 
@@ -92,7 +92,7 @@ EMC SHALL hide venue rows with neither positions nor Cross accounts and show the
 - **AND** required totals remain unavailable rather than reporting zero
 
 ### Requirement: TWAP cells show execution progress and snapshot duration
-Matching filled Phoenix TWAPs SHALL show a progressbar using executed/total child counts and an overlaid estimated duration to the next child in unbounded hours, minutes and seconds. Other cells SHALL be empty. Updates SHALL follow existing snapshots without a live timer. Failed retained observations SHALL be labeled retained; due or unknown schedules SHALL not show negative or wrapped times or imply execution.
+Matching filled Phoenix TWAPs SHALL show a progressbar using executed/total child counts and an overlaid estimated duration to the next child in unbounded hours, minutes and seconds. Cells with no eligible progress or warning SHALL be empty. Matched timing warnings SHALL coexist with their progressbar. Updates SHALL follow existing snapshots without a live timer. Failed retained observations SHALL be labeled retained; due or unknown schedules SHALL not show negative or wrapped times or imply execution.
 
 #### Scenario: Long interval
 - **WHEN** the snapshot's estimated wait is 28 hours 32 minutes 10 seconds, or 128 hours 32 minutes 10 seconds
@@ -126,3 +126,24 @@ EMC SHALL mark risk stale after five minutes from its original observation, on r
 #### 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
+
+### Requirement: TWAP warnings propagate through every ancestor
+EMC SHALL show an amber warning triangle and concise text at the owning position or Cross group and on every actual ancestor through Perpetual Contracts. Summaries SHALL count each distinct order once per scope independently of expansion state. Unfilled and completed orders SHALL remain invisible. Risk and capital totals SHALL remain independent.
+
+#### Scenario: Collapsed Cross branch
+- **WHEN** a filled outstanding Cross order has missing market metadata and Cross or Phoenix is collapsed
+- **THEN** Cross, Phoenix, wallet and Perpetual Contracts still carry the warning
+- **AND** each summary counts that order once
+
+#### Scenario: Position and multiple wallets
+- **WHEN** a position warning and an unmatched Cross warning affect different wallets
+- **THEN** each follows only its actual ancestors and the root counts two orders
+- **AND** clearing one warning leaves the other and its ancestor summaries intact
+
+### Requirement: Warning details preserve reason and freshness
+Warning tooltips SHALL identify wallet/account/position, reason, TWAP address, asset/subaccount IDs, raw progress/fills and original observation time. Unknown metadata SHALL remain unknown without unsupported cancellation/delisting/stoppage claims. Failure retention, future timestamps and the existing five-minute observation-age cutoff SHALL qualify all affected summaries.
+
+#### Scenario: Retained or aged warning
+- **WHEN** a warned venue or consumer read fails, or its original observation becomes five minutes old
+- **THEN** source and inherited warnings remain visible with retained/stale qualification and original times
+- **AND** existing UI polling updates age without additional venue reads or resetting selection and expansion