@ducatjs/money 0.2.1 → 0.3.0

package/README.md

@@ -12,7 +12,7 @@ import { money } from '@ducatjs/money';
 import '@ducatjs/money/allocate'; // opt-in modules add their methods to Money
 import '@ducatjs/money/tax';
 import '@ducatjs/money/convert';
-import '@ducatjs/money/format'; // or import '@ducatjs/money/all' for everything
+import '@ducatjs/money/format'; // or import '@ducatjs/money/all' for everything except the integrations that need optional peers
 
 const price = money('19.99', 'EUR'); // Money<'EUR'>
 const total = price.add(money('5.01', 'EUR')); // → 25.00 EUR
@@ -25,9 +25,23 @@ total.format('de-DE'); // → '25,00 €'
 price.add(money('1', 'USD')); // compile error, and throws if types are erased
 ```
 
-Operations are methods on `Money`. For pipelines or code that prefers plain functions, `@ducatjs/money/fn` has each of them as a function of the same name (`add(price, fee)`, `allocate(m, [1, 1, 1])`). The core (`@ducatjs/money`) holds construction, arithmetic, rounding, comparison and serialisation; everything else is an opt-in module, so a bundle only pays for what it imports (see [Modules](#modules)).
+Operations are methods on `Money`. For pipelines or code that prefers plain functions, `@ducatjs/money/fn` has each of them as a function of the same name (`add(price, fee)`, `allocate(m, [1, 1, 1])`), and a bundle keeps only the functions it imports: a program that only creates, adds and prints amounts is about 1.3 KiB gzipped through `/fn`. Importing `@ducatjs/money` installs the methods and registers every ISO 4217 currency; `/fn` does neither, so a `/fn` program imports the currencies it uses (`import '@ducatjs/money/iso/EUR'`, or `@ducatjs/money/iso` for all of them) and carries only those. The core (`@ducatjs/money`) holds construction, arithmetic, rounding, comparison and serialisation; everything else is an opt-in module, so a bundle only pays for what it imports (see [Modules](#modules)).
 
-Status: 0.x. The API is meant to stay small, but until 1.0 a minor version may change it; the [changelog](CHANGELOG.md) lists every breaking change. See [What's missing](#whats-missing-honest-list).
+Status: 0.x. The API is meant to stay small, but until 1.0 a minor version may change it; the [changelog](https://github.com/public/ducat/blob/main/CHANGELOG.md) lists every breaking change. See [What's missing](#whats-missing-honest-list).
+
+## Why ducat
+
+Choosing a money library for JavaScript today means choosing which problem to live with.
+
+- **Wrong, to varying degrees.** On the same 41 correctness vectors, no other money library passes more than 34, and most return some wrong answers without an error: multiplying through floats turns 0.50 × 1.15 into 0.57, splitting −100.00 three ways loses a cent, amounts past 2⁵³ minor units drift, and a decimal string from another locale can parse as 100 times the amount. Their issue trackers are full of these bugs, some open for years.
+- **Slow.** The libraries that get the arithmetic right pay for it in speed: dinero.js 2, the most careful of them, is 1.6× to 27× slower than ducat on the operations ducat leads.
+- **Missing features.** Most stop at add, multiply, allocate and format. Exact currency conversion, rounding modes beyond half up, cash rounding, the amounts payment processors expect and database storage are left to you, and that hand-written code is where the bugs come back.
+
+ducat is built to fix all three:
+
+- **Exact, and tested to stay exact.** Amounts are integers of minor units: a JS number while safe, a bigint beyond, so nothing is ever a float. Every operation that can round takes one of nine rounding modes (or `'unnecessary'`, which throws), the rounding kernel is generated from Lean proofs, and allocation is checked against a proved model. It passes all 41 vectors, and the bug classes found in the issue trackers and fix histories of dinero.js, currency.js, js-money, decimal.js, big.js and bignumber.js each have a regression test in ducat's suite.
+- **Fast.** Safe amounts stay on a plain-number fast path, so ducat is the fastest money library measured on creating, parsing, add, multiply, allocate and toDecimal on Node, Bun and Deno ([How it compares](#how-it-compares) has the numbers, and the cases where it isn't fastest).
+- **Complete, but you only pay for what you use.** Conversion with exact rates and their sources, rounding policies, cash rounding, processor amounts (Stripe, Adyen, Checkout.com, PayPal, Braintree, Klarna), tax, a fixed-point `Fixed`, Intl formatting and strict parsing, and Prisma, Drizzle, Kysely and Postgres helpers are all opt-in modules. The core is 5.5 KiB gzipped.
 
 ---
 
@@ -35,11 +49,11 @@ Status: 0.x. The API is meant to stay small, but until 1.0 a minor version may c
 
 The same 41 correctness vectors, the same benchmark and the same bundle snippet for every library. The details, the
 other libraries' bugs, the fixed-point libraries and the money libraries in other languages are in
-[docs/COMPARISON.md](docs/COMPARISON.md), regenerated from [compare/](compare) for each release.
+[docs/COMPARISON.md](https://github.com/public/ducat/blob/main/docs/COMPARISON.md), regenerated from [compare/](https://github.com/public/ducat/tree/main/compare) for each release.
 
 | library                            | correct (of 41) | wrong, silently |        bundle (gzip) |
 | ---------------------------------- | --------------: | --------------: | -------------------: |
-| **ducat**                          |          **41** |           **0** |              4.0 KiB |
+| **ducat**                          |          **41** |           **0** |              4.5 KiB |
 | dinero.js 2 (bigint calculator)    |              34 |               0 |              1.8 KiB |
 | monetra                            |              34 |               3 |              4.5 KiB |
 | ts-money / js-money                |              31 |           7 / 6 |       30.7 / 8.8 KiB |
@@ -51,23 +65,25 @@ other libraries' bugs, the fixed-point libraries and the money libraries in othe
 - **Correct everywhere:** ducat is the only library that passes every vector, including amounts beyond 2⁵³ minor
   units, float traps and negative allocations.
 - **Fastest on arithmetic:** with its methods API, it is the fastest money library on creating, parsing a decimal string
-  (`money('12.34', 'EUR')`), add, multiply, allocate and toDecimal on Node, Bun and Deno, and on compare on Node and Deno. Against the fastest other money library
-  the margin ranges from about 1.05× (compare on Node: 7.31 against 7.65 ns) to about 9.5× (allocate on Node: 46
-  against bigint-money's 437 ns). Against dinero.js 2, on the operations where ducat is fastest, it ranges from 1.4× (creating on
-  Deno) to about 28× (multiply on Bun).
-- **Where it isn't fastest:** formatting on Bun and Deno, where currency.js (formatting a float) is 3% faster (on Node,
-  ducat and currency.js are level, 380 against 381 ns, and so are ducat and dinero.js 1 on Bun). On Bun, libraries that
-  compare plain numbers are faster at compare (currency.js 6.4 against 9.8 ns).
-- **Fixed-point decimals:** ducat's `Fixed` is the fastest fixed-point library on parsing a decimal string (`fixed('12.34')`)
-  and multiply on every runtime,
-  and ahead of every other library on compare everywhere and on add on Node and Deno. bigdecimal.js is faster at
-  dividing a `Fixed` on every runtime, though `Money` divides faster than either, and at add on Bun (11.9 against 12.3
-  ns). js-big-decimal and ethers are faster on `toString` everywhere; see
-  [docs/COMPARISON.md](docs/COMPARISON.md#fixed-point-decimal-libraries).
+  (`money('12.34', 'EUR')`), add, multiply, allocate and toDecimal on Node, Bun and Deno, and on compare on Node and
+  Deno. Against the fastest other money library the margin ranges from about 1.06× (compare on Node and Deno: 7.05
+  against currency.js's 7.46 ns on Node) to about 9.0× (allocate on Node: 47 against bigint-money's 419 ns). Against
+  dinero.js 2, on the operations where ducat is fastest, it ranges from 1.6× (creating on Node) to about 27× (compare
+  on Node), measured on Node and Bun: dinero.js 2's Deno cells vary several-fold between machines (see
+  [the run's notes](https://github.com/public/ducat/blob/main/compare/results/genoa-2026-11-09-v030-final/README.md)).
+- **Where it isn't fastest:** formatting on Deno, where currency.js (formatting a float) is 6% faster (on Node and Bun
+  they are level, and ducat and dinero.js 1 are level everywhere). On Bun, libraries that compare plain numbers are
+  faster at compare (currency.js 6.5, js-money and ts-money 7.7 against 9.9 ns; Bun's compare cells vary a lot between
+  runs).
+- **Fixed-point decimals:** ducat's `Fixed` is the fastest fixed-point library on parsing a decimal string
+  (`fixed('12.34')`), multiply, divide and compare on every runtime, and on add on Node and Deno (on Bun bigdecimal.js
+  is 3% faster, 11.9 against 12.3 ns). It divides by 3 in 28, 28 and 25 ns on Node, Bun and Deno, against
+  bigdecimal.js's 57, 35 and 49. js-big-decimal and ethers are faster on `toString` everywhere; see
+  [docs/COMPARISON.md](https://github.com/public/ducat/blob/main/docs/COMPARISON.md#fixed-point-decimal-libraries).
 - **Not the smallest:** currency.js, bigint-money, dinero.js 2, @screeny05/ts-money, big.js and dinero.js 1 are smaller
   for the same snippet. ducat's core includes exact decimal parsing, bigint support and the ISO table; everything else
   is opt-in.
-- **Measurement:** speed is from one quiet AMD EPYC Genoa vCPU, on ducat 0.2.0 (commit 7c9455a) under Node 24.22.2,
+- **Measurement:** speed is from one quiet AMD EPYC Genoa vCPU, on ducat at commit 01753e5 (the 0.3.0 release candidate) under Node 24.22.2,
   Bun 1.4.4 and Deno 2.9.8; sizes are gzipped KiB. Differences within 2.5% are called level.
 
 ## Design
@@ -82,7 +98,7 @@ A `Money<C>` has three readonly fields:
 | `minor: number \| bigint` | Integer count of 10^-scale units. It is a **number whenever it is a safe integer** (absolute value ≤ 2^53−1) and a **bigint only beyond that**. The invariant is enforced everywhere, so ordinary amounts never allocate a bigint and huge amounts never lose a digit. |
 | `scale: number`           | Decimal places. Defaults to the currency's ISO exponent (EUR 2, JPY 0, KWD 3, CLF 4). It can be larger for sub-minor precision (unit prices, FX intermediates). `round()` brings it back.                                                                              |
 
-Why this representation, based on `bench/designs.ts` (the same seven operations written four ways and run on five engines; full tables in [bench/RESULTS.md](bench/RESULTS.md)):
+Why this representation, based on `bench/designs.ts` (the same seven operations written four ways and run on five engines; full tables in [bench/RESULTS.md](https://github.com/public/ducat/blob/main/bench/RESULTS.md)):
 
 | ns/op, indicative                    | **A: number + bigint fallback** | B: bigint everywhere |     C: decimal string | A + `Object.freeze` |
 | ------------------------------------ | ------------------------------: | -------------------: | --------------------: | ------------------: |
@@ -119,6 +135,8 @@ Engine notes (V8 vs JSC vs SpiderMonkey):
 
 ## API
 
+**From CommonJS.** ducat is an ES module, and Node 24 can `require()` it, so a CommonJS project needs no build step: `const { money } = require('@ducatjs/money')` works, and so does every entry below. TypeScript finds the types with any `moduleResolution`. `nodenext` and `bundler` read `exports`, while `node10` (the default for `module: "commonjs"`) reads `types` and `typesVersions`, which name the same declarations. So no `paths` mapping into `dist/` is needed.
+
 ### Modules
 
 | import                              | adds to `Money`                                                    | also exports                                                     |
@@ -126,6 +144,7 @@ Engine notes (V8 vs JSC vs SpiderMonkey):
 | `@ducatjs/money`                    | the core: arithmetic, rounding, comparison, `toDecimal`, `toJSON`… | `money`, `fromMinor`, `zero`, `sum`, `fromJSON`, ISO exponents   |
 | `@ducatjs/money/allocate`           | `allocate`, `split`, `instalments`, `schedule`, `chunk`            | the same as plain functions                                      |
 | `@ducatjs/money/tax`                | `percentage`, `discount`, `addTax`, `extractTax`                   | the same                                                         |
+| `@ducatjs/money/math`               | `ratioOf`, `divideToIntegral`, `remainder`, `trimScale`            | the same, `average`                                              |
 | `@ducatjs/money/convert`            | `convert`                                                          | `exchangeRate`, providers, `bag`, `comparator`…                  |
 | `@ducatjs/money/exact`              | `exact`                                                            | `ExactMoney`, `sumExact`                                         |
 | `.../convert/ecb`                   | nothing                                                            | `parseEcbXml`, `parseEcbCsv`, `parseEcbSdmxCsv`                  |
@@ -137,8 +156,16 @@ Engine notes (V8 vs JSC vs SpiderMonkey):
 | `.../convert/fetch`                 | nothing                                                            | `fetchEcb`, `fetchEcbRange`, `fetchBankOfCanada` (network I/O)   |
 | `.../stripe-fx`, `adyen-fx`         | nothing                                                            | `stripeRate`, `stripeImpliedRate`, `adyenRate`                   |
 | `@ducatjs/money/policy`             | nothing                                                            | `roundingPolicy`, `isoPolicy`, `assertScale`                     |
+| `@ducatjs/money/pricing`            | nothing                                                            | `priceEnding` (.99, .95, the nearest 5), `tieredPrice` (tiers)   |
 | `@ducatjs/money/cash`               | `cashRound`, `roundToIncrement`                                    | the same, `cashPolicy`, `cashRule`, `currencyDigits`             |
 | `@ducatjs/money/historic`           | nothing                                                            | `defineHistoricCurrencies`, `historicCurrency` (withdrawn codes) |
+| `@ducatjs/money/crypto`             | nothing                                                            | `defineCryptoCurrencies`, `toBaseUnits`, `fromBaseUnits`         |
+| `@ducatjs/money/currencies`         | nothing                                                            | numeric codes, `minorUnit`, `currencyName`, `currencySymbol`     |
+| `@ducatjs/money/territories`        | nothing                                                            | `territoryCurrencies`, `currencyTerritories` (CLDR)              |
+| `@ducatjs/money/wire`               | nothing                                                            | `google.type.Money`, ISO 20022 amounts, minor-unit JSON          |
+| `@ducatjs/money/words`              | nothing                                                            | `amountInWords`, `spellOut` (CLDR rules, no Money loaded)        |
+| `@ducatjs/money/words/<language>`   | nothing                                                            | `english`, `german`, `french`, `spanish`, `italian`…             |
+| `@ducatjs/money/finance`            | nothing                                                            | `yearFraction`, `amortise`, `npv`, `irr`, `discountedSum`…       |
 | `@ducatjs/money/format`             | `format`, `formatToParts`                                          | the same                                                         |
 | `@ducatjs/money/parse`              | nothing                                                            | `parse`, `parseMoney`                                            |
 | `@ducatjs/money/stripe`             | `toStripe`, `toStripeAmount`                                       | the same, `fromStripe`, `stripeExponent`…                        |
@@ -151,7 +178,8 @@ Engine notes (V8 vs JSC vs SpiderMonkey):
 | `.../drizzle/pg`, `mysql`, `sqlite` | nothing                                                            | `moneyMinor`, `moneyDecimal`, `moneyJson` Drizzle columns        |
 | `@ducatjs/money/kysely`             | nothing                                                            | `moneyHelpers`, `setMoney`, `MoneyResultPlugin`                  |
 | `@ducatjs/money/pg`                 | nothing                                                            | `exactTypes`, `moneyTypeSql`, `toNumeric`, composite I/O         |
-| `@ducatjs/money/fixed`              | `toFixedPoint`                                                     | `Fixed`, `fixed`, `fromScaled`, `isFixed`, `moneyToFixed`        |
+| `@ducatjs/money/fixed`              | nothing                                                            | `Fixed`, `fixed`, `fromScaled`, `isFixed` (without Money)        |
+| `@ducatjs/money/fixed/money`        | `toFixedPoint`, and `Fixed#toMoney`                                | `/fixed`, plus `moneyToFixed`, `fixedToMoney`                    |
 | `@ducatjs/money/zod`                | nothing                                                            | `moneySchema`, `moneyJSONSchema` (Zod, an optional peer)         |
 | `@ducatjs/money/valibot`            | nothing                                                            | `moneySchema`, `moneyJSONSchema` (Valibot, an optional peer)     |
 | `@ducatjs/money/testing`            | nothing                                                            | matchers, value equality, snapshot serializer                    |
