@actuarial-ts/compliance

Prepared package version: 0.22.0 (unreleased). Keep all five SDK packages on the same version. The version-pinned install below is an adoption command for after the complete release gate and registry readback, not a current publication claim. Preserve recorded producing versions on old results and frozen evidence. See docs/migrations/0.22-nominal-cashflow-aggregation.md and docs/migrations/0.22-premium-and-adjusted-prior.md in the private repository.

SDK 0.21 adds observed-triangle diagnostic preflight and execution without a fitted reserve model. See docs/migrations/0.21-observed-triangle-diagnostics.md and docs/reference/review-observed-diagnostics.md in the private repository.

Shared final-selection evidence retains /1 compatibility and adds explicit actuarial-review-evidence-graph/2 transport in prepared 0.22. The default core encodeReviewEvidence writer remains /1; portable analysis-review and verified snapshot writers use /2. Decoding neither version grants calculation or source authority. See docs/migrations/0.20-shared-review-evidence.md and docs/reference/shared-review-evidence.md in the private repository. All five SDK packages are prepared together at 0.22.0. The interchange wire remains 1.3.0 and Python/R adapter generator versions remain 0.3.0.

Candidate package version: 0.22.0. Sections labeled SDK 0.16 describe features introduced in that release and retained in the 0.22.0 candidate; the SDK 0.17 section and migration guide describe the current hardening rules.

SDK 0.19 fixes paired diagnostic structural-origin provenance and supplies bounded grouped original-history replay, typed model graphs and snapshot source bindings. See docs/migrations/0.19-grouped-history-and-origin-zero.md and docs/reference/bounded-grouped-history.md in the private repository.

SDK 0.18 adds authenticated bounded review-evidence indexes, exact and derivation projections, and dynamic numbered report references. Stable evidence IDs remain authoritative when presentation ordinals change. See docs/migrations/0.18-ai-native-protocol.md, docs/reference/agent-protocol.md, docs/reference/agent-tasks.md, and docs/reference/review-evidence.md.

The legacy A/E helpers delegate their calculations to core. Finite amounts and warnings are preserved; A/E ratios now require positive expected emergence. Invalid/nonfinite or overflowing legacy inputs throw ComplianceError("BAD_AVE_INPUT"); invalid CDFs retain BAD_CDF. See docs/reference/review-forecasts.md in the private repository for the forecast/scoring contracts and migration notes.

Documentation, judgment, provenance, and reproducibility primitives for actuarial-ts. The package is designed to support compliance work under applicable ASOPs; it neither determines compliance nor replaces the actuary’s review.

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

Node 20+, ESM.

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

SDK 0.8 adds fresh-execution customization provenance and source-bound bounded replay receipts. See the 0.8 adoption guide (docs/migrations/0.8-reusable-customization.md) and customization reference (docs/reference/reusable-customization.md).

Diagnostic provenance

The example below uses eager provenance. createDiagnosticRunIdentity accepts only an owner-authenticated, completed eager data-package run. It does not accept caller-restated formulas, filters, review status, or result identities. Compact runs use the separate workflow below.

import { createBundle, createDiagnosticRunIdentity } from "@actuarial-ts/compliance";

if (outcome.status !== "completed") throw new Error(`diagnostics blocked at ${outcome.stage}`);

const provenance = await createDiagnosticRunIdentity({
  completedRun: outcome,
  inputArtifacts: [
    { id: "loss-run", scope: "input", assurance: "sdk-computed", bytes: lossRunBytes },
    { id: "exposures", scope: "input", assurance: "sdk-computed", bytes: exposureBytes },
    { id: "source-archive", scope: "input", assurance: "caller-declared", algorithm: "sha256", value: archiveSha256 },
  ],
  preparationArtifacts: [
    { id: "transform-script", scope: "preparation", assurance: "caller-declared", algorithm: "git-sha", value: transformCommit },
  ],
  preparationLineage: [
    { outputArtifactId: "loss-run", inputArtifactIds: ["source-archive"], transformationArtifactIds: ["transform-script"] },
  ],
});

