@actuarial-ts/interchange 0.2.0 → 0.3.0

package/src/schemas/crosscheck.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { envelopeShape } from "../envelope.js";
+import { engineStampSchema, resultAppliesToSchema } from "./result.js";
+
+/**
+ * CrosscheckReportDoc (spec 3.2 / 5) — the referee's output: engines
+ * compared (with versions and profiles), the appliesTo tags matched,
+ * requested and effective parameter sets, per-origin and total relative
+ * deviations, the tolerance applied, and the verdict.
+ *
+ * Verdicts:
+ * - `agree` / `disagree`: independent recomputations inside/outside the
+ *   tolerance.
+ * - `not-comparable`: the inputs do not describe the same computation
+ *   (mismatched appliesTo tags, differing convention profiles, differing
+ *   origin sets, or a failed injection on either shore).
+ * - `verified-by-value`: the results match but the selection was
+ *   value-only, so no independent recomputation occurred — disclosure
+ *   renders it distinctly so nothing overstates what was checked.
+ */
+
+export const CROSSCHECK_VERDICTS = [
+  "agree",
+  "disagree",
+  "not-comparable",
+  "verified-by-value",
+] as const;
+
+export type CrosscheckVerdict = (typeof CROSSCHECK_VERDICTS)[number];
+
+/** Relative deviations per metric; null = not compared (metric absent on a side). */
+export const deviationCellSchema = z
+  .object({
+    ultimate: z.number().nullable(),
+    unpaid: z.number().nullable(),
+    standardError: z.number().nullable(),
+  })
+  .passthrough();
+
+export const originDeviationSchema = deviationCellSchema
+  .extend({ origin: z.string().min(1) })
+  .passthrough();
+
+const parameterSetSchema = z
+  .object({
+    requested: z.record(z.unknown()),
+    effective: z.record(z.unknown()).nullable(),
+  })
+  .passthrough();
+
+export const crosscheckBodySchema = z
+  .object({
+    engines: z.object({ a: engineStampSchema, b: engineStampSchema }).passthrough(),
+    /** The matched tags; null when the inputs' tags did not match. */
+    appliesTo: resultAppliesToSchema.nullable(),
+    parameters: z.object({ a: parameterSetSchema, b: parameterSetSchema }).passthrough(),
+    tolerance: z
+      .object({
+        central: z.number().positive(),
+        standardError: z.number().positive().nullable(),
+      })
+      .passthrough(),
+    deviations: z
+      .object({
+        perOrigin: z.array(originDeviationSchema),
+        totals: deviationCellSchema,
+      })
+      .passthrough(),
+    verdict: z.enum(CROSSCHECK_VERDICTS),
+    warnings: z.array(z.string()),
+  })
+  .passthrough();
+
+export type CrosscheckBody = z.infer<typeof crosscheckBodySchema>;
+
+export const crosscheckReportDocSchema = z
+  .object({
+    ...envelopeShape("crosscheck-report"),
+    /** Semantic body key per spec rev 2.1: `report` (the head-noun rule). */
+    report: crosscheckBodySchema,
+  })
+  .passthrough();
+
+export type CrosscheckReportDoc = z.infer<typeof crosscheckReportDocSchema>;

package/src/schemas/manifest.ts

