@actuarial-ts/core 0.7.0 → 0.8.0

package/src/exposureMovements.ts

@@ -0,0 +1,78 @@
+import type {
+  CustomizationCapabilityFinding,
+  CustomizationExposureObservation,
+  ExposureLevelSchedule,
+  ExposureLevelScheduleResult,
+} from "./customizationContracts.js";
+import { isRealIsoDate, snapshotDiagnosticJson } from "./diagnosticRuntime.js";
+import { daysBetweenIsoDates } from "./policyPeriods.js";
+import { DiagnosticValidationError, type DiagnosticValidationIssue } from "./types.js";
+
+function finding(message: string): CustomizationCapabilityFinding {
+  return { code: "ambiguous-attribution", capability: "exposure-earning", path: "$.movements", message };
+}
+
+/**
+ * Converts a declared daily exposure level, midterm replacements, and
+ * cancellation into nonoverlapping additive interval observations. A movement
+ * replaces the prior level; it is never interpreted as an undeclared delta.
+ */
+export function materializeExposureLevelSchedule(schedule: ExposureLevelSchedule): ExposureLevelScheduleResult {
+  const issues: DiagnosticValidationIssue[] = [];
+  if (!isRealIsoDate(schedule.startDate) || !isRealIsoDate(schedule.endDate) || schedule.startDate >= schedule.endDate)
+    issues.push({ domain: "input", code: "invalid-period", path: "$.schedule", message: "Exposure level schedule requires startDate before endDate" });
+  if (!Number.isFinite(schedule.initialDailyLevel) || schedule.initialDailyLevel < 0)
+    issues.push({ domain: "input", code: "invalid-number", path: "$.initialDailyLevel", message: "Initial daily level must be finite and nonnegative" });
+  for (const [index, movement] of schedule.movements.entries()) {
+    if (!isRealIsoDate(movement.effectiveDate) || movement.effectiveDate < schedule.startDate || movement.effectiveDate >= schedule.endDate)
+      issues.push({ domain: "input", code: "invalid-period", path: `$.movements[${index}].effectiveDate`, message: "Movement date must fall within the start-inclusive/end-exclusive schedule" });
+    if (movement.kind === "set-daily-level" && (!Number.isFinite(movement.dailyLevel) || movement.dailyLevel < 0))
+      issues.push({ domain: "input", code: "invalid-number", path: `$.movements[${index}].dailyLevel`, message: "Replacement daily level must be finite and nonnegative" });
+  }
+  if (issues.length > 0) throw new DiagnosticValidationError(issues);
+  const ordered = [...schedule.movements].sort((left, right) =>
+    left.effectiveDate === right.effectiveDate
+      ? left.id.localeCompare(right.id)
+      : left.effectiveDate.localeCompare(right.effectiveDate),
+  );
+  for (let index = 1; index < ordered.length; index += 1)
+    if (ordered[index - 1]!.effectiveDate === ordered[index]!.effectiveDate)
+      return snapshotDiagnosticJson({
+        status: "unavailable",
+        observations: [],
+        totalValue: null,
+        findings: [finding(`Multiple exposure movements are effective on ${ordered[index]!.effectiveDate}`)],
+      });
+
+  let cursor = schedule.startDate;
+  let level = schedule.initialDailyLevel;
+  let segment = 0;
+  const observations: CustomizationExposureObservation[] = [];
+  const emit = (endDate: string): void => {
+    if (cursor === endDate) return;
+    observations.push({
+      id: `${schedule.id}:segment-${segment}`,
+      measureId: schedule.measureId,
+      value: level * daysBetweenIsoDates(cursor, endDate),
+      startDate: cursor,
+      endDate,
+      ...(schedule.evaluationDate === undefined ? {} : { evaluationDate: schedule.evaluationDate }),
+      dimensions: schedule.dimensions,
+      revisionId: schedule.revisionId,
+      source: schedule.source,
+    });
+    segment += 1;
+    cursor = endDate;
+  };
+  for (const movement of ordered) {
+    emit(movement.effectiveDate);
+    level = movement.kind === "cancel" ? 0 : movement.dailyLevel;
+  }
+  emit(schedule.endDate);
+  return snapshotDiagnosticJson({
+    status: "available",
+    observations,
+    totalValue: observations.reduce((total, observation) => total + (observation.value ?? 0), 0),
+    findings: [],
+  });
+}

