@actuarial-ts/data

Typed ingestion, preparation, data review and host execution boundaries for the actuarial-ts SDK. Use this package to admit external inputs before calling core calculations and to retain structured findings when work is unavailable.

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.

Public input schemas

The SDK's schemas use its Zod 4 dependency. Keep wrapper types and any schemas composed with them on Zod 4; unrelated application forms may use another version. For JSON Schema input descriptions, use toBoundaryJsonSchema(schema, { io: "input" }) on the complete schema. This retains the SDK's dictionary contracts, including literal __proto__ keys, and declarations for core-validated payloads without losing recursive references. A generated description does not execute refinements or transforms; admit the actual request through its owning parser.

Ingestion and source review

parseLossRunCsv, parseExposureCsv, adaptAnnualClaimDevelopment, triangleFromLongFormat, reviewClaimData and reviewTriangles expose structured errors/findings instead of silently cleaning records. Physical source-line numbers are retained where available. reviewTriangles(paid, null) reviews paid-only data and marks missing incurred/cross-triangle checks not-evaluated.

decodeReviewSource uses an explicit JSON member path or complete CSV mapping. Malformed rows and rejected mappings refuse verification. It performs no I/O or source authentication; the host supplies original bytes and access controls.

Diagnostic run boundary

Supply a complete caller-authored diagnostic definition and the original selected loss/exposure records. Validation is atomic; the run then applies separate review and metric execution gates:

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 groups arise only through explicit mapping. Exposure observations are long-form and measure-specific. origin-static exposure honors source-group/origin filters; valuation-specific exposure also requires and honors valuation. Invalid, cutoff, filtered and retained records remain in the audit. Omitted and explicitly empty expected-cell grids have different meanings.

Review checks source and measure contracts, identities, periods, completeness, exposure attachment, expected cells and grouping evidence. Declarative rules include compare, reconcile, monotonic, layer-order and control-total. not-evaluated is not a pass. Allowing a failed gate requires an explicit rationale. Only a completed owner-authenticated outcome can authorize compliance provenance.

Compact runs and queries

validateDiagnosticRunInputCompact and runValidatedMetricDiagnosticsCompact retain complete review evidence behind authenticated owners. A review-blocked outcome has no result; a metric-blocked outcome retains its diagnostic result but cannot authorize provenance. Check the outcome before presenting a completed run.

| Need | Public API | |---|---| | Finding summaries | pageDiagnosticReviewFindings(receipt.findings, query) | | Sources for one finding | pageDiagnosticReviewFindingSources(receipt.findings, index, query) | | Passed, triggered and not-evaluated evaluations | Core pageDiagnosticReviewEvaluations(receipt.evaluations, query) | | Sources for one evaluation | Core pageDiagnosticReviewEvaluationSources |

Use stores from the same receipt throughout paging. Full findings can expand large source arrays. Compact representation is not a promise about total application memory or arbitrary dataset capacity. getCompletedCompactDiagnosticRunInput exposes the retained input owner; release obsolete runs when they are no longer needed.

createDiagnosticQueryContext and runDiagnosticQueryCompact apply changed filters, cutoffs, expected cells and grouping to one owned compact input. Definition, records, review evidence and execution policy stay fixed. Eligible scopes share immutable preparation; other scopes follow ordinary preparation with the same gates.

Discovery and review execution

Use listCapabilities to discover operations and their actual input schemas. Contextual preflight keeps deferred checks visible and does not fit reserve models; preparation and factor/tail checks may still perform native work. The *FromInput APIs validate unknown requests before delegating to the owning core operation. Parsing a result is not verification of its calculations.

executeReviewPlan runs the review graph with progress, between-node cancellation and an optional host checkpoint store. Cold restart recalculates a node before accepting serialized checkpoint content. verifyReviewPlanRunFromInput preserves an exact authentic current-process run; replayReviewPlanRunFromInput explicitly executes the graph again. Both return ReviewPlanVerification and enforce limits.

An authored limits.evidenceAccounting profile measures shared storage separately from logical expansion. An omitted profile uses DEFAULT_REVIEW_EVIDENCE_ACCOUNTING through that same graph owner; it does not select a second expanded-JSON implementation. Every restored checkpoint is compared completely; stored bytes and saved profiles do not create calculation authority.

executeReviewArtifactLifecycle separates calculation, durable save and publication. It verifies artifact references/readback and reports pending, confirmed, unknown, conflicting, failed and cancelled outcomes. The host owns storage, authorization, remote idempotency and publication.

For historical work, prepareHistoricalReviewFromInput, runHistoricalFoldFromInput and runHistoricalStudyFromInput retain revision/availability evidence, explicit assumptions and unavailable folds. Software version compatibility is separate from historical valuation analysis. examples/reserve-review and examples/customization-review in the private repository show host integration.

License

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