@ultimat3/money 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -49,7 +49,7 @@ the wide shape and answer with the row type.
   `scaleOf` still answer for a *currency*, which is a different question.
 - **A stated currency is an ASSERTION, never a fallback.** `sum(amounts, currency)` used its
   second argument only when the list was empty and ignored it entirely once a first addend existed:
-  `sum([money(1, 'EUR')], 'USD')` answered `{ minor: 1, currency: 'EUR' }`, so a caller who wrote
+  `sum([fromMinor(1, 'EUR')], 'USD')` answered `{ minor: 1, currency: 'EUR' }`, so a caller who wrote
   down USD received EUR with nothing refused — in the one entry point of a file whose header is
   "Integer arithmetic that refuses to mix currencies". A stated currency the first addend
   contradicts is `X_CURRENCY_MISMATCH`.
@@ -60,13 +60,13 @@ the wide shape and answer with the row type.
 - **Lossy narrowing names its mode at the call.** `rescale(m, 2)` throws rather than drop a
   non-zero digit; `rescale(m, 2, 'half-up')` is the same rule `fromDecimal` applies to excess
   precision. A narrowing that loses nothing needs no mode — nothing is being decided.
-- **`money()` is the only place the canonical form is decided.** It drops a `scale` equal to the
-  currency's exponent — only equal, so a deliberately *coarser* scale (`money(5, 'USD', 0)`, whole
+- **`fromMinor()` is the only place the canonical form is decided.** It drops a `scale` equal to the
+  currency's exponent — only equal, so a deliberately *coarser* scale (`fromMinor(5, 'USD', 0)`, whole
   dollars) is kept exactly as a finer one is. Every constructor, every arithmetic result and every
   allocation part therefore agree on one encoding without any of them repeating the rule.
 - **A widened value that will not fit is a scale error, not a fractional-minor one.** `add`,
   `subtract` and `rescale` convert through `toMinor`, which throws `X_MONEY_SCALE_INVALID` naming
-  the finest scale that fits. Letting `money()` refuse the raw number reported a fractional minor
+  the finest scale that fits. Letting `fromMinor()` refuse the raw number reported a fractional minor
   nobody wrote, with a `fromDecimal` fix line that threw the same error again.
 - Never combine currencies without `convert()` first.
 - Never round without naming a `RoundingMode` in the call or accepting the stated default.
@@ -85,7 +85,7 @@ the wide shape and answer with the row type.
   of a value that names none; a value that names one keeps it, because narrowing $0.000002 to
   EUR's two decimals is the 10,000x reinterpretation `scale` was added to prevent. Same rule as
   `multiply` and `divide`, which already kept theirs.
-- **`money()` normalises `-0` to `0`.** One amount must not have two identities: `JSON.stringify`
+- **`fromMinor()` normalises `-0` to `0`.** One amount must not have two identities: `JSON.stringify`
   writes `-0` as `0` while `Object.is` and any keyed `Map` see something else, so a refund
   rounding to nothing produced a value its own wire format cannot reproduce. `roundToInteger`
   refuses to produce it either — `sign * 0` is the source.
@@ -154,6 +154,14 @@ the wide shape and answer with the row type.
   `currencyCodes()` is what this process accepts, registrations included, and it is the list
   `X_CURRENCY_UNKNOWN`'s fix line names — so it must include them or that fix is the dead end it
   used to be.
+- **`trimZeroFraction` is `trailingZeroDisplay: 'stripIfInteger'`, never `minimumFractionDigits:
+  0`.** Min = max = the amount's scale, always; the min-0 form trimmed EVERY trailing zero and
+  rendered 1250 cents as `$12.5`. `trim` is in the formatter cache key because it no longer changes
+  the digit count.
+- **Every bound a caller names is screened before a built-in sees it.** `fractionDigits` outside
+  0…`MAX_FRACTION_DIGITS` is `X_MONEY_SCALE_INVALID` (`Intl` raised a bare `RangeError`), and
+  `allocate(m, parts)` past `MAX_ALLOCATION_PARTS` is `X_ALLOCATION_INVALID` (`new Array(1e10)`
+  did). Defaults are taken on `=== undefined`, never `??`, so a blanked `null` is refused.
 - Adding a currency to the *shipped* rows: one row in `currency.ts` with its correct exponent, plus
   a format test. An app never needs this — that is what `registerCurrency` is for.
 

package/README.md

