value-objects-money-and-units

Value objects: money & units

Store every quantity once, in one canonical form, and convert only when shown or exported. Money is integer minor units plus a currency; physical quantities are whole SI base units; time is UTC. This is what lets a user flip any display preference (currency symbol, unit system, locale) without corrupting one stored row, and lets "sum of parts == whole" be structural, not hoped-for.

This core is pure Dart — no flutter/*, no intl, no dart:io, no plugins. Formatting and digit normalization happen upstream/downstream, not here. These value objects live in lib/core/, the sanctioned pure-foundation layer (see project-structure-and-packages) — never a utils//common//shared/ grab-bag.

Read the reference for the task at hand:

• references/allocate-and-splitting.md — the largest-remainder allocate() primitive, its invariants, the two-rounding-sites trap, edge policies, verified test vectors, and the subtotal→tax→tip split pipeline.
• references/canonical-storage.md — the ISO-4217 exponent rule, the SI unit tables, decimal-based parsing, the cents-accumulator for keypad input, rounding discipline, and the Clock-injected dated-rate / staleness engine.
• references/domain-model.md — value-type modelling: relationships as id links, derive-don't-store, one currency per aggregate, immutable state with value equality.

Run scripts/check-money-violations.sh and scripts/verify-core.sh before a PR.

Non-negotiable rules

1. Money is int minor units + a Currency — NEVER double/num/REAL. Binary floats cannot represent 0.01; drift silently corrupts totals the user can never re-derive. No money API accepts or returns double.
2. Derive minor-units-per-major from the currency's real ISO-4217 exponent — NEVER hardcode * 100, / 100, or "2 decimals". Exponent is 0 for JPY/VND, 2 for USD/EUR, 3 for KWD/BHD/OMR. A hardcoded 100 is a 100× error for a 0-exponent currency and a 10× error for a 3-exponent one. Route through currency.minorPerMajor.
3. Unknown currency code is a typed failure, never a silent default-to-2. The exponent table lists only shipped currencies; Currency.tryParse returns null and the caller emits a Failure.
4. One currency per aggregate; cross-currency arithmetic is forbidden. Adding two Money of different currencies is a category error — throw (programmer error) or convert through the FX layer first. Keep currency a fact of the enclosing aggregate so Money arithmetic never has to guard it.
5. Route EVERY division of money through one allocate(amount, weights) primitive. Shared items, tax proration, tip proration, discounts — all one rounding path, so "parts sum to the whole to the exact minor unit" is proven once and tested once.
6. There are TWO rounding sites, not one: allocate() AND percent→minor-units. Round a percentage to integer minor units once before feeding allocate(). A naive double percent is a classic off-by-a-cent bug that allocate coverage will not catch.
7. Never sum independently-rounded parts to get a total. Always allocate() a known integer total and let the parts absorb the residual.
8. Derive totals; never store them. A denormalized stored total is the classic drift bug. Totals are computed from items + weights on read.
9. Model relationships as stable-id links, not embedded copies. Give every entity an explicit final id (e.g. a UUID). Editing a price then leaves assignments intact and deleting a participant just drops them from link sets.
10. Store canonically, convert at the edge. Physical quantities are whole SI base units (int metres / millilitres / minutes); time is a UTC DateTime. .from<DisplayUnit> factories round into canonical; to<DisplayUnit>() getters return a double used only at the presentation edge.
11. Normalize digits/separators to ASCII BEFORE input reaches this core. Never call int.parse/double.parse/Decimal.parse on raw localized input — it throws on Eastern-Arabic numerals. Fold upstream (see i18n-rtl-l10n).
12. Parse with decimal; round ONCE with an explicit mode at the boundary. Use package:decimal for exact division/parsing, apply an explicit RoundingMode (default half-even/banker's) once at the parse or final-total boundary — never on intermediate sums (accumulates bias).
13. Inject package:clock's Clock; NEVER call DateTime.now(), never roll a bespoke ClockService. Every time-reading class in this pure core takes a Clock constructor arg; Riverpod/feature code injects the same Clock through a clockProvider (see service-boundary-and-native) so the two vocabularies compose. Fixed clocks / fake_async then make time-dependent logic deterministic in tests.
14. The core stays Flutter-free and IO-free. Deps are only decimal and clock. Formatting lives in the presentation layer; storage in the data layer.