@actuarial-ts/compliance 0.6.0 → 0.7.0

package/src/diagnosticArtifactStream.ts

@@ -0,0 +1,148 @@
+import {
+  diagnosticJsonPreflight,
+  isDiagnosticPlainRecord,
+  isDiagnosticToken,
+} from "@actuarial-ts/core";
+import { ComplianceError } from "./errors.js";
+import type { DiagnosticArtifactDigest } from "./diagnosticRun.js";
+import { createSha256 } from "./sha256Stream.js";
+import { diagnosticByteView } from "./diagnosticByteView.js";
+import { consumeDiagnosticByteSource } from "./diagnosticByteSource.js";
+
+export interface DiagnosticArtifactStreamMetadata {
+  readonly id: string;
+  readonly scope: "input" | "preparation";
+  /** Optional completeness check; no digest handle is issued on truncation. */
+  readonly expectedByteLength?: number;
+  /** Caller-selected resource ceiling, at most Number.MAX_SAFE_INTEGER. */
+  readonly maximumByteLength?: number;
+}
+declare const computedArtifactDigestBrand: unique symbol;
+export type ComputedDiagnosticArtifactDigest = Extract<
+  DiagnosticArtifactDigest,
+  { assurance: "sdk-computed" }
+> & { readonly [computedArtifactDigestBrand]: true };
+
+const computed = new WeakSet<object>();
+const signalAborted = Object.getOwnPropertyDescriptor(AbortSignal.prototype, "aborted")!.get!;
+const throwIfAborted = AbortSignal.prototype.throwIfAborted;
+const COPY_SIZE = 65_536;
+
+function invalid(message: string, path = "$"): never {
+  throw new ComplianceError("BAD_DIAGNOSTIC_RUN", message, path);
+}
+
+function ownedMetadata(value: DiagnosticArtifactStreamMetadata) {
+  // Read descriptors once. A Proxy must not pass validation with one property
+  // value and supply a different value when the final digest is assembled.
+  if (!isDiagnosticPlainRecord(value)) invalid("Artifact metadata must be a plain object");
+  const snapshot = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string") invalid("Artifact metadata cannot have symbol keys");
+    const field = Object.getOwnPropertyDescriptor(value, key);
+    if (!field || !("value" in field) || !field.enumerable)
+      invalid("Artifact metadata must contain enumerable data properties", `$.${key}`);
+    snapshot[key] = field.value;
+  }
+  value = snapshot as unknown as DiagnosticArtifactStreamMetadata;
+  const issues = diagnosticJsonPreflight(value, "input");
+  if (issues.length) invalid(issues[0]!.message, issues[0]!.path);
+  if (!isDiagnosticPlainRecord(value)) invalid("Artifact metadata must be a plain object");
+  for (const key of Object.keys(value))
+    if (!["id", "scope", "expectedByteLength", "maximumByteLength"].includes(key))
+      invalid("Unknown artifact metadata key", `$.${key}`);
+  if (!isDiagnosticToken(value.id)) invalid("Artifact ID must be a valid token", "$.id");
+  if (value.scope !== "input" && value.scope !== "preparation")
+    invalid("Artifact scope must be input or preparation", "$.scope");
+  for (const key of ["expectedByteLength", "maximumByteLength"] as const)
+    if (value[key] !== undefined && (!Number.isSafeInteger(value[key]) || value[key]! < 0))
+      invalid("Byte length must be a nonnegative safe integer", `$.${key}`);
+  const maximumByteLength = value.maximumByteLength ?? Number.MAX_SAFE_INTEGER;
+  if (value.expectedByteLength !== undefined && value.expectedByteLength > maximumByteLength)
+    invalid("Expected byte length exceeds the resource ceiling", "$.expectedByteLength");
+  return {
+    id: value.id,
+    scope: value.scope,
+    expectedByteLength: value.expectedByteLength,
+    maximumByteLength,
+  };
+}
+
+function cancellation(options: { readonly signal?: AbortSignal }): () => void {
+  if (!isDiagnosticPlainRecord(options)) invalid("Artifact stream options must be a plain object");
+  for (const key of Reflect.ownKeys(options))
+    if (key !== "signal") invalid("Unknown artifact stream option");
+  const field = Object.getOwnPropertyDescriptor(options, "signal");
+  if (field && (!("value" in field) || !field.enumerable))
+    invalid("Artifact signal must be supplied as a data property");
+  const signal = field?.value;
+  if (signal === undefined) return () => {};
+  try {
+    signalAborted.call(signal);
+  } catch {
+    invalid("Artifact signal must be an AbortSignal");
+  }
+  // Capture the genuine signal and intrinsic method before any producer await.
+  return () => throwIfAborted.call(signal);
+}
+
+/**
+ * Hash the bytes actually received, retaining only a bounded chunk copy.
+ * The producer owns I/O. A completed handle means SDK-computed content digest,
+ * not source authenticity, a signature, or validation of an actuarial run.
+ * Shared buffers are refused; bytes are consumed before requesting the next
+ * chunk. A changing producer must be checked again against this digest on replay.
+ * Cancellation is cooperative between received chunks; the producer should use
+ * the same signal to cancel pending I/O. One synchronous chunk is not interrupted.
+ */
+export async function digestDiagnosticArtifactChunks(
+  metadata: DiagnosticArtifactStreamMetadata,
+  chunks: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
+  options: { readonly signal?: AbortSignal } = {},
+): Promise<ComputedDiagnosticArtifactDigest> {
+  const owned = ownedMetadata(metadata);
+  const checkCancellation = cancellation(options);
+  checkCancellation();
+  const hash = createSha256();
+  const copy = new Uint8Array(COPY_SIZE);
+  let byteLength = 0;
+  try {
+    for await (const chunk of consumeDiagnosticByteSource(chunks, checkCancellation)) {
+      checkCancellation();
+      const view = diagnosticByteView(chunk);
+      const size = view.byteLength;
+      if (!Number.isSafeInteger(byteLength + size) || byteLength + size > owned.maximumByteLength)
+        invalid("Artifact byte length exceeds the resource ceiling", "$.chunks");
+      if (owned.expectedByteLength !== undefined && byteLength + size > owned.expectedByteLength)
+        invalid("Artifact has more bytes than declared", "$.chunks");
+      for (let start = 0; start < size; start += COPY_SIZE) {
+        const length = Math.min(COPY_SIZE, size - start);
+        copy.set(new Uint8Array(view.buffer, view.byteOffset + start, length));
+        hash.update(copy.subarray(0, length));
+      }
+      byteLength += size;
+    }
+    checkCancellation();
+    if (owned.expectedByteLength !== undefined && byteLength !== owned.expectedByteLength)
+      invalid("Artifact ended before its declared byte length", "$.chunks");
+    const digest = Object.freeze({
+      id: owned.id,
+      scope: owned.scope,
+      assurance: "sdk-computed" as const,
+      algorithm: "sha256" as const,
+      value: hash.digest(),
+      byteLength,
+    }) as ComputedDiagnosticArtifactDigest;
+    computed.add(digest);
+    return digest;
+  } finally {
+    copy.fill(0);
+  }
+}
+
+export function assertComputedDiagnosticArtifactDigest(
+  value: unknown,
+): asserts value is ComputedDiagnosticArtifactDigest {
+  if (value === null || typeof value !== "object" || !computed.has(value))
+    invalid("Value is not an authentic SDK-computed streamed artifact digest");
+}