const bundle = createBundle({
  inputs,
  parameters,
  results: outcome.result,
  sdkVersions: {
    "@actuarial-ts/core": provenance.manifest.engine.packages.core,
    "@actuarial-ts/data": provenance.manifest.engine.packages.data,
    "@actuarial-ts/compliance": provenance.manifest.engine.packages.compliance,
  },
  createdAt: "2026-09-03T00:00:00Z",
  diagnosticRuns: [provenance],
  wrap: { triangles: [], selections: [], results: [] },
});

SDK-computed evidence requires actual Uint8Array bytes and records SHA-256 plus exact byte length. Caller-declared digests remain explicitly unverified. All evidence is synchronously validated and copied before hashing. Source, dataset fallback, external transformation, layer-comparability rationale, and fail-override references must resolve to the correct artifact scope. Lineage must have unique producers, resolve completely, be acyclic, and contain no orphan evidence.

The manifest contains the complete normalized definition, preparation identity and input audit, filter, cutoffs, expected-grid identity, grouping, review identity, two-gate execution policy, artifact graph, and core/data/compliance versions. The provenance adds the authentic complete result and separate run, result-content, and run-result binding fingerprints. Creation verifies preparation integrity, regenerates review and both gates, reruns core, and compares normalized output before stamping.

The returned VerifiedDiagnosticRunProvenance is frozen and registered in private owner state. A cast, clone, or parsed JSON object cannot author a new bundle. Use verifyDiagnosticRunIdentity(stored, sameRunAndEvidence) to regenerate and authenticate stored provenance; it reports the first mismatching JSON path and returns regenerated authentic review text rather than trusting stored prose.

Wrapped bundles include one deduplicated typed diagnostic-definition document per definition and require the outer SDK versions/generator to agree with every run manifest. verifyBundle also recompiles serialized definitions and rechecks definition, review, result, run, and binding fingerprints plus the typed definition mirror; merely re-stamping inconsistent JSON cannot make it verify. FNV-1a/JCS tags are deterministic integrity aids, not cryptographic authentication.

Material host judgments worth recording in the assumption ledger include amount basis and limit application, expense treatment, missingness, exposure timing, period convention, filters/grouping, communicated scale, and any policy that permits a failed review. Helpers never invent an actuary’s rationale.

The package also provides estimate metadata, assumption ledgers, ASOP No. 41 draft disclosure generation, ASOP No. 56 model cards, actual-versus-expected roll-forward, and canonical reproducibility bundles.

See the formula catalog (docs/reference/diagnostic-formulas.md) and migration guide (docs/migrations/0.6-generalized-diagnostics.md).

Connected review snapshots

The SDK 0.16 verifyReviewRun and createReviewSnapshot APIs replay the complete connected review, retain exact original-byte/mapping evidence and check declared minimum selection, paid-reconciliation, assumption and coverage requirements. Missing originals remain qualified. Parsed/copied receipts cannot authorize bundle or disclosure inclusion; reopen with replayReviewSnapshot. Freezing preserves unresolved requirements and does not attest review or publication. See the full contract and migration notes (docs/reference/review-snapshot.md in the private repository).

Snapshots can also retain complete attached diagnostic, sensitivity and grid studies. Optional profile requirements name exact results and evidence; related subjects and unavailable checks cannot silently satisfy them. Disclosure and bundle replay retain native qualifications and evidence paths. See docs/reference/review-studies.md for the study requirement contract.

The SDK 0.16 surface adds createReserveReviewProfile and exact node-output, source-binding and study evidence links. Required review items can be satisfied, unresolved, explicitly waived where the versioned profile permits it, or declared not applicable. Extended snapshots keep calculation, validation, selection, review and external-release facts separate and derive a convenience stage without claiming publication. Core createSelectedEstimateRange retains human-selected endpoint quantities, supporting result versions, rationale and optional caller materiality; it is explicitly nonprobabilistic. Evidence-linked observations keep descriptive findings separate from caller-authored hypotheses and adopted conclusions.

The tested examples/reserve-review consumer demonstrates exact source-byte bindings, explicit selections and paid controls, frozen readiness, reopening, bundle verification and disclosures. A mismatched control stays unresolved even when its artifact reproduces. Its actual source files also run against cleanly installed packed packages in both supported dependency profiles.

The ULAE model card describes the connected Conger–Nolibos calibration and reserve contract, including shared-calibration evidence, activity-weight judgment, disjoint expense/loss bases and unavailable uncertainty. Portable review evidence retains those findings; a model card does not make the selected weights or ratio appropriate.