@@ -0,0 +1,75 @@
+import type { z } from "zod";
+import type { DocumentKind } from "../envelope.js";
+import { triangleDocSchema } from "./triangle.js";
+import { selectionDocSchema } from "./selection.js";
+import { methodResultDocSchema, stochasticResultDocSchema } from "./result.js";
+import { studyDocSchema } from "./study.js";
+import { bundleDocSchema } from "./bundle.js";
+import { crosscheckReportDocSchema } from "./crosscheck.js";
+
+/**
+ * Schema publication manifest (spec 3.4). The zod schemas here are the
+ * single source of truth; they are mechanically emitted to JSON Schema
+ * under `schema/interchange/1.0/` (committed, URL-referenced by the
+ * Python/R validators). A vitest regenerates and diffs — drift fails the
+ * build; `scripts/emit-schema.ts` rewrites the committed files.
+ *
+ * `emitJsonSchema` takes the zod→JSON-Schema converter as an argument so
+ * `zod-to-json-schema` stays a devDependency (emission is build-time
+ * only; the published package depends on core + zod, nothing else).
+ *
+ * The emitted schemas are the STRUCTURAL contract. TS-side refinements
+ * (rationale-required-for-judgmental, medial-trim scoping, grid shape)
+ * are enforced by the zod schemas and restated in the spec; non-TS
+ * validators implement them as semantic checks beside the JSON Schema.
+ */
+
+export interface SchemaManifestEntry {
+  kind: DocumentKind;
+  fileName: string;
+  schema: z.ZodTypeAny;
+}
+
+export const INTERCHANGE_SCHEMA_MANIFEST: readonly SchemaManifestEntry[] = [
+  { kind: "triangle", fileName: "triangle.schema.json", schema: triangleDocSchema },
+  { kind: "selection", fileName: "selection.schema.json", schema: selectionDocSchema },
+  { kind: "method-result", fileName: "method-result.schema.json", schema: methodResultDocSchema },
+  {
+    kind: "stochastic-result",
+    fileName: "stochastic-result.schema.json",
+    schema: stochasticResultDocSchema,
+  },
+  { kind: "study", fileName: "study.schema.json", schema: studyDocSchema },
+  { kind: "bundle", fileName: "bundle.schema.json", schema: bundleDocSchema },
+  {
+    kind: "crosscheck-report",
+    fileName: "crosscheck-report.schema.json",
+    schema: crosscheckReportDocSchema,
+  },
+];
+
+/** Options both the emit script and the drift test must pass to the converter. */
+export function emitOptionsFor(kind: DocumentKind): { name: string; [key: string]: unknown } {
+  return { name: kind, target: "jsonSchema7", $refStrategy: "none" };
+}
+
+export interface EmittedSchema {
+  kind: DocumentKind;
+  fileName: string;
+  /** The serialized file content, byte-exact (2-space indent + trailing newline). */
+  content: string;
+}
+
+/**
+ * Emits every document kind's JSON Schema through the supplied converter
+ * (pass `zod-to-json-schema`'s default export). Build-time only.
+ */
+export function emitJsonSchema(
+  convert: (schema: z.ZodTypeAny, options: { name: string }) => unknown,
+): EmittedSchema[] {
+  return INTERCHANGE_SCHEMA_MANIFEST.map(({ kind, fileName, schema }) => ({
+    kind,
+    fileName,
+    content: `${JSON.stringify(convert(schema, emitOptionsFor(kind)), null, 2)}\n`,
+  }));
+}

package/src/schemas/result.ts