package/src/exposureRevisions.ts

@@ -0,0 +1,186 @@
+import { canonicalJson, fnv1a64 } from "./canonical.js";
+import type {
+  CustomizationCapabilityFinding,
+  CustomizationExposureObservation,
+  ExposureRevisionDisposition,
+  ExposureRevisionSelection,
+  ExposureScopeDefinition,
+  ExposureValuationSelection,
+  SelectedExposureRevisions,
+} from "./customizationContracts.js";
+import { isRealIsoDate, snapshotDiagnosticJson } from "./diagnosticRuntime.js";
+import { DiagnosticValidationError, type DiagnosticValidationIssue } from "./types.js";
+
+function correctedAt(observation: CustomizationExposureObservation): string | undefined {
+  return observation.revision?.correctedAt;
+}
+
+function orderValue(
+  observation: CustomizationExposureObservation,
+  precedence: ExposureRevisionSelection["revisionPrecedence"],
+): number | string | undefined {
+  return precedence === "sequence" ? observation.revision?.sequence : correctedAt(observation);
+}
+
+function compareOrder(
+  left: CustomizationExposureObservation,
+  right: CustomizationExposureObservation,
+  precedence: ExposureRevisionSelection["revisionPrecedence"],
+): number {
+  const a = orderValue(left, precedence);
+  const b = orderValue(right, precedence);
+  if (a === undefined || b === undefined) return 0;
+  if (a === b) return left.revisionId.localeCompare(right.revisionId);
+  return a < b ? -1 : 1;
+}
+
+function economic(observation: CustomizationExposureObservation): unknown {
+  const { source: _source, revisionId: _revisionId, revision: _revision, ...value } = observation;
+  return value;
+}
+
+/** Selects immutable exposure revisions without allowing later corrections into an as-known run. */
+export function selectExposureRevisions(input: {
+  readonly observations: readonly CustomizationExposureObservation[];
+  readonly selection: ExposureRevisionSelection;
+}): SelectedExposureRevisions {
+  const issues: DiagnosticValidationIssue[] = [];
+  if (
+    input.selection.revisionView.kind === "as-known" &&
+    !isRealIsoDate(input.selection.revisionView.knowledgeCutoff.slice(0, 10))
+  )
+    issues.push({
+      domain: "configuration",
+      code: "invalid-period",
+      path: "$.selection.revisionView.knowledgeCutoff",
+      message: "Exposure knowledge cutoff must begin with a real Gregorian date",
+    });
+  input.observations.forEach((observation, index) => {
+    const revision = observation.revision;
+    if (input.selection.revisionPrecedence === "sequence" && revision !== undefined && revision.sequence === undefined)
+      issues.push({ domain: "input", code: "missing-required", path: `$.observations[${index}].revision.sequence`, message: "Sequence precedence requires sequence on every revisioned exposure observation" });
+    if (input.selection.revisionPrecedence === "corrected-at" && revision !== undefined && revision.correctedAt === undefined)
+      issues.push({ domain: "input", code: "missing-required", path: `$.observations[${index}].revision.correctedAt`, message: "Corrected-at precedence requires correctedAt on every revisioned exposure observation" });
+  });
+  if (issues.length > 0) throw new DiagnosticValidationError(issues);
+
+  const groups = new Map<string, CustomizationExposureObservation[]>();
+  for (const observation of input.observations) {
+    const groupKey = canonicalJson([observation.id, observation.evaluationDate ?? null]);
+    const values = groups.get(groupKey) ?? [];
+    values.push(observation);
+    groups.set(groupKey, values);
+  }
+  const selected: CustomizationExposureObservation[] = [];
+  const dispositions: ExposureRevisionDisposition[] = [];
+  const findings: CustomizationCapabilityFinding[] = [];
+  for (const [, group] of [...groups].sort(([a], [b]) => a.localeCompare(b))) {
+    const observationId = group[0]!.id;
+    const evaluationDate = group[0]!.evaluationDate;
+    const disposition = (revisionId: string, value: ExposureRevisionDisposition["disposition"]): ExposureRevisionDisposition => ({
+      observationId,
+      ...(evaluationDate === undefined ? {} : { evaluationDate }),
+      revisionId,
+      disposition: value,
+    });
+    const eligible = group.filter((observation) => {
+      if (input.selection.revisionView.kind !== "as-known") return true;
+      const known = correctedAt(observation);
+      const include = known === undefined || known <= input.selection.revisionView.knowledgeCutoff;
+      if (!include) dispositions.push(disposition(observation.revisionId, "after-knowledge-cutoff"));
+      return include;
+    });
+    if (eligible.length === 0) continue;
+    eligible.sort((a, b) => compareOrder(a, b, input.selection.revisionPrecedence));
+    const winner = eligible.at(-1)!;
+    const sameOrder = eligible.filter((candidate) =>
+      orderValue(candidate, input.selection.revisionPrecedence) === orderValue(winner, input.selection.revisionPrecedence),
+    );
+    const distinct = new Set(sameOrder.map((candidate) => canonicalJson(economic(candidate))));
+    if (distinct.size > 1) {
+      sameOrder.forEach((candidate) => dispositions.push(disposition(candidate.revisionId, "conflict")));
+      findings.push({
+        code: "invalid-configuration",
+        capability: "exposure-earning",
+        path: `$.exposures.${observationId}`,
+        message: "Exposure revisions at the selected precedence conflict",
+      });
+      continue;
+    }
+    for (const candidate of eligible) {
+      if (candidate === winner) continue;
+      dispositions.push(disposition(candidate.revisionId, sameOrder.includes(candidate) ? "duplicate" : "superseded"));
+    }
+    if (winner.revision?.action === "delete")
+      dispositions.push(disposition(winner.revisionId, "deleted"));
+    else {
+      dispositions.push(disposition(winner.revisionId, "selected"));
+      selected.push(winner);
+    }
+  }
+  const economicInput = {
+    selection: input.selection,
+    observations: selected.map(economic),
+  };
+  const calculationRevisionId = `fnv1a64-jcs-v1:${fnv1a64(canonicalJson(economicInput))}`;
+  const lineageRevisionId = `fnv1a64-jcs-v1:${fnv1a64(canonicalJson({
+    calculationRevisionId,
+    selected,
+    dispositions,
+  }))}`;
+  return snapshotDiagnosticJson({
+    observations: selected,
+    dispositions,
+    calculationRevisionId,
+    lineageRevisionId,
+    findings,
+  });
+}
+
+/** Applies the declared origin-static or valuation-specific exposure view. */
+export function selectExposureValuation(input: {
+  readonly observations: readonly CustomizationExposureObservation[];
+  readonly scope: ExposureScopeDefinition;
+  readonly evaluationDate: string;
+}): ExposureValuationSelection {
+  const mode = input.scope.valuationSelection ?? "origin-static";
+  const dated = input.observations.filter((observation) => observation.evaluationDate !== undefined);
+  const undated = input.observations.filter((observation) => observation.evaluationDate === undefined);
+  if (mode === "origin-static") {
+    if (dated.length > 0)
+      return snapshotDiagnosticJson({ observations: [], findings: [{
+        code: "incompatible-semantics", capability: "exposure-earning", path: `$.scopes.${input.scope.id}.valuationSelection`,
+        message: "Origin-static exposure cannot contain valuation-specific observations",
+      }] });
+    return snapshotDiagnosticJson({ observations: undated, findings: [] });
+  }
+  if (undated.length > 0)
+    return snapshotDiagnosticJson({ observations: [], findings: [{
+      code: "missing-prerequisite", capability: "exposure-earning", path: `$.scopes.${input.scope.id}.valuationSelection`,
+      message: "Valuation-specific exposure requires evaluationDate on every observation", requiredFields: ["evaluationDate"],
+    }] });
+  if (mode === "exact") {
+    const selected = dated.filter((observation) => observation.evaluationDate === input.evaluationDate);
+    return snapshotDiagnosticJson({ observations: selected, findings: selected.length > 0 ? [] : [{
+      code: "missing-prerequisite", capability: "exposure-earning", path: `$.exposures.${input.evaluationDate}`,
+      message: "No exact exposure valuation exists for the analysis date",
+    }] });
+  }
+  const bySeries = new Map<string, CustomizationExposureObservation[]>();
+  for (const observation of dated) {
+    const seriesKey = canonicalJson([observation.id, observation.measureId, observation.startDate ?? null, observation.endDate ?? null, observation.pointDate ?? null, observation.dimensions]);
+    const values = bySeries.get(seriesKey) ?? [];
+    values.push(observation);
+    bySeries.set(seriesKey, values);
+  }
+  const selected = [...bySeries.values()].flatMap((series) => {
+    const eligible = series.filter((observation) => observation.evaluationDate! <= input.evaluationDate).sort((a, b) => a.evaluationDate!.localeCompare(b.evaluationDate!));
+    if (eligible.length === 0) return [];
+    const latest = eligible.at(-1)!.evaluationDate;
+    return eligible.filter((observation) => observation.evaluationDate === latest);
+  });
+  return snapshotDiagnosticJson({ observations: selected, findings: selected.length > 0 || dated.length === 0 ? [] : [{
+    code: "missing-prerequisite", capability: "exposure-earning", path: `$.exposures.${input.evaluationDate}`,
+    message: "No exposure valuation exists on or before the analysis date",
+  }] });
+}

