@ultimat3/money 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# 💶 @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.
+
+| 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` |
+| FX rate | explicit argument + timestamp | recorded on the converted value |
+
+## Use
+
+```ts
+import { add, allocate, formatMoney, fromDecimal, money } from '@ultimat3/money';
+
+const price = fromDecimal('12.99', 'EUR');   // { minor: 1299, currency: 'EUR' }
+const total = add(price, money(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
+```
+
+## Minor units are not always cents
+
+`exponentOf()` is the single source of truth: USD/EUR 2, JPY/KRW/VND/ISK 0, KWD/BHD/OMR 3.
+`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.
+
+## Allocation
+
+`allocate(money(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.
+
+## Rounding is never implicit
+
+`multiply(price, 0.19, 'half-up')` — the mode is an argument because tax and interest rules
+name one in law. `half-up`, `half-even` (banker's), `down`, `up`. The default is `half-up`
+and it is stated, not inherited from `Math.round`.
+
+## Conversion
+
+No default rate provider ships. `convert(amount, to, rate)` takes the rate explicitly and
+returns the source amount, the rate, and its timestamp alongside the result — a finance
+audit has to be able to reproduce the number. Implement `RateProvider` for a live feed;
+`fixedRateProvider()` covers tests, seeds and manually agreed invoice rates.
+
+## 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_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 |
+
+## Why it exists
+
+Every money bug in production is one of three things: a float, a missing currency, or a
+lost cent in a split. This package makes all three unrepresentable rather than discouraged.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ultimat3/money",
+  "version": "1.0.0",
+  "description": "Integer minor units with an attached currency: arithmetic, allocation, rounding, Intl formatting",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/money"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "1.0.0"
+  }
+}

package/src/allocate.ts

@@ -0,0 +1,91 @@
+/**
+ * Largest-remainder allocation: split a total so the parts add back up to the total.
+ *
+ * The classic bug: 100 cents split three ways with `round(100 / 3)` gives 33/33/33 and
+ * loses a cent, or 34/34/34 and invents one. Invoices that do this fail reconciliation,
+ * and a revenue share that does it pays out the wrong amount forever. The fix is to
+ * floor every part, then hand the leftover minor units out one at a time, largest
+ * fractional remainder first — deterministic, total-preserving, no floats in the result.
+ */
+
+import { assertSameCurrency } from './arithmetic';
+import { allocationInvalid } from './errors';
+import { type Money, money } from './money';
+
+/** Split into `parts` equal shares. `allocate(money(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)}`);
+  }
+  return allocateByRatios(amount, new Array<number>(parts).fill(1));
+}
+
+/**
+ * Split by weights. `allocateByRatios(money(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[] {
+  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 sign = amount.minor < 0 ? -1 : 1;
+  const magnitude = 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);
+    floors.push(floor);
+    remainders.push(exact - floor);
+    assigned += floor;
+  }
+
+  // Hand out the leftover units, largest remainder first; ties go to the earlier index
+  // so the same input always produces the same split (invoices must be reproducible).
+  let leftover = magnitude - assigned;
+  const order = remainders
+    .map((remainder, index) => ({ remainder, index }))
+    .sort((a, b) => b.remainder - a.remainder || a.index - b.index);
+  for (const { index } of order) {
+    if (leftover <= 0) break;
+    floors[index] = (floors[index] ?? 0) + 1;
+    leftover -= 1;
+  }
+
+  return floors.map((minor) => money(sign * minor, amount.currency));
+}
+
+/**
+ * Split into shares given as percentages that must sum to 100 — the invoice-line case
+ * where a mis-typed percentage should be an error, not a silent re-normalization.
+ */
+export function allocateByPercentages(amount: Money, percentages: readonly number[]): Money[] {
+  const total = percentages.reduce((sum, percentage) => sum + percentage, 0);
+  if (Math.abs(total - 100) > 1e-9) {
+    throw allocationInvalid(`percentages must sum to 100, got ${String(total)}`);
+  }
+  return allocateByRatios(amount, percentages);
+}
+
+/** Guard for callers building their own splits: parts must reconstruct the whole. */
+export function assertAllocationSums(amount: Money, parts: readonly Money[]): void {
+  let total = 0;
+  for (const part of parts) {
+    assertSameCurrency(amount, part);
+    total += part.minor;
+  }
+  if (total !== amount.minor) {
+    throw allocationInvalid(
+      `allocation of ${amount.currency} ${amount.minor} sums to ${total} — ${amount.minor - total} minor unit(s) lost`,
+    );
+  }
+}

package/src/arithmetic.ts

@@ -0,0 +1,101 @@
+/**
+ * Integer arithmetic that refuses to mix currencies.
+ * `add(usd, eur)` is not a rounding problem, it is a wrong answer — so it throws.
+ */
+
+import { allocationInvalid, currencyMismatch, currencyRequired } from './errors';
+import { type Money, money } from './money';
+import { DEFAULT_ROUNDING, type RoundingMode, roundToInteger } from './rounding';
+
+/** Throws `X_CURRENCY_MISMATCH` unless both operands carry the same currency. */
+export function assertSameCurrency(left: Money, right: Money): string {
+  if (left.currency !== right.currency) throw currencyMismatch(left.currency, right.currency);
+  return left.currency;
+}
+
+export function add(left: Money, right: Money): Money {
+  const currency = assertSameCurrency(left, right);
+  return money(left.minor + right.minor, currency);
+}
+
+export function subtract(left: Money, right: Money): Money {
+  const currency = assertSameCurrency(left, right);
+  return money(left.minor - right.minor, currency);
+}
+
+/** Every addend must share one currency; an empty list needs an explicit currency. */
+export function sum(amounts: readonly Money[], currency?: string): Money {
+  const base = amounts[0]?.currency ?? currency;
+  if (base === undefined) throw currencyRequired('sum([])');
+  return amounts.reduce((total, amount) => add(total, amount), money(0, base));
+}
+
+/**
+ * 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.
+ */
+export function multiply(
+  amount: Money,
+  factor: number,
+  mode: RoundingMode = DEFAULT_ROUNDING,
+): Money {
+  return money(roundToInteger(amount.minor * factor, mode), amount.currency);
+}
+
+/**
+ * Divide into a single share. Use `allocate` when the whole must be preserved —
+ * `divide` alone loses the remainder by design.
+ */
+export function divide(
+  amount: Money,
+  divisor: number,
+  mode: RoundingMode = DEFAULT_ROUNDING,
+): Money {
+  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);
+}
+
+export function negate(amount: Money): Money {
+  return money(-amount.minor, amount.currency);
+}
+
+export function absolute(amount: Money): Money {
+  return money(Math.abs(amount.minor), amount.currency);
+}
+
+/** `-1 | 0 | 1`, comparable currencies only. */
+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;
+}
+
+export function isZero(amount: Money): boolean {
+  return amount.minor === 0;
+}
+
+export function isNegative(amount: Money): boolean {
+  return amount.minor < 0;
+}
+
+export function isPositive(amount: Money): boolean {
+  return amount.minor > 0;
+}
+
+export function greaterThan(left: Money, right: Money): boolean {
+  return compare(left, right) === 1;
+}
+
+export function lessThan(left: Money, right: Money): boolean {
+  return compare(left, right) === -1;
+}
+
+export function min(left: Money, right: Money): Money {
+  return compare(left, right) <= 0 ? left : right;
+}
+
+export function max(left: Money, right: Money): Money {
+  return compare(left, right) >= 0 ? left : right;
+}

