@ultimat3/money 1.2.0 → 2.0.0

package/CLAUDE.md

@@ -0,0 +1,118 @@
+# @ultimat3/money — agent notes
+
+**Tier 1.** May import `@ultimat3/core`, `@ultimat3/schema`. No external deps, ever.
+`Money` is the shape the whole framework passes around, and the shape itself is declared once, in
+`packages/schema/src/money-value.ts` — read it there rather than trusting a copy here, which is
+the same reason `type-pins.ts` pins invariants instead of a snapshot. What this package adds is
+the *meaning* of the optional `scale`: the decimal exponent `minor` counts in when it is not the
+currency's own. Absent on every value that predates it, and absent again whenever it would only
+restate the currency, so an amount at the natural scale has exactly one encoding and existing
+JSON is untouched.
+
+**`Money` is an alias, not a declaration.** It is `@ultimat3/schema`'s `MoneyValue` — tier 0, the
+only tier every package may import — and `@ultimat3/entity`'s `MoneyValue` is the same alias. Never
+restate the shape here: it was three structural copies, the entity layer's had a `bigint` `minor`,
+and a row that layer decoded therefore threw inside `JSON.stringify` and failed `t.money`. That is
+also why `minor` is a `number` and stays one — money crosses every wire this framework projects,
+and `JSON.stringify` refuses a bigint. `packages/entity/src/type-pins.ts` fails the build if the
+alias is re-declared, if `minor` widens back to a `bigint`, if any field loses `readonly`, if a
+fourth field appears — or if `scale` ever stops being optional, which is the pin that says the
+shape is still additive and this is still a minor version.
+
+## Boundary
+
+| File | Single responsibility |
+|---|---|
+| `money.ts` | the value type + constructors (`money`, `fromDecimal`, `toDecimalString`) |
+| `currency.ts` | the currency table — the ISO-4217 rows shipped, the rows an app registers, and the minor-unit exponent every natural scale derives from |
+| `scale.ts` | what decimal place a value's `minor` counts (`moneyScale`), which scales are legal (`assertScale`), and the exact bigint widening every comparison starts with (`minorAt`) |
+| `rescale.ts` | moving between scales: widening exact, lossy narrowing only with a named mode |
+| `arithmetic.ts` | add/subtract/multiply/compare, refuses mixed currencies |
+| `allocate.ts` | largest-remainder splits that preserve the total |
+| `factor.ts` | the exact fraction a scaling factor's decimal spelling names. `factorFraction` is internal — never exported; the `Fraction` **type** is public, because `ExchangeRate.ratio` is one |
+| `rounding.ts` | explicit modes, no implicit default, over a float (`roundToInteger`) or a ratio (`roundRatio`) |
+| `format.ts` | `Intl.NumberFormat` only, digits from the exponent |
+| `convert.ts` | explicit rate + `RateProvider`, records provenance |
+
+## Rules
+
+- Never a float in a stored or returned amount. `fromDecimal` takes a **string**.
+- Never `/ 100`, and never `exponentOf(amount.currency)` for a value's own precision — that is
+  `moneyScale(amount)`, which falls back to the currency and is right for both. `exponentOf` and
+  `scaleOf` still answer for a *currency*, which is a different question.
+- **Two scales meet at the finer one, never the coarser.** `add`, `subtract` and `compare`
+  widen through `minorAt` (bigint, exact) before they do anything else, so a sub-cent fee added to
+  a cent survives and a comparison answers where storing the widened value would rightly be
+  refused. Rounding down to the coarser scale would silently delete the smaller operand.
+- **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
+  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
+  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.
+- **Never scale in floats and round after.** `multiply`, `divide`, `convert` **and `fromDecimal`**
+  take the decimal spelling as an exact fraction (`factorFraction`, or the digit strings
+  themselves) and hand it to `roundRatio`, so the mode judges 100.5 and not the
+  100.49999999999999 `100 * 1.005` produces. A new scaling entry point goes through the same pair
+  — `roundToInteger(a * b, mode)` is the bug, written again. `fromDecimal` was the last float
+  path and it is the one every user-typed price goes through: `Number('0.4999999999999999999')`
+  is exactly 0.5, so `half-up` saw a tie the written decimal does not have.
+- **`convert` preserves the amount's own `scale`.** `exponentOf(target)` decides the natural scale
+  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`
+  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.
+- **An audit timestamp is never fabricated.** `convertWith`'s identity branch takes `{ at }` or an
+  injected `{ clock }` (default `systemClock`); `new Date(0)` claimed a parity observed in 1970.
+- **A derived rate carries its fraction, never its reciprocal.** `fixedRateProvider` answers the
+  inverse direction by swapping `ExchangeRate.ratio`'s numerator and denominator: a table naming
+  `USD/EUR: 0.92` names 23/25, so EUR→USD is exactly 25/23, where `1 / 0.92` is a double whose own
+  decimal spelling rounds a large amount one minor unit low. `rate` stays the readable number the
+  audit trail records; `convert` scales by `ratio` whenever the provider supplied one.
+- **One place decides a sign.** `formatMoney` is `formatMoneyParts` joined, and `accounting`
+  reaches `Intl` as `currencySign` — so the locale places the minus and picks the parenthesised
+  form, and a UI styling the parts cannot render a different format from the label beside it.
+- **The table is open, and it is opened by a call.** `registerCurrency({ code, exponent, name })` is
+  how an app adds a currency the shipped rows do not carry — axiom 8: `As of 2026-08`, 53 of ~180
+  ISO codes is a *convention*, and a convention an app cannot extend is a fork waiting to happen.
+  The rest of the framework already treated the set as open — `@ultimat3/schema`'s `moneySchema`,
+  the published OpenAPI `pattern` and `@ultimat3/entity`'s `char(3)` CHECK all accept any
+  `^[A-Z]{3}$` — so an unregistered code could arrive over HTTP and reach a row, and only
+  arithmetic refused it.
+- **What a well-formed code IS lives in `packages/schema/src/money-value.ts`, and nothing here
+  restates it.** `CURRENCY_CODE_PATTERN` is the pattern *source* — a string, because the two
+  projections that cannot call a predicate need it: the published OpenAPI `pattern` and
+  `@ultimat3/entity`'s Postgres `~` CHECK — and `isCurrencyCode` is the predicate over it,
+  `isMoneyScale`'s twin, taking `unknown` because every caller is a boundary. `registerCurrency`
+  imports it for exactly the reason `assertScale` imports `isMoneyScale`, and `currency.test.ts`
+  asserts the shipped table through it rather than through a local regex. Never write
+  `/^[A-Z]{3}$/` in this package: it was seven copies across the repo, each individually correct,
+  and the only place a divergence would have surfaced is a psql session or a generated client.
+- **A registration is refused, never defaulted.** No exponent is guessable: a silent 2 reads
+  `1.23456789 XBT` as `1.23` and a stored `minor` shifts by a power of ten. Bad shape, bad exponent
+  or an empty name is `X_CURRENCY_INVALID`; a second declaration of one code is
+  `X_CURRENCY_REDEFINED`, and an **identical** one is a no-op so a twice-imported module is not a
+  crash. A shipped ISO row cannot be redefined at all.
+- **Two enumerations, two questions.** `CURRENCIES` is the constant this package ships;
+  `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.
+- 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.
+
+## Commands
+
+```
+bun test packages/money
+bun run --filter @ultimat3/money typecheck
+```