package/src/financialPipeline.ts

@@ -0,0 +1,93 @@
+import { canonicalJson, fnv1a64 } from "./canonical.js";
+import type {
+  CustomizationCapabilityFinding,
+  FinancialPipelineResult,
+  FinancialPipelineStage,
+  PreparedHistoricalObservation,
+} from "./customizationContracts.js";
+import { isRealIsoDate, snapshotDiagnosticJson } from "./diagnosticRuntime.js";
+import { applyFinancialTerms } from "./financialTerms.js";
+
+const PIPELINE_MEASURE = "financial-pipeline-amount";
+
+function key(observation: PreparedHistoricalObservation): string {
+  return canonicalJson([observation.sourceNamespace, observation.claimId]);
+}
+
+function unavailable(
+  input: object,
+  inputUnit: string,
+  outputUnit: string,
+  finding: CustomizationCapabilityFinding,
+): FinancialPipelineResult {
+  return snapshotDiagnosticJson({
+    status: "unavailable",
+    inputUnit,
+    outputUnit,
+    calculationIdentity: `fnv1a64-jcs-v1:${fnv1a64(canonicalJson(input))}`,
+    claims: [],
+    findings: [finding],
+  });
+}
+
+/** Applies caller-ordered amount transformations and shared terms with a complete audit trail. */
+export function applyFinancialPipeline(input: {
+  readonly observations: readonly PreparedHistoricalObservation[];
+  readonly amountMeasureId: string;
+  readonly inputUnit: string;
+  readonly stages: readonly FinancialPipelineStage[];
+  readonly completeFinancialPopulation: boolean;
+  readonly reportingClaims?: readonly { readonly sourceNamespace: string; readonly claimId: string }[];
+}): FinancialPipelineResult {
+  const identityInput = { kind: "financial-pipeline", ...input };
+  let outputUnit = input.inputUnit;
+  const working = new Map<string, { observation: PreparedHistoricalObservation; inputAmount: number; amount: number; stages: { stageId: string; stageKind: "adjustment" | "terms"; inputAmount: number; outputAmount: number }[] }>();
+  for (const observation of input.observations) {
+    const amount = observation.measures[input.amountMeasureId];
+    if (typeof amount !== "number" || !Number.isFinite(amount))
+      return unavailable(identityInput, input.inputUnit, outputUnit, { code: "missing-prerequisite", capability: "shared-financial-terms", path: `$.observations.${observation.claimId}.measures.${input.amountMeasureId}`, message: `Financial pipeline requires finite ${input.amountMeasureId}`, requiredFields: [input.amountMeasureId] });
+    if (working.has(key(observation)))
+      return unavailable(identityInput, input.inputUnit, outputUnit, { code: "incompatible-semantics", capability: "shared-financial-terms", path: "$.observations", message: "Financial pipeline requires one selected observation per claim" });
+    working.set(key(observation), { observation, inputAmount: amount, amount, stages: [] });
+  }
+  for (const stage of input.stages) {
+    if (stage.kind === "adjustment") {
+      const adjustment = stage.adjustment;
+      if ((adjustment.kind === "scale" && (!(adjustment.factor > 0) || !Number.isFinite(adjustment.factor))) ||
+        (adjustment.kind === "currency" && (!(adjustment.rate > 0) || !Number.isFinite(adjustment.rate) || !isRealIsoDate(adjustment.rateDate))))
+        return unavailable(identityInput, input.inputUnit, outputUnit, { code: "invalid-configuration", capability: "shared-financial-terms", path: `$.stages.${adjustment.id}`, message: "Scale/currency adjustments require a positive finite factor and currency requires a real rateDate" });
+      if (adjustment.kind === "currency") {
+        if (outputUnit !== adjustment.fromUnit)
+          return unavailable(identityInput, input.inputUnit, outputUnit, { code: "incompatible-semantics", capability: "shared-financial-terms", path: `$.stages.${adjustment.id}.fromUnit`, message: `Currency adjustment expected ${adjustment.fromUnit} but current unit is ${outputUnit}` });
+        outputUnit = adjustment.toUnit;
+      }
+      for (const item of working.values()) {
+        const before = item.amount;
+        if (adjustment.kind === "scale") item.amount *= adjustment.factor;
+        else if (adjustment.kind === "currency") item.amount *= adjustment.rate;
+        else {
+          const measureId = adjustment.kind === "net-recovery" ? adjustment.recoveryMeasureId : adjustment.expenseMeasureId;
+          const component = item.observation.measures[measureId];
+          if (typeof component !== "number" || !Number.isFinite(component))
+            return unavailable(identityInput, input.inputUnit, outputUnit, { code: "missing-prerequisite", capability: "shared-financial-terms", path: `$.observations.${item.observation.claimId}.measures.${measureId}`, message: `Adjustment ${adjustment.id} requires finite ${measureId}`, requiredFields: [measureId] });
+          item.amount += adjustment.kind === "include-expense" ? component : -component;
+        }
+        item.stages.push({ stageId: adjustment.id, stageKind: "adjustment", inputAmount: before, outputAmount: item.amount });
+      }
+    } else {
+      const observations = [...working.values()].map((item) => snapshotDiagnosticJson({ ...item.observation, measures: { ...item.observation.measures, [PIPELINE_MEASURE]: item.amount } }));
+      const terms = stage.terms.map((term) => ({ ...term, measureId: PIPELINE_MEASURE }));
+      const applied = applyFinancialTerms({ observations, terms, completeFinancialPopulation: input.completeFinancialPopulation, reportingClaims: input.reportingClaims });
+      if (applied.status === "unavailable")
+        return snapshotDiagnosticJson({ status: "unavailable", inputUnit: input.inputUnit, outputUnit, calculationIdentity: `fnv1a64-jcs-v1:${fnv1a64(canonicalJson(identityInput))}`, claims: [], findings: applied.findings });
+      for (const claim of applied.claims) {
+        const item = working.get(canonicalJson([claim.sourceNamespace, claim.claimId]))!;
+        const before = item.amount;
+        item.amount = claim.outputAmount;
+        item.stages.push({ stageId: stage.id, stageKind: "terms", inputAmount: before, outputAmount: item.amount });
+      }
+    }
+  }
+  const claims = [...working.values()].sort((a, b) => key(a.observation).localeCompare(key(b.observation))).map((item) => ({ sourceNamespace: item.observation.sourceNamespace, claimId: item.observation.claimId, inputAmount: item.inputAmount, outputAmount: item.amount, stages: item.stages }));
+  return snapshotDiagnosticJson({ status: "available", inputUnit: input.inputUnit, outputUnit, calculationIdentity: `fnv1a64-jcs-v1:${fnv1a64(canonicalJson(identityInput))}`, claims, findings: [] });
+}