package/src/diagnosticByteSource.ts

@@ -0,0 +1,82 @@
+type DiagnosticByteSource = Iterable<Uint8Array> | AsyncIterable<Uint8Array>;
+
+function isObject(value: unknown): value is object {
+  return (
+    value !== null && (typeof value === "object" || typeof value === "function")
+  );
+}
+
+/**
+ * Own one producer iterator through completion, cancellation or read failure.
+ * Unlike a bare for-await loop, a rejected next() also closes the producer.
+ * A cleanup failure never replaces the error that caused cleanup. Hosts should
+ * pass the same cancellation signal to pending I/O; checks cannot interrupt it.
+ */
+export async function* consumeDiagnosticByteSource(
+  source: DiagnosticByteSource,
+  checkCancellation: () => void = () => {},
+): AsyncGenerator<Uint8Array> {
+  if (!isObject(source))
+    throw new TypeError("Diagnostic byte source must be iterable");
+  const iterable = source as Partial<
+    Iterable<Uint8Array> & AsyncIterable<Uint8Array>
+  >;
+  const asynchronous = iterable[Symbol.asyncIterator];
+  const method = asynchronous ?? iterable[Symbol.iterator];
+  if (typeof method !== "function")
+    throw new TypeError(
+      "Diagnostic byte source must provide an iterator method",
+    );
+  const iterator: unknown = Reflect.apply(method, source, []);
+  if (!isObject(iterator))
+    throw new TypeError("Diagnostic byte iterator must be an object");
+  const protocol = iterator as { next?: unknown; return?: unknown };
+  let completed = false;
+  let failed = false;
+  try {
+    // Capture next once, as the iterator protocol does; never use a producer's
+    // potentially overwritten Function.call property.
+    const next = protocol.next;
+    if (typeof next !== "function")
+      throw new TypeError("Diagnostic byte iterator must provide next()");
+    for (;;) {
+      checkCancellation();
+      const result: unknown = await Reflect.apply(next, iterator, []);
+      if (!isObject(result))
+        throw new TypeError(
+          "Diagnostic byte read must return an iterator result",
+        );
+      const item = result as IteratorResult<Uint8Array>;
+      completed = Boolean(item.done);
+      checkCancellation();
+      if (completed) return;
+      // An async generator also observes a rejected value from a synchronous
+      // iterator here, so that failure follows the same cleanup path.
+      yield item.value;
+    }
+  } catch (error) {
+    failed = true;
+    throw error;
+  } finally {
+    if (!completed) {
+      try {
+        // Read return only when closing, once, following normal iterator
+        // semantics. The generator's finally executes at most once.
+        const close = protocol.return;
+        if (close !== undefined && close !== null) {
+          if (typeof close !== "function")
+            throw new TypeError(
+              "Diagnostic byte iterator return must be a function",
+            );
+          const result: unknown = await Reflect.apply(close, iterator, []);
+          if (!isObject(result))
+            throw new TypeError(
+              "Diagnostic byte iterator return must return an iterator result",
+            );
+        }
+      } catch (cleanupError) {
+        if (!failed) throw cleanupError;
+      }
+    }
+  }
+}

