@actuarial-ts/compliance 0.7.0 → 0.8.0

package/src/customizationHistoryReplay.ts

@@ -0,0 +1,221 @@
+import {
+  canonicalJson,
+  fnv1a64,
+  isDiagnosticToken,
+  isRealIsoDate,
+  type AnalysisStatisticDefinition,
+  type CustomizationResourceLimits,
+  type HistoricalDatasetInput,
+  type JsonValue,
+  type PreparedHistoricalObservation,
+} from "@actuarial-ts/core";
+import {
+  externalSortCustomizationRecords,
+  parseCustomizationResourceLimits,
+  parseHistoricalDatasetInput,
+  streamPreparedHistoricalDataset,
+  type CustomizationExternalRecord,
+  type CustomizationExternalStateAdapter,
+} from "@actuarial-ts/data";
+import { ComplianceError } from "./errors.js";
+import {
+  assertComputedDiagnosticArtifactDigest,
+  type ComputedDiagnosticArtifactDigest,
+} from "./diagnosticArtifactStream.js";
+import {
+  writeBoundedAnalysisReplay,
+  parseBoundedReplayMeasures,
+  type BoundedReplayMeasure,
+} from "./customizationBoundedReplay.js";
+
+type MergeableHistoryStatistic = Extract<
+  AnalysisStatisticDefinition,
+  {
+    readonly kind:
+      | "sum"
+      | "ratio"
+      | "weighted-mean"
+      | "minimum"
+      | "maximum";
+  }
+>;
+
+/** Statistics that can be calculated directly while normalized history is streamed. */
+export interface BoundedHistoryReplayMeasure
+  extends Omit<BoundedReplayMeasure, "statistic" | "orderedPopulationSize"> {
+  readonly statistic: MergeableHistoryStatistic;
+}
+
+type HistoryMeasureRecord = {
+  readonly measures: Readonly<Record<string, number | null>>;
+};
+
+function selectedRecord(
+  observation: PreparedHistoricalObservation,
+): CustomizationExternalRecord<HistoryMeasureRecord & JsonValue> {
+  const claimKey = canonicalJson([
+    observation.sourceNamespace,
+    observation.claimId,
+  ]);
+  const identity = canonicalJson([
+    observation.sourceNamespace,
+    observation.claimId,
+    observation.evaluationDate,
+  ]);
+  return {
+    id: `selected-${fnv1a64(identity)}`,
+    partitionKey: claimKey,
+    orderKey: observation.evaluationDate,
+    value: { measures: observation.measures } as HistoryMeasureRecord & JsonValue,
+  };
+}
+
+function reviewFailure(code: string, message: string): never {
+  throw new ComplianceError(
+    "BAD_DIAGNOSTIC_RUN",
+    `Historical preparation review failed (${code}): ${message}`,
+    "$.boundedHistoryReplay",
+  );
+}
+
+/**
+ * Connects raw versioned history to independently verifiable bounded replay.
+ *
+ * The function performs two host-owned external stages. The first resolves raw
+ * revisions one claim at a time. The second retains normalized selected
+ * records until preparation has completed without findings. No replay header
+ * is emitted before that review gate passes, so failed or cancelled work cannot
+ * be mistaken for a completed artifact.
+ *
+ * This path intentionally supports mergeable statistics only. Exact distinct
+ * counts and quantiles require their documented external ordering, while
+ * exposure joins and shared financial terms use their capability-specific
+ * execution paths.
+ */
+export async function* writeBoundedHistoryAnalysisReplay(input: {
+  readonly runId: string;
+  readonly sourceArtifact: ComputedDiagnosticArtifactDigest;
+  readonly header: Omit<HistoricalDatasetInput, "records">;
+  readonly records: AsyncIterable<unknown> | Iterable<unknown>;
+  readonly evaluationDate: string;
+  readonly observationSelection: "exact" | "latest-on-or-before";
+  readonly measures: readonly BoundedHistoryReplayMeasure[];
+  readonly adapter: CustomizationExternalStateAdapter;
+  readonly limits: CustomizationResourceLimits;
+  readonly signal?: AbortSignal;
+}): AsyncGenerator<Uint8Array> {
+  const runId = input.runId;
+  const sourceArtifact = input.sourceArtifact;
+  const records = input.records;
+  const adapter = input.adapter;
+  const signal = input.signal;
+  const evaluationDate = input.evaluationDate;
+  const observationSelection = input.observationSelection;
+  const limits = parseCustomizationResourceLimits(input.limits);
+  const parsedHeader = parseHistoricalDatasetInput({ ...input.header, records: [] });
+  const { records: _emptyRecords, ...header } = parsedHeader;
+  const parsedMeasures = parseBoundedReplayMeasures(input.measures, limits);
+  if (parsedMeasures.some((measure) => !["sum", "ratio", "weighted-mean", "minimum", "maximum"].includes(measure.statistic.kind)))
+    reviewFailure("unsupported-statistic", "Raw-history replay supports mergeable statistics only");
+  const measures = parsedMeasures as readonly BoundedHistoryReplayMeasure[];
+  const historyContext: JsonValue = JSON.parse(canonicalJson(header));
+  if (!isDiagnosticToken(runId))
+    reviewFailure("invalid-run", "runId must be a valid token");
+  assertComputedDiagnosticArtifactDigest(sourceArtifact);
+  if (!isRealIsoDate(evaluationDate))
+    reviewFailure("invalid-period", "evaluationDate must be a real Gregorian date");
+  if (observationSelection !== "exact" && observationSelection !== "latest-on-or-before")
+    reviewFailure("invalid-selection", "observationSelection is invalid");
+  async function* normalized(): AsyncGenerator<
+    CustomizationExternalRecord<HistoryMeasureRecord & JsonValue>
+  > {
+    let claimKey: string | undefined;
+    let claim: PreparedHistoricalObservation[] = [];
+    const selected = function* (): Generator<
+      CustomizationExternalRecord<HistoryMeasureRecord & JsonValue>
+    > {
+      const candidates = claim.filter((observation) =>
+        observationSelection === "exact"
+          ? observation.evaluationDate === evaluationDate
+          : observation.evaluationDate <= evaluationDate,
+      );
+      const observation = candidates.reduce<PreparedHistoricalObservation | undefined>(
+        (latest, candidate) =>
+          latest === undefined || candidate.evaluationDate > latest.evaluationDate
+            ? candidate
+            : latest,
+        undefined,
+      );
+      if (observation !== undefined) yield selectedRecord(observation);
+      claim = [];
+    };
+    for await (const event of streamPreparedHistoricalDataset({
+      runId: `${runId}-raw`,
+      header,
+      records,
+      adapter,
+      limits,
+      ...(signal === undefined ? {} : { signal }),
+    })) {
+      if (event.kind === "finding")
+        reviewFailure(event.finding.code, event.finding.message);
+      if (event.kind === "observation") {
+        const nextClaimKey = canonicalJson([
+          event.observation.sourceNamespace,
+          event.observation.claimId,
+        ]);
+        if (claimKey !== undefined && nextClaimKey !== claimKey) yield* selected();
+        claimKey = nextClaimKey;
+        claim.push(event.observation);
+      }
+    }
+    yield* selected();
+  }
+
+  const staged = externalSortCustomizationRecords({
+    runId: `${runId}-selected`,
+    records: normalized(),
+    adapter,
+    limits,
+    ...(signal === undefined ? {} : { signal }),
+  });
+  const iterator = staged[Symbol.asyncIterator]();
+
+  // Pulling the first record completes both preparation and the review gate.
+  // It retains at most one selected record in SDK memory.
+  const first = await iterator.next();
+  async function* reviewedRecords(): AsyncGenerator<
+    CustomizationExternalRecord<HistoryMeasureRecord & JsonValue>
+  > {
+    try {
+      if (!first.done) yield first.value;
+      if (!first.done) {
+        for (;;) {
+          const next = await iterator.next();
+          if (next.done) break;
+          yield next.value;
+        }
+      }
+    } finally {
+      await iterator.return?.(undefined);
+    }
+  }
+
+  try {
+    yield* writeBoundedAnalysisReplay({
+      runId,
+      sourceArtifact,
+      measures,
+      calculationContext: {
+        history: historyContext,
+        evaluationDate,
+        observationSelection,
+      },
+      records: reviewedRecords(),
+      limits,
+      ...(signal === undefined ? {} : { signal }),
+    });
+  } finally {
+    await iterator.return?.(undefined);
+  }
+}

