@seasonkoh/webaz 0.1.28 → 0.1.29

package/dist/direct-receive-deposits.js

@@ -0,0 +1,260 @@
+import { toUnits, toDecimal } from './money.js';
+import { getDepositRail, assertProductionDepositRail } from './deposit-rails.js';
+import { assertBondRailCleared } from './direct-pay-bond-rail-clearance.js';
+import { recordBaseBondSlash } from './direct-pay-ledger.js';
+/** LOCKED 保守默认(治理可调)。T0 = 固定 token 数(标签 ≈ S$500,非 FX)。 */
+export const DEFAULT_BASE_BOND_CONFIG = {
+    tierRequiredUnits: { T0: toUnits(500) },
+    pendingTtlDays: 7,
+};
+const isNonNegUnits = (x) => typeof x === 'number' && Number.isSafeInteger(x) && x >= 0;
+const getRow = (db, id) => db.prepare('SELECT id, user_id, tier, required_amount, amount, currency, deposit_rail, status, production_receipt_confirmed_at, created_at FROM direct_receive_deposits WHERE id = ?').get(id);
+/** 某档要求的【固定 token 数】(整数 base-units)。未配置的档 → 抛(T1/T2 在 PR-5 才支持)。 */
+export function requiredBondUnits(tier, config = DEFAULT_BASE_BOND_CONFIG) {
+    const u = config.tierRequiredUnits[tier];
+    if (!isNonNegUnits(u) || u <= 0)
+        throw new Error(`requiredBondUnits: tier '${tier}' 未配置或非正整数 units(4b-min 仅支持已配置档,通常 T0)`);
+    return u;
+}
+/** 开新存款:创建 pending 行。required = 该档固定 token 数。amount=0(待 confirm)。 */
+export function openDeposit(db, args) {
+    const { depositId, userId, tier, currency, depositRail, config } = args;
+    if (!depositId || !userId)
+        return { ok: false, reason: 'missing depositId/userId' };
+    // WAZ NOT enabled:base bond 只接受【外部资产币种】usdc | fiat(生产收款仍 GATED);'waz' 一律 fail-closed,
+    //   杜绝把 schema 默认 currency='waz' 固化成合法路径(防 4c/4f 误接成"WAZ 担保物可用")。
+    if (!['usdc', 'fiat'].includes(currency))
+        return { ok: false, reason: `currency '${currency}' not allowed for base bond (only usdc|fiat; WAZ not enabled)` };
+    if (!['manual', 'operator_attested', 'usdc_onchain', 'fiat_psp'].includes(depositRail))
+        return { ok: false, reason: `invalid deposit_rail '${depositRail}'` };
+    if (getRow(db, depositId))
+        return { ok: false, reason: 'deposit already exists' };
+    let required;
+    try {
+        required = requiredBondUnits(tier, config);
+    }
+    catch (e) {
+        return { ok: false, reason: e.message };
+    }
+    db.prepare(`INSERT INTO direct_receive_deposits (id, user_id, tier, required_amount, amount, currency, deposit_rail, status, created_at, updated_at)
+    VALUES (?,?,?,?,0,?,?, 'pending', datetime('now'), datetime('now'))`)
+        .run(depositId, userId, tier, toDecimal(required), currency, depositRail);
+    return { ok: true, status: 'pending' };
+}
+/**
+ * 确认到账(经 deposit-rail 网关)。
+ *  - manual rail:仅 test/non-production —— 置 amount + status=confirmed,**绝不**设 production_receipt_confirmed_at。
+ *  - usdc_onchain / fiat_psp:getDepositRail().confirmReceipt() 直接【抛】(GATED,fail-closed),本函数不吞。
+ * production_receipt_confirmed_at 只由【未来的 legal-cleared 生产 rail】设置(当前不存在)→ 本 PR 后恒 NULL。
+ */
+export function confirmDepositReceipt(db, args) {
+    const { depositId, expectedAmountUnits, externalRef } = args;
+    const row = getRow(db, depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    // 生产 rail(operator_attested / usdc_onchain / fiat_psp)只能走 confirmProductionReceipt(ROOT + Passkey + Lock B)。
+    //   confirmDepositReceipt 是【非生产 / manual 专用】路径 —— 任何生产 rail 在此即抛(fail-closed),杜绝被
+    //   confirmDepositReceipt + lockBond 锁成 active privilege、绕过生产确认门(operator_attested 的 record-only
+    //   confirmReceipt 不会自己抛,故必须在此显式拦)。
+    if (getDepositRail(row.deposit_rail).isProduction) {
+        throw new Error(`deposit-rail '${row.deposit_rail}' is a production rail — must use confirmProductionReceipt (ROOT + Passkey); confirmDepositReceipt is manual/non-production only`);
+    }
+    if (row.status === 'confirmed' || row.status === 'locked')
+        return { ok: true, status: row.status, already: true }; // 幂等
+    if (row.status !== 'pending' && row.status !== 'insufficient')
+        return { ok: false, reason: `cannot confirm from status '${row.status}'` };
+    if (!isNonNegUnits(expectedAmountUnits) || expectedAmountUnits <= 0)
+        return { ok: false, reason: 'expectedAmount must be a positive integer base-units' };
+    // 网关:manual → confirmed(test);usdc/fiat → 抛(GATED)。本函数不 try/catch 网关,让 GATED 抛穿透(fail-closed)。
+    const conf = getDepositRail(row.deposit_rail)
+        .confirmReceipt({ depositId, expectedAmount: expectedAmountUnits, currency: row.currency, externalRef });
+    if (!conf.confirmed)
+        return { ok: false, reason: conf.reason || 'receipt not confirmed' };
+    // manual = 非生产 → 绝不写 production_receipt_confirmed_at(保持 NULL)。
+    db.prepare(`UPDATE direct_receive_deposits SET amount = ?, status = 'confirmed', confirmed_at = datetime('now'),
+    external_ref = COALESCE(?, external_ref), updated_at = datetime('now') WHERE id = ?`)
+        .run(toDecimal(expectedAmountUnits), conf.externalRef ?? externalRef ?? null, depositId);
+    return { ok: true, status: 'confirmed' };
+}
+/** 锁定:confirmed 且 amount ≥ required → locked + 激活 privilege(单事务)。WAZ NOT enabled → 不动任何余额。 */
+export function lockBond(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (row.status === 'locked')
+        return { ok: true, status: 'locked', already: true }; // 幂等
+    if (row.status !== 'confirmed')
+        return { ok: false, reason: `cannot lock from status '${row.status}' (must be confirmed)` };
+    if (toUnits(row.amount) < toUnits(row.required_amount))
+        return { ok: false, reason: 'insufficient: amount < required' };
+    db.transaction(() => {
+        db.prepare("UPDATE direct_receive_deposits SET status = 'locked', locked_at = datetime('now'), updated_at = datetime('now') WHERE id = ?").run(args.depositId);
+        // ⚠️ privilege=active 在 4b-min 是【非生产】(manual/test;本 PR 的 lock 不带 production_receipt_confirmed_at)。
+        //   active 本身【不是】production go-live 的充分条件 —— 生产门是 isProductionBaseBondLocked()(production receipt 非 NULL),
+        //   由 4c 强制;active 仅表示"已走完非生产 lock 流程"。
+        db.prepare(`INSERT INTO direct_receive_privileges (user_id, status, tier, granted_at, updated_at)
+      VALUES (?, 'active', ?, datetime('now'), datetime('now'))
+      ON CONFLICT(user_id) DO UPDATE SET status='active', tier=excluded.tier, suspended_reason=NULL, granted_at=COALESCE(direct_receive_privileges.granted_at, excluded.granted_at), updated_at=datetime('now')`)
+            .run(row.user_id, row.tier);
+    })();
+    return { ok: true, status: 'locked' };
+}
+/** 标记不足:confirmed 但 amount < required → insufficient(待 top-up)。 */
+export function markInsufficient(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (row.status === 'insufficient')
+        return { ok: true, status: 'insufficient', already: true };
+    if (row.status !== 'confirmed')
+        return { ok: false, reason: `cannot mark insufficient from status '${row.status}'` };
+    if (toUnits(row.amount) >= toUnits(row.required_amount))
+        return { ok: false, reason: 'amount already meets required' };
+    db.prepare("UPDATE direct_receive_deposits SET status = 'insufficient', updated_at = datetime('now') WHERE id = ?").run(args.depositId);
+    return { ok: true, status: 'insufficient' };
+}
+/** 补足:amount += add(整数 units)。若达/超 required 且当前 insufficient/confirmed → 置 confirmed(可再 lock)。 */
+export function topUp(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (!isNonNegUnits(args.addUnits) || args.addUnits <= 0)
+        return { ok: false, reason: 'addUnits must be a positive integer base-units' };
+    if (!['confirmed', 'insufficient'].includes(row.status))
+        return { ok: false, reason: `cannot top-up from status '${row.status}'` };
+    const newAmount = toUnits(row.amount) + args.addUnits;
+    db.prepare("UPDATE direct_receive_deposits SET amount = ?, status = 'confirmed', updated_at = datetime('now') WHERE id = ?")
+        .run(toDecimal(newAmount), args.depositId);
+    return { ok: true, status: 'confirmed' };
+}
+/** 过期:pending 且超过 TTL → expired。 */
+export function expireDeposit(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (row.status !== 'pending')
+        return { ok: false, reason: `only pending can expire (got '${row.status}')` };
+    const ttlDays = args.config?.pendingTtlDays ?? DEFAULT_BASE_BOND_CONFIG.pendingTtlDays;
+    const created = Date.parse(row.created_at), now = Date.parse(args.nowIso);
+    if (!Number.isFinite(created) || !Number.isFinite(now))
+        return { ok: false, reason: 'unparseable timestamps' };
+    if (now - created < ttlDays * 86_400_000)
+        return { ok: false, reason: 'not yet past TTL' };
+    db.prepare("UPDATE direct_receive_deposits SET status = 'expired', updated_at = datetime('now') WHERE id = ?").run(args.depositId);
+    return { ok: true, status: 'expired' };
+}
+/**
+ * 罚没(卖家违约):locked → slashed,仅记 provenance(recordBaseBondSlash:total_base_bond_slash + txn),
+ *  **不动任何 balance / 无 outflow**(WAZ NOT enabled),并吊销 privilege(suspended)。单事务,幂等。
+ */
+export function slashBond(db, args) {
+    const row = getRow(db, args.depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (row.status === 'slashed')
+        return { ok: true, status: 'slashed', already: true }; // 幂等:不重复记 provenance
+    if (row.status !== 'locked')
+        return { ok: false, reason: `can only slash a locked bond (got '${row.status}')` };
+    db.transaction(() => {
+        recordBaseBondSlash(db, { userId: row.user_id, amountUnits: toUnits(row.amount), txnId: args.txnId, reason: args.reason }); // provenance only
+        db.prepare("UPDATE direct_receive_deposits SET status = 'slashed', updated_at = datetime('now') WHERE id = ?").run(args.depositId);
+        db.prepare(`INSERT INTO direct_receive_privileges (user_id, status, tier, suspended_reason, updated_at)
+      VALUES (?, 'suspended', ?, ?, datetime('now'))
+      ON CONFLICT(user_id) DO UPDATE SET status='suspended', suspended_reason=excluded.suspended_reason, updated_at=datetime('now')`)
+            .run(row.user_id, row.tier, args.reason ?? 'base_bond_slashed');
+    })();
+    return { ok: true, status: 'slashed' };
+}
+// ───── PR-4b-3: 生产 receipt 写入(唯一 writer)─────────────────────────────────────────────────
+/** base-bond/合规 policy 版本 —— 【服务端生成】(非客户端入参),legal clearance 落地时随 policy 更新。 */
+export const DIRECT_PAY_BASE_BOND_POLICY_VERSION = 'pre-legal-unset';
+/** 生产 receipt 允许的法域【严格白名单】。默认空 = 任何 jurisdiction 都拒(额外 fail-closed,待法务配置)。 */
+export const DIRECT_PAY_BOND_JURISDICTIONS = [];
+/**
+ * 生产保证金 receipt【唯一】writer(PR-4b-3 scaffold)。这是【整个协议中】唯一允许写 production_receipt_confirmed_at
+ *   的函数(#100 guard 机器强制:写赋值必在本函数内 且 本函数必调 assertProductionDepositRail)。
+ *
+ * 当前【fail-closed】:Lock A 对 manual(非生产)/usdc/fiat(GATED,implemented=false)抛;operator_attested 过 Lock A,
+ *   但 Lock B(assertBondRailCleared,registry 治理默认关)对所有 rail 抛 → 没有任何 rail 能写 production receipt
+ *   → 调用即抛 → 永不写 production receipt → Direct Pay 仍 non-launchable。assert 之后的写路径在 legal-cleared rail
+ *   落地前【不可达】(本 PR 不接真实 USDC/fiat/PSP/on-chain)。不碰 buyer wallet/escrow/order/settlement/refund。
+ *
+ * 硬约束(即便未来 rail 放行也必须守):
+ *  - 拒绝把【非生产 locked】(manual/test lock,无 production receipt)升级成生产 —— 旧/测试行不得冒充生产到位。
+ *  - jurisdiction 必须 ∈ DIRECT_PAY_BOND_JURISDICTIONS(严格白名单);policy_version 由服务端常量盖章,非入参。
+ *  - assert 在任何写之前;原子 confirm+lock(amount + status=locked + production receipt + provenance 快照 + privilege)。
+ */
+export function confirmProductionReceipt(db, args) {
+    const { depositId, railId, expectedAmountUnits, receiptRef, jurisdiction } = args;
+    // ⚠️ 生产/法务硬闸 —— assert【真正第一】:在任何 row 读取 / 幂等 / 拒绝 / 写之前。当前所有 rail 都被拒 → 抛 → 恒 fail-closed。
+    //   置于最前的语义意义:即便某 deposit 之前在【已 cleared 的 rail】下确认过,若该 rail 后被【撤回】(legalCleared→false),
+    //   重新确认也不再被当"幂等已确认"放过 —— 必须重新通过闸。#100 guard 要求本 helper body 必含此调用。
+    assertProductionDepositRail(getDepositRail(railId));
+    // Lock B(Phase 4 scaffold):rail-clearance registry 放行闸 —— legal_cleared + production_ready + 非占位 policy_version +
+    //   jurisdiction ∈ allowlist。与 Lock A【独立】,缺一即拒;当前 registry 全 fail-closed → 恒抛。置于任何 row 读/写之前。
+    assertBondRailCleared(railId, jurisdiction);
+    // ───── 以下在 legal-cleared 生产 rail 落地前【全部不可达】(两把闸已抛)─────
+    const row = getRow(db, depositId);
+    if (!row)
+        return { ok: false, reason: 'deposit not found' };
+    if (railId !== row.deposit_rail)
+        return { ok: false, reason: 'rail_id does not match the deposit rail' };
+    // 幂等:已生产确认 → already(此时 rail 仍 cleared,assert 已过)
+    if (row.status === 'locked' && row.production_receipt_confirmed_at != null)
+        return { ok: true, status: 'locked', already: true };
+    // 拒绝把【非生产 locked】(manual/test lock,无 production receipt)升级成生产
+    if (row.status === 'locked')
+        return { ok: false, reason: 'deposit is locked WITHOUT a production receipt (manual/test) — cannot be upgraded to production' };
+    if (!receiptRef)
+        return { ok: false, reason: 'missing production receipt ref' };
+    if (!DIRECT_PAY_BOND_JURISDICTIONS.includes(jurisdiction))
+        return { ok: false, reason: `jurisdiction '${jurisdiction}' not in allowlist` };
+    if (!['pending', 'confirmed', 'insufficient'].includes(row.status))
+        return { ok: false, reason: `cannot production-confirm from status '${row.status}'` };
+    if (!isNonNegUnits(expectedAmountUnits) || expectedAmountUnits <= 0)
+        return { ok: false, reason: 'expectedAmount must be a positive integer base-units' };
+    if (expectedAmountUnits < toUnits(row.required_amount))
+        return { ok: false, reason: 'insufficient: amount < required' };
+    db.transaction(() => {
+        db.prepare(`UPDATE direct_receive_deposits SET amount = ?, status = 'locked', confirmed_at = COALESCE(confirmed_at, datetime('now')),
+      locked_at = datetime('now'), production_receipt_confirmed_at = datetime('now'),
+      production_receipt_ref = ?, production_rail_id = ?, production_jurisdiction = ?, production_policy_version = ?,
+      external_ref = COALESCE(?, external_ref), updated_at = datetime('now') WHERE id = ?`)
+            .run(toDecimal(expectedAmountUnits), receiptRef, railId, jurisdiction, DIRECT_PAY_BASE_BOND_POLICY_VERSION, receiptRef, depositId);
+        db.prepare(`INSERT INTO direct_receive_privileges (user_id, status, tier, granted_at, updated_at)
+      VALUES (?, 'active', ?, datetime('now'), datetime('now'))
+      ON CONFLICT(user_id) DO UPDATE SET status='active', tier=excluded.tier, suspended_reason=NULL, granted_at=COALESCE(direct_receive_privileges.granted_at, excluded.granted_at), updated_at=datetime('now')`)
+            .run(row.user_id, row.tier);
+    })();
+    return { ok: true, status: 'locked' };
+}
+/**
+ * 生产门读取:某存款是否【生产级】锁定 = status='locked' 且 production_receipt_confirmed_at 非 NULL。
+ * 4b-min 永远 false(manual rail 不设该列;无生产 rail)。供后续 4c 生产 go-live 事实装配【单一真相】,杜绝 manual 冒充。
+ */
+export function isProductionBaseBondLocked(db, args) {
+    const row = getRow(db, args.depositId);
+    return !!row && row.status === 'locked' && row.production_receipt_confirmed_at != null;
+}
+/**
+ * 卖家级生产门(PR-4c go-live 充分必要的担保侧条件):该卖家是否有任一【生产级】锁定 base bond
+ *   (status='locked' 且 production_receipt_confirmed_at 非 NULL)。**非仅看 direct_receive_privileges.status='active'**。
+ * 4b-min 无生产 base-bond rail(WAZ 未启用 / USDC·fiat 生产收款 GATED)→ 恒 false → 直付建单 fail-closed / non-launchable。
+ * 一个生产级 receipt 只会发给已 KYC + 制裁筛查的商户,故该门也承接了 KYC/sanctions(独立 4a 事实门待其系统就绪再接)。
+ */
+export function sellerHasProductionBaseBondLocked(db, sellerId) {
+    return !!db.prepare("SELECT 1 FROM direct_receive_deposits WHERE user_id = ? AND status = 'locked' AND production_receipt_confirmed_at IS NOT NULL LIMIT 1").get(sellerId);
+}
+/**
+ * refund-on-exit 阻止原因(纯判断占位 —— 真实退款状态流 + RFC-018 clearing lock 集成 = 4b-2)。
+ * 返回阻止原因码;null = 在这些条件下【不被阻止】(但本 PR 不执行任何退款)。无副作用,不读库,不出款。
+ */
+export function refundOnExitBlockedReason(facts) {
+    if (facts.status !== 'locked')
+        return 'NOT_LOCKED';
+    if (facts.hasOpenDispute === true)
+        return 'OPEN_DISPUTE';
+    if (facts.withinCoolingWindow === true)
+        return 'COOLING_WINDOW';
+    return null;
+}

package/dist/direct-receive-payment-instruction.js

@@ -0,0 +1,26 @@
+/** instruction / label 文本上限(纯展示文本,防滥用;非业务语义)。 */
+export const MAX_INSTRUCTION_LEN = 500;
+export const MAX_LABEL_LEN = 40;
+/** 卖家当前 active 收款说明(最新一条)。无则 null → 调用方必须 fail-closed,不创建直付订单。 */
+export function getActivePaymentInstruction(db, sellerId) {
+    const r = db.prepare("SELECT id, instruction, label FROM direct_receive_payment_instructions WHERE seller_id = ? AND status = 'active' ORDER BY updated_at DESC, created_at DESC LIMIT 1").get(sellerId);
+    return r ?? null;
+}
+/**
+ * 设置/替换卖家当前 active 收款说明。原子:同一同步事务内先把该 seller 所有 active 置 inactive,再插入一条新 active。
+ *   保证至多一条 active。instruction/label 调用方需先 trim + 校验非空/长度;此处只信任已校验入参并落库。
+ *   只写 direct_receive_payment_instructions,绝不碰 wallet/escrow/settlement/order。
+ */
+export function setActivePaymentInstruction(db, sellerId, args, generateId) {
+    const id = generateId('dri');
+    db.transaction(() => {
+        db.prepare("UPDATE direct_receive_payment_instructions SET status = 'inactive', updated_at = datetime('now') WHERE seller_id = ? AND status = 'active'").run(sellerId);
+        db.prepare("INSERT INTO direct_receive_payment_instructions (id, seller_id, instruction, label, status) VALUES (?, ?, ?, ?, 'active')").run(id, sellerId, args.instruction, args.label);
+    })();
+    return { id, instruction: args.instruction, label: args.label };
+}
+/** 停用卖家当前所有 active 收款说明。返回是否有行被停用(false = 本来就没有 active)。 */
+export function deactivatePaymentInstruction(db, sellerId) {
+    const info = db.prepare("UPDATE direct_receive_payment_instructions SET status = 'inactive', updated_at = datetime('now') WHERE seller_id = ? AND status = 'active'").run(sellerId);
+    return info.changes > 0;
+}

package/dist/fx-rates.js

@@ -0,0 +1,71 @@
+/**
+ * FX rates (DISPLAY-ONLY) — USDC → buyer-local-currency conversion for price display.
+ *
+ * Scope (Holden decision 2026-07-01): USDC pricing display + real-time local conversion. This is NOT a
+ * settlement path — it NEVER changes the USDC amount owed; it only produces an informational "≈ ¥X" hint.
+ * USDC is treated 1:1 with USD (peg deviation ±0.1% is negligible for a display hint). No DB, no money move.
+ *
+ * Real-time: live rates are fetched from a keyless public FX API and cached briefly; on any failure we serve
+ * the last-known snapshot (marked stale) or a hardcoded fallback table, so the price display NEVER breaks.
+ */
+// users.region (VALID_REGIONS: china/us/eu/india/singapore/global_north/global) → buyer local display currency.
+// Anything unknown / broad-region / null → USD.
+export const REGION_CURRENCY = {
+    china: 'CNY', us: 'USD', eu: 'EUR', india: 'INR', singapore: 'SGD',
+    global_north: 'USD', global: 'USD',
+};
+export const SUPPORTED_CURRENCIES = ['USD', 'CNY', 'EUR', 'INR', 'SGD', 'IDR', 'MYR', 'PHP', 'VND', 'THB'];
+const isSupported = (c) => SUPPORTED_CURRENCIES.includes(c);
+export function regionToCurrency(region) {
+    const c = REGION_CURRENCY[String(region || '').toLowerCase()];
+    return c && isSupported(c) ? c : 'USD';
+}
+// Fallback (per 1 USD) — used ONLY when the live fetch fails AND no prior snapshot exists. Always served
+// with stale:true so the UI can show it as approximate. Kept coarse on purpose (a safety net, not a source).
+export const FALLBACK_USD_RATES = { USD: 1, CNY: 7.2, EUR: 0.92, INR: 83, SGD: 1.35, IDR: 16000, MYR: 4.5, PHP: 58, VND: 25000, THB: 34 };
+const TTL_MS = 15 * 60 * 1000; // 15-min cache: fiat FX barely moves intraday → "real-time" enough for a display hint, no API hammering
+const FX_URL = process.env.FX_RATES_URL || 'https://open.er-api.com/v6/latest/USD';
+let _cache = null;
+/** PURE: external payload → our supported-currency subset. Throws if any supported rate is missing/invalid. */
+export function parseUsdRates(payload) {
+    const p = payload;
+    const r = p?.rates || p?.conversion_rates;
+    if (!r || typeof r !== 'object')
+        throw new Error('fx: no rates in payload');
+    const out = {};
+    for (const c of SUPPORTED_CURRENCIES) {
+        const v = Number(r[c]);
+        if (!Number.isFinite(v) || v <= 0)
+            throw new Error(`fx: bad/absent rate for ${c}`);
+        out[c] = v;
+    }
+    return out;
+}
+/** Cached live USD rates; on failure serve last-known (stale) or the fallback table. fetchImpl/now injectable for tests. */
+export async function getUsdRates(fetchImpl = fetch, now = Date.now()) {
+    if (_cache && now - _cache.fetchedAt < TTL_MS)
+        return _cache.snap;
+    try {
+        const res = await fetchImpl(FX_URL, { signal: AbortSignal.timeout(5000) });
+        if (!res.ok)
+            throw new Error('fx: http ' + res.status);
+        const rates = parseUsdRates(await res.json());
+        const snap = { base: 'USD', rates, as_of: new Date(now).toISOString(), stale: false };
+        _cache = { snap, fetchedAt: now };
+        return snap;
+    }
+    catch {
+        if (_cache)
+            return { ...(_cache.snap), stale: true }; // last-known, flagged stale
+        return { base: 'USD', rates: { ...FALLBACK_USD_RATES }, as_of: new Date(now).toISOString(), stale: true };
+    }
+}
+/** PURE: USDC decimal amount → local-currency decimal (USDC≈USD). Display-only; returns NaN on bad input. */
+export function convertUsdcToLocal(usdcAmount, currency, rates) {
+    const rate = rates?.[currency];
+    if (!Number.isFinite(usdcAmount) || !Number.isFinite(rate) || rate <= 0)
+        return NaN;
+    return usdcAmount * rate;
+}
+/** test-only: reset the module cache so tests are deterministic. */
+export function __resetFxCacheForTest() { _cache = null; }