package/src/convert.ts

@@ -0,0 +1,119 @@
+/**
+ * Currency conversion with the rate as an explicit argument.
+ * There is no default rate provider: a wrong exchange rate is worse than a missing one,
+ * and every converted amount records which rate produced it.
+ */
+
+import { assertCurrency, exponentOf } from './currency';
+import { rateMissing } from './errors';
+import { type Money, money } from './money';
+import { DEFAULT_ROUNDING, type RoundingMode, roundToInteger } from './rounding';
+
+export interface ExchangeRate {
+  from: string;
+  to: string;
+  /** Major units of `to` per one major unit of `from`. */
+  rate: number;
+  /** When the rate was observed — part of the audit trail, not decoration. */
+  at: Date;
+  /** Where it came from: `ecb`, `openexchange`, `manual:invoice-4711`. */
+  source?: string;
+}
+
+/** A converted amount carries its provenance so a finance audit can reproduce it. */
+export interface ConvertedMoney {
+  amount: Money;
+  /** The untouched original — never overwrite what the customer was charged. */
+  source: Money;
+  rate: number;
+  at: string;
+  provider?: string;
+}
+
+export interface ConvertOptions {
+  rounding?: RoundingMode;
+}
+
+/**
+ * `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.
+ */
+export function convert(
+  amount: Money,
+  to: string,
+  rate: ExchangeRate,
+  options: ConvertOptions = {},
+): ConvertedMoney {
+  const target = assertCurrency(to);
+  if (rate.from !== amount.currency || rate.to !== target) {
+    throw rateMissing(amount.currency, target);
+  }
+  if (!Number.isFinite(rate.rate) || rate.rate <= 0) {
+    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,
+  );
+
+  return {
+    amount: money(converted, target),
+    source: amount,
+    rate: rate.rate,
+    at: rate.at.toISOString(),
+    ...(rate.source === undefined ? {} : { provider: rate.source }),
+  };
+}
+
+/** Rate lookup. Implemented by the app — the framework ships no live provider. */
+export interface RateProvider {
+  readonly name: string;
+  /** `at` requests a historical rate; providers that cannot honour it must return undefined. */
+  rateFor(from: string, to: string, at?: Date): Promise<ExchangeRate | undefined>;
+}
+
+/** Convert through a provider; a missing pair throws `X_RATE_MISSING`, never guesses 1.0. */
+export async function convertWith(
+  provider: RateProvider,
+  amount: Money,
+  to: string,
+  options: ConvertOptions & { at?: Date } = {},
+): Promise<ConvertedMoney> {
+  const target = assertCurrency(to);
+  if (amount.currency === target) {
+    const at = (options.at ?? new Date(0)).toISOString();
+    return { amount, source: amount, rate: 1, at, provider: 'identity' };
+  }
+  const rate = await provider.rateFor(amount.currency, target, options.at);
+  if (rate === undefined) throw rateMissing(amount.currency, target);
+  return {
+    ...convert(amount, target, rate, options),
+    provider: rate.source ?? provider.name,
+  };
+}
+
+/**
+ * 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.
+ */
+export function fixedRateProvider(
+  rates: Readonly<Record<string, number>>,
+  at: Date,
+  name = 'fixed',
+): RateProvider {
+  return {
+    name,
+    async rateFor(from: string, to: string): Promise<ExchangeRate | undefined> {
+      const direct = rates[`${from}/${to}`];
+      if (direct !== undefined) return { from, to, rate: direct, at, source: name };
+      const inverse = rates[`${to}/${from}`];
+      if (inverse !== undefined && inverse !== 0) {
+        return { from, to, rate: 1 / inverse, at, source: name };
+      }
+      return undefined;
+    },
+  };
+}

