@actuarial-ts/core 0.7.0 → 0.8.0

package/src/descriptiveStatistics.ts

@@ -0,0 +1,320 @@
+import type {
+  AnalysisMeasureDefinitionV1,
+  AnalysisObservationSelection,
+  AnalysisStatisticResult,
+  CustomizationCapabilityFinding,
+  HistoricalRelationships,
+  PreparedHistoricalObservation,
+} from "./customizationContracts.js";
+import { isRealIsoDate, snapshotDiagnosticJson } from "./diagnosticRuntime.js";
+import { daysBetweenIsoDates } from "./policyPeriods.js";
+import { kaplanMeierQuantiles } from "./ilf.js";
+
+function claimKey(observation: PreparedHistoricalObservation): string {
+  return `${observation.sourceNamespace}\u0000${observation.claimId}`;
+}
+
+function entityIds(
+  entity: Extract<AnalysisMeasureDefinitionV1["statistic"], { kind: "distinct-count" }>["entity"],
+  observation: PreparedHistoricalObservation,
+): readonly string[] {
+  if (entity === "claim") return [claimKey(observation)];
+  const field: keyof HistoricalRelationships =
+    entity === "claimant"
+      ? "claimantIds"
+      : entity === "occurrence"
+        ? "occurrenceId"
+        : entity === "policy"
+          ? "policyIds"
+          : "coverageIds";
+  const raw = observation.relationships[field];
+  const ids = raw === undefined ? [] : Array.isArray(raw) ? raw : [raw];
+  return ids.map((id) => `${observation.sourceNamespace}\u0000${id}`);
+}
+
+function selectObservations(
+  observations: readonly PreparedHistoricalObservation[],
+  selection: AnalysisObservationSelection,
+): readonly PreparedHistoricalObservation[] {
+  if (selection.kind === "all-observations") return observations;
+  if (selection.observationSelection === "exact")
+    return observations.filter((observation) => observation.evaluationDate === selection.evaluationDate);
+  const latest = new Map<string, PreparedHistoricalObservation>();
+  for (const observation of observations) {
+    if (observation.evaluationDate > selection.evaluationDate) continue;
+    const key = claimKey(observation);
+    const prior = latest.get(key);
+    if (prior === undefined || prior.evaluationDate < observation.evaluationDate)
+      latest.set(key, observation);
+  }
+  return [...latest.values()].sort((left, right) => claimKey(left).localeCompare(claimKey(right)));
+}
+
+function finding(
+  message: string,
+  code: CustomizationCapabilityFinding["code"] = "missing-prerequisite",
+): CustomizationCapabilityFinding {
+  return {
+    code,
+    capability: "descriptive-statistics",
+    path: "$.measure.statistic",
+    message,
+  };
+}
+
+function unavailable(
+  measure: AnalysisMeasureDefinitionV1,
+  excludedObservations: number,
+  findings: readonly CustomizationCapabilityFinding[],
+): AnalysisStatisticResult {
+  return snapshotDiagnosticJson({
+    measureId: measure.id,
+    unit: measure.unit,
+    value: null,
+    status: "unavailable",
+    contributingObservations: 0,
+    excludedObservations,
+    exact: true,
+    numerator: null,
+    denominator: null,
+    findings,
+  });
+}
+
+function sourceValue(
+  observation: PreparedHistoricalObservation,
+  measureId: string,
+): number | null | undefined {
+  const value = observation.measures[measureId];
+  return value === undefined || value === null || !Number.isFinite(value) ? value : Object.is(value, -0) ? 0 : value;
+}
+
+function hfType7(values: readonly number[], probability: number): number {
+  const sorted = [...values].sort((left, right) => left - right);
+  if (sorted.length === 1) return sorted[0]!;
+  const index = (sorted.length - 1) * probability;
+  const lower = Math.floor(index);
+  const fraction = index - lower;
+  return sorted[lower]! + fraction * (sorted[Math.min(lower + 1, sorted.length - 1)]! - sorted[lower]!);
+}
+
+function durationValue(
+  observation: PreparedHistoricalObservation,
+  statistic: Extract<AnalysisMeasureDefinitionV1["statistic"], { kind: "duration" }>,
+): number | null {
+  const start = statistic.start === "accident-date" ? observation.accidentDate : observation.reportDate;
+  const closed = observation.dimensions.closedDate;
+  const end =
+    statistic.end === "report-date"
+      ? observation.reportDate
+      : statistic.end === "evaluation-date"
+        ? observation.evaluationDate
+        : typeof closed === "string" && isRealIsoDate(closed)
+          ? closed
+          : null;
+  if (start === null || end === null) return null;
+  const days = daysBetweenIsoDates(start, end);
+  return days < 0 ? null : days;
+}
+
+/** Calculates one exact statistic over an explicitly selected observation population. */
+export function calculateAnalysisStatistic(input: {
+  readonly measure: AnalysisMeasureDefinitionV1;
+  readonly observations: readonly PreparedHistoricalObservation[];
+  readonly selection: AnalysisObservationSelection;
+}): AnalysisStatisticResult {
+  const { measure, selection } = input;
+  if (measure.developmentSemantics === "cumulative" && selection.kind === "all-observations")
+    return unavailable(
+      measure,
+      input.observations.length,
+      [finding("Cumulative measures require an explicit evaluation-date selection", "incompatible-semantics")],
+    );
+  const observations = selectObservations(input.observations, selection);
+  const statistic = measure.statistic;
+
+  if (statistic.kind === "ratio") {
+    let numerator = 0;
+    let denominator = 0;
+    let included = 0;
+    for (const observation of observations) {
+      const numeratorValue = sourceValue(observation, statistic.numeratorMeasureId);
+      const denominatorValue = sourceValue(observation, statistic.denominatorMeasureId);
+      if (typeof numeratorValue !== "number" || typeof denominatorValue !== "number") continue;
+      numerator += numeratorValue;
+      denominator += denominatorValue;
+      included += 1;
+    }
+    const validDenominator = statistic.denominatorRule === "positive" ? denominator > 0 : denominator !== 0;
+    if (included === 0 || !validDenominator)
+      return snapshotDiagnosticJson({
+        measureId: measure.id,
+        unit: measure.unit,
+        value: null,
+        status: "unavailable",
+        contributingObservations: included,
+        excludedObservations: input.observations.length - included,
+        exact: true,
+        numerator: included === 0 ? null : numerator,
+        denominator: included === 0 ? null : denominator,
+        findings: [finding("Ratio requires paired values and a denominator allowed by its declared rule")],
+      });
+    return snapshotDiagnosticJson({
+      measureId: measure.id,
+      unit: measure.unit,
+      value: (numerator / denominator) * statistic.scale,
+      status: "available",
+      contributingObservations: included,
+      excludedObservations: input.observations.length - included,
+      exact: true,
+      numerator,
+      denominator,
+      findings: [],
+    });
+  }
+
+  if (statistic.kind === "distinct-count") {
+    const ids = new Set<string>();
+    let missing = 0;
+    for (const observation of observations) {
+      const related = entityIds(statistic.entity, observation);
+      if (related.length === 0) missing += 1;
+      related.forEach((id) => ids.add(id));
+    }
+    return snapshotDiagnosticJson({
+      measureId: measure.id,
+      unit: measure.unit,
+      value: ids.size,
+      status: "available",
+      contributingObservations: observations.length - missing,
+      excludedObservations: input.observations.length - observations.length + missing,
+      exact: true,
+      numerator: null,
+      denominator: null,
+      findings: [],
+    });
+  }
+
+  if (statistic.kind === "duration") {
+    const values = observations
+      .filter((observation) => statistic.population !== "closed-only" || observation.status === "closed")
+      .map((observation) => durationValue(observation, statistic))
+      .filter((value): value is number => value !== null);
+    if (values.length === 0)
+      return unavailable(measure, input.observations.length, [finding("No observations have the required duration endpoints")]);
+    const value = values.reduce((total, item) => total + item, 0) / values.length;
+    return snapshotDiagnosticJson({
+      measureId: measure.id,
+      unit: measure.unit,
+      value,
+      status: "available",
+      contributingObservations: values.length,
+      excludedObservations: input.observations.length - values.length,
+      exact: true,
+      numerator: null,
+      denominator: null,
+      findings: [],
+    });
+  }
+
+  if (statistic.kind === "survival-quantile") {
+    if (statistic.probability < 0 || statistic.probability > 1)
+      return unavailable(measure, input.observations.length, [finding("Survival probability must be between zero and one", "invalid-configuration")]);
+    const exact: number[] = [];
+    const censored: number[] = [];
+    for (const observation of observations) {
+      const start = statistic.start === "accident-date" ? observation.accidentDate : observation.reportDate;
+      const suppliedClosedDate = observation.dimensions.closedDate;
+      const isObservedEvent = observation.status === "closed" && typeof suppliedClosedDate === "string" && isRealIsoDate(suppliedClosedDate);
+      const end = isObservedEvent ? suppliedClosedDate : observation.evaluationDate;
+      if (start === null || !isRealIsoDate(end)) continue;
+      const duration = daysBetweenIsoDates(start, end);
+      if (duration < 0) continue;
+      (isObservedEvent ? exact : censored).push(duration);
+    }
+    if (exact.length === 0)
+      return unavailable(measure, input.observations.length, [finding("Kaplan-Meier duration quantiles require at least one observed closure event")]);
+    const value = kaplanMeierQuantiles(exact, censored, [statistic.probability])[0] ?? null;
+    if (value === null)
+      return snapshotDiagnosticJson({
+        measureId: measure.id,
+        unit: measure.unit,
+        value: null,
+        status: "unavailable",
+        contributingObservations: exact.length + censored.length,
+        excludedObservations: input.observations.length - exact.length - censored.length,
+        exact: true,
+        numerator: null,
+        denominator: null,
+        findings: [finding("The observed survival curve does not reach the requested quantile because of right censoring")],
+      });
+    return snapshotDiagnosticJson({
+      measureId: measure.id,
+      unit: measure.unit,
+      value,
+      status: "available",
+      contributingObservations: exact.length + censored.length,
+      excludedObservations: input.observations.length - exact.length - censored.length,
+      exact: true,
+      numerator: null,
+      denominator: null,
+      findings: [],
+    });
+  }
+
+  if (statistic.kind === "weighted-mean") {
+    let weighted = 0;
+    let weights = 0;
+    let included = 0;
+    for (const observation of observations) {
+      const value = sourceValue(observation, statistic.measureId);
+      const weight = sourceValue(observation, statistic.weightMeasureId);
+      if (typeof value !== "number" || typeof weight !== "number") continue;
+      if (weight < 0)
+        return unavailable(measure, input.observations.length, [finding("Negative weights are unsupported", "incompatible-semantics")]);
+      if (weight === 0) continue;
+      weighted += value * weight;
+      weights += weight;
+      included += 1;
+    }
+    if (included === 0 || weights === 0)
+      return unavailable(measure, input.observations.length, [finding("Weighted mean requires at least one positive finite weight")]);
+    return snapshotDiagnosticJson({
+      measureId: measure.id,
+      unit: measure.unit,
+      value: weighted / weights,
+      status: "available",
+      contributingObservations: included,
+      excludedObservations: input.observations.length - included,
+      exact: true,
+      numerator: null,
+      denominator: null,
+      findings: [],
+    });
+  }
+
+  const values = observations
+    .map((observation) => sourceValue(observation, statistic.measureId))
+    .filter((value): value is number => typeof value === "number" && Number.isFinite(value));
+  if (values.length === 0)
+    return unavailable(measure, input.observations.length, [finding("No finite observed values are available")]);
+  let value: number;
+  if (statistic.kind === "sum") value = values.reduce((total, item) => total + item, 0);
+  else if (statistic.kind === "quantile") {
+    if (statistic.probability < 0 || statistic.probability > 1)
+      return unavailable(measure, input.observations.length, [finding("Quantile probability must be between zero and one", "invalid-configuration")]);
+    value = hfType7(values, statistic.probability);
+  } else value = statistic.kind === "minimum" ? Math.min(...values) : Math.max(...values);
+  return snapshotDiagnosticJson({
+    measureId: measure.id,
+    unit: measure.unit,
+    value: Object.is(value, -0) ? 0 : value,
+    status: "available",
+    contributingObservations: values.length,
+    excludedObservations: input.observations.length - values.length,
+    exact: true,
+    numerator: null,
+    denominator: null,
+    findings: [],
+  });
+}

