@actuarial-ts/core 0.1.0

package/dist/onlevel.js

@@ -0,0 +1,104 @@
+import { ReservingError } from "./types.js";
+import { isNum } from "./util.js";
+/** ISO date -> fractional year (2021-07-01 -> ~2021.5). */
+function dateToYearFraction(iso) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(iso);
+    if (!m) {
+        throw new ReservingError("BAD_DATE", `Not an ISO date: ${iso}`);
+    }
+    const year = Number(m[1]);
+    const start = Date.UTC(year, 0, 1);
+    const next = Date.UTC(year + 1, 0, 1);
+    const t = Date.UTC(year, Number(m[2]) - 1, Number(m[3]));
+    return year + (t - start) / (next - start);
+}
+/** Origin label -> [start, end) in fractional years ("2021" or "2021Q3"). */
+function originInterval(origin) {
+    const year = Number(origin.slice(0, 4));
+    if (!Number.isInteger(year)) {
+        throw new ReservingError("BAD_ORIGIN", `Cannot parse an origin period from "${origin}"`);
+    }
+    const qMatch = /Q([1-4])$/.exec(origin);
+    if (qMatch) {
+        const q = Number(qMatch[1]);
+        return [year + (q - 1) / 4, year + q / 4];
+    }
+    return [year, year + 1];
+}
+/**
+ * Earned-premium density of the period [p0, p1) by policy WRITTEN time w:
+ * overlap of the earning interval [w, w+1] with [p0, p1). Integrated exactly
+ * over [a, b] (the density is piecewise linear with breakpoints at p0-1,
+ * p1-1, p0, p1).
+ */
+function earnedArea(p0, p1, a, b) {
+    const lo = Math.max(a, p0 - 1);
+    const hi = Math.min(b, p1);
+    if (hi <= lo)
+        return 0;
+    const density = (w) => Math.max(0, Math.min(p1, w + 1) - Math.max(p0, w));
+    // Integrate exactly across the linear segments.
+    const breaks = [p0 - 1, p1 - 1, p0, p1]
+        .filter((x) => x > lo && x < hi)
+        .sort((x, y) => x - y);
+    const knots = [lo, ...breaks, hi];
+    let area = 0;
+    for (let i = 0; i + 1 < knots.length; i++) {
+        const x0 = knots[i];
+        const x1 = knots[i + 1];
+        area += ((density(x0) + density(x1)) / 2) * (x1 - x0); // exact: linear segment
+    }
+    return area;
+}
+/**
+ * On-level factors per origin period from a rate-change history. Changes
+ * effective before all data simply set the base level; an empty history
+ * yields factors of exactly 1.
+ */
+export function parallelogramOnLevel(origins, history) {
+    const warnings = [];
+    for (const rc of history) {
+        if (!isNum(rc.change) || rc.change <= -1) {
+            throw new ReservingError("BAD_RATE_CHANGE", "A rate change must be a number greater than -100%");
+        }
+    }
+    const changes = [...history]
+        .map((rc) => ({ at: dateToYearFraction(rc.effectiveDate), change: rc.change }))
+        .sort((a, b) => a.at - b.at);
+    // Rate-level eras: [eraStart_i, eraStart_{i+1}) at cumulative level_i.
+    const eras = [{ from: -Infinity, level: 1 }];
+    let level = 1;
+    for (const c of changes) {
+        level *= 1 + c.change;
+        eras.push({ from: c.at, level });
+    }
+    const currentLevel = level;
+    const rows = origins.map((origin) => {
+        const [p0, p1] = originInterval(origin);
+        const total = earnedArea(p0, p1, -Infinity, p1);
+        if (!(total > 0)) {
+            throw new ReservingError("BAD_ORIGIN", `Origin "${origin}" has no earnable area`);
+        }
+        let weighted = 0;
+        for (let i = 0; i < eras.length; i++) {
+            const from = eras[i].from;
+            const to = i + 1 < eras.length ? eras[i + 1].from : Infinity;
+            const share = earnedArea(p0, p1, from, to) / total;
+            weighted += share * eras[i].level;
+        }
+        return {
+            origin,
+            averageRateLevel: weighted,
+            onLevelFactor: currentLevel / weighted,
+        };
+    });
+    if (changes.length > 0) {
+        const lastOriginEnd = Math.max(...origins.map((o) => originInterval(o)[1]));
+        const beyond = changes.filter((c) => c.at >= lastOriginEnd);
+        if (beyond.length > 0) {
+            warnings.push(`${beyond.length} rate change(s) effective after the last origin period only move the current level (nothing historical to restate)`);
+        }
+    }
+    return { rows, currentLevel, warnings };
+}
+//# sourceMappingURL=onlevel.js.map