@@ -0,0 +1,180 @@
+import { z } from "zod";
+import { envelopeShape, generatorSchema, integritySchema } from "../envelope.js";
+
+/**
+ * MethodResultDoc / StochasticResultDoc (spec 3.2).
+ *
+ * - `appliesTo` links results to their inputs by integrity tag;
+ *   `selectionIntegrity` is null for runs with no selection document.
+ * - Method namespaces: actuarial-ts discriminants unprefixed, `clpy:` for
+ *   chainladder-python, `rcl:` for R ChainLadder.
+ * - `effectiveParameters` records what the engine ACTUALLY did when it
+ *   deviated from what was requested (R's est.sigma auto-fallback);
+ *   absent = as requested. The referee downgrades requested≠effective
+ *   comparisons with a comparability warning.
+ * - StochasticResultDoc adds seed/nSims/summary/byOrigin; samples travel
+ *   only via `samplesRef` in the bulk lane. Cross-engine stochastic
+ *   comparison is distribution-level only.
+ */
+
+export const resultAppliesToSchema = z
+  .object({
+    triangleIntegrity: integritySchema,
+    selectionIntegrity: integritySchema.nullable(),
+  })
+  .passthrough();
+
+export type ResultAppliesTo = z.infer<typeof resultAppliesToSchema>;
+
+export const engineStampSchema = generatorSchema
+  .extend({ conventionProfile: z.string().optional() })
+  .passthrough();
+
+export type EngineStamp = z.infer<typeof engineStampSchema>;
+
+export const methodResultRowSchema = z
+  .object({
+    origin: z.string().min(1),
+    ultimate: z.number().finite(),
+    unpaid: z.number().finite(),
+    standardError: z.number().finite().optional(),
+  })
+  .passthrough();
+
+export type MethodResultRow = z.infer<typeof methodResultRowSchema>;
+
+export const methodResultTotalsSchema = z
+  .object({
+    ultimate: z.number().finite(),
+    unpaid: z.number().finite(),
+    standardError: z.number().finite().optional(),
+  })
+  .passthrough();
+
+export type MethodResultTotals = z.infer<typeof methodResultTotalsSchema>;
+
+const resultCommonShape = {
+  appliesTo: resultAppliesToSchema,
+  engine: engineStampSchema,
+  method: z.string().min(1),
+  parameters: z.record(z.unknown()),
+  effectiveParameters: z.record(z.unknown()).optional(),
+  warnings: z.array(z.string()).optional(),
+};
+
+export const methodResultBodySchema = z
+  .object({
+    ...resultCommonShape,
+    rows: z.array(methodResultRowSchema),
+    totals: methodResultTotalsSchema,
+  })
+  .passthrough();
+
+export type MethodResultBody = z.infer<typeof methodResultBodySchema>;
+
+export const methodResultDocSchema = z
+  .object({
+    ...envelopeShape("method-result"),
+    result: methodResultBodySchema,
+  })
+  .passthrough();
+
+export type MethodResultDoc = z.infer<typeof methodResultDocSchema>;
+
+/** Bulk-lane reference for raw simulation output (spec 3.3). */
+export const samplesRefSchema = z
+  .object({ format: z.literal("arrow"), path: z.string().min(1), sha256: z.string().min(1) })
+  .passthrough();
+
+export const stochasticSummarySchema = z
+  .object({
+    mean: z.number().finite(),
+    sd: z.number().finite(),
+    cv: z.number().finite().nullable(),
+    /** e.g. { "75": ..., "95": ... } — percentile label → value. */
+    percentiles: z.record(z.number().finite()),
+  })
+  .passthrough();
+
+/**
+ * How much a consumer may rely on re-running this result.
+ *
+ * A seed is NOT the same guarantee as reproducibility: it removes one source
+ * of variance, but the engine underneath may still be non-deterministic. This
+ * field says which promise the document actually carries, so an actuary knows
+ * whether they hold a derivation anyone can regenerate or an observation
+ * somebody recorded.
+ *
+ * - `seeded-reproducible` — re-running with this seed reproduces this document
+ *   byte-for-byte. @actuarial-ts/core's own stochastic layer is this
+ *   (packages/core/test/odpBootstrap.test.ts pins it), because it uses a seeded
+ *   PRNG with no ambient randomness.
+ * - `witnessed` — the engine is NOT byte-reproducible even under a fixed seed.
+ *   The document is an integrity-checked record of what that engine produced on
+ *   that run, not something a reviewer can regenerate. Still legitimate ASOP
+ *   No. 56 evidence — it just supports an attestation, not a replay.
+ *
+ * Absent means unstated (documents written before this field existed); treat
+ * an absent value as unknown, never as a reproducibility guarantee.
+ *
+ * Deterministic methods do not carry this field: kind `method-result` already
+ * implies reproducibility, and the frozen conformance corpus proves it across
+ * three independent shores.
+ */
+export const reproducibilitySchema = z.enum(["seeded-reproducible", "witnessed"]);
+
+export type Reproducibility = z.infer<typeof reproducibilitySchema>;
+
+/**
+ * The engine's own self-check: it ran the identical seeded request more than
+ * once and reports whether the runs agreed. This is what lets a
+ * non-reproducible engine be HONEST rather than silently unstable — the
+ * instability is measured and disclosed on the document instead of surfacing
+ * later as a mysteriously failing test.
+ */
+export const stabilityCheckSchema = z
+  .object({
+    /** How many independent runs of the identical seeded request were compared (>= 2). */
+    repeats: z.number().int().min(2),
+    /** True when every repeat produced the identical semantic body. */
+    byteIdentical: z.boolean(),
+    /**
+     * Worst relative deviation observed across repeats on the summary mean,
+     * using the cross-shore definition |a-b| / max(|a|,|b|). Null when not
+     * computable. Zero with byteIdentical=false means the bodies differed
+     * somewhere other than the summary mean.
+     */
+    maxRelativeDeviation: z.number().finite().nonnegative().nullable(),
+  })
+  .passthrough();
+
+export type StabilityCheck = z.infer<typeof stabilityCheckSchema>;
+
+export const stochasticResultBodySchema = z
+  .object({
+    ...resultCommonShape,
+    seed: z.number().int().optional(),
+    nSims: z.number().int().positive(),
+    /** Which reproducibility promise this document carries; see the schema doc. */
+    reproducibility: reproducibilitySchema.optional(),
+    /** The engine's repeat-run self-check, when it performed one. */
+    stability: stabilityCheckSchema.optional(),
+    summary: stochasticSummarySchema,
+    byOrigin: z.array(z.object({ origin: z.string().min(1) }).passthrough()),
+    samplesRef: samplesRefSchema.optional(),
+    /** Point-estimate rows/totals may accompany the distribution summary. */
+    rows: z.array(methodResultRowSchema).optional(),
+    totals: methodResultTotalsSchema.optional(),
+  })
+  .passthrough();
+
+export type StochasticResultBody = z.infer<typeof stochasticResultBodySchema>;
+
+export const stochasticResultDocSchema = z
+  .object({
+    ...envelopeShape("stochastic-result"),
+    result: stochasticResultBodySchema,
+  })
+  .passthrough();
+
+export type StochasticResultDoc = z.infer<typeof stochasticResultDocSchema>;