package/README.md

@@ -1,14 +1,21 @@
 # 💶 @ultimat3/money
 
 **Golden rule: integer minor units, currency always attached, `Intl` at the edge.**
-`0.1 + 0.2 !== 0.3`, so no amount is ever a float. `Money` is `{ minor, currency }` — the
-two travel together, and arithmetic across two currencies throws instead of guessing.
+`0.1 + 0.2 !== 0.3`, so no amount is ever a float. `Money` carries `minor` and `currency` together
+— plus an optional `scale` — and arithmetic across two currencies throws instead of guessing.
+
+`Money` **is** `@ultimat3/schema`'s `MoneyValue`, and so is `@ultimat3/entity`'s: one declaration
+at tier 0, aliased twice, never restated. A row a `money()` column decodes is therefore a `Money`
+already — `add(row.price, shipping)` and `formatMoney(row.price, locale)` take it with no cast.
+`minor` is a `number` because money is projected onto every wire the framework generates and
+`JSON.stringify` refuses a bigint; the `bigint` column that backs it refuses a value past ±2^53 on
+read rather than rounding it. → [Money](https://github.com/developerz-ai/ultimate/wiki/Money)
 
 | Concern | Store | Format |
 |---|---|---|
 | Amount | integer minor units (`1299`) | `Intl.NumberFormat`, `style: 'currency'` |
-| Currency | ISO-4217 code (`'EUR'`) | fraction digits derived from its exponent |
-| Scale | never | `10 ** exponentOf(currency)` — never a literal `/ 100` |
+| Currency | a 3-letter code (`'EUR'`) — shipped ISO-4217 or `registerCurrency`'d | fraction digits derived from its exponent |
+| Scale | whenever it differs from the currency's, finer or coarser (`scale: 6`) | `10 ** moneyScale(amount)` — never a literal `/ 100` |
 | FX rate | explicit argument + timestamp | recorded on the converted value |
 
 ## Use
@@ -30,6 +37,63 @@ 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.
 
+## 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
+adds its own with a call rather than a fork: a local currency, a scrip, a loyalty point, a token.
+
+```ts
+import { fromDecimal, registerCurrency } from '@ultimat3/money';
+
+registerCurrency({ code: 'XBT', exponent: 8, name: 'Bitcoin' });
+fromDecimal('1.23456789', 'XBT');            // { minor: 123456789, currency: 'XBT' }
+```
+
+Once, at boot, before the first amount in that currency is built. The rules, each a refusal:
+
+| 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 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` |
+
+`CURRENCIES` stays the shipped constant; `currencyCodes()` answers for *this* process, registrations
+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⁻².
+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)`
+is $5 counted in whole dollars, and `rescale()` produces such values legitimately.
+
+```ts
+import { add, fromDecimal, money, 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
+fromDecimal('0.000002', 'USD', { scale: 6 });
+add(money(1, 'USD'), money(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
+a cent cannot round the fee away. `compare` and `equals` read the value rather than the encoding,
+so 1299 EUR and 12,990,000 EUR at scale 6 are one amount. `multiply`, `divide`, `negate`,
+`allocate` **and `convert`** keep the scale they were handed — a micro-priced amount is still
+micro-priced in the target currency. Widening is exact and free; a *lossy* narrowing needs
+a `RoundingMode` at the call site, exactly as excess precision does in `fromDecimal` — a narrowing
+that drops only zeros is exact and needs no mode.
+
+It exists because whole cents could not name the cost of a model call: 200 tokens at $0.80 per
+million is $0.00016, and rounding that up to 1¢ bills 62x — a budget built on that number is
+fiction. The alternative was a second money type.
+
 ## Allocation
 
 `allocate(money(100, 'USD'), 3)` → `34, 33, 33`. Largest-remainder split: floor every part,
@@ -50,12 +114,25 @@ returns the source amount, the rate, and its timestamp alongside the result —
 audit has to be able to reproduce the number. Implement `RateProvider` for a live feed;
 `fixedRateProvider()` covers tests, seeds and manually agreed invoice rates.
 
+A rate may also carry `ratio` — the exact `Fraction` its `rate` approximates — and `convert`
+scales by that when it is there. It is how a derived direction stays exact: a table naming
+`USD/EUR: 0.92` names 23/25, so `fixedRateProvider` answers EUR→USD with 25/23 rather than the
+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
+€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
+the epoch: `ExchangeRate.at` is the audit trail.
+
 ## Errors
 
 | Code | When |
 |---|---|
-| `X_MONEY_NOT_INTEGER` | fractional minor units, or a decimal string more precise than the currency |
-| `X_CURRENCY_UNKNOWN` | code not in the ISO-4217 table |
+| `X_MONEY_NOT_INTEGER` | fractional minor units, a decimal string more precise than the scale, or a `rescale` that would drop a digit with no mode named |
+| `X_MONEY_SCALE_INVALID` | a scale that is not a whole number of decimal places in 0…15, or a widening whose result no longer fits a safe integer |
+| `X_CURRENCY_UNKNOWN` | a code neither shipped nor registered by this process — `currencyCodes()` is the list |
 | `X_CURRENCY_MISMATCH` | arithmetic across two currencies |
 | `X_ALLOCATION_INVALID` | bad part count, empty/negative/all-zero ratios, percentages ≠ 100 |
 | `X_RATE_MISSING` | no rate for the pair — never assumes parity |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/money",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Integer minor units with an attached currency: arithmetic, allocation, rounding, Intl formatting",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,6 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "1.2.0"
+    "@ultimat3/core": "2.0.0",
+    "@ultimat3/schema": "2.0.0"
   }
 }

package/src/allocate.ts

@@ -10,7 +10,9 @@
 
 import { assertSameCurrency } from './arithmetic';
 import { allocationInvalid } from './errors';
-import { type Money, money } from './money';
+import { factorFraction } from './factor';
+import { formatMoneyDebug, type Money, money } from './money';
+import { minorAt, moneyScale } from './scale';
 
 /** Split into `parts` equal shares. `allocate(money(100,'USD'), 3)` → 34, 33, 33. */
 export function allocate(amount: Money, parts: number): Money[] {
@@ -26,26 +28,22 @@ export function allocate(amount: Money, parts: number): Money[] {
  */
 export function allocateByRatios(amount: Money, ratios: readonly number[]): Money[] {
   if (ratios.length === 0) throw allocationInvalid('ratios must not be empty');
-  let total = 0;
-  for (const ratio of ratios) {
-    if (!Number.isFinite(ratio) || ratio < 0) {
-      throw allocationInvalid(`ratios must be finite and non-negative, got ${String(ratio)}`);
-    }
-    total += ratio;
-  }
-  if (total <= 0) throw allocationInvalid('ratios must not all be zero');
+  const weights = weigh(ratios);
+  let total = 0n;
+  for (const weight of weights) total += weight;
+  if (total <= 0n) throw allocationInvalid('ratios must not all be zero');
 
   const sign = amount.minor < 0 ? -1 : 1;
-  const magnitude = Math.abs(amount.minor);
+  const magnitude = BigInt(Math.abs(amount.minor));
 
-  const floors: number[] = [];
-  const remainders: number[] = [];
-  let assigned = 0;
-  for (const ratio of ratios) {
-    const exact = (magnitude * ratio) / total;
-    const floor = Math.floor(exact);
+  const floors: bigint[] = [];
+  const remainders: bigint[] = [];
+  let assigned = 0n;
+  for (const weight of weights) {
+    const exact = magnitude * weight;
+    const floor = exact / total;
     floors.push(floor);
-    remainders.push(exact - floor);
+    remainders.push(exact % total);
     assigned += floor;
   }
 
@@ -54,14 +52,38 @@ export function allocateByRatios(amount: Money, ratios: readonly number[]): Mone
   let leftover = magnitude - assigned;
   const order = remainders
     .map((remainder, index) => ({ remainder, index }))
-    .sort((a, b) => b.remainder - a.remainder || a.index - b.index);
+    .sort((a, b) =>
+      a.remainder === b.remainder ? a.index - b.index : a.remainder < b.remainder ? 1 : -1,
+    );
   for (const { index } of order) {
-    if (leftover <= 0) break;
-    floors[index] = (floors[index] ?? 0) + 1;
-    leftover -= 1;
+    if (leftover <= 0n) break;
+    floors[index] = (floors[index] ?? 0n) + 1n;
+    leftover -= 1n;
   }
 
-  return floors.map((minor) => money(sign * minor, amount.currency));
+  return floors.map((minor) => money(sign * Number(minor), amount.currency, amount.scale));
+}
+
+/**
+ * The ratios as exact integer weights over one common denominator.
+ *
+ * `(magnitude * ratio) / total` in floats was only exact while the product stayed under 2^53 —
+ * true of most cent amounts and false of the same invoice held in micros, where the floor came
+ * out one unit low and largest-remainder handed the difference to the wrong part. Every
+ * denominator `factorFraction` produces is a power of ten, so the common one is just the largest.
+ */
+function weigh(ratios: readonly number[]): bigint[] {
+  const fractions = ratios.map((ratio) => {
+    if (!Number.isFinite(ratio) || ratio < 0) {
+      throw allocationInvalid(`ratios must be finite and non-negative, got ${String(ratio)}`);
+    }
+    return factorFraction(ratio);
+  });
+  let common = 1n;
+  for (const fraction of fractions) {
+    if (fraction.denominator > common) common = fraction.denominator;
+  }
+  return fractions.map((fraction) => fraction.numerator * (common / fraction.denominator));
 }
 
 /**
@@ -78,14 +100,19 @@ export function allocateByPercentages(amount: Money, percentages: readonly numbe
 
 /** Guard for callers building their own splits: parts must reconstruct the whole. */
 export function assertAllocationSums(amount: Money, parts: readonly Money[]): void {
-  let total = 0;
+  let scale = moneyScale(amount);
   for (const part of parts) {
     assertSameCurrency(amount, part);
-    total += part.minor;
+    scale = Math.max(scale, moneyScale(part));
   }
-  if (total !== amount.minor) {
+  // Summed at the finest scale present, so parts split finer than the whole still reconcile
+  // against it rather than reading as a total that lost everything below a cent.
+  let total = 0n;
+  for (const part of parts) total += minorAt(part, scale);
+  const whole = minorAt(amount, scale);
+  if (total !== whole) {
     throw allocationInvalid(
-      `allocation of ${amount.currency} ${amount.minor} sums to ${total} — ${amount.minor - total} minor unit(s) lost`,
+      `allocation of ${formatMoneyDebug(amount)} sums to ${total} at scale ${scale} — ${whole - total} minor unit(s) lost`,
     );
   }
 }

package/src/arithmetic.ts

@@ -4,8 +4,10 @@
  */
 
 import { allocationInvalid, currencyMismatch, currencyRequired } from './errors';
+import { factorFraction } from './factor';
 import { type Money, money } from './money';
-import { DEFAULT_ROUNDING, type RoundingMode, roundToInteger } from './rounding';
+import { DEFAULT_ROUNDING, type RoundingMode, roundRatio } from './rounding';
+import { commonScale, minorAt, toMinor } from './scale';
 
 /** Throws `X_CURRENCY_MISMATCH` unless both operands carry the same currency. */
 export function assertSameCurrency(left: Money, right: Money): string {
@@ -13,14 +15,28 @@ export function assertSameCurrency(left: Money, right: Money): string {
   return left.currency;
 }
 
+/**
+ * Two operands meet at the finer of their scales, which is exact for both — the coarser one is
+ * widened, never the finer one rounded, so adding a sub-cent fee to a cent cannot lose the fee.
+ */
 export function add(left: Money, right: Money): Money {
   const currency = assertSameCurrency(left, right);
-  return money(left.minor + right.minor, currency);
+  const scale = commonScale(left, right);
+  return money(
+    toMinor(minorAt(left, scale) + minorAt(right, scale), scale, currency),
+    currency,
+    scale,
+  );
 }
 
 export function subtract(left: Money, right: Money): Money {
   const currency = assertSameCurrency(left, right);
-  return money(left.minor - right.minor, currency);
+  const scale = commonScale(left, right);
+  return money(
+    toMinor(minorAt(left, scale) - minorAt(right, scale), scale, currency),
+    currency,
+    scale,
+  );
 }
 
 /** Every addend must share one currency; an empty list needs an explicit currency. */
@@ -33,18 +49,29 @@ export function sum(amounts: readonly Money[], currency?: string): Money {
 /**
  * Scale by a plain number (a tax rate, a quantity, a percentage). The result is rounded
  * to whole minor units with an explicit mode — the default is stated, not implied.
+ *
+ * The scale is taken as the exact fraction `factor`'s decimal spelling names, never as a float
+ * product: `100 * 1.005` is 100.49999999999999, so multiplying first hid the exact 100.5 from
+ * `half-up` and billed a 0.5% fee on €1.00 as nothing.
  */
 export function multiply(
   amount: Money,
   factor: number,
   mode: RoundingMode = DEFAULT_ROUNDING,
 ): Money {
-  return money(roundToInteger(amount.minor * factor, mode), amount.currency);
+  const ratio = factorFraction(factor);
+  // Scale-preserving: a fee on a micro-priced amount stays a micro-priced amount.
+  return money(
+    roundRatio(BigInt(amount.minor) * ratio.numerator, ratio.denominator, mode),
+    amount.currency,
+    amount.scale,
+  );
 }
 
 /**
  * Divide into a single share. Use `allocate` when the whole must be preserved —
- * `divide` alone loses the remainder by design.
+ * `divide` alone loses the remainder by design. Exact for the same reason `multiply` is:
+ * dividing by `d` is scaling by the reciprocal of the fraction `d` names.
  */
 export function divide(
   amount: Money,
@@ -54,22 +81,34 @@ export function divide(
   if (divisor === 0) {
     throw allocationInvalid('cannot divide money by zero — use allocate() to split a total');
   }
-  return money(roundToInteger(amount.minor / divisor, mode), amount.currency);
+  const ratio = factorFraction(divisor);
+  return money(
+    roundRatio(BigInt(amount.minor) * ratio.denominator, ratio.numerator, mode),
+    amount.currency,
+    amount.scale,
+  );
 }
 
 export function negate(amount: Money): Money {
-  return money(-amount.minor, amount.currency);
+  return money(-amount.minor, amount.currency, amount.scale);
 }
 
 export function absolute(amount: Money): Money {
-  return money(Math.abs(amount.minor), amount.currency);
+  return money(Math.abs(amount.minor), amount.currency, amount.scale);
 }
 
-/** `-1 | 0 | 1`, comparable currencies only. */
+/**
+ * `-1 | 0 | 1`, comparable currencies only — and comparing the value, not the encoding, so a
+ * finer scale is not automatically the larger number. Widened as bigints on purpose: a comparison
+ * must answer where storing the widened value would rightly be refused.
+ */
 export function compare(left: Money, right: Money): -1 | 0 | 1 {
   assertSameCurrency(left, right);
-  if (left.minor < right.minor) return -1;
-  return left.minor > right.minor ? 1 : 0;
+  const scale = commonScale(left, right);
+  const leftMinor = minorAt(left, scale);
+  const rightMinor = minorAt(right, scale);
+  if (leftMinor < rightMinor) return -1;
+  return leftMinor > rightMinor ? 1 : 0;
 }
 
 export function isZero(amount: Money): boolean {

package/src/convert.ts

@@ -4,16 +4,27 @@
  * and every converted amount records which rate produced it.
  */
 
+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 { DEFAULT_ROUNDING, type RoundingMode, roundToInteger } from './rounding';
+import { DEFAULT_ROUNDING, type RoundingMode, roundRatio } from './rounding';
+import { moneyScale } from './scale';
 
 export interface ExchangeRate {
   from: string;
   to: string;
   /** Major units of `to` per one major unit of `from`. */
   rate: number;
+  /**
+   * The exact value `rate` approximates, for a provider that knows one. `rate` is the number the
+   * audit trail records and a human reads; a reciprocal cannot be both. `1 / 0.92` is the double
+   * 1.0869565217391304, whose decimal spelling is NOT 25/23 — so scaling by it loses a minor unit
+   * on a large amount, and the table that named `USD/EUR = 0.92` never wrote that number at all.
+   * Omit it and `convert` expands `rate`'s own decimal spelling, which is exact for a direct rate.
+   */
+  ratio?: Fraction;
   /** When the rate was observed — part of the audit trail, not decoration. */
   at: Date;
   /** Where it came from: `ecb`, `openexchange`, `manual:invoice-4711`. */
@@ -37,7 +48,8 @@ export interface ConvertOptions {
 /**
  * `convert(money(1000,'USD'), 'EUR', { rate: 0.92, ... })`.
  * Scales across differing minor-unit exponents (USD 2 → JPY 0) instead of assuming both
- * sides have cents.
+ * 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.
  */
 export function convert(
   amount: Money,
@@ -52,15 +64,28 @@ export function convert(
   if (!Number.isFinite(rate.rate) || rate.rate <= 0) {
     throw rateMissing(amount.currency, target);
   }
+  if (rate.ratio !== undefined && (rate.ratio.numerator <= 0n || rate.ratio.denominator <= 0n)) {
+    throw rateMissing(amount.currency, target);
+  }
 
-  const scale = 10 ** (exponentOf(target) - exponentOf(amount.currency));
-  const converted = roundToInteger(
-    amount.minor * rate.rate * scale,
-    options.rounding ?? DEFAULT_ROUNDING,
-  );
+  // Exact, not a float product: `minor * rate * scale` shows the rounding mode a value IEEE-754
+  // has already moved, and a converted invoice line is off by a minor unit with nothing to trace.
+  // The provider's own fraction wins when it has one — see `ExchangeRate.ratio`.
+  const fraction = rate.ratio ?? factorFraction(rate.rate);
+  // The value's OWN precision, never the currency's: `moneyScale`, per this package's rule. A
+  // value carrying an explicit `scale` keeps it, because narrowing $0.000002 to EUR's two
+  // decimals is the 10,000x reinterpretation `scale` was added to prevent — and a value carrying
+  // none meets the target's natural scale, exactly as every conversion always has.
+  const resultScale = amount.scale ?? exponentOf(target);
+  const exponent = resultScale - moneyScale(amount);
+  let numerator = BigInt(amount.minor) * fraction.numerator;
+  let denominator = fraction.denominator;
+  if (exponent > 0) numerator *= 10n ** BigInt(exponent);
+  else if (exponent < 0) denominator *= 10n ** BigInt(-exponent);
+  const converted = roundRatio(numerator, denominator, options.rounding ?? DEFAULT_ROUNDING);
 
   return {
-    amount: money(converted, target),
+    amount: money(converted, target, resultScale),
     source: amount,
     rate: rate.rate,
     at: rate.at.toISOString(),
@@ -80,11 +105,14 @@ export async function convertWith(
   provider: RateProvider,
   amount: Money,
   to: string,
-  options: ConvertOptions & { at?: Date } = {},
+  options: ConvertOptions & { at?: Date; clock?: Clock } = {},
 ): Promise<ConvertedMoney> {
   const target = assertCurrency(to);
   if (amount.currency === target) {
-    const at = (options.at ?? new Date(0)).toISOString();
+    // The instant the parity was asserted, never `new Date(0)`: `ExchangeRate.at` is the audit
+    // trail, and a ledger row claiming its rate was observed on 1970-01-01 is a claim nobody
+    // made. The clock is injected for the same reason the rest of the framework injects one.
+    const at = (options.at ?? (options.clock ?? systemClock).now()).toISOString();
     return { amount, source: amount, rate: 1, at, provider: 'identity' };
   }
   const rate = await provider.rateFor(amount.currency, target, options.at);
@@ -95,9 +123,23 @@ export async function convertWith(
   };
 }
 
+/**
+ * The exact fraction a table entry names, or `undefined` for a number that is not a usable rate.
+ * `convert` refuses those on `rate.rate` with `X_RATE_MISSING`; expanding them here first would
+ * answer `X_NOT_ROUNDABLE` for the same mistake.
+ */
+function exactRate(value: number): Fraction | undefined {
+  return Number.isFinite(value) && value > 0 ? factorFraction(value) : undefined;
+}
+
 /**
  * Fixed-table provider for tests, seeds and manual invoice rates.
  * Keys are `FROM/TO`; the inverse is derived so a table needs one direction only.
+ *
+ * A table holds ONE observation, so a `wanted` instant other than its own is a rate this
+ * provider does not have — `undefined`, per `RateProvider`. Answering with today's number
+ * stamped `at: today` repriced a historical invoice against a rate nobody asked for and wrote a
+ * date into the audit trail that contradicted the request.
  */
 export function fixedRateProvider(
   rates: Readonly<Record<string, number>>,
@@ -106,12 +148,38 @@ export function fixedRateProvider(
 ): RateProvider {
   return {
     name,
-    async rateFor(from: string, to: string): Promise<ExchangeRate | undefined> {
+    async rateFor(from: string, to: string, wanted?: Date): Promise<ExchangeRate | undefined> {
+      if (wanted !== undefined && wanted.getTime() !== at.getTime()) return undefined;
       const direct = rates[`${from}/${to}`];
-      if (direct !== undefined) return { from, to, rate: direct, at, source: name };
+      if (direct !== undefined) {
+        const ratio = exactRate(direct);
+        return {
+          from,
+          to,
+          rate: direct,
+          at,
+          source: name,
+          ...(ratio === undefined ? {} : { ratio }),
+        };
+      }
       const inverse = rates[`${to}/${from}`];
       if (inverse !== undefined && inverse !== 0) {
-        return { from, to, rate: 1 / inverse, at, source: name };
+        // Swapped, never divided. A table holding `USD/EUR: 0.92` names 23/25, so the EUR/USD
+        // direction is exactly 25/23 — where `1 / 0.92` is a double whose own decimal spelling
+        // rounds a large amount one minor unit low. `rate` keeps the readable approximation.
+        const named = exactRate(inverse);
+        const ratio =
+          named === undefined
+            ? undefined
+            : { numerator: named.denominator, denominator: named.numerator };
+        return {
+          from,
+          to,
+          rate: 1 / inverse,
+          at,
+          source: name,
+          ...(ratio === undefined ? {} : { ratio }),
+        };
       }
       return undefined;
     },