insurance.sum-insured-average Unreviewed

export function averageClauseSettlement(loss: Money, sumInsured: Money, valueAtRisk: Money, conditionBasisPoints: number, mode: RoundingMode): AverageSettlement

/** The payout after average and what the policyholder bears. */
export interface AverageSettlement {
  readonly payout: Money;
  readonly averageApplied: boolean;
  /** sum insured over value at risk, rounded down, at most 10000 */
  readonly insuredProportionBasisPoints: number;
  /** loss minus payout */
  readonly shortfall: Money;
}

import { averageClauseSettlement } from "#fune/insurance.sum-insured-average@^1";

import { type RoundingMode, roundDiv } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { type Money, assertSameCurrency, money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { type AverageSettlement } from "./insurance_sum_insured_average_types.ts";

/**
 * Settle a claim under an average clause.
 *
 * A property insured for less than it is worth is paid only the share of the
 * loss that the sum insured bears to the value at risk: insured for 75% of
 * its value, it is paid 75% of any loss. With a special condition of average
 * the clause only applies once the sum insured falls below that share of the
 * value. The payout never exceeds the loss or the sum insured.
 */
export function averageClauseSettlement(
  loss: Money,
  sumInsured: Money,
  valueAtRisk: Money,
  conditionBasisPoints: number,
  mode: RoundingMode
): AverageSettlement {
  assertSameCurrency(loss, sumInsured);
  assertSameCurrency(loss, valueAtRisk);
  if (valueAtRisk.minor <= 0) {
    throw new RangeError(`valueAtRisk must be more than zero, received ${valueAtRisk.minor}`);
  }
  if (loss.minor < 0) throw new RangeError(`loss must not be negative, received ${loss.minor}`);
  if (sumInsured.minor < 0) throw new RangeError(`sumInsured must not be negative, received ${sumInsured.minor}`);
  if (loss.minor > valueAtRisk.minor) throw new RangeError("loss must not exceed the value at risk");
  if (!Number.isInteger(conditionBasisPoints) || conditionBasisPoints < 1 || conditionBasisPoints > 10000) {
    throw new RangeError(`conditionBasisPoints must be from 1 to 10000, received ${conditionBasisPoints}`);
  }
  const averageApplied = sumInsured.minor * 10000 < valueAtRisk.minor * conditionBasisPoints;
  let payout = loss.minor;
  if (averageApplied) {
    // A loss and a sum insured in pence multiply past 2^53, so divide in bigint
    // and round the remainder the way roundDiv would.
    const wide = BigInt(loss.minor) * BigInt(sumInsured.minor);
    const value = BigInt(valueAtRisk.minor);
    payout = Number(wide / value) + roundDiv(Number(wide % value), valueAtRisk.minor, mode);
  }
  payout = Math.min(payout, loss.minor, sumInsured.minor);
  const c = loss.currency;
  return {
    payout: money(payout, c),
    averageApplied,
    insuredProportionBasisPoints: Math.min(roundDiv(sumInsured.minor * 10000, valueAtRisk.minor, "down"), 10000),
    shortfall: money(loss.minor - payout, c),
  };
}

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.sum-insured-average

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

The whole function, every language, is one file too: insurance.sum-insured-average-1.0.1.fune, 24,793 bytes, sha256 8e7b374a3bc1f1004bf949a8fbe45e47610e61258200987c46eb572ebace2363. It installs into a project of any language.

// fune: before insurance.sum-insured-average

// fune: after insurance.sum-insured-average

// fune: replace math.round-div in insurance.sum-insured-average
// fune: replace money.amount in insurance.sum-insured-average

// fune: step insurance.sum-insured-average after <n|label>

More from the author

So a building worth 200,000 insured for 150,000 (75%) is paid 30,000 on a 40,000 loss, not 40,000. The payout is never more than the loss (over- insurance does not pay a profit) or the sum insured (a total loss when underinsured pays the sum insured).

## The condition

`conditionBasisPoints` says when average applies at all:

- **10000**: pro rata average, whenever the sum insured is below the value. - **7500** (or 8500 and so on): a *special condition of average*, where average applies only if the sum insured is below that share of the value at risk; above it, losses are paid in full up to the sum insured. When it applies, it applies in the full proportion (sum insured / value), which is the usual UK wording. Some wordings instead scale by sum insured over the threshold value; that is a different clause and not this one.

The test is strict: insured for exactly 75% under a 75% condition is not below it, so no average.

## Details

- The payout rounds to the minor unit in the caller's mode. The product of a loss and a sum insured in pence can pass 2^53 (a 12,000,000.00 building), so it is divided exactly as a big integer (i128 in Rust) before rounding. - `insuredProportionBasisPoints` is sum insured over value at risk, rounded down and capped at 10000, for display ("insured for 83.33% of value"). - `valueAtRisk` is the full reinstatement (or market) value at the time of the loss, on whatever basis the policy says; the loss may not exceed it. - Apply the excess with `insurance.excess-apply`; whether the excess comes off before or after average is a matter of the policy wording.

## 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