package/src/currency.ts

@@ -0,0 +1,108 @@
+/**
+ * The ISO-4217 minor-unit exponent table. Every scale in the package derives from here —
+ * a hardcoded `/ 100` is a bug in JPY (0 digits) and in KWD (3 digits).
+ * As of 2026-07.
+ */
+
+import { currencyUnknown } from './errors';
+
+/** Uppercase ISO-4217 alphabetic code. */
+export type CurrencyCode = string;
+
+export interface CurrencyInfo {
+  code: CurrencyCode;
+  /** Number of decimal digits in the minor unit: USD 2, JPY 0, KWD 3. */
+  exponent: number;
+  name: string;
+}
+
+const TABLE: readonly CurrencyInfo[] = [
+  { code: 'AED', exponent: 2, name: 'UAE Dirham' },
+  { code: 'ARS', exponent: 2, name: 'Argentine Peso' },
+  { code: 'AUD', exponent: 2, name: 'Australian Dollar' },
+  { code: 'BGN', exponent: 2, name: 'Bulgarian Lev' },
+  { code: 'BHD', exponent: 3, name: 'Bahraini Dinar' },
+  { code: 'BRL', exponent: 2, name: 'Brazilian Real' },
+  { code: 'CAD', exponent: 2, name: 'Canadian Dollar' },
+  { code: 'CHF', exponent: 2, name: 'Swiss Franc' },
+  { code: 'CLP', exponent: 0, name: 'Chilean Peso' },
+  { code: 'CNY', exponent: 2, name: 'Yuan Renminbi' },
+  { code: 'COP', exponent: 2, name: 'Colombian Peso' },
+  { code: 'CZK', exponent: 2, name: 'Czech Koruna' },
+  { code: 'DKK', exponent: 2, name: 'Danish Krone' },
+  { code: 'EGP', exponent: 2, name: 'Egyptian Pound' },
+  { code: 'EUR', exponent: 2, name: 'Euro' },
+  { code: 'GBP', exponent: 2, name: 'Pound Sterling' },
+  { code: 'HKD', exponent: 2, name: 'Hong Kong Dollar' },
+  { code: 'HUF', exponent: 2, name: 'Forint' },
+  { code: 'IDR', exponent: 2, name: 'Rupiah' },
+  { code: 'ILS', exponent: 2, name: 'New Israeli Sheqel' },
+  { code: 'INR', exponent: 2, name: 'Indian Rupee' },
+  { code: 'ISK', exponent: 0, name: 'Iceland Krona' },
+  { code: 'JOD', exponent: 3, name: 'Jordanian Dinar' },
+  { code: 'JPY', exponent: 0, name: 'Yen' },
+  { code: 'KES', exponent: 2, name: 'Kenyan Shilling' },
+  { code: 'KRW', exponent: 0, name: 'Won' },
+  { code: 'KWD', exponent: 3, name: 'Kuwaiti Dinar' },
+  { code: 'MAD', exponent: 2, name: 'Moroccan Dirham' },
+  { code: 'MXN', exponent: 2, name: 'Mexican Peso' },
+  { code: 'MYR', exponent: 2, name: 'Malaysian Ringgit' },
+  { code: 'NGN', exponent: 2, name: 'Naira' },
+  { code: 'NOK', exponent: 2, name: 'Norwegian Krone' },
+  { code: 'NZD', exponent: 2, name: 'New Zealand Dollar' },
+  { code: 'OMR', exponent: 3, name: 'Rial Omani' },
+  { code: 'PEN', exponent: 2, name: 'Sol' },
+  { code: 'PHP', exponent: 2, name: 'Philippine Peso' },
+  { code: 'PKR', exponent: 2, name: 'Pakistan Rupee' },
+  { code: 'PLN', exponent: 2, name: 'Zloty' },
+  { code: 'RON', exponent: 2, name: 'Romanian Leu' },
+  { code: 'RSD', exponent: 2, name: 'Serbian Dinar' },
+  { code: 'SAR', exponent: 2, name: 'Saudi Riyal' },
+  { code: 'SEK', exponent: 2, name: 'Swedish Krona' },
+  { code: 'SGD', exponent: 2, name: 'Singapore Dollar' },
+  { code: 'THB', exponent: 2, name: 'Baht' },
+  { code: 'TND', exponent: 3, name: 'Tunisian Dinar' },
+  { code: 'TRY', exponent: 2, name: 'Turkish Lira' },
+  { code: 'TWD', exponent: 2, name: 'New Taiwan Dollar' },
+  { code: 'UAH', exponent: 2, name: 'Hryvnia' },
+  { code: 'USD', exponent: 2, name: 'US Dollar' },
+  { code: 'UYU', exponent: 2, name: 'Peso Uruguayo' },
+  { code: 'VND', exponent: 0, name: 'Dong' },
+  { code: 'XOF', exponent: 0, name: 'CFA Franc BCEAO' },
+  { code: 'ZAR', exponent: 2, name: 'Rand' },
+];
+
+const BY_CODE: ReadonlyMap<string, CurrencyInfo> = new Map(
+  TABLE.map((info) => [info.code, info] as const),
+);
+
+export const CURRENCIES: readonly CurrencyInfo[] = TABLE;
+
+export function isValidCurrency(currency: string): boolean {
+  return BY_CODE.has(currency);
+}
+
+/** Loud lookup: an unknown code is a data bug, not a formatting quirk. */
+export function currencyInfo(currency: string): CurrencyInfo {
+  const info = BY_CODE.get(currency);
+  if (info === undefined) throw currencyUnknown(currency);
+  return info;
+}
+
+export function assertCurrency(currency: string): CurrencyCode {
+  return currencyInfo(currency).code;
+}
+
+/** Decimal digits in the minor unit. */
+export function exponentOf(currency: string): number {
+  return currencyInfo(currency).exponent;
+}
+
+/** Minor units per major unit: 100 for EUR, 1 for JPY, 1000 for KWD. */
+export function scaleOf(currency: string): number {
+  return 10 ** exponentOf(currency);
+}
+
+export function currencyCodes(): CurrencyCode[] {
+  return TABLE.map((info) => info.code);
+}

