@actuarial-ts/compliance 0.6.1 → 0.7.0

package/src/diagnosticRunEvidence.ts

@@ -0,0 +1,391 @@
+import type { CompactPreparedDiagnosticData } from "@actuarial-ts/core";
+import type { CompactDiagnosticReviewReceipt } from "@actuarial-ts/data";
+import type {
+  DiagnosticArtifactDigest,
+  DiagnosticPreparationLineage,
+} from "./diagnosticRun.js";
+import { ComplianceError } from "./errors.js";
+
+/** Shared content validation; callers separately authenticate their run owner. */
+export interface DiagnosticArtifactGraphContent {
+  readonly prepared: Pick<
+    CompactPreparedDiagnosticData,
+    "inputAudit" | "definition"
+  >;
+  readonly review: Pick<CompactDiagnosticReviewReceipt, "evidence">;
+  readonly datasetArtifactId: string | null;
+  readonly gate: { readonly rationaleRef: string | null };
+}
+
+export const token = (value: string, path: string) => {
+  if (
+    value.length === 0 ||
+    /^[\t-\r ]|[\t-\r ]$/.test(value) ||
+    value.includes("\0")
+  )
+    throw new ComplianceError(
+      "BAD_DIAGNOSTIC_RUN",
+      `${path} must be a nonempty token`,
+      path,
+    );
+  for (let index = 0; index < value.length; index++) {
+    const unit = value.charCodeAt(index);
+    if (unit >= 0xd800 && unit <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff))
+        throw new ComplianceError(
+          "BAD_DIAGNOSTIC_RUN",
+          `${path} contains malformed Unicode`,
+          path,
+        );
+      index++;
+    } else if (unit >= 0xdc00 && unit <= 0xdfff)
+      throw new ComplianceError(
+        "BAD_DIAGNOSTIC_RUN",
+        `${path} contains malformed Unicode`,
+        path,
+      );
+  }
+};
+export function plain(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+export function exactKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  path: string,
+): void {
+  for (const key of Object.keys(value))
+    if (!allowed.includes(key))
+      throw new ComplianceError(
+        "BAD_DIAGNOSTIC_RUN",
+        `Unknown field ${key}`,
+        `${path}.${key}`,
+      );
+}
+export function snapshotLineage(
+  lineage: unknown,
+): readonly DiagnosticPreparationLineage[] {
+  if (!Array.isArray(lineage))
+    throw new ComplianceError(
+      "BAD_DIAGNOSTIC_RUN",
+      "$.preparationLineage must be an array",
+      "$.preparationLineage",
+    );
+  return lineage
+    .map((raw, index) => {
+      const path = `$.preparationLineage[${index}]`;
+      if (!plain(raw))
+        throw new ComplianceError(
+          "BAD_DIAGNOSTIC_RUN",
+          "Lineage edge must be a plain object",
+          path,
+        );
+      exactKeys(
+        raw,
+        ["outputArtifactId", "inputArtifactIds", "transformationArtifactIds"],
+        path,
+      );
+      if (typeof raw.outputArtifactId !== "string")
+        throw new ComplianceError(
+          "BAD_DIAGNOSTIC_RUN",
+          "Lineage output must be a string",
+          `${path}.outputArtifactId`,
+        );
+      token(raw.outputArtifactId, `${path}.outputArtifactId`);
+      const readIds = (value: unknown, key: string) => {
+        if (!Array.isArray(value))
+          throw new ComplianceError(
+            "BAD_DIAGNOSTIC_RUN",
+            `Lineage ${key} must be an array`,
+            `${path}.${key}`,
+          );
+        const result = value.map((id, inputIndex) => {
+          if (typeof id !== "string")
+            throw new ComplianceError(
+              "BAD_DIAGNOSTIC_RUN",
+              "Lineage artifact id must be a string",
+              `${path}.${key}[${inputIndex}]`,
+            );
+          token(id, `${path}.${key}[${inputIndex}]`);
+          return id;
+        });
+        if (new Set(result).size !== result.length)
+          throw new ComplianceError(
+            "BAD_DIAGNOSTIC_RUN",
+            `Lineage ${key} must be unique`,
+            `${path}.${key}`,
+          );
+        return [...result].sort();
+      };
+      const inputs = readIds(raw.inputArtifactIds, "inputArtifactIds"),
+        transformations = readIds(
+          raw.transformationArtifactIds,
+          "transformationArtifactIds",
+        );
+      if (inputs.length + transformations.length === 0)
+        throw new ComplianceError(
+          "BAD_DIAGNOSTIC_RUN",
+          "Lineage edge must have at least one upstream artifact",
+          path,
+        );
+      return {
+        outputArtifactId: raw.outputArtifactId,
+        inputArtifactIds: inputs,
+        transformationArtifactIds: transformations,
+      };
+    })
+    .sort((a, b) =>
+      a.outputArtifactId < b.outputArtifactId
+        ? -1
+        : a.outputArtifactId > b.outputArtifactId
+          ? 1
+          : 0,
+    );
+}
+
+export function validateArtifactGraph(
+  run: DiagnosticArtifactGraphContent,
+  inputArtifacts: readonly Pick<
+    DiagnosticArtifactDigest,
+    "id" | "scope" | "assurance"
+  >[],
+  preparationArtifacts: readonly Pick<
+    DiagnosticArtifactDigest,
+    "id" | "scope" | "assurance"
+  >[],
+  lineage: readonly DiagnosticPreparationLineage[],
+): void {
+  const byId = new Map<
+    string,
+    Pick<DiagnosticArtifactDigest, "id" | "scope" | "assurance">
+  >();
+  for (const [index, item] of [
+    ...inputArtifacts,
+    ...preparationArtifacts,
+  ].entries()) {
+    if (byId.has(item.id))
+      throw new ComplianceError(
+        "BAD_DIAGNOSTIC_RUN",
+        `Duplicate artifact ID ${item.id}`,
+        `$.${index < inputArtifacts.length ? "inputArtifacts" : "preparationArtifacts"}[${index < inputArtifacts.length ? index : index - inputArtifacts.length}].id`,
+      );
+    byId.set(item.id, item);
+  }
+  const referenced = new Set<string>();
+  const requireArtifact = (
+    id: string,
+    scope: "input" | "preparation",
+    path: string,
+  ) => {
+    const artifact = byId.get(id);
+    if (!artifact)
+      throw new ComplianceError(
+        "BAD_DIAGNOSTIC_RUN",
+        `Artifact reference ${id} is unresolved`,
+        path,
+      );
+    if (artifact.scope !== scope)
+      throw new ComplianceError(
+        "BAD_DIAGNOSTIC_RUN",
+        `Artifact ${id} must have ${scope} scope`,
+        path,
+      );
+    referenced.add(id);
+  };
+  let unsourced = false;
+  for (const [index, item] of run.prepared.inputAudit.entries()) {
+    const source = item.record.source;
+    if (source)
+      requireArtifact(
+        source.artifactId,
+        "input",
+        `$.completedRun.prepared.inputAudit[${index}].record.source.artifactId`,
+      );
+    else unsourced = true;
+  }
+  const evidence = run.review.evidence;
+  if (evidence) {
+    for (const [index, item] of evidence.groupingAssignments.entries()) {
+      if (item.source)
+        requireArtifact(
+          item.source.artifactId,
+          "input",
+          `$.completedRun.review.evidence.groupingAssignments[${index}].source.artifactId`,
+        );
+      else unsourced = true;
+    }
+    for (const [index, item] of evidence.cachedFormulas.entries()) {
+      if (item.source)
+        requireArtifact(
+          item.source.artifactId,
+          "input",
+          `$.completedRun.review.evidence.cachedFormulas[${index}].source.artifactId`,
+        );
+      else unsourced = true;
+    }
+  }
+  if (unsourced) {
+    if (run.datasetArtifactId === null)
+      throw new ComplianceError(
+        "BAD_DIAGNOSTIC_RUN",
+        "Unsourced diagnostic input requires datasetArtifactId",
+        "$.completedRun.datasetArtifactId",
+      );
+    const fallback = byId.get(run.datasetArtifactId);
+    if (
+      !fallback ||
+      fallback.scope !== "input" ||
+      fallback.assurance !== "sdk-computed"
+    )
+      throw new ComplianceError(
+        "BAD_DIAGNOSTIC_RUN",
+        "datasetArtifactId must resolve to SDK-computed input evidence",
+        "$.completedRun.datasetArtifactId",
+      );
+    referenced.add(run.datasetArtifactId);
+  } else if (run.datasetArtifactId !== null) {
+    requireArtifact(
+      run.datasetArtifactId,
+      "input",
+      "$.completedRun.datasetArtifactId",
+    );
+    if (byId.get(run.datasetArtifactId)!.assurance !== "sdk-computed")
+      throw new ComplianceError(
+        "BAD_DIAGNOSTIC_RUN",
+        "datasetArtifactId must resolve to SDK-computed input evidence",
+        "$.completedRun.datasetArtifactId",
+      );
+  }
+  for (const [
+    basisIndex,
+    basis,
+  ] of run.prepared.definition.definition.amountBases.entries())
+    for (const [componentIndex, component] of basis.components.entries())
+      if (
+        component.limitation.kind !== "unlimited" &&
+        component.limitation.kind !== "unknown" &&
+        component.limitation.derivation.kind === "external"
+      )
+        requireArtifact(
+          component.limitation.derivation.transformationRef,
+          "preparation",
+          `$.definition.amountBases[${basisIndex}].components[${componentIndex}].limitation.derivation.transformationRef`,
+        );
+  for (const [
+    ruleIndex,
+    rule,
+  ] of run.prepared.definition.definition.reviewRules.entries())
+    if (
+      rule.kind === "layer-order" &&
+      rule.comparability.kind === "caller-asserted"
+    )
+      requireArtifact(
+        rule.comparability.rationaleArtifactId,
+        "preparation",
+        `$.definition.reviewRules[${ruleIndex}].comparability.rationaleArtifactId`,
+      );
+  if (run.gate.rationaleRef !== null)
+    requireArtifact(
+      run.gate.rationaleRef,
+      "preparation",
+      "$.completedRun.gate.rationaleRef",
+    );
+  const edges = new Map<string, readonly string[]>();
+  for (const [index, edge] of lineage.entries()) {
+    const path = `$.preparationLineage[${index}]`;
+    if (edges.has(edge.outputArtifactId))
+      throw new ComplianceError(
+        "BAD_DIAGNOSTIC_RUN",
+        "An artifact may have only one producing lineage edge",
+        `${path}.outputArtifactId`,
+      );
+    const downstream = byId.get(edge.outputArtifactId);
+    if (!downstream)
+      throw new ComplianceError(
+        "BAD_DIAGNOSTIC_RUN",
+        `Lineage artifact ${edge.outputArtifactId} is unresolved`,
+        `${path}.outputArtifactId`,
+      );
+    if (downstream.scope !== "input")
+      throw new ComplianceError(
+        "BAD_DIAGNOSTIC_RUN",
+        "Lineage output artifact must have input scope",
+        `${path}.outputArtifactId`,
+      );
+    for (const [inputIndex, id] of edge.inputArtifactIds.entries()) {
+      if (id === edge.outputArtifactId)
+        throw new ComplianceError(
+          "BAD_DIAGNOSTIC_RUN",
+          "Lineage may not reference itself",
+          `${path}.inputArtifactIds[${inputIndex}]`,
+        );
+      const artifact = byId.get(id);
+      if (!artifact || artifact.scope !== "input")
+        throw new ComplianceError(
+          "BAD_DIAGNOSTIC_RUN",
+          `Lineage input ${id} must resolve to input evidence`,
+          `${path}.inputArtifactIds[${inputIndex}]`,
+        );
+    }
+    for (const [
+      transformIndex,
+      id,
+    ] of edge.transformationArtifactIds.entries()) {
+      const artifact = byId.get(id);
+      if (!artifact || artifact.scope !== "preparation")
+        throw new ComplianceError(
+          "BAD_DIAGNOSTIC_RUN",
+          `Lineage transformation ${id} must resolve to preparation evidence`,
+          `${path}.transformationArtifactIds[${transformIndex}]`,
+        );
+    }
+    edges.set(edge.outputArtifactId, [
+      ...edge.inputArtifactIds,
+      ...edge.transformationArtifactIds,
+    ]);
+  }
+  const visiting = new Set<string>(),
+    visited = new Set<string>();
+  for (const root of [...referenced]) {
+    const stack = [{ id: root, exit: false }];
+    while (stack.length > 0) {
+      const { id, exit } = stack.pop()!;
+      if (exit) {
+        visiting.delete(id);
+        visited.add(id);
+        continue;
+      }
+      if (visiting.has(id))
+        throw new ComplianceError(
+          "BAD_DIAGNOSTIC_RUN",
+          "Artifact lineage contains a cycle",
+          "$.preparationLineage",
+        );
+      if (visited.has(id)) continue;
+      visiting.add(id);
+      stack.push({ id, exit: true });
+      for (const upstream of [...(edges.get(id) ?? [])].reverse()) {
+        referenced.add(upstream);
+        stack.push({ id: upstream, exit: false });
+      }
+    }
+  }
+  for (const [index, artifact] of inputArtifacts.entries())
+    if (!referenced.has(artifact.id))
+      throw new ComplianceError(
+        "BAD_DIAGNOSTIC_RUN",
+        `Artifact ${artifact.id} is orphaned`,
+        `$.inputArtifacts[${index}].id`,
+      );
+  for (const [index, artifact] of preparationArtifacts.entries())
+    if (!referenced.has(artifact.id))
+      throw new ComplianceError(
+        "BAD_DIAGNOSTIC_RUN",
+        `Artifact ${artifact.id} is orphaned`,
+        `$.preparationArtifacts[${index}].id`,
+      );
+}

