@actuarial-ts/core 0.7.1 → 0.8.0

package/src/historyPreparation.ts

@@ -0,0 +1,645 @@
+import { auditedDiagnosticContribution, finalizeDiagnosticContributions } from "./diagnosticAggregation.js";
+import { canonicalJson, fnv1a64 } from "./canonical.js";
+import {
+  HISTORICAL_DATASET_CONTRACT_VERSION,
+  type CustomizationCapabilityFinding,
+  type HistoricalDatasetInput,
+  type HistoricalObservationRecord,
+  type HistoricalRecordDisposition,
+  type HistoricalScalar,
+  type PreparedHistoricalDataset,
+  type PreparedHistoricalObservation,
+} from "./customizationContracts.js";
+import { diagnosticJsonPreflight, isDiagnosticToken, isRealIsoDate, snapshotDiagnosticJson } from "./diagnosticRuntime.js";
+import { DiagnosticValidationError, type DiagnosticValidationIssue } from "./types.js";
+
+interface IndexedRecord {
+  readonly index: number;
+  readonly record: HistoricalObservationRecord;
+}
+
+function compareText(left: string, right: string): number {
+  return left === right ? 0 : left < right ? -1 : 1;
+}
+
+function recordKey(record: HistoricalObservationRecord): string {
+  return canonicalJson([record.sourceNamespace, record.recordId]);
+}
+
+function claimEvaluationKey(record: HistoricalObservationRecord): string {
+  return canonicalJson([record.sourceNamespace, record.claimId, record.evaluationDate]);
+}
+
+function claimKey(sourceNamespace: string, claimId: string): string {
+  return canonicalJson([sourceNamespace, claimId]);
+}
+
+function addToMap<K, V>(map: Map<K, V[]>, key: K, value: V): void {
+  const current = map.get(key);
+  if (current === undefined) map.set(key, [value]);
+  else current.push(value);
+}
+
+function inputIssues(input: HistoricalDatasetInput): DiagnosticValidationIssue[] {
+  const issues = [...diagnosticJsonPreflight(input, "input")];
+  if (input.historyContractVersion !== HISTORICAL_DATASET_CONTRACT_VERSION)
+    issues.push({
+      domain: "input",
+      code: "invalid-configuration",
+      path: "$.historyContractVersion",
+      message: `Expected ${HISTORICAL_DATASET_CONTRACT_VERSION}`,
+    });
+  if (!isDiagnosticToken(input.datasetId))
+    issues.push({
+      domain: "input",
+      code: "invalid-string",
+      path: "$.datasetId",
+      message: "datasetId must be a valid token",
+    });
+  const namespaces = new Map(input.sources.map((source) => [source.namespace, source]));
+  if (namespaces.size !== input.sources.length)
+    issues.push({
+      domain: "input",
+      code: "duplicate-id",
+      path: "$.sources",
+      message: "Source namespaces must be unique",
+    });
+  if (
+    input.evaluationDates !== undefined &&
+    input.evaluationDates.some(
+      (date, index) =>
+        !isRealIsoDate(date) ||
+        (index > 0 && input.evaluationDates![index - 1]! >= date),
+    )
+  )
+    issues.push({
+      domain: "input",
+      code: "invalid-period",
+      path: "$.evaluationDates",
+      message: "evaluationDates must be unique, ascending real Gregorian dates",
+    });
+  input.records.forEach((record, index) => {
+    const source = namespaces.get(record.sourceNamespace);
+    if (source === undefined)
+      issues.push({
+        domain: "input",
+        code: "unknown-reference",
+        path: `$.records[${index}].sourceNamespace`,
+        message: "Record references an unknown source namespace",
+      });
+    else if (source.artifactId !== record.source.artifactId)
+      issues.push({
+        domain: "input",
+        code: "invalid-input-relationship",
+        path: `$.records[${index}].source.artifactId`,
+        message: "Record artifact does not match its source namespace",
+      });
+    if (!isRealIsoDate(record.evaluationDate) && record.grain !== "transaction")
+      issues.push({
+        domain: "input",
+        code: "invalid-period",
+        path: `$.records[${index}].evaluationDate`,
+        message: "Snapshot evaluationDate must be a real Gregorian date",
+      });
+    if (!isRealIsoDate(record.effectiveDate) && record.grain === "transaction")
+      issues.push({
+        domain: "input",
+        code: "invalid-period",
+        path: `$.records[${index}].effectiveDate`,
+        message: "Transaction effectiveDate must be a real Gregorian date",
+      });
+    if (input.revisionPrecedence === "sequence" && !Number.isSafeInteger(record.revision.sequence))
+      issues.push({
+        domain: "input",
+        code: "missing-required",
+        path: `$.records[${index}].revision.sequence`,
+        message: "Sequence precedence requires a safe integer sequence",
+      });
+    if (input.revisionPrecedence === "corrected-at" && record.revision.correctedAt === undefined)
+      issues.push({
+        domain: "input",
+        code: "missing-required",
+        path: `$.records[${index}].revision.correctedAt`,
+        message: "Corrected-at precedence requires correctedAt",
+      });
+    if (input.revisionView.kind === "as-known" && record.revision.correctedAt === undefined)
+      issues.push({
+        domain: "input",
+        code: "missing-required",
+        path: `$.records[${index}].revision.correctedAt`,
+        message: "As-known revision views require correctedAt",
+      });
+  });
+  if (input.historyMode !== "full-snapshots" && input.evaluationDates === undefined)
+    issues.push({
+      domain: "input",
+      code: "missing-required",
+      path: "$.evaluationDates",
+      message: "Change history requires explicit evaluationDates",
+    });
+  return issues;
+}
+
+function precedence(record: HistoricalObservationRecord, input: HistoricalDatasetInput): number | string {
+  return input.revisionPrecedence === "sequence"
+    ? record.revision.sequence!
+    : record.revision.correctedAt!;
+}
+
+function comparePrecedence(
+  left: HistoricalObservationRecord,
+  right: HistoricalObservationRecord,
+  input: HistoricalDatasetInput,
+): number {
+  const a = precedence(left, input);
+  const b = precedence(right, input);
+  return a === b ? 0 : a < b ? -1 : 1;
+}
+
+function eligible(record: HistoricalObservationRecord, input: HistoricalDatasetInput): boolean {
+  return (
+    input.revisionView.kind === "restated" ||
+    record.revision.correctedAt! <= input.revisionView.knowledgeCutoff
+  );
+}
+
+function sumMeasures(
+  records: readonly HistoricalObservationRecord[],
+): Readonly<Record<string, number | null>> {
+  const ids = [...new Set(records.flatMap((record) => Object.keys(record.measures)))].sort();
+  return Object.freeze(
+    Object.fromEntries(
+      ids.map((id) => {
+        const contributions = records
+          .filter((record) => Object.hasOwn(record.measures, id))
+          .map((record) =>
+            auditedDiagnosticContribution(
+              `${record.sourceNamespace}:${record.recordId}`,
+              record.measures[id],
+              "unknown",
+              [record.source],
+            ),
+          );
+        return [id, finalizeDiagnosticContributions(contributions, "unknown").value];
+      }),
+    ),
+  );
+}
+
+function mergeDimensions(
+  records: readonly HistoricalObservationRecord[],
+  findings: CustomizationCapabilityFinding[],
+): Readonly<Record<string, HistoricalScalar | readonly HistoricalScalar[]>> {
+  const result: Record<string, HistoricalScalar | readonly HistoricalScalar[]> = Object.create(null);
+  for (const id of [...new Set(records.flatMap((record) => Object.keys(record.dimensions ?? {})))].sort()) {
+    const values = records
+      .filter((record) => Object.hasOwn(record.dimensions ?? {}, id))
+      .map((record) => record.dimensions![id]!);
+    const unique = new Map(values.map((value) => [canonicalJson(value), value]));
+    if (unique.size === 1) result[id] = unique.values().next().value!;
+    else
+      findings.push({
+        code: "ambiguous-attribution",
+        capability: "history-snapshots",
+        path: `$.records.${records[0]!.sourceNamespace}.${records[0]!.claimId}.dimensions.${id}`,
+        message: `Component snapshots disagree on dimension ${id}`,
+      });
+  }
+  return Object.freeze(result);
+}
+
+function mergeSnapshotCohort(
+  records: readonly HistoricalObservationRecord[],
+  findings: CustomizationCapabilityFinding[],
+): PreparedHistoricalObservation | null {
+  const claimRows = records.filter((record) => record.grain === "claim-snapshot");
+  const componentRows = records.filter((record) => record.grain === "claim-component-snapshot");
+  if (claimRows.length > 1 || (claimRows.length > 0 && componentRows.length > 0)) {
+    findings.push({
+      code: "ambiguous-attribution",
+      capability: "history-snapshots",
+      path: `$.records.${records[0]!.sourceNamespace}.${records[0]!.claimId}.${records[0]!.evaluationDate}`,
+      message: "Claim/evaluation has incompatible claim and component snapshot grains",
+    });
+    return null;
+  }
+  if (componentRows.length > 0) {
+    const components = componentRows.map((record) => record.componentId!);
+    if (new Set(components).size !== components.length) {
+      findings.push({
+        code: "ambiguous-attribution",
+        capability: "history-snapshots",
+        path: `$.records.${records[0]!.sourceNamespace}.${records[0]!.claimId}.${records[0]!.evaluationDate}`,
+        message: "Claim/evaluation repeats a component identity",
+      });
+      return null;
+    }
+  }
+  const dates = (field: "accidentDate" | "reportDate") => [
+    ...new Set(records.map((record) => record[field]).filter((value): value is string => value !== undefined)),
+  ];
+  const accidentDates = dates("accidentDate");
+  const reportDates = dates("reportDate");
+  const statuses = [...new Set(records.map((record) => record.status).filter((value): value is string => value !== undefined))];
+  const relationships = [
+    ...new Map(
+      records
+        .filter((record) => record.relationships !== undefined)
+        .map((record) => [canonicalJson(record.relationships), record.relationships!]),
+    ).values(),
+  ];
+  if (accidentDates.length > 1 || reportDates.length > 1 || statuses.length > 1 || relationships.length > 1) {
+    findings.push({
+      code: "ambiguous-attribution",
+      capability: "history-snapshots",
+      path: `$.records.${records[0]!.sourceNamespace}.${records[0]!.claimId}.${records[0]!.evaluationDate}`,
+      message: "Component snapshots disagree on claim dates, status, or relationships",
+    });
+    return null;
+  }
+  return {
+    sourceNamespace: records[0]!.sourceNamespace,
+    claimId: records[0]!.claimId,
+    evaluationDate: records[0]!.evaluationDate!,
+    observationKind: "observed-snapshot",
+    accidentDate: accidentDates[0] ?? null,
+    reportDate: reportDates[0] ?? null,
+    measures: claimRows.length === 1 ? claimRows[0]!.measures : sumMeasures(componentRows),
+    status: statuses[0] ?? null,
+    dimensions: mergeDimensions(records, findings),
+    relationships: relationships[0] ?? {},
+    sources: records.map((record) => record.source),
+  };
+}
+
+function transactionObservations(
+  input: HistoricalDatasetInput,
+  records: readonly HistoricalObservationRecord[],
+  findings: CustomizationCapabilityFinding[],
+): PreparedHistoricalObservation[] {
+  const output: PreparedHistoricalObservation[] = [];
+  const byClaim = new Map<string, HistoricalObservationRecord[]>();
+  for (const record of records) addToMap(byClaim, claimKey(record.sourceNamespace, record.claimId), record);
+  const balances = new Map(
+    (input.openingBalances ?? []).map((balance) => [
+      claimKey(balance.sourceNamespace, balance.claimId),
+      balance,
+    ]),
+  );
+  for (const [key, claimRecords] of byClaim) {
+    const opening = balances.get(key);
+    if (opening === undefined) {
+      findings.push({
+        code: "missing-prerequisite",
+        capability: "history-changes",
+        path: `$.openingBalances.${claimRecords[0]!.sourceNamespace}.${claimRecords[0]!.claimId}`,
+        message: "Cumulative history from changes requires an opening balance",
+        requiredFields: ["openingBalances"],
+      });
+      continue;
+    }
+    const values: Record<string, number | null> = { ...opening.measures };
+    const ordered = [...claimRecords].sort(
+      (left, right) =>
+        compareText(left.effectiveDate!, right.effectiveDate!) ||
+        compareText(left.recordId, right.recordId),
+    );
+    let next = 0;
+    const appliedSources = [opening.source];
+    for (const evaluationDate of input.evaluationDates ?? []) {
+      while (next < ordered.length && ordered[next]!.effectiveDate! <= evaluationDate) {
+        const transaction = ordered[next++]!;
+        if (transaction.effectiveDate! > opening.asOfDate) {
+          for (const [measureId, amount] of Object.entries(transaction.measures)) {
+            if (amount === null || values[measureId] === null) values[measureId] = null;
+            else values[measureId] = (values[measureId] ?? 0) + amount;
+          }
+          appliedSources.push(transaction.source);
+        }
+      }
+      const latest = ordered[Math.max(0, next - 1)];
+      output.push({
+        sourceNamespace: opening.sourceNamespace,
+        claimId: opening.claimId,
+        evaluationDate,
+        observationKind: "reconstructed-from-changes",
+        accidentDate: latest?.accidentDate ?? null,
+        reportDate: latest?.reportDate ?? null,
+        measures: { ...values },
+        status: latest?.status ?? null,
+        dimensions: latest?.dimensions ?? {},
+        relationships: latest?.relationships ?? {},
+        sources: [...appliedSources],
+      });
+    }
+  }
+  return output;
+}
+
+function mixedObservations(
+  input: HistoricalDatasetInput,
+  snapshots: readonly PreparedHistoricalObservation[],
+  transactions: readonly HistoricalObservationRecord[],
+  findings: CustomizationCapabilityFinding[],
+): PreparedHistoricalObservation[] {
+  const output: PreparedHistoricalObservation[] = [];
+  const snapshotByClaim = new Map<string, PreparedHistoricalObservation[]>();
+  const transactionsByClaim = new Map<string, HistoricalObservationRecord[]>();
+  for (const observation of snapshots)
+    addToMap(snapshotByClaim, claimKey(observation.sourceNamespace, observation.claimId), observation);
+  for (const transaction of transactions)
+    addToMap(transactionsByClaim, claimKey(transaction.sourceNamespace, transaction.claimId), transaction);
+  const openings = new Map((input.openingBalances ?? []).map((opening) => [claimKey(opening.sourceNamespace, opening.claimId), opening]));
+  const claimKeys = [...new Set([...snapshotByClaim.keys(), ...transactionsByClaim.keys()])].sort(compareText);
+  for (const key of claimKeys) {
+    const claimSnapshots = [...(snapshotByClaim.get(key) ?? [])].sort((a, b) => compareText(a.evaluationDate, b.evaluationDate));
+    const claimTransactions = [...(transactionsByClaim.get(key) ?? [])].sort((a, b) => compareText(a.effectiveDate!, b.effectiveDate!) || compareText(a.recordId, b.recordId));
+    const opening = openings.get(key);
+    let baseline: PreparedHistoricalObservation | undefined;
+    let baselineDate = opening?.asOfDate;
+    let values: Record<string, number | null> | undefined = opening === undefined ? undefined : { ...opening.measures };
+    let sources = opening === undefined ? [] : [opening.source];
+    let applied = new Set<string>();
+    for (const evaluationDate of input.evaluationDates ?? []) {
+      const exact = claimSnapshots.find((observation) => observation.evaluationDate === evaluationDate);
+      if (exact !== undefined) {
+        baseline = exact;
+        baselineDate = evaluationDate;
+        values = { ...exact.measures };
+        sources = [...exact.sources];
+        applied = new Set(claimTransactions.filter((transaction) => transaction.effectiveDate! <= evaluationDate).map(recordKey));
+        output.push(exact);
+        continue;
+      }
+      const priorSnapshot = [...claimSnapshots].reverse().find((observation) => observation.evaluationDate < evaluationDate && (baselineDate === undefined || observation.evaluationDate > baselineDate));
+      if (priorSnapshot !== undefined) {
+        baseline = priorSnapshot;
+        baselineDate = priorSnapshot.evaluationDate;
+        values = { ...priorSnapshot.measures };
+        sources = [...priorSnapshot.sources];
+        applied = new Set(claimTransactions.filter((transaction) => transaction.effectiveDate! <= priorSnapshot.evaluationDate).map(recordKey));
+      }
+      if (values === undefined) {
+        if (claimTransactions.some((transaction) => transaction.effectiveDate! <= evaluationDate))
+          findings.push({
+            code: "missing-prerequisite",
+            capability: "history-changes",
+            path: `$.openingBalances.${claimTransactions[0]!.sourceNamespace}.${claimTransactions[0]!.claimId}`,
+            message: "Mixed history requires a prior snapshot or opening balance before applying changes",
+            requiredFields: ["prior snapshot", "openingBalances"],
+          });
+        continue;
+      }
+      let latestTransaction: HistoricalObservationRecord | undefined;
+      for (const transaction of claimTransactions) {
+        if (transaction.effectiveDate! > evaluationDate || applied.has(recordKey(transaction))) continue;
+        for (const [measureId, amount] of Object.entries(transaction.measures)) {
+          if (amount === null || values[measureId] === null) values[measureId] = null;
+          else values[measureId] = (values[measureId] ?? 0) + amount;
+        }
+        sources.push(transaction.source);
+        applied.add(recordKey(transaction));
+        latestTransaction = transaction;
+      }
+      output.push({
+        sourceNamespace: baseline?.sourceNamespace ?? opening!.sourceNamespace,
+        claimId: baseline?.claimId ?? opening!.claimId,
+        evaluationDate,
+        observationKind: "reconstructed-from-changes",
+        accidentDate: latestTransaction?.accidentDate ?? baseline?.accidentDate ?? null,
+        reportDate: latestTransaction?.reportDate ?? baseline?.reportDate ?? null,
+        measures: { ...values },
+        status: latestTransaction?.status ?? baseline?.status ?? null,
+        dimensions: latestTransaction?.dimensions ?? baseline?.dimensions ?? {},
+        relationships: latestTransaction?.relationships ?? baseline?.relationships ?? {},
+        sources: [...sources],
+      });
+    }
+  }
+  return output;
+}
+
+function addMissingSnapshotObservations(
+  input: HistoricalDatasetInput,
+  observations: PreparedHistoricalObservation[],
+  findings: CustomizationCapabilityFinding[],
+): void {
+  if (input.evaluationDates === undefined) return;
+  const byClaim = new Map<string, PreparedHistoricalObservation[]>();
+  for (const observation of observations.filter((item) => item.observationKind !== "reconstructed-from-changes"))
+    addToMap(byClaim, claimKey(observation.sourceNamespace, observation.claimId), observation);
+  for (const claimObservations of byClaim.values()) {
+    claimObservations.sort((left, right) => compareText(left.evaluationDate, right.evaluationDate));
+    const exact = new Set(claimObservations.map((observation) => observation.evaluationDate));
+    for (const evaluationDate of input.evaluationDates) {
+      if (exact.has(evaluationDate)) continue;
+      const prior = [...claimObservations]
+        .reverse()
+        .find((observation) => observation.evaluationDate < evaluationDate);
+      if (prior === undefined) continue;
+      if (input.missingSnapshotRecord === "carried-forward") {
+        const carried = snapshotDiagnosticJson({
+          ...prior,
+          evaluationDate,
+          observationKind: "carried-forward" as const,
+        });
+        observations.push(carried);
+        claimObservations.push(carried);
+        claimObservations.sort((left, right) => compareText(left.evaluationDate, right.evaluationDate));
+        exact.add(evaluationDate);
+      } else {
+        findings.push({
+          code: "missing-prerequisite",
+          capability: "history-snapshots",
+          path: `$.records.${prior.sourceNamespace}.${prior.claimId}.${evaluationDate}`,
+          message: "Missing snapshot remains unknown under the declared history rule",
+        });
+      }
+    }
+  }
+}
+
+function totalsByDate(
+  rows: readonly {
+    readonly evaluationDate?: string;
+    readonly effectiveDate?: string;
+    readonly measures: Readonly<Record<string, number | null>>;
+  }[],
+): Readonly<Record<string, Readonly<Record<string, number>>>> {
+  const result: Record<string, Record<string, number>> = Object.create(null);
+  for (const row of rows) {
+    const date = row.evaluationDate ?? row.effectiveDate;
+    if (date === undefined) continue;
+    const dateTotals = (result[date] ??= Object.create(null) as Record<string, number>);
+    for (const [id, value] of Object.entries(row.measures))
+      if (value !== null) dateTotals[id] = (dateTotals[id] ?? 0) + value;
+  }
+  return Object.freeze(
+    Object.fromEntries(
+      Object.keys(result)
+        .sort()
+        .map((date) => [date, Object.freeze(result[date]!)]),
+    ),
+  );
+}
+
+/**
+ * Selects immutable source revisions and assembles claim observations without
+ * using arrival order. Unknown input should first pass the data-package Zod
+ * boundary; this pure core boundary independently protects its typed contract.
+ */
+export function prepareHistoricalDataset(input: HistoricalDatasetInput): PreparedHistoricalDataset {
+  const issues = inputIssues(input);
+  if (issues.length > 0) throw new DiagnosticValidationError(issues);
+  const owned = snapshotDiagnosticJson(input);
+  const dispositions: HistoricalRecordDisposition[] = [];
+  const selected: HistoricalObservationRecord[] = [];
+  const byRecord = new Map<string, IndexedRecord[]>();
+  owned.records.forEach((record, index) => addToMap(byRecord, recordKey(record), { index, record }));
+  for (const cohort of byRecord.values()) {
+    const candidates = cohort.filter(({ record }) => eligible(record, owned));
+    for (const { record } of cohort.filter(({ record }) => !eligible(record, owned)))
+      dispositions.push({
+        sourceNamespace: record.sourceNamespace,
+        recordId: record.recordId,
+        revisionId: record.revision.id,
+        disposition: "after-knowledge-cutoff",
+      });
+    if (candidates.length === 0) continue;
+    const maximum = candidates.reduce((best, item) =>
+      comparePrecedence(best.record, item.record, owned) < 0 ? item : best,
+    );
+    const winners = candidates.filter(
+      (item) => comparePrecedence(item.record, maximum.record, owned) === 0,
+    );
+    const uniqueWinners = new Map(winners.map((item) => [canonicalJson(item.record), item]));
+    if (uniqueWinners.size > 1) {
+      for (const { record } of winners)
+        dispositions.push({
+          sourceNamespace: record.sourceNamespace,
+          recordId: record.recordId,
+          revisionId: record.revision.id,
+          disposition: "conflict",
+        });
+    } else {
+      const winner = winners[0]!.record;
+      if (winner.revision.action === "delete")
+        dispositions.push({
+          sourceNamespace: winner.sourceNamespace,
+          recordId: winner.recordId,
+          revisionId: winner.revision.id,
+          disposition: "deleted",
+        });
+      else {
+        selected.push(winner);
+        dispositions.push({
+          sourceNamespace: winner.sourceNamespace,
+          recordId: winner.recordId,
+          revisionId: winner.revision.id,
+          disposition: "selected",
+        });
+      }
+      for (const { record } of winners.slice(1))
+        dispositions.push({
+          sourceNamespace: record.sourceNamespace,
+          recordId: record.recordId,
+          revisionId: record.revision.id,
+          disposition: "duplicate",
+        });
+    }
+    for (const { record } of candidates.filter(
+      (item) => comparePrecedence(item.record, maximum.record, owned) < 0,
+    ))
+      dispositions.push({
+        sourceNamespace: record.sourceNamespace,
+        recordId: record.recordId,
+        revisionId: record.revision.id,
+        disposition: "superseded",
+      });
+  }
+
+  const findings: CustomizationCapabilityFinding[] = [];
+  for (const disposition of dispositions.filter((item) => item.disposition === "conflict"))
+    findings.push({
+      code: "ambiguous-attribution",
+      capability: "history-snapshots",
+      path: `$.records.${disposition.sourceNamespace}.${disposition.recordId}`,
+      message: "Equal-precedence revisions conflict; no revision was selected",
+    });
+
+  selected.sort(
+    (left, right) =>
+      compareText(recordKey(left), recordKey(right)) ||
+      comparePrecedence(left, right, owned) ||
+      compareText(left.revision.id, right.revision.id),
+  );
+  const snapshotRecords = selected.filter((record) => record.grain !== "transaction");
+  const transactionRecords = selected.filter((record) => record.grain === "transaction");
+  let observations: PreparedHistoricalObservation[] = [];
+  const byClaimEvaluation = new Map<string, HistoricalObservationRecord[]>();
+  for (const record of snapshotRecords)
+    addToMap(byClaimEvaluation, claimEvaluationKey(record), record);
+  for (const cohort of byClaimEvaluation.values()) {
+    const observation = mergeSnapshotCohort(cohort, findings);
+    if (observation !== null) observations.push(observation);
+  }
+  if (owned.historyMode === "mixed")
+    observations = mixedObservations(owned, observations, transactionRecords, findings);
+  else if (owned.historyMode === "changes")
+    observations.push(...transactionObservations(owned, transactionRecords, findings));
+  else
+    addMissingSnapshotObservations(owned, observations, findings);
+  observations.sort(
+    (left, right) =>
+      compareText(left.sourceNamespace, right.sourceNamespace) ||
+      compareText(left.claimId, right.claimId) ||
+      compareText(left.evaluationDate, right.evaluationDate),
+  );
+  dispositions.sort(
+    (left, right) =>
+      compareText(left.sourceNamespace, right.sourceNamespace) ||
+      compareText(left.recordId, right.recordId) ||
+      compareText(left.revisionId, right.revisionId) ||
+      compareText(left.disposition, right.disposition),
+  );
+  const economicObservations = observations.map(({ sources: _sources, ...observation }) => observation);
+  const calculationIdentityValue = {
+    historyContractVersion: owned.historyContractVersion,
+    revisionView: owned.revisionView,
+    revisionPrecedence: owned.revisionPrecedence,
+    historyMode: owned.historyMode,
+    missingSnapshotRecord: owned.missingSnapshotRecord,
+    observations: economicObservations,
+  };
+  const calculationRevisionId = `fnv1a64-jcs-v1:${fnv1a64(canonicalJson(calculationIdentityValue))}`;
+  const lineageIdentityValue = {
+    historyContractVersion: owned.historyContractVersion,
+    datasetId: owned.datasetId,
+    sources: owned.sources,
+    selected,
+    calculationRevisionId,
+  };
+  const lineageRevisionId = `fnv1a64-jcs-v1:${fnv1a64(canonicalJson(lineageIdentityValue))}`;
+  const result: PreparedHistoricalDataset = {
+    historyContractVersion: HISTORICAL_DATASET_CONTRACT_VERSION,
+    datasetId: owned.datasetId,
+    datasetRevisionId: lineageRevisionId,
+    calculationRevisionId,
+    lineageRevisionId,
+    revisionView: owned.revisionView,
+    observations,
+    dispositions,
+    reconciliation: {
+      inputRecords: owned.records.length,
+      selectedRevisions: dispositions.filter((item) => item.disposition === "selected").length,
+      duplicateRecords: dispositions.filter((item) => item.disposition === "duplicate").length,
+      supersededRecords: dispositions.filter((item) => item.disposition === "superseded").length,
+      deletedRecords: dispositions.filter((item) => item.disposition === "deleted").length,
+      outputObservations: observations.length,
+      inputMeasureTotalsByDate: totalsByDate(selected),
+      outputMeasureTotalsByEvaluation: totalsByDate(observations),
+    },
+    findings,
+  };
+  return snapshotDiagnosticJson(result);
+}

