@actuarial-ts/interchange 0.2.0 → 0.3.0

package/src/convert/triangle.ts

@@ -0,0 +1,208 @@
+import {
+  ReservingError,
+  type Triangle,
+  type TriangleKind,
+  incrementalToCumulative,
+  triangleFromGrid,
+} from "@actuarial-ts/core";
+import {
+  DEFAULT_GENERATOR,
+  INTERCHANGE_SPEC_VERSION,
+  type GeneratorStamp,
+  stampIntegrity,
+} from "../envelope.js";
+import {
+  CORE_MEASURES,
+  type CoreMeasure,
+  type Measure,
+  type OriginLengthMonths,
+  type TriangleBody,
+  type TriangleDoc,
+  triangleDocSchema,
+} from "../schemas/triangle.js";
+
+/**
+ * core `Triangle` ↔ TriangleDoc.
+ *
+ * - The seven core TriangleKind values are the interchange measures of the
+ *   same name, both directions.
+ * - Cadence: annual ("2023") and quarterly ("2023Q3") origin labels derive
+ *   starts and originLengthMonths automatically; anything else needs
+ *   explicit `originStarts` + `originLengthMonths`. Reading 1- or 6-month
+ *   cadences parses with a capability warning (spec 3.2).
+ * - `createdAt` and `valuationDate` are caller-supplied — this module
+ *   never reads a clock (purity rule).
+ * - Null means unobserved, both directions, always.
+ */
+
+export interface TriangleToDocOptions {
+  /** ISO timestamp for the envelope (caller-supplied; purity rule). */
+  createdAt: string;
+  /** ISO yyyy-mm-dd valuation date of the triangle. */
+  valuationDate: string;
+  /** Interchange measure; defaults to the core kind, which maps verbatim. */
+  measure?: Measure;
+  /** Whether values are cumulative. Core triangles are; defaults true. */
+  cumulative?: boolean;
+  /** Override when labels are not annual/quarterly (e.g. semiannual). */
+  originLengthMonths?: OriginLengthMonths;
+  /** Explicit origin period start dates; required when labels do not parse. */
+  originStarts?: string[];
+  basis?: TriangleBody["basis"];
+  units?: TriangleBody["units"];
+  segment?: TriangleBody["segment"];
+  extensions?: Record<string, unknown>;
+  generator?: GeneratorStamp;
+}
+
+interface DerivedOrigin {
+  start: string;
+  lengthMonths: 12 | 3;
+}
+
+function deriveOrigin(label: string): DerivedOrigin | null {
+  const annual = /^(\d{4})$/.exec(label);
+  if (annual) return { start: `${annual[1]}-01-01`, lengthMonths: 12 };
+  const quarterly = /^(\d{4})[Qq]([1-4])$/.exec(label);
+  if (quarterly) {
+    const month = (Number(quarterly[2]) - 1) * 3 + 1;
+    return {
+      start: `${quarterly[1]}-${String(month).padStart(2, "0")}-01`,
+      lengthMonths: 3,
+    };
+  }
+  return null;
+}
+
+export function triangleToDoc(tri: Triangle, options: TriangleToDocOptions): TriangleDoc {
+  let starts = options.originStarts;
+  let lengthMonths = options.originLengthMonths;
+  if (starts === undefined || lengthMonths === undefined) {
+    const derived = tri.origins.map(deriveOrigin);
+    const missing = derived.findIndex((d) => d === null);
+    if (missing >= 0) {
+      throw new ReservingError(
+        "BAD_INTERCHANGE",
+        `Origin label "${tri.origins[missing]}" is neither annual ("2023") nor quarterly ` +
+          `("2023Q3"); supply originStarts and originLengthMonths explicitly`,
+      );
+    }
+    const lengths = new Set(derived.map((d) => d!.lengthMonths));
+    if (lengths.size > 1) {
+      throw new ReservingError(
+        "BAD_INTERCHANGE",
+        "Origin labels mix annual and quarterly forms; supply originStarts and originLengthMonths explicitly",
+      );
+    }
+    starts ??= derived.map((d) => d!.start);
+    lengthMonths ??= derived[0]!.lengthMonths;
+  }
+  if (starts.length !== tri.origins.length) {
+    throw new ReservingError(
+      "BAD_INTERCHANGE",
+      `originStarts has ${starts.length} entries but the triangle has ${tri.origins.length} origins`,
+    );
+  }
+
+  const body: TriangleBody = {
+    measure: options.measure ?? tri.kind,
+    cumulative: options.cumulative ?? true,
+    originLengthMonths: lengthMonths,
+    origins: tri.origins.map((label, i) => ({ label, start: starts![i]! })),
+    agesMonths: [...tri.ages],
+    values: tri.values.map((row) => [...row]),
+    valuationDate: options.valuationDate,
+  };
+  if (options.basis !== undefined) body.basis = options.basis;
+  if (options.units !== undefined) body.units = options.units;
+  if (options.segment !== undefined) body.segment = options.segment;
+
+  const doc = stampIntegrity<TriangleDoc>({
+    interchangeVersion: INTERCHANGE_SPEC_VERSION,
+    kind: "triangle",
+    generator: options.generator ?? DEFAULT_GENERATOR,
+    createdAt: options.createdAt,
+    extensions: options.extensions ?? {},
+    triangle: body,
+  });
+  const checked = triangleDocSchema.safeParse(doc);
+  if (!checked.success) {
+    throw new ReservingError(
+      "BAD_INTERCHANGE",
+      `triangleToDoc produced an invalid document: ${checked.error.issues
+        .map((i) => i.message)
+        .join("; ")}`,
+    );
+  }
+  return checked.data;
+}
+
+export interface DocToTriangleResult {
+  triangle: Triangle;
+  warnings: string[];
+}
+
+function measureToKind(measure: Measure): TriangleKind | null {
+  return (CORE_MEASURES as readonly string[]).includes(measure)
+    ? (measure as CoreMeasure)
+    : null;
+}
+
+/**
+ * TriangleDoc → core `Triangle`. Validates the document SCHEMA (integrity
+ * verification is parseDocument's job — pass documents through it first
+ * when provenance matters), maps the measure to a core kind, cumulates incremental
+ * values through core's `incrementalToCumulative` (with a warning), and
+ * channels reader-capability warnings for 1-/6-month cadences.
+ */
+export function docToTriangle(doc: unknown): DocToTriangleResult {
+  const parsed = triangleDocSchema.safeParse(doc);
+  if (!parsed.success) {
+    throw new ReservingError(
+      "BAD_INTERCHANGE",
+      `Not a valid TriangleDoc: ${parsed.error.issues
+        .map((i) => `${i.path.join(".") || "$"}: ${i.message}`)
+        .join("; ")}`,
+    );
+  }
+  const triangleDoc = parsed.data;
+  const body = triangleDoc.triangle;
+
+  const kind = measureToKind(body.measure);
+  if (kind === null) {
+    throw new ReservingError(
+      "BAD_INTERCHANGE",
+      `Measure "${body.measure}" has no core triangle kind (core kinds: ${CORE_MEASURES.join(", ")}); ` +
+        "premium and custom measures are handled as exposure/reference data, not core triangles",
+    );
+  }
+  if (body.values === undefined) {
+    throw new ReservingError(
+      "BAD_INTERCHANGE",
+      "This triangle carries only a bulk-lane valuesRef; Phase A converters require inline values",
+    );
+  }
+
+  const warnings: string[] = [];
+  if (body.originLengthMonths === 1 || body.originLengthMonths === 6) {
+    warnings.push(
+      `originLengthMonths ${body.originLengthMonths} parsed successfully, but actuarial-ts ` +
+        "computes natively on 12- and 3-month cadences; computation support is limited",
+    );
+  }
+
+  let triangle = triangleFromGrid(
+    kind,
+    body.origins.map((o) => o.label),
+    body.agesMonths,
+    body.values,
+  );
+  if (!body.cumulative) {
+    triangle = incrementalToCumulative(triangle);
+    warnings.push(
+      "Incremental values were cumulated via core incrementalToCumulative (a null stops " +
+        "accumulation for its row); core methods run on cumulative triangles",
+    );
+  }
+  return { triangle, warnings };
+}