package/src/errors.ts

@@ -0,0 +1,118 @@
+/**
+ * The X_* error codes owned by @ultimat3/money.
+ * A money bug that throws is a bug you can fix; one that rounds is a bug you ship.
+ */
+
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+export const MONEY_ERROR_CODES = [
+  'X_MONEY_NOT_INTEGER',
+  'X_CURRENCY_UNKNOWN',
+  'X_CURRENCY_MISMATCH',
+  'X_ALLOCATION_INVALID',
+  'X_RATE_MISSING',
+] as const;
+
+export type MoneyErrorCode = (typeof MONEY_ERROR_CODES)[number];
+
+export const MONEY_ERROR_TITLES: Readonly<Record<MoneyErrorCode, string>> = {
+  X_MONEY_NOT_INTEGER: 'a Money.minor value that is not an integer',
+  X_CURRENCY_UNKNOWN: 'currency code not in the currency table',
+  X_CURRENCY_MISMATCH: 'two Money values in different currencies',
+  X_ALLOCATION_INVALID: 'split ratios or part count are unusable',
+  X_RATE_MISSING: 'no FX rate for the pair',
+};
+
+// Titles must be registered for `format()` to render the contract's first line. Every code above is
+// owned here and none is borrowed, so the call is unconditional: a second package claiming one has
+// to fail as X_ERROR_CODE_DUPLICATE, not quietly keep whichever title was registered first.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(MONEY_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+export class MoneyError extends UltimateError {
+  constructor(init: { code: MoneyErrorCode; cause: string; fix: string }) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+      docs: `https://ultimate.dev/errors/${init.code}`,
+    });
+  }
+}
+
+export function moneyNotInteger(minor: number, currency: string): MoneyError {
+  return new MoneyError({
+    code: 'X_MONEY_NOT_INTEGER',
+    cause: `minor units must be a safe integer, got ${String(minor)} for ${currency}`,
+    fix: `use fromDecimal('${Number.isFinite(minor) ? minor : 0}', '${currency}') or round explicitly with multiply(m, factor, 'half-up')`,
+  });
+}
+
+/**
+ * A non-finite input to rounding is upstream float arithmetic that already lost the amount —
+ * rounding it would invent a number, so it throws instead.
+ */
+export function notRoundable(value: number): MoneyError {
+  return new MoneyError({
+    code: 'X_MONEY_NOT_INTEGER',
+    cause: `cannot round a non-finite amount: ${String(value)}`,
+    fix: 'trace the amount back to its source — a NaN or Infinity here means a division or a float multiply upstream; build amounts with fromDecimal(string, currency)',
+  });
+}
+
+export function decimalTooPrecise(value: string, currency: string, exponent: number): MoneyError {
+  return new MoneyError({
+    code: 'X_MONEY_NOT_INTEGER',
+    cause: `"${value}" has more fraction digits than ${currency} has minor units (${exponent})`,
+    fix: `pass { rounding: 'half-up' } to fromDecimal to accept the loss of precision on purpose`,
+  });
+}
+
+export function decimalNotNumeric(value: string, currency: string): MoneyError {
+  return new MoneyError({
+    code: 'X_MONEY_NOT_INTEGER',
+    cause: `"${value}" is not a decimal amount — no grouping separators, no exponent notation`,
+    fix: `pass a plain decimal string: fromDecimal('12.99', '${currency}')`,
+  });
+}
+
+export function currencyUnknown(currency: string): MoneyError {
+  return new MoneyError({
+    code: 'X_CURRENCY_UNKNOWN',
+    cause: `"${currency}" is not an ISO-4217 code in the currency table`,
+    fix: `x money add-currency ${currency.toUpperCase().slice(0, 3) || 'XXX'} --exponent 2`,
+  });
+}
+
+export function currencyRequired(context: string): MoneyError {
+  return new MoneyError({
+    code: 'X_CURRENCY_UNKNOWN',
+    cause: `${context}: no currency to infer, and none was passed`,
+    fix: "pass the currency explicitly, e.g. sum([], 'EUR')",
+  });
+}
+
+export function currencyMismatch(left: string, right: string): MoneyError {
+  return new MoneyError({
+    code: 'X_CURRENCY_MISMATCH',
+    cause: `refusing to combine ${left} and ${right} — two currencies are not one number`,
+    fix: `convert(rightOperand, '${left}', rate) first, then combine`,
+  });
+}
+
+export function allocationInvalid(cause: string): MoneyError {
+  return new MoneyError({
+    code: 'X_ALLOCATION_INVALID',
+    cause,
+    fix: 'pass a positive integer part count, or ratios that are finite, non-negative and not all zero',
+  });
+}
+
+export function rateMissing(from: string, to: string): MoneyError {
+  return new MoneyError({
+    code: 'X_RATE_MISSING',
+    cause: `no exchange rate available for ${from}→${to}`,
+    fix: 'register a RateProvider that covers this pair — there is no default provider, because a wrong rate is worse than a missing one',
+  });
+}

