id: CORE-002
title: Instrument-Aware Quote Units and Conversion Multipliers
status: backlog
priority: P0
effort: M
depends_on:
  - CORE-001A
  - CORE-001B
  - CORE-001C
tags: [core, units, pricing, domain]
summary: >
  Complete the instrument-aware quote-unit rollout so quoted instruments like GLD are
  handled explicitly as USD/share and only converted to ounce-equivalent values through
  named metadata-backed seams.
acceptance_criteria:
  - GLD quotes are modeled explicitly as prices per share, not as ambiguous gold-ounce prices.
  - Instrument metadata encodes that 1 GLD share represents 0.1 troy ounces of gold exposure.
  - Storage/domain value classes know the unit relationship and convert correctly when calculations combine instrument prices with ounce-based quantities.
  - Cross-unit operations fail closed when no explicit instrument conversion path exists.
  - Visible ounce-based pages beyond overview use the explicit conversion seam instead of heuristic fallbacks.
  - Tests cover GLD share <-> troy-ounce conversion and reject unsupported mixed-unit operations.
technical_notes:
  - `CORE-002A` is complete: overview now uses explicit GLD share -> USD/ozt conversion with quote-unit metadata and cache normalization.
  - Next suggested slice is `CORE-002B`: apply the same explicit quote-unit model to the next visible ounce-based path, especially hedge/runtime portfolio displays that still assume ounce-native spots.
  - Prefer explicit instrument/unit types over ad hoc scale factors in page/service code.
  - This should integrate with the Decimal/unit-safe domain model rather than bypass it with raw floats.
  - Consider extending historical/unit types so both live overview paths and backtesting/event paths can share the same conversion rules.