# Tasks: enterprise-money

**Change ID**: enterprise-money
**Package**: `@suaveplan/money`
**Target path**: `finance/currency/money`
**Prerequisites on Verdaccio**: `@suaveplan/error`, `zod`

---

## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 1. Scaffold

- [ ] Create full directory tree per `proposal.md`.
- [ ] `package.json` at `0.1.0`, `"sideEffects": false`, exports `"."` + `core/money` + `core/currency-registry` + `core/currencies` + `core/money-range` + `formatting` + `allocation` + `schemas` + `serialization`.
- [ ] Deps: `@suaveplan/error workspace:^`, `zod catalog:forms`, `tslib catalog:build`.
- [ ] DevDeps: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `fast-check catalog:testing`, `@suaveplan/testing workspace:^`.
- [ ] `tsconfig.json` extending `library.json`; `vitest.config.ts` with `createTestConfig()`.
- [ ] Scripts: `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check`.

## 2. Error hierarchy

- [ ] `src/error-codes.ts`: define `MoneyErrorCode` union; implement `MoneyError`, `CurrencyMismatchError`, `UnknownCurrencyError`, `AllocationError`, `ParseError` extending `SuaveplanError`; `registerMoneyErrorCodes()`; eager call.

## 3. Currency registry + ISO data

- [ ] Implement `CurrencyRegistry` in `src/core/currency-registry/currency-registry.ts`: internal `Map<string, CurrencyInfo>`; all methods per API surface.
- [ ] `src/core/currencies/currencies.ts`: ISO 4217 data (≥50 common currencies minimum, full list preferred); seed the global `CurrencyRegistry.global()` on module load.
- [ ] Write tests: register/get/virtual/multiplier; `getCurrencyOrThrow` throws `UnknownCurrencyError`; virtual vs ISO separation.

## 4. Money class

- [ ] Implement `Money` in `src/core/money/money.ts`:
  - `fromMajor(value, currency, registry?)`: use `BigInt(Math.round(Number(value) * Number(multiplier)))` for number; use exact decimal-string parse for string inputs (no float intermediate).
  - All arithmetic: BigInt operations; throw `CurrencyMismatchError` on mismatched currencies.
  - `toDecimalString()`: format as exact decimal (e.g. `"12.34"` for USD with 2 minor units).
  - `toJSON()` / `Money.withRegistry(registry)`.
  - Negative-zero guard: ensure `0n` never becomes `-0n`.
- [ ] Write `money.test.ts` (≤500 lines): all operators, edge cases, currency mismatch, negative-zero, decimal-string round-trip.

## 5. Formatting + parse

- [ ] Implement `formatMoney`, `formatMoneyCompact`, `parseMoney` in `src/formatting/formatter/formatter.ts`.
- [ ] `parseMoney`: handle comma decimals, grouped separators, currency symbol removal via `Intl.NumberFormat`.
- [ ] Write `formatter.test.ts`: multiple locales, compact, parseMoney round-trip.

## 6. Allocation

- [ ] Implement all five allocators + `sumMoney` + `minMoney` + `maxMoney` + `applyRounding` in `src/allocation/allocator/allocator.ts`.
- [ ] Remainder redistribution: no minor unit lost or invented.
- [ ] Write `allocator.test.ts`: even/ratio/percentage edge cases, remainder, sum invariant.

## 7. MoneyRange

- [ ] Implement `MoneyRange` in `src/core/money-range/money-range.ts`: constructor validates `min <= max`; all methods per API surface.
- [ ] Write `money-range.test.ts`: contains, intersect (null on no overlap), union, toArray.

## 8. Zod schemas + serialization

- [ ] Implement `MoneyLikeSchema`, `CurrencyCodeSchema`, `FormatOptionsSchema` in `src/schemas/money-schemas/money-schemas.ts`.
- [ ] Implement `moneyToJSON` / `moneyFromJSON` in `src/serialization/json/json.ts`.
- [ ] Write tests for each.

## 9. Property-based tests

- [ ] `tests/property.test.ts` (fast-check, `{ timeout: 30000 }`):
  - `a + b - b = a` for arbitrary same-currency `Money` pairs.
  - `allocateEvenly(m, n)` sums to `m`.
  - `allocateByRatios(m, rs)` sums to `m`.
  - `toDecimalString` round-trip identity.
  - `parseMoney(formatMoney(m, locale), m.currency, locale)` equals `m` for common locales.
  - `MoneyRange` `intersect` is commutative and associative on overlapping ranges.

## 10. Docs + verify + publish

- [ ] All `.md` files per layout; root `README.md` with arithmetic quick-start, allocation example, MoneyRange, API table.
- [ ] `bunx turbo lint --filter=@suaveplan/money` — zero errors.
- [ ] `bunx turbo typecheck --filter=@suaveplan/money` — zero errors.
- [ ] `bunx turbo test --filter=@suaveplan/money` — all pass.
- [ ] `bunx turbo test:coverage --filter=@suaveplan/money` — 100%.
- [ ] `bun scripts/publish.ts --package @suaveplan/money`.
- [ ] Update `CLAUDE.md`; archive to `openspec/archive/2026-04-24-enterprise-money/`.