102: EMC Perps: show liquidation risk and account health

2026-10-26 06:05:26 +01:00
parent 2f30712004
commit e71a8daa8d
30 changed files with 1070 additions and 48 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-24
@@ -0,0 +1,33 @@
+# 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.
@@ -0,0 +1,31 @@
+# Proposal
+
+## Why
+
+The owner cannot currently distinguish liquidation risk from profitability in EMC. Issue #102 requires venue-reported risk at isolated-position and shared Cross-account level, including honest handling of old or incomplete observations.
+
+## What Changes
+
+- Add venue reference/liquidation prices to Jupiter's overview-only observations.
+- Read Phoenix TraderView risk using officially derived trader addresses independently of TWAP, preserving account thresholds and sentinel handling.
+- **BREAKING**: Phoenix adapter constructors now require the existing SolanaBlockChain dependency for local address derivation; Hub wiring is updated.
+- Add a Risk column, scope-aware summaries and freshness expiration during existing UI polling.
+- Use the owner's selected policy: neutral isolated distance, red only for reached/crossed boundary; Phoenix's own tiers retain their colors.
+- Expire risk observations at five minutes without implying a five-minute safety guarantee. Preserve prior critical states with age/failure annotations.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `jupiter-perps-overview`: reported risk prices and observation timestamps.
+- `phoenix-perps-service`: official address resolution and reported account/position risk.
+- `evelyn-perps-service`: immutable risk scopes with exact distance/utilization and retained status.
+- `evelyn-perps-overview`: Risk cells, deduplicated group summaries and expiration of unchanged snapshots.
+
+## Impact
+
+Integration DTOs/readers, Phoenix's existing Solana dependency wiring, Evelyn snapshots, JavaFX cells and existing project/shared documentation. No new dependencies, trading, live polling, commits or pushes.
@@ -0,0 +1,40 @@
+## MODIFIED 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.
+
+#### Scenario: Open either environment's Perps tab
+- **WHEN** the owner opens Perps in Production or Test
+- **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 a wallet, venue or Cross account
+- **THEN** the group still shows its worst known risk and incomplete-observation counts without changing totals
+
+### 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.
+
+#### 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
+
+## ADDED Requirements
+
+### 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
@@ -0,0 +1,14 @@
+## ADDED Requirements
+
+### Requirement: Risk observations preserve scope and exact meaning
+Snapshots SHALL preserve isolated risk prices and Cross account tiers/thresholds with original observation times. Signed price distance SHALL use the current venue reference as denominator and preserve boundary crossing. Cross MM utilization SHALL use effective collateral, with nonpositive denominators unavailable. Group risk SHALL count each isolated position and shared account once and retain worst known severity plus unknown/stale counts without averaging.
+
+#### Scenario: Shared positions and incomplete data
+- **WHEN** a Cross account owns multiple positions and another scope has unknown risk
+- **THEN** account risk contributes once and the aggregate exposes the unknown count
+- **AND** its closing Value is not substituted for effective collateral
+
+#### Scenario: Boundary and zero denominator
+- **WHEN** isolated distance reaches/crosses zero or effective collateral is nonpositive
+- **THEN** the signed boundary is preserved or MM percentage is unavailable respectively
+- **AND** display rounding does not determine risk classification
@@ -0,0 +1,8 @@
+## ADDED Requirements
+
+### Requirement: Report venue risk prices with observation time
+The overview SHALL expose the venue reference and liquidation prices in exact USD units with the original response observation time. Missing or nonpositive risk prices SHALL be unavailable, never zero safety or infinite distance. Stable position identity and the separate transaction/alarm read path SHALL remain unchanged.
+
+#### Scenario: Missing or sentinel price
+- **WHEN** a valid position has no actionable liquidation price
+- **THEN** its other metrics remain present and its liquidation distance is unavailable
@@ -0,0 +1,14 @@
+## ADDED Requirements
+
+### Requirement: Read venue account health independently of TWAP
+The reader SHALL resolve the official trader account for authority/PDA/subaccount and read its venue risk classification, effective collateral, maintenance margin and position liquidation prices. It SHALL validate identities and amounts, use venue reference prices with original observation times and normalize sentinel liquidation prices to unavailable. Existing pacing, cooldown, timeout and failure retention contracts SHALL apply without signing or TWAP dependence.
+
+#### Scenario: Same-symbol isolated and Cross accounts
+- **WHEN** the wallet holds the same market in multiple accounts without active TWAPs
+- **THEN** each visible account receives only its own reported risk and liquidation data
+- **AND** a mismatched trader identity or position size fails the observation
+
+#### Scenario: Missing or unsupported risk field
+- **WHEN** a response has missing optional risk values or an unknown tier
+- **THEN** those values remain unavailable without assuming a safe state
+- **AND** a nonpositive liquidation-price sentinel does not invalidate independent account health
@@ -0,0 +1,17 @@
+# Tasks
+
+## 1. Integration risk observations
+
+- [x] 1.1 Extend Jupiter overview risk prices and Phoenix account/position risk reads with validated local PDA resolution; verify exact units, sentinels, identities and paced failures in temporary fixtures.
+- [x] 1.2 Update integration documentation for the actual risk sources, units, dependencies and failure behavior; verify against the code and official contracts.
+
+## 2. Snapshot and presentation
+
+- [x] 2.1 Add immutable risk mapping and scope-aware assessments/summaries; verify signed distances, tiers, partial scopes, deduplication and nonpositive collateral with temporary checks.
+- [x] 2.2 Render Risk cells/tooltips and age unchanged snapshots on existing UI polling; verify direction/TWAP preservation, shared scope, critical retention and selection/expansion with JavaFX checks.
+- [x] 2.3 Update Evelyn and shared r35157_docs documentation with the owner-selected neutral-distance policy and five-minute freshness cutoff; verify links and remove conflicting descriptions.
+
+## 3. Integration verification
+
+- [x] 3.1 Run the normal build and focused fixtures/UI/read-only live observations, recording evidence and limitations.
+- [x] 3.2 Sync all four delta specs, validate affected specs/change and inspect final diffs without committing or pushing.
@@ -0,0 +1,96 @@
+# Verification — issue #102
+
+Verified locally on 2026-10-24. The owner explicitly selected neutral isolated
+distance, red only at a reached/crossed boundary, and Phoenix's own tier colors.
+No commit, push, deployment, Hub restart, trading or signing was performed.
+Unrelated pre-existing staged/deleted issue #97/#99 OpenSpec files were preserved.
+
+## Build and focused fixtures
+
+`JAVA_HOME=/usr/local/software/java/jfx-25 ./gradlew build` passed; all 42 existing
+tests passed with no failures/errors. Intermittent inability to delete NFS-held
+test binary output was resolved by normal build retries; no source/build workaround
+was introduced for it.
+
+Temporary `/tmp/Issue102Check.java` passed 68 focused assertions. Coverage includes:
+
+- Exact Long/Short distance, sign-preserved boundary crossing and tiny positive distance.
+- All supported Phoenix tiers, unknown future tiers and missing/sentinel prices.
+- Distinct effective collateral, MM utilization and headroom; negative/zero collateral,
+  zero MM and accounts without positions; missing/contradictory Safe inputs stay uncertain.
+- Five-minute expiration including the exact boundary, future timestamps and failures.
+- Cross counted once, neutral scopes never becoming a group safety rating, and retained
+  critical severity alongside unknown/stale counts, including hidden empty venues.
+- Actual local PDA derivation matching the independently observed official Cross address,
+  distinct isolated addresses and no currency lookup/RPC needed for derivation.
+- HTTP fixtures without active TWAPs, with separate same-market Cross/isolated risk.
+- Amount objects with different/signed decimal exponents, ignored UI strings and rejected
+  invalid scales; original/oldest observation timestamps.
+- Trader authority/key/PDA/subaccount, position membership/quantity and duplicate validation.
+- Missing optional values remain unavailable. HTTP failure retains the prior complete
+  venue/time; independent venue refresh still succeeds; consumer reads cause no I/O.
+- Risk requests obey shared 429 cooldown; empty wallets need no risk calls.
+- Captured Jupiter price fields convert from micro-USD and preserve observation time.
+
+No permanent automated tests were added, consistent with repository conventions.
+
+## JavaFX and visual checks
+
+Temporary `Issue102Preview` passed, including repeated assertions that recycled empty
+cells clear graphics/tooltips. Verified on the actual JavaFX rendering:
+
+- Risk is second among ten columns; neutral isolated distances and color/text tier indicators.
+- Tiny positive distance is shown as `<0.1%`; unsupported values never imply safety.
+- Cross account MM labels, Shared children and owning-account tooltip identification.
+- Worst known group severity plus visibly rendered unknown/stale counts on a separate line.
+- Old critical observations stay red; unchanged snapshots expire with only the injected
+  clock advanced; failed snapshot getters suppress fresh green immediately and recovery works.
+- Stable row-value objects on unchanged fresh data, selection/expansion retention,
+  no table.refresh/rebuild and preserved TWAP duration/graphic behavior.
+- Horizontal scrolling and clearing removed rows. Actual table/tooltip PNGs inspected
+  under `/tmp/issue102-check/`.
+
+The initial extra-line implementation was clipped by JavaFX despite its text being
+present. Final cells use actual primary/secondary graphic labels; the final check
+also inspects rendered Text nodes and the screenshot for the complete counts.
+
+## Read-only live observation
+
+2026-10-24 18:37:35–18:37:49 UTC:
+
+- Jupiter: six configured PROD positions, all with positive reference/liquidation prices.
+- Phoenix: ten positions and one account with independently read/validated account risk
+  on the checked PROD wallet; tier `safe`, effective collateral 92.502602 USD,
+  maintenance margin 31.093010 USD, MM utilization 33.613119336902544644%,
+  headroom 61.409592 USD.
+- TEST Phoenix: zero positions.
+
+Jupiter and Phoenix were checked on different PROD wallets to keep the additional
+Phoenix read volume bounded. These are independent observations, not one atomic
+portfolio valuation; the normal service still passes each configured wallet to
+both venue readers.
+
+An earlier attempt to read the larger wallet encountered HTTP 429 on a mark-price
+request and stopped. No immediate retry occurred; the later smaller-wallet check
+followed cooldown and completed successfully. Live reads used existing pacing and
+only GET operations. Verification artifacts contain no signing keys.
+
+## Specs and documentation
+
+All four deltas were synchronized into existing main specs. Strict validation passed
+for the change and `jupiter-perps-overview`, `phoenix-perps-service`,
+`evelyn-perps-service`, `evelyn-perps-overview`. Relevant project docs and the existing
+shared Evelyn overview were updated; local link targets and change-scoped whitespace
+checks passed. Unrelated existing staged issue #97 specs retain their prior trailing-
+blank-line warnings and were not changed.
+
+## Limits
+
+Risk is the latest observation, not a live alarm or safety guarantee. The five-minute
+cutoff ages receipt timestamps; source APIs can lag the chain, and mark/state/view
+reads are not atomic. Position changes during Phoenix reads can fail identity/quantity
+validation and retain the previous observation until a later successful cycle. Slow
+normal cycles can expire observations. No faster polling, notifications, automatic
+collateral adjustment or local liquidation engine was introduced. Cross tiers and
+MM utilization do not promise future execution outcomes; isolated distance has no
+generic green/yellow safety bands.
@@ -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
@@ -95,3 +95,16 @@ The service SHALL publish immutable TWAP observations only on matching existing
 - **WHEN** the TWAP read fails after a successful venue observation
 - **THEN** prior positions, TWAP observations and original timestamps remain with failed venue status
 - **AND** other venues and wallets continue refreshing