The case-outstanding model card distinguishes the native kernel's documented fallbacks from the connected contract's required complete adopted pattern. It records case-practice stability, terminal payout and negative recovery limitations; a model card does not establish that the method or selected ratios are suitable for a portfolio.

The Fisher–Lange model card distinguishes the native kernel's diagonal-disposal and sparse-severity fallbacks from the connected contract's adopted complete assumptions and dated cadence checks. It records ultimate-count, disposal-rate, settlement-severity and trend limitations; a model card does not establish that the inputs or method are suitable for a portfolio.

Compact provenance and replay streams

Introduced in 0.7.0, this separate path retains complete audit evidence without requiring expanded manifest/result objects or one archive-sized identity string. It does not certify dataset capacity or total application memory use. Existing eager provenance and interchange BundleDoc APIs remain available.

| Step | Public API and host responsibility | |---|---| | Produce a genuine completed run | Use the compact validated gateway in @actuarial-ts/data; handle both review and metric blocks. | | Hash actual artifact bytes | digestDiagnosticArtifactChunks returns an authenticated computed digest. Keep a repeatable byte source; hashes without retained original bytes must remain caller-declared. | | Bind run and artifact evidence | createCompactDiagnosticRunIdentity accepts the completed compact run, genuine computed receipts or explicitly declared evidence, and complete preparation lineage. | | Write complete replay evidence | Consume writeDiagnosticReplayStream into a temporary host destination and publish it only after successful completion. openArtifact must reopen the bytes matching each computed digest. | | Independently verify | verifyDiagnosticReplayStream requires explicit host resource limits, reruns the recorded input, and compares complete canonical evidence before issuing a receipt. Success requires the trailer and EOF. |

The host owns file/network I/O, pending-I/O cancellation, retention, and access control. Supply the same abort signal to host I/O and the SDK. Cancellation is cooperative between chunks/phases, not interruption of synchronous calculation. Use summaries/pages for routine views; materializing all findings or identity documents afterward can erase the representation's memory benefit.

VerifiedCompactDiagnosticRunProvenance is a distinct owner-authenticated object, not an eager VerifiedDiagnosticRunProvenance or a serializable authorization token. It cannot be cast into createBundle, the eager verifier, or the current diagnostic agent executor. The stream format is diagnostic-replay/1, separate from interchange wire 1.3.0; it is not a single JSON document or a BundleDoc.

Replay identities include the producing SDK's engine versions. Preserve those exact package versions with stored evidence and use a matching runtime for verification. Stream version 1 does not guarantee cross-SDK-version replay; in particular, a patch upgrade must not be assumed to verify an older stream. Successful replay establishes internal reproducibility, not source authenticity, a digital signature, correct claim-level capping, or actuarial correctness.

Reusable customization replay

writeBoundedAnalysisReplay writes independently recalculable evidence for normalized selected records. writeBoundedHistoryAnalysisReplay adds raw history validation, revision selection, exact/latest evaluation selection, a blocking preparation-review gate, and two host-owned external-state stages. The latter supports mergeable sums, ratios, weighted means, and extrema. Exact distinct counts and type-7 quantiles use writeBoundedAnalysisReplay after the host supplies their required global order. verifyBoundedAnalysisReplay returns a VerifiedBoundedReplayReceipt; use assertVerifiedBoundedReplayReceipt when an authentic in-process receipt is a precondition. Verification requires expectedSourceArtifact, the authentic handle returned by digestDiagnosticArtifactChunks for the source bytes. Parsed or copied JSON cannot satisfy either authenticity check.

All paths require explicit record, partition, memory, input, output, and active scenario ceilings. A ceiling applies to the stated SDK record or frame; it is not a promise about total process RSS or host storage caches. The host owns the adapter, source bytes, output publication, pending-I/O cancellation, and temporary-state durability.

The runnable compact adoption guide (docs/migrations/0.7-compact-diagnostics.md) and complete replay reference (docs/reference/diagnostic-replay-stream.md) document ownership, artifact bytes, paging, framing, resource limits, and assurance boundaries. These repository guides are linked here for npm users; the guide files themselves are not shipped inside the package.

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 adds verified review snapshots, caller-defined readiness, source-bound observations and explicit calculated/saved/published states. A frozen artifact can retain visible limitations and does not itself prove publication. 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.