Architecture [Needs Review]: Integer minor-unit Money foundation (main/core/money.ts)

[khaira777]

Important

Status: Needs Architectural Review
This issue outlines a proposed core architectural change. It requires technical review and approval before deciding whether to implement or adopt.

Extracted from fork richanonymous22/FloCafe (branch: claude/plemmo-epos-audit-fro8v9):

Overview

Replace floating-point currency math in standard JavaScript numbers (0.1 + 0.2 = 0.30000000000000004) with a deterministic, integer-minor-unit Money library (main/core/money.ts).

Key Features & Technical Details

1. Integer Minor-Unit Storage:
   • Stores all monetary values in minor units (e.g. cents, pence, paise: $19.99 = 1999).
2. Banker’s Rounding (ROUND_HALF_EVEN):
   • Uses standard accounting Banker’s Rounding on exact halves to eliminate systemic upward rounding bias over large volumes of sales.
3. Penny-Safe split() Distribution:
   • Safely divides totals without penny-loss discrepancies (e.g. splitting $10.00 three ways yields [$3.34, $3.33, $3.33] totaling $10.00 exactly).
4. Reference Implementation:
   • main/core/money.ts & tests/plemmo-money.test.ts.

[khaira777]

Verdict: VALID BUT NEEDS RESCOPING (architecture review warranted)

Findings:

• Money is stored as REAL floats (main/db.ts:4015 price REAL; order/bill totals :4166-4205 REAL) and manipulated with JS numbers in places — the float-drift concern is real.
• The tax engine already uses decimal.js with configurable rounding including half_even (main/services/tax-engine.ts:10, :117-118; main/tax-packs/types.ts:3 RoundingMethod), and penny-safe split math with minor-unit rounding + remainder distribution already exists (main/routes/bills.ts:96-99, :175, :548-556).

Suggested scope: don't replace every money path with a library in one change. Start with (a) minor-unit conversion at persistence/calculation boundaries (store cents as INTEGER or round at write via Decimal), (b) centralize rounding/split helpers by reusing the existing bills.ts math, (c) a reconciliation test. Maintainer decision needed on how far to take it (full library vs boundary-only). Related: #282 (tender service), #280 (REAL stock_quantity), #278.