com_r35157_nenjim-hubd-impl_ref/openspec/specs/evelyn-status-index-history/spec.md

evelyn-status-index-history Specification

Purpose

Provide typed process-local Evelyn status measurements and visualize the currently implemented live indexes over time in Mission Control while preserving the six-index model for future work.

Requirements

Requirement: Evelyn calculates the live price index

Evelyn SHALL obtain the actual EVE/USDT price from the latest AssetAZ Ticker observation for the canonical EVE/USDT trading pair. It SHALL treat USDT as USD for this calculation and SHALL NOT access Raydium directly. At sampling instant t, on or after 2026-07-31T22:00:00Z, the expected price SHALL be 15 × 1.20^(elapsedSeconds / 31,536,000) and the Evelyn Price Index SHALL be ((actualPrice / expectedPrice) - 1) × 10, calculated with adequate decimal precision and without arbitrary history rounding.

Scenario: Calculate expected price at the configured start

• WHEN the sampling instant is 2026-07-31T22:00:00Z
• THEN the expected EVE price is exactly 15 USD

Scenario: Calculate expected price after one year

• WHEN exactly 31,536,000 seconds have elapsed since the configured start
• THEN the expected EVE price is exactly 18 USD

Scenario: Calculate representative fractional-year growth

• WHEN 18 days, 3 hours, 8 minutes, and 14 seconds have elapsed
• THEN the expected EVE price is approximately 15.136464436276 USD

Scenario: Calculate index from actual price

• WHEN actual price equals expected price, is 10 percent above, is 10 percent below, is double, or is half the expected price
• THEN the respective index is 0, 1, -1, 10, or -5

Requirement: Evelyn samples without overlapping or catch-up attempts

Each started Evelyn environment SHALL own its sampling executor, attempt its first sample immediately, and make subsequent attempts approximately one minute after the preceding attempt completes. Sampling SHALL remain active for the Evelyn lifecycle independently of whether Mission Control is open. Evelyn SHALL add exactly one timestamped point per successful attempt and SHALL isolate a failed or temporarily unavailable Ticker lookup without adding a fake point, terminating Evelyn, or cancelling the next attempt. Stopping Evelyn SHALL terminate its sampling executor.

Scenario: Initial Ticker data is unavailable

• WHEN the immediate sampling attempt cannot obtain a latest EVE/USDT price
• THEN no point is added, diagnostic context is logged, and the next fixed-delay attempt remains scheduled

Scenario: A later sample succeeds

• WHEN a later attempt obtains a latest EVE/USDT price
• THEN exactly one point is appended using the sampling instant for both expected-price calculation and point timestamp

Requirement: Evelyn provides historical status-index measurements

Each Evelyn instance SHALL begin with an empty, process-local in-memory history and expose a safe, non-null snapshot of typed measurement points ordered from oldest to newest while sampling may continue concurrently. Each successful point SHALL contain its sampling timestamp, the calculated Evelyn Price Index, and BigDecimal.ZERO placeholders for EVE_SYRUP Pool Depth Index, EVE_SYRUP Pool Balance Index, AAZDKK_USDT Pool Balance Index, AAZDKK_USDT Pool Price Index, and AAZDKK_USDT Pool Depth Index. Production and Test SHALL use separate history collections, and no point SHALL be persisted, restored, or backfilled.

Scenario: Status-index history is requested during sampling

• WHEN a caller requests an Evelyn environment's status-index history while points may be appended
• THEN it receives a safe, non-null, oldest-to-newest snapshot containing all six typed fields

Scenario: A process starts two Evelyn environments

• WHEN Production and Test Evelyn instances are created for a new process
• THEN both histories start empty and remain separate even if their calculated values are identical

Scenario: A real point is sampled

• WHEN Evelyn appends a successful price-index point
• THEN its Evelyn Price Index contains the calculated value and each of the other five fields contains zero

Scenario: An Evelyn instance is stopped

• WHEN a Production or Test Evelyn instance is stopped
• THEN its sampling executor terminates and its complete process-local history is discarded without affecting the other environment

Requirement: Evelyn Mission Control visualizes status-index measurements

Evelyn Mission Control SHALL display separate live Production and Test Overview charts from their corresponding authoritative Evelyn snapshots. Each chart SHALL contain one enabled series named Evelyn Price Index; the five future series and their typed fields SHALL remain available as disabled source scaffolding. Opening or reopening EMC SHALL immediately reconstruct each chart from the complete current snapshot before periodically refreshing it. Successful points SHALL be added to chart objects only on the JavaFX Application Thread while the window remains open. Timestamp bounds SHALL expand as points arrive, and only enabled Evelyn Price Index values SHALL determine a dynamic Y-axis range that is symmetric around and always displays zero, using a reasonable default range for empty or all-zero history. Hiding or closing EMC SHALL release only EMC's JavaFX refresh resources and SHALL NOT start, stop, or clear either Evelyn environment.

Scenario: Production and Test Overviews start empty

• WHEN Mission Control opens with two newly created Evelyn environments
• THEN it displays two separate empty one-series charts with valid timestamp axes and symmetric Y-axes containing zero

Scenario: A successful point appears while EMC is open

• WHEN an Evelyn history receives a new successful point
• THEN the corresponding chart adds it on the JavaFX Application Thread and updates its timestamp and symmetric price-index bounds without reopening EMC

Scenario: EMC reopens after collecting hidden-window samples

• WHEN the same EMC instance is reopened after Evelyn collected additional points while its window was hidden
• THEN each chart is reconstructed immediately from its environment's complete current history without missing points because of stale rendering state

Scenario: Future fields contain larger values

• WHEN any disabled future-index field has a greater absolute value than Evelyn Price Index
• THEN that disabled value does not affect the visible Y-axis bounds