@actuarial-ts/core

Pure, framework-free P&C actuarial calculations: reserving models, development patterns, diagnostic metrics, financial adjustments, forecasts and review graphs.

This README describes the 0.27.0 candidate. Use all five SDK packages from the same versioned package set. ESM, TypeScript-first, Node 20+, with no runtime dependencies.

The source repository is private. Repository users can start with docs/sdk-guide.md and docs/migrations/0.27-sdk-cleanup.md for installation, package boundaries and the archive/recalculate path. Those guides are not included in the npm tarball. Candidate documentation is not a publication claim.

Reserving quick start

Given claim snapshots with declared dates and amounts:

import { buildTriangles, computeDevelopmentFactors, runChainLadder, runMack } from "@actuarial-ts/core";

const { paid } = buildTriangles(claimSnapshots, { cadence: "annual", asOfDate: "2025-12-31" });
const selected = computeDevelopmentFactors(paid).averages.find((item) => item.spec.key === "all-wtd")!.values;
const chainLadder = runChainLadder(paid, { selected, tailFactor: 1.02 });
const mack = runMack(paid, { selected, tailFactor: 1.02 });

Unobservable triangle cells are null. Volume-weighted factors use sum/sum over rows where both observations exist. CDFs multiply right to left, tail last. Missing, zero or negative divisors produce unavailable factors rather than NaN. True cumulative development age zero is numeric zero; missing positive-age observations remain missing. An origin label such as "0" is an ordinary label.

Use runModel for the connected model contract: it retains typed quantities, source references, assumptions, findings and available uncertainty. Native kernels such as runChainLadder remain useful for direct calculation.

Review execution and verification

A ReviewPlan binds typed inputs, dependencies, operations and named outputs. For a validated plan:

import {
  runReviewPlan,
  verifyReviewPlanRun,
  replayReviewPlanRun,
  REVIEW_PLAN_VERIFICATION_LIMITS,
} from "@actuarial-ts/core";

const run = runReviewPlan(plan);
const verification = verifyReviewPlanRun({
  run,
  limits: REVIEW_PLAN_VERIFICATION_LIMITS,
});
// Explicitly execute the graph again, even for this exact live run:
const replay = replayReviewPlanRun({ run, limits: REVIEW_PLAN_VERIFICATION_LIMITS });

verifyReviewPlanRun preserves an exact authentic current-process execution; imported or copied runs must reproduce through current-SDK execution. Both paths check the caller's limits. ReviewPlanVerification.assurance.calculations records executed-current-sdk or replayed-current-sdk. Re-executing the same SDK is reproducibility evidence, not independent actuarial validation. isVerifiedReviewPlan recognizes only receipts issued by this process.

encodeReviewEvidence and decodeReviewEvidence use actuarial-review-evidence-graph/3. Shared JSON transport does not grant execution or source authority. Physical graph limits govern actual retained work. Explicit tree serialization has its own expansion bound; ordinary graph ownership does not expand shared children. canonicalJsonEqual compares complete canonical content; structural sharing is not permission to skip validation or rely on a hash alone.

Generalized diagnostics

Measures declare quantities, units, development semantics, missingness and population/basis meaning. Formula instances bind typed roles to those measures; presentation and review rules remain separate from arithmetic identity. The following uses caller-authored measures, populations, bases and period policy:

import {
  CASUALTY_FORMULA_TEMPLATES,
  compileDiagnosticDefinition,
  createCasualtyMetricInstances,
  prepareDiagnosticData,
  runMetricDiagnostics,
} from "@actuarial-ts/core";

const instances = createCasualtyMetricInstances({
  counts: { reported: "reported", open: "open", closedNoPay: "closed-no-pay", closedWithPay: "closed-with-pay" },
  exposure: "earned-vehicle-years",
  amountBindings: [
    { id: "gross", paid: "gross-paid", incurred: "gross-incurred" },
    { id: "primary-250k", paid: "primary-paid", incurred: "primary-incurred" },
  ],
});

const compiled = compileDiagnosticDefinition({
  diagnosticDefinitionVersion: "1.0.0",
  id: "fleet-diagnostics",
  version: "1.0.0",
  lossRowGrain: "aggregate",
  measures,
  countPopulations,
  exposureBases,
  amountBases,
  derivedMeasures: [],
  formulas: CASUALTY_FORMULA_TEMPLATES,
  instances,
  reviewRules,
  periodAxis,
});

const prepared = prepareDiagnosticData({ definition: compiled, losses, exposures });
const result = runMetricDiagnostics({ prepared, groupMap: { fleet: "all-fleet" } });

Metrics divide after source-group/origin/valuation aggregation and explicit group mapping. Exposure timing is declared as origin-static or valuation-specific. Claim-level caps are applied before aggregation; pre-limited source values must retain their declared transformation and cannot imply recreated claim detail. Compilation validates the complete definition, dependencies and period coordinates.

Choose matching preparation, calculation and maturity functions:

| Operation | Eager evidence | Compact evidence | |---|---|---| | Prepare | prepareDiagnosticData | prepareDiagnosticDataCompact | | Calculate | runMetricDiagnostics | runMetricDiagnosticsCompact | | Select development age | sameMaturity | sameMaturityCompact | | Latest common age | commonMaturity | commonMaturityCompact |

Compact owners retain complete audit evidence. Page review evaluations and their sources with pageDiagnosticReviewEvaluations and pageDiagnosticReviewEvaluationSources; paging is not sampling. Materialization explicitly expands evidence and may use substantially more memory. Copies and parsed JSON cannot recreate authentic compiled/prepared owners. For imported data and review/execution gates, use the gateway in @actuarial-ts/data.

Models, assumptions and financial meaning

• Reserving includes chain ladder, Mack, BF, Benktander, Cape Cod, Expected Claims, frequency-severity, Munich chain ladder, case outstanding, Fisher-Lange, Clark, ODP bootstrap and Merz-Wüthrich one-year risk. Availability and uncertainty are method-specific; inspect the result's findings.
• selectDevelopmentPattern binds explicit averaging/tail intent to native evidence. createSelectedEstimateRange records human-selected endpoints and rationale; it is a nonprobabilistic range.
• Connected adjustments cover premium on-leveling/trend, capping/ILFs, ULAE, nominal cash flows and discounting with explicit sources, dates and quantities. createModelForecast and scoreModelForecast preserve frozen forecast vintages and distinguish later restatements from actual emergence.

AnalysisDefinition.financialTermSchedules resolves declared accident/report/date fields over complete claim, occurrence or policy populations. Starts are inclusive, ends exclusive; an equal-priority match is unavailable. A schedule boundary does not create a new deductible or infer annual resets. Use createFinancialTermScheduleBinding for heterogeneous scheduled limitations and deriveRecipeFinancialBasis to derive supported output meaning from a confirmed input basis. These declarations do not authenticate external source facts.

Published source fixtures and independent comparisons are the numerical contract. The package is designed to support the actuary's compliance with the ASOPs; it does not make a work product compliant or replace professional judgment.

License

Apache-2.0. See LICENSE and NOTICE. The source repository is private; the published packages retain their Apache-2.0 license.