package/src/index.ts

@@ -5,5 +5,15 @@ export * from "./ledger.js";
 export * from "./modelCards.js";
 export * from "./disclosure.js";
 export * from "./diagnosticRun.js";
+export * from "./diagnosticArtifactStream.js";
+export {
+  createCompactDiagnosticRunIdentity,
+  assertVerifiedCompactDiagnosticRunProvenance,
+  type CompactDiagnosticArtifactEvidence,
+  type CreateCompactDiagnosticRunIdentityInput,
+  type VerifiedCompactDiagnosticRunProvenance,
+} from "./diagnosticCompactRun.js";
+export * from "./diagnosticReplayWriter.js";
+export * from "./diagnosticReplayReader.js";
 export * from "./bundle.js";
 export * from "./ave.js";

package/src/sha256Stream.ts

@@ -0,0 +1,108 @@
+/**
+ * Private incremental SHA-256, following FIPS 180-4 sections 4.1.2, 4.2.2,
+ * 5.1.1, 5.3.3 and 6.2.2. No I/O, dependencies or whole-message buffering.
+ * https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf
+ * This implementation is not a NIST/FIPS-validated cryptographic module.
+ */
+const ROUND = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+const rotate = (value: number, count: number) => (value >>> count) | (value << (32 - count));
+
+/** Internal state never escapes; update consumes bytes synchronously. */
+export function createSha256() {
+  const state = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ]);
+  const block = new Uint8Array(64);
+  const words = new Uint32Array(64);
+  let buffered = 0;
+  let byteLength = 0;
+  let finalized = false;
+
+  function compress() {
+    const view = new DataView(block.buffer);
+    for (let index = 0; index < 16; index++) words[index] = view.getUint32(index * 4, false);
+    for (let index = 16; index < 64; index++) {
+      const a = words[index - 15]!;
+      const b = words[index - 2]!;
+      const small0 = rotate(a, 7) ^ rotate(a, 18) ^ (a >>> 3);
+      const small1 = rotate(b, 17) ^ rotate(b, 19) ^ (b >>> 10);
+      words[index] = (words[index - 16]! + small0 + words[index - 7]! + small1) >>> 0;
+    }
+    let a = state[0]!,
+      b = state[1]!,
+      c = state[2]!,
+      d = state[3]!;
+    let e = state[4]!,
+      f = state[5]!,
+      g = state[6]!,
+      h = state[7]!;
+    for (let index = 0; index < 64; index++) {
+      const large1 = rotate(e, 6) ^ rotate(e, 11) ^ rotate(e, 25);
+      const choose = (e & f) ^ (~e & g);
+      const t1 = (h + large1 + choose + ROUND[index]! + words[index]!) >>> 0;
+      const large0 = rotate(a, 2) ^ rotate(a, 13) ^ rotate(a, 22);
+      const majority = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (large0 + majority) >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = (d + t1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (t1 + t2) >>> 0;
+    }
+    const completed = [a, b, c, d, e, f, g, h];
+    for (let index = 0; index < 8; index++)
+      state[index] = (state[index]! + completed[index]!) >>> 0;
+  }
+
+  return {
+    update(bytes: Uint8Array): void {
+      if (finalized) throw new Error("SHA-256 state is finalized");
+      if (!Number.isSafeInteger(byteLength + bytes.byteLength))
+        throw new RangeError("SHA-256 byte length exceeds the safe integer range");
+      byteLength += bytes.byteLength;
+      let offset = 0;
+      while (offset < bytes.byteLength) {
+        const count = Math.min(64 - buffered, bytes.byteLength - offset);
+        block.set(bytes.subarray(offset, offset + count), buffered);
+        buffered += count;
+        offset += count;
+        if (buffered === 64) {
+          compress();
+          buffered = 0;
+        }
+      }
+    },
+    digest(): string {
+      if (finalized) throw new Error("SHA-256 state is finalized");
+      finalized = true;
+      block[buffered++] = 0x80;
+      block.fill(0, buffered);
+      if (buffered > 56) {
+        compress();
+        block.fill(0);
+      }
+      const view = new DataView(block.buffer);
+      // Split the bit length before multiplying: exact for every safe byte length.
+      view.setUint32(56, Math.floor(byteLength / 0x20000000), false);
+      view.setUint32(60, (byteLength % 0x20000000) * 8, false);
+      compress();
+      const hex = Array.from(state, (word) => word.toString(16).padStart(8, "0")).join("");
+      block.fill(0);
+      words.fill(0);
+      state.fill(0);
+      return hex;
+    },
+  };
+}

package/src/version.ts

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