package/src/financialTerms.ts

@@ -0,0 +1,263 @@
+import { canonicalJson, fnv1a64 } from "./canonical.js";
+import type {
+  CustomizationCapabilityFinding,
+  FinancialClaimAllocationResult,
+  FinancialTermApplicationResult,
+  FinancialTermDefinition,
+  FinancialTermScheduleEntry,
+  FinancialTermScheduleResolution,
+  AnalysisMeasureDefinitionV1,
+  PreparedHistoricalObservation,
+} from "./customizationContracts.js";
+import { isRealIsoDate, snapshotDiagnosticJson } from "./diagnosticRuntime.js";
+
+function claimKey(sourceNamespace: string, claimId: string): string {
+  return canonicalJson([sourceNamespace, claimId]);
+}
+
+function finding(
+  code: CustomizationCapabilityFinding["code"],
+  message: string,
+  requiredFields?: readonly string[],
+): CustomizationCapabilityFinding {
+  return {
+    code,
+    capability: "shared-financial-terms",
+    path: "$.financialTerms",
+    message,
+    ...(requiredFields === undefined ? {} : { requiredFields }),
+  };
+}
+
+/** Resolves the highest-priority applicable term schedule entry at a coverage date. */
+export function resolveFinancialTermSchedule(input: {
+  readonly entries: readonly FinancialTermScheduleEntry[];
+  readonly coverageDate: string;
+  readonly policyIds: readonly string[];
+  readonly coverageIds: readonly string[];
+}): FinancialTermScheduleResolution {
+  if (!isRealIsoDate(input.coverageDate))
+    return snapshotDiagnosticJson({
+      status: "unavailable",
+      entryId: null,
+      termIds: [],
+      finding: finding("missing-prerequisite", "A valid coverage date is required", ["coverageDate"]),
+    });
+  if (
+    input.entries.some(
+      (entry) =>
+        !isRealIsoDate(entry.effectiveStart) ||
+        !isRealIsoDate(entry.effectiveEnd) ||
+        entry.effectiveStart >= entry.effectiveEnd ||
+        !Number.isSafeInteger(entry.priority),
+    )
+  )
+    return snapshotDiagnosticJson({
+      status: "unavailable",
+      entryId: null,
+      termIds: [],
+      finding: finding("invalid-configuration", "Term schedule entries require valid intervals and safe-integer priorities"),
+    });
+  const applicable = input.entries.filter((entry) => {
+    const dateMatches = entry.effectiveStart <= input.coverageDate && input.coverageDate < entry.effectiveEnd;
+    const policyMatches = entry.policyIds === undefined || entry.policyIds.some((id) => input.policyIds.includes(id));
+    const coverageMatches = entry.coverageIds === undefined || entry.coverageIds.some((id) => input.coverageIds.includes(id));
+    return dateMatches && policyMatches && coverageMatches;
+  });
+  if (applicable.length === 0)
+    return snapshotDiagnosticJson({
+      status: "unavailable",
+      entryId: null,
+      termIds: [],
+      finding: finding("missing-prerequisite", "No financial term schedule entry applies"),
+    });
+  const priority = Math.max(...applicable.map((entry) => entry.priority));
+  const selected = applicable.filter((entry) => entry.priority === priority);
+  if (selected.length !== 1)
+    return snapshotDiagnosticJson({
+      status: "ambiguous",
+      entryId: null,
+      termIds: [],
+      finding: finding("ambiguous-attribution", `Multiple financial term schedule entries share priority ${priority}`),
+    });
+  return snapshotDiagnosticJson({
+    status: "resolved",
+    entryId: selected[0]!.id,
+    termIds: selected[0]!.termIds,
+    finding: null,
+  });
+}
+
+interface WorkingClaim {
+  readonly observation: PreparedHistoricalObservation;
+  readonly key: string;
+  readonly inputAmount: number;
+  amount: number;
+  readonly stages: {
+    termId: string;
+    groupId: string;
+    inputAmount: number;
+    outputAmount: number;
+    removedAmount: number;
+  }[];
+}
+
+function limitedAmount(total: number, attachment: number, limit: number | null): number {
+  const excess = Math.max(total - attachment, 0);
+  return limit === null ? excess : Math.min(excess, limit);
+}
+
+function unavailable(
+  observations: readonly PreparedHistoricalObservation[],
+  terms: readonly FinancialTermDefinition[],
+  issues: readonly CustomizationCapabilityFinding[],
+): FinancialTermApplicationResult {
+  const identity = `fnv1a64-jcs-v1:${fnv1a64(canonicalJson({ kind: "financial-terms", observations, terms }))}`;
+  return snapshotDiagnosticJson({
+    status: "unavailable",
+    calculationIdentity: identity,
+    inputTotal: null,
+    outputTotal: null,
+    claims: [],
+    findings: issues,
+  });
+}
+
+/** Applies ordered shared financial terms to the complete population, then marks the reporting view. */
+export function applyFinancialTerms(input: {
+  readonly observations: readonly PreparedHistoricalObservation[];
+  readonly terms: readonly FinancialTermDefinition[];
+  readonly completeFinancialPopulation: boolean;
+  readonly measureDefinitions?: readonly AnalysisMeasureDefinitionV1[];
+  readonly reportingClaims?: readonly { readonly sourceNamespace: string; readonly claimId: string }[];
+}): FinancialTermApplicationResult {
+  if (!input.completeFinancialPopulation)
+    return unavailable(input.observations, input.terms, [
+      finding("incomplete-financial-population", "Shared financial terms require the complete related population"),
+    ]);
+  if (input.terms.some((term) => term.kind === "policy-aggregate" && term.allocation === "chronological"))
+    return unavailable(input.observations, input.terms, [
+      finding("unsupported-operation", "Chronological aggregate allocation requires ordered transaction input", ["ordered transactions"]),
+    ]);
+  const sourceMeasure = (id: string): string | undefined => {
+    const definition = input.measureDefinitions?.find((measure) => measure.id === id);
+    if (definition === undefined) return input.measureDefinitions === undefined ? id : undefined;
+    return definition.statistic.kind === "sum" ? definition.statistic.measureId : undefined;
+  };
+  const measureIds = [...new Set(input.terms.map((term) => sourceMeasure(term.measureId)))];
+  if (measureIds.includes(undefined))
+    return unavailable(input.observations, input.terms, [
+      finding("incompatible-semantics", "Financial terms require a referenced sum measure"),
+    ]);
+  if (measureIds.length > 1)
+    return unavailable(input.observations, input.terms, [
+      finding("incompatible-semantics", "One ordered financial term application must use a single amount measure"),
+    ]);
+  const measureId = measureIds[0];
+  if (measureId === undefined)
+    return unavailable(input.observations, input.terms, [
+      finding("invalid-configuration", "At least one financial term is required"),
+    ]);
+  const seen = new Set<string>();
+  const working: WorkingClaim[] = [];
+  for (const observation of input.observations) {
+    const key = claimKey(observation.sourceNamespace, observation.claimId);
+    if (seen.has(key))
+      return unavailable(input.observations, input.terms, [
+        finding("incompatible-semantics", "Financial input must contain one selected observation per claim"),
+      ]);
+    seen.add(key);
+    const amount = observation.measures[measureId];
+    if (typeof amount !== "number" || !Number.isFinite(amount))
+      return unavailable(input.observations, input.terms, [
+        finding("missing-prerequisite", `Claim ${observation.claimId} lacks finite measure ${measureId}`, [measureId]),
+      ]);
+    if (amount < 0)
+      return unavailable(input.observations, input.terms, [
+        finding("unsupported-operation", "Negative amounts and recoveries require a separately declared financial convention"),
+      ]);
+    working.push({ observation, key, inputAmount: amount, amount, stages: [] });
+  }
+  working.sort((left, right) => left.key.localeCompare(right.key));
+
+  for (const term of input.terms) {
+    const groups = new Map<string, WorkingClaim[]>();
+    for (const claim of working) {
+      let groupId: string | undefined;
+      if (term.kind === "claim-layer") groupId = claim.key;
+      else if (term.kind === "occurrence-layer") {
+        const occurrenceId = claim.observation.relationships.occurrenceId;
+        if (occurrenceId !== undefined) groupId = canonicalJson([claim.observation.sourceNamespace, occurrenceId]);
+      } else {
+        const policyIds = claim.observation.relationships.policyIds;
+        if (policyIds?.length === 1) groupId = canonicalJson([claim.observation.sourceNamespace, policyIds[0]]);
+      }
+      if (groupId === undefined)
+        return unavailable(input.observations, input.terms, [
+          finding(
+            "missing-prerequisite",
+            `${term.kind} requires one unambiguous grouping identifier for claim ${claim.observation.claimId}`,
+            [term.kind === "occurrence-layer" ? "occurrenceId" : "policyId"],
+          ),
+        ]);
+      const group = groups.get(groupId);
+      if (group === undefined) groups.set(groupId, [claim]);
+      else group.push(claim);
+    }
+    for (const [groupId, group] of groups) {
+      const total = group.reduce((sum, claim) => sum + claim.amount, 0);
+      const output =
+        term.kind === "policy-aggregate"
+          ? limitedAmount(total, term.deductible, term.limit)
+          : limitedAmount(total, term.attachment, term.limit);
+      let allocated = 0;
+      group.forEach((claim, index) => {
+        const before = claim.amount;
+        const after =
+          index === group.length - 1
+            ? output - allocated
+            : total === 0
+              ? 0
+              : output * (before / total);
+        allocated += after;
+        claim.amount = Object.is(after, -0) ? 0 : after;
+        claim.stages.push({
+          termId: term.id,
+          groupId,
+          inputAmount: before,
+          outputAmount: claim.amount,
+          removedAmount: before - claim.amount,
+        });
+      });
+    }
+  }
+
+  const reported = new Set(
+    input.reportingClaims?.map((claim) => claimKey(claim.sourceNamespace, claim.claimId)) ?? working.map((claim) => claim.key),
+  );
+  const claims: FinancialClaimAllocationResult[] = working
+    .sort((left, right) => left.key.localeCompare(right.key))
+    .map((claim) => ({
+      sourceNamespace: claim.observation.sourceNamespace,
+      claimId: claim.observation.claimId,
+      reported: reported.has(claim.key),
+      inputAmount: claim.inputAmount,
+      outputAmount: claim.amount,
+      stages: claim.stages,
+    }));
+  const identityValue = {
+    kind: "financial-terms",
+    population: [...input.observations].sort((left, right) =>
+      claimKey(left.sourceNamespace, left.claimId).localeCompare(claimKey(right.sourceNamespace, right.claimId)),
+    ),
+    terms: input.terms,
+  };
+  return snapshotDiagnosticJson({
+    status: "available",
+    calculationIdentity: `fnv1a64-jcs-v1:${fnv1a64(canonicalJson(identityValue))}`,
+    inputTotal: claims.reduce((total, claim) => total + claim.inputAmount, 0),
+    outputTotal: claims.reduce((total, claim) => total + claim.outputAmount, 0),
+    claims,
+    findings: [],
+  });
+}

