currency: no exchange-rate / home-currency conversion — dynamic multi-currency amounts cannot be reconciled or aggregated across currencies

[os-zhuang]

Status

Maintainer decision (2026-08-13): scheduled for v18.

Context

Surfaced while scoping a solution for an overseas port/terminal customer (2026-08): billing / reconciliation / invoicing must run in multiple currencies, with consolidated reporting in one home currency.

What the platform has today

• currency field type with currencyConfig — currencyMode: 'dynamic' (per-record currency) or 'fixed', defaultCurrency, precision (packages/spec/src/data/field.zod.ts).
• ISO 4217 fraction-digit consistency validation at publish time (packages/spec/src/data/currency-fraction-digits.ts — JPY 0, KWD 3, CLDR 48.0 snapshot).
• Tenant default currency in Localization settings (packages/services/service-settings/src/manifests/localization.manifest.ts, valueDomain: 'iso_4217_currency').
• Analytics currency labeling resolution chain (ADR-0053): measure currency → field currencyConfig.defaultCurrency → ctx.currency (packages/services/service-analytics/src/analytics-service.ts).

What is missing

• No exchange-rate table / object, no dated-rate history.
• No conversion engine: formula / summary roll-ups and analytics aggregations over a dynamic-currency field combine nominal values as if they were one currency — a sum across USD + EUR rows is numerically meaningless.
• No "record currency + home-currency shadow amount" projection (Salesforce ACM-style) for consolidated reporting.

Grep evidence: exchange rate / fx_rate / currency_conversion have zero implementation hits under packages/. The one prose mention ("Money with exchange rates", content/docs/protocol/objectql/index.mdx) does not match the shipped field.zod.ts behavior and reads as a doc leftover.

Possible scope sketch (for discussion)

1. M1 — sys_exchange_rate platform object (base currency, quote currency, rate, effective date) + settings for the org home currency (already exists in Localization).
2. M2 — CEL stdlib conversion function(s) (e.g. convertCurrency(amount, from, to, date?)) usable in formula fields.
3. M3 — opt-in converted projection for summary roll-ups and analytics measures over dynamic currency fields (aggregate in home currency; keep per-currency breakdown available).
4. Guard rails: refuse (or warn on) cross-currency sum/avg over a dynamic currency field when no conversion is configured — today it fails silently into wrong numbers.

Workaround today

App-level customization: model an exchange-rate object, snapshot the rate onto each billing record via hook, and compute home-currency amounts with formula. Works, but every implementation reinvents it and the naive-aggregation foot-gun above remains for anyone who doesn't.

[hotlong]

Triage: confirming the filer's domain:spec — M1/M2 both start from packages/spec/src/data/field.zod.ts and currency-fraction-digits.ts (new sys_exchange_rate shape, CEL stdlib surface declared there), and the guard-rail item explicitly asks for a schema-level refusal. M3 (service-analytics aggregation) is a downstream consumer, not the anchor.

Hold (2026-08-13): maintainer already scheduled this for v18 (per issue body) — adding pm:on-hold (the label was missing; domain:spec/target:v18 were already set by the filer).

Restart trigger files:

• packages/spec/src/data/field.zod.ts (currencyConfig shape)
• packages/spec/src/data/currency-fraction-digits.ts
• packages/services/service-analytics/src/analytics-service.ts (ADR-0053 currency labeling chain)

---

Generated by Claude Code

[os-zhuang]

Hold-condition completion (triage seat, session session_014qTKTqjme5Fp5BH9iRmy6t, on-hold weak-hit audit): the v18 park is sound and stands, but it had no executable boundary wake — the repo emits no v18 signal today (zero milestones, no v18 refs, spec at 17.0.0, no .changeset/pre.json, releases end at v17), so the only wake was the trigger-file list, which over-fires on incidental churn and never fires on "v18 opened". Adding the boundary leg; the existing trigger-file list stays for re-pricing.

Restart-when: the v18 cycle opens — first true of: .changeset/pre.json exists on origin/main, packages/spec/package.json version matches ^18., a milestone or ref matching v18 exists (git ls-remote origin 'refs/*v18*'), or content/docs/releases/v18.mdx is created — or a maintainer re-schedules the card

---

Generated by Claude Code

[os-sam]

H17 restart-touch notice (spec seat, session_01RadETjNRLALFLhFA3xehZP): this hold declares packages/spec/src/data/field.zod.ts as a trigger file, and PR #11213 (Fixes #10928) touches it. Characterization of the touch: docblock/comment-level only — the uniqueScopeError map's documentation is rewritten for the field/index surface split and the UniqueScopeSchema docblock gains a surface warning; no schema shape, no field-type surface, nothing currency-adjacent moves. Assessed as NOT meeting this hold's restart bar; no opportunistic rider taken. Recorded per the H17 protocol so the intersection is declared rather than discovered.

---

Generated by Claude Code