@actuarial-ts/interchange

Typed TypeScript implementation of actuarial-interchange: portable, integrity-stamped documents shared by actuarial-ts, chainladder-python, and R ChainLadder.

npm install @actuarial-ts/[email protected] @actuarial-ts/[email protected]

Node 20+, ESM. Current writers use interchange wire 1.3.0 and readers accept compatible major-version-1 documents. SDK package versions and interchange wire versions are independent.

The source repository is private, so the guide, reference, and specification links below open only with repository access. The published package is unaffected and remains Apache-2.0.

Wire 1.2 adds the portable customization-analysis document. TypeScript can execute and verify its current contracts; Python and R adapter 0.3 parse and preserve it without claiming execution. See the 0.8 adoption guide (docs/migrations/0.8-reusable-customization.md) and customization reference (docs/reference/reusable-customization.md).

Document kinds

triangle, selection, method-result, stochastic-result, study, bundle, crosscheck-report, diagnostic-definition, customization-analysis, and analysis-review share an envelope with writer version, generator, caller-supplied timestamp, semantic-body FNV-1a/JCS integrity tag, and optional governance/extensions.

import {
  diagnosticDefinitionToDoc,
  docToDiagnosticDefinition,
  parseDocument,
} from "@actuarial-ts/interchange";

const document = diagnosticDefinitionToDoc(compiledDefinition, {
  createdAt: "2026-09-03T00:00:00Z",
});
const generic = parseDocument(document);
const executable = docToDiagnosticDefinition(document);

Generic parsing validates known fields, preserves same-major unknown envelope and nested fields, verifies integrity, and recursively verifies documents embedded in studies/bundles. Executable diagnostic conversion is intentionally stricter: it requires the current normalized vocabulary, recompiles the complete definition, and verifies formula, calculation, and definition identities. A future field can therefore survive a storage hop without being silently executed.

Bundles may carry typed diagnostic definition documents under interchange.diagnosticDefinitions; each nested document has its own tag and is also covered by the outer { bundle, interchange } tag. Current JSON Schemas live in schema/interchange/1.3; the 1.0, 1.1 and 1.2 directories remain historical.

Wire 1.3 adds analysis-review for complete connected review runs. Generic parsing preserves evidence and verifies structural references; executable conversion replays every node and returns a current-process receipt. Python and R preserve this body and explicitly declare graph execution unsupported. See the review contract (docs/reference/review-interchange.md) for reference resolution, native typed payloads, limits and migration guidance.

The same analysis-review body preserves the connected Munich Chain Ladder graph, including both paid/incurred source revisions, final-sigma declaration, native specialist evidence, selection and paid reconciliation. TypeScript replays the calculation; Python and R retain it without claiming Munich graph execution.

It also preserves connected case-outstanding paid/case sources, adopted ratio provenance, native payment paths, selection and paid reconciliation. TypeScript replays the complete graph; Python and R preserve it without claiming independent case-outstanding graph execution.

It preserves connected Fisher–Lange paid/closed-count sources, count meaning, adopted ultimate-count, disposal-pattern and severity-trend assumptions, native age evidence, selection and paid reconciliation. TypeScript replays the complete graph; Python and R preserve it without claiming independent Fisher–Lange graph execution.

The same document also preserves governed ULAE calibration, selected-ratio provenance, expense/loss scopes, origin reserve rows and calculated selection. TypeScript replays both ULAE operations; Python and R preserve the graph without claiming execution.

The SDK 0.16 optional analysisReview.studies member retains complete diagnostic suites, sensitivities and grids with a separate reference inventory. Executable conversion replays their native calculations and exact subject bindings. Python and R preserve these studies without claiming execution. See docs/reference/review-studies.md for attachment contracts and limits.

Interoperability

The three shores share RFC 8785 vectors, frozen reserving fixtures, and generalized casualty definitions with six formulas and 22 bound instances. Python and R independently recompute definition identities and replay every formula and all five review-rule kinds across the calendar and ordered-axis aggregate-cell corpus, including missingness, tolerance boundaries, and overflow. The replay contract does not claim to reproduce arbitrary raw-data ingestion or selection in those languages.

The compact diagnostic-replay/1 stream introduced in SDK 0.7.0 belongs to @actuarial-ts/compliance. It is not an interchange document kind, cannot be passed to parseDocument, and is not the three-shore aggregate-cell replay contract described above. Use compliance's dedicated stream reader with its required resource policy. A stream's engine-version identities also require retaining the producing SDK versions; same interchange or stream wire versions do not promise cross-SDK-version verification. See the compact adoption guide (docs/migrations/0.7-compact-diagnostics.md) and replay reference (docs/reference/diagnostic-replay-stream.md).

crosscheck compares two method-result documents under explicit convention profiles. Outcomes are agree, disagree, not-comparable, or verified-by-value; the referee never hides convention differences or treats mutual agreement as proof of correctness.

Integrity tags detect accidental drift and support deterministic linking. FNV-1a is unkeyed and is not tamper resistance, authentication, or a security boundary.

The normative format is actuarial-interchange rev 2.6 (docs/spec/actuarial-interchange.md). See the generated diagnostic formula catalog (docs/reference/diagnostic-formulas.md) and 0.6 migration guide (docs/migrations/0.6-generalized-diagnostics.md).

License

Apache-2.0. See LICENSE and NOTICE.

SDK 0.9 adds native post-aggregation formulas and correct financial currency units. See the 0.9 migration guide (docs/migrations/0.9-analysis-expressions.md).

Composite history sources

SDK 0.10 adds multiple original artifacts within one claim namespace, explicit composite identity selectors and complete input-artifact membership checks. Upgrade the five SDK packages together and preserve the producing runtime with archived evidence. See the 0.10 migration guide (docs/migrations/0.10-composite-history.md).

Connected reserve review

SDK 0.16 writes the analysis-review document on interchange wire 1.3.0. TypeScript supports current-runtime graph replay; Python and R preserve the document without claiming that execution. Upgrade all five SDK packages together and see the 0.16 migration guide (docs/migrations/0.16-connected-reserve-review.md).

SDK 0.17 audit hardening

SDK 0.17 closes the audited validation and evidence boundaries while retaining interchange wire 1.3.0. Upgrade all five SDK packages together and see docs/migrations/0.17-audit-hardening.md.