2.8 KiB
Design
Context
See proposal.md for motivation. Jupiter already parses optional micro-USD fields through strict decimal-integer validation. Immutable snapshot Metrics own completeness-aware totals; venue totals add isolated positions and shared Cross accounts once. EMC formats those totals independently of visible descendants.
Goals / Non-Goals
Goals: Carry numeric Value and its estimate provenance together through the existing pipeline, preserving original observation/failure semantics and source compatibility for existing constructors.
Non-Goals: Correcting Jupiter fees, verifying closing proceeds, adding network requests, changing Phoenix valuation formulas, or modifying refresh/configuration.
Decisions
- Extend the overview position with nullable USD Value, using the existing exact micro-USD parser. Retain earlier constructors with unavailable Value defaults. An independent decimal parser would risk a different validation contract.
- Add an immutable set of Value estimate sources to Metrics (Jupiter/Phoenix). Mark each integration's available closing Values and union sources in totals. A single boolean would lose the source-specific explanation at mixed wallet/root levels; deriving qualification from rendered descendants would fail when groups are hidden/collapsed.
- Estimate sources survive incomplete totals so their tooltips can still explain the contributions. Numeric availability controls whether a marker is shown. Totals still apply the existing all-components-required rule. Empty sums remain zero. Source sets do not affect other metrics or Cross account ownership.
- Format Value with a single prefix only for available qualified amounts. Add source explanations to the Value cell tooltip from its Metrics, so ancestors do not depend on descendant notes. Preserve the existing position notes, read status and USD rounding.
- Verify with temporary deterministic HTTP/service/JavaFX harnesses outside the repository, following the project's separate test-artifact policy. Record checks in verification.md.
Risks / Trade-offs
- Reported Jupiter estimates may differ materially from closing proceeds → use the number as supplied and describe observed fee uncertainty plus unverified collateral/profit-cap semantics at contributing scopes.
- Losing qualification during aggregation → keep provenance in immutable Metrics and verify mixed, missing, zero and collapsed totals.
- Mistaking retained values for new observations → keep the existing whole-venue retention path and verify original timestamps through failure/recovery.
Migration Plan
No stored schema or configuration migration. Rebuild the existing source; retained constructors support current callers. Deploy/restart remains outside this implementation task. Reverting the source restores the previous presentation.