package/src/format.ts

@@ -0,0 +1,97 @@
+/**
+ * `Intl.NumberFormat` at the edge. Fraction digits come from the currency exponent, so
+ * JPY renders without decimals and KWD with three, without a per-locale special case.
+ */
+
+import { exponentOf } from './currency';
+import { type Money, toDecimalNumber } from './money';
+
+export interface FormatMoneyOptions {
+  /** How the currency appears: `€1,299.00` / `EUR 1,299.00` / `1,299.00 euros`. */
+  display?: 'symbol' | 'narrowSymbol' | 'code' | 'name';
+  /** Accounting negatives: `(€12.99)` instead of `-€12.99`. */
+  accounting?: boolean;
+  /** Drop `.00` on whole amounts — price lists, never invoices. */
+  trimZeroFraction?: boolean;
+  /** Force a digit count; defaults to the currency's minor-unit exponent. */
+  fractionDigits?: number;
+  /** `never` disables grouping separators. */
+  grouping?: 'auto' | 'never';
+}
+
+/** `formatMoney(money(129900,'EUR'), 'de-DE')` → `1.299,00 €`. */
+export function formatMoney(
+  amount: Money,
+  locale: string,
+  options: FormatMoneyOptions = {},
+): string {
+  const rendered = formatterFor(amount.currency, locale, options).format(
+    Math.abs(toDecimalNumber(amount)),
+  );
+  if (amount.minor < 0) {
+    return options.accounting === true ? `(${rendered})` : `-${rendered}`;
+  }
+  return rendered;
+}
+
+/**
+ * Parts, for UI that styles the symbol or the decimals differently (a smaller superscript
+ * cent, a muted currency code). Never re-split a formatted string with a regex.
+ */
+export function formatMoneyParts(
+  amount: Money,
+  locale: string,
+  options: FormatMoneyOptions = {},
+): Intl.NumberFormatPart[] {
+  return formatterFor(amount.currency, locale, options).formatToParts(toDecimalNumber(amount));
+}
+
+/** The symbol alone, e.g. for an input prefix: `€`, `¥`, `KD`. */
+export function currencySymbol(currency: string, locale: string): string {
+  const parts = formatterFor(currency, locale, { display: 'narrowSymbol' }).formatToParts(0);
+  return parts.find((part) => part.type === 'currency')?.value ?? currency;
+}
+
+/** Digits only, no symbol — for editable inputs and CSV exports. */
+export function formatMoneyDecimal(amount: Money, locale: string): string {
+  const digits = exponentOf(amount.currency);
+  return new Intl.NumberFormat(locale, {
+    style: 'decimal',
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+    useGrouping: false,
+  }).format(toDecimalNumber(amount));
+}
+
+const cache = new Map<string, Intl.NumberFormat>();
+
+function formatterFor(
+  currency: string,
+  locale: string,
+  options: FormatMoneyOptions,
+): Intl.NumberFormat {
+  const exponent = exponentOf(currency);
+  const digits =
+    options.fractionDigits ?? (options.trimZeroFraction === true ? undefined : exponent);
+  const key = [
+    locale,
+    currency,
+    options.display ?? 'symbol',
+    digits ?? 'auto',
+    options.grouping ?? 'auto',
+  ].join('|');
+  const cached = cache.get(key);
+  if (cached !== undefined) return cached;
+
+  const formatter = new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency,
+    currencyDisplay: options.display ?? 'symbol',
+    ...(digits === undefined
+      ? { minimumFractionDigits: 0, maximumFractionDigits: exponent }
+      : { minimumFractionDigits: digits, maximumFractionDigits: digits }),
+    ...(options.grouping === 'never' ? { useGrouping: false } : {}),
+  });
+  cache.set(key, formatter);
+  return formatter;
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+/** Public surface of @ultimat3/money. Explicit exports only. */
+
+export {
+  allocate,
+  allocateByPercentages,
+  allocateByRatios,
+  assertAllocationSums,
+} from './allocate';
+export {
+  absolute,
+  add,
+  assertSameCurrency,
+  compare,
+  divide,
+  greaterThan,
+  isNegative,
+  isPositive,
+  isZero,
+  lessThan,
+  max,
+  min,
+  multiply,
+  negate,
+  subtract,
+  sum,
+} from './arithmetic';
+export {
+  type ConvertedMoney,
+  type ConvertOptions,
+  convert,
+  type ExchangeRate,
+  fixedRateProvider,
+  type RateProvider,
+} from './convert';
+export {
+  assertCurrency,
+  CURRENCIES,
+  type CurrencyCode,
+  type CurrencyInfo,
+  currencyCodes,
+  currencyInfo,
+  exponentOf,
+  isValidCurrency,
+  scaleOf,
+} from './currency';
+export {
+  allocationInvalid,
+  currencyMismatch,
+  currencyRequired,
+  currencyUnknown,
+  decimalNotNumeric,
+  decimalTooPrecise,
+  MONEY_ERROR_CODES,
+  MONEY_ERROR_TITLES,
+  MoneyError,
+  type MoneyErrorCode,
+  moneyNotInteger,
+  rateMissing,
+} from './errors';
+export {
+  currencySymbol,
+  type FormatMoneyOptions,
+  formatMoney,
+  formatMoneyDecimal,
+  formatMoneyParts,
+} from './format';
+export {
+  currencyOf,
+  equals,
+  type FromDecimalOptions,
+  formatMoneyDebug,
+  fromDecimal,
+  isMoney,
+  type Money,
+  money,
+  toDecimalNumber,
+  toDecimalString,
+  zero,
+} from './money';
+export {
+  DEFAULT_ROUNDING,
+  ROUNDING_MODES,
+  type RoundingMode,
+  roundToDigits,
+  roundToInteger,
+} from './rounding';

