102: EMC Perps: show liquidation risk and account health

2026-10-25 16:35:17 +01:00
parent 2f30712004
commit b4c7fe87d9
30 changed files with 1070 additions and 48 deletions
@@ -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.