insurance.claim-reserve Unreviewed

def claim_reserve_history(transactions: Sequence[ClaimTransaction], currency: str) -> List[ReservePosition]

ClaimTransactionKind = Literal["reserve", "payment", "recovery"]

@dataclass(frozen=True)
class ClaimTransaction:
    """One event on a claim."""

    date: str
    #: reserve sets the outstanding estimate; payment pays; recovery brings money back
    kind: ClaimTransactionKind
    #: reserve: the new outstanding estimate, 0 or more; payment and recovery: more than 0
    amount: Money

@dataclass(frozen=True)
class ReservePosition:
    """The claim after one transaction."""

    date: str
    kind: ClaimTransactionKind
    #: paid to date
    paid: Money
    #: salvage and subrogation recovered to date
    recovered: Money
    #: the case reserve: what is still expected to be paid
    outstanding: Money
    #: paid minus recovered plus outstanding
    incurred: Money
    #: the change in incurred this transaction made
    movement: Money

from fune.insurance.claim_reserve import claim_reserve_history  # insurance.claim-reserve@^1

from typing import List, Optional, Sequence

from .dates_add_days import epoch_day_from_iso  ← from dates.add-days ^1.0.0 · built alongside by fune
from .insurance_claim_reserve_types import ClaimTransaction, ReservePosition
from .money_amount import assert_same_currency, money  ← from money.amount ^1.0.0 · built alongside by fune


def claim_reserve_history(transactions: Sequence[ClaimTransaction], currency: str) -> List[ReservePosition]:
    """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.
    """
    zero = money(0, currency)
    paid = 0
    recovered = 0
    outstanding = 0
    incurred = 0
    previous_day: Optional[int] = None
    previous_date = ""
    out: List[ReservePosition] = []
    for t in transactions:
        day = epoch_day_from_iso(t.date)
        if previous_day is not None and day < previous_day:
            raise ValueError("transactions must be in date order: %s comes after %s" % (t.date, previous_date))
        previous_day = day
        previous_date = t.date
        assert_same_currency(zero, t.amount)
        if t.kind == "reserve":
            if t.amount.minor < 0:
                raise ValueError("a reserve must not be negative, received %d on %s" % (t.amount.minor, t.date))
            outstanding = t.amount.minor
        elif t.kind in ("payment", "recovery"):
            if t.amount.minor <= 0:
                raise ValueError("a %s must be more than zero, received %d on %s" % (t.kind, t.amount.minor, t.date))
            if t.kind == "payment":
                paid += t.amount.minor
                outstanding = max(outstanding - t.amount.minor, 0)
            else:
                recovered += t.amount.minor
        else:
            raise ValueError('unknown transaction kind "%s": use reserve, payment or recovery' % (t.kind,))
        now = paid - recovered + outstanding
        out.append(
            ReservePosition(
                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 Python project (language python in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the Python 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 Python implementation. Install it without the registry with fune add ./insurance.claim-reserve-1.0.1-python.fune, or fetch it from a terminal with fune pull insurance.claim-reserve@1.0.1:python.

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