package/dist/onlevel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onlevel.js","sourceRoot":"","sources":["../src/onlevel.ts"],"names":[],"mappings":"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"}

package/dist/salvageSubro.d.ts

@@ -0,0 +1,82 @@
+import type { ChainLadderResult, LdfSelections, Triangle, TriangleKind } from "./types.js";
+/**
+ * Salvage & subrogation: recovery triangles develop like loss triangles, so
+ * ultimate recoveries come from a chain ladder on cumulative RECEIVED
+ * recoveries with the caller's selected factors, and net results come from
+ * subtracting the recovery projection from a gross one, aligned by origin.
+ *
+ * Ground truth:
+ * - Recovery development is commonly SLOWER and LUMPIER than the loss
+ *   development it offsets (recoveries lag settlement); every run says so in
+ *   warnings, because borrowing loss LDFs for recoveries is the classic
+ *   mistake this module exists to prevent.
+ * - `netOfRecoveries` never fabricates: an origin present on only one side
+ *   is EXCLUDED with a warning, and both sides' totals cover only the
+ *   aligned origins so net = gross - recoveries holds exactly within the
+ *   result.
+ * - Algebra identity (tested): with the same selections on both triangles,
+ *   netting the two projections equals a chain ladder on the cell-wise
+ *   difference triangle (subtractTriangles), because CL is linear in the
+ *   latest diagonal.
+ */
+export interface SalvageSubroOptions {
+    /** Selected recovery LDFs, one per development interval (null -> 1.000 with a warning). */
+    selected: LdfSelections["selected"];
+    tailFactor?: number;
+}
+export interface SalvageSubroRow {
+    origin: string;
+    latestAge: number;
+    /** Cumulative recoveries received as of the latest diagonal. */
+    receivedToDate: number;
+    /** Cumulative development factor from latestAge to ultimate. */
+    cdf: number;
+    ultimateRecoveries: number;
+    /** ultimate - received: recoveries still expected. */
+    futureRecoveries: number;
+}
+export interface SalvageSubroResult {
+    method: "salvageSubro";
+    basis: TriangleKind;
+    cdfs: number[];
+    percentDeveloped: number[];
+    rows: SalvageSubroRow[];
+    totals: {
+        receivedToDate: number;
+        ultimateRecoveries: number;
+        futureRecoveries: number;
+    };
+    warnings: string[];
+}
+/** Chain ladder on a cumulative received-recoveries triangle. */
+export declare function runSalvageSubro(recoveries: Triangle, options: SalvageSubroOptions): SalvageSubroResult;
+export interface NetOfRecoveriesRow {
+    origin: string;
+    grossUltimate: number;
+    ultimateRecoveries: number;
+    netUltimate: number;
+    grossUnpaid: number;
+    futureRecoveries: number;
+    netUnpaid: number;
+}
+export interface NetOfRecoveriesResult {
+    method: "netOfRecoveries";
+    basis: TriangleKind;
+    rows: NetOfRecoveriesRow[];
+    totals: {
+        grossUltimate: number;
+        ultimateRecoveries: number;
+        netUltimate: number;
+        grossUnpaid: number;
+        futureRecoveries: number;
+        netUnpaid: number;
+    };
+    warnings: string[];
+}
+/**
+ * Nets a gross chain ladder against a recovery projection, aligned by origin
+ * label. Origins missing on either side are warned and EXCLUDED - never
+ * zero-filled - so the totals net exactly over the aligned origins.
+ */
+export declare function netOfRecoveries(gross: ChainLadderResult, recoveries: SalvageSubroResult): NetOfRecoveriesResult;
+//# sourceMappingURL=salvageSubro.d.ts.map