package/src/diagnosticByteView.ts

@@ -0,0 +1,27 @@
+import { ComplianceError } from "./errors.js";
+
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const byteLength = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength")!.get!;
+const byteOffset = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteOffset")!.get!;
+const bufferOf = Object.getOwnPropertyDescriptor(typedArrayPrototype, "buffer")!.get!;
+const arrayBufferLength = Object.getOwnPropertyDescriptor(ArrayBuffer.prototype, "byteLength")!
+  .get!;
+const resizable = Object.getOwnPropertyDescriptor(ArrayBuffer.prototype, "resizable")?.get;
+
+/** Borrow a synchronous intrinsic-only view; callers copy before yielding. */
+export function diagnosticByteView(chunk: unknown): Uint8Array<ArrayBuffer> {
+  const fail = (message: string): never => {
+    throw new ComplianceError("BAD_DIAGNOSTIC_RUN", message, "$.chunks");
+  };
+  if (!(chunk instanceof Uint8Array) || !ArrayBuffer.isView(chunk))
+    fail("Artifact chunks must be Uint8Array values");
+  const buffer = bufferOf.call(chunk) as ArrayBuffer;
+  try {
+    arrayBufferLength.call(buffer);
+  } catch {
+    fail("Shared artifact buffers cannot provide a stable byte snapshot");
+  }
+  if (resizable?.call(buffer))
+    fail("Resizable artifact buffers cannot provide a stable byte snapshot");
+  return new Uint8Array(buffer, byteOffset.call(chunk), byteLength.call(chunk));
+}