@amboras-dev/money 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,394 @@
-# Temporary Holding Version
+# `@amboras-dev/money`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Money core shared by the Amboras orchestrator (backend + admin), Medusa and plugins:
+the storage rule, a generated currency registry, and exact conversion between major
+units and stored integers. Zero dependencies; CommonJS + ESM + types; Node >= 20 and
+browsers.
+
+```ts
+import { fromMajor, money, toMajorDecimal, readStored, currencyCode, defaultCurrencyForCountry } from '@amboras-dev/money'
+
+fromMajor(19.99, 'USD')                       // { amount: 1999, currency: 'USD' }
+fromMajor(1200, 'jpy')                        // { amount: 120000, currency: 'JPY' }  (x100, not x1)
+fromMajor('1.234', 'KWD')                     // { amount: 1234, currency: 'KWD' }    (x1000)
+fromMajor(5.5, 'JPY')                         // throws MoneyError 'precision'
+fromMajor(1500.4, 'JPY', { precision: 'round' }) // { amount: 150000, currency: 'JPY' }
+toMajorDecimal(readStored({ value: '4300', precision: 20 }, 'usd')) // '43.00'
+toMajorDecimal(money(4350, 'HUF'), { digits: 'display' })           // '44'
+currencyCode('bgn')                           // throws: BGN was replaced by EUR
+defaultCurrencyForCountry('BG')               // 'EUR'
+```
+
+## The storage rule
+
+Amboras stores **every currency at x100, including zero-decimal ones** (JPY 1200 is
+stored as `120000`, VND 5,810,000 as `581000000`), and **x1000 for exactly KWD, BHD,
+OMR, TND, JOD, IQD, LYD**. The rule is keyed by currency code, never derived from ISO
+4217 digits: `10 ** isoDigits` as a divisor is the shape of every 100x money bug
+Amboras has had. Medusa's payment module is the reference implementation.
+
+## Four digit concepts
+
+They answer different questions and disagree on purpose. Never substitute one for another.
+
+| Concept | Question | Values | API |
+|---|---|---|---|
+| Storage scale | What do I multiply a major amount by to store it? | 100, or 1000 for the seven | `storageScale(code)` |
+| Storage digits | How many fraction digits does a stored amount keep on the way in? (Medusa `fractionDigitsFor`) | 0 for JPY, KRW, VND...; 3 for the seven; else 2 | `storageDigits(code)` |
+| Display digits | How many fraction digits do people see? (Medusa `isoFractionDigits`) | 0 for JPY, HUF, IDR, IQD...; 3 for KWD, BHD, OMR, TND, JOD, LYD; else 2 | `displayDigits(code)` |
+| PSP wire digits | What does a given payment provider expect on the wire? | per provider | `pspWireDigits` in `@amboras-dev/money/wire` |
+
+IQD stores 3 digits and displays 0; HUF stores 2 and displays 0; JPY stores 0 digits
+but at x100 scale, so a stored JPY integer has 2 implied decimals.
+
+## Entry points
+
+Each subpath is a thin public surface over the core and the shared internals.
+None re-implements a conversion, a rounding, a lookup or a parser.
+
+| Import | For | Main exports |
+|---|---|---|
+| `@amboras-dev/money` | everyone | registry, `Money`, `fromMajor`, `readStored`, arithmetic, allocation, decimal text, `formatMoney` |
+| `@amboras-dev/money/wire` | Medusa payment providers, pixels, feeds, carriers | `encodeWire`, `decodeWire`, `sameWireAmount`, `conventionOf`, `destinationAmount`, `feedPrice` |
+| `@amboras-dev/money/sql` | Medusa and orchestrator SQL | `storedToMajorSql`, `toReportingSql`, `convertStoredSql`, `summaryAmountSql` |
+| `@amboras-dev/money/fx` | rates and conversion (rates are passed in, never fetched) | `rate`, `rateFromDecimal`, `convert`, `toReporting`, `roundRetail` |
+| `@amboras-dev/money/commerce` | Medusa and the orchestrator backend | tax, discounts, markup, cost, order value |
+| `@amboras-dev/money/billing` | Amboras SaaS money (USD cents, credits), never merchant money | `usdCost`, `usdToCredits`, `applyCoupons` |
+| `@amboras-dev/money/ai` | agent tools, prompts, manifests | `MONEY_UNIT_SENTENCE`, `moneyView`, `parseModelMoney`, `moneyMentions` |
+| `@amboras-dev/money/input` | admin and ds money fields, imports, scrapers | `parseAmountInput`, `formatAmountInput`, `parseImportAmount`, `moneyTemplateOf` |
+| `@amboras-dev/money/testing` | consumers' tests | `CURRENCY_CASES`, `MEDUSA_AMOUNT_SHAPES`, `PSP_GOLDEN_VECTORS`, `checkWireDigits` |
+
+The checker that keeps hand-written money code out of the apps is a separate dev package, [`@amboras-dev/money-gate`](../money-gate).
+
+## Core API: currencies and Money
+
+**Currencies** (`CurrencyCode` is a branded upper-case string)
+
+- `currencyCode(input, { allowHistoric?, field? })`: `'usd'` to `'USD'`. Throws
+  `currency_invalid` for unknown codes. Retired codes (BGN, HRK) are accepted by default, so an
+  existing store's currency keeps validating; `allowHistoric: false` refuses them where a
+  currency is picked for something new (a new store or region).
+- `parseCurrencyCode(input, { allowHistoric? })`, `findCurrency`: the same rule, `null` instead of a throw.
+- `isCurrencyCode(value, { allowHistoric? })`: type guard; only canonical upper case; historic codes by default.
+- `currencyOptions({ preferred?, locale?, includeHistoric? })`: the picker for a new choice, active
+  codes only unless `includeHistoric: true`.
+- `currencyInfo(code)`: name, symbol, narrow symbol, `symbolIsAmbiguous` (another active
+  currency shares the narrow symbol), ISO numeric code, status, `replacedBy`, and the
+  three digit/scale values. Accepts historic codes.
+- `storageScale(code)`, `storageDigits(code)`, `displayDigits(code)`; unknown codes throw
+  (no silent 2-digit default).
+- `CURRENCIES`: every known currency, active and historic, sorted, frozen.
+- `defaultCurrencyForCountry(iso2)`: current legal tender, or `null`. Never guesses USD.
+
+**Money** (`Money = { amount: StoredAmount; currency: CurrencyCode }`, `StoredAmount` a
+branded safe integer, `MajorDecimal` branded canonical decimal text)
+
+- `money(stored, currency)`: wrap an already-stored integer.
+- `fromMajor(major, currency, { precision?, rounding?, field? })`: number or decimal
+  string to Money. `precision: 'reject'` (default) is capability-kit `toStorageAmount`
+  exactly: too many fraction digits throws `precision` unless a number is within float
+  noise of an allowed amount (`0.1 + 0.2`); strings are exact and get no noise
+  allowance. `precision: 'round'` rounds to the storage digits with `rounding`
+  (`half-up` default, a tie away from zero; also `half-even`, `down`, `up`, `floor`,
+  `ceil`). `unit: 'storage'` keeps one storage unit instead of the storage digits, Medusa
+  `toMinorUnits` (`Math.round(major x divisor)`): JPY 1200.5 is 120050 (with `'currency'`,
+  the default, it throws `precision`, or is 120100 with `precision: 'round'`).
+  More than 2^46 units throws `overflow`.
+- `toMajorDecimal(m, { digits?, rounding? })`: exact text by default, with the storage
+  digits, widened to the storage scale only when the stored value needs it (JPY
+  `120050` is `'1200.50'`); `digits: 'display'` rounds to the display digits.
+- `toMajorNumber(m)`: the double nearest the exact amount.
+- `readStored(raw, currency, { mode?, field? })`: Medusa's amount shapes (number,
+  numeric string, `{ value, precision }`, BigNumber) with Medusa `unwrapAmount`
+  precedence `value ?? numeric ?? itself`. A non-integer or unreadable amount throws
+  `amount_invalid`, or returns `null` with `mode: 'lenient'`; never `0`.
+
+Every function accepts historic codes so stores and amounts in BGN or HRK keep working;
+only choosing a currency for something new refuses them (`currencyOptions`, or
+`currencyCode(input, { allowHistoric: false })`).
+
+**Errors**: everything throws `MoneyError` with `code` in `currency_invalid`,
+`currency_mismatch`, `amount_invalid`, `precision`, `overflow`, `parse`, and `field`
+when the caller named one.
+
+## Core API: arithmetic, Medusa shapes, allocation, formatting
+
+**Currencies**: `parseCurrencyCode` (null while unknown, never throws), `firstCurrency(...candidates)`
+(no implicit default: `currency_missing` when every candidate is empty, `currency_invalid` for a
+corrupt one), `sameCurrency`, `medusaCurrencyCode` (the only sanctioned lower-casing),
+`currencySymbol`, `currencyName`, `currencyLabel`, `currencyOptions`, `localeForCurrency` (opt-in),
+`medusaEpsilon` (Medusa core payment-status epsilon from the generated `medusaDigits` column,
+pinned to `@medusajs/utils` 2.13.4). `CurrencyInfo` also carries `symbolAliases`, `localeHint` and `commaDecimal` (TND: its decimal mark is a comma, so `'12,500'` is 12.5).
+
+**Medusa shapes**: `readStored` reads `.value ?? .raw.value ?? .raw_.value`, then
+`.numeric ?? .numeric_`, then the primitive. `readStoredField` (`raw_<key>` first, no fallback
+when it is unreadable), `readStoredDecimal` (keeps fractions, canonical text),
+`readCalculatedPrice`, `toMedusaRaw` (never an exponent), `toMedusaAmountInput` (`'0'` for zero),
+`moneyByCurrency` / `moneyFor` (per-currency settings and price lists), `isPositiveAmount`.
+
+**Arithmetic** (exact, rounded once): `add`, `subtract`, `sum(items, currency)`, `multiply`,
+`divide`, `percentOf`, `compare`, `equals` (false across currencies), `isZero`, `isPositive`,
+`isNegative`, `min`, `max`, `clamp`, `remaining`, `within`, `excessOver`, `isStoredAmount`,
+`roundToUnit(value, currency, { unit: 'storage' | 'currency' | 'major', rounding })`, `roundMajor`.
+Every result is bounded at 2^46 units of the storage digits (`overflow`).
+Rounding modes: `half-up` (default), `half-even`, `down`, `up`, `floor`, `ceil`,
+`floor-after-tenth` (Shopify discount truncation).
+
+**ISO minor** (not for PSPs): `toIsoMinor`, `fromIsoMinor` at the display digits or declared ones.
+
+**Allocation**: `allocate(total, weights, { strategy, unit, caps })` with strategies
+`largest-remainder` (default), `largest-weight`, `last`, `last-first`, `cumulative`; shares
+always add up exactly; a DecimalText overload splits exact decimals at a scale.
+`allocateWaterfall` (greedy capped, shortfall), `splitUnitPrice` (one or two unit prices one
+unit apart).
+
+**Decimal text**: `parseDecimalText`, `isDecimalLiteral` (the one storage-literal grammar),
+`assertDecimalLiteral`, `trimDecimalZeros`, `decimalSum`, `decimalSubtract`, `decimalMultiply`,
+`decimalDivide`, `decimalRound`, `decimalCompare`, `decimalClamp`, `decimalWithin`. Exact; `''`
+and exponents are refused.
+
+**Formatting** (for people, not byte-stable across ICU): `formatMoney` (display digits, or
+`widen` / `trim-zero`; explicit locale, default `en-US`), `formatMoneyCompact`,
+`formatMoneyRange`, `moneyAxisFormatter`.
+
+Internals other entry points build on (never exported), each the only implementation of its concept:
+`internal/number-text.ts` `readNumberText` (the one separator engine), `internal/rational.ts`
+`mulDiv`/`ratioToDecimal`/`compareRatio`, `internal/percent.ts` `hundredPercent`/`percentOfUnits`/`percentRatio`/`basisPointsOf`,
+`internal/intl.ts`, `decimal.ts` `addDecimal`/`multiplyDecimal`/`roundToScale`, `iso-minor.ts` `isoMinorFactor`,
+`rounding.ts` `unitSize`/`mulDivToUnit`/`roundStoredDecimal`, `allocate.ts` `allocateUnits`, `medusa.ts` `storedFieldValue`,
+`registry.ts` `currencyMarks`, `money.ts` `storedDecimal`/`majorDecimal`/`boundedMoney`/`medusaAmountDecimal`.
+
+## `/wire`: what payment providers and destinations receive
+
+```ts
+import { money } from '@amboras-dev/money'
+import { ISO_MINOR_V2, conventionOf, decodeWire, encodeWire } from '@amboras-dev/money/wire'
+
+encodeWire('stripe', money(120000, 'JPY'), { convention: ISO_MINOR_V2 }) // 1200
+decodeWire('stripe', 1200, 'JPY', conventionOf(paymentIntent))          // { amount: 120000, currency: 'JPY' }
+```
+
+- Codec: `encodeWire`, `decodeWire`, `tryDecodeWire` (never throws), `wireFactor`, `pspWireDigits`, `oneWireUnit`, `wireBreakdown` (line items that sum to the encoded total), `wireKeyPart`.
+- Cutover marker: `WIRE_SCALE_KEY`, `WIRE_SCALE_ISO_MINOR_V2`, `WIRE_SCALE_MARKER`, `ISO_MINOR_V2`, `PRE_CUTOVER`, `conventionOf` (gated PSPs need the convention; there is no hidden default).
+- Provider tables: `PSP_IDS`, `pspSupportsCurrency`, `assertPspCurrency`, `pspCurrencies`, `pspDefaultCurrency`, `pspMinimumAmount`.
+- Comparison: `sameWireAmount` (a webhook amount against the expected Money, at storage scale).
+- Provider quirks: `verificationCharge`, `RAZORPAY_AFA_FREE_CAP`, `iyzicoPrice`, `authorizeNetReversibleAmount`, `jsonDecimalLiteral`.
+- Provider text: `parseProviderAmount` (carrier quotes, dispute amounts; `decimalSeparator: 'auto'` is the `/input` rule).
+- Destinations: `destinationAmount` (pixels, ad platforms, email tools), `feedPrice`, `googleMicros`, `eventMoney` (ClickHouse `Int64` contract).
+- Plugin slots: `slotMoney`, `readSlotMoney`.
+
+## `/sql`: money in Postgres and ClickHouse
+
+Every builder returns one shape, a `SqlFragment` `{ sql, bindings }` with knex `?` placeholders: run it as `knex.raw(f.sql, f.bindings)`.
+Values a caller passes are bindings, never inlined: `convertStoredSql`'s rate numerator and denominator (exact bigint text), `summaryAmountSql`'s JSON keys; `chEventRevenueByCurrencySql` returns ClickHouse `params` for its `{revenue_event:String}` query parameter.
+Column and expression arguments are identifiers and expressions written in code (a column name), or another builder's `SqlFragment`, whose bindings are carried along in placeholder order (`storedToMajorSql(summaryAmountSql('os.totals', 'paid_total'), 'o.currency_code')`).
+Text arguments are inlined as-is and never sanitised; the guard only refuses a blank value, the statement breakers `;`, `--`, `/*`, `*/` and NUL, and a `?` (which would shift the bindings), a tripwire for mistakes, not an injection defence.
+The DDL builders refuse fragments with bindings, since Postgres DDL takes no parameters.
+Values the package inlines itself (code lists, digits, divisors) come from the registry; currency facts never come from `currency.decimal_digits`.
+ClickHouse money is Decimal: `storedToMajorSql` divides `toDecimal128(amount, 3)` and `roundMajorSql` rounds `toDecimal128(value, 12)`, half away from zero like Postgres `ROUND(numeric)` (a Float64 is inexact and ClickHouse rounds it half-to-even; checked on ClickHouse 24.8).
+
+- Amounts: `storageDivisorSql`, `storedToMajorSql`, `roundMajorSql`, `medusaEpsilonSql`, `withinEpsilonSql`, `summaryAmountSql` (`raw_<key>` first), `rawAmountJsonSql`, `parseDecimalSql`, `normalizeCurrencySql`.
+- FX: `convertStoredSql`, `convertStoredByColumnsSql`, `toReportingSql`, `reportingCompleteSql` (with `fx.storeFactors` tables).
+- DDL: `STORAGE_AMOUNT_SQL_TYPE`, `storageAmountCheckSql` (`columnType: 'bigint'` default checks only the sign, since Postgres refuses `bigint <> 'NaN'`; `'numeric'` emits migration 106's NaN/Infinity guard compared as text), `currencyCodeCheckSql`.
+- Billing twins: `usdToCreditsSql`, `monthlyEquivalentSql` (same results as `/billing`).
+- ClickHouse: `chEventRevenueByCurrencySql`.
+
+## `/fx`: rates and conversion
+
+Rates are exact fractions (`Rate = { numerator, denominator }`, bigint) passed in by the caller, never fetched.
+
+- Rates: `rate`, `rateFromDecimal`, `rateFromRow`, `rateToDecimal`, `rateToNumber`, `rateEquals`, `invertRate`, `crossRate`, `formatRate`, `RATE_REF`, `RATE_BOUNDS`.
+  `rateFromDecimal` rounds the exact decimal, while the orchestrator's `lockedRateNumerator` rounds the float `Math.round(rate * 1e7)`; about 0.6% of rates get a numerator one unit apart.
+  Adoption: the orchestrator and Medusa switch rate encoding in the same release, and the dynamic rate refresh compares a fresh rate with the locked one by `rateEquals` (value, cross-multiplied), never by numerator, or migrating one repo first re-locks those pairs every day.
+- Conversion: `convert` (one rounding to a unit, then an optional retail ending), `convertFactor`, `impliedRate`.
+- Reporting: `storeFactors`, `toReporting` (per-item rounding, missing currencies reported, never dropped silently).
+- Retail endings: `roundRetail`, `priceRoundingParams`.
+- Plausibility: `classifyRate`, `deviationFactor`, `rateConsensus`, `confirmStoredFactor`, `DEFAULT_RATE_MAX_DEVIATION`, `FACTOR_TOLERANCE`.
+- Rate tables: `USD_PEGS`, `pegFallback`, `mergeRateTables`, `sanitizeRateTable`.
+- Store settings: `RATE_MODES`, `parseRateMode`, `PRICE_ROUNDINGS`, `parsePriceRounding`, `resolveMoneyByCurrency`.
+
+## `/commerce`: tax, discounts, pricing, cost
+
+- Tax: `splitGross`, `unitNetOfTax`, `allocateWithTax` (refunds; per row `net + tax == gross`), `inferTaxRatePercent`, `solveTaxRate`, `inferTaxesIncluded`, `displayTotals`.
+- Discounts: `discountAmount` (order or per-unit rounding, Shopify truncation via `floor-after-tenth`), `buyGetReward`, `formatDiscount`.
+- Pricing: `applyMarkup`, `retailPrice`, `marginPercent`, `percentChange`, `netOfFee`.
+- Inventory cost (major-unit decimals): `landedUnitCosts`, `weightedAverageCost`.
+- Orders: `resolveOrderValue` (the value ad platforms receive), `requiresPayment`, `storageConventionOf`.
+
+## `/billing`: Amboras SaaS money (USD cents and AI credits)
+
+- Usage: `usdCost` (exact token cost, 6 decimals).
+- Credits (1 credit = 1 US cent): `usdToCredits` (`ceil`, no epsilon; text and Money exact, a float cost first rounded half-even to 8 decimals so `0.07 * 3` gives 21), `creditsToUsd`, `prorateCredits`, `bucketCredits`.
+- Plans: `annualPrice`, `monthlyEquivalent`, `applyCoupons` (Stripe sequential or additive), `grossUpForPercentOffs`.
+  `grossUpForPercentOffs` is the orchestrator's `grossUpCredit` verbatim, float product included (9 cents at `[10, 20]` gives 12): it inverts `applyCoupons` for one percent coupon, and can miss by a cent for stacked percents because Stripe rounds each coupon's cut.
+
+## `/input`: text to amount and back
+
+One rule for every money field (the contract a future ds `<MoneyInput>` builds on), and one for files.
+All of them read text through the one separator engine (`internal/number-text.ts`); none uses `parseFloat` or `Number`.
+
+```ts
+import { parseAmountInput, formatAmountInput, parseImportAmount, inputStep } from '@amboras-dev/money/input'
+
+parseAmountInput('1,250', 'USD')                          // { ok: true, money: { amount: 125000, ... }, text: '1250.00' }
+parseAmountInput('29,99', 'EUR')                          // 29.99 (no locale: the 'auto' rule, as admin reads it today)
+parseAmountInput('1,5', 'KWD')                            // 1.5
+parseAmountInput('1200.5', 'JPY')                         // 1201 (no locale: a whole yen, half-up, as admin)
+parseAmountInput('29,99', 'USD', { locale: 'en-US' })     // { ok: false, reason: 'unparseable' } (en-US groups with ',')
+parseAmountInput('29,99', 'EUR', { locale: 'de-DE' })     // 29.99
+parseAmountInput('1200.5', 'JPY', { locale: 'en-US' })    // { ok: false, reason: 'too_many_decimals' } (never rounded)
+parseAmountInput('1,2345', 'USD')                         // { ok: false, reason: 'too_many_decimals' }
+parseAmountInput('99.000', 'VND')                         // 99000 (3-digit tail groups in a currency without decimals)
+parseAmountInput('12.99.', 'USD')                         // { ok: false, reason: 'unparseable' } (groups must be thousands or lakh)
+parseAmountInput('1.500', 'TND', { decimalSeparator: '.' }) // 1.5 (an <input type="number"> value: '.' is always the decimal)
+formatAmountInput(money(1500, 'TND'), { decimalSeparator: '.' }) // '1.5' (the number input's prefill, read back exactly)
+formatAmountInput(money(123456789, 'USD'), { grouped: true, locale: 'de-DE' }) // '1.234.567,89'
+parseImportAmount('1.299,00')                             // '1299'
+parseImportAmount('0,500')                                // '0.5' (a group never follows a lone zero)
+parseImportAmount('12,500', { currency: 'TND' })          // '12.5' (TND writes a decimal comma; KWD '1,500' is '1500')
+parseImportAmount('1200,5', { currency: 'JPY' })          // '1201' (rounded to a whole yen)
+inputStep('KWD')                                          // '0.001'
+```
+
+- `parseAmountInput(text, currency, { locale, decimalSeparator, allowNegative, allowZero, min, max, original })`: strips the currency's symbols and code and refuses more fraction digits than the currency stores.
+  Without `locale` (the chat wizard and any field that has none) it reads the `'auto'` rule below, which is today's admin `parseMajorUnits` except the listed differences, and a currency storing 0 digits rounds a fraction half-up to a whole unit (`'1200.5'` JPY is 1201), as admin does.
+  With `locale` it reads that locale's separators: the group separator is valid only in thousands groups (`'1,234,567'`) or Indian lakh groups (`'12,34,567'`: three digits on the right, then pairs), and only when every group fits (`'1,2345'` and `'12,3,456'` are `unparseable`), and extra digits are `too_many_decimals` in every currency.
+  **Every number input (`<input type="number">`) must pass `{ decimalSeparator: '.' }`**: browsers always serialise its value with a `.` decimal and no grouping, so the free-text rule would misread it (TND and IQD `'1.500'` are 1,500 there, 1.5 here).
+  In `'.'` mode `.` is the decimal, `,` and grouping are `unparseable`, a zero whole part may be omitted (`'.5'` is 0.5), and a currency storing 0 digits rounds a fraction half-up to a whole unit, as admin `numericEntryToMinorUnits` does (`'1200.5'` JPY is 1201).
+  It equals that function on every `.`-only value within the storage digits (`test/input/input.test.ts`), except one class:
+  - `extra-fraction-digits`: in a currency storing 2 or 3 digits, more fraction digits than it stores is `too_many_decimals`, never rounded (`'1.239'` USD, admin 124 cents; KWD `'1.0005'`, admin 1001).
+  Failure reasons: `empty`, `unparseable`, `too_many_decimals`, `negative`, `zero`, `below_min`, `above_max`.
+- `formatAmountInput(m, { locale, decimalSeparator, grouped, digits })`: the field text for a stored amount, no symbol, exact: a sub-unit stored amount keeps its digits (JPY 120050, which Medusa writes today, is `'1200.5'`), never rounded on display.
+  Without `locale` it prints the spelling `parseAmountInput` reads back without a locale: trailing fraction zeros dropped (USD `'12.5'`, KWD 1500 `'1.5'`, IQD 10000000 `'10000'`), and TND, which writes a decimal comma, with `,` as the decimal and `.` as the group (`'1,125'`, `'1.234,5'`).
+  Two amounts have no such spelling and read back only through `original`: IQD with a three-digit fraction (`'1.125'` reads as 1,125, since IQD displays no decimals) and a sub-unit amount of a currency storing 0 digits (`'1200.5'` JPY reads as a whole 1,201).
+  With `locale` it uses that locale's separators and the storage digits (`'12,50'` de-DE); `digits: 'storage'` or `'trim-zero'` overrides the zeros either way.
+  With `decimalSeparator: '.'` (a number input's prefill) it prints `.` as the decimal, never groups and drops trailing zeros (TND 1500 is `'1.5'`), so `parseAmountInput(text, currency, { decimalSeparator: '.' })` reads it back exactly (a sub-unit JPY amount through `original`).
+  Prefill and save with `parseAmountInput(text, currency, { original: m })`: the untouched prefill text, or any text equal in value to `m`, returns `m` unchanged, so saving an untouched field never rewrites the amount.
+- `inputStep`, `inputPlaceholder`: from the storage digits, never a hardcoded `0.01`.
+- `parseImportAmount(text, { decimalSeparator: 'auto' | '.' | ',', currency, allowNegative, allowTrailingText })`: CSV, supplier, scraped and carrier text to `DecimalText` (major units), or `null`.
+  `'auto'` is the only comma/dot rule in the package (`/ai` `moneyMentions`, `/wire` `parseProviderAmount` and `moneyTemplateOf` use it too), and it treats `.` and `,` the same way:
+  when both appear, the later one is the decimal and the other groups (`'1.299,00'` and `'1,299.00'` are 1299).
+  One separator used more than once groups (`'1.299.000'` is 1299000, `'₹1,00,000'` is 100000).
+  One separator after nothing but zeros is the decimal (`'0,500'` and `'.5'` are 0.5).
+  One separator before exactly three digits groups (`'1.299'` EUR, `'1,299'` USD and `'Rp 199.000'` IDR are thousands), unless the currency displays three decimals and the separator is its decimal mark: KWD `'1.500'` is 1.5 while KWD `'1,500'` is 1500, and TND, which writes a decimal comma, reads `'12,500'` as 12.5 and `'1.500'` as 1500; IQD (displays 0 digits) groups both.
+  One separator before any other number of digits is the decimal (`'29,99'` is 29.99); more digits than the currency stores is left to the caller's precision policy.
+  Currencies without decimals (JPY, VND) group before three digits and round any other fraction to a whole unit (`'1200,5'` JPY is 1201).
+  Wherever a separator groups, the groups must be thousands (first group 1 to 3 digits, then exactly 3) or Indian lakh, none empty and none followed by a trailing separator; otherwise the text is `unparseable` (`'12.99.'`, `'1,2,3'`, `'1,23,4567'`, `'1,299,'`).
+- `parseDecimalInput`, `parsePercentInput`: strict decimal and percent entry with digit limits and bounds.
+- `parseRateInput(text, { locale })`: a typed exchange rate as a precise `fx` `Rate`, or `null`.
+- `moneyTemplateOf(sample)`, `formatWithTemplate(m, template)`: replay a merchant's captured print format (`'Rp 199.000,00'`, `"1'299.00 CHF"`); the separators are read by the `'auto'` rule (`'Rp 199.000'` captures dot grouping and no decimals); the amount converts by the storage scale, so x1000 currencies are right.
+
+## `/ai`: money for agent tools
+
+```ts
+import { MONEY_UNIT_SENTENCE, moneyFieldDescription, moneyView, parseModelMoney, moneyMentions } from '@amboras-dev/money/ai'
+
+moneyFieldDescription('Refund amount.')    // 'Refund amount. Amount in normal currency units as the merchant says it ...'
+moneyView(money(1999, 'USD'))              // { amount: 19.99, currency: 'USD', display: '$19.99' }
+parseModelMoney('1,299.00', 'USD')         // { ok: true, money: { amount: 129900, currency: 'USD' } }
+parseModelMoney(19.999, 'USD')             // { ok: false, error: '19.999 has more decimal places than USD uses (at most 2). Amount in ...' }
+moneyMentions('Now AED 4,200.00')          // [{ raw: 'AED 4,200.00', index: 4, symbol: 'AED', code: 'AED', amount: '4200' }]
+```
+
+- `MONEY_UNIT_SENTENCE` and `MONEY_META_KEY` are verbatim from capability-kit and hashed into manifests.
+  `STORAGE_UNIT_SENTENCE` and `RATE_UNIT_SENTENCE` are the wording for stored amounts and manual rates.
+- `moneyView(m)`: the one stored-to-model rendering: exact `amount`, and a `display` at the display digits, widened to keep a stored value finer than them (JPY 550 is `'¥5.5'`, HUF 435050 `'HUF 4,350.5'`).
+  Not capability-kit's digits: its `moneyView` uses the storage digits as the minimum (`'HUF 4,350.00'`, `'IQD 1.500'` where this shows `'HUF 4,350'`, `'IQD 1.5'`); see [Behaviour changes](#behaviour-changes-for-adopters).
+- `parseModelMoney(input, currency, { allowNegative, allowZero })`: numbers through `fromMajor` (float noise allowed), strings through the `/input` entry rule in English.
+  It refuses extra fraction digits and negatives instead of guessing, and every error ends with `MONEY_UNIT_SENTENCE`, so the model is asked again.
+- `moneyMentions(text, { currency })`, `moneyLiteralPattern(...)`, `currencySymbolAliases(code)`: prices in visible text from one fixed table (registry symbols, aliases and codes plus any Unicode currency sign), never the runtime's Intl data.
+  The pattern is `{ source, flags }` so a browser script (`page.evaluate`) runs exactly what Node runs.
+
+## `/testing`: shared fixtures and golden data
+
+Framework-agnostic: no test runner or fast-check dependency.
+
+- `CURRENCY_CASES`: one currency per storage, display and wire class (USD, JPY, KWD, IQD, HUF, IDR, ISK, UGX, CLP, CVE, MGA, XOF, VND, INR, historic BGN).
+- `MEDUSA_AMOUNT_SHAPES`: every amount shape Medusa hands over, with what `readStored` and `readStoredDecimal` give.
+- `ROUNDING_VECTORS`: the cases float code got wrong (`1.005`, `0.1 + 0.2`, `-2.5`, Shopify truncation) and the tie rules.
+- `PSP_GOLDEN_VECTORS`: the wire bytes today's Medusa codecs produce for every PSP, every currency it presents and 18 storage amounts (one unit, ties at /100 and /1000, typical prices, the 2^46-unit bound), with refusals as their verbatim messages.
+  `/wire`'s `encodeWire` must reproduce every vector (decision D2: wire bytes feed idempotency keys, Redis keys and HMAC strings).
+  A positive amount whose wire rounds to 0 (68 vectors: one storage unit of a zero-decimal currency at Stripe, Adyen, Razorpay, Airwallex, PayPal HUF/JPY/TWD, Mollie ISK/JPY) is a refusal vector by package policy: `encodeWire` refuses it with `wire_refused` (`... rounds to 0 at <Tag> ...`).
+  Medusa today puts 0 on the wire at initiate for Stripe and Adyen, and for Razorpay, PayPal and Airwallex everywhere; it refuses at refund and capture for Stripe and Adyen, and in Mollie, iyzico and Authorize.Net.
+- `DESTINATION_GOLDEN_VECTORS`: what `destinationAmount`, `feedPrice` and `googleMicros` must give per destination.
+- `checkWireDigits(psp, documented)`: the capability-consistency probe; returns mismatch messages.
+- `normalizeIntlSpaces(s)`, `sampleMoney(currency, major)`.
+
+The golden vectors are generated, never edited: `scripts/gen-golden-vectors.mjs` runs Medusa's own adapter encoders (`src/payment-seam/adapters/*/amount.ts` and `src/common/money`) under Node's type stripping.
+The file header pins a SHA-256 of every Medusa source it read, so `--check` fails when a codec changes.
+
+```sh
+node scripts/gen-golden-vectors.mjs --medusa ../medusa-backend-orchestrator --ref origin/staging
+node scripts/gen-golden-vectors.mjs --medusa ../medusa-backend-orchestrator --ref origin/staging --check
+```
+
+## Behaviour changes for adopters
+
+What an app sees change when it moves its own money code onto the package.
+The full list, with the decision behind each, is in [`docs/money/API-SPEC.md`](../../docs/money/API-SPEC.md) ("Behaviour changes").
+
+- **Display digits for 15 currencies.** AFN, ALL, COP, HUF, IDR, IQD, IRR, KPW, LAK, LBP, MMK, PKR, SOS, SYP and YER display fewer digits than they store (IQD stores 3 and shows 0, the rest store 2 and show 0).
+  `formatMoney`, `moneyView` (`/ai`), `destinationAmount` and `feedPrice` (`/wire`) use the display digits; capability-kit, the plugins and Medusa's `formatMoney` use the storage digits today.
+  This is deliberate: it is what the PSPs charge and what people read.
+  - `formatMoney` (default `digits: 'display'`) rounds half-up: HUF 435050 was `HUF 4,350.50` and is `HUF 4,351`; IQD 1500 was `IQD 1.500` and is `IQD 2`.
+  - Catalog feeds and destinations drop the sub-unit the same way: `feedPrice(money(435050, 'HUF'))` is `'4351 HUF'`, IQD 1500 is `'2 IQD'`.
+  - Model views keep the value but show fewer zeros: `moneyView` returns the exact `amount` and widens `display` only for a sub-unit value (`'HUF 4,350.5'`), so HUF 435000 is `'HUF 4,350'` where capability-kit shows `'HUF 4,350.00'`, and IQD 1500 is `'IQD 1.5'` where it shows `'IQD 1.500'`.
+  - Machine files that need storage precision use `toMajorDecimal(m)` or `formatAmountInput(m)`.
+- **Retail `'none'` rounds zero-decimal currencies to a whole unit**, as Medusa `applyRounding` does (JPY 150050 gives 150100).
+- **Rate encoding** rounds the exact decimal, not the float (see `/fx`); both repos switch together and compare rates with `rateEquals`.
+- **BGN is historic, and only new choices drop it.** Existing BGN stores (401 regions, 363 `store_currency` rows on prod) keep working: `currencyCode`, `parseCurrencyCode`, `isCurrencyCode`, `moneyByCurrency` and every Money function accept historic codes by default.
+  The picker for a new store or region, `currencyOptions()`, no longer lists BGN (Bulgaria is EUR), while Medusa's `iso-currencies.ts` and the orchestrator still do; validate a new choice with `currencyCode(input, { allowHistoric: false })`.
+- **Lesotho defaults to LSL** (the orchestrator says LSL too; CLDR lists ZAR first). BY, SL and ZW default to BYN, SLE and ZWG, where the orchestrator's map still seeds the retired BYR, SLL and ZWL.
+- **The OMR fallback peg is 0.3845** (CBO midpoint), not the orchestrator's 0.385: OMR fallbacks move by 0.13%.
+- **Lakh grouping reads**: `parseAmountInput('1,00,000', 'INR')` is 100000 (it was `unparseable`), and `moneyMentions('₹1,00,000')` reads 100000 (it was 1).
+- **Typed price text: `parseAmountInput` without a locale is admin `parseMajorUnits` + `majorToMinorUnits` except these classes.**
+  `test/input/parse-corpus.test.ts` pins it on 643 inputs x 12 currencies (7,716 cases) against a verbatim port of the admin rule (dev-orch `admin/lib/chat/price-units.ts` at `8125e05c`); every other case is identical, including every case in JPY, VND and CLP outside `negative-sign`, `foreign-characters`, `above-storage-limit` and `invalid-grouping`.
+  Number inputs are not in this list: they use `{ decimalSeparator: '.' }`, compared with admin `numericEntryToMinorUnits` above.
+  Counts are differing cases in that corpus.
+  - `lone-dot-thousands` (68): in a currency storing two decimals, one `.` before exactly three digits groups thousands, as `,` does: `'1.299'` USD is $1,299 (admin $1.30), `'99.000'` is $99,000 (admin $99).
+  - `dot-not-decimal-mark` (26): one separator before exactly three digits is the decimal only when the currency displays three decimals and it is that currency's decimal mark (the dot for KWD, BHD, OMR, JOD and LYD, the comma for TND); otherwise it groups. So TND `'1.500'` is 1,500 (admin 1.5) while TND `'12,500'` is 12.5, and IQD, which displays 0 digits, reads `'1.500'` and `'1,500'` as 1,500 (admin 1.5 and 1,500); KWD `'1.500'` is 1.5 and `'1,500'` is 1,500, as admin.
+    `formatAmountInput` therefore prints TND with a decimal comma and drops trailing zeros, so its no-locale text reads back without `original`, except IQD amounts with a three-digit fraction.
+  - `repeated-dot` (117): `.` written more than once, in valid groups, groups, where admin kept the first dot as the decimal: `'1.299.000'` USD is $1,299,000 (admin $1.30), KWD is 1,299,000 (admin 1.299).
+  - `comma-long-fraction` (158): one `,` before more digits than the currency stores (other than three) is the decimal and the precision rule decides, where admin removed the comma: `'1,2345'` USD is `too_many_decimals` (admin $12,345); KWD `'1,5000'` is 1.5 (admin 15,000).
+  - `extra-fraction-digits` (297): more fraction digits than the currency stores is `too_many_decimals`, where admin rounded to the storage unit: `'1.2345'` USD (admin 123 cents), `'1,299.005'` USD (admin 129901).
+  - `negative-sign` (72): a leading `-` or U+2212 is a negative amount (`negative` unless `allowNegative`), where admin dropped it: `'-5'` USD (admin $5).
+  - `foreign-characters` (316): text other than digits, separators, spaces, apostrophes, a sign and the currency's own symbols and code is `unparseable`, where admin deleted it: `'1e3'` (admin 13), `'1,299 abc'` (admin 1299), `'Rs. 1,299'` in USD (admin $1.30; INR reads it as 1299).
+  - `above-storage-limit` (144): past 2^46 units of the storage digits is `above_max`, where admin lost digits in a float: `'12345678901234567'` JPY (admin 1234567890123460000).
+  - `invalid-grouping` (3,652): a separator read as grouping must sit in thousands groups (first group 1 to 3 digits, then groups of exactly 3) or Indian lakh groups, with no empty group and no separator after them; otherwise the text is `unparseable`, where admin read a number: `'12.99.'` USD (admin $12.99; the package read $1,299 before this rule), `'1,2,3'` (admin $123), `'12,3,456'`, `'1,23,4567'`, `'1,299,'`, `'1234.500'` USD (admin $1,234.50) and `'1.2.3'` JPY (admin 12 yen).
+    Most of this class comes from the corpus's generated doubled-segment strings (`'12.50.50'`); `'1.299.000'` and `'12,34,567'` still read.
+- **Negative exact ties round away from zero (D1).** The default `half-up` gives `fromMajor(-2.5, 'JPY', { precision: 'round' })` = -300 where Medusa `Math.round` (ties toward +infinity) gives -200; positive ties agree.
+  A read of Medusa `origin/staging` on 2026-10-22 (all 205 `Math.round` calls in `src/` and every caller of `toMinorUnits`, `roundToDisplayUnit` and `roundToStorageUnit`) found no refund, return, store-credit, gift-card or dispute path that rounds a negative exact tie: each operand is non-negative, or clamped to zero or above around the rounding.
+  One path does: `src/common/orders/order-address-change.ts:290` rounds the total change of a shipping-address tax requote with `roundToDisplayUnit`, and that delta is negative when the new address taxes less and can be an exact tie (the totals are unrounded).
+  A -0.5 unit delta rounds to -0 there, which also passes the hold gate (`delta !== 0` in `order-address-change-service.ts`), where the package gives -1; that site's adoption must choose its tie rule explicitly.
+
+## Decisions
+
+- **One implementation per concept.** One decimal engine (bigint, exact) and one
+  rounding function; one registry lookup for every scale and digits question.
+  Every amount is computed exactly, except one documented verbatim port:
+  `/billing` `grossUpForPercentOffs` keeps the orchestrator's float64 `grossUpCredit`
+  so granted upgrade credits match to the cent (money-gate exemptions MG002/MG003 on
+  its lines; see `docs/decisions.md` for the plan to make it exact).
+- **Generated registry.** `src/data/currencies.ts` and `src/data/countries.ts` come from
+  `scripts/gen-currency-data.mjs` and pinned CLDR JSON (version in `CLDR_VERSION`),
+  never from the runtime's `Intl`, which changes with Node/ICU. CI runs `--check`.
+  The script holds the decisions: the storage sets, Medusa's digit tables, retired codes
+  and their replacements, active codes CLDR no longer lists as tender (SVC, VED).
+  It fails instead of guessing when a CLDR release needs a new decision.
+- **Codes** are Medusa's ISO 4217 list plus retired codes (ANG, BGN, BYR, CUC, EEK,
+  HRK, LTL, LVL, MRO, SLL, STD, VEF, ZMK, ZWL). BGN is historic: CLDR 48.2.0 ends it on
+  2026-01-31 after Bulgaria adopted the euro.
+- **Numeric codes** come from CLDR `codeMappings` and are `null` where CLDR has none
+  (BYN, SLE, SVC, XCG, ZWG and some retired codes).
+- **Countries** map each CLDR region to its first listed open legal tender (what ICU
+  uses: PA is PAB, BT is BTN), except where that is a foreign currency: Lesotho is LSL
+  (CLDR lists ZAR first). See `docs/decisions.md` for every difference from the
+  orchestrator's country map.
+
+## Testing
+
+`pnpm test` (vitest, 100% coverage). Property tests check the rounding modes against an
+independent distance-based reference and the classic rounding table, the
+`fromMajor`/`toMajorDecimal` round trip for every currency, and registry parity with
+Medusa's digit tables (encoded in the test as fixtures). capability-kit's
+`toStorageAmount` tests are ported as parity tests for `precision: 'reject'`.

package/dist/ai.cjs

@@ -0,0 +1,185 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_money = require("./money-D5-vlv0h.cjs");
+const require_format = require("./format-BnA1aLJk.cjs");
+const require_number_text = require("./number-text-BpvN6NAo.cjs");
+const require_amount = require("./amount-DHtvZSSm.cjs");
+//#region src/ai/mentions.ts
+const ACTIVE = require_money.CURRENCIES.filter((c) => c.status === "active");
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const LETTER_START = /^\p{L}/u;
+const LETTER_END = /\p{L}$/u;
+const SINGLE_LETTER = /^\p{L}$/u;
+const OWNERS = /* @__PURE__ */ new Map();
+for (const info of ACTIVE) for (const mark of require_money.currencyMarks(info)) OWNERS.set(mark, [...OWNERS.get(mark) ?? [], info.code]);
+/**
+* Every spelling a store may print for `currency` besides its ISO code, from the registry:
+* symbol, narrow symbol and aliases (`['₹', 'Rs.', 'Rs']` for INR, `['$', 'US$']` for USD).
+*/
+function currencySymbolAliases(currency) {
+	const info = require_money.resolveCurrency(currency, { allowHistoric: true });
+	return Object.freeze(require_money.currencyMarks(info).filter((mark) => mark !== info.code));
+}
+/** A mark as a regex alternative; a mark that starts or ends with a letter must not touch another letter. */
+function markSource(mark) {
+	const before = LETTER_START.test(mark) ? "(?<!\\p{L})" : "";
+	const after = LETTER_END.test(mark) ? "(?!\\p{L})" : "";
+	return `${before}${escapeRegExp(mark)}${after}`;
+}
+function numberSource(maxFractionDigits) {
+	const fraction = maxFractionDigits === 0 ? "" : `(?:[.,]\\d{1,${maxFractionDigits}})?`;
+	return `(?:${require_number_text.digitGroupingSource("[ \\u00a0\\u2009\\u202f.,'’]")})${fraction}|\\d+${fraction}`;
+}
+/**
+* The money-literal regex as `{ source, flags }` (flags `'gu'`), a string so a browser script
+* (`page.evaluate`) runs exactly what Node runs. It matches a currency mark next to a number,
+* either order, at most one space between: the marks of `currency`, or of every active
+* currency (single-letter marks such as `R` only when `currency` names them), plus any Unicode
+* currency sign. Numbers group in threes or in Indian lakh (`1,00,000`) with `.`, `,`, space
+* or apostrophe and carry up to `maxFractionDigits` (default 3) fraction digits. Groups: 1 mark and 2 number, or 3 number
+* and 4 mark. A bare number never matches.
+*/
+function moneyLiteralPattern(options = {}) {
+	const digits = options.maxFractionDigits ?? 3;
+	if (!Number.isInteger(digits) || digits < 0 || digits > 6) throw new require_money.MoneyError("amount_invalid", `maxFractionDigits must be an integer from 0 to 6, got ${require_money.describeValue(digits)}`);
+	const mark = `(${[...(options.currency === void 0 ? [...OWNERS.keys()].filter((mark) => !SINGLE_LETTER.test(mark)) : require_money.currencyMarks(require_money.resolveCurrency(options.currency, { allowHistoric: true }))).sort((a, b) => b.length - a.length || (a < b ? -1 : 1)).map(markSource), "\\p{Sc}"].join("|")})`;
+	const number = `(${numberSource(digits)})`;
+	return {
+		source: `${mark}\\s?${number}|${number}\\s?${mark}`,
+		flags: "gu"
+	};
+}
+function codeOfMark(mark, currency) {
+	if (currency && require_money.currencyMarks(currency).includes(mark)) return currency.code;
+	const owners = OWNERS.get(mark);
+	return owners?.length === 1 ? owners[0] : void 0;
+}
+/**
+* Every price in `text`, in order (see `moneyLiteralPattern`). With `currency`, its marks are
+* matched (single letters too) and claim the mentions they appear in; a mark only one active
+* currency prints names that currency; `$`, `kr` and other shared marks leave `code` unset.
+* `amount` is read with the separator engine's `'auto'` rule in the named currency (one
+* separator before exactly three digits groups, except a KWD-style decimal mark).
+*/
+function moneyMentions(text, options = {}) {
+	const currency = options.currency === void 0 ? null : require_money.resolveCurrency(options.currency, { allowHistoric: true });
+	const { source, flags } = moneyLiteralPattern({ currency: currency?.code });
+	const mentions = [];
+	for (const match of String(text).matchAll(new RegExp(source, flags))) {
+		const symbol = match[1] ?? match[4];
+		const code = codeOfMark(symbol, currency);
+		const read = require_number_text.readNumberText(match[2] ?? match[3], {
+			decimalSeparator: "auto",
+			currency: code
+		});
+		mentions.push({
+			raw: match[0],
+			index: match.index,
+			symbol,
+			...code === void 0 ? {} : { code },
+			..."reason" in read ? {} : { amount: require_money.toDecimalText({
+				units: read.units,
+				scale: read.scale
+			}) }
+		});
+	}
+	return mentions;
+}
+//#endregion
+//#region src/ai/wording.ts
+/** The one unit sentence every money field carries, for the model and for people. Verbatim. */
+const MONEY_UNIT_SENTENCE = "Amount in normal currency units as the merchant says it (99 means 99.00; 1.5 means 1.50). Never cents or minor units.";
+/** JSON Schema keyword marking a money field. Verbatim. */
+const MONEY_META_KEY = "x-amboras-money";
+/** How store API amounts are scaled, for tool descriptions that hand stored amounts to the model. */
+const STORAGE_UNIT_SENTENCE = "Store API amounts are storage units: major units x100, x1000 for KWD, BHD, OMR, TND, JOD, IQD and LYD, and x100 for zero-decimal currencies too. Render them with the money formatter; never divide or multiply by hand.";
+/** What a manual exchange rate means, for rate fields. */
+const RATE_UNIT_SENTENCE = "1 unit of the store currency equals this many units of the other currency.";
+/** A money field's description: `describe` (trimmed) followed by the unit sentence, or the sentence alone. */
+function moneyFieldDescription(describe) {
+	const lead = typeof describe === "string" ? describe.trim() : "";
+	return lead ? `${lead} ${MONEY_UNIT_SENTENCE}` : MONEY_UNIT_SENTENCE;
+}
+//#endregion
+//#region src/ai/model-money.ts
+/**
+* `{ amount: 19.99, currency: 'USD', display: '$19.99' }`. `amount` is exact; `display` shows the
+* display digits, widened to keep a stored value finer than them (JPY 550 is `'¥5.5'`, HUF 435050
+* `'HUF 4,350.5'`). capability-kit's `moneyView` uses the storage digits as the minimum instead
+* (HUF 435000 is `'HUF 4,350.00'` there and `'HUF 4,350'` here, IQD 1500 `'IQD 1.500'` against
+* `'IQD 1.5'`): a deliberate change, listed in the README's behaviour changes.
+*/
+function moneyView(m) {
+	const { info } = require_money.storedDecimal(m);
+	return {
+		amount: require_money.toMajorNumber(m),
+		currency: info.code,
+		display: require_format.formatMoney(m, {
+			locale: "en",
+			digits: "widen"
+		})
+	};
+}
+function failure(reason, input, code, digits) {
+	const shown = require_money.describeValue(input);
+	return {
+		ok: false,
+		error: `${{
+			empty: `Not an amount: ${shown}.`,
+			unparseable: `Not an amount: ${shown}.`,
+			too_many_decimals: `${shown} has more decimal places than ${code} uses (at most ${digits}).`,
+			negative: "The amount must not be negative.",
+			zero: "The amount must be more than zero.",
+			below_min: `${shown} is out of range for ${code}.`,
+			above_max: `${shown} is out of range for ${code}.`
+		}[reason]} ${MONEY_UNIT_SENTENCE}`
+	};
+}
+function fromNumber(input, currency, options) {
+	if (!Number.isFinite(input)) return "unparseable";
+	if (input < 0 && !options.allowNegative) return "negative";
+	if (input === 0 && options.allowZero === false) return "zero";
+	try {
+		return require_money.fromMajor(input, currency);
+	} catch (error) {
+		return error.code === "precision" ? "too_many_decimals" : "above_max";
+	}
+}
+/**
+* An amount from a model tool call (major units, as the merchant says it) as Money, or an
+* error to send back to the model ending with `MONEY_UNIT_SENTENCE`. Numbers go through
+* `fromMajor` (float noise such as 0.1 + 0.2 allowed); strings through `/input`'s entry rule
+* in English (`'1,299.00'`, `'$1,299'`, `'99.000'` VND, `'1.500'` JPY). More fraction digits
+* than the currency stores and negative amounts are refused, never rounded or flipped. An
+* unknown currency throws `currency_invalid` (it is the tool's, not the model's).
+*/
+function parseModelMoney(input, currency, options = {}) {
+	const info = require_money.resolveCurrency(currency, { allowHistoric: true });
+	if (typeof input === "number") {
+		const result = fromNumber(input, info.code, options);
+		return typeof result === "string" ? failure(result, input, info.code, info.storageDigits) : {
+			ok: true,
+			money: result
+		};
+	}
+	if (typeof input !== "string") return failure("unparseable", input, info.code, info.storageDigits);
+	const result = require_amount.parseAmountInput(input, info.code, {
+		locale: "en",
+		allowNegative: options.allowNegative,
+		allowZero: options.allowZero
+	});
+	return result.ok ? {
+		ok: true,
+		money: result.money
+	} : failure(result.reason, input, info.code, info.storageDigits);
+}
+//#endregion
+exports.MONEY_META_KEY = MONEY_META_KEY;
+exports.MONEY_UNIT_SENTENCE = MONEY_UNIT_SENTENCE;
+exports.RATE_UNIT_SENTENCE = RATE_UNIT_SENTENCE;
+exports.STORAGE_UNIT_SENTENCE = STORAGE_UNIT_SENTENCE;
+exports.currencySymbolAliases = currencySymbolAliases;
+exports.moneyFieldDescription = moneyFieldDescription;
+exports.moneyLiteralPattern = moneyLiteralPattern;
+exports.moneyMentions = moneyMentions;
+exports.moneyView = moneyView;
+exports.parseModelMoney = parseModelMoney;