@actuarial-ts/data 0.6.1 → 0.7.0

package/src/diagnosticInput.ts

@@ -2,8 +2,13 @@ import {
   DiagnosticValidationError,
   compileDiagnosticDefinition,
   prepareDiagnosticData,
+  prepareDiagnosticDataCompact,
   runMetricDiagnostics,
+  runMetricDiagnosticsCompact,
   validateDiagnosticGroupingConfiguration,
+  validateCompactDiagnosticGroupingConfiguration,
+  type CompactMetricDiagnosticsResult,
+  type CompactPreparedDiagnosticData,
   type CompiledDiagnosticDefinition,
   type DiagnosticCompletePeriodCutoff,
   type DiagnosticDeepReadonly,
@@ -14,6 +19,7 @@ import {
   type DiagnosticsFilter,
   type JsonValue,
   type MetricDiagnosticsResult,
+  type PreparedDiagnosticData,
   type DiagnosticValidationIssue,
   diagnosticRecord,
   isDiagnosticToken,
@@ -22,9 +28,11 @@ import {
 import { z } from "zod";
 import {
   reviewPreparedDiagnosticData,
+  reviewPreparedDiagnosticDataCompact,
   validateDiagnosticReviewEvidence,
   type DiagnosticReviewEvidence,
   type DiagnosticReviewReceipt,
+  type CompactDiagnosticReviewReceipt,
 } from "./diagnosticPreparedReview.js";
 
 // Zod 3 validates but drops the literal __proto__ key while assembling records.
@@ -46,16 +54,10 @@ function recordSchema<T extends z.ZodTypeAny>(value: T) {
 
 const tokenSchema = z
   .string()
-  .refine(
-    isDiagnosticToken,
-    "Expected a nonempty token with valid Unicode and no U+0000",
-  );
+  .refine(isDiagnosticToken, "Expected a nonempty token with valid Unicode and no U+0000");
 const jsonStringSchema = z
   .string()
-  .refine(
-    isWellFormedDiagnosticString,
-    "Expected valid Unicode without U+0000",
-  );
+  .refine(isWellFormedDiagnosticString, "Expected valid Unicode without U+0000");
 const sourceSchema = z
   .object({
     artifactId: tokenSchema,
@@ -65,10 +67,7 @@ const sourceSchema = z
     sourceCell: tokenSchema.optional(),
   })
   .strict();
-const rawNumberSchema = z.custom<number>(
-  (value) => typeof value === "number",
-  "Expected number",
-);
+const rawNumberSchema = z.custom<number>((value) => typeof value === "number", "Expected number");
 const measuresSchema = recordSchema(z.union([rawNumberSchema, z.null()]));
 const lossBase = {
   recordId: tokenSchema,
@@ -80,9 +79,7 @@ const lossBase = {
   measures: measuresSchema,
 };
 const lossSchema = z.discriminatedUnion("rowType", [
-  z
-    .object({ ...lossBase, rowType: z.literal("claim"), claimId: tokenSchema })
-    .strict(),
+  z.object({ ...lossBase, rowType: z.literal("claim"), claimId: tokenSchema }).strict(),
   z.object({ ...lossBase, rowType: z.literal("aggregate") }).strict(),
 ]);
 const exposureSchema = z
@@ -139,12 +136,8 @@ const jsonSchema: z.ZodType<JsonValue> = z.lazy(() =>
 );
 const policySchema = z
   .object({
-    allowedReviewStatuses: z
-      .array(z.enum(["pass", "warning", "not-evaluated", "fail"]))
-      .optional(),
-    allowedMetricFindingSeverities: z
-      .array(z.enum(["info", "warning", "fail"]))
-      .optional(),
+    allowedReviewStatuses: z.array(z.enum(["pass", "warning", "not-evaluated", "fail"])).optional(),
+    allowedMetricFindingSeverities: z.array(z.enum(["info", "warning", "fail"])).optional(),
     rationaleRef: tokenSchema.optional(),
   })
   .strict();
@@ -165,18 +158,10 @@ const runSchema = z
   })
   .strict();
 
-export type DiagnosticAllowedReviewStatus =
-  | "pass"
-  | "warning"
-  | "not-evaluated"
-  | "fail";
+export type DiagnosticAllowedReviewStatus = "pass" | "warning" | "not-evaluated" | "fail";
 export interface DiagnosticExecutionPolicyInput {
   readonly allowedReviewStatuses?: readonly DiagnosticAllowedReviewStatus[];
-  readonly allowedMetricFindingSeverities?: readonly (
-    | "info"
-    | "warning"
-    | "fail"
-  )[];
+  readonly allowedMetricFindingSeverities?: readonly ("info" | "warning" | "fail")[];
   readonly rationaleRef?: string;
 }
 export interface DiagnosticRunInput {
@@ -209,21 +194,23 @@ export interface ValidatedDiagnosticRunInput {
   readonly groupDimensions: Readonly<Record<string, JsonValue>>;
   readonly policy: {
     readonly allowedReviewStatuses: readonly DiagnosticAllowedReviewStatus[];
-    readonly allowedMetricFindingSeverities: readonly (
-      | "info"
-      | "warning"
-      | "fail"
-    )[];
+    readonly allowedMetricFindingSeverities: readonly ("info" | "warning" | "fail")[];
     readonly rationaleRef: string | null;
   };
 }
+
+type DiagnosticRunInputContent = Omit<
+  ValidatedDiagnosticRunInput,
+  typeof validatedDiagnosticRunInputBrand
+>;
+declare const compactValidatedDiagnosticRunInputBrand: unique symbol;
+/** Validated owned input whose preparation does not eagerly expand identity evidence. */
+export interface CompactValidatedDiagnosticRunInput extends DiagnosticRunInputContent {
+  readonly [compactValidatedDiagnosticRunInputBrand]: true;
+}
 export interface DiagnosticExecutionGateReceipt {
   readonly allowedReviewStatuses: readonly DiagnosticAllowedReviewStatus[];
-  readonly allowedMetricFindingSeverities: readonly (
-    | "info"
-    | "warning"
-    | "fail"
-  )[];
+  readonly allowedMetricFindingSeverities: readonly ("info" | "warning" | "fail")[];
   readonly rationaleRef: string | null;
   readonly reviewGate: "passed" | "blocked";
   readonly metricGate: "not-run" | "passed" | "blocked";
@@ -275,16 +262,63 @@ export type ValidatedMetricDiagnosticsOutcome =
       };
     };
 
+/** A distinct authenticated run; it cannot be substituted for an eager receipt. */
+export interface CompletedCompactMetricDiagnosticsRun {
+  readonly status: "completed";
+  readonly prepared: CompactPreparedDiagnosticData;
+  readonly review: CompactDiagnosticReviewReceipt;
+  readonly result: DiagnosticDeepReadonly<CompactMetricDiagnosticsResult>;
+  readonly runPresetId: string | null;
+  readonly datasetArtifactId: string | null;
+  readonly groupMap: Readonly<Record<string, string>>;
+  readonly groupDimensions: Readonly<Record<string, JsonValue>>;
+  readonly gate: DiagnosticExecutionGateReceipt & {
+    readonly reviewGate: "passed";
+    readonly metricGate: "passed";
+  };
+}
+type CompactRunMetadata = Omit<CompletedCompactMetricDiagnosticsRun, "status" | "result" | "gate">;
+export type CompactMetricDiagnosticsOutcome =
+  | CompletedCompactMetricDiagnosticsRun
+  | (CompactRunMetadata & {
+      readonly status: "blocked";
+      readonly stage: "review";
+      readonly result: null;
+      readonly gate: DiagnosticExecutionGateReceipt & {
+        readonly reviewGate: "blocked";
+        readonly metricGate: "not-run";
+      };
+    })
+  | (CompactRunMetadata & {
+      readonly status: "blocked";
+      readonly stage: "metric";
+      readonly result: DiagnosticDeepReadonly<CompactMetricDiagnosticsResult>;
+      readonly gate: DiagnosticExecutionGateReceipt & {
+        readonly reviewGate: "passed";
+        readonly metricGate: "blocked";
+      };
+    });
+
 const authentic = new WeakSet<object>();
-function freeze<T>(
-  value: T,
-  seen = new WeakSet<object>(),
-): DiagnosticDeepReadonly<T> {
+// Only owned, frozen inputs can enter this cache. Weak keys do not retain a
+// completed analysis after its caller releases it, and JSON cannot restore it.
+const preparedByInput = new WeakMap<ValidatedDiagnosticRunInput, PreparedDiagnosticData>();
+const compactPreparedByInput = new WeakMap<
+  CompactValidatedDiagnosticRunInput,
+  CompactPreparedDiagnosticData
+>();
+const compactCompleted = new WeakSet<object>();
+// Retain the exact immutable validated input only while its completed run lives.
+// Reconstructing from the audit would lose the original optional/raw-value form.
+const compactInputByCompletedRun = new WeakMap<
+  CompletedCompactMetricDiagnosticsRun,
+  CompactValidatedDiagnosticRunInput
+>();
+function freeze<T>(value: T, seen = new WeakSet<object>()): DiagnosticDeepReadonly<T> {
   if (value === null || typeof value !== "object" || seen.has(value))
     return value as DiagnosticDeepReadonly<T>;
   seen.add(value);
-  for (const child of Object.values(value as Record<string, unknown>))
-    freeze(child, seen);
+  for (const child of Object.values(value as Record<string, unknown>)) freeze(child, seen);
   return Object.freeze(value) as DiagnosticDeepReadonly<T>;
 }
 function issues(error: z.ZodError): DiagnosticValidationError {
@@ -306,28 +340,19 @@ function issues(error: z.ZodError): DiagnosticValidationError {
 function codeUnit(left: string, right: string): number {
   return left < right ? -1 : left > right ? 1 : 0;
 }
-function sortedRecord<T>(
-  value: Readonly<Record<string, T>>,
-): Readonly<Record<string, T>> {
+function sortedRecord<T>(value: Readonly<Record<string, T>>): Readonly<Record<string, T>> {
   const result = diagnosticRecord<T>();
-  for (const key of Object.keys(value).sort(codeUnit))
-    result[key] = value[key]!;
+  for (const key of Object.keys(value).sort(codeUnit)) result[key] = value[key]!;
   return result;
 }
 
 function explicitUndefinedIssues(value: unknown): DiagnosticValidationIssue[] {
   const found: DiagnosticValidationIssue[] = [];
-  const stack: { readonly value: unknown; readonly path: string }[] = [
-    { value, path: "$" },
-  ];
+  const stack: { readonly value: unknown; readonly path: string }[] = [{ value, path: "$" }];
   const seen = new WeakSet<object>();
   while (stack.length > 0) {
     const current = stack.pop()!;
-    if (
-      current.value === null ||
-      typeof current.value !== "object" ||
-      seen.has(current.value)
-    )
+    if (current.value === null || typeof current.value !== "object" || seen.has(current.value))
       continue;
     seen.add(current.value);
     for (const [key, child] of Object.entries(current.value)) {
@@ -355,38 +380,29 @@ function explicitUndefinedIssues(value: unknown): DiagnosticValidationIssue[] {
   return found;
 }
 
-export function validateDiagnosticRunInput(
-  value: unknown,
-): ValidatedDiagnosticRunInput {
+// Both public gateways share the same full validation/ownership boundary.
+// Selecting compact storage never invokes the eager preparation first.
+function validateRunInputContent(value: unknown): DiagnosticRunInputContent {
   const undefinedIssues = explicitUndefinedIssues(value);
-  if (undefinedIssues.length > 0)
-    throw new DiagnosticValidationError(undefinedIssues);
+  if (undefinedIssues.length > 0) throw new DiagnosticValidationError(undefinedIssues);
   const parsed = runSchema.safeParse(value);
   if (!parsed.success) throw issues(parsed.error);
-  const definition = compileDiagnosticDefinition(
-    parsed.data.definition as DiagnosticDefinition,
+  const definition = compileDiagnosticDefinition(parsed.data.definition as DiagnosticDefinition);
+  const relationIssues: DiagnosticValidationIssue[] = parsed.data.losses.flatMap((row, index) =>
+    row.rowType === definition.definition.lossRowGrain
+      ? []
+      : [
+          {
+            domain: "input" as const,
+            code: "invalid-input-relationship" as const,
+            path: `$.losses[${index}].rowType`,
+            message: "Loss row type does not match definition grain",
+          },
+        ],
   );
-  const relationIssues: DiagnosticValidationIssue[] =
-    parsed.data.losses.flatMap((row, index) =>
-      row.rowType === definition.definition.lossRowGrain
-        ? []
-        : [
-            {
-              domain: "input" as const,
-              code: "invalid-input-relationship" as const,
-              path: `$.losses[${index}].rowType`,
-              message: "Loss row type does not match definition grain",
-            },
-          ],
-    );
   for (const [index, row] of (parsed.data.exposures ?? []).entries()) {
-    const measure = definition.definition.measures.find(
-      (item) => item.id === row.measureId,
-    );
-    if (
-      measure?.exposureTiming === "valuation-specific" &&
-      row.valuation === undefined
-    )
+    const measure = definition.definition.measures.find((item) => item.id === row.measureId);
+    if (measure?.exposureTiming === "valuation-specific" && row.valuation === undefined)
       relationIssues.push({
         domain: "input",
         code: "missing-required",
@@ -394,22 +410,11 @@ export function validateDiagnosticRunInput(
         message: "Valuation-specific exposure requires valuation",
       });
   }
-  if (relationIssues.length)
-    throw new DiagnosticValidationError(relationIssues);
-  const review = parsed.data.policy?.allowedReviewStatuses ?? [
-    "pass",
-    "warning",
-    "not-evaluated",
-  ];
-  const metric = parsed.data.policy?.allowedMetricFindingSeverities ?? [
-    "info",
-    "warning",
-  ];
+  if (relationIssues.length) throw new DiagnosticValidationError(relationIssues);
+  const review = parsed.data.policy?.allowedReviewStatuses ?? ["pass", "warning", "not-evaluated"];
+  const metric = parsed.data.policy?.allowedMetricFindingSeverities ?? ["info", "warning"];
   const rationale = parsed.data.policy?.rationaleRef ?? null;
-  if (
-    (review.includes("fail") || metric.includes("fail")) &&
-    rationale === null
-  )
+  if ((review.includes("fail") || metric.includes("fail")) && rationale === null)
     throw new DiagnosticValidationError([
       {
         domain: "configuration",
@@ -419,24 +424,16 @@ export function validateDiagnosticRunInput(
       },
     ]);
   const reviewEvidence =
-    parsed.data.reviewEvidence === undefined ||
-    parsed.data.reviewEvidence === null
+    parsed.data.reviewEvidence === undefined || parsed.data.reviewEvidence === null
       ? null
-      : validateDiagnosticReviewEvidence(
-          parsed.data.reviewEvidence,
-          "$.reviewEvidence",
-        );
+      : validateDiagnosticReviewEvidence(parsed.data.reviewEvidence, "$.reviewEvidence");
   const reviewOrder: readonly DiagnosticAllowedReviewStatus[] = [
     "pass",
     "warning",
     "not-evaluated",
     "fail",
   ];
-  const metricOrder: readonly ("info" | "warning" | "fail")[] = [
-    "info",
-    "warning",
-    "fail",
-  ];
+  const metricOrder: readonly ("info" | "warning" | "fail")[] = ["info", "warning", "fail"];
   for (const key of [
     ...Object.keys(parsed.data.groupMap ?? {}),
     ...Object.keys(parsed.data.groupDimensions ?? {}),
@@ -447,8 +444,7 @@ export function validateDiagnosticRunInput(
           domain: "configuration",
           code: "invalid-string",
           path: `$.groupMap[${JSON.stringify(key)}]`,
-          message:
-            "Group key must be a nonempty token with valid Unicode and no U+0000",
+          message: "Group key must be a nonempty token with valid Unicode and no U+0000",
         },
       ]);
   const result = freeze({
@@ -461,39 +457,76 @@ export function validateDiagnosticRunInput(
     reviewEvidence,
     runPresetId: parsed.data.runPresetId ?? null,
     datasetArtifactId: parsed.data.datasetArtifactId ?? null,
-    groupMap: sortedRecord(parsed.data.groupMap ?? diagnosticRecord()),
-    groupDimensions: sortedRecord(
-      parsed.data.groupDimensions ?? diagnosticRecord(),
+    groupMap: sortedRecord<string>(parsed.data.groupMap ?? diagnosticRecord<string>()),
+    groupDimensions: sortedRecord<JsonValue>(
+      parsed.data.groupDimensions ?? diagnosticRecord<JsonValue>(),
     ),
     policy: {
-      allowedReviewStatuses: reviewOrder.filter((status) =>
-        review.includes(status),
-      ),
-      allowedMetricFindingSeverities: metricOrder.filter((severity) =>
-        metric.includes(severity),
-      ),
+      allowedReviewStatuses: reviewOrder.filter((status) => review.includes(status)),
+      allowedMetricFindingSeverities: metricOrder.filter((severity) => metric.includes(severity)),
       rationaleRef: rationale,
     },
-  }) as unknown as ValidatedDiagnosticRunInput;
-  const prepared = prepareDiagnosticData({
-    definition: result.definition,
-    losses: result.losses,
-    exposures: result.exposures,
-    ...(result.filter === null ? {} : { filter: result.filter }),
-    completePeriodCutoffs: result.completePeriodCutoffs,
-    ...(result.expectedCells === null
-      ? {}
-      : { expectedCells: result.expectedCells }),
   });
+  return result;
+}
+
+function preparationInput(input: DiagnosticRunInputContent) {
+  return {
+    definition: input.definition,
+    losses: input.losses,
+    exposures: input.exposures,
+    ...(input.filter === null ? {} : { filter: input.filter }),
+    completePeriodCutoffs: input.completePeriodCutoffs,
+    ...(input.expectedCells === null ? {} : { expectedCells: input.expectedCells }),
+  };
+}
+
+export function validateDiagnosticRunInput(value: unknown): ValidatedDiagnosticRunInput {
+  const result = validateRunInputContent(value) as ValidatedDiagnosticRunInput;
+  const prepared = prepareDiagnosticData(preparationInput(result));
   validateDiagnosticGroupingConfiguration({
     prepared,
     groupMap: result.groupMap,
     groupDimensions: result.groupDimensions,
   });
   authentic.add(result);
+  preparedByInput.set(result, prepared);
   return result;
 }
 
+/** Validate, own and prepare inputs without eagerly materializing identity graphs. */
+export function validateDiagnosticRunInputCompact(
+  value: unknown,
+): CompactValidatedDiagnosticRunInput {
+  const result = validateRunInputContent(value) as CompactValidatedDiagnosticRunInput;
+  const prepared = prepareDiagnosticDataCompact(preparationInput(result));
+  validateCompactDiagnosticGroupingConfiguration({
+    prepared,
+    groupMap: result.groupMap,
+    groupDimensions: result.groupDimensions,
+  });
+  compactPreparedByInput.set(result, prepared);
+  return result;
+}
+
+export function assertCompactValidatedDiagnosticRunInput(
+  value: unknown,
+): asserts value is CompactValidatedDiagnosticRunInput {
+  if (
+    value === null ||
+    typeof value !== "object" ||
+    !compactPreparedByInput.has(value as CompactValidatedDiagnosticRunInput)
+  )
+    throw new DiagnosticValidationError([
+      {
+        domain: "input",
+        code: "invalid-input-relationship",
+        path: "$",
+        message: "Value is not an authentic compact validated diagnostic run input",
+      },
+    ]);
+}
+
 export function assertValidatedDiagnosticRunInput(
   value: unknown,
 ): asserts value is ValidatedDiagnosticRunInput {
@@ -513,16 +546,9 @@ export function runValidatedMetricDiagnostics(
   input: ValidatedDiagnosticRunInput,
 ): ValidatedMetricDiagnosticsOutcome {
   assertValidatedDiagnosticRunInput(input);
-  const prepared = prepareDiagnosticData({
-    definition: input.definition,
-    losses: input.losses,
-    exposures: input.exposures,
-    ...(input.filter === null ? {} : { filter: input.filter }),
-    completePeriodCutoffs: input.completePeriodCutoffs,
-    ...(input.expectedCells === null
-      ? {}
-      : { expectedCells: input.expectedCells }),
-  });
+  // Validation already prepared these exact immutable inputs and checked their
+  // grouping. Reuse the authentic result without skipping any execution gate.
+  const prepared = preparedByInput.get(input)!;
   validateDiagnosticGroupingConfiguration({
     prepared,
     groupMap: input.groupMap,
@@ -547,10 +573,7 @@ export function runValidatedMetricDiagnostics(
       (check) => !input.policy.allowedReviewStatuses.includes(check.status),
     ) ||
     review.evaluations.some(
-      (evaluation) =>
-        !input.policy.allowedReviewStatuses.includes(
-          evaluationStatus(evaluation),
-        ),
+      (evaluation) => !input.policy.allowedReviewStatuses.includes(evaluationStatus(evaluation)),
     );
   const base = {
     prepared,
@@ -560,8 +583,13 @@ export function runValidatedMetricDiagnostics(
     groupMap: input.groupMap,
     groupDimensions: input.groupDimensions,
   };
+  // These graphs were deeply frozen by their authentic SDK constructors. Walk
+  // only the new outcome envelope; a shallow-frozen caller object never enters
+  // this set, so the public input boundary still checks/freezes every child.
+  const frozenSdkGraphs = new WeakSet<object>([prepared, review]);
+  const freezeOutcome = <T>(value: T) => freeze(value, frozenSdkGraphs);
   if (disallowedReview)
-    return freeze({
+    return freezeOutcome({
       ...base,
       status: "blocked" as const,
       stage: "review" as const,
@@ -577,13 +605,14 @@ export function runValidatedMetricDiagnostics(
     groupMap: input.groupMap,
     groupDimensions: input.groupDimensions,
   });
+  frozenSdkGraphs.add(result);
   const disallowedMetric = result.findings.some(
     (finding) =>
       finding.category !== "structural" &&
       !input.policy.allowedMetricFindingSeverities.includes(finding.severity),
   );
   if (disallowedMetric)
-    return freeze({
+    return freezeOutcome({
       ...base,
       status: "blocked" as const,
       stage: "metric" as const,
@@ -594,7 +623,7 @@ export function runValidatedMetricDiagnostics(
         metricGate: "blocked" as const,
       },
     }) as ValidatedMetricDiagnosticsOutcome;
-  const outcome = freeze({
+  const outcome = freezeOutcome({
     ...base,
     status: "completed" as const,
     result,
@@ -620,3 +649,121 @@ export function assertCompletedValidatedMetricDiagnosticsRun(
       },
     ]);
 }
+
+/** Run every review and metric gate while retaining complete compact evidence. */
+export function runValidatedMetricDiagnosticsCompact(
+  input: CompactValidatedDiagnosticRunInput,
+): CompactMetricDiagnosticsOutcome {
+  assertCompactValidatedDiagnosticRunInput(input);
+  const prepared = compactPreparedByInput.get(input)!;
+  validateCompactDiagnosticGroupingConfiguration({
+    prepared,
+    groupMap: input.groupMap,
+    groupDimensions: input.groupDimensions,
+  });
+  const review = reviewPreparedDiagnosticDataCompact({
+    prepared,
+    evidence: input.reviewEvidence as DiagnosticReviewEvidence | null,
+  });
+  const counts = review.evaluations.summary;
+  // Aggregate check status and individual effective status are both necessary:
+  // an allowed failure must not hide a disallowed not-evaluated row (or vice versa).
+  const effectiveCounts: Readonly<Record<DiagnosticAllowedReviewStatus, number>> = {
+    pass: counts.pass,
+    warning: counts.warning,
+    "not-evaluated": counts.notEvaluated,
+    fail: counts.fail,
+  };
+  const disallowedReview =
+    review.report.checks.some(
+      (check) => !input.policy.allowedReviewStatuses.includes(check.status),
+    ) ||
+    (Object.keys(effectiveCounts) as DiagnosticAllowedReviewStatus[]).some(
+      (status) =>
+        effectiveCounts[status] > 0 && !input.policy.allowedReviewStatuses.includes(status),
+    );
+  const base = {
+    prepared,
+    review,
+    runPresetId: input.runPresetId,
+    datasetArtifactId: input.datasetArtifactId,
+    groupMap: input.groupMap,
+    groupDimensions: input.groupDimensions,
+  };
+  const frozenSdkGraphs = new WeakSet<object>([prepared, review]);
+  const freezeOutcome = <T>(value: T) => freeze(value, frozenSdkGraphs);
+  if (disallowedReview)
+    return freezeOutcome({
+      ...base,
+      status: "blocked" as const,
+      stage: "review" as const,
+      result: null,
+      gate: {
+        ...input.policy,
+        reviewGate: "blocked" as const,
+        metricGate: "not-run" as const,
+      },
+    });
+  const result = runMetricDiagnosticsCompact({
+    prepared,
+    groupMap: input.groupMap,
+    groupDimensions: input.groupDimensions,
+  });
+  frozenSdkGraphs.add(result);
+  const disallowedMetric = result.findings.some(
+    (finding) =>
+      finding.category !== "structural" &&
+      !input.policy.allowedMetricFindingSeverities.includes(finding.severity),
+  );
+  if (disallowedMetric)
+    return freezeOutcome({
+      ...base,
+      status: "blocked" as const,
+      stage: "metric" as const,
+      result,
+      gate: {
+        ...input.policy,
+        reviewGate: "passed" as const,
+        metricGate: "blocked" as const,
+      },
+    });
+  const outcome = freezeOutcome({
+    ...base,
+    status: "completed" as const,
+    result,
+    gate: {
+      ...input.policy,
+      reviewGate: "passed" as const,
+      metricGate: "passed" as const,
+    },
+  });
+  compactCompleted.add(outcome);
+  compactInputByCompletedRun.set(outcome, input);
+  return outcome;
+}
+
+export function assertCompletedCompactMetricDiagnosticsRun(
+  value: unknown,
+): asserts value is CompletedCompactMetricDiagnosticsRun {
+  if (value === null || typeof value !== "object" || !compactCompleted.has(value))
+    throw new DiagnosticValidationError([
+      {
+        domain: "input",
+        code: "invalid-input-relationship",
+        path: "$",
+        message: "Value is not an authentic completed compact diagnostic run",
+      },
+    ]);
+}
+
+/**
+ * Return the original SDK-owned validated input for an authentic completed run.
+ * This is the same deeply immutable input owner, not a reconstruction from its
+ * normalized audit or a mutable copy of the caller's upload values.
+ */
+export function getCompletedCompactDiagnosticRunInput(
+  run: CompletedCompactMetricDiagnosticsRun,
+): CompactValidatedDiagnosticRunInput {
+  assertCompletedCompactMetricDiagnosticsRun(run);
+  return compactInputByCompletedRun.get(run)!;
+}