package/src/money.ts

@@ -0,0 +1,105 @@
+/**
+ * The `Money` value type: an integer count of minor units with its currency attached.
+ * There is no float anywhere in this package, and no amount without a currency.
+ */
+
+import { assertCurrency, type CurrencyCode, exponentOf, scaleOf } from './currency';
+import { decimalNotNumeric, decimalTooPrecise, moneyNotInteger } from './errors';
+import { type RoundingMode, roundToInteger } from './rounding';
+
+/** `{ minor: 129900, currency: 'EUR' }` is €1,299.00. Treat instances as immutable. */
+export type Money = { minor: number; currency: string };
+
+const DECIMAL = /^([+-])?(\d+)(?:\.(\d+))?$/;
+
+/** The only constructor. Validates the currency and rejects fractional minor units. */
+export function money(minor: number, currency: string): Money {
+  const code = assertCurrency(currency);
+  if (!Number.isSafeInteger(minor)) throw moneyNotInteger(minor, code);
+  return { minor, currency: code };
+}
+
+export function zero(currency: string): Money {
+  return money(0, currency);
+}
+
+export interface FromDecimalOptions {
+  /** Required to accept a value with more precision than the currency has. */
+  rounding?: RoundingMode;
+}
+
+/**
+ * Parse a decimal **string** — never a float. `fromDecimal(12.99, 'EUR')` would already
+ * have lost the value before this function saw it, so the signature refuses it.
+ * `'12.99'` → 1299 EUR · `'1200'` → 1200 JPY · `'1.234'` → 1234 KWD.
+ */
+export function fromDecimal(
+  value: string,
+  currency: string,
+  options: FromDecimalOptions = {},
+): Money {
+  const code = assertCurrency(currency);
+  const match = DECIMAL.exec(value.trim());
+  const integerPart = match?.[2];
+  if (match === null || integerPart === undefined) {
+    throw decimalNotNumeric(value, code);
+  }
+
+  const exponent = exponentOf(code);
+  const negative = match[1] === '-';
+  const fractionPart = match[3] ?? '';
+
+  let minor: number;
+  if (fractionPart.length <= exponent) {
+    // Concatenating the digits *is* the minor-unit integer — no multiply, no drift.
+    minor = Number(`${integerPart}${fractionPart.padEnd(exponent, '0')}`);
+  } else {
+    const mode = options.rounding;
+    if (mode === undefined) throw decimalTooPrecise(value, code, exponent);
+    const kept = Number(`${integerPart}${fractionPart.slice(0, exponent)}`);
+    const remainder = Number(`0.${fractionPart.slice(exponent)}`);
+    minor = roundToInteger(kept + remainder, mode);
+  }
+
+  if (!Number.isSafeInteger(minor)) throw moneyNotInteger(minor, code);
+  return { minor: negative ? -minor : minor, currency: code };
+}
+
+/** `1299 EUR` → `'12.99'`; `1200 JPY` → `'1200'`; `1234 KWD` → `'1.234'`. */
+export function toDecimalString(amount: Money): string {
+  const exponent = exponentOf(amount.currency);
+  const sign = amount.minor < 0 ? '-' : '';
+  const digits = Math.abs(amount.minor)
+    .toString()
+    .padStart(exponent + 1, '0');
+  if (exponent === 0) return `${sign}${digits}`;
+  return `${sign}${digits.slice(0, digits.length - exponent)}.${digits.slice(-exponent)}`;
+}
+
+/**
+ * Major units as a float. **Format-time only** — the one place a division by the
+ * currency scale is legitimate, because `Intl.NumberFormat` takes a number.
+ */
+export function toDecimalNumber(amount: Money): number {
+  return amount.minor / scaleOf(amount.currency);
+}
+
+export function isMoney(value: unknown): value is Money {
+  if (value === null || typeof value !== 'object') return false;
+  const candidate = value as { minor?: unknown; currency?: unknown };
+  return Number.isSafeInteger(candidate.minor) && typeof candidate.currency === 'string';
+}
+
+/** Same currency, same minor units. */
+export function equals(left: Money, right: Money): boolean {
+  return left.currency === right.currency && left.minor === right.minor;
+}
+
+/** Stable serialization for logs, JSON columns and the manifest: `EUR 1299`. */
+export function formatMoneyDebug(amount: Money): string {
+  return `${amount.currency} ${amount.minor}`;
+}
+
+export function currencyOf(amount: Money): CurrencyCode {
+  return amount.currency;
+}