package/src/customizationRun.ts

@@ -0,0 +1,113 @@
+import {
+  canonicalJson,
+  fnv1a64,
+  isRealIsoDate,
+  runAnalysisRecipe,
+  type AnalysisDefinition,
+  type AnalysisRecipe,
+  type AnalysisResult,
+  type CustomizationExposureObservation,
+  type ExposureAllocationTarget,
+  type ExposureRevisionSelection,
+  type HistoricalDatasetInput,
+} from "@actuarial-ts/core";
+import {
+  parseAnalysisDefinition,
+  parseAnalysisRecipe,
+  parseAnalysisResult,
+  parseCustomizationExposureObservations,
+  parseExposureAllocationTargets,
+  parseExposureRevisionSelection,
+  parseHistoricalDatasetInput,
+} from "@actuarial-ts/data";
+import { ComplianceError } from "./errors.js";
+import {
+  assertComputedDiagnosticArtifactDigest,
+  type ComputedDiagnosticArtifactDigest,
+} from "./diagnosticArtifactStream.js";
+import type { DiagnosticArtifactDigest } from "./diagnosticRun.js";
+
+declare const verifiedCustomizationRunBrand: unique symbol;
+export interface VerifiedCustomizationAnalysisRun {
+  readonly [verifiedCustomizationRunBrand]: true;
+  readonly assurance: "sdk-rerun-verified";
+  readonly runIdentity: string;
+  readonly result: AnalysisResult;
+  readonly inputArtifacts: readonly DiagnosticArtifactDigest[];
+}
+
+const verifiedRuns = new WeakSet<object>();
+
+function invalid(message: string, path = "$.customizationRun"): never {
+  throw new ComplianceError("BAD_DIAGNOSTIC_RUN", message, path);
+}
+
+/**
+ * Revalidates and reruns a complete supported customization recipe, then issues
+ * an authentic receipt binding the exact output to the supplied source digests.
+ */
+export function verifyCustomizationAnalysisRun(input: {
+  readonly history: HistoricalDatasetInput;
+  readonly definition: AnalysisDefinition;
+  readonly recipe: AnalysisRecipe;
+  readonly expectedResult: AnalysisResult;
+  readonly inputArtifacts: readonly ComputedDiagnosticArtifactDigest[];
+  readonly exposureObservations?: readonly CustomizationExposureObservation[];
+  readonly exposureTargets?: readonly ExposureAllocationTarget[];
+  readonly exposureRevisionSelection?: ExposureRevisionSelection;
+  readonly evaluationDate?: string;
+}): VerifiedCustomizationAnalysisRun {
+  if (!Array.isArray(input.inputArtifacts) || input.inputArtifacts.length === 0)
+    invalid("Customization verification requires at least one authentic input artifact", "$.inputArtifacts");
+  const artifacts = [...input.inputArtifacts];
+  artifacts.forEach(assertComputedDiagnosticArtifactDigest);
+  if (new Set(artifacts.map((artifact) => artifact.id)).size !== artifacts.length)
+    invalid("Customization input artifact IDs must be unique", "$.inputArtifacts");
+  if (input.evaluationDate !== undefined && !isRealIsoDate(input.evaluationDate))
+    invalid("Customization evaluationDate must be a real Gregorian date", "$.evaluationDate");
+
+  const history = parseHistoricalDatasetInput(input.history);
+  const definition = parseAnalysisDefinition(input.definition);
+  const recipe = parseAnalysisRecipe(input.recipe);
+  const expected = parseAnalysisResult(input.expectedResult);
+  const exposureObservations = parseCustomizationExposureObservations(input.exposureObservations ?? []);
+  const exposureTargets = parseExposureAllocationTargets(input.exposureTargets ?? []);
+  const exposureRevisionSelection = input.exposureRevisionSelection === undefined
+    ? undefined
+    : parseExposureRevisionSelection(input.exposureRevisionSelection);
+  const result = runAnalysisRecipe({
+    history,
+    definition,
+    recipe,
+    exposureObservations,
+    exposureTargets,
+    ...(exposureRevisionSelection === undefined ? {} : { exposureRevisionSelection }),
+    ...(input.evaluationDate === undefined ? {} : { evaluationDate: input.evaluationDate }),
+  });
+  if (canonicalJson(result) !== canonicalJson(expected))
+    throw new ComplianceError(
+      "DIAGNOSTIC_MISMATCH",
+      "Customization result does not match an exact fresh SDK rerun",
+      "$.expectedResult",
+    );
+  const inputArtifacts = Object.freeze(artifacts) as readonly DiagnosticArtifactDigest[];
+  const runIdentity = `fnv1a64-jcs-v1:${fnv1a64(canonicalJson({
+    result,
+    inputArtifacts,
+  }))}`;
+  const receipt = Object.freeze({
+    assurance: "sdk-rerun-verified" as const,
+    runIdentity,
+    result,
+    inputArtifacts,
+  }) as VerifiedCustomizationAnalysisRun;
+  verifiedRuns.add(receipt);
+  return receipt;
+}
+
+export function assertVerifiedCustomizationAnalysisRun(
+  value: unknown,
+): asserts value is VerifiedCustomizationAnalysisRun {
+  if (value === null || typeof value !== "object" || !verifiedRuns.has(value))
+    invalid("Value is not an authentic SDK-rerun-verified customization run");
+}

package/src/index.ts

@@ -15,5 +15,8 @@ export {
 } from "./diagnosticCompactRun.js";
 export * from "./diagnosticReplayWriter.js";
 export * from "./diagnosticReplayReader.js";
+export * from "./customizationBoundedReplay.js";
+export * from "./customizationHistoryReplay.js";
+export * from "./customizationRun.js";
 export * from "./bundle.js";
 export * from "./ave.js";

package/src/version.ts

@@ -1 +1 @@
-export const COMPLIANCE_PACKAGE_VERSION = "0.7.0";
+export const COMPLIANCE_PACKAGE_VERSION = "0.8.0";