100: Add Perps collateral, leverage, value, uPnL and gross-exposure totals in EMC

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

@@ -22,7 +22,7 @@ The service SHALL run as two separate Hub-managed processes registered as `evely
 - **AND** no placeholder positions are generated before successful retrieval
 
 ### Requirement: Wallet configuration belongs to service construction
-The Hub SHALL supply the six PROD wallet addresses and one TEST wallet address specified in issue #98 and the corresponding existing Jupiter integration plus a read-only Phoenix integration at construction. Each service SHALL retain immutable configuration and own its snapshot. Wallet addresses SHALL be used as stable identities and display labels. EMC SHALL neither own nor pass wallet configuration; reads SHALL remain parameterless.
+The Hub SHALL supply the six PROD wallet addresses and one TEST wallet address specified in issue #98, a read-only Jupiter overview reader and a read-only Phoenix integration at construction. Each service SHALL retain immutable configuration and own its snapshot. Wallet addresses SHALL be used as stable identities and display labels. EMC SHALL neither own nor pass wallet configuration; reads SHALL remain parameterless. Existing Jupiter trading/alarm services SHALL retain their behavior.
 
 #### Scenario: Separate configured instances
 - **WHEN** the Hub constructs and starts both instances
@@ -30,15 +30,19 @@ The Hub SHALL supply the six PROD wallet addresses and one TEST wallet address s
 - **AND** the implementation does not define the wallet list internally
 
 ### Requirement: Background Jupiter refresh
-The service SHALL refresh immediately after startup and wait 60 seconds between completed cycles, without overlapping cycles or depending on EMC visibility. It SHALL use Jupiter and Phoenix read operations and respect the existing Jupiter cache. Snapshot reads SHALL make no integration calls. No transaction signing or position-management operation SHALL occur.
+The service SHALL refresh immediately after startup and wait 60 seconds after completed cycles without overlap or dependence on EMC visibility. It SHALL use a dedicated read-only Jupiter overview and the Phoenix account reader. Snapshot reads SHALL make no integration calls. No signing or position-management operation SHALL occur; existing transaction/alarm reads SHALL retain their behavior.
 
 #### Scenario: Background update while EMC is hidden
 - **WHEN** EMC is hidden and the next refresh is due
-- **THEN** the service still refreshes configured wallets and publishes immutable snapshots
-- **AND** no freshness guarantee bypasses the existing 60-second integration cache
+- **THEN** the service refreshes configured wallets and publishes immutable snapshots
+- **AND** all UI snapshot reads remain in-memory
 
 ### Requirement: Position mapping is stable and complete
-The service SHALL map position account to stable ID, mint to known instrument label or raw mint fallback, direction to Long/Short, and positionSize to USD size. Wallet order SHALL follow configuration, and positions SHALL be ordered deterministically by position account. Phoenix SHALL use PDA index, subaccount index and symbol as stable identity, signed quantity for direction and absolute current USD notional for size. Jupiter and Phoenix SHALL appear as separate venues, with no subaccount tree level.
+The service SHALL preserve Jupiter position-account identities and its existing USD position-size basis. Phoenix SHALL preserve PDA/subaccount/symbol identities and absolute current notional. Isolated positions SHALL remain directly under venues; Cross accounts SHALL own their positions and shared balances separately. Wallet and position ordering SHALL be deterministic. No account membership SHALL be inferred from instrument labels.
+
+#### Scenario: Same-market cross and isolated positions
+- **WHEN** a Phoenix wallet holds SOL in Cross and an isolated subaccount
+- **THEN** both positions retain distinct IDs and their actual account membership
 
 #### Scenario: Changed and unknown positions
 - **WHEN** a successful read returns newly opened positions including an unknown token mint
@@ -56,3 +60,26 @@ A failed read or mapping SHALL retain the last successful data for that wallet a
 - **WHEN** Phoenix fails for a wallet while Jupiter succeeds, or vice versa
 - **THEN** only the successful venue is updated and the failed venue retains its previous data
 - **AND** subsequent wallets are still attempted
+
+### Requirement: Complete gross and account-aware totals
+Exposure and dollar price PnL SHALL sum through all levels. Exposure SHALL be gross, with positive absolute notionals. Capital and closing Value SHALL count isolated positions and shared Cross accounts once. Missing required components SHALL make only the affected total unavailable. Successfully read empty scopes SHALL total zero. Leverage and PnL percentages SHALL NOT be aggregated.
+
+#### Scenario: Opposite directions and shared collateral
+- **WHEN** two Cross positions have notionals 100 USD Long and 100 USD Short, shared collateral 80 USD, combined PnL 5 USD and closing fees 1 USD
+- **THEN** exposure totals 200 USD, collateral 80 USD and Value 84 USD at account, venue, wallet and root levels
+- **AND** collapsing any UI group does not change totals
+
+#### Scenario: First read fails
+- **WHEN** one configured venue has never been read successfully
+- **THEN** it remains unknown and cannot silently produce complete portfolio totals
+
+### Requirement: Retained observations communicate status
+Each venue SHALL carry its last-success time and whether the latest attempt failed. Failure SHALL preserve positions and account balances independently per wallet/venue. A valid funded empty Cross account SHALL remain visible. Retained data SHALL NOT be described as fresh.
+
+#### Scenario: Last Cross position closes
+- **WHEN** a successful refresh returns a Cross account with nonzero collateral and no positions
+- **THEN** its capital and Value remain included without synthetic positions
+
+#### Scenario: Retained last success
+- **WHEN** a subsequent read fails
+- **THEN** its previous observations remain available with their original success time and failure indication