# Tasks — add @suaveplan/currency

> Every checkbox MUST reflect work actually done in this change.

## 1. Spec authoring

- [x] 1.1 Read `../suaveplan/enterprise/currency.md` end-to-end
- [x] 1.2 `openspec/specs/currency/spec.md` does not exist — confirmed
- [x] 1.3 Read `openspec/AGENTS.md` Sections 13 and 14
- [x] 1.4 Draft `proposal.md` from `openspec/templates/proposal.md`
- [x] 1.5 Fill in `## Source mapping` table — every requirement cites a line range
- [x] 1.6 Draft `specs/currency/spec.md` from `openspec/templates/spec-delta.md`
- [x] 1.7 Every requirement carries a `**Verified by:**` line naming concrete `it(...)` titles

## 2. Implementation

- [x] 2.1 Scaffold `packages/finance/currency/` (`package.json`, `tsconfig.json`, `tsconfig.lib.json`, `vite.config.ts`, `vitest.config.ts`, `tests/setup/polyfills.ts`, `README.md`)
- [x] 2.2 `src/types/common.ts` — `CurrencyProvider`, `ExchangeRate`, `RateFetchOptions`, `RateFetchResult`, `VirtualCurrencyConfig`, `ConverterConfig`, `ConvertOptions`, `ConversionResult` (all named interfaces; no inline shapes)
- [x] 2.3 `src/error-codes/error-codes.ts` — `CURRENCY_CODES` registry + `CurrencyError extends SuaveplanError<CurrencyErrorCode>` with optional `from` / `to` / `providerName` discriminants
- [x] 2.4 `src/schemas/schemas.ts` — Zod schemas + `parseConverterConfig` / `parseConvertOptions` / `parseVirtualCurrencyConfig` / `parseRateFetchOptions` helpers that throw `CurrencyError`
- [x] 2.5 `src/rate-cache/rate-cache.ts` — `RateCache` class with TTL eviction, direct / inverse / triangulated lookup
- [x] 2.6 `src/provider/provider.ts` — `InMemoryProvider` class + `createStaticProvider` factory honouring AbortSignal
- [x] 2.7 `src/converter/converter.ts` — `CurrencyConverter` class with fallback chain, triangulation, virtual currency, AbortSignal, Zod-validated boundary, enriched `ConversionResult`
- [x] 2.8 `src/index.ts` — explicit named re-exports
- [x] 2.9 Sub-path exports declared in `package.json` for every public module

## 3. Tests

- [x] 3.1 `src/converter/converter.test.ts` — every requirement scenario
- [x] 3.2 `src/rate-cache/rate-cache.test.ts` — every requirement scenario
- [x] 3.3 `src/provider/provider.test.ts` — every requirement scenario
- [x] 3.4 `src/error-codes/error-codes.test.ts` — every `CURRENCY.*` code reachable from a call site; SuaveplanError contract preserved
- [x] 3.5 `src/schemas/schemas.test.ts` — every Zod schema accepts a valid payload and rejects each documented bad shape
- [x] 3.6 Every `it(...)` carries `{ timeout: 5000 }`
- [x] 3.7 All test files import runner primitives from `@suaveplan/testing/runner`

## 4. Documentation

- [x] 4.1 Sibling `.md` for every implementation `.ts` (≥200 words, basic + advanced examples, full API reference)
- [x] 4.2 `README.md` links every co-located `.md` under `## Modules`
- [x] 4.3 Update `MANIFEST.md` / `STATUS.md` / `SUMMARY.md` / `MISSING.yml` on archive

## 5. Pre-archive verification (the 5-gate triple)

- [x] 5.1 `bun run check` — Biome 0 errors / 0 warnings / 0 info on touched files
- [x] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/currency` — green
- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/currency` — 100/100/100/100
- [x] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/currency` — exit 0 (if script applies)
- [x] 5.5 `bunx turbo build --filter=@suaveplan/currency` — green

## 6. Pre-archive 9-row checklist (skill SKILL.md step 7)

- [x] 6.1 Generics threaded; literal-type assertions on every literal-type claim
- [x] 6.2 Zod schemas wired at every declared boundary (`CurrencyConverter` constructor + `convert` / `convertAmount` / `getRate` entry)
- [x] 6.3 Every `CURRENCY.*` code thrown by at least one production path
- [x] 6.4 Strict-mode behaviours (AbortSignal cancellation; identity short-circuit) tested
- [x] 6.5 No OTel instruments shipped this change (deferred — see proposal `## Out of scope`)
- [x] 6.6 Lifecycle dedup tested (virtual-currency reseed after every provider fetch)
- [x] 6.7 No retroactive tick — every box above reflects work done in this change
- [x] 6.8 No `export *` in any feature-module barrel
- [x] 6.9 No direct `vitest` / `bun:test` imports in test files

## 7. Archive

- [x] 7.1 Fold spec delta into `openspec/specs/currency/spec.md`
- [x] 7.2 Move `openspec/changes/add-currency/` → `openspec/archive/2026-05-17-add-currency/`
- [x] 7.3 Refresh `MANIFEST.md`, `MISSING.yml`, `STATUS.md`, `SUMMARY.md`