suaveplan/openspec/changes/enterprise-money/proposal.md

# OpenSpec Change: enterprise-money

- **Change ID**: enterprise-money
- **Package**: `@suaveplan/money`
- **Category**: finance
- **Target path**: `finance/currency/money`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/money.md`

---

## Summary

Deliver `@suaveplan/money` on the genesis branch from scratch at enterprise quality. The package provides precise currency / money arithmetic using BigInt minor-unit representation. It ships the immutable `Money` class, a `CurrencyRegistry` (constructor-injectable, with a default global instance), ISO 4217 metadata, virtual-currency registration, `Intl`-backed formatting, allocation helpers, aggregation helpers, `MoneyRange`, locale-aware parse, BigInt-safe JSON serialization, Zod schemas, property-based tests, and a typed error hierarchy. Zero runtime dependencies beyond `tslib` and `zod`.

---

## Current-state audit (genesis)

Does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | Base for `MoneyError` hierarchy |
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` (not used at runtime; types only) |
| `zod` (`catalog:forms`) | `MoneyLike` / `CurrencyCode` schemas |
| `tslib` (`catalog:build`) | Runtime helpers |

Dev dep: `fast-check catalog:testing`.

---

## Public API surface (from main branch, fully preserved + genesis additions)

```ts
// Core
class Money {
  static fromMajor(value: number | string, currency: string, registry?: CurrencyRegistry): Money
  static fromMinor(minorUnits: bigint, currency: string, registry?: CurrencyRegistry): Money
  static zero(currency: string, registry?: CurrencyRegistry): Money
  static withRegistry(registry: CurrencyRegistry): typeof Money
  get amount(): bigint           // minor units
  get currency(): string
  add(other: Money): Money
  subtract(other: Money): Money
  multiply(factor: number): Money
  divide(divisor: number, mode?: RoundingMode): Money
  compare(other: Money): -1 | 0 | 1
  equals(other: Money): boolean
  abs(): Money
  negate(): Money
  isZero(): boolean
  isPositive(): boolean
  isNegative(): boolean
  toMajor(): number
  toDecimalString(): string
  toJSON(): { amount: string; currency: string }
}

// Registry
class CurrencyRegistry {
  static global(): CurrencyRegistry
  getCurrency(code: string): CurrencyInfo | undefined
  getCurrencyOrThrow(code: string): CurrencyInfo
  getAllCurrencyCodes(): string[]
  registerCurrency(info: CurrencyInfo): void
  getVirtualCurrencies(): CurrencyInfo[]
  isVirtualCurrency(code: string): boolean
  minorUnitMultiplier(code: string): bigint
}
function getCurrency(code: string): CurrencyInfo | undefined        // delegates to global
function getCurrencyOrThrow(code: string): CurrencyInfo
function getAllCurrencyCodes(): string[]
function registerCurrency(info: CurrencyInfo): void
function getVirtualCurrencies(): CurrencyInfo[]
function isVirtualCurrency(code: string): boolean
function minorUnitMultiplier(code: string): bigint

// Formatting
function formatMoney(money: Money, options?: FormatOptions): string
function formatMoneyCompact(money: Money, options?: FormatOptions): string
function parseMoney(input: string, currency: string, locale?: string): Money

// Allocation
function allocateEvenly(money: Money, parts: number): Money[]
function allocateByRatios(money: Money, ratios: number[]): Money[]
function allocateByPercentages(money: Money, percentages: number[]): Money[]
function sumMoney(moneys: Money[]): Money
function minMoney(...moneys: Money[]): Money
function maxMoney(...moneys: Money[]): Money
function applyRounding(money: Money, mode: RoundingMode): Money

// MoneyRange (genesis addition)
class MoneyRange {
  constructor(min: Money, max: Money)
  contains(money: Money): boolean
  intersect(other: MoneyRange): MoneyRange | null
  union(other: MoneyRange): MoneyRange
  toArray(step: Money): Money[]
}

// Serialization
function moneyToJSON(money: Money): { amount: string; currency: string }
function moneyFromJSON(json: { amount: string; currency: string }): Money

// Zod schemas
const MoneyLikeSchema: z.ZodType<MoneyLike>
const CurrencyCodeSchema: z.ZodType<CurrencyCode>
const FormatOptionsSchema: z.ZodType<FormatOptions>

// Error types
class MoneyError extends SuaveplanError { }
class CurrencyMismatchError extends MoneyError { }
class UnknownCurrencyError extends MoneyError { }
class AllocationError extends MoneyError { }
class ParseError extends MoneyError { }
```

---

## File layout

```text
finance/currency/money/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    constants/index.ts
    types/
      money.types.ts
      money.types.md
    core/
      money/
        money.ts / money.md / money.types.ts / money.test.ts / index.ts
      currency-registry/
        currency-registry.ts / .md / .types.ts / .test.ts / index.ts
      currencies/
        currencies.ts / currencies.md / currencies.test.ts / index.ts
      money-range/
        money-range.ts / .md / .test.ts / index.ts
    formatting/
      formatter/
        formatter.ts / formatter.md / formatter.test.ts / index.ts
    allocation/
      allocator/
        allocator.ts / allocator.md / allocator.test.ts / index.ts
    schemas/
      money-schemas/
        money-schemas.ts / money-schemas.md / money-schemas.test.ts / index.ts
    serialization/
      json/
        json.ts / json.md / json.test.ts / index.ts
  tests/
    property.test.ts
```

---

## Impact

Downstream: `@suaveplan/currency` (uses `MoneyLike`), `@suaveplan/currency-providers`, payment and billing packages.

**Prerequisites on Verdaccio**: `@suaveplan/error`, `zod`.