package/src/schemas/selection.ts

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { envelopeShape, integritySchema } from "../envelope.js";
+import { measureSchema } from "./triangle.js";
+
+/**
+ * SelectionDoc (spec 3.2): intent + values, with the coherence rule.
+ *
+ * - Intent is authoritative for replay and promotion; values are
+ *   authoritative only for `judgmental`/`external` intents, whose
+ *   `rationale` is REQUIRED (it carries the judgment's justification).
+ * - `windowOriginPeriods` counts ORIGIN PERIODS in the triangle's own
+ *   cadence; omitted = all periods.
+ * - `excludeHigh`/`excludeLow` are medial trims and are valid ONLY with
+ *   `kind: "medial"` (the spec's normative comment; its illustrative
+ *   example showing zeros on a volume-weighted intent is not).
+ * - The coherence rule itself (recompute computable intents within 1e-9
+ *   relative, warn|refuse on divergence) is enforced by
+ *   `convert/selection.ts`, not by this structural schema.
+ */
+
+export const DEVELOPMENT_INTENT_KINDS = [
+  "volume-weighted",
+  "simple",
+  "regression",
+  "geometric",
+  "medial",
+  "judgmental",
+  "external",
+] as const;
+
+export type DevelopmentIntentKind = (typeof DEVELOPMENT_INTENT_KINDS)[number];
+
+/** Intent kinds whose `value` is the judgment itself (never recomputed). */
+export const VALUE_AUTHORITATIVE_KINDS = ["judgmental", "external"] as const;
+
+export const exclusionSchema = z
+  .object({ origin: z.string().min(1), reason: z.string().optional() })
+  .passthrough();
+
+function requireRationale(
+  intent: { kind: string; rationale?: string | undefined },
+  ctx: z.RefinementCtx,
+): void {
+  if (
+    (VALUE_AUTHORITATIVE_KINDS as readonly string[]).includes(intent.kind) &&
+    (intent.rationale === undefined || intent.rationale.trim() === "")
+  ) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `rationale is required when intent kind is "${intent.kind}"`,
+      path: ["rationale"],
+    });
+  }
+}
+
+export const developmentIntentSchema = z
+  .object({
+    kind: z.enum(DEVELOPMENT_INTENT_KINDS),
+    windowOriginPeriods: z.number().int().positive().optional(),
+    excludeHigh: z.number().int().nonnegative().optional(),
+    excludeLow: z.number().int().nonnegative().optional(),
+    exclusions: z.array(exclusionSchema).optional(),
+    rationale: z.string().optional(),
+  })
+  .passthrough()
+  .superRefine((intent, ctx) => {
+    requireRationale(intent, ctx);
+    if (intent.kind !== "medial") {
+      for (const field of ["excludeHigh", "excludeLow"] as const) {
+        if (intent[field] !== undefined) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `${field} is a medial trim; it is valid only with kind "medial"`,
+            path: [field],
+          });
+        }
+      }
+    }
+  });
+
+export type DevelopmentIntent = z.infer<typeof developmentIntentSchema>;
+
+export const developmentSelectionSchema = z
+  .object({
+    fromAgeMonths: z.number().int().positive(),
+    toAgeMonths: z.number().int().positive(),
+    value: z.number().finite(),
+    intent: developmentIntentSchema,
+  })
+  .passthrough()
+  .superRefine((entry, ctx) => {
+    if (entry.toAgeMonths <= entry.fromAgeMonths) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "toAgeMonths must be greater than fromAgeMonths",
+        path: ["toAgeMonths"],
+      });
+    }
+  });
+
+export type DevelopmentSelection = z.infer<typeof developmentSelectionSchema>;
+
+export const TAIL_FAMILIES = ["exponential-decay", "inverse-power"] as const;
+
+export type TailFamily = (typeof TAIL_FAMILIES)[number];
+
+export const tailIntentSchema = z
+  .discriminatedUnion("kind", [
+    z
+      .object({
+        kind: z.literal("fitted"),
+        family: z.enum(TAIL_FAMILIES),
+        /** First development age (months) included in the fit; omitted = all. */
+        fitFromAgeMonths: z.number().int().positive().optional(),
+        /** Informative fit coefficients; the coherence check refits from data. */
+        params: z
+          .object({ intercept: z.number(), slope: z.number() })
+          .passthrough()
+          .optional(),
+      })
+      .passthrough(),
+    z
+      .object({ kind: z.literal("judgmental"), rationale: z.string().optional() })
+      .passthrough(),
+    z
+      .object({ kind: z.literal("external"), rationale: z.string().optional() })
+      .passthrough(),
+  ])
+  .superRefine((intent, ctx) => {
+    requireRationale(intent, ctx);
+  });
+
+export type TailIntent = z.infer<typeof tailIntentSchema>;
+
+export const tailSelectionSchema = z
+  .object({ value: z.number().finite(), intent: tailIntentSchema })
+  .passthrough();
+
+export type TailSelection = z.infer<typeof tailSelectionSchema>;
+
+export const selectionAppliesToSchema = z
+  .object({ measure: measureSchema, triangleIntegrity: integritySchema })
+  .passthrough();
+
+export const selectionBodySchema = z
+  .object({
+    appliesTo: selectionAppliesToSchema,
+    development: z.array(developmentSelectionSchema),
+    tail: tailSelectionSchema.optional(),
+  })
+  .passthrough();
+
+export type SelectionBody = z.infer<typeof selectionBodySchema>;
+
+export const selectionDocSchema = z
+  .object({
+    ...envelopeShape("selection"),
+    selection: selectionBodySchema,
+  })
+  .passthrough();
+
+export type SelectionDoc = z.infer<typeof selectionDocSchema>;
+
+/** True when every intent in the selection is judgmental/external — i.e., a
+ * replay applies values directly and no independent recomputation occurs
+ * (the referee's `verified-by-value` case). */
+export function isValueOnlySelection(body: SelectionBody): boolean {
+  const devValueOnly = body.development.every((d) =>
+    (VALUE_AUTHORITATIVE_KINDS as readonly string[]).includes(d.intent.kind),
+  );
+  const tailValueOnly =
+    body.tail === undefined ||
+    (VALUE_AUTHORITATIVE_KINDS as readonly string[]).includes(body.tail.intent.kind);
+  return devValueOnly && tailValueOnly;
+}

