@actuarial-ts/data

The SDK 0.16 reviewOnLevelRequestSchema, parseReviewOnLevelRequest, calculateReviewOnLevelFromInput and replayReviewOnLevelFromInput expose strict earned-premium, rate-history and calculated-factor boundaries. Review graphs, typed sensitivity controls and historical model policies use the same core calculation. Missing history remains unavailable; source authenticity and earning assumptions remain explicit qualifications.

The SDK 0.16 capping/ILF schemas and parsers provide strict boundaries for exact layer application, fitted or table calibration, and broader-layer application. The corresponding FromInput functions execute and replay the same core operations used by contextual discovery and review-plan nodes. Missing shared membership, table extrapolation and mismatched financial bases are refused. See docs/reference/review-capping-ilf.md in the private repository.

The common modelRequestSchema and parseModelRequest now include the connected Munich Chain Ladder request. Both paid/incurred sources, exact quantities, mask policy, final-column sigma policy and no-tail declaration are strictly parsed. The same schema powers contextual discovery and paired-source review-plan import. See docs/reference/review-munich-chain-ladder.md in the private repository.

The same strict model boundary includes connected case-outstanding requests. It requires a separately typed case source, an adopted complete pattern, latest-joint maturity policy and explicit negative-case treatment. Review-plan import resolves paid, case and assumption nodes through their typed ports. See docs/reference/review-case-outstanding.md in the private repository.

It also includes connected Fisher–Lange requests with an exact closed-count operand, count definition and population relationship, adopted ultimate-count, disposal-pattern and severity-trend assumptions, latest-joint maturity and explicit negative-paid policy. Review-plan import resolves both sources and all three assumptions through typed ports. See docs/reference/review-fisher-lange.md in the private repository.

The SDK 0.16 ULAE calibration and reserve schemas enforce the connected calendar-period, financial-basis, population, assumption and origin-series contracts. Their FromInput functions execute and replay the same native calculations used by discovery and review graphs. Missing required activity measures remain unavailable and a different same-currency scope is refused. See docs/reference/review-ulae.md in the private repository.

The SDK 0.16 discounting schema and parser require complete origin schedules, cash-flow and rate provenance, purpose and discount date, a versioned annual-effective rate assumption, explicit curve/tie-out policies and a separate risk-margin policy. The FromInput calculation and replay functions use the same core validator advertised by contextual discovery and the same typed ports used by review plans. See docs/reference/review-discounting.md in the private repository.

The SDK 0.16 assessEligibilityFromInput API applies safe JSON/Zod boundaries and core's shared eligibility validators. getCapabilityInputSchema exposes the actual execution schema for each advertised contextual capability. Workflow preflight keeps deferred checks explicit and avoids reserve-model fitting; retained preparation and factor/tail calculations may replay during validation. See docs/reference/review-operation-discovery.md in the private repository.

createModelForecastFromInput, scoreModelForecastFromInput and calculateEmergenceFromInput provide strict boundaries for frozen forecasts and A/E evidence. Forecast and scoring graph ports remain distinct; parsing alone does not verify a saved calculation. See docs/reference/review-forecasts.md in the private repository.

resolveHistoricalInformationSetFromInput validates and resolves a declared historical input catalog. Availability evidence, fixed/latest revision rules and exact dependencies remain visible; it does not execute a historical model fold. See docs/reference/historical-information.md in the private repository.

prepareHistoricalReviewFromInput validates selected preparation definitions and binds them to record-level revision selection. The same strict schema supports historical preparation in a review graph; unknown availability remains a visible limitation.

runHistoricalFoldFromInput and runHistoricalStudyFromInput validate selected model policies and compose historical model execution through public core APIs. The same schemas support the fold and study graph operations; forecast coverage remains distinct from independent validation.

Typed ingestion, preparation, and data-review boundaries for the actuarial-ts SDK. It supports loss-run/exposure CSVs, annual claim-development adaptation, triangle assembly, and generalized diagnostic review designed to support ASOP No. 23 work.

The SDK 0.16 createReviewStudyCollection and replayReviewStudyCollection reexecute complete diagnostic/sensitivity/grid studies and bind their subjects to a verified review. Exact review evidence and caller-declared related evidence retain distinct qualifications. See docs/reference/review-studies.md in the private repository for portable documents and snapshot requirements.

