@actuarial-ts/compliance 0.6.0 → 0.7.0

package/src/diagnosticCompactRun.ts

@@ -0,0 +1,462 @@
+import {
+  CORE_PACKAGE_VERSION,
+  canonicalFnv1a64,
+  compareDiagnosticIdentityDocuments,
+  createDiagnosticIdentityArray,
+  createDiagnosticIdentityObject,
+  createDiagnosticIdentityValue,
+  fingerprintDiagnosticIdentity,
+  getCompactMetricDiagnosticsResultIdentityDocument,
+  getCompactPreparedDiagnosticDataFingerprint,
+  normalizeDiagnosticsFilterIdentity,
+  runMetricDiagnosticsCompact,
+  type DiagnosticIdentityDocument,
+} from "@actuarial-ts/core";
+import {
+  DATA_PACKAGE_VERSION,
+  assertCompletedCompactMetricDiagnosticsRun,
+  getCompactDiagnosticReviewReceiptFingerprint,
+  getCompactDiagnosticReviewReceiptIdentityDocument,
+  reviewPreparedDiagnosticDataCompact,
+  type CompletedCompactMetricDiagnosticsRun,
+} from "@actuarial-ts/data";
+import {
+  assertComputedDiagnosticArtifactDigest,
+  type ComputedDiagnosticArtifactDigest,
+} from "./diagnosticArtifactStream.js";
+import type {
+  DiagnosticArtifactDigest,
+  DiagnosticPreparationLineage,
+  DiagnosticRunIdentity,
+  DiagnosticRunProvenance,
+} from "./diagnosticRun.js";
+import {
+  plain,
+  snapshotLineage,
+  token,
+  validateArtifactGraph,
+} from "./diagnosticRunEvidence.js";
+import { ComplianceError } from "./errors.js";
+import { COMPLIANCE_PACKAGE_VERSION } from "./version.js";
+
+/** Computed digests must be authentic completed byte-stream receipts, not JSON copies. */
+export type CompactDiagnosticArtifactEvidence =
+  | ComputedDiagnosticArtifactDigest
+  | Extract<DiagnosticArtifactDigest, { assurance: "caller-declared" }>;
+
+export interface CreateCompactDiagnosticRunIdentityInput {
+  readonly completedRun: CompletedCompactMetricDiagnosticsRun;
+  readonly inputArtifacts: readonly CompactDiagnosticArtifactEvidence[];
+  readonly preparationArtifacts: readonly CompactDiagnosticArtifactEvidence[];
+  readonly preparationLineage: readonly DiagnosticPreparationLineage[];
+}
+
+declare const verifiedCompactDiagnosticRunProvenanceBrand: unique symbol;
+/**
+ * Verified compact evidence, not a legacy provenance DTO or BundleDoc.
+ * Documents emit the complete legacy normalized manifest/result identity bytes.
+ * They retain immutable owners, not expanded identity arrays or source bytes.
+ * The provenance brand, not a structural document, establishes verification.
+ */
+export interface VerifiedCompactDiagnosticRunProvenance
+  extends DiagnosticRunIdentity {
+  readonly [verifiedCompactDiagnosticRunProvenanceBrand]: true;
+  readonly definition: DiagnosticRunProvenance["definition"];
+  readonly inputArtifacts: readonly DiagnosticArtifactDigest[];
+  readonly preparationArtifacts: readonly DiagnosticArtifactDigest[];
+  readonly preparationLineage: readonly DiagnosticPreparationLineage[];
+  readonly preparationFingerprint: string;
+  readonly reviewFingerprint: string;
+  readonly manifestIdentityDocument: DiagnosticIdentityDocument;
+  readonly resultIdentityDocument: DiagnosticIdentityDocument;
+}
+
+const verified = new WeakMap<object, CompletedCompactMetricDiagnosticsRun>();
+
+function bad(message: string, path: string): never {
+  throw new ComplianceError("BAD_DIAGNOSTIC_RUN", message, path);
+}
+
+/** Snapshot boundary metadata without invoking getters or caller array methods. */
+function record(
+  value: unknown,
+  allowed: readonly string[],
+  path: string,
+): Record<string, unknown> {
+  if (!plain(value)) bad("Expected a plain metadata object", path);
+  const copy: Record<string, unknown> = Object.create(null);
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string" || !allowed.includes(key))
+      bad("Unknown metadata field", `${path}.${String(key)}`);
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+      bad(
+        "Metadata fields must be enumerable data properties",
+        `${path}.${key}`,
+      );
+    copy[key] = descriptor.value;
+  }
+  return copy;
+}
+
+function array(value: unknown, path: string): unknown[] {
+  if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype)
+    bad("Expected a plain metadata array", path);
+  const length = Object.getOwnPropertyDescriptor(value, "length")?.value;
+  if (!Number.isSafeInteger(length) || length < 0)
+    bad("Invalid array length", path);
+  for (const key of Reflect.ownKeys(value)) {
+    if (key === "length") continue;
+    if (
+      typeof key !== "string" ||
+      !/^(0|[1-9][0-9]*)$/.test(key) ||
+      Number(key) >= length
+    )
+      bad("Unexpected array property", `${path}.${String(key)}`);
+  }
+  const copy: unknown[] = [];
+  for (let index = 0; index < length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+      bad("Array items must be present data properties", `${path}[${index}]`);
+    copy.push(descriptor.value);
+  }
+  return copy;
+}
+
+function artifacts(
+  value: unknown,
+  scope: "input" | "preparation",
+  path: string,
+): readonly DiagnosticArtifactDigest[] {
+  const seen = new Set<string>();
+  const result = array(value, path).map(
+    (raw, index): DiagnosticArtifactDigest => {
+      const itemPath = `${path}[${index}]`;
+      const item = record(
+        raw,
+        ["id", "scope", "assurance", "algorithm", "value", "byteLength"],
+        itemPath,
+      );
+      if (typeof item.id !== "string")
+        bad("Artifact id must be a string", `${itemPath}.id`);
+      token(item.id, `${itemPath}.id`);
+      if (seen.has(item.id))
+        bad("Artifact IDs must be unique", `${itemPath}.id`);
+      seen.add(item.id);
+      if (item.scope !== scope)
+        bad(`Artifact must have ${scope} scope`, `${itemPath}.scope`);
+      if (item.assurance === "sdk-computed") {
+        assertComputedDiagnosticArtifactDigest(raw);
+        return raw;
+      }
+      if (item.assurance !== "caller-declared")
+        bad("Unknown artifact assurance", `${itemPath}.assurance`);
+      if (Object.hasOwn(item, "byteLength"))
+        bad(
+          "Caller-declared evidence cannot claim a computed byte length",
+          `${itemPath}.byteLength`,
+        );
+      if (typeof item.algorithm !== "string" || typeof item.value !== "string")
+        bad("Declared algorithm and value must be strings", itemPath);
+      token(item.algorithm, `${itemPath}.algorithm`);
+      token(item.value, `${itemPath}.value`);
+      return Object.freeze({
+        id: item.id,
+        scope,
+        assurance: "caller-declared",
+        algorithm: item.algorithm,
+        value: item.value,
+      });
+    },
+  );
+  return Object.freeze(
+    result.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
+  );
+}
+
+function lineage(value: unknown): readonly DiagnosticPreparationLineage[] {
+  const copied = array(value, "$.preparationLineage").map((raw, index) => {
+    const path = `$.preparationLineage[${index}]`;
+    const item = record(
+      raw,
+      ["outputArtifactId", "inputArtifactIds", "transformationArtifactIds"],
+      path,
+    );
+    return {
+      outputArtifactId: item.outputArtifactId,
+      inputArtifactIds: array(
+        item.inputArtifactIds,
+        `${path}.inputArtifactIds`,
+      ),
+      transformationArtifactIds: array(
+        item.transformationArtifactIds,
+        `${path}.transformationArtifactIds`,
+      ),
+    };
+  });
+  return Object.freeze(
+    snapshotLineage(copied).map((edge) =>
+      Object.freeze({
+        outputArtifactId: edge.outputArtifactId,
+        inputArtifactIds: Object.freeze([...edge.inputArtifactIds]),
+        transformationArtifactIds: Object.freeze([
+          ...edge.transformationArtifactIds,
+        ]),
+      }),
+    ),
+  );
+}
+
+function requireEqual(
+  actual: DiagnosticIdentityDocument,
+  expected: DiagnosticIdentityDocument,
+  path: string,
+): void {
+  const comparison = compareDiagnosticIdentityDocuments(actual, expected);
+  if (!comparison.equal)
+    throw new ComplianceError(
+      "DIAGNOSTIC_MISMATCH",
+      `Deterministic replay differs at canonical code-unit offset ${comparison.codeUnitOffset}`,
+      path,
+    );
+}
+
+/** Replay before issuing authority; hashes never replace complete identity comparison. */
+function rerunAndVerify(run: CompletedCompactMetricDiagnosticsRun): void {
+  const review = reviewPreparedDiagnosticDataCompact({
+    prepared: run.prepared,
+    evidence: run.review.evidence,
+  });
+  requireEqual(
+    getCompactDiagnosticReviewReceiptIdentityDocument(review),
+    getCompactDiagnosticReviewReceiptIdentityDocument(run.review),
+    "$.review",
+  );
+  const rerun = runMetricDiagnosticsCompact({
+    prepared: run.prepared,
+    groupMap: run.groupMap,
+    groupDimensions: run.groupDimensions,
+  });
+  requireEqual(
+    getCompactMetricDiagnosticsResultIdentityDocument(rerun),
+    getCompactMetricDiagnosticsResultIdentityDocument(run.result),
+    "$.result",
+  );
+  const counts = review.evaluations.summary;
+  const effectiveCounts = {
+    pass: counts.pass,
+    warning: counts.warning,
+    fail: counts.fail,
+    "not-evaluated": counts.notEvaluated,
+  };
+  const statuses = ["pass", "warning", "fail", "not-evaluated"] as const;
+  const reviewBlocked =
+    review.report.checks.some(
+      (check) => !run.gate.allowedReviewStatuses.includes(check.status),
+    ) ||
+    statuses.some(
+      (status) =>
+        effectiveCounts[status] > 0 &&
+        !run.gate.allowedReviewStatuses.includes(status),
+    );
+  const metricBlocked = rerun.findings.some(
+    (finding) =>
+      finding.category !== "structural" &&
+      !run.gate.allowedMetricFindingSeverities.includes(finding.severity),
+  );
+  if (
+    reviewBlocked ||
+    metricBlocked ||
+    run.gate.reviewGate !== "passed" ||
+    run.gate.metricGate !== "passed"
+  )
+    throw new ComplianceError(
+      "DIAGNOSTIC_MISMATCH",
+      "Diagnostic execution gates do not recompute as passed",
+      "$.gate",
+    );
+}
+
+function manifestDocument(
+  run: CompletedCompactMetricDiagnosticsRun,
+  inputArtifacts: readonly DiagnosticArtifactDigest[],
+  preparationArtifacts: readonly DiagnosticArtifactDigest[],
+  preparationLineage: readonly DiagnosticPreparationLineage[],
+  preparationFingerprint: string,
+  reviewFingerprint: string,
+): DiagnosticIdentityDocument {
+  const prepared = run.prepared;
+  const expectedCells = createDiagnosticIdentityArray(
+    prepared.expectedCells.length,
+    (index) => {
+      const cell = prepared.expectedCells[index]!;
+      return createDiagnosticIdentityObject({
+        sourceGroup: createDiagnosticIdentityValue(cell.sourceGroup),
+        origin: createDiagnosticIdentityValue(cell.origin),
+        valuation: createDiagnosticIdentityValue(cell.valuation),
+        source: createDiagnosticIdentityValue(cell.source ?? null),
+      });
+    },
+  );
+  return createDiagnosticIdentityObject({
+    definitionIntegrity: createDiagnosticIdentityValue(
+      prepared.definition.definitionIntegrity,
+    ),
+    preparationFingerprint: createDiagnosticIdentityValue(
+      preparationFingerprint,
+    ),
+    runPresetId: createDiagnosticIdentityValue(run.runPresetId),
+    datasetArtifactId: createDiagnosticIdentityValue(run.datasetArtifactId),
+    inputArtifacts: createDiagnosticIdentityValue(inputArtifacts),
+    preparationArtifacts: createDiagnosticIdentityValue(preparationArtifacts),
+    preparationLineage: createDiagnosticIdentityValue(preparationLineage),
+    inputAudit: createDiagnosticIdentityValue(prepared.inputAudit),
+    filter: createDiagnosticIdentityValue(
+      normalizeDiagnosticsFilterIdentity(prepared.filter),
+    ),
+    groupMap: createDiagnosticIdentityValue(run.groupMap),
+    groupDimensions: createDiagnosticIdentityValue(run.groupDimensions),
+    completePeriodCutoffs: createDiagnosticIdentityValue(
+      prepared.completePeriodCutoffs,
+    ),
+    expectedCellGridFingerprint: createDiagnosticIdentityValue(
+      prepared.expectedCellsProvided
+        ? fingerprintDiagnosticIdentity(expectedCells, {
+            kind: "diagnostic-expected-cell-grid",
+            property: "expectedCells",
+          })
+        : null,
+    ),
+    executionPolicy: createDiagnosticIdentityObject({
+      gate: createDiagnosticIdentityValue(run.gate),
+      review: createDiagnosticIdentityObject({
+        body: getCompactDiagnosticReviewReceiptIdentityDocument(run.review),
+        reportFingerprint: createDiagnosticIdentityValue(reviewFingerprint),
+      }),
+    }),
+    engine: createDiagnosticIdentityValue(
+      Object.freeze({
+        packages: Object.freeze({
+          core: CORE_PACKAGE_VERSION,
+          data: DATA_PACKAGE_VERSION,
+          compliance: COMPLIANCE_PACKAGE_VERSION,
+        }),
+        algorithmVersion: "diagnostics-1",
+      }),
+    ),
+  });
+}
+
+/**
+ * Verify an authentic compact completed run and bind completed artifact digests.
+ * Synchronous: source bytes were consumed by digestDiagnosticArtifactChunks already.
+ * This deliberately replays review/math and compares every identity code unit.
+ */
+export function createCompactDiagnosticRunIdentity(
+  input: CreateCompactDiagnosticRunIdentityInput,
+): VerifiedCompactDiagnosticRunProvenance {
+  const snapshot = record(
+    input,
+    [
+      "completedRun",
+      "inputArtifacts",
+      "preparationArtifacts",
+      "preparationLineage",
+    ],
+    "$",
+  );
+  const run = snapshot.completedRun;
+  try {
+    assertCompletedCompactMetricDiagnosticsRun(run);
+  } catch {
+    bad(
+      "completedRun must be an authentic completed compact diagnostic run",
+      "$.completedRun",
+    );
+  }
+  const inputArtifacts = artifacts(
+    snapshot.inputArtifacts,
+    "input",
+    "$.inputArtifacts",
+  );
+  const preparationArtifacts = artifacts(
+    snapshot.preparationArtifacts,
+    "preparation",
+    "$.preparationArtifacts",
+  );
+  const preparationLineage = lineage(snapshot.preparationLineage);
+  validateArtifactGraph(
+    run,
+    inputArtifacts,
+    preparationArtifacts,
+    preparationLineage,
+  );
+  rerunAndVerify(run);
+  const preparationFingerprint = getCompactPreparedDiagnosticDataFingerprint(
+    run.prepared,
+  );
+  const reviewFingerprint = getCompactDiagnosticReviewReceiptFingerprint(
+    run.review,
+  );
+  const manifestIdentityDocument = manifestDocument(
+    run,
+    inputArtifacts,
+    preparationArtifacts,
+    preparationLineage,
+    preparationFingerprint,
+    reviewFingerprint,
+  );
+  const resultIdentityDocument =
+    getCompactMetricDiagnosticsResultIdentityDocument(run.result);
+  const runFingerprint = fingerprintDiagnosticIdentity(
+    manifestIdentityDocument,
+    { kind: "diagnostic-run", property: "manifest" },
+  );
+  const resultFingerprint = fingerprintDiagnosticIdentity(
+    resultIdentityDocument,
+    { kind: "diagnostic-result", property: "result" },
+  );
+  const runResultFingerprint = `fnv1a64-jcs-v1:${canonicalFnv1a64({ identityVersion: 1, kind: "diagnostic-run-result", runFingerprint, resultFingerprint })}`;
+  const definition = run.prepared.definition;
+  const provenance = Object.freeze({
+    definition: Object.freeze({
+      definition: definition.definition,
+      identities: Object.freeze({
+        algorithm: "fnv1a64-jcs-v1" as const,
+        formulaById: Object.freeze({ ...definition.formulaFingerprints }),
+        calculationByInstanceId: Object.freeze({
+          ...definition.calculationFingerprints,
+        }),
+        definition: definition.definitionIntegrity,
+      }),
+    }),
+    inputArtifacts,
+    preparationArtifacts,
+    preparationLineage,
+    preparationFingerprint,
+    reviewFingerprint,
+    manifestIdentityDocument,
+    resultIdentityDocument,
+    runFingerprint,
+    resultFingerprint,
+    runResultFingerprint,
+  }) as VerifiedCompactDiagnosticRunProvenance;
+  verified.set(provenance, run);
+  return provenance;
+}
+
+export function assertVerifiedCompactDiagnosticRunProvenance(
+  value: unknown,
+): asserts value is VerifiedCompactDiagnosticRunProvenance {
+  if (value === null || typeof value !== "object" || !verified.has(value))
+    bad("Value is not authentic verified compact diagnostic provenance", "$");
+}
+
+/** Internal transport plumbing; deliberately not exported from the package index. */
+export function getCompactDiagnosticRunOwner(
+  provenance: VerifiedCompactDiagnosticRunProvenance,
+): CompletedCompactMetricDiagnosticsRun {
+  assertVerifiedCompactDiagnosticRunProvenance(provenance);
+  return verified.get(provenance)!;
+}