@@ -21,14 +21,14 @@ read rather than rounding it. → [Money](https://github.com/developerz-ai/ultim
 ## Use
 
 ```ts
-import { add, allocate, formatMoney, fromDecimal, money } from '@ultimat3/money';
+import { add, allocate, formatMoney, fromDecimal, fromMinor } from '@ultimat3/money';
 
 const price = fromDecimal('12.99', 'EUR');   // { minor: 1299, currency: 'EUR' }
-const total = add(price, money(500, 'EUR')); // 1799
+const total = add(price, fromMinor(500, 'EUR')); // 1799
 formatMoney(total, 'de-DE');                 // "17,99 €"
-formatMoney(money(1200, 'JPY'), 'en-US');    // "¥1,200"  — 0 decimals
-formatMoney(money(1234, 'KWD'), 'en-US');    // "KWD 1.234" — 3 decimals
-add(price, money(500, 'USD'));               // throws X_CURRENCY_MISMATCH
+formatMoney(fromMinor(1200, 'JPY'), 'en-US');    // "¥1,200"  — 0 decimals
+formatMoney(fromMinor(1234, 'KWD'), 'en-US');    // "KWD 1.234" — 3 decimals
+add(price, fromMinor(500, 'USD'));               // throws X_CURRENCY_MISMATCH
 ```
 
 ## Minor units are not always cents
@@ -37,6 +37,11 @@ add(price, money(500, 'USD'));               // throws X_CURRENCY_MISMATCH
 `fromDecimal` scales by it (`'1.234'` KWD → 1234), `toDecimalString` reverses it, and
 `formatMoney` sets the fraction digits from it. Hardcoding `/ 100` is a JPY bug and a KWD bug.
 
+`formatMoney(amount, locale, { trimZeroFraction: true })` drops the fraction of a WHOLE amount and
+nothing else — 1200 USD is `$12`, 1250 USD is `$12.50`, never `$12.5` (`trailingZeroDisplay:
+'stripIfInteger'`, with min = max = the amount's scale). `fractionDigits` is a whole number from 0
+to `MAX_FRACTION_DIGITS` (100, `Intl`'s own ceiling); anything else is `X_MONEY_SCALE_INVALID`.
+
 ## A currency the shipped rows do not carry
 
 `As of 2026-08`, 53 ISO-4217 rows ship. They are a *convention* — one useful subset — so an app
@@ -54,7 +59,7 @@ Once, at boot, before the first amount in that currency is built. The rules, eac
 | Rule | Refusal |
 |---|---|
 | three A–Z letters — `Intl` throws a `RangeError` on anything else | `X_CURRENCY_INVALID` |
-| a whole exponent from 0 to `MAX_MONEY_SCALE` — there is no safe default, and a silent 2 is the corrupted maths this package exists to prevent | `X_CURRENCY_INVALID` |
+| a whole exponent from 0 to `@ultimat3/schema`'s `MAX_MONEY_SCALE` — there is no safe default, and a silent 2 is the corrupted maths this package exists to prevent | `X_CURRENCY_INVALID` |
 | a non-empty name | `X_CURRENCY_INVALID` |
 | one code, one declaration — a second exponent reinterprets every stored amount by a power of ten, and a second name makes `currencyInfo().name` depend on import order. An **identical** re-registration is a no-op, so a module imported twice is not a crash | `X_CURRENCY_REDEFINED` |
 | a shipped ISO row is not the app's to redefine | `X_CURRENCY_REDEFINED` |
@@ -64,22 +69,22 @@ included. That is why one is a value and the other is a call.
 
 ## Sub-cent amounts carry a scale
 
-`money(2, 'USD', 6)` is $0.000002 — `minor` counting 10⁻⁶ instead of the currency's own 10⁻².
+`fromMinor(2, 'USD', 6)` is $0.000002 — `minor` counting 10⁻⁶ instead of the currency's own 10⁻².
 A value that names no scale means the currency's, which is every amount that already exists, so
 nothing about `{ minor, currency }` changes: same shape, same JSON, same columns. Only a scale
-*equal* to the currency's is dropped, so a deliberately coarser one is kept too: `money(5, 'USD', 0)`
+*equal* to the currency's is dropped, so a deliberately coarser one is kept too: `fromMinor(5, 'USD', 0)`
 is $5 counted in whole dollars, and `rescale()` produces such values legitimately.
 
 ```ts
-import { add, fromDecimal, money, moneyScale, rescale } from '@ultimat3/money';
+import { add, fromDecimal, fromMinor, moneyScale, rescale } from '@ultimat3/money';
 
-moneyScale(money(1299, 'EUR'));              // 2 — the currency's own
-moneyScale(money(2, 'USD', 6));              // 6
-rescale(money(80, 'USD'), 8);                // $0.80 as 80,000,000 hundred-millionths
-rescale(money(1_234_567, 'USD', 6), 2);      // throws X_MONEY_NOT_INTEGER — digits would go
-rescale(money(1_234_567, 'USD', 6), 2, 'half-up');  // 123¢, the loss named at the call
+moneyScale(fromMinor(1299, 'EUR'));              // 2 — the currency's own
+moneyScale(fromMinor(2, 'USD', 6));              // 6
+rescale(fromMinor(80, 'USD'), 8);                // $0.80 as 80,000,000 hundred-millionths
+rescale(fromMinor(1_234_567, 'USD', 6), 2);      // throws X_MONEY_NOT_INTEGER — digits would go
+rescale(fromMinor(1_234_567, 'USD', 6), 2, 'half-up');  // 123¢, the loss named at the call
 fromDecimal('0.000002', 'USD', { scale: 6 });
-add(money(1, 'USD'), money(2, 'USD', 6));    // meets at scale 6: 10002, nothing lost
+add(fromMinor(1, 'USD'), fromMinor(2, 'USD', 6));    // meets at scale 6: 10002, nothing lost
 ```
 
 Arithmetic normalises to the *finer* of two scales, never the coarser — adding a sub-cent fee to
@@ -96,10 +101,13 @@ fiction. The alternative was a second money type.
 
 ## Allocation
 
-`allocate(money(100, 'USD'), 3)` → `34, 33, 33`. Largest-remainder split: floor every part,
+`allocate(fromMinor(100, 'USD'), 3)` → `34, 33, 33`. Largest-remainder split: floor every part,
 then hand out the leftover units one at a time, biggest fractional remainder first.
 `round(100 / 3)` either loses a cent or invents one, and an invoice that does that fails
 reconciliation forever. `allocateByRatios` does the same for revenue shares and line splits.
+A part count is a positive integer of at most `MAX_ALLOCATION_PARTS` (1,000,000) — every part is a
+`Money` held at once, so `allocate(m, 1e10)` is `X_ALLOCATION_INVALID`, where it was a bare
+`RangeError` out of `new Array`. More parts than minor units is fine: the surplus parts are zero.
 
 ## Rounding is never implicit
 
@@ -120,7 +128,7 @@ scales by that when it is there. It is how a derived direction stays exact: a ta
 double `1 / 0.92`, whose own decimal spelling rounds a large amount one minor unit low. `rate`
 stays the readable number the audit trail records.
 
-`convert` preserves the amount's own `scale`. `convert(money(2, 'USD', 6), 'EUR', parity)` is
+`convert` preserves the amount's own `scale`. `convert(fromMinor(2, 'USD', 6), 'EUR', parity)` is
 €0.000002, not €0.02 — the target currency's minor unit decides nothing about a value that
 already carries its own precision. `convertWith` on a same-currency pair stamps `at` from an
 injected `Clock` (`{ clock }`, default `systemClock`) or from an explicit `{ at }`, never from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/money",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "Integer minor units with an attached currency: arithmetic, allocation, rounding, Intl formatting",
   "license": "MIT",
   "type": "module",
@@ -28,14 +28,14 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "23.0.0",
-    "@ultimat3/schema": "23.0.0"
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/schema": "25.0.0"
   }
 }

package/src/allocate.ts

@@ -11,19 +11,32 @@
 import { assertSameCurrency } from './arithmetic';
 import { allocationInvalid } from './errors';
 import { factorFraction } from './factor';
-import { formatMoneyDebug, type Money, money } from './money';
+import { formatMoneyDebug, fromMinor, type Money } from './money';
 import { minorAt, moneyScale } from './scale';
 
-/** Split into `parts` equal shares. `allocate(money(100,'USD'), 3)` → 34, 33, 33. */
+/**
+ * The most equal shares one `allocate` call hands back. A bound on memory, not on business: every
+ * part is a `Money` held at once, so `allocate(m, 1e10)` was a bare `RangeError` out of `new
+ * Array` and a count just under that an out-of-memory kill. A split wider than this is paged by
+ * the caller — `allocateByRatios` over each page's share.
+ */
+export const MAX_ALLOCATION_PARTS = 1_000_000;
+
+/** Split into `parts` equal shares. `allocate(fromMinor(100,'USD'), 3)` → 34, 33, 33. */
 export function allocate(amount: Money, parts: number): Money[] {
   if (!Number.isSafeInteger(parts) || parts <= 0) {
     throw allocationInvalid(`part count must be a positive integer, got ${String(parts)}`);
   }
+  if (parts > MAX_ALLOCATION_PARTS) {
+    throw allocationInvalid(
+      `part count ${String(parts)} is over the ${MAX_ALLOCATION_PARTS} shares one call holds in memory`,
+    );
+  }
   return allocateByRatios(amount, new Array<number>(parts).fill(1));
 }
 
 /**
- * Split by weights. `allocateByRatios(money(1000,'USD'), [70, 20, 10])` → 700, 200, 100;
+ * Split by weights. `allocateByRatios(fromMinor(1000,'USD'), [70, 20, 10])` → 700, 200, 100;
  * `[1, 1, 1]` over 100 → 34, 33, 33. Weights need not sum to anything in particular.
  */
 export function allocateByRatios(amount: Money, ratios: readonly number[]): Money[] {
@@ -61,7 +74,7 @@ export function allocateByRatios(amount: Money, ratios: readonly number[]): Mone
     leftover -= 1n;
   }
 
-  return floors.map((minor) => money(sign * Number(minor), amount.currency, amount.scale));
+  return floors.map((minor) => fromMinor(sign * Number(minor), amount.currency, amount.scale));
 }
 
 /**

package/src/arithmetic.ts

@@ -5,7 +5,7 @@
 
 import { allocationInvalid, currencyMismatch, currencyRequired } from './errors';
 import { factorFraction } from './factor';
-import { type Money, money } from './money';
+import { fromMinor, type Money } from './money';
 import { DEFAULT_ROUNDING, type RoundingMode, roundRatio } from './rounding';
 import { commonScale, minorAt, toMinor } from './scale';
 
@@ -22,7 +22,7 @@ export function assertSameCurrency(left: Money, right: Money): string {
 export function add(left: Money, right: Money): Money {
   const currency = assertSameCurrency(left, right);
   const scale = commonScale(left, right);
-  return money(
+  return fromMinor(
     toMinor(minorAt(left, scale) + minorAt(right, scale), scale, currency),
     currency,
     scale,
@@ -32,7 +32,7 @@ export function add(left: Money, right: Money): Money {
 export function subtract(left: Money, right: Money): Money {
   const currency = assertSameCurrency(left, right);
   const scale = commonScale(left, right);
-  return money(
+  return fromMinor(
     toMinor(minorAt(left, scale) - minorAt(right, scale), scale, currency),
     currency,
     scale,
@@ -43,7 +43,7 @@ export function subtract(left: Money, right: Money): Money {
  * Every addend must share one currency; an empty list needs an explicit currency.
  *
  * A stated currency the first addend contradicts is `X_CURRENCY_MISMATCH`, not a silent win for
- * the list: `sum([money(1, 'EUR')], 'USD')` used to answer `{ minor: 1, currency: 'EUR' }`, so a
+ * the list: `sum([fromMinor(1, 'EUR')], 'USD')` used to answer `{ minor: 1, currency: 'EUR' }`, so a
  * caller who wrote down USD received EUR and nothing refused — the exact failure this file's
  * header exists to rule out, in the one entry point that treated its currency as a fallback rather
  * than as an assertion.
@@ -55,7 +55,7 @@ export function sum(amounts: readonly Money[], currency?: string): Money {
   }
   const base = first ?? currency;
   if (base === undefined) throw currencyRequired('sum([])');
-  return amounts.reduce((total, amount) => add(total, amount), money(0, base));
+  return amounts.reduce((total, amount) => add(total, amount), fromMinor(0, base));
 }
 
 /**
@@ -73,7 +73,7 @@ export function multiply(
 ): Money {
   const ratio = factorFraction(factor);
   // Scale-preserving: a fee on a micro-priced amount stays a micro-priced amount.
-  return money(
+  return fromMinor(
     roundRatio(BigInt(amount.minor) * ratio.numerator, ratio.denominator, mode),
     amount.currency,
     amount.scale,
@@ -94,7 +94,7 @@ export function divide(
     throw allocationInvalid('cannot divide money by zero — use allocate() to split a total');
   }
   const ratio = factorFraction(divisor);
-  return money(
+  return fromMinor(
     roundRatio(BigInt(amount.minor) * ratio.denominator, ratio.numerator, mode),
     amount.currency,
     amount.scale,
@@ -102,11 +102,11 @@ export function divide(
 }
 
 export function negate(amount: Money): Money {
-  return money(-amount.minor, amount.currency, amount.scale);
+  return fromMinor(-amount.minor, amount.currency, amount.scale);
 }
 
 export function absolute(amount: Money): Money {
-  return money(Math.abs(amount.minor), amount.currency, amount.scale);
+  return fromMinor(Math.abs(amount.minor), amount.currency, amount.scale);
 }
 
 /**

package/src/convert.ts

@@ -8,7 +8,7 @@ import { type Clock, systemClock } from '@ultimat3/core';
 import { assertCurrency, exponentOf } from './currency';
 import { rateMissing } from './errors';
 import { type Fraction, factorFraction } from './factor';
-import { type Money, money } from './money';
+import { fromMinor, type Money } from './money';
 import { DEFAULT_ROUNDING, type RoundingMode, roundRatio } from './rounding';
 import { moneyScale } from './scale';
 
@@ -46,7 +46,7 @@ export interface ConvertOptions {
 }
 
 /**
- * `convert(money(1000,'USD'), 'EUR', { rate: 0.92, ... })`.
+ * `convert(fromMinor(1000,'USD'), 'EUR', { rate: 0.92, ... })`.
  * Scales across differing minor-unit exponents (USD 2 → JPY 0) instead of assuming both
  * sides have cents, and **preserves the amount's own `scale`**: a micro-priced amount stays
  * micro-priced in the target currency, exactly as `multiply` and `divide` keep theirs.
@@ -85,7 +85,7 @@ export function convert(
   const converted = roundRatio(numerator, denominator, options.rounding ?? DEFAULT_ROUNDING);
 
   return {
-    amount: money(converted, target, resultScale),
+    amount: fromMinor(converted, target, resultScale),
     source: amount,
     rate: rate.rate,
     at: rate.at.toISOString(),

package/src/errors.ts

@@ -84,7 +84,7 @@ export function moneyNotInteger(minor: number, currency: string): MoneyError {
 }
 
 /**
- * Three arrivals reach `money()` with an unusable `minor`, and each needs its own instruction.
+ * Three arrivals reach `fromMinor()` with an unusable `minor`, and each needs its own instruction.
  * One line answered all three — `fromDecimal('<minor>', '<ccy>')` — and it raised THIS code back
  * at the reader for every value past the currency's own digits, which is the anti-pattern
  * `currencyDeclarationInvalid` below already names; for `1e21` it read `fromDecimal('1e+21', …)`,
@@ -104,7 +104,7 @@ function notIntegerFix(minor: number, currency: string): string {
   // Safe to interpolate un-escaped, and only here: `PLAIN_DECIMAL` has just proved the spelling is
   // digits, one dot and one leading `-`, so it closes no literal `renderFixLiteral` would escape.
   const spelling = String(minor);
-  const rounded = `money(Math.round(${spelling}), ${code})`;
+  const rounded = `fromMinor(Math.round(${spelling}), ${code})`;
   if (!PLAIN_DECIMAL.test(spelling)) {
     return `${rounded} — the value counts minor units, and that is the whole one nearest it`;
   }
@@ -165,12 +165,24 @@ export function digitsInvalid(digits: number): MoneyError {
   });
 }
 
+/**
+ * A `formatMoney` digit count `Intl.NumberFormat` cannot be built with. Never echoes the rejected
+ * value into the `fix:` — an instruction that raises the error it is answering is not one.
+ */
+export function fractionDigitsInvalid(digits: number, max: number): MoneyError {
+  return new MoneyError({
+    code: 'X_MONEY_SCALE_INVALID',
+    cause: `fractionDigits must be a whole number between 0 and ${max}, got ${String(digits)}`,
+    fix: "formatMoney(amount, locale, { fractionDigits: 2 }) — or omit fractionDigits and take the amount's own scale",
+  });
+}
+
 /** A scale outside 0…MAX_MONEY_SCALE names no decimal place a `minor` could count in. */
 export function scaleInvalid(scale: number): MoneyError {
   return new MoneyError({
     code: 'X_MONEY_SCALE_INVALID',
     cause: `a money scale must be a whole number of decimal places between 0 and ${MAX_MONEY_SCALE}, got ${String(scale)}`,
-    fix: `use a scale in range — money(minor, currency, 6) for micros, or omit it for the currency's own minor unit`,
+    fix: `use a scale in range — fromMinor(minor, currency, 6) for micros, or omit it for the currency's own minor unit`,
   });
 }
 