package/src/envelope.ts

@@ -0,0 +1,193 @@
+import { ReservingError, canonicalJson, fnv1a64 } from "@actuarial-ts/core";
+import { z } from "zod";
+
+/**
+ * The interchange document envelope (spec 3.1 / 3.5).
+ *
+ * Every interchange document is an envelope around exactly one semantic
+ * body. The envelope carries `interchangeVersion`, `kind`, `generator`,
+ * `createdAt`, `extensions`, and `integrity`; the semantic body is the ONE
+ * kind-named object (`triangle`, `selection`, `result`, `study`,
+ * `report` — and for `kind: "bundle"`, per spec 3.2, the two-field
+ * object `{ bundle, interchange }` the outer tag is defined over).
+ *
+ * Ground truth:
+ * - `integrity` = fnv1a64(canonicalJson(semantic body)) — NEVER the
+ *   envelope. Re-exporting a document through another adapter changes the
+ *   envelope (generator, createdAt), not the tag, so appliesTo-by-tag
+ *   linkage survives cross-language hops. FNV-1a detects ACCIDENTAL
+ *   divergence only; tamper evidence requires host-side signing.
+ * - `governance` (StudyDoc) sits beside the semantic body: it is neither
+ *   envelope nor integrity-covered; adapters round-trip it opaquely.
+ * - Version acceptance (spec 3.5): wrong-major documents are refused with
+ *   `UNSUPPORTED_VERSION`; same-major unknown minors are accepted, unknown
+ *   fields are preserved (schemas are passthrough), and
+ *   `governance`/`extensions` round-trip opaquely.
+ * - `createdAt` is caller-supplied (purity rule) — this module never reads
+ *   a clock.
+ */
+
+/** The interchange spec version this package writes. */
+export const INTERCHANGE_SPEC_VERSION = "1.0.0";
+
+/** The spec major this package accepts (spec 3.5: readers accept same-major). */
+export const INTERCHANGE_SPEC_MAJOR = 1;
+
+/**
+ * This package's version, stamped into `generator` by default. A sync test
+ * asserts it matches package.json so it cannot silently drift.
+ */
+export const INTERCHANGE_PACKAGE_VERSION = "0.3.0";
+
+export interface GeneratorStamp {
+  name: string;
+  version: string;
+}
+
+/** Default `generator` stamp for documents authored by this package. */
+export const DEFAULT_GENERATOR: GeneratorStamp = {
+  name: "@actuarial-ts/interchange",
+  version: INTERCHANGE_PACKAGE_VERSION,
+};
+
+export const DOCUMENT_KINDS = [
+  "triangle",
+  "selection",
+  "method-result",
+  "stochastic-result",
+  "study",
+  "bundle",
+  "crosscheck-report",
+] as const;
+
+export type DocumentKind = (typeof DOCUMENT_KINDS)[number];
+
+/**
+ * kind → the top-level key(s) holding the semantic body. Single-key kinds
+ * hash the named object itself; `bundle` hashes `{ bundle, interchange }`
+ * (spec 3.2's outer tag).
+ */
+const SEMANTIC_BODY_KEYS: Record<DocumentKind, readonly string[]> = {
+  triangle: ["triangle"],
+  selection: ["selection"],
+  "method-result": ["result"],
+  "stochastic-result": ["result"],
+  study: ["study"],
+  bundle: ["bundle", "interchange"],
+  "crosscheck-report": ["report"],
+};
+
+/** A 16-hex-char fnv1a64 tag. */
+export const integritySchema = z.string().regex(/^[0-9a-f]{16}$/);
+
+export const generatorSchema = z
+  .object({ name: z.string().min(1), version: z.string().min(1) })
+  .passthrough();
+
+/**
+ * The shared envelope fields for a document of the given kind. Doc schemas
+ * spread this shape and add their semantic body key(s); every object is
+ * passthrough so unknown same-major minor fields are preserved, keeping
+ * integrity tags stable across a parse → re-serialize hop.
+ */
+export function envelopeShape<K extends DocumentKind>(kind: K) {
+  return {
+    interchangeVersion: z.string().regex(/^\d+\.\d+\.\d+$/),
+    kind: z.literal(kind),
+    generator: generatorSchema,
+    createdAt: z.string().datetime({ offset: true }),
+    extensions: z.record(z.unknown()).optional(),
+    integrity: integritySchema,
+  };
+}
+
+/** Minimal structural view of a document for integrity/version helpers. */
+export interface DocumentLike {
+  kind: string;
+  [key: string]: unknown;
+}
+
+function isKnownKind(kind: string): kind is DocumentKind {
+  return (DOCUMENT_KINDS as readonly string[]).includes(kind);
+}
+
+/**
+ * Extracts the semantic body the integrity tag is defined over. Throws
+ * BAD_INTERCHANGE for unknown kinds or a missing body key.
+ */
+export function semanticBodyOf(doc: DocumentLike): unknown {
+  if (!isKnownKind(doc.kind)) {
+    throw new ReservingError(
+      "BAD_INTERCHANGE",
+      `Unknown document kind "${doc.kind}"; this reader understands: ${DOCUMENT_KINDS.join(", ")}`,
+    );
+  }
+  const keys = SEMANTIC_BODY_KEYS[doc.kind];
+  for (const key of keys) {
+    if (doc[key] === undefined) {
+      throw new ReservingError(
+        "BAD_INTERCHANGE",
+        `Document of kind "${doc.kind}" is missing its semantic body field "${key}"`,
+      );
+    }
+  }
+  if (keys.length === 1) return doc[keys[0]!];
+  const body: Record<string, unknown> = {};
+  for (const key of keys) body[key] = doc[key];
+  return body;
+}
+
+/** integrity = fnv1a64(canonicalJson(semantic body)) — spec 3.1. */
+export function computeIntegrity(doc: DocumentLike): string {
+  return fnv1a64(canonicalJson(semanticBodyOf(doc)));
+}
+
+/** Returns the document with a freshly computed integrity tag. */
+export function stampIntegrity<T extends DocumentLike>(
+  doc: DocumentLike & Omit<T, "integrity">,
+): T {
+  return { ...doc, integrity: computeIntegrity(doc) } as unknown as T;
+}
+
+export interface IntegrityCheck {
+  ok: boolean;
+  /** The tag recomputed from the semantic body. */
+  expected: string;
+  /** The tag the document claims. */
+  actual: string | null;
+}
+
+/** Recomputes the tag from the semantic body and compares to the stated one. */
+export function verifyIntegrity(doc: DocumentLike): IntegrityCheck {
+  const expected = computeIntegrity(doc);
+  const actual = typeof doc["integrity"] === "string" ? (doc["integrity"] as string) : null;
+  return { ok: actual === expected, expected, actual };
+}
+
+export interface ParsedVersion {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+/**
+ * Version acceptance (spec 3.5): parses `interchangeVersion` and refuses
+ * wrong-major documents with UNSUPPORTED_VERSION. Unparseable versions are
+ * BAD_INTERCHANGE (a malformed document, not a future one).
+ */
+export function acceptVersion(version: unknown): ParsedVersion {
+  if (typeof version !== "string" || !/^\d+\.\d+\.\d+$/.test(version)) {
+    throw new ReservingError(
+      "BAD_INTERCHANGE",
+      `interchangeVersion must be a MAJOR.MINOR.PATCH string; got ${JSON.stringify(version)}`,
+    );
+  }
+  const [major, minor, patch] = version.split(".").map(Number) as [number, number, number];
+  if (major !== INTERCHANGE_SPEC_MAJOR) {
+    throw new ReservingError(
+      "UNSUPPORTED_VERSION",
+      `Interchange version ${version} has major ${major}; this reader accepts major ${INTERCHANGE_SPEC_MAJOR} only`,
+    );
+  }
+  return { major, minor, patch };
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from "./envelope.js";
+export * from "./parse.js";
+export * from "./schemas/triangle.js";
+export * from "./schemas/selection.js";
+export * from "./schemas/result.js";
+export * from "./schemas/study.js";
+export * from "./schemas/bundle.js";
+export * from "./schemas/crosscheck.js";
+export * from "./schemas/manifest.js";
+export * from "./convert/triangle.js";
+export * from "./convert/selection.js";
+export * from "./convert/result.js";
+export * from "./referee/profiles.js";
+export * from "./referee/crosscheck.js";
+export * from "./referee/crosscheckStochastic.js";

package/src/parse.ts

@@ -0,0 +1,175 @@
+import { ReservingError } from "@actuarial-ts/core";
+import type { z } from "zod";
+import {
+  type DocumentKind,
+  DOCUMENT_KINDS,
+  acceptVersion,
+  verifyIntegrity,
+} from "./envelope.js";
+import { INTERCHANGE_SCHEMA_MANIFEST } from "./schemas/manifest.js";
+import type { TriangleDoc } from "./schemas/triangle.js";
+import type { SelectionDoc } from "./schemas/selection.js";
+import type { MethodResultDoc, StochasticResultDoc } from "./schemas/result.js";
+import type { StudyDoc } from "./schemas/study.js";
+import type { BundleDoc } from "./schemas/bundle.js";
+import type { CrosscheckReportDoc } from "./schemas/crosscheck.js";
+
+/**
+ * `parseDocument` (spec 4.1): version-checked, schema-validated,
+ * integrity-verified, warning-channeled entry point for any interchange
+ * document.
+ *
+ * Order of checks:
+ * 1. version acceptance (spec 3.5) — wrong major → UNSUPPORTED_VERSION;
+ * 2. kind dispatch — unknown kind → BAD_INTERCHANGE (a new kind is a spec
+ *    minor this reader does not know how to interpret; refusing loudly
+ *    beats pretending);
+ * 3. zod validation (passthrough: unknown same-major minor fields are
+ *    preserved, so a parse → re-serialize hop keeps the integrity tag);
+ * 4. integrity verification — per `strictness`, a mismatched tag either
+ *    refuses (default; accidental divergence is what the tag exists to
+ *    catch) or warns.
+ *
+ * Reader-side capability warnings (spec 3.2): a triangle with
+ * originLengthMonths 1 or 6 parses successfully and reports a warning
+ * that computation support is limited — a reader capability note, not a
+ * format error.
+ */
+
+export type InterchangeDocument =
+  | TriangleDoc
+  | SelectionDoc
+  | MethodResultDoc
+  | StochasticResultDoc
+  | StudyDoc
+  | BundleDoc
+  | CrosscheckReportDoc;
+
+export interface ParseDocumentOptions {
+  /** How to treat a failed integrity check. Default "refuse". */
+  strictness?: "warn" | "refuse";
+}
+
+export interface ParsedDocument {
+  doc: InterchangeDocument;
+  warnings: string[];
+}
+
+const SCHEMA_BY_KIND: ReadonlyMap<DocumentKind, z.ZodTypeAny> = new Map(
+  INTERCHANGE_SCHEMA_MANIFEST.map((entry) => [entry.kind, entry.schema]),
+);
+
+function formatZodError(error: z.ZodError): string {
+  return error.issues
+    .map((issue) => `${issue.path.length > 0 ? `$.${issue.path.join(".")}` : "$"}: ${issue.message}`)
+    .join("; ");
+}
+
+/**
+ * Documents embedded inside a study or bundle, as `<path>` -> document.
+ *
+ * A study carries whole TriangleDocs, SelectionDocs and result documents; a
+ * bundle mirrors the same set under `interchange`. Each is a complete document
+ * with its OWN integrity tag over its OWN body.
+ */
+function embeddedDocuments(doc: InterchangeDocument): { path: string; value: unknown }[] {
+  const found: { path: string; value: unknown }[] = [];
+  const collect = (prefix: string, list: unknown): void => {
+    if (!Array.isArray(list)) return;
+    list.forEach((value, index) => found.push({ path: `${prefix}[${index}]`, value }));
+  };
+  if (doc.kind === "study") {
+    collect("$.study.triangles", doc.study.triangles);
+    collect("$.study.selections", doc.study.selections);
+    collect("$.study.supportingResults", doc.study.supportingResults);
+  } else if (doc.kind === "bundle") {
+    const mirror = (doc as { interchange?: Record<string, unknown> }).interchange;
+    if (mirror !== undefined) {
+      collect("$.interchange.triangles", mirror["triangles"]);
+      collect("$.interchange.selections", mirror["selections"]);
+      collect("$.interchange.results", mirror["results"]);
+    }
+  }
+  return found;
+}
+
+export function parseDocument(
+  value: unknown,
+  options: ParseDocumentOptions = {},
+): ParsedDocument {
+  const strictness = options.strictness ?? "refuse";
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new ReservingError(
+      "BAD_INTERCHANGE",
+      "An interchange document must be a JSON object with interchangeVersion and kind",
+    );
+  }
+  const raw = value as Record<string, unknown>;
+  acceptVersion(raw["interchangeVersion"]);
+
+  const kind = raw["kind"];
+  const schema = typeof kind === "string" ? SCHEMA_BY_KIND.get(kind as DocumentKind) : undefined;
+  if (schema === undefined) {
+    throw new ReservingError(
+      "BAD_INTERCHANGE",
+      `Unknown document kind ${JSON.stringify(kind)}; this reader understands: ${DOCUMENT_KINDS.join(", ")}`,
+    );
+  }
+
+  const parsed = schema.safeParse(raw);
+  if (!parsed.success) {
+    throw new ReservingError(
+      "BAD_INTERCHANGE",
+      `Document of kind "${String(kind)}" failed schema validation: ${formatZodError(parsed.error)}`,
+    );
+  }
+  const doc = parsed.data as InterchangeDocument;
+
+  const warnings: string[] = [];
+  const integrity = verifyIntegrity(doc);
+  if (!integrity.ok) {
+    const message =
+      `Integrity tag mismatch on kind "${doc.kind}": document states ` +
+      `${integrity.actual ?? "(none)"} but the semantic body hashes to ${integrity.expected}. ` +
+      "The document diverged from its stated content after it was stamped.";
+    if (strictness === "refuse") {
+      throw new ReservingError("BAD_INTERCHANGE", message);
+    }
+    warnings.push(message);
+  }
+
+  // Embedded documents carry their own tags, and nothing checked them. That
+  // matters because `appliesTo.triangleIntegrity` is the linkage primitive the
+  // referee relies on: a result claims to apply to a triangle BY TAG, so a
+  // nested triangle whose tag no longer matches its own body makes every such
+  // claim point at something other than what is actually there.
+  for (const { path, value } of embeddedDocuments(doc)) {
+    const nested = verifyIntegrity(value as Parameters<typeof verifyIntegrity>[0]);
+    if (nested.ok) continue;
+    const nestedKind =
+      typeof (value as { kind?: unknown })?.kind === "string"
+        ? (value as { kind: string }).kind
+        : "unknown";
+    const message =
+      `Integrity tag mismatch on the embedded "${nestedKind}" document at ${path}: it states ` +
+      `${nested.actual ?? "(none)"} but its own semantic body hashes to ${nested.expected}. ` +
+      "The enclosing document's tag is intact, so this diverged before it was embedded.";
+    if (strictness === "refuse") {
+      throw new ReservingError("BAD_INTERCHANGE", message);
+    }
+    warnings.push(message);
+  }
+
+  if (doc.kind === "triangle") {
+    const cadence = doc.triangle.originLengthMonths;
+    if (cadence === 1 || cadence === 6) {
+      warnings.push(
+        `originLengthMonths ${cadence} (${cadence === 1 ? "monthly" : "semiannual"}) parsed ` +
+          "successfully, but actuarial-ts computes natively on 12- and 3-month cadences; " +
+          "computation support for this triangle is limited",
+      );
+    }
+  }
+
+  return { doc, warnings };
+}