fix: PR D — decimal.js migration across monetary math (round 4, bug 11) (#81)

Replace float arithmetic on monetary values with decimal.js operating on
Drizzle's string numeric representation. Round only at persist/display boundary.

Primary fix (Bug 11): tax engine
- calculateTaxes compound base: runningBase.plus(rounded) exact each step
- backCalculateFromInclusive: gross / (1 + rate) now bit-exact
- Percentage rate application Decimal-safe

Full sweep — 11 business-logic files:
- folio.service (reversal/negation, tax charge reversal)
- payment.service (gateway amount, partial-refund idempotency key stability)
- reservation.service (120% deposit, express-checkout balance guard)
- reports.service (daily/financial/trend aggregation, ADR, RevPAR)
- night-audit.service (totalRoom/totalTax, ADR, RevPAR)
- connect-booking/search/insights.service (rate shopping, nightly breakdown,
  cancellation first-night penalty sums to totalAmount exactly)
- channel/ari.service + rate-parity.service (override percentage math exact)

parseFloat instances: 44 → 19 (25 removed). Remaining 19 intentionally kept:
- tests (6), statistical/ML agent inputs (9), OTA XML boundary parsers (2),
  confidence probabilities (2). Documented by decision rule.

562/562 tests pass unchanged — existing tax assertions lived in float-safe
zone; Decimal output matched at 2-decimal precision.

Co-authored-by: Dušan Milićević <dusanmilicevic33@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: telivity-otaip

apps/api/src/modules/channel/ari.service.ts

@@ -1,6 +1,7 @@
 import { Injectable, Inject } from '@nestjs/common';
 import { OnEvent } from '@nestjs/event-emitter';
 import { eq, and } from 'drizzle-orm';
+import Decimal from 'decimal.js';
 import { ariSyncLogs, ratePlans, rateRestrictions } from '@haip/database';
 import { DRIZZLE } from '../../database/database.module';
 import { ChannelAdapterFactory } from './channel-adapter.factory';
@@ -166,7 +167,7 @@ export class AriService {
         const end = new Date(endDate);
         for (let d = new Date(start); d <= end; d.setDate(d.getDate() + 1)) {
           const dateStr = d.toISOString().split('T')[0]!;
-          const baseRate = parseFloat(ratePlan.baseAmount);
+          const baseRate = new Decimal(ratePlan.baseAmount).toNumber();
 
           rateItems.push({
             channelRoomCode: roomMapping.channelRoomCode,

apps/api/src/modules/channel/rate-parity.service.ts

@@ -1,5 +1,6 @@
 import { Injectable, Inject } from '@nestjs/common';
 import { eq, and, gte, lte } from 'drizzle-orm';
+import Decimal from 'decimal.js';
 import { ratePlans, channelConnections } from '@haip/database';
 import { DRIZZLE } from '../../database/database.module';
 
@@ -65,7 +66,7 @@ export class RateParityService {
     const results: RateParityResult[] = [];
 
     for (const plan of plans) {
-      const baseAmount = parseFloat(plan.baseAmount);
+      const baseAmount = new Decimal(plan.baseAmount).toNumber();
       const channels: RateParityResult['channels'] = [];
       let parityViolations = 0;
 
@@ -83,16 +84,16 @@ export class RateParityService {
         const overrides = (config['rateOverrides'] as RateOverride[] | undefined) ?? [];
         const override = overrides.find((o) => o.ratePlanId === plan.id);
 
-        let effectiveRate = baseAmount;
+        let effectiveRateDec = new Decimal(baseAmount);
         let hasOverride = false;
 
         if (override) {
           hasOverride = true;
-          effectiveRate = this.applyOverride(baseAmount, override);
+          effectiveRateDec = this.applyOverrideDecimal(effectiveRateDec, override);
         }
 
-        const variance = Math.abs(effectiveRate - baseAmount);
-        const isParity = variance < 0.01; // Within 1 cent tolerance
+        const varianceDec = effectiveRateDec.minus(baseAmount).abs();
+        const isParity = varianceDec.lt('0.01'); // Within 1 cent tolerance
 
         if (!isParity) {
           parityViolations++;
@@ -103,10 +104,10 @@ export class RateParityService {
           channelCode: conn.channelCode,
           channelName: conn.channelName,
           channelRateCode: mapping.channelRateCode,
-          effectiveRate: Math.round(effectiveRate * 100) / 100,
+          effectiveRate: Number(effectiveRateDec.toFixed(2)),
           hasOverride,
           isParity,
-          variance: Math.round(variance * 100) / 100,
+          variance: Number(varianceDec.toFixed(2)),
         });
       }
 
@@ -152,10 +153,11 @@ export class RateParityService {
       );
 
     if (!conn) {
-      return { baseAmount: parseFloat(plan.baseAmount), effectiveRate: parseFloat(plan.baseAmount), hasOverride: false };
+      const base = new Decimal(plan.baseAmount).toNumber();
+      return { baseAmount: base, effectiveRate: base, hasOverride: false };
     }
 
-    const baseAmount = parseFloat(plan.baseAmount);
+    const baseAmount = new Decimal(plan.baseAmount).toNumber();
     const config = (conn.config ?? {}) as Record<string, unknown>;
     const overrides = (config['rateOverrides'] as RateOverride[] | undefined) ?? [];
 
@@ -166,10 +168,10 @@ export class RateParityService {
       return { baseAmount, effectiveRate: baseAmount, hasOverride: false };
     }
 
-    const effectiveRate = this.applyOverride(baseAmount, applicableOverride);
+    const effectiveRateDec = this.applyOverrideDecimal(new Decimal(baseAmount), applicableOverride);
     return {
       baseAmount,
-      effectiveRate: Math.round(effectiveRate * 100) / 100,
+      effectiveRate: Number(effectiveRateDec.toFixed(2)),
       hasOverride: true,
       override: applicableOverride,
     };
@@ -271,11 +273,17 @@ export class RateParityService {
   // --- Private Helpers ---
 
   private applyOverride(baseAmount: number, override: RateOverride): number {
+    return this.applyOverrideDecimal(new Decimal(baseAmount), override).toNumber();
+  }
+
+  // Decimal-safe override math — preferred internally to avoid float drift on
+  // percentage adjustments (e.g. 10% of 127.35 drifts under JS multiply).
+  private applyOverrideDecimal(baseAmount: Decimal, override: RateOverride): Decimal {
     if (override.adjustmentType === 'percentage') {
-      return baseAmount * (1 + override.adjustmentValue / 100);
+      return baseAmount.times(new Decimal(1).plus(new Decimal(override.adjustmentValue).div(100)));
     }
     // Fixed adjustment
-    return baseAmount + override.adjustmentValue;
+    return baseAmount.plus(override.adjustmentValue);
   }
 
   private findApplicableOverride(

apps/api/src/modules/connect/connect-booking.service.ts

@@ -1,5 +1,6 @@
 import { Injectable, Inject, NotFoundException, BadRequestException } from '@nestjs/common';
 import { eq, and } from 'drizzle-orm';
+import Decimal from 'decimal.js';
 import { bookings, reservations, guests, ratePlans, roomTypes, folios, rooms } from '@haip/database';
 import { DRIZZLE } from '../../database/database.module';
 import { AvailabilityService } from '../reservation/availability.service';
@@ -60,8 +61,11 @@ export class ConnectBookingService {
     const arrival = new Date(dto.checkIn);
     const departure = new Date(dto.checkOut);
     const nights = Math.ceil((departure.getTime() - arrival.getTime()) / (1000 * 60 * 60 * 24));
-    const baseAmount = parseFloat(ratePlan.baseAmount);
-    const totalAmount = baseAmount * nights;
+    // Monetary math via Decimal (baseAmount is a numeric string from PG)
+    const baseAmountDec = new Decimal(ratePlan.baseAmount);
+    const totalAmountDec = baseAmountDec.times(nights);
+    const baseAmount = baseAmountDec.toNumber();
+    const totalAmount = totalAmountDec.toNumber();
 
     // 5. Generate confirmation number
     const confirmationNumber = `HAIP-${Date.now().toString(36).toUpperCase()}-${randomUUID().slice(0, 4).toUpperCase()}`;
@@ -91,7 +95,7 @@ export class ConnectBookingService {
         nights,
         roomTypeId: dto.roomTypeId,
         ratePlanId: dto.ratePlanId,
-        totalAmount: totalAmount.toString(),
+        totalAmount: totalAmountDec.toFixed(2),
         currencyCode: ratePlan.currencyCode,
         adults: dto.adults,
         children: dto.children ?? 0,
@@ -209,12 +213,12 @@ export class ConnectBookingService {
       checkIn: reservation.arrivalDate,
       checkOut: reservation.departureDate,
       roomType: roomType?.name ?? 'Unknown',
-      rateAmount: parseFloat(reservation.totalAmount),
+      rateAmount: new Decimal(reservation.totalAmount).toNumber(),
       currencyCode: reservation.currencyCode,
       roomAssigned: !!reservation.roomId,
       roomNumber,
       folioExists: !!folio,
-      folioBalance: folio ? parseFloat(folio.balance) : undefined,
+      folioBalance: folio ? new Decimal(folio.balance).toNumber() : undefined,
       lastModified: reservation.updatedAt?.toISOString() ?? reservation.createdAt.toISOString(),
       verifiedAt: new Date().toISOString(),
     };
@@ -247,8 +251,9 @@ export class ConnectBookingService {
     }
 
     const updateFields: Record<string, any> = { updatedAt: new Date() };
-    let costDifference = 0;
-    const previousAmount = parseFloat(reservation.totalAmount);
+    let costDifferenceDec = new Decimal(0);
+    const previousAmountDec = new Decimal(reservation.totalAmount);
+    const previousAmount = previousAmountDec.toNumber();
 
     // Handle guest detail updates
     if (dto.guestFirstName || dto.guestLastName) {
@@ -302,17 +307,17 @@ export class ConnectBookingService {
       const arrival = new Date(newCheckIn);
       const departure = new Date(newCheckOut);
       const nights = Math.ceil((departure.getTime() - arrival.getTime()) / (1000 * 60 * 60 * 24));
-      const newTotal = parseFloat(ratePlan.baseAmount) * nights;
+      const newTotalDec = new Decimal(ratePlan.baseAmount).times(nights);
 
       updateFields['arrivalDate'] = newCheckIn;
       updateFields['departureDate'] = newCheckOut;
       updateFields['nights'] = nights;
       updateFields['roomTypeId'] = newRoomTypeId;
       updateFields['ratePlanId'] = newRatePlanId;
-      updateFields['totalAmount'] = newTotal.toString();
+      updateFields['totalAmount'] = newTotalDec.toFixed(2);
       updateFields['currencyCode'] = ratePlan.currencyCode;
 
-      costDifference = newTotal - previousAmount;
+      costDifferenceDec = newTotalDec.minus(previousAmountDec);
     }
 
     // Apply update
@@ -336,9 +341,9 @@ export class ConnectBookingService {
       confirmationNumber,
       reservationId: reservation.id,
       status: updated.status,
-      previousAmount: Math.round(previousAmount * 100) / 100,
-      newAmount: Math.round(parseFloat(updated.totalAmount) * 100) / 100,
-      costDifference: Math.round(costDifference * 100) / 100,
+      previousAmount: Number(previousAmountDec.toFixed(2)),
+      newAmount: Number(new Decimal(updated.totalAmount).toFixed(2)),
+      costDifference: Number(costDifferenceDec.toFixed(2)),
       modifiedAt: new Date().toISOString(),
     };
   }
@@ -454,15 +459,16 @@ export class ConnectBookingService {
     taxRate: number,
   ) {
     const breakdown = [];
+    const baseAmountDec = new Decimal(baseAmount);
+    const taxPerNightDec = baseAmountDec.times(taxRate).div(100);
     for (let i = 0; i < nights; i++) {
       const date = new Date(arrival);
       date.setDate(date.getDate() + i);
       const dateStr = date.toISOString().split('T')[0]!;
-      const tax = baseAmount * (taxRate / 100);
       breakdown.push({
         date: dateStr,
-        rate: Math.round(baseAmount * 100) / 100,
-        tax: Math.round(tax * 100) / 100,
+        rate: Number(baseAmountDec.toFixed(2)),
+        tax: Number(taxPerNightDec.toFixed(2)),
       });
     }
     return breakdown;
@@ -476,7 +482,9 @@ export class ConnectBookingService {
   }
 
   private calculateCancellationPenalty(ratePlan: any, reservation: any) {
-    const totalAmount = parseFloat(reservation.totalAmount);
+    // Money math via Decimal; refundAmount / penaltyAmount are displayed as currency
+    const totalAmountDec = new Decimal(reservation.totalAmount);
+    const totalAmount = totalAmountDec.toNumber();
 
     // Non-refundable rate
     if (ratePlan?.type === 'promotional') {
@@ -504,11 +512,11 @@ export class ConnectBookingService {
 
     // First night penalty
     const nights = reservation.nights || 1;
-    const firstNightAmount = totalAmount / nights;
+    const firstNightAmountDec = totalAmountDec.div(nights);
     return {
       penaltyApplied: true,
-      penaltyAmount: Math.round(firstNightAmount * 100) / 100,
-      refundAmount: Math.round((totalAmount - firstNightAmount) * 100) / 100,
+      penaltyAmount: Number(firstNightAmountDec.toFixed(2)),
+      refundAmount: Number(totalAmountDec.minus(firstNightAmountDec).toFixed(2)),
       policyDescription: 'First night charge applies — cancelled within 24 hours of check-in.',
     };
   }

apps/api/src/modules/connect/connect-insights.service.ts

@@ -1,5 +1,6 @@
 import { Injectable, Inject } from '@nestjs/common';
 import { eq, and, sql, gte, lte } from 'drizzle-orm';
+import Decimal from 'decimal.js';
 import {
   properties,
   reservations,
@@ -47,14 +48,15 @@ export class ConnectInsightsService {
     const roomsAvailable = Math.max(0, totalRooms - roomsSold);
     const occupancyRate = totalRooms > 0 ? (roomsSold / totalRooms) * 100 : 0;
 
-    // Calculate ADR
-    const totalRevenue = soldReservations.reduce((sum: number, r: any) => {
-      const amount = parseFloat(r.totalAmount) || 0;
+    // Calculate ADR via Decimal — displayed as currency
+    const totalRevenueDec = soldReservations.reduce((sum: Decimal, r: any) => {
+      const amount = r.totalAmount ? new Decimal(r.totalAmount) : new Decimal(0);
       const nights = r.nights || 1;
-      return sum + (amount / nights);
-    }, 0);
-    const adr = roomsSold > 0 ? totalRevenue / roomsSold : 0;
-    const revpar = totalRooms > 0 ? totalRevenue / totalRooms : 0;
+      return sum.plus(amount.div(nights));
+    }, new Decimal(0));
+    const totalRevenue = totalRevenueDec.toNumber();
+    const adr = roomsSold > 0 ? totalRevenueDec.div(roomsSold).toNumber() : 0;
+    const revpar = totalRooms > 0 ? totalRevenueDec.div(totalRooms).toNumber() : 0;
 
     // Count today's new reservations and cancellations
     const reservationsToday = await this.db
@@ -103,7 +105,7 @@ export class ConnectInsightsService {
       roomsSold,
       reservationsToday: Number(reservationsToday[0]?.count ?? 0),
       cancellationsToday: Number(cancellationsToday[0]?.count ?? 0),
-      currentBarRate: barRate ? parseFloat(barRate.baseAmount) : 0,
+      currentBarRate: barRate ? new Decimal(barRate.baseAmount).toNumber() : 0,
       barRatePlanId: barRate?.id,
       suggestions,
     };

apps/api/src/modules/connect/connect-search.service.ts

@@ -1,5 +1,6 @@
 import { Injectable, Inject } from '@nestjs/common';
 import { eq, and, gte, lte } from 'drizzle-orm';
+import Decimal from 'decimal.js';
 import { properties, roomTypes, ratePlans, rateRestrictions } from '@haip/database';
 import { DRIZZLE } from '../../database/database.module';
 import { AvailabilityService } from '../reservation/availability.service';
@@ -270,7 +271,7 @@ export class ConnectSearchService {
     checkOut: string,
     taxRate: number,
   ) {
-    const baseAmount = parseFloat(plan.baseAmount);
+    const baseAmount = new Decimal(plan.baseAmount).toNumber();
 
     // Get restrictions for the date range
     const restrictions = await this.db
@@ -307,34 +308,36 @@ export class ConnectSearchService {
     if (minLos && nights < minLos) return null;
     if (maxLos && maxLos !== Infinity && nights > maxLos) return null;
 
-    // Build nightly breakdown
+    // Build nightly breakdown — Decimal for all per-night money math
     const nightlyBreakdown = [];
-    let totalAmount = 0;
+    let totalAmountDec = new Decimal(0);
+    const taxRateDec = new Decimal(taxRate).div(100);
     for (let i = 0; i < nights; i++) {
       const date = new Date(arrival);
       date.setDate(date.getDate() + i);
       const dateStr = date.toISOString().split('T')[0]!;
 
       // Check for day-of-week overrides
       const dayName = date.toLocaleDateString('en-US', { weekday: 'long' }).toLowerCase();
-      let nightRate = baseAmount;
+      let nightRateDec = new Decimal(baseAmount);
 
       for (const restriction of restrictions) {
         const overrides = (restriction.dayOfWeekOverrides ?? {}) as Record<string, number>;
         if (overrides[dayName]) {
-          nightRate = baseAmount + overrides[dayName]!;
+          nightRateDec = new Decimal(baseAmount).plus(overrides[dayName]!);
         }
       }
 
-      const taxAmount = nightRate * (taxRate / 100);
+      const taxAmountDec = nightRateDec.times(taxRateDec);
       nightlyBreakdown.push({
         date: dateStr,
-        baseRate: Math.round(nightRate * 100) / 100,
-        taxAmount: Math.round(taxAmount * 100) / 100,
-        totalRate: Math.round((nightRate + taxAmount) * 100) / 100,
+        baseRate: Number(nightRateDec.toFixed(2)),
+        taxAmount: Number(taxAmountDec.toFixed(2)),
+        totalRate: Number(nightRateDec.plus(taxAmountDec).toFixed(2)),
       });
-      totalAmount += nightRate + taxAmount;
+      totalAmountDec = totalAmountDec.plus(nightRateDec).plus(taxAmountDec);
     }
+    const totalAmount = Number(totalAmountDec.toFixed(2));
 
     // Build cancellation policy
     const cancellationPolicy = this.buildCancellationPolicy(plan);
@@ -344,7 +347,7 @@ export class ConnectSearchService {
       ratePlanName: plan.name,
       ratePlanCode: plan.code,
       rateType: plan.type,
-      totalAmount: Math.round(totalAmount * 100) / 100,
+      totalAmount,
       currencyCode: plan.currencyCode,
       nightlyBreakdown,
       cancellationPolicy,

apps/api/src/modules/folio/folio.service.ts

@@ -107,7 +107,7 @@ export class FolioService {
     if (folio.status !== 'open') {
       throw new BadRequestException('Folio is not open');
     }
-    if (Math.abs(parseFloat(folio.balance)) > 0.01) {
+    if (new Decimal(folio.balance).abs().gt('0.01')) {
       throw new BadRequestException(
         `Folio balance must be zero to settle (current: ${folio.balance})`,
       );
@@ -390,8 +390,8 @@ export class FolioService {
       throw new BadRequestException('Charge has already been reversed');
     }
 
-    const negatedAmount = (parseFloat(original.amount) * -1).toFixed(2);
-    const negatedTax = (parseFloat(original.taxAmount) * -1).toFixed(2);
+    const negatedAmount = new Decimal(original.amount).negated().toFixed(2);
+    const negatedTax = new Decimal(original.taxAmount).negated().toFixed(2);
 
     const [reversal] = await this.db
       .insert(charges)
@@ -440,7 +440,7 @@ export class FolioService {
           folioId,
           type: 'tax',
           description: `Reversal: ${taxCharge.description}`,
-          amount: (parseFloat(taxCharge.amount) * -1).toFixed(2),
+          amount: new Decimal(taxCharge.amount).negated().toFixed(2),
           currencyCode: taxCharge.currencyCode,
           taxAmount: '0',
           taxRate: taxCharge.taxRate,