package/src/diagnosticAggregation.ts

@@ -99,6 +99,22 @@ export function finalizeDiagnosticContributions(
   missingPolicy: DiagnosticMissingPolicy,
   blockers: readonly DiagnosticStructuralBlocker[] = [],
 ): DiagnosticMeasureStats {
+  // Aggregate loss snapshots commonly have one leaf per measure/cell. Sorting
+  // and materializing status partitions cannot change a singleton's order.
+  if (contributions.length === 1) {
+    const item = contributions[0]!;
+    const observed = item.status === "observed" ? 1 : 0;
+    const imputedZero = item.status === "imputed-zero" ? 1 : 0;
+    const missing = item.status === "missing" ? 1 : imputedZero;
+    const nonFinite = item.status === "non-finite" ? 1 : 0;
+    const finiteSum = item.status === "observed" ? neumaier([item.value]) : 0;
+    const sum = nonFinite > 0 || blockers.length > 0 ? null : finiteSum;
+    return Object.freeze({
+      value: sum === null || (missingPolicy === "unknown" && missing > 0) ? null : sum,
+      sum, observed, missing, nonFinite, imputedZero,
+      deduplicated: 0 + item.deduplicated, structural: blockers.length,
+    });
+  }
   const ordered = [...contributions].sort(compareDiagnosticContributions);
   const observed = ordered.filter((item) => item.status === "observed");
   const imputed = ordered.filter((item) => item.status === "imputed-zero");

package/src/diagnosticFreeze.ts

@@ -0,0 +1,37 @@
+import type { DiagnosticDeepReadonly } from "./diagnosticDefinitions.js";
+
+// Private knowledge of graphs traversed by this freezer. Object.isFrozen alone
+// is not evidence that caller-supplied children are immutable. Weak membership
+// does not keep released diagnostic datasets alive.
+let completedGraphs = new WeakSet<object>();
+let completedCount = 0;
+const MAX_COMPLETED_MEMBERS = 100_000;
+
+/** Freeze owned plain-data snapshots, visiting shared subgraphs only once. */
+export function freezeDiagnosticGraph<T>(value: T): DiagnosticDeepReadonly<T> {
+  // This walk already retains its nodes until success; a strong local set avoids
+  // a second large weak table and is released when the invocation returns.
+  const seen = new Set<object>();
+  const visit = (node: unknown): void => {
+    if (node === null || typeof node !== "object" || seen.has(node) || completedGraphs.has(node)) return;
+    seen.add(node);
+    for (const child of Object.values(node as Record<string, unknown>)) visit(child);
+    Object.freeze(node);
+  };
+  visit(value);
+  // Mark only after the whole walk succeeds: a cyclic child must not become
+  // trusted while pointing at a parent whose freeze failed.
+  for (const node of seen) {
+    // This is a traversal shortcut, never an authentication receipt. Forgetting
+    // old membership is safe: a later visit traverses and freezes that graph
+    // again. Bound the weak-table bookkeeping even when millions of source
+    // objects are still strongly retained by a large diagnostic dataset.
+    if (completedCount >= MAX_COMPLETED_MEMBERS) {
+      completedGraphs = new WeakSet<object>();
+      completedCount = 0;
+    }
+    completedGraphs.add(node);
+    completedCount++;
+  }
+  return value as DiagnosticDeepReadonly<T>;
+}

package/src/diagnosticIdentityStream.ts

@@ -36,6 +36,7 @@ interface Fields {
   readonly keys: readonly string[];
   readonly values: readonly unknown[];
   readonly documents: boolean;
+  readonly documentKeys?: ReadonlySet<string>;
 }
 const nodes = new WeakMap<DiagnosticIdentityDocument, Node>();
 const CHUNK_UNITS = 16_384;
@@ -84,6 +85,40 @@ export function createDiagnosticIdentityObject(
   return descriptor({ kind: "object", fields: { keys, values, documents: true } });
 }
 
+/** @internal Compose raw field snapshots with lazy document children without
+ * allocating a descriptor for every scalar. This grants no identity authority;
+ * raw children retain the normal live-value validation during iteration. */
+export function createDiagnosticIdentityMixedObject(
+  raw: Readonly<Record<string, unknown>>,
+  documents: Readonly<Record<string, DiagnosticIdentityDocument>>,
+): DiagnosticIdentityDocument {
+  if (!isDiagnosticPlainRecord(raw) || !isDiagnosticPlainRecord(documents))
+    fail("$", "Identity fields must be plain records", "invalid-type");
+  const rawSnapshot = rawFields(raw, "$"), documentSnapshot = rawFields(documents, "$");
+  const valuesByKey = new Map(rawSnapshot.keys.map((key, index) => [key, rawSnapshot.values[index]]));
+  for (let index = 0; index < documentSnapshot.keys.length; index++) {
+    const key = documentSnapshot.keys[index]!;
+    if (valuesByKey.has(key)) fail(childPath("$", key), "Duplicate identity field", "invalid-type");
+    const value = documentSnapshot.values[index] as DiagnosticIdentityDocument;
+    readDocument(value, childPath("$", key));
+    valuesByKey.set(key, value);
+  }
+  const keys = [...valuesByKey.keys()].sort();
+  return descriptor({
+    kind: "object",
+    fields: {
+      keys,
+      values: keys.map((key) => valuesByKey.get(key)),
+      documents: false,
+      documentKeys: new Set(documentSnapshot.keys),
+    },
+  });
+}
+
+function isDocumentField(fields: Fields, index: number): boolean {
+  return fields.documents || !!fields.documentKeys?.has(fields.keys[index]!);
+}
+
 /**
  * A structural lazy sequence. The callback grants NO review/run authority and
  * is invoked only as iteration reaches an index. It must remain repeatable for
@@ -110,7 +145,7 @@ function childPath(path: string, key: string): string {
     : `${path}[${JSON.stringify(key)}]`;
 }
 function scalar(fields: Fields, index: number): unknown {
-  if (!fields.documents) return fields.values[index];
+  if (!isDocumentField(fields, index)) return fields.values[index];
   const node = readDocument(fields.values[index] as DiagnosticIdentityDocument, "$");
   // Non-scalar composition has an object value, and cannot be a source token.
   return node.kind === "value" ? node.value : {};
@@ -373,7 +408,7 @@ export function* iterateDiagnosticIdentityJson(
               depth: depth + 1,
             };
             stack.push(
-              fields.documents
+              isDocumentField(fields, index)
                 ? { kind: "document", document: child as DiagnosticIdentityDocument, ...location }
                 : { kind: "value", value: child, ...location },
             );