The SDK 0.16 runDiagnosticSuite, validateDiagnosticSuiteRequest and replayDiagnosticSuite compose caller-selected source, metric and model checks with explicit gates, retained native evidence and exact replay. Source-check IDs are discoverable through listDiagnosticDataChecks. Descriptive metrics do not certify reserve adequacy; unavailable checks remain not evaluated. See docs/reference/review-diagnostic-suites.md in the private repository.

runReviewSensitivityGridFromInput executes bounded typed parameter grids over the existing review graph, with explicit baseline comparisons and full evidence. expandReviewSensitivityGridFromInput validates and expands without fitting; replayReviewSensitivityGridFromInput verifies saved results by exact execution. See docs/reference/review-sensitivity.md in the private repository.

parseDevelopmentSelectionRequest, selectDevelopmentPatternFromInput and replayDevelopmentSelectionFromInput expose strict imported-data boundaries for native factor/tail intent, supporting assumptions and exact replay. The same schemas support development-selection graph nodes and factor-intent scenarios. See docs/reference/review-development-selection.md in the private repository.

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

Node 20+, ESM. Responsibility for the review and resulting actuarial work remains with the actuary.

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 strict parsers, source mapping, externally staged revision history, and complete customization resource-policy validation. See the 0.8 adoption guide (docs/migrations/0.8-reusable-customization.md) and customization reference (docs/reference/reusable-customization.md).

Declared original-source decoding

The SDK 0.16 decodeReviewSource accepts an explicit JSON member path or a complete historical CSV mapping and returns immutable values and decoding evidence. CSV structural warnings, malformed row widths and rejected mappings refuse verification. It performs no I/O or source authentication. Compliance combines this with byte digests and exact graph-input comparisons; see docs/reference/review-snapshot.md in the private repository.

Existing ingestion and triangle review

parseLossRunCsv, parseExposureCsv, adaptAnnualClaimDevelopment, triangleFromLongFormat, reviewClaimData, and reviewTriangles return structured errors/findings rather than silently cleaning source records. Physical source-line numbers are retained where available.

reviewTriangles(paid, null) explicitly reviews paid-only data and marks missing incurred/cross-triangle checks not-evaluated. A supplied pair with no finite overlapping observations also cannot pass the paid-versus-incurred check. The public examples/reserve-review consumer in the private repository covers both this literature-data path and actual paid/incurred synthetic sources.

Diagnostic run boundary

The example below uses the retained eager path: validateDiagnosticRunInput before runValidatedMetricDiagnostics. Validation parses the entire configuration atomically and compiles its definition; no partially validated run escapes. The compact path below uses the same input model and execution policies with a distinct evidence representation.

import { runValidatedMetricDiagnostics, validateDiagnosticRunInput } from "@actuarial-ts/data";

const validated = validateDiagnosticRunInput({
  definition,
  losses: [{
    rowType: "aggregate",
    recordId: "loss-1",
    sourceGroup: "fleet-a",
    origin: "2025",
    valuation: "2025Q1",
    complete: true,
    source: { artifactId: "loss-run", sourceRow: 2 },
    measures: { reported: 4, "gross-paid": 100, "gross-incurred": 160 },
  }],
  exposures: [{
    key: "exp-2025",
    sourceGroup: "fleet-a",
    origin: "2025",
    measureId: "earned-vehicle-years",
    value: 20,
    complete: true,
    source: { artifactId: "exposures", sourceRow: 2 },
  }],
  filter: { sourceGroups: ["fleet-a"], instanceIds: ["casualty/count/reported-frequency"] },
  groupMap: { "fleet-a": "all-fleet" },
  groupDimensions: { "all-fleet": { region: "all" } },
  runPresetId: "annual-review-v1",
  datasetArtifactId: "loss-run",
});

const outcome = runValidatedMetricDiagnostics(validated);
if (outcome.status !== "completed") console.error(outcome.stage, outcome.review.report);

Loss rows use sourceGroup; output group exists only after explicit mapping. Exposure observations are long-form and measure-specific. origin-static exposures ignore valuation filters but honor source-group/origin selection; valuation-specific exposures require and honor a valuation. The pre-exclusion audit retains invalid, cutoff, filtered, and retained inputs. Omitted and explicitly empty expected-cell grids remain distinct.