package/dist/salvageSubro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"salvageSubro.d.ts","sourceRoot":"","sources":["../src/salvageSubro.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI3F;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,2FAA2F;IAC3F,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,MAAM,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,kBAAkB,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,CAAC;IACzF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAC7B,UAAU,EAAE,QAAQ,EACpB,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAwCpB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,kBAAkB,EAAE,CAAC;IAC3B,MAAM,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,iBAAiB,EACxB,UAAU,EAAE,kBAAkB,GAC7B,qBAAqB,CAuEvB"}

package/dist/salvageSubro.js

@@ -0,0 +1,100 @@
+import { runChainLadder } from "./chainladder.js";
+import { ReservingError } from "./types.js";
+import { isNum } from "./util.js";
+/** Chain ladder on a cumulative received-recoveries triangle. */
+export function runSalvageSubro(recoveries, options) {
+    const warnings = [
+        "Salvage and subrogation typically develop more slowly and less smoothly than the losses they offset; select recovery factors from recovery experience rather than borrowing loss LDFs",
+    ];
+    const negativeOrigins = recoveries.origins.filter((_, i) => recoveries.values[i].some((v) => isNum(v ?? null) && v < 0));
+    if (negativeOrigins.length > 0) {
+        warnings.push(`Negative cumulative recoveries for origin(s) ${negativeOrigins.join(", ")}; received salvage/subrogation should be non-negative - verify the data`);
+    }
+    const cl = runChainLadder(recoveries, {
+        selected: options.selected,
+        tailFactor: options.tailFactor ?? 1,
+    });
+    warnings.push(...cl.warnings);
+    return {
+        method: "salvageSubro",
+        basis: cl.basis,
+        cdfs: cl.cdfs,
+        percentDeveloped: cl.percentDeveloped,
+        rows: cl.rows.map((r) => ({
+            origin: r.origin,
+            latestAge: r.latestAge,
+            receivedToDate: r.latestValue,
+            cdf: r.cdf,
+            ultimateRecoveries: r.ultimate,
+            futureRecoveries: r.unpaid,
+        })),
+        totals: {
+            receivedToDate: cl.totals.latest,
+            ultimateRecoveries: cl.totals.ultimate,
+            futureRecoveries: cl.totals.unpaid,
+        },
+        warnings,
+    };
+}
+/**
+ * Nets a gross chain ladder against a recovery projection, aligned by origin
+ * label. Origins missing on either side are warned and EXCLUDED - never
+ * zero-filled - so the totals net exactly over the aligned origins.
+ */
+export function netOfRecoveries(gross, recoveries) {
+    const warnings = [];
+    const recoveryByOrigin = new Map(recoveries.rows.map((r) => [r.origin, r]));
+    const grossOrigins = new Set(gross.rows.map((r) => r.origin));
+    const rows = [];
+    const negativeNetOrigins = [];
+    for (const g of gross.rows) {
+        const rec = recoveryByOrigin.get(g.origin);
+        if (!rec) {
+            warnings.push(`Origin ${g.origin} has no recovery projection; excluded from the net results (never zero-filled)`);
+            continue;
+        }
+        if (g.latestAge !== rec.latestAge) {
+            warnings.push(`Origin ${g.origin}: gross projected from age ${g.latestAge} months but recoveries from age ${rec.latestAge}; the net mixes valuation dates`);
+        }
+        const row = {
+            origin: g.origin,
+            grossUltimate: g.ultimate,
+            ultimateRecoveries: rec.ultimateRecoveries,
+            netUltimate: g.ultimate - rec.ultimateRecoveries,
+            grossUnpaid: g.unpaid,
+            futureRecoveries: rec.futureRecoveries,
+            netUnpaid: g.unpaid - rec.futureRecoveries,
+        };
+        if (row.netUltimate < 0 || row.netUnpaid < 0)
+            negativeNetOrigins.push(g.origin);
+        rows.push(row);
+    }
+    for (const rec of recoveries.rows) {
+        if (!grossOrigins.has(rec.origin)) {
+            warnings.push(`Origin ${rec.origin} has a recovery projection but no gross result; excluded from the net results (never zero-filled)`);
+        }
+    }
+    if (rows.length === 0) {
+        throw new ReservingError("NO_DATA", "No origin appears in both the gross and recovery projections");
+    }
+    if (negativeNetOrigins.length > 0) {
+        warnings.push(`Projected recoveries exceed gross losses for origin(s) ${negativeNetOrigins.join(", ")}; the net result is negative - verify the recovery development`);
+    }
+    const totals = rows.reduce((acc, r) => ({
+        grossUltimate: acc.grossUltimate + r.grossUltimate,
+        ultimateRecoveries: acc.ultimateRecoveries + r.ultimateRecoveries,
+        netUltimate: acc.netUltimate + r.netUltimate,
+        grossUnpaid: acc.grossUnpaid + r.grossUnpaid,
+        futureRecoveries: acc.futureRecoveries + r.futureRecoveries,
+        netUnpaid: acc.netUnpaid + r.netUnpaid,
+    }), {
+        grossUltimate: 0,
+        ultimateRecoveries: 0,
+        netUltimate: 0,
+        grossUnpaid: 0,
+        futureRecoveries: 0,
+        netUnpaid: 0,
+    });
+    return { method: "netOfRecoveries", basis: gross.basis, rows, totals, warnings };
+}
+//# sourceMappingURL=salvageSubro.js.map

