suaveplan/openspec/archive/2026-05-17-add-currency-provider-virtual/proposal.md

# Add @suaveplan/currency-provider-virtual

**Package**: `@suaveplan/currency-provider-virtual`
**Status**: PROPOSED
**Type**: new package (sibling of `@suaveplan/currency-providers` slim core)

- **Design**: ./design.md
- **Spec delta**: ./specs/currency-provider-virtual/spec.md

## Why

The 2026-05-17 `slim-currency-providers` refactor split the original 9-provider
bundle into a slim core (`@suaveplan/currency-providers`) plus nine sibling
`@suaveplan/currency-provider-<name>` packages. Of the nine, eight wrap remote
HTTP APIs (ECB, Fixer, OXR, Binance, CoinGecko, CoinMarketCap, CryptoCompare,
Kraken); the ninth — **virtual** — serves operator-defined virtual / game
currencies whose rates are programmable in memory and never round-trip a
network.

This change lands the virtual sibling. It is the only sibling that does NOT
consume `httpRequest` / `FetchLike` from the slim core (it has no upstream to
fetch) and that DOES set `supportsVirtual: true` on the
`CurrencyProvider` contract.

## What changes

### ADDED

- New package `@suaveplan/currency-provider-virtual` at
  `packages/finance/currency-provider-virtual/` (universal-tier, `0.1.0`).
- `VirtualCurrencyProvider` — implements `CurrencyProvider` from
  `@suaveplan/currency`. Constructor takes an initial rate table and an
  optional `Clock` (default `Date.now`) used for `fetchRates` timestamps. No
  HTTP, no API key, no `FetchLike`.
- Programmable rate-table API: `setRate(from, to, rate)`,
  `removeRate(from, to): boolean`, `clear()`, plus the read helpers
  `hasRate(from, to)`, `getRate(from, to)`, `listCurrencies(): readonly string[]`.
- `fetchRates(options?)` — returns every rate denominated against the
  requested `base` (default the provider's `defaultBase`), filtered by the
  optional `targets` set, with `timestamp` derived from the injected `Clock`.
- Raises `CurrencyProviderError(UNKNOWN_CURRENCY)` (registered in
  `@suaveplan/currency-providers`) when `fetchRates` is asked for a base that
  is not present in the rate table — there is no triangulation, the registry
  can be empty.

### KEPT (inherited)

- `CurrencyProvider` contract from `@suaveplan/currency` (unchanged).
- `CurrencyProviderError` + `CURRENCY_PROVIDER_CODES.UNKNOWN_CURRENCY` from
  `@suaveplan/currency-providers` (already present in the 8-code slim-core
  registry).
- Universal-tier purity (zero browser / Node APIs in `src/`), explicit named
  barrels, `@suaveplan/testing/runner` imports, 100/100/100/100 istanbul
  coverage.

## Source mapping

The upstream reference shape lived in
`../suaveplan/packages/finance/currency-providers/src/virtual/virtual.ts`
(pre-slim, now removed). That upstream shape coupled the provider to
`@suaveplan/money` (`registerCurrency`) and stored rates as a record of
`VirtualCurrencyConfig { rate, name, symbol, exponent?, issuerId? }` keyed by
currency code, assuming a single shared base.

| Capability | Upstream | Migrated | Notes |
|---|---|---|---|
| Programmable per-currency rate table | ✅ | ✅ | Surface generalised — `setRate(from, to, rate)` lets callers store arbitrary directed pairs (game internal rates, partial graphs) rather than only "one base, many targets". |
| `fetchRates({ base, targets })` | ✅ | ✅ | |
| `supportsVirtual: true` flag | ✅ | ✅ | |
| Triangulation from any virtual base | ✅ | 🚫 | Scoped out: the slim-core / `CurrencyConverter` already handles triangulation via the rate cache; duplicating it here would split the algorithm across two packages. Callers that need triangulated rates either pre-populate both directions with `setRate` or wire the provider through `CurrencyConverter` which triangulates from the cached `RateFetchResult`. |
| Auto-registering currencies via `@suaveplan/money` `registerCurrency` | ✅ | 🚫 | Scoped out: the slim refactor explicitly dropped the `@suaveplan/money` dep so the slim core stays universal and zero-side-effect. Callers that want money-registry integration call `registerCurrency` themselves before constructing the provider — keeps this package side-effect-free per `sideEffects: false`. |
| `Clock`-injected `timestamp` for deterministic tests | ⬆️ | ⬆️ | Enhanced: upstream hard-coded `Date.now()`. We inject a `Clock` so `FakeClock`-driven tests get deterministic timestamps without monkey-patching `Date`. |
| `UNKNOWN_CURRENCY` typed error | ⬆️ | ⬆️ | Enhanced: upstream threw plain `Error("VirtualCurrencyProvider: no rates for base UNKNOWN")`. We throw `CurrencyProviderError(CURRENCY_PROVIDER.UNKNOWN_CURRENCY)` with `providerName` populated. |
| `defineCurrencyProvider`-friendly | ⬆️ | ⬆️ | Enhanced: the provider exposes a stable class with the programmable methods AND can be wrapped via `defineCurrencyProvider` if a consumer prefers the object-literal idiom. |

The enterprise audit reference is
`../suaveplan/enterprise/currency-providers.md`; the virtual provider is one
row in that audit and carried no specific gaps beyond the registry-typed-error
gap, which is closed here.

## Impact

### Affected dependents

Run `bunx turbo ls --filter=...@suaveplan/currency-provider-virtual` to enumerate.

- No current dependents (verified by `bunx turbo ls --filter=...@suaveplan/currency-provider-virtual`).

The package is a leaf sibling — the future commerce / gaming stack downstream
will consume it directly, but those packages are still pending migration.

## Out of scope

- Triangulation across the rate table (see Parity Checklist row).
- `@suaveplan/money` `registerCurrency` integration (see Parity Checklist row).
- Persistence — the rate table is purely in-memory by design (this provider's
  whole purpose). Callers that need persistence layer a storage adapter on top
  and reload the table at construction.
- `AbortSignal` plumbing on `fetchRates` — the operation is synchronous over
  an in-memory `Map`; an injected `signal` would have nothing to abort. The
  optional `signal` from `RateFetchOptions` is accepted by the type but
  unused.