package/src/format.ts

@@ -5,6 +5,7 @@
 
 import { assertLocale, cachedFormatter } from '@ultimat3/core';
 import { exponentOf } from './currency';
+import { fractionDigitsInvalid } from './errors';
 import { type Money, toDecimalString } from './money';
 import { moneyScale } from './scale';
 
@@ -16,17 +17,20 @@ export interface FormatMoneyOptions {
    * locale decides the notation: `de-DE` has no parenthesised form in CLDR and keeps `-1.299,00 €`.
    */
   accounting?: boolean;
-  /** Drop `.00` on whole amounts — price lists, never invoices. */
+  /**
+   * Drop `.00` on whole amounts — price lists, never invoices. A fractional amount keeps every
+   * digit: 1250 cents is `$12.50`, never `$12.5`.
+   */
   trimZeroFraction?: boolean;
-  /** Force a digit count; defaults to the value's own scale, which is the currency's unless
-   * the amount names a finer one. */
+  /** Force a digit count, 0…`MAX_FRACTION_DIGITS` (`X_MONEY_SCALE_INVALID` otherwise); defaults
+   * to the value's own scale, which is the currency's unless the amount names a finer one. */
   fractionDigits?: number;
   /** `never` disables grouping separators. */
   grouping?: 'auto' | 'never';
 }
 
 /**
- * `formatMoney(money(129900,'EUR'), 'de-DE')` → `1.299,00 €`.
+ * `formatMoney(fromMinor(129900,'EUR'), 'de-DE')` → `1.299,00 €`.
  *
  * Delegates to `formatMoneyParts` and joins: a UI styling the symbol off the parts and a label
  * rendering the string must not disagree about where the sign goes. Hand-prefixing `-` here put
@@ -98,6 +102,20 @@ export function formatMoneyDecimal(amount: Money, locale: string): string {
  */
 const exactDecimal = (amount: Money): `${number}` => toDecimalString(amount) as `${number}`;
 
