@actuarial-ts/compliance 0.7.1 → 0.8.0

package/src/customizationBoundedReplay.ts

@@ -0,0 +1,524 @@
+import {
+  BOUNDED_REPLAY_CONTRACT_VERSION,
+  canonicalJson,
+  diagnosticJsonPreflight,
+  fnv1a64,
+  isDiagnosticPlainRecord,
+  isDiagnosticToken,
+  snapshotDiagnosticJson,
+  type AnalysisStatisticDefinition,
+  type CustomizationResourceLimits,
+  type JsonValue,
+} from "@actuarial-ts/core";
+import {
+  parseCustomizationResourceLimits,
+  type CustomizationExternalRecord,
+} from "@actuarial-ts/data";
+import { z } from "zod";
+import { ComplianceError } from "./errors.js";
+import {
+  assertComputedDiagnosticArtifactDigest,
+  type ComputedDiagnosticArtifactDigest,
+} from "./diagnosticArtifactStream.js";
+import { createSha256 } from "./sha256Stream.js";
+import type { DiagnosticArtifactDigest } from "./diagnosticRun.js";
+
+export type BoundedReplayStatistic = Extract<
+  AnalysisStatisticDefinition,
+  { readonly kind: "sum" | "ratio" | "weighted-mean" | "minimum" | "maximum" | "distinct-count" | "quantile" }
+>;
+
+export interface BoundedReplayMeasure {
+  readonly id: string;
+  readonly unit: string;
+  readonly statistic: BoundedReplayStatistic;
+  /** Required for exact externally ordered quantiles; counts finite values. */
+  readonly orderedPopulationSize?: number;
+}
+
+export interface BoundedReplayValue {
+  readonly measureId: string;
+  readonly value: number | null;
+  readonly numerator: number | null;
+  readonly denominator: number | null;
+}
+
+export interface BoundedReplayVerification {
+  readonly contractVersion: typeof BOUNDED_REPLAY_CONTRACT_VERSION;
+  readonly runId: string;
+  readonly sourceArtifact: DiagnosticArtifactDigest;
+  readonly calculationContext?: JsonValue;
+  readonly recordCount: number;
+  readonly recordDigest: string;
+  readonly calculationIdentity: string;
+  readonly values: readonly BoundedReplayValue[];
+}
+
+declare const verifiedBoundedReplayBrand: unique symbol;
+export type VerifiedBoundedReplayReceipt = BoundedReplayVerification & {
+  readonly [verifiedBoundedReplayBrand]: true;
+};
+const verifiedBoundedReplayReceipts = new WeakSet<object>();
+
+/** Refuses structurally similar JSON that did not come from independent replay. */
+export function assertVerifiedBoundedReplayReceipt(
+  value: unknown,
+): asserts value is VerifiedBoundedReplayReceipt {
+  if (
+    value === null ||
+    typeof value !== "object" ||
+    !verifiedBoundedReplayReceipts.has(value)
+  )
+    invalid("Value is not an authentic independently verified bounded replay receipt");
+}
+
+type MeasureRecord = {
+  readonly measures: Readonly<Record<string, number | null>>;
+  /** Namespaced stable keys used by externally ordered exact distinct counts. */
+  readonly entityKeys?: Readonly<Record<string, string | null>>;
+};
+const encoder = new TextEncoder();
+const tokenSchema = z.string().refine(isDiagnosticToken, "Expected a valid token");
+const finiteSchema = z.number().finite();
+const jsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([
+    z.null(),
+    z.boolean(),
+    finiteSchema,
+    z.string(),
+    z.array(jsonValueSchema),
+    z.record(jsonValueSchema),
+  ]),
+);
+const sourceArtifactSchema = z.object({
+  id: tokenSchema,
+  scope: z.enum(["input", "preparation"]),
+  assurance: z.literal("sdk-computed"),
+  algorithm: z.literal("sha256"),
+  value: z.string().regex(/^[0-9a-f]{64}$/),
+  byteLength: z.number().int().nonnegative().safe(),
+}).strict();
+const statisticSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("sum"), measureId: tokenSchema }).strict(),
+  z.object({
+    kind: z.literal("ratio"),
+    numeratorMeasureId: tokenSchema,
+    denominatorMeasureId: tokenSchema,
+    scale: finiteSchema,
+    denominatorRule: z.enum(["positive", "nonzero"]),
+  }).strict(),
+  z.object({ kind: z.literal("weighted-mean"), measureId: tokenSchema, weightMeasureId: tokenSchema }).strict(),
+  z.object({ kind: z.literal("minimum"), measureId: tokenSchema }).strict(),
+  z.object({ kind: z.literal("maximum"), measureId: tokenSchema }).strict(),
+  z.object({ kind: z.literal("distinct-count"), entity: z.enum(["claim", "claimant", "occurrence", "policy", "coverage"]) }).strict(),
+  z.object({ kind: z.literal("quantile"), measureId: tokenSchema, probability: finiteSchema.min(0).max(1), method: z.literal("hf-type-7") }).strict(),
+]);
+const boundedReplayMeasureSchema: z.ZodType<BoundedReplayMeasure> = z.object({
+  id: tokenSchema,
+  unit: tokenSchema,
+  statistic: statisticSchema,
+  orderedPopulationSize: z.number().int().positive().safe().optional(),
+}).strict();
+const replayValueSchema: z.ZodType<BoundedReplayValue> = z.object({
+  measureId: tokenSchema,
+  value: finiteSchema.nullable(),
+  numerator: finiteSchema.nullable(),
+  denominator: finiteSchema.nullable(),
+}).strict();
+const headerSchema = z.object({
+  type: z.literal("header"),
+  contractVersion: z.literal(BOUNDED_REPLAY_CONTRACT_VERSION),
+  runId: tokenSchema,
+  sourceArtifact: sourceArtifactSchema,
+  measures: z.array(boundedReplayMeasureSchema),
+  calculationContext: jsonValueSchema.optional(),
+}).strict();
+const measureRecordSchema = z.object({
+  measures: z.record(tokenSchema, finiteSchema.nullable()),
+  entityKeys: z.record(tokenSchema, z.string().nullable()).optional(),
+}).strict();
+const recordFrameSchema = z.object({
+  type: z.literal("record"),
+  record: z.object({
+    id: tokenSchema,
+    partitionKey: z.string(),
+    orderKey: z.string(),
+    value: measureRecordSchema,
+  }).strict(),
+}).strict();
+const trailerSchema = z.object({
+  type: z.literal("trailer"),
+  recordCount: z.number().int().nonnegative().safe(),
+  recordDigest: z.string().regex(/^[0-9a-f]{64}$/),
+  calculationIdentity: z.string().regex(/^fnv1a64-jcs-v1:[0-9a-f]{16}$/),
+  values: z.array(replayValueSchema),
+}).strict();
+
+function invalid(message: string): never {
+  throw new ComplianceError("BAD_DIAGNOSTIC_RUN", message, "$.boundedReplay");
+}
+
+function validateLimits(limits: unknown): CustomizationResourceLimits {
+  try {
+    return parseCustomizationResourceLimits(limits);
+  } catch (error) {
+    invalid(error instanceof Error ? error.message : "Invalid customization resource limits");
+  }
+}
+
+/** Validates and owns an untrusted bounded replay measure list. */
+export function parseBoundedReplayMeasures(
+  value: unknown,
+  limits: CustomizationResourceLimits,
+): readonly BoundedReplayMeasure[] {
+  const parsed = z.array(boundedReplayMeasureSchema).safeParse(value);
+  if (!parsed.success) invalid(`Bounded replay measures are invalid: ${parsed.error.issues[0]?.message ?? "schema mismatch"}`);
+  const measures = parsed.data;
+  if (measures.length === 0 || measures.length > limits.maximumOutputValues)
+    invalid("Bounded replay measure count is outside maximumOutputValues");
+  if (new Set(measures.map((measure) => measure.id)).size !== measures.length)
+    invalid("Bounded replay measure IDs must be unique");
+  for (const measure of measures) {
+    const statistic = measure.statistic;
+    if (statistic.kind === "quantile" && (!Number.isSafeInteger(measure.orderedPopulationSize) || measure.orderedPopulationSize! < 1))
+      invalid("Bounded replay exact quantile requires positive orderedPopulationSize");
+    if (statistic.kind !== "quantile" && measure.orderedPopulationSize !== undefined)
+      invalid("orderedPopulationSize applies only to bounded exact quantiles");
+  }
+  const distinctEntities = new Set(measures.flatMap((measure) => measure.statistic.kind === "distinct-count" ? [measure.statistic.entity] : []));
+  if (distinctEntities.size > 1) invalid("One bounded replay may externally order one distinct entity kind");
+  const quantileMeasures = new Set(measures.flatMap((measure) => measure.statistic.kind === "quantile" ? [measure.statistic.measureId] : []));
+  if (quantileMeasures.size > 1) invalid("One bounded replay may externally order one quantile source measure");
+  return snapshotDiagnosticJson(measures);
+}
+
+function checkedAdd(left: number, right: number, description: string): number {
+  const result = left + right;
+  if (!Number.isFinite(result)) invalid(`Bounded replay ${description} overflowed the finite number range`);
+  return Object.is(result, -0) ? 0 : result;
+}
+
+function checkedProduct(left: number, right: number, description: string): number {
+  const result = left * right;
+  if (!Number.isFinite(result)) invalid(`Bounded replay ${description} overflowed the finite number range`);
+  return Object.is(result, -0) ? 0 : result;
+}
+
+function checkedResult(value: number, description: string): number {
+  if (!Number.isFinite(value)) invalid(`Bounded replay ${description} overflowed the finite number range`);
+  return Object.is(value, -0) ? 0 : value;
+}
+
+interface Aggregate {
+  readonly definition: BoundedReplayMeasure;
+  sum: number;
+  numerator: number;
+  denominator: number;
+  pairs: number;
+  minimum: number;
+  maximum: number;
+  lastDistinctKey: string | null;
+  distinctCount: number;
+  orderedCount: number;
+  lastOrderedValue: number | null;
+  lowerOrderedValue: number | null;
+  upperOrderedValue: number | null;
+}
+
+function aggregates(measures: readonly BoundedReplayMeasure[]): Aggregate[] {
+  return measures.map((definition) => ({ definition, sum: 0, numerator: 0, denominator: 0, pairs: 0, minimum: Number.POSITIVE_INFINITY, maximum: Number.NEGATIVE_INFINITY, lastDistinctKey: null, distinctCount: 0, orderedCount: 0, lastOrderedValue: null, lowerOrderedValue: null, upperOrderedValue: null }));
+}
+
+function acceptRecord(state: Aggregate[], record: MeasureRecord): void {
+  for (const aggregate of state) {
+    const statistic = aggregate.definition.statistic;
+    if (statistic.kind === "sum") {
+      const value = record.measures[statistic.measureId];
+      if (typeof value === "number" && Number.isFinite(value)) aggregate.sum = checkedAdd(aggregate.sum, value, "sum");
+    } else if (statistic.kind === "ratio") {
+      const numerator = record.measures[statistic.numeratorMeasureId];
+      const denominator = record.measures[statistic.denominatorMeasureId];
+      if (typeof numerator === "number" && Number.isFinite(numerator) && typeof denominator === "number" && Number.isFinite(denominator)) {
+        aggregate.numerator = checkedAdd(aggregate.numerator, numerator, "ratio numerator");
+        aggregate.denominator = checkedAdd(aggregate.denominator, denominator, "ratio denominator");
+        aggregate.pairs += 1;
+      }
+    } else if (statistic.kind === "weighted-mean") {
+      const value = record.measures[statistic.measureId];
+      const weight = record.measures[statistic.weightMeasureId];
+      if (typeof value === "number" && Number.isFinite(value) && typeof weight === "number" && Number.isFinite(weight)) {
+        if (weight < 0) invalid("Bounded weighted mean encountered a negative weight");
+        if (weight > 0) {
+          aggregate.numerator = checkedAdd(aggregate.numerator, checkedProduct(value, weight, "weighted product"), "weighted numerator");
+          aggregate.denominator = checkedAdd(aggregate.denominator, weight, "weight denominator");
+          aggregate.pairs += 1;
+        }
+      }
+    } else if (statistic.kind === "minimum" || statistic.kind === "maximum") {
+      const value = record.measures[statistic.measureId];
+      if (typeof value === "number" && Number.isFinite(value)) {
+        aggregate.minimum = Math.min(aggregate.minimum, value);
+        aggregate.maximum = Math.max(aggregate.maximum, value);
+        aggregate.pairs += 1;
+      }
+    } else if (statistic.kind === "distinct-count") {
+      const distinctKey = record.entityKeys?.[statistic.entity];
+      if (distinctKey === undefined) invalid(`Bounded distinct count requires entityKeys.${statistic.entity}`);
+      if (distinctKey === null) continue;
+      if (aggregate.lastDistinctKey !== null && distinctKey < aggregate.lastDistinctKey)
+        invalid("Bounded distinct keys are not in external ascending order");
+      if (distinctKey !== aggregate.lastDistinctKey) {
+        if (aggregate.distinctCount === Number.MAX_SAFE_INTEGER) invalid("Bounded distinct count exceeds the safe integer range");
+        aggregate.distinctCount += 1;
+      }
+      aggregate.lastDistinctKey = distinctKey;
+    } else {
+      if (statistic.kind !== "quantile") invalid("Unsupported bounded replay statistic");
+      const value = record.measures[statistic.measureId];
+      if (typeof value !== "number" || !Number.isFinite(value)) continue;
+      if (aggregate.lastOrderedValue !== null && value < aggregate.lastOrderedValue)
+        invalid("Bounded quantile values are not in external ascending order");
+      const populationSize = aggregate.definition.orderedPopulationSize!;
+      const h = (populationSize - 1) * statistic.probability;
+      const lower = Math.floor(h);
+      const upper = Math.ceil(h);
+      if (aggregate.orderedCount === lower) aggregate.lowerOrderedValue = value;
+      if (aggregate.orderedCount === upper) aggregate.upperOrderedValue = value;
+      if (aggregate.orderedCount === Number.MAX_SAFE_INTEGER) invalid("Bounded quantile count exceeds the safe integer range");
+      aggregate.orderedCount += 1;
+      aggregate.lastOrderedValue = value;
+    }
+  }
+}
+
+function values(state: readonly Aggregate[]): readonly BoundedReplayValue[] {
+  return state.map((aggregate) => {
+    const statistic = aggregate.definition.statistic;
+    if (statistic.kind === "sum")
+      return { measureId: aggregate.definition.id, value: Object.is(aggregate.sum, -0) ? 0 : aggregate.sum, numerator: null, denominator: null };
+    if (statistic.kind === "weighted-mean")
+      return { measureId: aggregate.definition.id, value: aggregate.denominator > 0 ? checkedResult(aggregate.numerator / aggregate.denominator, "weighted mean") : null, numerator: aggregate.pairs > 0 ? aggregate.numerator : null, denominator: aggregate.pairs > 0 ? aggregate.denominator : null };
+    if (statistic.kind === "minimum" || statistic.kind === "maximum") {
+      const selected = statistic.kind === "minimum" ? aggregate.minimum : aggregate.maximum;
+      return { measureId: aggregate.definition.id, value: aggregate.pairs === 0 ? null : Object.is(selected, -0) ? 0 : selected, numerator: null, denominator: null };
+    }
+    if (statistic.kind === "distinct-count")
+      return { measureId: aggregate.definition.id, value: aggregate.distinctCount, numerator: null, denominator: null };
+    if (statistic.kind === "quantile") {
+      if (aggregate.orderedCount !== aggregate.definition.orderedPopulationSize)
+        invalid(`Bounded quantile received ${aggregate.orderedCount} finite values but orderedPopulationSize is ${aggregate.definition.orderedPopulationSize}`);
+      const h = (aggregate.orderedCount - 1) * statistic.probability;
+      const fraction = h - Math.floor(h);
+      const lower = aggregate.lowerOrderedValue!;
+      const upper = aggregate.upperOrderedValue!;
+      const interpolated = fraction === 0
+        ? lower
+        : checkedAdd(
+            checkedProduct(lower, 1 - fraction, "quantile interpolation"),
+            checkedProduct(upper, fraction, "quantile interpolation"),
+            "quantile interpolation",
+          );
+      return { measureId: aggregate.definition.id, value: interpolated, numerator: null, denominator: null };
+    }
+    if (statistic.kind !== "ratio") invalid("Unsupported bounded replay statistic");
+    const allowed = statistic.denominatorRule === "positive" ? aggregate.denominator > 0 : aggregate.denominator !== 0;
+    return {
+      measureId: aggregate.definition.id,
+      value: aggregate.pairs > 0 && allowed ? checkedResult(checkedResult(aggregate.numerator / aggregate.denominator, "ratio") * statistic.scale, "scaled ratio") : null,
+      numerator: aggregate.pairs > 0 ? aggregate.numerator : null,
+      denominator: aggregate.pairs > 0 ? aggregate.denominator : null,
+    };
+  });
+}
+
+function line(value: unknown, maximumBytes: number, limitName = "maximumInMemoryBytes"): Uint8Array {
+  const bytes = encoder.encode(`${JSON.stringify(value)}\n`);
+  if (bytes.byteLength > maximumBytes) invalid(`Bounded replay frame exceeds ${limitName}`);
+  return bytes;
+}
+
+function throwIfCancelled(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new ComplianceError("BAD_DIAGNOSTIC_RUN", "Bounded replay was cancelled", "$.boundedReplay");
+}
+
+/** Writes a replay whose retained SDK state is bounded by measures and one record frame. */
+export async function* writeBoundedAnalysisReplay(input: {
+  readonly runId: string;
+  readonly sourceArtifact: ComputedDiagnosticArtifactDigest;
+  readonly measures: readonly BoundedReplayMeasure[];
+  /** Optional closed calculation/selection context bound into the receipt identity. */
+  readonly calculationContext?: JsonValue;
+  readonly records: AsyncIterable<CustomizationExternalRecord<MeasureRecord>> | Iterable<CustomizationExternalRecord<MeasureRecord>>;
+  readonly limits: CustomizationResourceLimits;
+  readonly signal?: AbortSignal;
+}): AsyncGenerator<Uint8Array> {
+  const limits = validateLimits(input.limits);
+  const runId = input.runId;
+  const sourceArtifactHandle = input.sourceArtifact;
+  const records = input.records;
+  const signal = input.signal;
+  const suppliedContext = input.calculationContext;
+  if (!isDiagnosticToken(runId)) invalid("Bounded replay runId is invalid");
+  assertComputedDiagnosticArtifactDigest(sourceArtifactHandle);
+  const sourceArtifact = snapshotDiagnosticJson(sourceArtifactHandle);
+  const measures = parseBoundedReplayMeasures(input.measures, limits);
+  if (suppliedContext !== undefined) {
+    const issues = diagnosticJsonPreflight(suppliedContext, "input");
+    if (issues.length > 0) invalid(issues[0]!.message);
+  }
+  const calculationContext = suppliedContext === undefined
+    ? undefined
+    : snapshotDiagnosticJson(suppliedContext);
+  const header = snapshotDiagnosticJson({
+    type: "header",
+    contractVersion: BOUNDED_REPLAY_CONTRACT_VERSION,
+    runId,
+    sourceArtifact,
+    measures,
+    ...(calculationContext === undefined ? {} : { calculationContext }),
+  });
+  yield line(header, limits.maximumInMemoryBytes);
+  const state = aggregates(measures);
+  const digest = createSha256();
+  let recordCount = 0;
+  for await (const external of records) {
+    throwIfCancelled(signal);
+    if (recordCount >= limits.maximumInputRecords) invalid("Bounded replay exceeds maximumInputRecords");
+    recordCount += 1;
+    const preflight = diagnosticJsonPreflight(external, "input");
+    if (preflight.length > 0) invalid(preflight[0]!.message);
+    if (!isDiagnosticPlainRecord(external.value) || !isDiagnosticPlainRecord(external.value.measures))
+      invalid("Bounded replay records require a measures object");
+    const owned = snapshotDiagnosticJson({ type: "record", record: external });
+    const parsedRecord = recordFrameSchema.safeParse(owned);
+    if (!parsedRecord.success) invalid(`Bounded replay record is invalid: ${parsedRecord.error.issues[0]?.message ?? "schema mismatch"}`);
+    const bytes = line(parsedRecord.data, limits.maximumRecordBytes, "maximumRecordBytes");
+    digest.update(bytes);
+    acceptRecord(state, parsedRecord.data.record.value);
+    yield bytes;
+  }
+  const calculatedValues = values(state);
+  const recordDigest = digest.digest();
+  const identityValue = {
+    contractVersion: BOUNDED_REPLAY_CONTRACT_VERSION,
+    runId,
+    sourceArtifact,
+    measures,
+    ...(calculationContext === undefined ? {} : { calculationContext }),
+    recordCount,
+    recordDigest,
+    values: calculatedValues,
+  };
+  const trailer = snapshotDiagnosticJson({
+    type: "trailer",
+    recordCount,
+    recordDigest,
+    calculationIdentity: `fnv1a64-jcs-v1:${fnv1a64(canonicalJson(identityValue))}`,
+    values: calculatedValues,
+  });
+  yield line(trailer, limits.maximumInMemoryBytes);
+}
+
+async function* decodedLines(
+  chunks: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
+  maximumBytes: number,
+): AsyncGenerator<{ readonly text: string; readonly bytes: Uint8Array }> {
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let pending = "";
+  for await (const chunk of chunks) {
+    if (!(chunk instanceof Uint8Array) || chunk.byteLength > maximumBytes) invalid("Invalid or oversized bounded replay chunk");
+    pending += decoder.decode(chunk, { stream: true });
+    if (encoder.encode(pending).byteLength > maximumBytes) invalid("Bounded replay line exceeds maximumInMemoryBytes");
+    let boundary;
+    while ((boundary = pending.indexOf("\n")) >= 0) {
+      const text = pending.slice(0, boundary);
+      pending = pending.slice(boundary + 1);
+      yield { text, bytes: encoder.encode(`${text}\n`) };
+    }
+  }
+  pending += decoder.decode();
+  if (pending !== "") invalid("Bounded replay ends with an incomplete frame");
+}
+
+/** Independently recomputes every bounded result and identity while reading one frame at a time. */
+export async function verifyBoundedAnalysisReplay(input: {
+  readonly chunks: AsyncIterable<Uint8Array> | Iterable<Uint8Array>;
+  readonly limits: CustomizationResourceLimits;
+  /** Authentic handle recomputed from the source bytes being verified. */
+  readonly expectedSourceArtifact: ComputedDiagnosticArtifactDigest;
+  readonly signal?: AbortSignal;
+}): Promise<VerifiedBoundedReplayReceipt> {
+  const limits = validateLimits(input.limits);
+  const chunks = input.chunks;
+  const signal = input.signal;
+  const expectedSourceArtifactHandle = input.expectedSourceArtifact;
+  assertComputedDiagnosticArtifactDigest(expectedSourceArtifactHandle);
+  const expectedSourceArtifact = snapshotDiagnosticJson(expectedSourceArtifactHandle);
+  let header: z.infer<typeof headerSchema> | undefined;
+  let trailer: z.infer<typeof trailerSchema> | undefined;
+  let state: Aggregate[] = [];
+  let recordCount = 0;
+  const digest = createSha256();
+  for await (const frame of decodedLines(chunks, limits.maximumInMemoryBytes)) {
+    throwIfCancelled(signal);
+    let parsed: unknown;
+    try { parsed = JSON.parse(frame.text); } catch { invalid("Bounded replay frame is not valid JSON"); }
+    const preflight = diagnosticJsonPreflight(parsed, "input");
+    if (preflight.length > 0 || !isDiagnosticPlainRecord(parsed)) invalid("Bounded replay frame is not plain JSON data");
+    if (parsed.type === "header") {
+      if (header !== undefined || recordCount > 0 || trailer !== undefined) invalid("Bounded replay header is out of order");
+      const result = headerSchema.safeParse(parsed);
+      if (!result.success) invalid(`Bounded replay header is invalid: ${result.error.issues[0]?.message ?? "schema mismatch"}`);
+      const measures = parseBoundedReplayMeasures(result.data.measures, limits);
+      header = snapshotDiagnosticJson(result.data);
+      state = aggregates(measures);
+      if (canonicalJson(header.sourceArtifact) !== canonicalJson(expectedSourceArtifact)) invalid("Bounded replay source artifact differs from the expected immutable source");
+    } else if (parsed.type === "record") {
+      if (header === undefined || trailer !== undefined) invalid("Bounded replay record is out of order");
+      if (frame.bytes.byteLength > limits.maximumRecordBytes) invalid("Bounded replay record exceeds maximumRecordBytes");
+      const result = recordFrameSchema.safeParse(parsed);
+      if (!result.success) invalid(`Bounded replay record is invalid: ${result.error.issues[0]?.message ?? "schema mismatch"}`);
+      if (recordCount >= limits.maximumInputRecords) invalid("Bounded replay exceeds maximumInputRecords");
+      recordCount += 1;
+      digest.update(frame.bytes);
+      acceptRecord(state, result.data.record.value);
+    } else if (parsed.type === "trailer") {
+      if (header === undefined || trailer !== undefined) invalid("Bounded replay trailer is out of order");
+      const result = trailerSchema.safeParse(parsed);
+      if (!result.success) invalid(`Bounded replay trailer is invalid: ${result.error.issues[0]?.message ?? "schema mismatch"}`);
+      trailer = snapshotDiagnosticJson(result.data);
+    } else invalid("Unknown bounded replay frame type");
+  }
+  if (header === undefined || trailer === undefined) invalid("Bounded replay is truncated");
+  const calculatedValues = values(state);
+  const recordDigest = digest.digest();
+  const identityValue = {
+    contractVersion: BOUNDED_REPLAY_CONTRACT_VERSION,
+    runId: header.runId,
+    sourceArtifact: header.sourceArtifact,
+    measures: header.measures,
+    ...(header.calculationContext === undefined
+      ? {}
+      : { calculationContext: header.calculationContext }),
+    recordCount,
+    recordDigest,
+    values: calculatedValues,
+  };
+  const calculationIdentity = `fnv1a64-jcs-v1:${fnv1a64(canonicalJson(identityValue))}`;
+  if (trailer.recordCount !== recordCount || trailer.recordDigest !== recordDigest || trailer.calculationIdentity !== calculationIdentity || canonicalJson(trailer.values) !== canonicalJson(calculatedValues))
+    invalid("Bounded replay verification differs from its recorded trailer");
+  const receipt = snapshotDiagnosticJson({
+    contractVersion: BOUNDED_REPLAY_CONTRACT_VERSION,
+    runId: header.runId,
+    sourceArtifact: header.sourceArtifact,
+    ...(header.calculationContext === undefined
+      ? {}
+      : { calculationContext: header.calculationContext }),
+    recordCount,
+    recordDigest,
+    calculationIdentity,
+    values: calculatedValues,
+  }) as VerifiedBoundedReplayReceipt;
+  verifiedBoundedReplayReceipts.add(receipt);
+  return receipt;
+}