package/dist/salvageSubro.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"salvageSubro.js","sourceRoot":"","sources":["../src/salvageSubro.ts"],"names":[],"mappings":"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"}

package/dist/stochastic.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Stochastic infrastructure: a seeded, reproducible RNG and the shared
+ * result shape every simulation-based method returns.
+ *
+ * Ground truth:
+ * - NO ambient randomness anywhere in the engine: every stochastic method
+ *   takes an explicit integer seed, and the same seed + same inputs must
+ *   reproduce the same output bit for bit (the reproducibility-bundle
+ *   contract depends on it).
+ * - The generator is mulberry32: tiny, fast, well-distributed for
+ *   simulation purposes. It is NOT cryptographic and does not need to be.
+ */
+export interface Rng {
+    /** Uniform on [0, 1). */
+    next(): number;
+    /** Standard normal (Box-Muller with cached spare). */
+    normal(): number;
+    /**
+     * Gamma(shape, scale = 1) via Marsaglia-Tsang squeeze (shape >= 1) with
+     * the Ahrens-Dieter boost for shape < 1.
+     */
+    gamma(shape: number): number;
+}
+/** Deterministic seeded RNG. Same seed = same stream, forever. */
+export declare function createRng(seed: number): Rng;
+/** The percentiles every stochastic summary reports, as fractions. */
+export declare const STANDARD_PERCENTILES: readonly [0.01, 0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, 0.99];
+export interface StochasticSummary {
+    mean: number;
+    /** Sample standard deviation (n - 1). */
+    sd: number;
+    /** sd / |mean|; null when the mean is 0. */
+    cv: number | null;
+    /** Keyed "p50", "p75", ... per STANDARD_PERCENTILES; linear interpolation. */
+    percentiles: Record<string, number>;
+}
+export interface StochasticOriginResult {
+    origin: string;
+    summary: StochasticSummary;
+}
+export interface StochasticResult {
+    /** What the simulated quantity IS (e.g. "unpaid", "ultimate", "cdr"). */
+    quantity: string;
+    seed: number;
+    nSims: number;
+    total: StochasticSummary;
+    byOrigin: StochasticOriginResult[];
+    /** Total-level simulated values, ascending, for caller-side percentiles/plots. */
+    totalSamples: number[];
+    warnings: string[];
+}
+/** Linear-interpolated percentile of a SORTED ascending sample. */
+export declare function percentileOfSorted(sorted: number[], p: number): number;
+/** Summarizes a sample (sorts a copy; the input is not mutated). */
+export declare function summarizeSample(values: number[]): StochasticSummary;
+//# sourceMappingURL=stochastic.d.ts.map

