Financial Integrity

In the "Action Era", LivestockAI agents may autonomously propose sales or analyze profit. Trust is our currency. Calculations must be mathematically provable.

Core Principle: The "Penny Perfect" Rule

All financial storage and calculation must treat money as an integer (minor units) or high-precision decimal. NEVER use standard generic

number

floating point math for money.

1. Storage Standards

Database:

DECIMAL(19, 4)

for unit prices (allows for precise small-unit costs like feed per gram).

DECIMAL(19, 2)

for final transaction amounts (invoices, payments).

TypeScript: Always use

decimal.js

via the project's currency utilities.

// ❌ Dangerous
const total = 0.1 + 0.2 // 0.30000000000000004

// ✅ Safe
import { add } from '~/features/settings/currency'
const total = add(0.1, 0.2) // Decimal(0.3)

2. Invariant Testing (Property Tests)

Use

fast-check

to prove financial laws hold true for all inputs.

Profit Law

Profit = Revenue - (COGS + Expenses)

test('Profit Invariant', () => {
  fc.assert(
    fc.property(fc.integer(), fc.integer(), (revenue, cost) => {
      const profit = calculateProfit(revenue, cost)
      // Profit + Cost must always exactly equal Revenue
      return profit.add(cost).equals(revenue)
    }),
  )
})

Allocation Law

When splitting a cost across N batches, the sum of parts must equal the total. Watch out for rounding leftovers.

Pattern: The "Penny Allocate" Algorithm If splitting $100 among 3 batches: Batch 1: $33.33 Batch 2: $33.33 Batch 3: $33.34 (Takes the remainder)

3. Immutability

Financial records (

invoices

,

sales

,

expenses

) should be "Append-Only" to the user. If a mistake is made:

1. Create a Reversal Transaction (negative amount) to void the error.
2. Create a new Correct Transaction. This preserves the audit trail.

4. Multi-Currency Safety

Always store

exchangeRate

and

currencyCode

at the time of transaction. Never calculate historical value using current exchange rates.

Related Skills

• financial-calculations

  - The specific library calls implementation

• property-testing

  - The value verification method