feat(fiat): multi-provider resilience, best-execution quoting, rate-drift protection

[sammajayi]

Summary

Turns the fiat on-ramp/off-ramp layer from a single hardcoded MoonPay integration into a resilient, price-transparent, multi-provider system, per the problem statement in #313.

• Multi-provider registry with health tracking + failover (src/fiat/registry.ts): per-provider circuit breaker (closed → open after N consecutive failures → half-open after a reset window, matching utils/http-client.ts semantics), and a documented selection policy (DEFAULT, BEST_QUOTE, ROUND_ROBIN_HEALTHY, PREFER_PROVIDER). Failover only ever picks a provider for a new order/quote — an order already in flight stays pinned to the provider that created it.
• Second provider: a deterministic SandboxProvider (src/fiat/providers/sandbox.ts) proves the abstraction supports more than one vendor end-to-end (quote, order, webhook signature verification, reconciliation), registered by default outside production.
• Best-execution quoting: GET /api/v1/fiat/quotes queries every healthy provider in parallel (Promise.allSettled + per-provider timeout), ranks results, and returns the best executable quote plus the full ranked list and any excluded providers with reasons. Each quote is persisted as a time-boxed FiatQuoteLock (default 60s) so POST /fiat/orders can reference a quoteId to lock in that exact rate — an expired lock is rejected with quote_expired rather than silently re-pricing.
• Fee transparency: providers return a structured FeeBreakdown (provider fee / network fee / FX spread) or explicit fees: null + unpriced: true — never an assumed zero.
• Rate-drift protection: FiatOrder gains quoteRate, quotedCryptoAmount, fees, providerQuoteId, rateLockExpiresAt, settledRate, settledCryptoAmount. On settlement, quoted-vs-settled drift is computed; beyond a configurable tolerance (default 2%) it raises an operational alert and a new fiat.order.rate_mismatch webhook. Over-delivery is credited to the user, not capped — still reported for audit visibility.
• Reconciliation hardening: reconcileFiatOrders now matches a candidate on-chain transaction against an order's quoted crypto amount (within tolerance) instead of "most recent unlinked for this user+asset", closing a cross-provider mis-link risk when two providers have concurrent PROCESSING orders for the same user + asset. Provider-keyed webhook idempotency ((provider, providerOrderId)) is unchanged, so a provider's webhook still can never mutate another provider's order.
• Admin ops: GET /api/admin/fiat/providers (health snapshot) and POST /api/admin/fiat/providers/:name/failover (manual circuit override) behind new fiat:read/fiat:write admin scopes, audited via AdminAuditLog.
• Observability: Prometheus metrics for quote latency, quote failure rate, order outcomes, circuit state, and rate drift, all labeled by provider.
• Docs: docs/openapi.yaml updated (new GET /fiat/quotes path, extended CreateFiatOrderRequest/FiatOrder schemas, FeeBreakdown/RankedQuote/BestExecutionQuoteResult schemas, new error responses). Validated with redocly lint / redocly bundle.

Settlement correctness is unchanged/preserved: on-chain confirmation via a CONFIRMED Transaction row owned by the same user remains the sole path to SETTLED; a provider "completed" webhook still only advances an order to PROCESSING.

Test plan

• npx tsc --noEmit — clean
• npx eslint on all touched files — clean
• redocly lint docs/openapi.yaml / redocly bundle — valid (only pre-existing warning categories)
• New unit tests: provider registry (health/circuit breaker/selection policy/admin failover), sandbox provider, best-execution quote ranking + partial-failure/timeout handling, quote-lock consumption/expiry/mismatch rejection, quoted-vs-settled drift alerting (including over-delivery), and a dedicated multi-provider cross-linking regression test (two providers, same user, same asset)
• Extended tests/integration/fiat.integration.test.ts for GET /fiat/quotes and the new order-creation error paths (quote_expired, no_healthy_providers, provider preference passthrough)
• Full suite: npm test → 59 suites / 656 tests passing (also re-verified by the repo's pre-push hook)

Closes #313