@actuarial-ts/interchange

Portable, integrity-stamped actuarial documents for TypeScript, chainladder-python and R ChainLadder. This package owns document envelopes, conversion, reference bindings and cross-engine comparison; calculation ownership stays in core.

This README describes the 0.27.0 candidate. Use all five SDK packages from the same versioned package set. ESM, Node 20+.

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.

Documents and parsing

Document kinds include triangle, selection, method-result, stochastic-result, study, bundle, crosscheck-report, diagnostic-definition, customization-analysis and analysis-review. They share a generator, caller-supplied timestamp, semantic-body integrity tag and optional governance/extensions. Current writers use interchange wire 1.3.0; SDK package versions and document wire versions have different roles.

Given an authentic compiled diagnostic definition:

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);

parseDocument validates the document and its integrity, including embedded documents in studies/bundles. Preserved unknown fields remain data. docToDiagnosticDefinition requires the executable vocabulary, recompiles the complete definition and checks formula, calculation and definition identities. Successful generic parsing alone does not authorize execution.

Connected review documents

For a completed current-SDK review run:

import { REVIEW_PLAN_VERIFICATION_LIMITS } from "@actuarial-ts/core";
import {
  analysisReviewToDoc,
  docToAnalysisReview,
  replayAnalysisReview,
} from "@actuarial-ts/interchange";

const document = analysisReviewToDoc({
  run,
  supportingDocuments: [],
  limits: REVIEW_PLAN_VERIFICATION_LIMITS,
}, { createdAt: "2026-10-30T00:00:00Z" });

const checked = docToAnalysisReview(document);
const verification = checked.verification;
// This operation explicitly re-executes the graph:
const replayed = replayAnalysisReview(document);

Authoring preserves the exact authentic execution object through verification. Executable conversion can reuse that current-process evidence; imported or copied runs must reproduce through current-SDK execution. replayAnalysisReview always re-executes. Complete node outputs, references, supporting documents and attached studies retain their own validation and resource limits.

The current analysis-review body /3 already contains the complete shared actuarial-review-evidence-graph/3. Read its structural content with readAnalysisReviewContent(document) and inspect unique definitions with analysisReviewReferences(document). Decoding creates no calculation or source authority. Complete wrapper bindings and exact collision checks remain mandatory.

Interoperability and assurance

Python and R adapters preserve review documents without claiming to execute their TypeScript review graphs. Their supported independent reserving and diagnostic checks are separate capabilities. Generalized diagnostic conformance covers formula and review-rule evaluation over declared aggregate cells; it does not imply arbitrary raw-data ingestion or selection in those languages.

crosscheck compares method-result documents under explicit convention profiles. Its outcomes are agree, disagree, not-comparable and verified-by-value. Mutual agreement is not proof that assumptions or methods are appropriate.

FNV-1a/JCS integrity tags detect drift and support deterministic linking. They are unkeyed integrity aids, not cryptographic signatures or source authentication. The compliance diagnostic-replay/1 stream is a separate format, not a document accepted by parseDocument; use its dedicated reader and resource policy.

Preserve original producing versions and original bytes when archiving old work. A current calculation is a new linked result, not a restamped old document. Runnable cross-engine examples are examples/chain-ladder-typescript, examples/chain-ladder-python, examples/chain-ladder-r and examples/chain-ladder-crosscheck in the private repository.

License

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