package/src/fnvAccumulator.ts

@@ -4,14 +4,20 @@ export function createFnvAccumulator() {
   let low = 0x84222325;
   return {
     update(bytes: Uint8Array) {
-      for (const byte of bytes) {
-        low = (low ^ byte) >>> 0;
+      // Keep the hot byte loop's words local rather than writing captured
+      // accumulator state on every byte. Chunk boundaries do not affect FNV.
+      let nextHigh = high;
+      let nextLow = low;
+      for (let index = 0; index < bytes.length; index++) {
+        nextLow = (nextLow ^ bytes[index]!) >>> 0;
         // FNV_PRIME = 2^40 + 435. Every intermediate stays below 2^42,
         // preserving the exact modular multiplication of the BigInt form.
-        const product = low * 0x1b3;
-        high = (high * 0x1b3 + Math.floor(product / 0x100000000) + (low << 8)) >>> 0;
-        low = product >>> 0;
+        const product = nextLow * 0x1b3;
+        nextHigh = (nextHigh * 0x1b3 + Math.floor(product / 0x100000000) + (nextLow << 8)) >>> 0;
+        nextLow = product >>> 0;
       }
+      high = nextHigh;
+      low = nextLow;
     },
     digest() {
       return high.toString(16).padStart(8, "0") + low.toString(16).padStart(8, "0");