package/src/index.ts

@@ -1,7 +1,30 @@
 export * from "./types.js";
+export * from "./customizationContracts.js";
+export * from "./historyPreparation.js";
+export * from "./policyPeriods.js";
+export * from "./exposureEarning.js";
+export * from "./exposureRevisions.js";
+export * from "./exposureMovements.js";
+export * from "./populations.js";
+export * from "./classifications.js";
+export * from "./descriptiveStatistics.js";
+export * from "./reservingAdapter.js";
+export * from "./financialTerms.js";
+export * from "./financialPipeline.js";
+export * from "./analysisRecipe.js";
 export * from "./util.js";
 export * from "./canonical.js";
-export * from "./diagnosticIdentityStream.js";
+export {
+  createDiagnosticIdentityValue,
+  createDiagnosticIdentityObject,
+  createDiagnosticIdentityArray,
+  iterateDiagnosticIdentityJson,
+  fingerprintDiagnosticIdentity,
+  compareDiagnosticIdentityDocuments,
+  compareDiagnosticIdentityJsonChunks,
+  type DiagnosticIdentityDocument,
+  type DiagnosticIdentityComparison,
+} from "./diagnosticIdentityStream.js";
 export * from "./version.js";
 export {
   MAX_DIAGNOSTIC_JSON_DEPTH,
@@ -131,6 +154,10 @@ export {
   materializePreparedDiagnosticData,
   prepareDiagnosticData,
   prepareDiagnosticDataCompact,
+  reselectCompactDiagnosticMetrics,
+  selectCompactDiagnosticSourceGroups,
+  selectCompactDiagnosticOrigins,
+  selectCompactDiagnosticCoordinates,
   verifyPreparedDiagnosticDataIntegrity,
 } from "./diagnosticPreparation.js";
 export type {