package/src/diagnosticReplayFrames.ts

@@ -0,0 +1,99 @@
+import { ComplianceError } from "./errors.js";
+import { diagnosticByteView } from "./diagnosticByteView.js";
+import { consumeDiagnosticByteSource } from "./diagnosticByteSource.js";
+
+// Transport granularity only: not a limit on total evidence or dataset size.
+export const MAX_REPLAY_FRAME_BYTES = 131_072;
+export const MAX_REPLAY_READ_BYTES = 131_072;
+export const REPLAY_TEXT_UNITS = 16_384;
+export type ReplayAtom = string | number | boolean | null;
+export type ReplayFrame = readonly ReplayAtom[];
+function invalid(message: string): never {
+  throw new ComplianceError("BAD_DIAGNOSTIC_RUN", message, "$.replayFrames");
+}
+function snapshotFrame(value: unknown): ReplayFrame {
+  if (!Array.isArray(value)) invalid("Replay frame must be an array");
+  const length = Object.getOwnPropertyDescriptor(value, "length")?.value;
+  if (!Number.isInteger(length) || length < 1 || length > 16)
+    invalid("Replay frame must be a nonempty flat array with at most 16 items");
+  const owned: ReplayAtom[] = [];
+  for (let index = 0; index < length; index++) {
+    const field = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!field || !("value" in field))
+      invalid("Replay frames must contain indexed data properties");
+    const item: unknown = field.value;
+    if (item === null || typeof item === "boolean") {
+      owned.push(item);
+      continue;
+    }
+    if (typeof item === "number" && Number.isFinite(item)) {
+      owned.push(item);
+      continue;
+    }
+    // Enough for a base64-encoded 64 KiB artifact chunk. Higher-level protocol
+    // validates each event's arity, sequencing, and narrower field limits.
+    if (typeof item === "string" && item.length <= 87_384) {
+      owned.push(item);
+      continue;
+    }
+    invalid("Replay frames contain only bounded JSON primitives");
+  }
+  return Object.freeze(owned);
+}
+
+/** Private transport codec; construction does not grant diagnostic authority. */
+export async function* encodeReplayFrames(
+  frames: AsyncIterable<ReplayFrame> | Iterable<ReplayFrame>,
+): AsyncGenerator<Uint8Array> {
+  const encoder = new TextEncoder();
+  for await (const frame of frames) {
+    const owned = snapshotFrame(frame);
+    const atoms: string[] = [];
+    let bytes = 3;
+    for (const item of owned) {
+      const text = JSON.stringify(item);
+      bytes += encoder.encode(text).byteLength + (atoms.length ? 1 : 0);
+      if (bytes > MAX_REPLAY_FRAME_BYTES) invalid("Replay frame exceeds its byte limit");
+      atoms.push(text);
+    }
+    yield encoder.encode(`[${atoms.join(",")}]\n`);
+  }
+}
+
+/** Parse bounded flat frames, never a complete candidate audit/identity. */
+export async function* decodeReplayFrames(
+  chunks: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
+): AsyncGenerator<ReplayFrame> {
+  const line = new Uint8Array(MAX_REPLAY_FRAME_BYTES);
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let used = 0;
+  try {
+    for await (const chunk of consumeDiagnosticByteSource(chunks)) {
+      const view = diagnosticByteView(chunk);
+      if (view.byteLength > MAX_REPLAY_READ_BYTES)
+        invalid("Replay read chunk exceeds its transport limit; split input reads");
+      // Snapshot before yielding any frame: reused buffers cannot alter later
+      // frames in the same delivered chunk. This copy is always bounded.
+      const owned = new Uint8Array(view);
+      for (const byte of owned) {
+        if (byte === 10) {
+          if (used === 0) invalid("Empty replay frame");
+          let parsed: unknown;
+          try {
+            parsed = JSON.parse(decoder.decode(line.subarray(0, used)));
+          } catch {
+            invalid("Replay frame is not valid UTF-8 JSON");
+          }
+          used = 0;
+          yield snapshotFrame(parsed);
+        } else {
+          if (used >= MAX_REPLAY_FRAME_BYTES - 1) invalid("Replay frame exceeds its byte limit");
+          line[used++] = byte;
+        }
+      }
+    }
+    if (used !== 0) invalid("Replay stream ended inside a frame");
+  } finally {
+    line.fill(0);
+  }
+}