package/dist/stochastic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stochastic.d.ts","sourceRoot":"","sources":["../src/stochastic.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,GAAG;IAClB,yBAAyB;IACzB,IAAI,IAAI,MAAM,CAAC;IACf,sDAAsD;IACtD,MAAM,IAAI,MAAM,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAwD3C;AAED,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,8DAA+D,CAAC;AAEjG,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,iBAAiB,CAAC;IACzB,QAAQ,EAAE,sBAAsB,EAAE,CAAC;IACnC,kFAAkF;IAClF,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAYtE;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAiBnE"}

package/dist/stochastic.js

@@ -0,0 +1,99 @@
+import { ReservingError } from "./types.js";
+import { isNum } from "./util.js";
+/** Deterministic seeded RNG. Same seed = same stream, forever. */
+export function createRng(seed) {
+    if (!Number.isInteger(seed)) {
+        throw new ReservingError("BAD_SEED", "The RNG seed must be an integer");
+    }
+    let a = seed >>> 0;
+    const next = () => {
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    let spare = null;
+    const normal = () => {
+        if (spare !== null) {
+            const v = spare;
+            spare = null;
+            return v;
+        }
+        // Box-Muller; u clamped away from 0 so log stays finite.
+        let u = next();
+        if (u < 1e-12)
+            u = 1e-12;
+        const v = next();
+        const r = Math.sqrt(-2 * Math.log(u));
+        const theta = 2 * Math.PI * v;
+        spare = r * Math.sin(theta);
+        return r * Math.cos(theta);
+    };
+    const gamma = (shape) => {
+        if (!isNum(shape) || shape <= 0) {
+            throw new ReservingError("BAD_SHAPE", "Gamma shape must be a positive number");
+        }
+        if (shape < 1) {
+            // Ahrens-Dieter boost: G(a) = G(a+1) * U^(1/a).
+            const u = Math.max(next(), 1e-12);
+            return gamma(shape + 1) * Math.pow(u, 1 / shape);
+        }
+        // Marsaglia & Tsang (2000).
+        const d = shape - 1 / 3;
+        const c = 1 / Math.sqrt(9 * d);
+        for (;;) {
+            let x;
+            let v;
+            do {
+                x = normal();
+                v = 1 + c * x;
+            } while (v <= 0);
+            v = v * v * v;
+            const u = next();
+            if (u < 1 - 0.0331 * x * x * x * x)
+                return d * v;
+            if (Math.log(Math.max(u, 1e-300)) < 0.5 * x * x + d * (1 - v + Math.log(v)))
+                return d * v;
+        }
+    };
+    return { next, normal, gamma };
+}
+/** The percentiles every stochastic summary reports, as fractions. */
+export const STANDARD_PERCENTILES = [0.01, 0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, 0.99];
+/** Linear-interpolated percentile of a SORTED ascending sample. */
+export function percentileOfSorted(sorted, p) {
+    if (sorted.length === 0) {
+        throw new ReservingError("NO_DATA", "Cannot take a percentile of an empty sample");
+    }
+    if (!isNum(p) || p < 0 || p > 1) {
+        throw new ReservingError("BAD_PERCENTILE", `Percentile must be in [0, 1] (got ${p})`);
+    }
+    const idx = p * (sorted.length - 1);
+    const lo = Math.floor(idx);
+    const hi = Math.ceil(idx);
+    if (lo === hi)
+        return sorted[lo];
+    return sorted[lo] + (idx - lo) * (sorted[hi] - sorted[lo]);
+}
+/** Summarizes a sample (sorts a copy; the input is not mutated). */
+export function summarizeSample(values) {
+    if (values.length < 2) {
+        throw new ReservingError("TOO_SMALL", "A stochastic summary needs at least two simulations");
+    }
+    const sorted = [...values].sort((a, b) => a - b);
+    const n = sorted.length;
+    let sum = 0;
+    for (const v of sorted)
+        sum += v;
+    const mean = sum / n;
+    let ss = 0;
+    for (const v of sorted)
+        ss += (v - mean) ** 2;
+    const sd = Math.sqrt(ss / (n - 1));
+    const percentiles = {};
+    for (const p of STANDARD_PERCENTILES) {
+        percentiles[`p${Math.round(p * 100)}`] = percentileOfSorted(sorted, p);
+    }
+    return { mean, sd, cv: mean === 0 ? null : sd / Math.abs(mean), percentiles };
+}
+//# sourceMappingURL=stochastic.js.map

package/dist/stochastic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stochastic.js","sourceRoot":"","sources":["../src/stochastic.ts"],"names":[],"mappings":"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"}

package/dist/tail.d.ts

@@ -0,0 +1,18 @@
+import type { TailFit, TailMethod } from "./types.js";
+export interface FitTailOptions {
+    method: TailMethod;
+    /**
+     * Selected LDFs by development column (from ages[j] to ages[j+1]);
+     * null entries are skipped.
+     */
+    selectedLdfs: (number | null)[];
+    /** Cap on extrapolated development periods (default 200). */
+    maxHorizon?: number;
+}
+export declare function fitTail(options: FitTailOptions): TailFit;
+/** Fits both supported curves so the user can compare them side by side. */
+export declare function fitAllTails(selectedLdfs: (number | null)[]): {
+    exponentialDecay: TailFit;
+    inversePower: TailFit;
+};
+//# sourceMappingURL=tail.d.ts.map

package/dist/tail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tail.d.ts","sourceRoot":"","sources":["../src/tail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAwBtD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IAChC,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CA8GxD;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CACzB,YAAY,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAC9B;IAAE,gBAAgB,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAKtD"}

package/dist/tail.js

@@ -0,0 +1,121 @@
+import { isNum, ols } from "./util.js";
+/**
+ * Tail factor curve fitting per Sherman (1984) and Boor (2006).
+ *
+ * - Exponential decay: ln(LDF_j - 1) is linear in the development period index.
+ * - Inverse power:     ln(LDF_j - 1) is linear in ln(period index).
+ *
+ * The fit runs on the SELECTED age-to-age factors. Guards:
+ * - fewer than MIN_POINTS usable points (factor > 1) -> invalid;
+ * - non-negative slope (growth instead of decay) -> invalid;
+ * - extrapolation is capped in horizon and in total tail size, with a loud
+ *   warning when the cap binds (inverse power with slope > -1 diverges).
+ */
+const MIN_POINTS = 3;
+/** Extrapolate at most this many development periods beyond the last age. */
+const MAX_HORIZON = 200;
+/** Stop extrapolating once the incremental factor is this close to 1. */
+const CONVERGENCE_EPS = 1e-7;
+/** A fitted tail beyond this bound is treated as divergent. */
+const MAX_TAIL = 5;
+export function fitTail(options) {
+    const { method, selectedLdfs } = options;
+    const maxHorizon = options.maxHorizon ?? MAX_HORIZON;
+    const warnings = [];
+    // x = 1-based development period index of each factor; y = ln(f - 1).
+    const xs = [];
+    const ys = [];
+    let skippedAtOrBelowOne = 0;
+    for (let j = 0; j < selectedLdfs.length; j++) {
+        const f = selectedLdfs[j] ?? null;
+        if (!isNum(f))
+            continue;
+        if (f <= 1) {
+            skippedAtOrBelowOne++;
+            continue;
+        }
+        const idx = j + 1;
+        xs.push(method === "exponentialDecay" ? idx : Math.log(idx));
+        ys.push(Math.log(f - 1));
+    }
+    if (skippedAtOrBelowOne > 0) {
+        warnings.push(`${skippedAtOrBelowOne} selected factor(s) at or below 1.000 were excluded from the fit (ln(f-1) undefined)`);
+    }
+    const invalid = (message) => ({
+        method,
+        intercept: NaN,
+        slope: NaN,
+        rSquared: NaN,
+        nPoints: xs.length,
+        extrapolatedFactors: [],
+        tailFactor: 1,
+        valid: false,
+        warnings: [...warnings, message],
+    });
+    if (xs.length < MIN_POINTS) {
+        return invalid(`Only ${xs.length} usable point(s); at least ${MIN_POINTS} factors above 1.000 are required to fit a tail curve`);
+    }
+    const fit = ols(xs, ys);
+    if (!fit)
+        return invalid("Degenerate regression (no variation in development ages)");
+    if (fit.slope >= 0) {
+        return invalid("Fitted curve grows with age instead of decaying; the selected factors do not support a tail extrapolation with this model");
+    }
+    // Extrapolate incremental factors beyond the last SELECTED column. Trailing
+    // null selections carry no development of their own (chain ladder treats
+    // them as 1.000), so the extrapolation must start right after the last
+    // non-null selection or the curve's predicted factors for those columns
+    // would silently vanish from the tail.
+    let lastIdx = 0; // 1-based index of the last non-null selection
+    for (let j = selectedLdfs.length - 1; j >= 0; j--) {
+        if (isNum(selectedLdfs[j] ?? null)) {
+            lastIdx = j + 1;
+            break;
+        }
+    }
+    if (lastIdx < selectedLdfs.length) {
+        warnings.push(`The last ${selectedLdfs.length - lastIdx} development column(s) have no selected factor; the fitted tail covers them via the curve (chain ladder would otherwise treat them as 1.000)`);
+    }
+    const extrapolatedFactors = [];
+    let tail = 1;
+    let converged = false;
+    for (let step = 1; step <= maxHorizon; step++) {
+        const idx = lastIdx + step;
+        const x = method === "exponentialDecay" ? idx : Math.log(idx);
+        const f = 1 + Math.exp(fit.intercept + fit.slope * x);
+        extrapolatedFactors.push(f);
+        tail *= f;
+        if (tail > MAX_TAIL) {
+            return invalid(`Extrapolated tail exceeded ${MAX_TAIL.toFixed(1)} after ${step} periods; the fit is divergent (inverse power with slope > -1 has an unbounded product). Enter a tail judgmentally instead.`);
+        }
+        if (f - 1 < CONVERGENCE_EPS) {
+            converged = true;
+            break;
+        }
+    }
+    if (!converged) {
+        warnings.push(`Extrapolation stopped at the ${maxHorizon}-period horizon before the factors converged to 1.000; the tail is truncated and understated`);
+    }
+    if (fit.rSquared < 0.8) {
+        warnings.push(`Fit quality is weak (R-squared ${fit.rSquared.toFixed(3)}); treat this tail as indicative only`);
+    }
+    return {
+        method,
+        intercept: fit.intercept,
+        slope: fit.slope,
+        rSquared: fit.rSquared,
+        nPoints: fit.n,
+        extrapolatedFactors,
+        tailFactor: tail,
+        valid: true,
+        warnings,
+    };
+}
+/** Fits both supported curves so the user can compare them side by side. */
+export function fitAllTails(selectedLdfs) {
+    return {
+        exponentialDecay: fitTail({ method: "exponentialDecay", selectedLdfs }),
+        inversePower: fitTail({ method: "inversePower", selectedLdfs }),
+    };
+}
+//# sourceMappingURL=tail.js.map

package/dist/tail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tail.js","sourceRoot":"","sources":["../src/tail.ts"],"names":[],"mappings":"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"}