package/src/rounding.ts

@@ -0,0 +1,56 @@
+/**
+ * Explicit rounding modes. Tax, interest and VAT rules each name a mode in law;
+ * whichever one `Math.round` happens to implement is not an answer.
+ */
+
+import { notRoundable } from './errors';
+
+export type RoundingMode =
+  /** 0.5 away from zero — the commercial default most invoicing rules specify. */
+  | 'half-up'
+  /** 0.5 to the nearest even — banker's rounding, ISO 80000-1, avoids upward drift. */
+  | 'half-even'
+  /** Truncate toward zero — never overcharge. */
+  | 'down'
+  /** Away from zero — never undercharge. */
+  | 'up';
+
+export const ROUNDING_MODES: readonly RoundingMode[] = ['half-up', 'half-even', 'down', 'up'];
+
+export const DEFAULT_ROUNDING: RoundingMode = 'half-up';
+
+/** Round a fractional minor-unit amount to an integer number of minor units. */
+export function roundToInteger(value: number, mode: RoundingMode = DEFAULT_ROUNDING): number {
+  if (!Number.isFinite(value)) throw notRoundable(value);
+  const sign = value < 0 ? -1 : 1;
+  const magnitude = Math.abs(value);
+  const floor = Math.floor(magnitude);
+  const fraction = magnitude - floor;
+
+  switch (mode) {
+    case 'down':
+      return sign * floor;
+    case 'up':
+      return sign * (fraction > 0 ? floor + 1 : floor);
+    case 'half-up':
+      return sign * (fraction >= 0.5 ? floor + 1 : floor);
+    case 'half-even': {
+      if (fraction > 0.5) return sign * (floor + 1);
+      if (fraction < 0.5) return sign * floor;
+      return sign * (floor % 2 === 0 ? floor : floor + 1);
+    }
+  }
+}
+
+/**
+ * Round to `digits` decimal places, used when converting a decimal string whose
+ * precision exceeds the currency's minor unit.
+ */
+export function roundToDigits(
+  value: number,
+  digits: number,
+  mode: RoundingMode = DEFAULT_ROUNDING,
+): number {
+  const factor = 10 ** digits;
+  return roundToInteger(value * factor, mode) / factor;
+}