@actuarial-ts/compliance 0.6.0 → 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/ledger.ts

@@ -30,7 +30,13 @@ import { canonicalJson, ComplianceError } from "./bundle.js";
 export type AssumptionActor = "default" | "actuary" | "agent";
 
 /** JSON-representable assumption value (the ledger stores data, not behavior). */
-export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
 
 export interface AssumptionEntry {
   /** 1-based position in the ledger; assigned by recordAssumption, never by the caller. */
@@ -58,7 +64,31 @@ export interface AssumptionLedger {
 
 /** An empty, frozen ledger. */
 export function createLedger(): AssumptionLedger {
-  return Object.freeze({ entries: Object.freeze([]) as readonly AssumptionEntry[] });
+  return Object.freeze({
+    entries: Object.freeze([]) as readonly AssumptionEntry[],
+  });
+}
+
+function snapshotJson(value: JsonValue): JsonValue {
+  let cloned: JsonValue;
+  try {
+    cloned = JSON.parse(canonicalJson(value)) as JsonValue;
+  } catch {
+    throw new ComplianceError(
+      "BAD_BUNDLE",
+      "Assumption values must be finite, acyclic JSON data",
+    );
+  }
+  const freeze = (item: JsonValue): JsonValue => {
+    if (item === null || typeof item !== "object") return item;
+    if (Array.isArray(item)) {
+      for (const child of item) freeze(child);
+    } else {
+      for (const child of Object.values(item)) freeze(child);
+    }
+    return Object.freeze(item) as JsonValue;
+  };
+  return freeze(cloned);
 }
 
 /**
@@ -67,15 +97,30 @@ export function createLedger(): AssumptionLedger {
  * ComplianceError("MISSING_RATIONALE") when actor !== "default" and rationale
  * is missing or blank.
  */
-export function recordAssumption(ledger: AssumptionLedger, entry: NewAssumptionEntry): AssumptionLedger {
-  if (entry.actor !== "default" && (entry.rationale === undefined || entry.rationale.trim() === "")) {
+export function recordAssumption(
+  ledger: AssumptionLedger,
+  entry: NewAssumptionEntry,
+): AssumptionLedger {
+  if (
+    entry.actor !== "default" &&
+    (entry.rationale === undefined || entry.rationale.trim() === "")
+  ) {
     throw new ComplianceError(
       "MISSING_RATIONALE",
       `assumption "${entry.field}" set by actor "${entry.actor}" requires a rationale; only actor "default" may omit one`,
     );
   }
-  const recorded: AssumptionEntry = Object.freeze({ ...entry, seq: ledger.entries.length + 1 });
-  return Object.freeze({ entries: Object.freeze([...ledger.entries, recorded]) });
+  const recorded: AssumptionEntry = Object.freeze({
+    ...entry,
+    value: snapshotJson(entry.value),
+    ...(entry.previousValue === undefined
+      ? {}
+      : { previousValue: snapshotJson(entry.previousValue) }),
+    seq: ledger.entries.length + 1,
+  });
+  return Object.freeze({
+    entries: Object.freeze([...ledger.entries, recorded]),
+  });
 }
 
 /** Entries that represent judgment (actor !== "default"), in ledger order. */
@@ -120,7 +165,9 @@ export function changedAssumptions(
   const added: string[] = [];
   const removed: string[] = [];
   const changed: AssumptionValueChange[] = [];
-  const fields = [...new Set([...priorLatest.keys(), ...currentLatest.keys()])].sort();
+  const fields = [
+    ...new Set([...priorLatest.keys(), ...currentLatest.keys()]),
+  ].sort();
   for (const field of fields) {
     const before = priorLatest.get(field);
     const after = currentLatest.get(field);
@@ -133,7 +180,11 @@ export function changedAssumptions(
       continue;
     }
     if (canonicalJson(before.value) !== canonicalJson(after.value)) {
-      changed.push({ field, priorValue: before.value, currentValue: after.value });
+      changed.push({
+        field,
+        priorValue: before.value,
+        currentValue: after.value,
+      });
     }
   }
   return { added, removed, changed };

package/src/metadata.ts

@@ -92,7 +92,20 @@ function isIsoDate(value: string): boolean {
   const day = Number(match[3]);
   if (month < 1 || month > 12) return false;
   const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
-  const daysInMonth = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1]!;
+  const daysInMonth = [
+    31,
+    leap ? 29 : 28,
+    31,
+    30,
+    31,
+    30,
+    31,
+    31,
+    30,
+    31,
+    30,
+    31,
+  ][month - 1]!;
   return day >= 1 && day <= daysInMonth;
 }
 
@@ -100,13 +113,20 @@ function isNonEmptyString(value: unknown): value is string {
   return typeof value === "string" && value.trim() !== "";
 }
 
-function checkDate(problems: string[], name: string, value: unknown, required: boolean): void {
+function checkDate(
+  problems: string[],
+  name: string,
+  value: unknown,
+  required: boolean,
+): void {
   if (value === undefined) {
     if (required) problems.push(`${name} is required (ISO yyyy-mm-dd)`);
     return;
   }
   if (typeof value !== "string" || !isIsoDate(value)) {
-    problems.push(`${name} must be a valid ISO date (yyyy-mm-dd); got ${JSON.stringify(value)}`);
+    problems.push(
+      `${name} must be a valid ISO date (yyyy-mm-dd); got ${JSON.stringify(value)}`,
+    );
   }
 }
 
@@ -123,7 +143,9 @@ export function validateMetadata(metadata: EstimateMetadata): string[] {
 
   if (metadata.intendedUsers !== undefined) {
     if (!Array.isArray(metadata.intendedUsers)) {
-      problems.push("intendedUsers, when provided, must be an array of non-empty strings");
+      problems.push(
+        "intendedUsers, when provided, must be an array of non-empty strings",
+      );
     } else {
       metadata.intendedUsers.forEach((user, index) => {
         if (!isNonEmptyString(user)) {
@@ -145,8 +167,15 @@ export function validateMetadata(metadata: EstimateMetadata): string[] {
     if (measure.kind === "specified-percentile") {
       const p = measure.percentile;
       if (p === undefined) {
-        problems.push('intendedMeasure.percentile is required when kind is "specified-percentile"');
-      } else if (typeof p !== "number" || !Number.isFinite(p) || p <= 0 || p >= 1) {
+        problems.push(
+          'intendedMeasure.percentile is required when kind is "specified-percentile"',
+        );
+      } else if (
+        typeof p !== "number" ||
+        !Number.isFinite(p) ||
+        p <= 0 ||
+        p >= 1
+      ) {
         problems.push(
           `intendedMeasure.percentile must be a fraction strictly between 0 and 1 (e.g. 0.75); got ${JSON.stringify(p)}`,
         );
@@ -177,8 +206,20 @@ export function validateMetadata(metadata: EstimateMetadata): string[] {
   checkDate(problems, "accountingDate", metadata.accountingDate, true);
   checkDate(problems, "valuationDate", metadata.valuationDate, true);
   checkDate(problems, "reviewDate", metadata.reviewDate, false);
+  if (
+    typeof metadata.reviewDate === "string" &&
+    isIsoDate(metadata.reviewDate) &&
+    typeof metadata.valuationDate === "string" &&
+    isIsoDate(metadata.valuationDate) &&
+    metadata.reviewDate < metadata.valuationDate
+  ) {
+    problems.push("reviewDate cannot precede valuationDate");
+  }
 
-  if (metadata.scopeNotes !== undefined && !isNonEmptyString(metadata.scopeNotes)) {
+  if (
+    metadata.scopeNotes !== undefined &&
+    !isNonEmptyString(metadata.scopeNotes)
+  ) {
     problems.push("scopeNotes, when provided, must be a non-empty string");
   }
   if (metadata.currency !== undefined && !isNonEmptyString(metadata.currency)) {