+/** `Intl.NumberFormat`'s own ceiling on a fraction digit count. */
+export const MAX_FRACTION_DIGITS = 100;
+
+/**
+ * `Intl` refuses a digit count outside 0…100, a fraction and `NaN` with a bare `RangeError`,
+ * several frames from the call that named it. A digit count IS a scale, so it is refused as one.
+ */
+function assertFractionDigits(digits: number): number {
+  if (!Number.isInteger(digits) || digits < 0 || digits > MAX_FRACTION_DIGITS) {
+    throw fractionDigitsInvalid(digits, MAX_FRACTION_DIGITS);
+  }
+  return digits;
+}
+
 const cache = new Map<string, Intl.NumberFormat>();
 const decimalCache = new Map<string, Intl.NumberFormat>();
 
@@ -123,21 +141,22 @@ function formatterFor(
   options: FormatMoneyOptions,
   exponent: number,
 ): Intl.NumberFormat {
+  // `=== undefined`, never `??`: `??` coalesces on `null` too, so an untyped caller's blanked
+  // option took the default instead of the refusal beside it.
   const digits =
-    options.fractionDigits ?? (options.trimZeroFraction === true ? undefined : exponent);
+    options.fractionDigits === undefined ? exponent : assertFractionDigits(options.fractionDigits);
+  const trim = options.trimZeroFraction === true;
   const sign = options.accounting === true ? 'accounting' : 'standard';
   const tag = assertLocale(locale);
-  // `exponent` is in the key because it stopped being derivable from `currency` the moment it
-  // started coming from the amount's own scale. On the `trimZeroFraction` path `digits` is
-  // `undefined`, so without it every scale of one currency shared a formatter: format 12.99 EUR
-  // first and 12.990001 EUR then rendered as `12,99 €` — the sub-cent bug back, silently, in the
-  // one place a human reads the number.
+  // `trim` is in the key because it no longer changes `digits`: a trimmed and an untrimmed
+  // formatter at one digit count are two formatters, and sharing an entry rendered whichever was
+  // built first.
   const key = [
     tag,
     currency,
     options.display ?? 'symbol',
-    digits ?? 'auto',
-    exponent,
+    digits,
+    trim ? 'trim' : 'keep',
     options.grouping ?? 'auto',
     sign,
   ].join('|');
@@ -150,9 +169,12 @@ function formatterFor(
         currency,
         currencyDisplay: options.display ?? 'symbol',
         currencySign: sign,
-        ...(digits === undefined
-          ? { minimumFractionDigits: 0, maximumFractionDigits: exponent }
-          : { minimumFractionDigits: digits, maximumFractionDigits: digits }),
+        // min = max, always: the digit count is the value's scale and never a range. Trimming is
+        // `stripIfInteger` — drop the fraction of a WHOLE amount — because `minimumFractionDigits:
+        // 0` trimmed every trailing zero and rendered 1250 cents as `$12.5`.
+        minimumFractionDigits: digits,
+        maximumFractionDigits: digits,
+        ...(trim ? { trailingZeroDisplay: 'stripIfInteger' as const } : {}),
         ...(options.grouping === 'never' ? { useGrouping: false } : {}),
       }),
   );

