initial commit

_bmad-output/implementation-artifacts/3-3-historical-rates.md

@@ -0,0 +1,44 @@
+---
+epic: 3
+story: 3.3
+title: "Historical Rates"
+status: draft
+---
+
+## Epic 3 — Currency & Cryptocurrency
+**Goal:** Real-time and historical currency conversion with 180+ fiat and 50+ crypto.
+
+### Story 3.3: Historical Rates
+
+As a CalcPad user,
+I want to convert currencies using historical exchange rates on specific dates,
+So that I can calculate what an amount was worth at a particular point in time.
+
+**Acceptance Criteria:**
+
+**Given** the expression `$100 in EUR on 2024-01-15`
+**When** the engine evaluates it
+**Then** it fetches (or uses cached) the EUR/USD rate from January 15, 2024
+**And** the result reflects the historical conversion
+
+**Given** historical rates for a specific date have been fetched before
+**When** the same date is queried again
+**Then** the cached historical rates are used without a network call
+
+**Given** a historical rate result
+**When** the result is displayed
+**Then** the metadata clearly indicates "historical rate from [date]"
+**And** it is visually distinct from live rate results
+
+**Given** the expression `$100 in EUR on 1900-01-01` (a date before available data)
+**When** the engine evaluates it
+**Then** it returns a `CalcResult::Error` indicating historical rates are not available for that date
+
+**Given** the device is offline and no cached historical rate exists for the requested date
+**When** a historical conversion is requested
+**Then** the engine returns a `CalcResult::Error` indicating the historical rate is not available offline
+
+**Given** the expression `€500 in GBP on March 5, 2023`
+**When** the engine evaluates it
+**Then** it correctly parses the natural-language date format
+**And** fetches the historical rate for 2023-03-05