@@ -159,8 +187,10 @@ Engine notes (V8 vs JSC vs SpiderMonkey):
 | `.../testing/arbitraries`           | nothing                                                            | `arbMoney`, `arbCurrency` (fast-check)                           |
 | `@ducatjs/money/all`                | the methods of every module above                                  | everything except the database, schema and testing entries       |
 | `@ducatjs/money/fn`                 | nothing                                                            | every operation as a plain function, core and modules            |
+| `@ducatjs/money/iso`                | nothing (registers every ISO 4217 currency, for `/fn`)             | nothing                                                          |
+| `@ducatjs/money/iso/EUR`, ...       | nothing (registers that one currency, for `/fn`)                   | nothing                                                          |
 
-Importing a module (`import '@ducatjs/money/allocate'`, or any named import from it) installs its methods on `Money.prototype`, and its `declare module` augmentation makes them type-check. Without the import, `m.allocate()` is a compile error. The trade-off: the methods are installed for the whole program, so one import anywhere makes them available everywhere at run time, while TypeScript only knows about them in a program that includes the import. Import a module in each file that uses its methods: the import is cheap and installing twice is harmless, and it keeps working where files run in isolation (test runners, workers), where a single import in the entry point would leave `m.allocate` undefined at run time even though the code type-checks. Code that must not change any prototype (a library built on ducat, for example) can use the plain functions from `@ducatjs/money/fn` instead.
+Importing a module (`import '@ducatjs/money/allocate'`, or any named import from it) installs its methods on `Money.prototype`, and its `declare module` augmentation makes them type-check. Without the import, `m.allocate()` is a compile error. The trade-off: the methods are installed for the whole program, so one import anywhere makes them available everywhere at run time, while TypeScript only knows about them in a program that includes the import. Import a module in each file that uses its methods: the import is cheap and installing twice is harmless, and it keeps working where files run in isolation (test runners, workers), where a single import in the entry point would leave `m.allocate` undefined at run time even though the code type-checks. Code that must not change any prototype (a library built on ducat, for example) can use the plain functions from `@ducatjs/money/fn` instead, and imports the currencies it uses (`import '@ducatjs/money/iso'`), since `/fn` registers none. The core methods (`add`, `round`, `toDecimal`...) work the same way: the root entry `@ducatjs/money` installs them, so a program that imports only `/fn` has Money values without methods and keeps only the functions it calls. Currencies work the same way. Every entry except `/fn` registers the whole ISO 4217 table (`/fixed`, `/words` and `/territories` never build Money and don't need it); a program that imports only `/fn` registers what it uses with `import '@ducatjs/money/iso/EUR'` (one module per ISO code) or `import '@ducatjs/money/iso'` (all of them), and any other code throws "Unknown currency", naming the import. Registration is by import, so it's the same bundled and unbundled. It's per module, not per program: a module that imports only `/fn` and builds Money while it loads (`const FEE = money('0.30', 'EUR')` in a config file) runs before the modules that import it, so it throws even when the app's entry point imports `@ducatjs/money`; give such a module, and any library built on `/fn`, its own `import '@ducatjs/money/iso'` (or `/iso/EUR`). The per-code modules are named by the uppercase ISO code: `/iso/eur` may resolve on a case-insensitive file system and then fail elsewhere. The types don't track registration: `/fn` accepts any ISO code at compile time. `defineCurrency` checks the ISO table so ISO codes can't be redefined, so a `/fn` program that calls it carries the table again: about 0.6 kB gzipped with `defineCurrency` itself.
 
 Your own module can add methods the same way:
 
@@ -207,6 +237,28 @@ const other = fromJSON({ amount: '1', currency: 'USD' as string });
 assertCurrency(other, 'EUR'); // throws CurrencyMismatchError
 ```
 
+**Decimal strings.** `money()`, `fixed()`, `ratio()` and every other place that takes an amount or a factor as a string accept exactly this, and nothing else:
+
+- an optional sign, `+` or `-`;
+- one or more ASCII digits;
+- optionally a point followed by one or more digits;
+- optionally an exponent: `e` or `E`, an optional sign, and digits.
+
+The exponent is at most 1000 either way, and so is the number of decimal places once it is applied. `'.5'`, `'5.'`, `'-.5'`, grouping (`'1,000'`, `'1_000'`), other scripts' digits and surrounding whitespace are refused with a `SyntaxError`, because each is more often a truncated or mangled value than a deliberate one. Exponents are accepted because they're unambiguous and other systems write them: `String(1e-7)`, Java's `BigDecimal.toString()` and Python's `str(Decimal)` all do. For text as people write it, with grouping, symbols or another locale's separators, use `parse()` (below). A factor can also be written `'a/b'`, two of these strings around a slash.
+
+```ts
+import { money } from '@ducatjs/money';
+
+money('-12.34', 'EUR'); // → -12.34 EUR
+money('+7', 'EUR'); // → 7.00 EUR
+money('1.5e3', 'EUR'); // → 1500.00 EUR
+money('125E-2', 'EUR'); // → 1.25 EUR
+money('.5', 'EUR'); // throws SyntaxError
+money('5.', 'EUR'); // throws SyntaxError
+money(' 12.34', 'EUR'); // throws SyntaxError
+money('1,000', 'EUR'); // throws SyntaxError
+```
+
 **Arithmetic.** All of these are immutable and return new values.
 
 - `add`, `subtract`, `sum(list, currency?)`, `negate`, `abs`
@@ -224,6 +276,19 @@ const toFiveRappen = (value: Money<'CHF'>) => value.divide(5).round('halfExpand'
 money('10.00', 'CHF').multiply('1.077').with(toFiveRappen); // → 10.75 CHF
 ```
 
+**Averages, shares and remainders** (`@ducatjs/money/math`). `average(list, rounding?)` divides the exact sum by the count and rounds once. `ratioOf(part, total)` is the exact share as a `Ratio`, which `multiply` and `allocate` accept. `divideToIntegral(m, divisor)` counts how many whole times one amount fits into another (truncated toward zero), and `remainder(m, divisor)` is what is left, with `m`'s sign, so `m = divisor × count + remainder` exactly. `trimScale(m, minimumScale?)` drops trailing zeros down to the currency's exponent (or `minimumScale`).
+
+```ts
+import { money } from '@ducatjs/money';
+import { average } from '@ducatjs/money/math';
+
+average([money('10', 'EUR'), money('10', 'EUR'), money('10.01', 'EUR')]); // → 10.00 EUR
+money('25', 'EUR').ratioOf(money('100', 'EUR')); // → { num: 1n, den: 4n, n: 1, d: 4 }
+money('9.99', 'EUR').divideToIntegral(money('2.50', 'EUR')); // → 3
+money('9.99', 'EUR').remainder(money('2.50', 'EUR')); // → 2.49 EUR
+money('1.2300', 'EUR', { scale: 4 }).trimScale(); // → 1.23 EUR
+```
+
 **Compare**
 
 - `compare` (returns −1, 0 or 1), `equals`, `lessThan`, `lessThanOrEqual`, `greaterThan`, `greaterThanOrEqual`
@@ -265,6 +330,20 @@ one.identical(money('1', 'EUR', { scale: 1 })); // → false
 | `Floor`                | `'floor'`       | always toward −∞                                   |
 | `Unnecessary`          | `'unnecessary'` | throws `RoundingError` if rounding would be needed |
 
+**Price endings** (`@ducatjs/money/pricing`). `priceEnding({ ending, step?, rounding? })` builds a rule that moves a computed price to a retail ending: the allowed prices are `ending + k × step` (step 1 by default), and `rounding` picks one: `'ceil'` (the default) the next one up, `'floor'` the next one down, `'halfCeil'` the nearest. The rule is a function, so `price.with(rule)` and `prices.map(rule)` work, and the result is exact, at the price's scale.
+
+```ts
+import { money } from '@ducatjs/money';
+import { priceEnding } from '@ducatjs/money/pricing';
+
+const charm = priceEnding({ ending: '0.99' });
+money('23.41', 'EUR').with(charm); // → 23.99 EUR
+money('23.41', 'EUR').with(priceEnding({ ending: '9.90', step: 10 })); // → 29.90 EUR
+money('22.50', 'EUR').with(priceEnding({ ending: 0, step: 5, rounding: 'halfCeil' })); // → 25.00 EUR
+money('1234', 'JPY').with(priceEnding({ ending: 80, step: 100 })); // → 1280 JPY
+money('100', 'JPY').with(charm); // throws RangeError: JPY has no cents
+```
+
 **Rounding policies** (`@ducatjs/money/policy`). A policy bundles a scale, an increment and a mode ("CHF cash", "4 decimals, half even") into one value that goes wherever a rounding mode goes: `multiply`, `divide`, `round`, `percentage`, `discount`, `addTax`, `extractTax`. The result is rounded once, straight to the policy, so it never rounds twice through the amount's own scale. A policy is also a function that rounds an amount, so `amounts.map(policy)` and `m.with(policy)` work.
 
 - `roundingPolicy({ scale?, increment?, rounding?, currency? })`. The scale defaults to the currency's exponent, the increment (counted in 10^-scale units) to 1, and the mode to `'halfExpand'`. With `currency`, the policy refuses amounts in other currencies.
@@ -287,6 +366,19 @@ money('10.00', 'EUR').divide(3, unitPrice); // → 3.3333 EUR
 assertScale(money('1.234', 'EUR', { scale: 3 }), isoPolicy); // throws RangeError
 ```
 
+**Tens, hundreds and thousands.** A scale is never negative: it counts decimal places, from 0 to 1000, so `round('floor', -2)` throws. To round to whole hundreds (Swiss tax rounds taxable income down to 100 CHF, for example), use an increment: a policy at scale 0 with `increment: 100`, or `roundToIncrement` from `@ducatjs/money/cash`. The same increment does tens, thousands and cash rounding.
+
+```ts
+import { money } from '@ducatjs/money';
+import { roundingPolicy } from '@ducatjs/money/policy';
+import { roundToIncrement } from '@ducatjs/money/cash';
+
+const downToHundreds = roundingPolicy({ scale: 0, increment: 100, rounding: 'floor' });
+money('12345.60', 'CHF').round(downToHundreds); // → 12300 CHF
+roundToIncrement(money('12345.60', 'CHF'), money('100', 'CHF'), 'floor'); // → 12300.00 CHF
+money('12345.60', 'CHF').round('floor', -2); // throws RangeError
+```
+
 **Cash rounding**
 
 - `cashRound(m, { country?, rounding?, includeUnverified? })` uses the table in `data/cash-rounding.json`:
@@ -333,7 +425,17 @@ parseMoney('12.34', 'en', { hint: 'EUR', lenient: true }); // → 12.34 EUR
 **Serialise**
 
 - `toDecimal(m)` gives `"12.34"` for NUMERIC/DECIMAL and wire formats.
-- `toMinor(m)` gives a bigint for BIGINT columns. `toMinorNumber(m)` gives a number and throws if it isn't safe.
+- `toMinor(m)` gives the currency's minor units (cents for EUR) as a bigint, whatever the value's scale, and throws a `RoundingError` if that would need rounding. `toMinorNumber(m)` gives a number and also throws if it isn't safe. `toScaledUnits(m)` gives units of the value's own scale, to store next to that scale.
+
+```ts
+import { money } from '@ducatjs/money';
+
+money('12.340', 'EUR', { scale: 3 }).toMinor(); // → 1234n
+money('1.5', 'EUR', { scale: 1 }).toMinor(); // → 150n
+money('12.345', 'EUR', { scale: 3 }).toMinor(); // throws RoundingError: round() first
+money('12.345', 'EUR', { scale: 3 }).toScaledUnits(); // → 12345n (pair it with scale 3)
+```
+
 - `majorPart(m)` and `minorPart(m)` split the amount at the decimal point, truncating toward zero, and both keep its sign: `money('-12.34', 'EUR').majorPart()` is `-12` and `.minorPart()` is `-34`. Each is a number while it is a safe integer and a bigint beyond, like `minor`.
 - `JSON.stringify(m)` gives `{"amount":"12.34","currency":"EUR"}`, and `fromJSON` reverses it. The amount is a string so it survives JSON parsers that turn numbers into floats.
 
@@ -364,7 +466,7 @@ v.parse(moneySchema({ currency: 'JPY' }), { amount: '1000', currency: 'JPY' });
 
 **Currencies**
 
-- `currencyExponent(code)`, `isCurrency(code)`, `ISO_EXPONENTS`, `ISO_4217_PUBLISHED`
+- `currencyExponent(code)`, `isCurrency(code)`, `ISO_EXPONENTS`, `ISO_4217_PUBLISHED`. `isCurrency` and `currencyExponent` see the registered codes: every ISO code wherever an entry other than `/fn` is imported, and in a `/fn`-only program the ones imported from `@ducatjs/money/iso` (see [Modules](#modules)).
 - `defineCurrency('BTC', 8)` adds a non-ISO code. To also get it in the `CurrencyCode` type, augment `interface CustomCurrencies`.
 - Withdrawn codes (`@ducatjs/money/historic`): 54 codes ISO 4217 has withdrawn (HRK, BGN, ANG, STD, SLL, ZWL, CUC, VEF, the euro's predecessors…) and the offshore yuan CNH, each with the exponent ISO gave it while it was current, so old records and processor listings load. Nothing is registered until you call `defineHistoricCurrencies`, with a list of codes or none for all of them. `historicCurrency(code)` gives the name, exponent, ISO numeric code and the month ISO withdrew it, from ISO 4217 List Three. Older codes whose minor units aren't sourced are left out; register those with `defineCurrency`.
 
@@ -389,6 +491,128 @@ declare module '@ducatjs/money' {
 }
 ```
 
+**Crypto currencies and tokens** (`@ducatjs/money/crypto`). BTC (8 decimals, satoshi), ETH (18, wei), SOL (9, lamport) and common Ethereum tokens (USDC, USDT, DAI, WBTC, EURC, PYUSD) as an opt-in table, registered by `defineCryptoCurrencies`, like the historic codes. Each unit's decimals are read from the source that defines it, pinned to a release or commit (Bitcoin Core's `COIN`, Ethereum mainnet in ethereum-lists/chains, the Solana SDK, and the Uniswap default token list for tokens). A token's decimals belong to its contract on one network: these are Ethereum mainnet's (USDT has 18 on BNB Chain, 6 here), so `cryptoUnit(code)` names the network and the contract. Define another network's tokens with `defineCurrency`, under codes of your own. `toBaseUnits(m)` gives the exact count of base units as a bigint, and `fromBaseUnits(count, code)` parses one strictly: digits and an optional minus sign only. Amounts at 18 decimals use Money's bigint path, so they stay exact.
+
+```ts
+import { money } from '@ducatjs/money';
+import { defineCryptoCurrencies, fromBaseUnits, toBaseUnits } from '@ducatjs/money/crypto';
+
+defineCryptoCurrencies(['BTC', 'ETH']);
+toBaseUnits(money('0.00000001', 'BTC')); // → 1n
+fromBaseUnits('1500000000000000000', 'ETH'); // → 1.500000000000000000 ETH
+money('0.1', 'ETH').add(money('0.2', 'ETH')).toDecimal(); // → '0.300000000000000000'
+fromBaseUnits('1e18', 'ETH'); // throws SyntaxError
+```
+
+**Currency metadata** (`@ducatjs/money/currencies`). ISO 4217 numeric codes both ways (`numericCode`, `currencyFromNumeric`), for card networks, ISO 8583 and ISO 20022 messages; `minorUnit(code)`, the size of the minor unit; and names and symbols per locale (`currencyName`, `currencySymbol`). Names and symbols come from the runtime's `Intl`, not a bundled table, so they follow its CLDR version. The smallest coin is `cashUnit(code, { country? })` in `@ducatjs/money/cash`, from the cash rules. Which currencies a territory uses, and since when, is in `@ducatjs/money/territories` (`territoryCurrencies`, `currencyTerritories`, from CLDR). It is a separate entry because the table is most of its 4.5 KiB gzipped.
+
+```ts
+import { cashUnit } from '@ducatjs/money/cash';
+import {
+  currencyFromNumeric,
+  currencySymbol,
+  minorUnit,
+  numericCode,
+} from '@ducatjs/money/currencies';
+import { territoryCurrencies } from '@ducatjs/money/territories';
+
+numericCode('EUR'); // → '978'
+currencyFromNumeric(8); // → 'ALL'
+minorUnit('KWD'); // → '0.001'
+currencySymbol('USD', 'en-CA'); // → 'US$'
+cashUnit('CHF'); // → '0.05'
+territoryCurrencies('DE', { on: '2001-06-01' }).map((use) => use.currency); // → ['EUR', 'DEM']
+```
+
+### Interest, loans, NPV and proration
+
+`@ducatjs/money/finance` has the calculations billing and lending code keeps rewriting in floats, in exact arithmetic: every amount that is paid or booked is rounded once from its exact value, with a rounding mode or a policy. Dates are `'YYYY-MM-DD'` strings or `{ year, month, day }` objects (so a `Temporal.PlainDate` works), never `Date`. The design is in [docs/FINANCE.md](https://github.com/public/ducat/blob/main/docs/FINANCE.md).
+
+- `yearFraction(start, end, convention)` is an exact `Ratio` under `ACT/360`, `ACT/365F`, `ACT/ACT ISDA`, `30/360` (Bond Basis), `30E/360` or `30E/360 ISDA` (pass `maturity: true` or `false` when the end date is the last day of February), as the 2006 ISDA Definitions §4.16 define them. It isn't Excel's YEARFRAC, whose bases differ (US 30/360, an average year length for actual/actual). `interest` is simple interest over a day count, and `compound` is periodic compounding over a whole number of periods.
+- `amortise(loan, options)` builds an annuity, linear or interest-only schedule. Each period's interest is the balance times `rate / perYear`, rounded; the principal parts sum exactly to the loan and the balance ends at zero, because the rounding residual goes to the last payment (or, with `residual: 'lastInterest'`, to the last interest). It takes a `balloon` and a `firstPayment` date.
+- Functions named after Excel's give Excel's values. `npv(rate, flows)` is Excel's NPV: the first flow is at the end of period 1, so, like Excel, an initial outlay at period 0 goes outside, `flows[0] + npv(rate, rest)`. `discountedSum(rate, flows)` takes flows from period 0. Both are exact and rounded once, so `npv` matches Excel to the cent.
+- `irr(flows, { digits })` is Excel's IRR, exact to `digits` places (floored): it bisects in exact integer arithmetic, the IRR lies between `lower` and `upper`, 10^−digits apart, and `rate` is `lower`. Where Excel guesses, it throws: with no sign change (Excel's #NUM!), and with more than one unless a `bracket` (in place of Excel's `guess`) selects one root.
+- `prorate(price, { period, used })` charges the used part of a period (by the day, or with `unit: 'second'` by the second), and `splitPeriod(price, { period, at })` splits a period's price at plan changes into pieces that sum exactly to it.
+
+```ts
+import { money } from '@ducatjs/money';
+import {
+  amortise,
+  interest,
+  irr,
+  npv,
+  discountedSum,
+  prorate,
+  splitPeriod,
+} from '@ducatjs/money/finance';
+
+const period = { from: '2026-01-15', to: '2026-07-15', dayCount: 'ACT/365F' } as const;
+interest(money('10000', 'EUR'), '0.05', period, 'halfEven'); // → 247.95 EUR
+
+const plan = amortise(money('200000', 'EUR'), { rate: '0.045', perYear: 12, periods: 300 });
+plan.payment; // → 1111.66 EUR
+plan.rows[0]?.interest; // → 750.00 EUR
+plan.rows.at(-1)?.balance; // → 0.00 EUR
+plan.totalInterest; // → 133500.69 EUR
+
+const flows = ['-1000', '300', '400', '500'].map((amount) => money(amount, 'EUR'));
+discountedSum('0.08', flows, 'halfEven'); // → 17.63 EUR
+npv('0.08', flows.slice(1), 'halfEven'); // → 1017.63 EUR (Excel's NPV: add the outlay yourself)
+irr(flows, { digits: 8 }); // → { rate: '0.08896339', lower: '0.08896339', upper: '0.08896340' }
+irr(['-100', '230', '-132'].map((amount) => money(amount, 'EUR'))); // throws RangeError: two IRRs, 10% and 20%
+
+const march = { start: '2026-03-01', end: '2026-04-01' };
+prorate(money('30', 'EUR'), { period: march, used: { start: '2026-03-11', end: '2026-04-01' } }); // → 20.32 EUR
+splitPeriod(money('30', 'EUR'), { period: march, at: ['2026-03-11', '2026-03-20'] }); // → [9.68 EUR, 8.71 EUR, 11.61 EUR]
+```
+
+### Tiered and volume pricing
+
+`tieredPrice(quantity, { mode, tiers })` in `@ducatjs/money/pricing` prices a quantity under tiers in the style of Stripe's: each tier has an inclusive `upTo` (`'inf'` on the last), a `unitAmount` (sub-cent amounts are fine) and a `flatAmount`, either or both. In `'graduated'` mode each tier prices the units that fall in it; in `'volume'` mode the tier the whole quantity falls in prices every unit. Quantity 0 falls in the first tier, so its flat amount is billed, as Stripe does. The arithmetic is exact and the total is rounded once (with a mode or a policy). The breakdown has a line per tier with its exact charge and an `amount` rounded from the running total, so the lines always sum to the total.
+
+```ts
+import { money } from '@ducatjs/money';
+import { tieredPrice } from '@ducatjs/money/pricing';
+
+const tiers = [
+  { upTo: 5, unitAmount: money('5', 'USD'), flatAmount: money('10', 'USD') },
+  { upTo: 10, unitAmount: money('4', 'USD'), flatAmount: money('20', 'USD') },
+  { upTo: 'inf', unitAmount: money('3', 'USD'), flatAmount: money('30', 'USD') },
+] as const;
+tieredPrice(12, { mode: 'graduated', tiers }).total; // → 111.00 USD
+tieredPrice(12, { mode: 'graduated', tiers }).lines.map((line) => line.amount); // → [35.00 USD, 40.00 USD, 36.00 USD]
+tieredPrice(12, { mode: 'volume', tiers }).total; // → 66.00 USD
+tieredPrice(0, { mode: 'volume', tiers }).total; // → 10.00 USD (the first tier's flat amount)
+```
+
+Real tier tables need a few more things, and get them as options:
+
+- **Quantities** can be fractional, exactly: a decimal string (`'12.25'` kWh), an `'a/b'` string (`'250/3'`), a `ratio()` or a `Fixed`.
+- **The last tier** may be open with `upTo: 'inf'`, `null` or `Infinity`. Bounds must increase, and the error names the tier that doesn't.
+- **Past a bounded last tier**, the quantity throws by default. With `beyondLastTier: 'cap'` it is charged as if it were the last `upTo`, so nothing more is charged past it.
+- **Tier by one quantity, charge by another** (volume mode): `chargeQuantity` multiplies the chosen tier's `unitAmount`, for tiers chosen by meter count but priced per unit used. The tier's `flatAmount` is charged once. Tiers with only a `flatAmount` give flat-fee pricing, chosen by the quantity. Graduated tiers split the quantity across tiers, so there is no single tier to apply to another quantity, and `chargeQuantity` throws there.
+
+```ts
+import { money } from '@ducatjs/money';
+import { fixed } from '@ducatjs/money/fixed';
+import { tieredPrice } from '@ducatjs/money/pricing';
+
+const capped = [
+  { upTo: 10, unitAmount: money('2', 'EUR') },
+  { upTo: 100, unitAmount: money('1.50', 'EUR'), flatAmount: money('5', 'EUR') },
+];
+tieredPrice(250, { mode: 'graduated', tiers: capped, beyondLastTier: 'cap' }).total; // → 160.00 EUR
+tieredPrice(250, { mode: 'graduated', tiers: capped }); // throws RangeError
+tieredPrice('250/3', { mode: 'volume', tiers: capped }).total; // → 130.00 EUR
+tieredPrice(fixed('12.25'), { mode: 'volume', tiers: capped }).total; // → 23.38 EUR
+
+const perMeter = [
+  { upTo: 1, unitAmount: money('0.30', 'EUR'), flatAmount: money('10', 'EUR') },
+  { upTo: null, unitAmount: money('0.25', 'EUR'), flatAmount: money('25', 'EUR') },
+];
+tieredPrice(3, { mode: 'volume', tiers: perMeter, chargeQuantity: '1234.5' }).total; // → 333.63 EUR
+```
+
 ### Currency conversion
 
 `@ducatjs/money/convert` converts at exact rates and rounds once, at the end. A rate is a `Rate`, an exact rational with the pair in its type, so converting the wrong currency is a compile error. Inverses and chains of rates are exact too: nothing is rounded until an amount is converted.
@@ -464,7 +688,7 @@ nok.rate('NOK', 'JPY')?.quote; // → { rate: '6.50', per: 100, inverted: true }
 nok.missing; // → ['ISK']
 ```
 
-**Where rates come from.** ducat ships parsers for the ECB's euro reference rates (`@ducatjs/money/convert/ecb`): the daily, 90-day and full-history eurofxref XML and CSV files, and the ECB Data Portal's SDMX-CSV (`parseEcbSdmxCsv`), which has any date range back to 1999 in one file. The opt-in fetchers are in `@ducatjs/money/convert/fetch`: `fetchEcb()` for the eurofxref files and `fetchEcbRange({ start, end, currencies })` for the Data Portal, which needs no key and allows browsers (CORS). They use the platform `fetch` and have a 30-second default timeout. Nothing else in ducat touches the network. The ECB publishes once per TARGET working day at about 16:00 CET, for information only, so its rates are typed `'reference'`. The Data Portal strips trailing zeros (`147.2` for 147.20), so the parser rebuilds the published digits from each series' `DECIMALS` attribute. The Bank of Canada's daily rates come from its Valet API (`parseBankOfCanadaJson` in `@ducatjs/money/convert/boc`, and `fetchBankOfCanada()`, also keyless and CORS-enabled). The Bank quotes CAD per unit of each currency, so the tables hold exact inverses with the published quote kept, and its rates carry `availableAt` 16:30 Toronto time, when it says it publishes them. It quotes four decimals (up to six for small rates), so a small rate has only about four significant digits: JPY `0.008760`, KRW `0.000929`, and IDR `0.000082` with two. The inverse of such a rate is exact, but no more precise than the quote, so for those currencies prefer a source that quotes them the other way round. The Federal Reserve's H.10 rates (noon buying rates in New York, certified for US customs, daily since 1971) have a parser only, `parseFedH10Csv` in `@ducatjs/money/convert/fed`, for the CSV from the Board's Data Download Program (release H10, series in columns, with labels). H.10 quotes currency per USD except AUD, EUR, NZD and GBP, which it quotes as USD per unit; those four are stored as exact inverses with the published quote kept, so every table is USD → currency. Holidays are rows of `ND` and are left out. The Board is retiring the Data Download Program in favour of FRED, whose terms (an API key, no storing or caching, no commercial use without consent) rule out a fetcher in ducat, so download the CSV yourself. For sterling there are two parsers. HMRC's monthly exchange rates (`parseHmrcMonthlyCsv` in `@ducatjs/money/convert/hmrc`) are the UK's rates for customs and VAT, under the Open Government Licence. Each month's table is valid for that month (`asOf` the 1st, `validUntil` the last day) and is available from the end of the Wednesday HMRC publishes it, the day before the penultimate Thursday of the month before (the `publication_date` the trade tariff service's API gives every monthly file). The Bank of England's daily spot rates (`parseBankOfEnglandCsv` in `@ducatjs/money/convert/boe`) come from CSV downloaded from its database. The Bank's legal page excludes "selected exchange rate data and series" from its Open Government Licence as third-party data, and its spot rates may come from LSEG, whose content can't be redistributed without consent. So ducat ships no Bank of England data and no fetcher, and **you must check the licence of every Bank of England series you load** before you use or republish it. For what a payment actually settled at, read the processor's own rate: `stripeRate` and `stripeImpliedRate` from a Stripe balance transaction, and `adyenRate` from an Adyen settlement details row. Any other source is a small loader that returns a `rateTable`.
+**Where rates come from.** ducat ships parsers for the ECB's euro reference rates (`@ducatjs/money/convert/ecb`): the daily, 90-day and full-history eurofxref XML and CSV files, and the ECB Data Portal's SDMX-CSV (`parseEcbSdmxCsv`), which has any date range back to 1999 in one file. The opt-in fetchers are in `@ducatjs/money/convert/fetch`: `fetchEcb()` for the eurofxref files and `fetchEcbRange({ start, end, currencies })` for the Data Portal, which needs no key and allows browsers (CORS). They use the platform `fetch` and have a 30-second default timeout. Nothing else in ducat touches the network. The ECB publishes once per TARGET working day at about 16:00 CET, for information only, so its rates are typed `'reference'`. Its files give no publication time, so the parsers set no `availableAt` unless asked: pass `availableAt: true` (to the parsers, `fetchEcb` or `fetchEcbRange`) for the documented 16:00 CET, which is Frankfurt time (15:00 UTC in winter, 14:00 in summer), or a function of the day for your own, and a historical lookup at 10:00 that day then gets the day before's rate. The Data Portal strips trailing zeros (`147.2` for 147.20), so the parser rebuilds the published digits from each series' `DECIMALS` attribute. The Bank of Canada's daily rates come from its Valet API (`parseBankOfCanadaJson` in `@ducatjs/money/convert/boc`, and `fetchBankOfCanada()`, also keyless and CORS-enabled). The Bank quotes CAD per unit of each currency, so the tables hold exact inverses with the published quote kept, and its rates carry `availableAt` 16:30 Toronto time, when it says it publishes them. It quotes four decimals (up to six for small rates), so a small rate has only about four significant digits: JPY `0.008760`, KRW `0.000929`, and IDR `0.000082` with two. The inverse of such a rate is exact, but no more precise than the quote, so for those currencies prefer a source that quotes them the other way round. The Federal Reserve's H.10 rates (noon buying rates in New York, certified for US customs, daily since 1971) have a parser only, `parseFedH10Csv` in `@ducatjs/money/convert/fed`, for the CSV from the Board's Data Download Program (release H10, series in columns, with labels). H.10 quotes currency per USD except AUD, EUR, NZD and GBP, which it quotes as USD per unit; those four are stored as exact inverses with the published quote kept, so every table is USD → currency. Holidays are rows of `ND` and are left out. The Board is retiring the Data Download Program in favour of FRED, whose terms (an API key, no storing or caching, no commercial use without consent) rule out a fetcher in ducat, so download the CSV yourself. For sterling there are two parsers. HMRC's monthly exchange rates (`parseHmrcMonthlyCsv` in `@ducatjs/money/convert/hmrc`) are the UK's rates for customs and VAT, under the Open Government Licence. Each month's table is valid for that month (`asOf` the 1st, `validUntil` the last day) and is available from the end of the Wednesday HMRC publishes it, the day before the penultimate Thursday of the month before (the `publication_date` the trade tariff service's API gives every monthly file). The Bank of England's daily spot rates (`parseBankOfEnglandCsv` in `@ducatjs/money/convert/boe`) come from CSV downloaded from its database. The Bank's legal page excludes "selected exchange rate data and series" from its Open Government Licence as third-party data, and its spot rates may come from LSEG, whose content can't be redistributed without consent. So ducat ships no Bank of England data and no fetcher, and **you must check the licence of every Bank of England series you load** before you use or republish it. For what a payment actually settled at, read the processor's own rate: `stripeRate` and `stripeImpliedRate` from a Stripe balance transaction, and `adyenRate` from an Adyen settlement details row. Any other source is a small loader that returns a `rateTable`.
 
 <!-- doctest: setup import { readFileSync } from 'node:fs'; const sdmxCsv = readFileSync('test/fixtures/ecb-sdmx/exr-d-full.csv', 'utf8'); -->
 
@@ -537,13 +761,37 @@ fixed('1.5').add('0.25'); // → 1.75: mixed scales align to the larger one
 fixed('2.5').round('halfEven'); // → 2: round() defaults to scale 0
 fromScaled(12345, 3).toString(); // → '12.345'
 JSON.stringify({ unitPrice }); // → '{"unitPrice":"0.0425"}'
+fixed('12.3400').trimScale(); // → 12.34: the smallest exact scale (at least the argument, default 0)
+fixed('0.1').toNumber(); // → 0.1: the nearest double, for display and charts only
 ```
 
+`Number(fixed)` and `+fixed` throw, so a float never slips in unnoticed. `toNumber()` is the named way to accept one, where a chart or a UI library wants a number.
+
 Input is strict in the same way as `money()`. A string keeps its own scale. A number is read at its shortest decimal form, and only when that has at most 15 significant digits, which a double always holds faithfully. So `fixed(0.1 + 0.2)` throws instead of becoming 0.30000000000000004: pass the decimal as a string, or give `{ scale, rounding }`. With a `scale`, input that has more decimals throws unless `rounding` is also given.
 
+**A Fixed is a factor** wherever Money takes one: `multiply`, `divide`, the tax and percentage functions, `ExactMoney`, conversion and rates. It is read exactly, as its scaled integer over 10^scale, so a rate kept as a Fixed needs no conversion. `toRatio()` gives the reduced `Ratio`, to keep for reuse.
+
+```ts
+import { money } from '@ducatjs/money';
+import { fixed } from '@ducatjs/money/fixed';
+
+const vat = fixed('0.0725');
+money('199.99', 'EUR').multiply(vat, 'halfEven'); // → 14.50 EUR
+vat.toRatio(); // → { num: 29n, den: 400n, n: 29, d: 400 }
+```
+
 Arithmetic follows Money's rules. `add`, `subtract` and `compare` align to the larger scale exactly. `multiply` and `divide` take exact factors (integers, decimal strings, bigints, `ratio()` or another `Fixed`) and round once, with `'halfExpand'` by default. The result keeps this value's scale unless you pass another: `fixed('9.990').divide('1.2', 'halfEven', { scale: 2 })` is 8.32. Pass the scale instead of calling `toScale` afterwards, which would round twice. `toScale` and `round` take any of the ten rounding modes, including `'unnecessary'`, which throws if digits would be lost.
 
-To convert, `money.toFixedPoint()` gives the exact amount at the money's scale, and `fixedValue.toMoney('EUR')` makes Money at the currency's exponent. That conversion throws RoundingError when it would drop digits, unless a rounding mode is passed: `fixed('1.005').toMoney('EUR', 'halfEven')` is 1.00 EUR.
+`@ducatjs/money/fixed` doesn't load Money or the currency table, so a program that uses only `Fixed` doesn't carry them. `toMoney()` needs `import '@ducatjs/money/fixed/money'`: that entry has everything in `/fixed`, and adds `money.toFixedPoint()`, the exact amount at the money's scale, and `fixedValue.toMoney('EUR')`, Money at the currency's exponent. That conversion throws RoundingError when it would drop digits, unless a rounding mode is passed.
+
+```ts
+import { money } from '@ducatjs/money';
+import { fixed } from '@ducatjs/money/fixed/money';
+
+money('12.34', 'EUR').toFixedPoint(); // → 12.34
+fixed('1.005').toMoney('EUR', 'halfEven'); // → 1.00 EUR
+fixed('1.005').toMoney('EUR'); // throws RoundingError
+```
 
 ### Payment processors: the amount you send
 
@@ -586,6 +834,54 @@ When the processor needs less precision than the value has, the conversion throw
 
 Signs follow each processor's docs and are checked after rounding. Checkout.com (a card verification) and PayPal (breakdown fields) take zero, Braintree doesn't ("Amount must be greater than zero"), and none of the three takes negative amounts: refunds are sent as positive amounts. Klarna takes both, because its order lines document negative amounts for discounts ("Negative when type is discount").
 
+### Wire formats
+
+`@ducatjs/money/wire` converts Money to and from formats other systems send, exactly both ways. Every reader checks the format strictly, and every writer throws rather than send a value the format can't hold.
+
+- `toGoogleMoney(m)` and `fromGoogleMoney(value)`: `google.type.Money` in its proto3 JSON form (`currencyCode`, `units` as an int64 string, `nanos` with the same sign), as Google APIs and many gRPC services use. More than 9 decimals, or units beyond int64, don't fit.
+- `toIso20022Amount(m)` and `fromIso20022Amount({ Ccy, value })`: the amount in `<InstdAmt Ccy="EUR">12.34</InstdAmt>`. It is written with the currency's decimals, as the payment networks' rules (CBPR+, HVPS+) require, whatever the Money's scale. The schema allows at most 5 decimals and 18 digits, and no negative amounts (the direction goes in the credit/debit indicator).
+- `toMinorUnits(m)` and `fromMinorUnits({ value, currency })`: an integer count of ISO 4217 minor units, the JSON several processors and ledgers use. Where a processor's exponents differ from ISO, use its own view (`toAdyen`, `toCheckout`, ...).
+
+The readers return Money at the currency's exponent, and throw a RoundingError for extra decimals unless `{ scale }` or `{ rounding }` says what to do.
+
+```ts
+import { money } from '@ducatjs/money';
+import {
+  fromGoogleMoney,
+  toGoogleMoney,
+  toIso20022Amount,
+  toMinorUnits,
+} from '@ducatjs/money/wire';
+
+toGoogleMoney(money('-1.75', 'EUR')); // → { currencyCode: 'EUR', units: '-1', nanos: -750000000 }
+fromGoogleMoney({ currencyCode: 'USD', units: '12', nanos: 340000000 }); // → 12.34 USD
+toIso20022Amount(money('12.34', 'EUR')); // → { Ccy: 'EUR', value: '12.34' }
+toIso20022Amount(money('-5', 'EUR')); // throws RangeError: use the credit/debit indicator
+toMinorUnits(money('500', 'JPY')); // → { value: 500, currency: 'JPY' }
+```
+
+### Amounts in words
+
+`@ducatjs/money/words` writes amounts in words, as cheques, invoices and legal documents need. `Intl` can't spell numbers out, so the words come from CLDR's rule-based number formats (RBNF), the rules ICU uses, through a small interpreter that matches ICU on every test vector. Each language is its own entry, so a bundle carries only the ones it imports: `@ducatjs/money/words/en`, `/de`, `/fr`, `/es`, `/it`, `/pt` and `/nl`, from 0.6 to 1.8 KiB each. The currency's name, in the right plural and word order, comes from the runtime's `Intl`, and so do the word for "and" and the digit grouping of numbers the rules write as digits (from 10^18 in most rule sets). A currency code `Intl` can't name (not three letters) throws a `RangeError`.
+
+- `amountInWords(m, language, options?)` writes the whole units, then the minor part as cheques do ("and 45/100"). CLDR has no names for minor units, so pass them to spell the minor part out: `{ minor: { one: 'cent', other: 'cents' } }`.
+- `gender` picks the number's agreement where the language has genders (Spanish "veintiún euros", "veintiuna libras"); CLDR doesn't record a currency's gender, so it's the caller's. `ruleSet` picks any of the language's rule sets.
+- `spellOut(n, language, ruleSet?)` spells a whole number: cardinals, ordinals (`'%spellout-ordinal'`) and the other public sets CLDR has, listed by `ruleSets(language)`. Where it can't give ICU's words it throws a `RangeError` instead: outside ±(2^63 − 1), the range of ICU's rules; for a private (`%%`) rule set; and for the few English ordinals from 10^18 whose suffix ICU takes from the number cut to 32 bits.
+
+```ts
+import { money } from '@ducatjs/money';
+import { amountInWords, spellOut } from '@ducatjs/money/words';
+import { english } from '@ducatjs/money/words/en';
+import { french } from '@ducatjs/money/words/fr';
+
+amountInWords(money('123.45', 'EUR'), english); // → 'one hundred twenty-three euros and 45/100'
+amountInWords(money('21', 'EUR'), french); // → 'vingt-et-un euros et 00/100'
+amountInWords(money('1.01', 'USD'), english, { minor: { one: 'cent', other: 'cents' } }); // → 'one US dollar and one cent'
+spellOut(21, english, '%spellout-ordinal'); // → 'twenty-first'
+```
+
+German, Italian and Dutch words keep CLDR's soft hyphens (U+00AD), which show only where a line breaks. The grammar is CLDR's numbers plus Intl's currency name, so a preposition some languages put after a round million ("un million de yens") isn't added.
+
 ### Databases
 
 | storage                              | Postgres                                                      | MySQL             | SQLite                                                                          | helpers                                                                                |
@@ -594,10 +890,11 @@ Signs follow each processor's docs and are checked after rounding. Checkout.com
 | **decimal**                          | `NUMERIC(19,4)` for most cases; `NUMERIC(38,8)` for crypto/FX | `DECIMAL(19,4)`   | **avoid** (NUMERIC affinity may store REAL); use TEXT + `toDecimal` if you must | `toDecimalValue(m, Prisma.Decimal)`, `fromDecimal(d, 'EUR')`, `decimalMoneyField(...)` |
 | **JSON**                             | `jsonb` `{amount: "12.34", currency}`                         | `JSON`            | `TEXT`                                                                          | `JSON.stringify(m)`, `fromJSON`                                                        |
 
+- **Writing a BIGINT minor-units column:** `toMinorColumns(m, 'amountMinor', 'currency')` (or `m.toMinor()` for the amount alone), and `fromMinor(row.amountMinor, row.currency)` to read it back. Both use the currency's ISO exponent; a value with digits below the minor unit throws, so `round()` it first. With a scale column, write `m.toScaledUnits()` and `m.scale`, as below.
 - BIGINT holds ±9.2·10^18 minor units, which is 92 quadrillion EUR. Postgres's `money` type is locale-dependent; don't use it.
 - Choose a NUMERIC scale of at least the largest exponent you store: 4 covers CLF/UYW, and 3 covers BHD/KWD.
 - Prisma maps `BigInt` to JS `bigint`. The helpers accept it, and `fromMinor` normalises it back to a number when it is safe.
-- **A scale column** makes minor units self-describing: `amount_scale SMALLINT NOT NULL` next to `amount_minor` and `currency`. Write with `toMinorColumns(m, 'amountMinor', 'currency', { scale: 'amountScale' })` and read with `minorMoneyField('amountMinor', 'currency', { scale: 'amountScale' })`. Any scale then round-trips, sub-minor amounts included, which `toMinorColumns` alone refuses. Stored rows also keep their meaning if a currency's exponent changes (see below). To add the column to existing rows, backfill each currency's current exponent in the migration; a missing (NULL) scale throws on read.
+- **A scale column** (the Prisma helpers) makes minor units self-describing: `amount_scale SMALLINT NOT NULL` next to `amount_minor` and `currency`. Write with `toMinorColumns(m, 'amountMinor', 'currency', { scale: 'amountScale' })` and read with `minorMoneyField('amountMinor', 'currency', { scale: 'amountScale' })`. Any scale then round-trips, sub-minor amounts included, which `toMinorColumns` alone refuses. Stored rows also keep their meaning if a currency's exponent changes (see below). To add the column to existing rows, backfill each currency's current exponent in the migration; a missing (NULL) scale throws on read.
 - **Exponent changes.** Minor units stored without a scale are read at the currency's exponent in the installed version of ducat, so a changed exponent would silently change what old rows mean: 1234 stored as 12.34 would read as 1.234 or 123.4. So an exponent change is a breaking change (see [Decisions](#decisions)), listed under **Changed** in the changelog with the currencies affected. Before upgrading across one, migrate the affected rows, or store a scale column (or a decimal) so the question never arises. Custom currencies keep the exponent given to `defineCurrency`.
 - `fromDecimal` rejects values with more decimals than the currency allows (e.g. `12.3456` in NUMERIC(19,4) for EUR) unless you pass `{ scale }` or `{ rounding }`. Trailing zeros are fine.
 
@@ -755,17 +1052,19 @@ The columns check what the types can't: writing another currency, a value at a s
 
 ## Currency data: source, generation, verification
 
-| file                        | source                                                                                                                                                                                                        |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `data/iso4217-list-one.xml` | ISO 4217 List One from SIX (the maintenance agency), published **2026-09-17**. It has 178 codes with minor units, plus N.A. codes such as XAU and XDR, which are excluded as non-monetary.                    |
-| `data/stripe.json`          | https://docs.stripe.com/currencies, retrieved 2026-11-07, with verbatim quotes for every special case                                                                                                         |
-| `data/adyen.json`           | https://docs.adyen.com/development-resources/currency-codes, retrieved 2026-11-07                                                                                                                             |
-| `data/checkout.json`        | https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value, the currency-codes page and the API reference, retrieved 2026-11-07, with verbatim quotes                                     |
-| `data/paypal.json`          | https://developer.paypal.com/api/rest/reference/currency-codes/, the other currency-codes page and the Orders v2 schema, retrieved 2026-11-07, with verbatim quotes                                           |
-| `data/braintree.json`       | https://developer.paypal.com/braintree/docs/reference/general/currencies, the transaction.sale reference, the validation-error list and the GraphQL `Amount` type, retrieved 2026-11-07, with verbatim quotes |
-| `data/klarna.json`          | https://docs.klarna.com/acquirer/klarna/get-started/integration-resilience/data-types/, the purchase-countries page and the Payments API reference, retrieved 2026-11-07, with verbatim quotes                |
-| `data/cash-rounding.json`   | Central-bank, statute and government pages per rule. Each entry has a `source` URL and a `verified` flag.                                                                                                     |
-| `data/cldr-cash.json`       | CLDR release 49 `supplementalData.xml` cash digits and rounding, the second source for the cash rules (`scripts/fetch-cldr-cash.mjs` refreshes it)                                                            |
+| file                         | source                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `data/iso4217-list-one.xml`  | ISO 4217 List One from SIX (the maintenance agency), published **2026-09-17**. It has 178 codes with minor units, plus N.A. codes such as XAU and XDR, which are excluded as non-monetary. The numeric codes in `@ducatjs/money/currencies` come from it too.                                                                                                                  |
+| `data/stripe.json`           | https://docs.stripe.com/currencies, retrieved 2026-11-07, with verbatim quotes for every special case                                                                                                                                                                                                                                                                          |
+| `data/adyen.json`            | https://docs.adyen.com/development-resources/currency-codes, retrieved 2026-11-07                                                                                                                                                                                                                                                                                              |
+| `data/checkout.json`         | https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value, the currency-codes page and the API reference, retrieved 2026-11-07, with verbatim quotes                                                                                                                                                                                                      |
+| `data/paypal.json`           | https://developer.paypal.com/api/rest/reference/currency-codes/, the other currency-codes page and the Orders v2 schema, retrieved 2026-11-07, with verbatim quotes                                                                                                                                                                                                            |
+| `data/braintree.json`        | https://developer.paypal.com/braintree/docs/reference/general/currencies, the transaction.sale reference, the validation-error list and the GraphQL `Amount` type, retrieved 2026-11-07, with verbatim quotes                                                                                                                                                                  |
+| `data/klarna.json`           | https://docs.klarna.com/acquirer/klarna/get-started/integration-resilience/data-types/, the purchase-countries page and the Payments API reference, retrieved 2026-11-07, with verbatim quotes                                                                                                                                                                                 |
+| `data/cash-rounding.json`    | Central-bank, statute and government pages per rule. Each entry has a `source` URL and a `verified` flag.                                                                                                                                                                                                                                                                      |
+| `data/cldr-cash.json`        | CLDR release 49 `supplementalData.xml` cash digits and rounding, the second source for the cash rules (`scripts/fetch-cldr-cash.mjs` refreshes it)                                                                                                                                                                                                                             |
+| `data/cldr-territories.json` | CLDR release 49 `supplementalData.xml` currencies per territory, with their first and last days (`scripts/fetch-cldr-territories.mjs` refreshes it)                                                                                                                                                                                                                            |
+| `data/rbnf/<language>.txt`   | CLDR release 49 spell-out rules (RBNF) from the cldr-rbnf package (`scripts/fetch-cldr-rbnf.mjs` refreshes them). `test/vectors/rbnf.json` holds ICU 4C 79.1's output for them, the oracle the interpreter is tested against, and `test/vectors/rbnf-data.json` ICU 4C 74.2's engine run on this text for the other rule sets (`scripts/gen-rbnf-vectors.mjs`, `--from-data`). |
 
 - `pnpm gen` (`scripts/gen-currencies.mjs`) turns these into `src/generated/*.ts`.
 - `pnpm gen:check` fails if the generated files are stale. It also runs inside the test suite.
@@ -974,20 +1273,23 @@ Vitest and fast-check are optional peer dependencies, used only by these entries
 ## Benchmarks
 
 - Clean-machine numbers against the other money and fixed-point libraries are in [How it compares](#how-it-compares) and
-  [docs/COMPARISON.md](docs/COMPARISON.md), generated from [compare/](compare) on one quiet AMD EPYC Genoa vCPU under
+  [docs/COMPARISON.md](https://github.com/public/ducat/blob/main/docs/COMPARISON.md), generated from [compare/](https://github.com/public/ducat/tree/main/compare) on one quiet AMD EPYC Genoa vCPU under
   Node, Bun and Deno.
 - CodSpeed measures every pull request by instruction count, so speed regressions show up even on noisy CI machines.
 - The benchmarks in `bench/` are for quick local comparisons; on a shared machine their run-to-run variation is often
   ±20–30%.
 - Bundle size (esbuild, minified + gzip; `pnpm size` checks every entry point and snippet against `scripts/size-budgets.json`):
-  - `money('1.00', 'EUR').add(…).multiply('1.075', 'halfEven').toDecimal()`: **4.0 KiB**, of which about 0.55 KiB is the ISO table
-  - the core entry point: 4.9 KiB; everything (`@ducatjs/money/all`): 27.6 KiB
+  - `money('1.00', 'EUR').add(…).multiply('1.075', 'halfEven').toDecimal()`: **4.5 KiB**, of which about 0.55 KiB is the ISO table. 0.3 grew it from 4.0 KiB, and the core from 4.9: stricter input validation and clearer errors (the port-test fixes), and the root entry installing the methods and currencies so that `/fn` programs can leave them out
+  - the core entry point: 5.5 KiB; everything (`@ducatjs/money/all`): 50.5 KiB
+  - `Fixed` alone (`fixed('1.00')`, add, multiply, toString): 3.5 KiB
   - the same snippet with dinero.js (EUR only): 1.8 KiB
+  - the same snippet through `/fn`, with `import '@ducatjs/money/iso/EUR'`: 3.0 KiB; create, add and print only: 1.3 KiB
 
 ---
 
 ## Decisions
 
+- **Amounts in words come from CLDR's RBNF rules, not hand-written grammars.** `Intl` has no spell-out, and ECMA-402 doesn't expose ICU's RuleBasedNumberFormat. CLDR's rules are small (about 1 KiB gzipped per language), carry every language's agreement and compounding rules, and are the same text ICU runs, so an interpreter can be tested against ICU itself. Each language is its own entry so bundles pay only for what they use. Minor-unit names (cent, centime) and a currency's grammatical gender are in no standard data, so the default is the cheque form ("and 45/100") and both are options the caller supplies.
 - **JSON is a decimal string plus the currency, never minor units**: `{"amount":"12.34","currency":"EUR"}`. Minor units only mean something to a reader who knows the exponent, and the exponent isn't fixed:
   - Processors disagree with ISO. Stripe sends ISK and UGX as two-decimal; Adyen has its own exceptions.
   - ISO exponents change over time.
@@ -999,7 +1301,7 @@ Vitest and fast-check are optional peer dependencies, used only by these entries
 
 - **The package is `@ducatjs/money`** (the brand and repo stay ducat). npm's name-similarity rule blocks the unscoped `ducat`, and the npm org `ducat` was taken, so it lives under the `ducatjs` org; one package, with opt-in subpath modules. The ducat was the Venetian gold trade coin, used across Europe for about 600 years.
 - **Methods on `Money`**, because free functions alone are awkward to use: `price.add(fee).multiply('1.075').split(3)`. The same operations as plain functions are in `@ducatjs/money/fn`, not in the root entry, so there is one way to write each in ordinary code. Operands are `Money` only, never bare numbers (monetra's `add(5)` means 5 minor units, a trap we avoid).
-- **The core is small; everything else is an opt-in module that installs methods.** Methods on one class pull every feature into every bundle, so `Money` carries only the core, and `@ducatjs/money/allocate`, `/tax`, `/format`… add their methods when imported (types through `declare module` augmentation, as dayjs plugins do). The cost is that installed methods are global at run time. `@ducatjs/money/fn` offers the same functions without touching the prototype, for function-level tree-shaking.
+- **The core is small; everything else is an opt-in module that installs methods.** Methods on one class pull every feature into every bundle, so `Money` carries only the core, and `@ducatjs/money/allocate`, `/tax`, `/format`… add their methods when imported (types through `declare module` augmentation, as dayjs plugins do). The cost is that installed methods are global at run time. `@ducatjs/money/fn` offers the same functions without touching the prototype, for function-level tree-shaking: even the core methods are installed by the root entry rather than written into the class, so `/fn` programs carry only what they call.
 - **Correctness and features come before bundle size.** The core keeps the currency table, the comparison methods, bigint support and exact string parsing; everything else is an opt-in module, and size budgets in CI stop either from growing.
 - **Default rounding is `'halfExpand'`** (ties away from zero) for arithmetic, the most common default. It is the default of decimal.js, Prisma.Decimal, big.js, bignumber.js and `Intl.NumberFormat`, and what currency.js, js-money and ts-money intend with `Math.round` (which differs for negative ties). The minority defaults: half-even (dinero.js 1, bigint-money), throw (monetra), truncate (dinero.js 2 `transformScale`). Parsing (`money('1.005','EUR')`, `fromDecimal`) and processor amounts (`toStripeAmount`, `toAdyen`) still throw unless a mode is passed, as ts-money and monetra do for input. The default is exported as `DEFAULT_ROUNDING`.
 - **Rounding policies are explicit values.** A policy (scale, increment and mode) is passed to each operation that rounds, the way a rounding mode is. It is never attached to an amount or installed as a global default: a stored or global policy would make the same expression round differently depending on where a value came from or what ran earlier, which is the kind of action at a distance a money library should rule out.
@@ -1030,6 +1332,6 @@ Vitest and fast-check are optional peer dependencies, used only by these entries
   - Memory and GC pressure, which were reasoned about but not measured.
   - dinero.js's bigint calculator.
 - **No Money arrays or columnar ops** (e.g. summing a `Float64Array`/`BigInt64Array` of minor units).
-- **The ISO table is always bundled** (about 0.55 KiB gzipped, 1 KiB minified). Per-currency imports like dinero's would make the minimum bundle smaller.
-- **Minor-unit columns can't round-trip values with a non-ISO scale.** `toMinorColumns` refuses them by design. There is no `scale` column helper.
+- **The root entry always bundles the ISO table** (about 0.55 KiB gzipped, 1 KiB minified). A program written with `/fn` imports only the currencies it uses (`@ducatjs/money/iso/EUR`), like dinero.js's per-currency objects.
+- **Only the Prisma helpers have a scale column.** Without one, minor-unit columns can't round-trip values at a scale other than the currency's, so `toMinorColumns`, the Kysely `setMoney` and the Drizzle `moneyMinor` columns refuse them by design. With Prisma, `{ scale: 'amountScale' }` stores the scale alongside (see [Databases](#databases)). Elsewhere, store `m.toScaledUnits()` and `m.scale` yourself, or use a decimal, JSON or the node-postgres composite column, which keep the scale.
 - **No docs site yet.**