money-math-invariants

Files (1)

• SKILL.md

SKILL.md (first lines)

# Money Math Invariants

This skill codifies **6 money-math invariants** whose violation produces bugs like "profit shows $498,669", "'—' in the payment history", or "the AI tells the user they paid $9.90 instead of $990".

Each invariant is a **class of bug** that a typecheck does not catch, because the violation happens at a seam: name ↔ unit, Prisma ↔ JSON, frontend ↔ backend, seed ↔ schema.

> The convention below uses a currency suffix to encode the unit in the field name: `*Dollars` holds a major unit, `*Cents` holds a minor unit (1/100). Substitute your own currency, but keep the principle — **the name must not lie about the unit.**

## When to activate

Any edit to a file in one of these zones:

- payment / checkout service modules
- admin billing / billing-adjustment services
- LLM/agent data-source files that surface billing context
- shared billing/pricing type packages
- admin billing pages, organization/user detail pages
- account billing settings pages, public pricing page
- database seed scripts and one-off migration/update scripts

## The 6 invariants

### Invariant 1: "Field name = unit of its contents"

**Rule:** if a field is named `*Dollars` it stores dollars; if `*Cents` it stores cents. **The name must not lie about the unit.**

**Example violation:**
```ts
// schema.prisma
model Plan {
  priceMonthlyDollars  Int  // ← name says "Dollars", but it stored 499000 (cents) for $4990
}
```

**Check:** for every `*Dollars` field — contents × 1.0 = dollars (not × 0.01 = cents divided by 100).

**How to verify:** a runtime test with sample values + a grep for `*Cents` in any DTO that flows to the UI.

### Invariant 2: "Decimal does not go into JSON directly"

**Rule:** the Prisma `Decimal` type is a `Prisma.Decimal` object (a Decimal.js wrapper). When serialized to JSON it becomes `{d:[4990],e:3,s:1}` or a string `"4990"`, **not a number**. The frontend expects a number → gets garbage.

**Example violation:**
```ts
// billing.service.ts
return {
  amountDollars: p.amount,  // ← Decimal object, not number. Frontend receives {d:[4990]...}
};
```

**Correct:**
```ts
return {
  amountDollars: p.amount.toNumber(),  // ← number
};
```

**Check:** for every `prisma.X.findMany().select(...)` where the select contains a money field — the DTO map must call `.toNumber()` on it.

**Grep:**
```bash
# Find Decimal money fields without .toNumber():
grep -rn "amount\b\|priceMonthlyDollars\b\|unitPriceDollars\b\|amountDollars\b" \
  src --include="*.ts" | grep -v ".spec.ts" | grep -v ".toNumber()"
```

### Invariant 3: "No `/100` in the UI layer"

**Rule:** the frontend never divides by 100. The cents↔dollars conversion happens **only at the API boundary** (Prisma read/write in the backend). The UI receives dollars as a ready `number`.

**Example violation:**
```tsx
// organizations/[id]/page.tsx
Math.round(s.plan.priceMonthlyDollars / 100)  // ← /100 in UI, divides twice
```

**Correct:**
```tsx
s.plan.priceMonthlyDollars  // ← already dollars, no /100
```

**Check:** `grep -rn "/ 100\|/100\b" web/ --include="*.tsx" --include="*.ts" | grep -v ".next"` — results must not contain money-related variables (`amount`, `price`, `cost`, `*Dollars`, `*Cents`).

**Exception:** percentages (`discount / 100 * 100`) are OK.

### Invariant 4: "Frontend ↔ backend DTO names match"

**Rule:** the field name in the backend DTO interface = the field name in the frontend type. If the backend sends `amount`, the frontend must read `amount` (not `amountDollars`).

**Example violation:**
```ts
// backend: SerialisedPayment.amount: number
// frontend: BillingPortalState.payments[].amountDollars: number
// → frontend reads amountDollars → undefined → "—" in UI
```

**Check:** for every admin/account/public endpoint, diff the type in shared-types VS the type in the frontend API client VS the interface in the backend service.

A name mismatch is a BLOCKER, not cosmetic. Prefer converging on one name on either side (ideally `*Dollars` for money, with the unit in the name).

### Invariant 5: "Seed scripts use the same units as the schema"

**Rule:** values in seed and one-off migration scripts must match the current type in the schema. After a rename `Int (cents) → Decimal (dollars)`, seed values change `99000 → 990`.

**Example violation:**
```ts
// seed.ts (after the migration but without updating seed)
{ slug: "personal-start", priceMonthlyDollars: 99000 }  // ← now this is $99,000, not $990
```

**Correct:**
```ts
{ slug: "personal-start", priceMonthlyDollars: 990 }  // ← dollars, as in schema
```

**Check:** on any money-field rename in schema — `grep -rn "<fieldName>" prisma/` and walk every occurrence.

**Especially dangerous:** seed scripts are often **outside tsconfig** → typecheck does not see them. They only fail on `db:seed` against a clean DB, usually weeks after the schema change.

### Invariant 6: "LLM context = real units"

From signalo-rust/agent-guardrails, MIT.

More from signalo-rust/agent-guardrails