Review happens before output-group filtering and calculation. The structural catalog checks identities, periods, measure/source contracts, completeness, exposure attachment, expected-cell coverage, grouping evidence, and cached-formula provenance in deterministic order. Full findings retain code, message, complete source unions, origin, valuation, derived development age, and unit. not-evaluated is not treated as pass.

Definitions add declarative compare, reconcile, monotonic, layer-order, and control-total review rules. createCasualtyDiagnosticReviewRules is an optional convenience factory, not a fixed taxonomy. Missing rule inputs follow each rule’s explicit not-evaluated or finding policy. Review and metric gates have separate allowed status/severity sets; permitting a fail requires a nonblank rationale reference.

Completed outcomes are owner-branded and include the exact prepared data, review receipt, run preset, dataset artifact, grouping, result, and two-gate receipt. Compliance provenance accepts only that completed object.

Compact runs and paged review

Introduced in 0.7.0, validateDiagnosticRunInputCompact followed by runValidatedMetricDiagnosticsCompact retains complete review evidence behind authenticated owners. Check outcome.status before using a completed run: a review-blocked result is null, while a metric-blocked outcome includes its diagnostic result but still cannot authorize provenance. Neither blocked path should be presented as a successfully reviewed analysis.

Compact receipts have summary checks with findingCount, an evaluations store, and a findings store. They do not contain eager per-check finding arrays. Use the store from the same receipt throughout paging:

| Need | Public API | |---|---| | Finding summaries without expanded source lists | pageDiagnosticReviewFindings(receipt.findings, query) from data | | Sources for one finding's stable index | pageDiagnosticReviewFindingSources(receipt.findings, index, query) from data | | Passed, triggered, and not-evaluated evaluation summaries | pageDiagnosticReviewEvaluations(receipt.evaluations, query) from core | | Sources for one evaluation | pageDiagnosticReviewEvaluationSources from core |

Finding-source queries distinguish context and review scope sources. Page results disclose totals and continuation offsets; a summary's source count is not the source list. getDiagnosticReviewFinding and iterateDiagnosticReviewFindings provide full individual findings when needed, but can expand their source arrays. Do not collect every full finding merely to paginate it afterward.

getCompletedCompactDiagnosticRunInput exposes the retained immutable input owner for a genuine completed run. Keeping that run alive also keeps its replay inputs alive; release obsolete runs when the host no longer needs them. Parsed JSON, spreads, and casts cannot recreate these owners. Use createCompactDiagnosticRunIdentity in compliance for compact completed runs; the eager provenance function is not interchangeable.

See the runnable compact adoption guide (docs/migrations/0.7-compact-diagnostics.md) and replay/resource-policy reference (docs/reference/diagnostic-replay-stream.md). Compact representation preserves evidence; it is not a claim that an arbitrary large dataset or host memory budget has passed acceptance.

Compact diagnostic queries

createDiagnosticQueryContext owns one compact run input, and runDiagnosticQueryCompact validates, prepares, reviews, calculates, and gates each requested scope. Queries can replace declared filters, cutoffs, expected cells, grouping, and evidence labels. Definition, source rows, review evidence, and execution policy stay fixed. Eligible clean aggregate selections reuse immutable preparation and exact review evidence; every other selection follows the ordinary compact preparation path. The API does not promise a latency or process-memory target.

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

Review execution host boundary

executeReviewPlan runs the pure review graph one bounded node at a time. It supports exact progress counts, cancellation between nodes, a caller-owned checkpoint store and readback verification after every attempted save. Cold restart recalculates a node before accepting serialized checkpoint content; saved bytes alone never become mathematical execution evidence.

executeReviewArtifactLifecycle keeps calculation, durable save and host publication separate. It verifies the complete artifact reference, derives an idempotency key from that snapshot and a versioned destination, and reports pending, confirmed, unknown, conflicting, failed and cancelled outcomes. The host owns storage, publication, authorization and remote idempotency. See the repository's docs/reference/review-plan.md and tested customization SQLite host for the complete contract and limitations.

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 contextual preflight, typed review inputs, bounded graph execution and a readback-confirmed artifact lifecycle. Development age zero is the structural cumulative origin and always has value 0. 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.