package/src/schemas/study.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { envelopeShape, type GeneratorStamp } from "../envelope.js";
+import { type TriangleDoc, triangleDocSchema } from "./triangle.js";
+import { type SelectionDoc, selectionDocSchema } from "./selection.js";
+import {
+  type MethodResultDoc,
+  type StochasticResultDoc,
+  methodResultDocSchema,
+  stochasticResultDocSchema,
+} from "./result.js";
+
+/**
+ * StudyDoc (spec 3.2) — the promotion unit: a notebook study packaged for
+ * the governed workflow.
+ *
+ * - `narrative.summary` must be non-empty (adapters refuse an empty
+ *   summary; the Python `save_study` does the same).
+ * - `supportingResults` is OPTIONAL: when absent, promotion Gate 2 verifies
+ *   coherence + replays with no cross-engine referee step.
+ * - `expectations.replayTolerance` is subject to the host ceiling at
+ *   promotion time (spec 6) — the schema carries it, the host enforces it.
+ * - `governance` sits BESIDE the semantic body: reserved, round-tripped
+ *   opaquely by every adapter, not covered by the integrity tag (which
+ *   covers the `study` object only, per spec 3.1).
+ *
+ * The interfaces are written out (rather than z.infer'd) because the
+ * composite document types exceed tsc's declaration-emit serialization
+ * limit; the schemas are annotated with them, so the two cannot drift
+ * without a compile error.
+ */
+
+export interface StudyNarrative {
+  analyst?: string;
+  sourceRef?: string;
+  summary: string;
+  [key: string]: unknown;
+}
+
+export interface StudyExpectations {
+  replayTolerance?: number;
+  [key: string]: unknown;
+}
+
+export interface StudyBody {
+  title: string;
+  narrative: StudyNarrative;
+  triangles: TriangleDoc[];
+  selections: SelectionDoc[];
+  supportingResults?: (MethodResultDoc | StochasticResultDoc)[];
+  expectations?: StudyExpectations;
+  [key: string]: unknown;
+}
+
+export interface StudyDoc {
+  interchangeVersion: string;
+  kind: "study";
+  generator: GeneratorStamp & { [key: string]: unknown };
+  createdAt: string;
+  extensions?: Record<string, unknown>;
+  integrity: string;
+  study: StudyBody;
+  /** Reserved; round-tripped opaquely by non-TS adapters. */
+  governance?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export const studyNarrativeSchema: z.ZodType<StudyNarrative> = z
+  .object({
+    analyst: z.string().optional(),
+    sourceRef: z.string().optional(),
+    summary: z.string().min(1),
+  })
+  .passthrough();
+
+export const studyExpectationsSchema: z.ZodType<StudyExpectations> = z
+  .object({ replayTolerance: z.number().positive().optional() })
+  .passthrough();
+
+export const studyBodySchema: z.ZodType<StudyBody> = z
+  .object({
+    title: z.string().min(1),
+    narrative: studyNarrativeSchema,
+    triangles: z.array(triangleDocSchema),
+    selections: z.array(selectionDocSchema),
+    supportingResults: z
+      .array(z.union([methodResultDocSchema, stochasticResultDocSchema]))
+      .optional(),
+    expectations: studyExpectationsSchema.optional(),
+  })
+  .passthrough();
+
+export const studyDocSchema: z.ZodType<StudyDoc> = z
+  .object({
+    ...envelopeShape("study"),
+    study: studyBodySchema,
+    governance: z.record(z.unknown()).optional(),
+  })
+  .passthrough();