package/src/index.ts

@@ -5,6 +5,7 @@ export {
   allocateByPercentages,
   allocateByRatios,
   assertAllocationSums,
+  MAX_ALLOCATION_PARTS,
 } from './allocate';
 export {
   absolute,
@@ -71,6 +72,7 @@ export {
   formatMoney,
   formatMoneyDecimal,
   formatMoneyParts,
+  MAX_FRACTION_DIGITS,
 } from './format';
 export {
   currencyOf,
@@ -78,9 +80,9 @@ export {
   type FromDecimalOptions,
   formatMoneyDebug,
   fromDecimal,
+  fromMinor,
   isMoney,
   type Money,
-  money,
   toDecimalNumber,
   toDecimalString,
   zero,
@@ -93,4 +95,4 @@ export {
   roundToDigits,
   roundToInteger,
 } from './rounding';
-export { assertScale, commonScale, MAX_MONEY_SCALE, minorAt, moneyScale } from './scale';
+export { assertScale, commonScale, minorAt, moneyScale } from './scale';

package/src/money.ts

@@ -26,11 +26,11 @@ const DECIMAL = /^([+-])?(\d+)(?:\.(\d+))?$/;
  * The only constructor. Validates the currency and rejects fractional minor units.
  *
  * `scale` names how many decimal places `minor` counts when the currency's own are not enough:
- * `money(2, 'USD', 6)` is $0.000002. Omitted — and canonically omitted again when it says nothing
+ * `fromMinor(2, 'USD', 6)` is $0.000002. Omitted — and canonically omitted again when it says nothing
  * the currency does not already say — so a value at the natural scale serializes byte-for-byte as
  * it always has, and there is exactly one encoding of it.
  */
-export function money(minor: number, currency: string, scale?: number): Money {
+export function fromMinor(minor: number, currency: string, scale?: number): Money {
   const code = assertCurrency(currency);
   if (!Number.isSafeInteger(minor)) throw moneyNotInteger(minor, code);
   // `-0` is one amount with two identities: `JSON.stringify` writes `0` while `Object.is` and any
@@ -45,7 +45,7 @@ export function money(minor: number, currency: string, scale?: number): Money {
 }
 
 export function zero(currency: string): Money {
-  return money(0, currency);
+  return fromMinor(0, currency);
 }
 
 export interface FromDecimalOptions {
@@ -97,7 +97,7 @@ export function fromDecimal(
     );
   }
 
-  return money(negative ? -minor : minor, code, options.scale);
+  return fromMinor(negative ? -minor : minor, code, options.scale);
 }
 
 /** `1299 EUR` → `'12.99'`; `1200 JPY` → `'1200'`; `2 USD @ scale 6` → `'0.000002'`. */
@@ -114,7 +114,7 @@ export function toDecimalString(amount: Money): string {
 /**
  * Major units as a float — lossy past 2^53 / 10^scale, so never for arithmetic and no longer for
  * formatting either: `format.ts` hands `Intl` the exact `toDecimalString`, since a float rendered
- * `money(9007199254740991, 'USD', 6)` as `…740992`. Kept as public API for a chart axis or a sort
+ * `fromMinor(9007199254740991, 'USD', 6)` as `…740992`. Kept as public API for a chart axis or a sort
  * key, where an approximation is the point.
  */
 export function toDecimalNumber(amount: Money): number {

package/src/rescale.ts

@@ -5,12 +5,12 @@
  */
 
 import { rescaleNotExact } from './errors';
-import { type Money, money } from './money';
+import { fromMinor, type Money } from './money';
 import { type RoundingMode, roundRatio } from './rounding';
 import { assertScale, minorAt, moneyScale, toMinor } from './scale';
 
 /**
- * `rescale(money(80, 'USD'), 8)` → 80,000,000 hundred-millionths, the granularity a per-token
+ * `rescale(fromMinor(80, 'USD'), 8)` → 80,000,000 hundred-millionths, the granularity a per-token
  * price needs. `rescale(m, 2, 'half-up')` brings it back to cents, having named who pays for the
  * digits that go.
  */
@@ -18,7 +18,11 @@ export function rescale(amount: Money, scale: number, mode?: RoundingMode): Mone
   assertScale(scale);
   const from = moneyScale(amount);
   if (scale >= from) {
-    return money(toMinor(minorAt(amount, scale), scale, amount.currency), amount.currency, scale);
+    return fromMinor(
+      toMinor(minorAt(amount, scale), scale, amount.currency),
+      amount.currency,
+      scale,
+    );
   }
 
   const divisor = 10n ** BigInt(from - scale);
@@ -27,5 +31,5 @@ export function rescale(amount: Money, scale: number, mode?: RoundingMode): Mone
   if (mode === undefined && numerator % divisor !== 0n) {
     throw rescaleNotExact(amount, from, scale);
   }
-  return money(roundRatio(numerator, divisor, mode), amount.currency, scale);
+  return fromMinor(roundRatio(numerator, divisor, mode), amount.currency, scale);
 }

package/src/rounding.ts

@@ -3,7 +3,7 @@
  * whichever one `Math.round` happens to implement is not an answer.
  */
 
-import { invariant } from '@ultimat3/core';
+import { assertCoded } from '@ultimat3/core';
 import { MAX_MONEY_SCALE } from '@ultimat3/schema';
 import { digitsInvalid, notRoundable } from './errors';
 import { factorFraction } from './factor';
@@ -66,7 +66,7 @@ export function roundRatio(
   denominator: bigint,
   mode: RoundingMode = DEFAULT_ROUNDING,
 ): number {
-  invariant(
+  assertCoded(
     denominator !== 0n,
     'X_INVARIANT',
     'cannot round a ratio whose denominator is zero',
@@ -98,7 +98,7 @@ export function roundRatio(
       else rounded = whole % 2n === 0n ? whole : whole + 1n;
       break;
   }
-  // Past 2^53 the `Number` is already approximate, which `money()` refuses as X_MONEY_NOT_INTEGER.
+  // Past 2^53 the `Number` is already approximate, which `fromMinor()` refuses as X_MONEY_NOT_INTEGER.
   return Number(negative ? -rounded : rounded);
 }
 

package/src/scale.ts

@@ -4,13 +4,11 @@
  * which is why nothing that predates this file has to change to keep meaning what it meant.
  */
 
-import { isMoneyScale, MAX_MONEY_SCALE } from '@ultimat3/schema';
+import { isMoneyScale } from '@ultimat3/schema';
 import { exponentOf } from './currency';
 import { scaleInvalid, scaleNotWidening, scaleOverflow } from './errors';
 import type { Money } from './money';
 
-export { MAX_MONEY_SCALE };
-
 /**
  * The decimal exponent this value's `minor` counts in — its own, or the currency's.
  *
@@ -31,7 +29,7 @@ export function assertScale(scale: number): number {
  * `amount.minor` restated at `scale`, exactly, as a bigint.
  *
  * A bigint because widening is what a comparison does first, and a comparison must not throw:
- * `MAX_SAFE_INTEGER` cents restated in micros is past 2^53, which `money()` rightly refuses to
+ * `MAX_SAFE_INTEGER` cents restated in micros is past 2^53, which `fromMinor()` rightly refuses to
  * *store* and which says nothing about whether it is larger than the value beside it.
  *
  * Widening only. Narrowing drops digits, and which digits go is a decision with a mode attached —
@@ -52,7 +50,7 @@ export function commonScale(left: Money, right: Money): number {
 /**
  * A widened bigint back to a storable `minor`, or a scale error naming the finest scale that
  * would fit. The one place that conversion happens, because `Number(widened)` alone reached
- * `money()` as a plain out-of-range amount — reported as a fractional minor nobody wrote, with a
+ * `fromMinor()` as a plain out-of-range amount — reported as a fractional minor nobody wrote, with a
  * `fromDecimal` fix line that throws the same error again.
  */
 export function toMinor(widened: bigint, scale: number, currency: string): number {