package/src/diagnosticReplayProtocol.ts

@@ -0,0 +1,99 @@
+import { isDiagnosticPlainRecord, isDiagnosticToken } from "@actuarial-ts/core";
+import { ComplianceError } from "./errors.js";
+import { MAX_REPLAY_FRAME_BYTES, type ReplayFrame } from "./diagnosticReplayFrames.js";
+
+export const REPLAY_FORMAT = "diagnostic-replay";
+export const REPLAY_VERSION = 1;
+export const ARTIFACT_CHUNK_BYTES = 65_536;
+
+export function badReplay(message: string): never {
+  throw new ComplianceError("BAD_DIAGNOSTIC_RUN", message, "$.replay");
+}
+export function mismatch(message: string): never {
+  throw new ComplianceError("DIAGNOSTIC_MISMATCH", message, "$.replay");
+}
+
+/** Snapshot host metadata once, without invoking accessors or caller methods. */
+export function replayRecord(value: unknown, keys: readonly string[]): Record<string, unknown> {
+  if (!isDiagnosticPlainRecord(value)) badReplay("Expected a plain replay metadata object");
+  const result: Record<string, unknown> = Object.create(null);
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string" || !keys.includes(key)) badReplay("Unknown replay metadata field");
+    const field = Object.getOwnPropertyDescriptor(value, key);
+    if (!field || !("value" in field) || !field.enumerable)
+      badReplay("Replay metadata must contain enumerable data properties");
+    result[key] = field.value;
+  }
+  return result;
+}
+export function replayArray(value: unknown): unknown[] {
+  if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype)
+    badReplay("Expected a plain replay metadata array");
+  const length: unknown = Object.getOwnPropertyDescriptor(value, "length")?.value;
+  if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0)
+    badReplay("Invalid replay metadata array length");
+  for (const key of Reflect.ownKeys(value))
+    if (
+      key !== "length" &&
+      (typeof key !== "string" || !/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= length)
+    )
+      badReplay("Unexpected replay array property");
+  const result: unknown[] = [];
+  for (let index = 0; index < length; index++) {
+    const field = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!field || !("value" in field) || !field.enumerable)
+      badReplay("Replay array has a hole or accessor");
+    result.push(field.value);
+  }
+  return result;
+}
+export function replayToken(value: unknown): string {
+  if (!isDiagnosticToken(value)) badReplay("Expected a nonempty replay token with valid Unicode");
+  return value;
+}
+export function replayLimit(value: unknown, label: string): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
+    badReplay(`${label} must be a positive safe integer`);
+  return value;
+}
+
+const signalAborted = Object.getOwnPropertyDescriptor(AbortSignal.prototype, "aborted")!.get!;
+const throwIfAborted = AbortSignal.prototype.throwIfAborted;
+export function replayCancellation(signal: unknown): () => void {
+  if (signal === undefined) return () => {};
+  try {
+    signalAborted.call(signal);
+  } catch {
+    badReplay("Replay signal must be an AbortSignal");
+  }
+  return () => throwIfAborted.call(signal);
+}
+
+/** Exactly the writer's bounded canonical flat-frame bytes, including newline. */
+export function replayFrameBytes(frame: ReplayFrame): Uint8Array {
+  const bytes = new TextEncoder().encode(`${JSON.stringify(frame)}\n`);
+  if (bytes.byteLength > MAX_REPLAY_FRAME_BYTES) badReplay("Replay frame exceeds its byte limit");
+  return bytes;
+}
+
+export function encodeArtifactChunk(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+export function decodeArtifactChunk(value: unknown): Uint8Array {
+  if (
+    typeof value !== "string" ||
+    !value.length ||
+    value.length > 87_384 ||
+    value.length % 4 ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)
+  )
+    badReplay("Invalid bounded artifact base64 chunk");
+  const binary = atob(value);
+  if (binary.length > ARTIFACT_CHUNK_BYTES || btoa(binary) !== value)
+    badReplay("Artifact base64 must use canonical padding bits and bounded chunks");
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}