+
+### Requirement: Risk observations preserve scope and exact meaning
+Snapshots SHALL preserve isolated risk prices and Cross account tiers/thresholds with original observation times. Signed price distance SHALL use the current venue reference as denominator and preserve boundary crossing. Cross MM utilization SHALL use effective collateral, with nonpositive denominators unavailable. Group risk SHALL count each isolated position and shared account once and retain worst known severity plus unknown/stale counts without averaging.
+
+#### Scenario: Shared positions and incomplete data
+- **WHEN** a Cross account owns multiple positions and another scope has unknown risk
+- **THEN** account risk contributes once and the aggregate exposes the unknown count
+- **AND** its closing Value is not substituted for effective collateral
+
+#### Scenario: Boundary and zero denominator
+- **WHEN** isolated distance reaches/crosses zero or effective collateral is nonpositive
+- **THEN** the signed boundary is preserved or MM percentage is unavailable respectively
+- **AND** display rounding does not determine risk classification
@@ -27,3 +27,10 @@ The overview SHALL preserve size basis, use post-fee USD collateral and price Pn
 #### Scenario: Nonpositive collateral
 - **WHEN** a position's collateral is zero or negative
 - **THEN** its leverage and PnL percentage are unavailable
+
+### Requirement: Report venue risk prices with observation time
+The overview SHALL expose the venue reference and liquidation prices in exact USD units with the original response observation time. Missing or nonpositive risk prices SHALL be unavailable, never zero safety or infinite distance. Stable position identity and the separate transaction/alarm read path SHALL remain unchanged.
+
+#### Scenario: Missing or sentinel price
+- **WHEN** a valid position has no actionable liquidation price
+- **THEN** its other metrics remain present and its liquidation distance is unavailable
@@ -79,3 +79,16 @@ The reader SHALL estimate future execution times from snapshot slot, due slot an
 #### 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
+
+### Requirement: Read venue account health independently of TWAP
+The reader SHALL resolve the official trader account for authority/PDA/subaccount and read its venue risk classification, effective collateral, maintenance margin and position liquidation prices. It SHALL validate identities and amounts, use venue reference prices with original observation times and normalize sentinel liquidation prices to unavailable. Existing pacing, cooldown, timeout and failure retention contracts SHALL apply without signing or TWAP dependence.
+
+#### Scenario: Same-symbol isolated and Cross accounts
+- **WHEN** the wallet holds the same market in multiple accounts without active TWAPs
+- **THEN** each visible account receives only its own reported risk and liquidation data
+- **AND** a mismatched trader identity or position size fails the observation
+
+#### Scenario: Missing or unsupported risk field
+- **WHEN** a response has missing optional risk values or an unknown tier
+- **THEN** those values remain unavailable without assuming a safe state
+- **AND** a nonpositive liquidation-price sentinel does not invalidate independent account health