101: EMC Perps - show Phoenix TWAP progress and time until next suborder

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

@@ -21,15 +21,20 @@ Position direction SHALL follow signed quantity. USD size SHALL be the absolute
 - **THEN** it represents -1.25 base units, Short direction and 130.5625 USD notional
 
 ### Requirement: Read failures cannot masquerade as empty portfolios
-HTTP, authentication, malformed schema, identity mismatch and numeric conversion errors SHALL fail the read. Requests SHALL have bounded timeouts. Only a valid response with no nonzero positions SHALL produce an empty result. Required mark prices SHALL be positive and finite.
+HTTP, authentication, malformed schema, identity mismatch and numeric conversion errors SHALL fail the read. Requests SHALL have bounded timeouts. Only a valid response with no nonzero positions SHALL produce an empty result. Present mark prices SHALL be positive and finite; an explicitly absent mark SHALL preserve positions and quantities with unavailable price-dependent valuations.
 
-#### Scenario: Missing mark price or rejected access
-- **WHEN** a required price is missing or an HTTP request is rejected
+#### Scenario: Missing mark price
+- **WHEN** a valid mark response has no mark price for a held position
+- **THEN** the position and its TWAP quantities remain present with unknown USD valuations
+- **AND** affected aggregate valuations remain unknown
+
+#### Scenario: Rejected access or invalid price
+- **WHEN** an HTTP request is rejected or a present mark price is invalid
 - **THEN** the read fails instead of returning an empty or partial portfolio
 
 #### Scenario: Empty account
 - **WHEN** a valid trader snapshot has no subaccounts or no nonzero positions
-- **THEN** an empty result is returned without market-price requests
+- **THEN** an empty result is returned without market-price or TWAP requests
 
 #### Scenario: Public API rate limit
 - **WHEN** the shared adapter issues requests for PROD and TEST
@@ -55,3 +60,22 @@ Equity SHALL include collateral, undiscounted price PnL and signed unsettled fun
 - **WHEN** collateral is 100 USD, PnL 5 USD, unsettled funding -2 USD, and estimated exit fee 1 USD
 - **THEN** equity is 103 USD and estimated Value 102 USD
 - **AND** effective Cross leverage uses 103 USD as its denominator
+
+### Requirement: Read precise TWAP snapshots for held markets
+The reader SHALL read official TWAP snapshots through its existing paced transport and associate orders by authority, PDA, subaccount and market identity. Only orders with actual fills and remaining children on an existing position SHALL be exposed. Quantities SHALL use exact lot conversion and explicit/legacy dust semantics. Unavailable size inputs SHALL remain unknown. Existing mark prices SHALL be reused without Ticker reads.
+
+#### Scenario: Explicit and legacy dust
+- **WHEN** total children are 5, regular size 10 lots and explicit dust count/size are 2/3
+- **THEN** total size is 36 lots and the fourth child is 3 lots
+- **AND** legacy zero dust count with size 3 instead represents four regular children and a final 3-lot child
+
+#### Scenario: Identity mismatch or unfilled order
+- **WHEN** authority/PDA/subaccount/asset identities disagree or an order has no fills
+- **THEN** disagreement fails the read, while a valid unfilled order is absent from returned positions' TWAP data
+
+### Requirement: TWAP time estimates disclose their slot assumption
+The reader SHALL estimate future execution times from snapshot slot, due slot and cooldown using a documented nominal slot duration and response observation time. Completion SHALL derive from remaining executions, never expiry. Already-due schedules, invalidated completion schedules and unrepresentable estimates SHALL remain unavailable instead of predicting fills.
+
+#### Scenario: Expiry before planned completion
+- **WHEN** the scheduled final child lies beyond the order's expiry
+- **THEN** the reader does not provide that schedule as an estimated completion time