captjay98/Financial Integrity

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