# @actuarial-ts/data

**Prepared package version:** 0.23.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.23-native-observed-facts.md`,
`docs/reference/review-observed-facts.md`,
`docs/migrations/0.22.1-current-input-ownership.md`,
`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.
SDK 0.21 also introduced `comparison.observed` discovery, `observedComparisonRequestSchema`, `parseObservedComparisonRequest`, `assessObservedComparisonEligibilityFromInput`, `runObservedComparisonFromInput`, and `replayObservedComparisonFromInput`. Strict coordinate/semantic matching gates SDK-owned descriptive arithmetic. Source verification remains the trusted host responsibility; calculation does not establish causality or a reserve selection.

All five SDK packages are prepared together at 0.23.0. The interchange wire
remains 1.3.0 and Python/R adapter generator versions remain 0.3.0.

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

SDK 0.18 projects contextual eligibility and checkpoint-verified review
execution into the neutral agent protocol. Data remains the validated execution
boundary; it does not accept tenant identity, formulas or source locations from
a model. 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 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.

```bash
npm install @actuarial-ts/data@0.23.0 @actuarial-ts/core@0.23.0
```

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.

```ts
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`.

SDK 0.19 adds bounded grouped history and corrected neutral paired diagnostics.
See `docs/migrations/0.19-grouped-history-and-origin-zero.md` and
`docs/reference/bounded-grouped-history.md` in the private repository.