insurance.claim-reserve Unreviewed

export function claimReserveHistory(transactions: readonly ClaimTransaction[], currency: string): readonly ReservePosition[]

export type ClaimTransactionKind = "reserve" | "payment" | "recovery";

/** One event on a claim. */
export interface ClaimTransaction {
  readonly date: string;
  /** reserve sets the outstanding estimate; payment pays; recovery brings money back */
  readonly kind: ClaimTransactionKind;
  /** reserve: the new outstanding estimate, 0 or more; payment and recovery: more than 0 */
  readonly amount: Money;
}

/** The claim after one transaction. */
export interface ReservePosition {
  readonly date: string;
  readonly kind: ClaimTransactionKind;
  /** paid to date */
  readonly paid: Money;
  /** salvage and subrogation recovered to date */
  readonly recovered: Money;
  /** the case reserve: what is still expected to be paid */
  readonly outstanding: Money;
  /** paid minus recovered plus outstanding */
  readonly incurred: Money;
  /** the change in incurred this transaction made */
  readonly movement: Money;
}

import { claimReserveHistory } from "#fune/insurance.claim-reserve@^1";

import { epochDayFromIso } from "./dates_add_days.ts";  ← from dates.add-days ^1.0.0 · built alongside by fune
import { assertSameCurrency, money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { type ClaimTransaction, type ReservePosition } from "./insurance_claim_reserve_types.ts";

/**
 * A claim's position after each transaction: paid, recovered, the outstanding
 * case reserve, and incurred = paid - recovered + outstanding.
 *
 * A payment erodes the outstanding reserve by what it pays, never below zero:
 * a payment larger than the reserve raises incurred by the excess, which is
 * how an under-reserved claim shows up. A reserve transaction sets the
 * outstanding estimate outright. The movement is what each transaction did to
 * incurred, the figure that goes through the accounts.
 */
export function claimReserveHistory(transactions: readonly ClaimTransaction[], currency: string): readonly ReservePosition[] {
  const zero = money(0, currency);
  let paid = 0;
  let recovered = 0;
  let outstanding = 0;
  let incurred = 0;
  let previousDay: number | null = null;
  let previousDate = "";
  const out: ReservePosition[] = [];
  for (const t of transactions) {
    const day = epochDayFromIso(t.date);
    if (previousDay !== null && day < previousDay) {
      throw new RangeError(`transactions must be in date order: ${t.date} comes after ${previousDate}`);
    }
    previousDay = day;
    previousDate = t.date;
    assertSameCurrency(zero, t.amount);
    if (t.kind === "reserve") {
      if (t.amount.minor < 0) {
        throw new RangeError(`a reserve must not be negative, received ${t.amount.minor} on ${t.date}`);
      }
      outstanding = t.amount.minor;
    } else if (t.kind === "payment" || t.kind === "recovery") {
      if (t.amount.minor <= 0) {
        throw new RangeError(`a ${t.kind} must be more than zero, received ${t.amount.minor} on ${t.date}`);
      }
      if (t.kind === "payment") {
        paid += t.amount.minor;
        outstanding = Math.max(outstanding - t.amount.minor, 0);
      } else {
        recovered += t.amount.minor;
      }
    } else {
      throw new RangeError(`unknown transaction kind "${t.kind}": use reserve, payment or recovery`);
    }
    const now = paid - recovered + outstanding;
    out.push({
      date: t.date,
      kind: t.kind,
      paid: money(paid, currency),
      recovered: money(recovered, currency),
      outstanding: money(outstanding, currency),
      incurred: money(now, currency),
      movement: money(now - incurred, currency),
    });
    incurred = now;
  }
  return out;
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add insurance.claim-reserve

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./insurance.claim-reserve-1.0.1-typescript.fune, or fetch it from a terminal with fune pull insurance.claim-reserve@1.0.1:typescript.

The whole function, every language, is one file too: insurance.claim-reserve-1.0.1.fune, 28,921 bytes, sha256 36fadf22a15bc9a0a8ff4a780f9c86d616fdf776b90d5c8689674c66f2246539. It installs into a project of any language.

// fune: before insurance.claim-reserve

// fune: after insurance.claim-reserve

// fune: replace dates.add-days in insurance.claim-reserve
// fune: replace money.amount in insurance.claim-reserve

// fune: step insurance.claim-reserve after <n|label>

More from the author

## Transactions

- **reserve**: the claims handler's new estimate of what is still to be paid. It sets `outstanding` outright (0 closes the claim or releases the reserve). - **payment**: money paid out. It adds to `paid` and erodes `outstanding` by the same amount, never below zero. A payment within the reserve therefore leaves incurred unchanged; one larger than the reserve raises incurred by the difference, which is how an under-reserved claim shows up. - **recovery**: salvage, subrogation or third-party recoveries received. They reduce net incurred. A claim recovered in full with costs can show negative incurred.

`movement` is the change in incurred made by each transaction: the figure that goes through the claims account for the period, and what a development triangle is built from. Summing the movements in a period gives that period's incurred movement.

Transactions must be in date order; same-day transactions keep the order given, so a payment and the reserve change that follows it on one day come out as two positions. Dates are checked as real calendar dates.

Not covered: IBNR and other reserves not held against a specific claim, reserve currency conversion, and claims handling expenses (pass them as payments if your reporting counts them in incurred).

## Before you rely on this

**Not professional advice.** This capability calculates insurance figures from published rules. It is a software component for developers, not financial advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have an actuary review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified actuary has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed. The code and the tests are unchanged.

Files