import { DiagnosticValidationError, compileDiagnosticDefinition, prepareDiagnosticData, prepareDiagnosticDataCompact, reselectCompactDiagnosticMetrics, selectCompactDiagnosticSourceGroups, selectCompactDiagnosticOrigins, selectCompactDiagnosticCoordinates, runMetricDiagnostics, runMetricDiagnosticsCompact, validateDiagnosticGroupingConfiguration, validateCompactDiagnosticGroupingConfiguration, type CompactMetricDiagnosticsResult, type CompactPreparedDiagnosticData, type CompiledDiagnosticDefinition, type DiagnosticCompletePeriodCutoff, type DiagnosticDeepReadonly, type DiagnosticDefinition, type DiagnosticExpectedCell, type DiagnosticExposureObservation, type DiagnosticLossInput, type DiagnosticsFilter, type JsonValue, type MetricDiagnosticsResult, type PreparedDiagnosticData, type DiagnosticValidationIssue, diagnosticRecord, isDiagnosticToken, isWellFormedDiagnosticString, AnalysisReviewError, snapshotDiagnosticJson, type AnalysisReviewFinding, } from "@actuarial-ts/core"; import { z } from "zod"; import { reviewPreparedDiagnosticData, reviewPreparedDiagnosticDataCompact, validateDiagnosticReviewEvidence, type DiagnosticReviewEvidence, type DiagnosticReviewReceipt, type CompactDiagnosticReviewReceipt, } from "./diagnosticPreparedReview.js"; import { parseDiagnosticExecutionRequest, diagnosticExecutionLimit, type DiagnosticExecutionPreflight } from "./diagnosticExecutionContracts.js"; // Zod 3 validates but drops the literal __proto__ key while assembling records. // Encode every key reversibly during validation, then restore owned data keys. // The same adapter is exercised by the shared three-shore prototype-key corpus. function recordSchema(value: T) { return z .record( z.string().transform((key) => `:${key}`), value, ) .transform( (record) => Object.fromEntries( Object.entries(record).map(([key, item]) => [key.slice(1), item]), ) as Record>, ); } const tokenSchema = z .string() .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"); const sourceSchema = z .object({ artifactId: tokenSchema, sourceFile: tokenSchema.optional(), sourceSheet: tokenSchema.optional(), sourceRow: z.number().int().nonnegative().safe().optional(), sourceCell: tokenSchema.optional(), }) .strict(); const rawNumberSchema = z.custom((value) => typeof value === "number", "Expected number"); const measuresSchema = recordSchema(z.union([rawNumberSchema, z.null()])); const lossBase = { recordId: tokenSchema, sourceGroup: tokenSchema, origin: tokenSchema, valuation: tokenSchema, complete: z.boolean(), source: sourceSchema.optional(), measures: measuresSchema, }; const lossSchema = z.discriminatedUnion("rowType", [ z.object({ ...lossBase, rowType: z.literal("claim"), claimId: tokenSchema }).strict(), z.object({ ...lossBase, rowType: z.literal("aggregate") }).strict(), ]); const exposureSchema = z .object({ key: tokenSchema, sourceGroup: tokenSchema, origin: tokenSchema, valuation: tokenSchema.optional(), measureId: tokenSchema, value: z.union([rawNumberSchema, z.null()]), complete: z.boolean(), source: sourceSchema.optional(), }) .strict(); const filterSchema = z .object({ sourceGroups: z.array(tokenSchema).optional(), outputGroups: z.array(tokenSchema).optional(), origins: z.array(tokenSchema).optional(), originFrom: tokenSchema.optional(), originThrough: tokenSchema.optional(), valuations: z.array(tokenSchema).optional(), valuationFrom: tokenSchema.optional(), valuationThrough: tokenSchema.optional(), minDevelopmentAge: z.number().int().nonnegative().safe().optional(), maxDevelopmentAge: z.number().int().nonnegative().safe().optional(), instanceIds: z.array(tokenSchema).optional(), }) .strict(); const cutoffSchema = z .object({ sourceGroup: tokenSchema, originThrough: tokenSchema.nullable(), valuationThrough: tokenSchema.nullable(), }) .strict(); const expectedSchema = z .object({ sourceGroup: tokenSchema, origin: tokenSchema, valuation: tokenSchema, source: sourceSchema.optional(), }) .strict(); const jsonSchema: z.ZodType = z.lazy(() => z.union([ z.null(), z.boolean(), z.number().finite(), jsonStringSchema, z.array(jsonSchema), recordSchema(jsonSchema), ]), ); const policySchema = z .object({ allowedReviewStatuses: z.array(z.enum(["pass", "warning", "not-evaluated", "fail"])).optional(), allowedMetricFindingSeverities: z.array(z.enum(["info", "warning", "fail"])).optional(), rationaleRef: tokenSchema.optional(), }) .strict(); const runSchema = z .object({ definition: z.unknown(), losses: z.array(lossSchema), exposures: z.array(exposureSchema).optional(), filter: filterSchema.optional(), completePeriodCutoffs: z.array(cutoffSchema).optional(), expectedCells: z.array(expectedSchema).optional(), reviewEvidence: z.unknown().nullable().optional(), runPresetId: tokenSchema.optional(), datasetArtifactId: tokenSchema.optional(), groupMap: recordSchema(tokenSchema).optional(), groupDimensions: recordSchema(jsonSchema).optional(), policy: policySchema.optional(), }) .strict(); export type DiagnosticAllowedReviewStatus = "pass" | "warning" | "not-evaluated" | "fail"; export interface DiagnosticExecutionPolicyInput { readonly allowedReviewStatuses?: readonly DiagnosticAllowedReviewStatus[]; readonly allowedMetricFindingSeverities?: readonly ("info" | "warning" | "fail")[]; readonly rationaleRef?: string; } export interface DiagnosticRunInput { readonly definition: DiagnosticDefinition; readonly losses: readonly DiagnosticLossInput[]; readonly exposures?: readonly DiagnosticExposureObservation[]; readonly filter?: DiagnosticsFilter; readonly completePeriodCutoffs?: readonly DiagnosticCompletePeriodCutoff[]; readonly expectedCells?: readonly DiagnosticExpectedCell[]; readonly reviewEvidence?: DiagnosticReviewEvidence | null; readonly runPresetId?: string; readonly datasetArtifactId?: string; readonly groupMap?: Readonly>; readonly groupDimensions?: Readonly>; readonly policy?: DiagnosticExecutionPolicyInput; } declare const validatedDiagnosticRunInputBrand: unique symbol; export interface ValidatedDiagnosticRunInput { readonly [validatedDiagnosticRunInputBrand]: true; readonly definition: CompiledDiagnosticDefinition; readonly losses: readonly DiagnosticDeepReadonly[]; readonly exposures: readonly DiagnosticDeepReadonly[]; readonly filter: DiagnosticDeepReadonly | null; readonly completePeriodCutoffs: readonly DiagnosticCompletePeriodCutoff[]; readonly expectedCells: readonly DiagnosticExpectedCell[] | null; readonly reviewEvidence: DiagnosticDeepReadonly | null; readonly runPresetId: string | null; readonly datasetArtifactId: string | null; readonly groupMap: Readonly>; readonly groupDimensions: Readonly>; readonly policy: { readonly allowedReviewStatuses: readonly DiagnosticAllowedReviewStatus[]; 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 rationaleRef: string | null; readonly reviewGate: "passed" | "blocked"; readonly metricGate: "not-run" | "passed" | "blocked"; } export interface CompletedValidatedMetricDiagnosticsRun { readonly status: "completed"; readonly prepared: import("@actuarial-ts/core").PreparedDiagnosticData; readonly review: DiagnosticReviewReceipt; readonly result: DiagnosticDeepReadonly; readonly runPresetId: string | null; readonly datasetArtifactId: string | null; readonly groupMap: Readonly>; readonly groupDimensions: Readonly>; readonly gate: DiagnosticExecutionGateReceipt & { readonly reviewGate: "passed"; readonly metricGate: "passed"; }; } export type ValidatedMetricDiagnosticsOutcome = | CompletedValidatedMetricDiagnosticsRun | { readonly status: "blocked"; readonly stage: "review"; readonly prepared: import("@actuarial-ts/core").PreparedDiagnosticData; readonly review: DiagnosticReviewReceipt; readonly result: null; readonly runPresetId: string | null; readonly datasetArtifactId: string | null; readonly groupMap: Readonly>; readonly groupDimensions: Readonly>; readonly gate: DiagnosticExecutionGateReceipt & { readonly reviewGate: "blocked"; readonly metricGate: "not-run"; }; } | { readonly status: "blocked"; readonly stage: "metric"; readonly prepared: import("@actuarial-ts/core").PreparedDiagnosticData; readonly review: DiagnosticReviewReceipt; readonly result: DiagnosticDeepReadonly; readonly runPresetId: string | null; readonly datasetArtifactId: string | null; readonly groupMap: Readonly>; readonly groupDimensions: Readonly>; readonly gate: DiagnosticExecutionGateReceipt & { readonly reviewGate: "passed"; readonly metricGate: "blocked"; }; }; /** 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; readonly runPresetId: string | null; readonly datasetArtifactId: string | null; readonly groupMap: Readonly>; readonly groupDimensions: Readonly>; readonly gate: DiagnosticExecutionGateReceipt & { readonly reviewGate: "passed"; readonly metricGate: "passed"; }; } type CompactRunMetadata = Omit; 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; readonly gate: DiagnosticExecutionGateReceipt & { readonly reviewGate: "passed"; readonly metricGate: "blocked"; }; }); const authentic = new WeakSet(); // 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(); const compactPreparedByInput = new WeakMap< CompactValidatedDiagnosticRunInput, CompactPreparedDiagnosticData >(); declare const queryContextBrand: unique symbol; /** SDK-owned source snapshot. Cloning or serializing this handle loses authority. */ export interface DiagnosticQueryContext { readonly [queryContextBrand]: true; } /** * Omitted fields inherit the context; null clears filter/expected-cell selection. * Group maps/dimensions must match the selected scope; empty records clear them. */ export interface DiagnosticQuery { /** Per-query evidence labels; null clears the inherited label. */ readonly runPresetId?: string | null; readonly datasetArtifactId?: string | null; readonly filter?: DiagnosticsFilter | null; readonly completePeriodCutoffs?: readonly DiagnosticCompletePeriodCutoff[]; readonly expectedCells?: readonly DiagnosticExpectedCell[] | null; readonly groupMap?: Readonly>; readonly groupDimensions?: Readonly>; } const querySchema = z.object({ runPresetId: tokenSchema.nullable().optional(), datasetArtifactId: tokenSchema.nullable().optional(), filter: filterSchema.nullable().optional(), completePeriodCutoffs: z.array(cutoffSchema).optional(), expectedCells: z.array(expectedSchema).nullable().optional(), groupMap: recordSchema(tokenSchema).optional(), groupDimensions: recordSchema(jsonSchema).optional(), }).strict(); const queryContexts = new WeakMap(); const compactCompleted = new WeakSet(); // 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 >(); // Validated inputs are JSON-shaped trees (the schema copies every row), so a // shared node is a small leaf visited once per reference rather than tracked in // a table of every node. Ancestors are recorded only past this depth, which a // cycle in a caller-supplied graph must exceed before it is cut. const UNGUARDED_FREEZE_DEPTH = 64; function freeze(value: T, skip?: WeakSet): DiagnosticDeepReadonly { let ancestors: Set | undefined; const visit = (node: unknown, depth: number): void => { if (node === null || typeof node !== "object" || skip?.has(node)) return; const guarded = depth > UNGUARDED_FREEZE_DEPTH; if (guarded) { ancestors ??= new Set(); if (ancestors.has(node)) return; ancestors.add(node); } if (Array.isArray(node)) { for (let index = 0; index < node.length; index++) visit(node[index], depth + 1); } else { const record = node as Record; const keys = Object.keys(record); for (let index = 0; index < keys.length; index++) visit(record[keys[index]!], depth + 1); } if (guarded) ancestors!.delete(node); Object.freeze(node); }; visit(value, 0); return value as DiagnosticDeepReadonly; } function issues(error: z.ZodError): DiagnosticValidationError { return new DiagnosticValidationError( error.issues.map((issue) => ({ domain: (issue.path[0] === "definition" ? "definition" : issue.path[0] === "losses" || issue.path[0] === "exposures" || issue.path[0] === "reviewEvidence" ? "input" : "configuration") as "definition" | "input" | "configuration", code: issue.code === "unrecognized_keys" ? "unknown-key" : "invalid-type", path: `$${issue.path.map((part) => (typeof part === "number" ? `[${part}]` : /^[A-Za-z_$][\w$]*$/.test(part) ? `.${part}` : `[${JSON.stringify(part)}]`)).join("")}`, message: issue.message, })), ); } function codeUnit(left: string, right: string): number { return left < right ? -1 : left > right ? 1 : 0; } function sortedRecord(value: Readonly>): Readonly> { const result = diagnosticRecord(); for (const key of Object.keys(value).sort(codeUnit)) result[key] = value[key]!; return result; } interface UndefinedScanFrame { readonly value: unknown; readonly parent: UndefinedScanFrame | null; readonly key: string | null; } /** Renders the JSON path of a frame only when an issue must cite it. */ function scanFramePath(frame: UndefinedScanFrame): string { if (frame.parent === null || frame.key === null) return "$"; const parentPath = scanFramePath(frame.parent); return Array.isArray(frame.parent.value) ? `${parentPath}[${frame.key}]` : /^[A-Za-z_$][\w$]*$/.test(frame.key) ? `${parentPath}.${frame.key}` : `${parentPath}[${JSON.stringify(frame.key)}]`; } function explicitUndefinedIssues(value: unknown): DiagnosticValidationIssue[] { const found: DiagnosticValidationIssue[] = []; const stack: UndefinedScanFrame[] = [{ value, parent: null, key: null }]; const seen = new WeakSet(); while (stack.length > 0) { const current = stack.pop()!; if (current.value === null || typeof current.value !== "object" || seen.has(current.value)) continue; seen.add(current.value); const record = current.value as Record; // Large inputs are ordinary: build no path text or entry pairs on the // common path, only the frame links needed to render a path on demand. const keys = Object.keys(record); for (let index = 0; index < keys.length; index++) { const key = keys[index]!; const child = record[key]; if (child === undefined) { const path = scanFramePath({ value: child, parent: current, key }); found.push({ domain: path.startsWith("$.definition") ? "definition" : path.startsWith("$.losses") || path.startsWith("$.exposures") || path.startsWith("$.reviewEvidence") ? "input" : "configuration", code: "invalid-type", path, message: "Explicit undefined is not allowed", }); } else if (child !== null && typeof child === "object") stack.push({ value: child, parent: current, key }); } } return found; } // --------------------------------------------------------------------------- // Large-input fast path for the two row arrays. Zod validates and copies every // row through generic machinery, which on 100,000-row inputs allocates more // than the preparation itself. Rows are accepted here only under exactly the // schema's rules (plain records, strict keys, token strings, boolean flags, // safe non-negative integer source rows, raw number-or-null measures) and are // copied in the schema's key order, so the owned rows are indistinguishable // from the schema's output. Anything the check does not accept, including any // non-plain prototype, is handed to the schema unchanged, so every rejection // and every error message still comes from zod. type FastLossRow = z.output; type FastExposureRow = z.output; const isPlainRecord = (value: unknown): value is Record => { if (value === null || typeof value !== "object" || Array.isArray(value)) return false; const prototype: unknown = Object.getPrototypeOf(value); return prototype === Object.prototype || prototype === null; }; const hasOwn = (value: object, key: string): boolean => Object.prototype.hasOwnProperty.call(value, key); function fastSource(value: unknown): z.output | undefined { if (!isPlainRecord(value)) return undefined; const artifactId = value.artifactId; if (!isDiagnosticToken(artifactId)) return undefined; const out: Record = { artifactId }; let matched = 1; for (const field of ["sourceFile", "sourceSheet"] as const) if (hasOwn(value, field)) { const item = value[field]; if (!isDiagnosticToken(item)) return undefined; out[field] = item; matched++; } if (hasOwn(value, "sourceRow")) { const item = value.sourceRow; if (typeof item !== "number" || !Number.isSafeInteger(item) || item < 0) return undefined; out.sourceRow = item; matched++; } if (hasOwn(value, "sourceCell")) { const item = value.sourceCell; if (!isDiagnosticToken(item)) return undefined; out.sourceCell = item; matched++; } if (Object.keys(value).length !== matched) return undefined; return out as z.output; } function fastMeasures(value: unknown): Record | undefined { if (!isPlainRecord(value)) return undefined; const out: Record = {}; const keys = Object.keys(value); for (let index = 0; index < keys.length; index++) { const key = keys[index]!; const item = value[key]; if (item !== null && typeof item !== "number") return undefined; // The schema's key round trip keeps a literal "__proto__" as own data. if (key === "__proto__") Object.defineProperty(out, key, { value: item, enumerable: true, writable: true, configurable: true }); else out[key] = item; } return out; } function fastLossRow(value: unknown): FastLossRow | undefined { if (!isPlainRecord(value)) return undefined; const { recordId, sourceGroup, origin, valuation, complete, rowType } = value; if ( !isDiagnosticToken(recordId) || !isDiagnosticToken(sourceGroup) || !isDiagnosticToken(origin) || !isDiagnosticToken(valuation) || typeof complete !== "boolean" ) return undefined; const out: Record = { recordId, sourceGroup, origin, valuation, complete }; let expected = 7; if (hasOwn(value, "source")) { const source = fastSource(value.source); if (source === undefined) return undefined; out.source = source; expected++; } const measures = fastMeasures(value.measures); if (measures === undefined) return undefined; out.measures = measures; if (rowType === "claim") { const claimId = value.claimId; if (!hasOwn(value, "claimId") || !isDiagnosticToken(claimId)) return undefined; out.rowType = "claim"; out.claimId = claimId; expected++; } else if (rowType === "aggregate") out.rowType = "aggregate"; else return undefined; if (Object.keys(value).length !== expected) return undefined; return out as FastLossRow; } function fastExposureRow(value: unknown): FastExposureRow | undefined { if (!isPlainRecord(value)) return undefined; const { key, sourceGroup, origin, measureId, complete } = value; const measure = value.value; if ( !isDiagnosticToken(key) || !isDiagnosticToken(sourceGroup) || !isDiagnosticToken(origin) || !isDiagnosticToken(measureId) || (measure !== null && typeof measure !== "number") || typeof complete !== "boolean" ) return undefined; const out: Record = { key, sourceGroup, origin }; let expected = 6; if (hasOwn(value, "valuation")) { const valuation = value.valuation; if (!isDiagnosticToken(valuation)) return undefined; out.valuation = valuation; expected++; } out.measureId = measureId; out.value = measure; out.complete = complete; if (hasOwn(value, "source")) { const source = fastSource(value.source); if (source === undefined) return undefined; out.source = source; expected++; } if (Object.keys(value).length !== expected) return undefined; return out as FastExposureRow; } /** * Validates and copies the row arrays directly when every row is schema-shaped. * Returns the owned rows plus a shell of the input with empty row arrays for * the schema to validate everything else; undefined defers the whole input. */ function fastSourceRows( value: unknown, ): { shell: Record; losses: FastLossRow[]; exposures: FastExposureRow[] | undefined } | undefined { if (!isPlainRecord(value) || !Array.isArray(value.losses)) return undefined; const losses: FastLossRow[] = []; for (let index = 0; index < value.losses.length; index++) { const row = fastLossRow(value.losses[index]); if (row === undefined) return undefined; losses.push(row); } let exposures: FastExposureRow[] | undefined; if (hasOwn(value, "exposures")) { if (!Array.isArray(value.exposures)) return undefined; exposures = []; for (let index = 0; index < value.exposures.length; index++) { const row = fastExposureRow(value.exposures[index]); if (row === undefined) return undefined; exposures.push(row); } } return { shell: { ...value, losses: [], ...(exposures === undefined ? {} : { exposures: [] }) }, losses, exposures, }; } // Both public gateways share the same full validation/ownership boundary. // Selecting compact storage never invokes the eager preparation first. function validateRunInputContent(value: unknown): DiagnosticRunInputContent { // A row the fast check accepts holds no explicit undefined anywhere: every // field it reads must be a token, boolean, or number-or-null, and any other // value (including undefined) makes it decline the whole input. So when it // accepts, scanning its row-free shell reports exactly the same issues. const fast = fastSourceRows(value); const undefinedIssues = explicitUndefinedIssues(fast === undefined ? value : fast.shell); if (undefinedIssues.length > 0) throw new DiagnosticValidationError(undefinedIssues); const parsed = runSchema.safeParse(fast === undefined ? value : fast.shell); if (!parsed.success) throw issues(parsed.error); const losses = fast === undefined ? parsed.data.losses : fast.losses; const exposures = (fast === undefined ? parsed.data.exposures : fast.exposures) ?? []; const definition = compileDiagnosticDefinition(parsed.data.definition as DiagnosticDefinition); const relationIssues: DiagnosticValidationIssue[] = 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 exposures.entries()) { 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", path: `$.exposures[${index}].valuation`, 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"]; const rationale = parsed.data.policy?.rationaleRef ?? null; if ((review.includes("fail") || metric.includes("fail")) && rationale === null) throw new DiagnosticValidationError([ { domain: "configuration", code: "missing-required", path: "$.policy.rationaleRef", message: "A rationale is required when fail outcomes are allowed", }, ]); const reviewEvidence = parsed.data.reviewEvidence === undefined || parsed.data.reviewEvidence === null ? null : validateDiagnosticReviewEvidence(parsed.data.reviewEvidence, "$.reviewEvidence"); const reviewOrder: readonly DiagnosticAllowedReviewStatus[] = [ "pass", "warning", "not-evaluated", "fail", ]; const metricOrder: readonly ("info" | "warning" | "fail")[] = ["info", "warning", "fail"]; for (const key of [ ...Object.keys(parsed.data.groupMap ?? {}), ...Object.keys(parsed.data.groupDimensions ?? {}), ]) if (!isDiagnosticToken(key)) throw new DiagnosticValidationError([ { 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", }, ]); const result = freeze({ definition, losses, exposures, filter: parsed.data.filter ?? null, completePeriodCutoffs: parsed.data.completePeriodCutoffs ?? [], expectedCells: parsed.data.expectedCells ?? null, reviewEvidence, runPresetId: parsed.data.runPresetId ?? null, datasetArtifactId: parsed.data.datasetArtifactId ?? null, groupMap: sortedRecord(parsed.data.groupMap ?? diagnosticRecord()), groupDimensions: sortedRecord( parsed.data.groupDimensions ?? diagnosticRecord(), ), policy: { allowedReviewStatuses: reviewOrder.filter((status) => review.includes(status)), allowedMetricFindingSeverities: metricOrder.filter((severity) => metric.includes(severity)), rationaleRef: rationale, }, }); 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 { return ownEagerDiagnosticInput(validateRunInputContent(value)); } function ownEagerDiagnosticInput(content: DiagnosticRunInputContent): ValidatedDiagnosticRunInput { const result = content 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 { return ownCompactDiagnosticInput(validateRunInputContent(value)); } function ownCompactDiagnosticInput(content: DiagnosticRunInputContent): CompactValidatedDiagnosticRunInput { const result = content as CompactValidatedDiagnosticRunInput; const prepared = prepareDiagnosticDataCompact(preparationInput(result)); validateCompactDiagnosticGroupingConfiguration({ prepared, groupMap: result.groupMap, groupDimensions: result.groupDimensions, }); compactPreparedByInput.set(result, prepared); return result; } /** * Own and validate source rows and compile the definition once. Queries keep the * definition, execution policy, source order and review evidence fixed. * Metric selections and eligible clean aggregate source/origin/date/age queries * share prepared cells; ineligible inputs still perform full core preparation. * Source/origin queries reuse invariant owned review evidence. Date/age queries * reuse cell-local checks but recompute monotonic comparisons and controls. Every * query enforces review and metric gates, including unchanged evidence validation. */ export function createDiagnosticQueryContext(value: unknown): DiagnosticQueryContext { const validated = validateDiagnosticRunInputCompact(value); const handle = Object.freeze({}) as DiagnosticQueryContext; queryContexts.set(handle, validated); return handle; } /** Create an authentic per-query input without cloning/reparsing owned source rows. */ export function validateDiagnosticQueryCompact( context: DiagnosticQueryContext, query: unknown = {}, ): CompactValidatedDiagnosticRunInput { const base = queryContexts.get(context); if (!base) throw new DiagnosticValidationError([{ domain: "input", code: "invalid-input-relationship", path: "$", message: "Value is not an authentic diagnostic query context", }]); const undefinedIssues = explicitUndefinedIssues(query); if (undefinedIssues.length) throw new DiagnosticValidationError(undefinedIssues); const parsed = querySchema.safeParse(query); if (!parsed.success) throw issues(parsed.error); if (Object.keys(parsed.data).length === 0) return base; const ownedQuery = freeze({ ...parsed.data, ...(parsed.data.groupMap === undefined ? {} : { groupMap: sortedRecord(parsed.data.groupMap) }), ...(parsed.data.groupDimensions === undefined ? {} : { groupDimensions: sortedRecord(parsed.data.groupDimensions) }), }); // Only the new query fields require freezing. Every inherited graph belongs // to the authentic validated base; never trust caller Object.freeze markers. const result = Object.freeze({ ...base, ...ownedQuery }) as CompactValidatedDiagnosticRunInput; const projected = Object.keys(ownedQuery).every((key) => ["filter", "groupMap", "groupDimensions", "runPresetId", "datasetArtifactId"].includes(key)) ? reselectCompactDiagnosticMetrics(compactPreparedByInput.get(base)!, result.filter ?? undefined) ?? selectCompactDiagnosticSourceGroups(compactPreparedByInput.get(base)!, result.filter ?? undefined) ?? selectCompactDiagnosticOrigins(compactPreparedByInput.get(base)!, result.filter ?? undefined) ?? selectCompactDiagnosticCoordinates(compactPreparedByInput.get(base)!, result.filter ?? undefined) : undefined; const prepared = projected ?? prepareDiagnosticDataCompact(preparationInput(result)); validateCompactDiagnosticGroupingConfiguration({ prepared, groupMap: result.groupMap, groupDimensions: result.groupDimensions, }); compactPreparedByInput.set(result, prepared); return result; } /** Execute all review and metric gates for this scope, even if another scope passed. */ export function runDiagnosticQueryCompact( context: DiagnosticQueryContext, query: DiagnosticQuery = {}, ): CompactMetricDiagnosticsOutcome { return runValidatedMetricDiagnosticsCompact(validateDiagnosticQueryCompact(context, query)); } 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 { if (value === null || typeof value !== "object" || !authentic.has(value)) throw new DiagnosticValidationError([ { domain: "input", code: "invalid-input-relationship", path: "$", message: "Value is not an authentic validated diagnostic run input", }, ]); } const completed = new WeakSet(); export function runValidatedMetricDiagnostics( input: ValidatedDiagnosticRunInput, ): ValidatedMetricDiagnosticsOutcome { assertValidatedDiagnosticRunInput(input); // 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, groupDimensions: input.groupDimensions, }); const review = reviewPreparedDiagnosticData({ prepared, evidence: input.reviewEvidence as DiagnosticReviewEvidence | null, }); const evaluationStatus = ( evaluation: DiagnosticReviewReceipt["evaluations"][number], ): DiagnosticAllowedReviewStatus => evaluation.expressionOverflows.length > 0 ? "fail" : evaluation.status === "not-evaluated" ? "not-evaluated" : evaluation.status === "triggered" ? evaluation.severity : "pass"; const disallowedReview = review.report.checks.some( (check) => !input.policy.allowedReviewStatuses.includes(check.status), ) || review.evaluations.some( (evaluation) => !input.policy.allowedReviewStatuses.includes(evaluationStatus(evaluation)), ); const base = { prepared, review, runPresetId: input.runPresetId, datasetArtifactId: input.datasetArtifactId, 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([prepared, review]); const freezeOutcome = (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, }, }) as ValidatedMetricDiagnosticsOutcome; const result = runMetricDiagnostics({ 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, }, }) as ValidatedMetricDiagnosticsOutcome; const outcome = freezeOutcome({ ...base, status: "completed" as const, result, gate: { ...input.policy, reviewGate: "passed" as const, metricGate: "passed" as const, }, }) as unknown as CompletedValidatedMetricDiagnosticsRun; completed.add(outcome); return outcome; } export function assertCompletedValidatedMetricDiagnosticsRun( value: unknown, ): asserts value is CompletedValidatedMetricDiagnosticsRun { if (value === null || typeof value !== "object" || !completed.has(value)) throw new DiagnosticValidationError([ { domain: "input", code: "invalid-input-relationship", path: "$", message: "Value is not an authentic completed diagnostic run", }, ]); } /** 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> = { 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([prepared, review]); const freezeOutcome = (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)!; } function boundedDiagnosticPreparation(value: unknown, storage: "eager"): { input: ValidatedDiagnosticRunInput; preflight: DiagnosticExecutionPreflight }; function boundedDiagnosticPreparation(value: unknown, storage: "compact"): { input: CompactValidatedDiagnosticRunInput; preflight: DiagnosticExecutionPreflight }; function boundedDiagnosticPreparation(value: unknown, storage: "eager" | "compact"): { input: ValidatedDiagnosticRunInput | CompactValidatedDiagnosticRunInput; preflight: DiagnosticExecutionPreflight } { const request = parseDiagnosticExecutionRequest(value); let input: ValidatedDiagnosticRunInput | CompactValidatedDiagnosticRunInput; let inputRows: number, preparationPositionUpperBound: number; try { const content = validateRunInputContent(request.source); inputRows = content.losses.length + content.exposures.length + (content.expectedCells?.length ?? 0); // Reject large row/measure products before native preparation expands cell // statistics or eager identity. This is an expansion bound, not a work timer. preparationPositionUpperBound = inputRows * content.definition.definition.measures.length; if (!Number.isSafeInteger(preparationPositionUpperBound) || preparationPositionUpperBound > request.limits.maximumPreparationPositions) diagnosticExecutionLimit("$.limits.maximumPreparationPositions", "Raw record/declared-measure positions exceed the preparation expansion budget"); input = storage === "eager" ? ownEagerDiagnosticInput(content) : ownCompactDiagnosticInput(content); } catch (error) { if (!(error instanceof DiagnosticValidationError)) throw error; throw new AnalysisReviewError(error.issues.map((issue) => ({ code: issue.code, message: issue.message, path: `$.source${issue.domain === "definition" ? ".definition" : ""}${issue.path.startsWith("$") ? issue.path.slice(1) : issue.path.startsWith("input") ? issue.path.slice(5) : `.${issue.path}`}`, remedies: ["Resolve the native diagnostic definition, source row, filter or policy at the indicated coordinate"] }))); } const prepared = storage === "eager" ? preparedByInput.get(input as ValidatedDiagnosticRunInput)! : compactPreparedByInput.get(input as CompactValidatedDiagnosticRunInput)!; if (prepared.cells.length > request.limits.maximumPreparedCells) diagnosticExecutionLimit("$.limits.maximumPreparedCells", "Native preparation exceeds the declared cell budget"); // Ignore output-group filters when bounding dense grid positions. They can // only remove groups. No row or metric is dropped to make a budget pass. const groups = new Map; ages: Set }>(); for (const cell of prepared.cells) { const group = Object.hasOwn(input.groupMap, cell.sourceGroup) ? input.groupMap[cell.sourceGroup]! : cell.sourceGroup; let dimensions = groups.get(group); if (!dimensions) { dimensions = { origins: new Set(), ages: new Set() }; groups.set(group, dimensions); } dimensions.origins.add(cell.origin); dimensions.ages.add(cell.developmentAge); } const instances = input.definition.definition.instances.filter((instance) => input.filter?.instanceIds === undefined || input.filter.instanceIds.includes(instance.id)); const metricPositionUpperBound = [...groups.values()].reduce((sum, group) => sum + group.origins.size * group.ages.size * instances.length, 0); const reviewEvaluationUpperBound = Math.max(1, prepared.cells.length + prepared.expectedCells.length) * input.definition.definition.reviewRules.length; if (!Number.isSafeInteger(metricPositionUpperBound) || metricPositionUpperBound > request.limits.maximumMetricPositions) diagnosticExecutionLimit("$.limits.maximumMetricPositions", "Potential dense metric grid positions exceed the declared budget"); if (!Number.isSafeInteger(reviewEvaluationUpperBound) || reviewEvaluationUpperBound > request.limits.maximumReviewEvaluationPositions) diagnosticExecutionLimit("$.limits.maximumReviewEvaluationPositions", "Authored review-rule evaluation positions exceed the declared budget"); const findings: AnalysisReviewFinding[] = prepared.findings.map((finding, index) => ({ code: finding.code, path: "$.source", message: finding.message, coordinates: { severity: finding.severity, category: finding.category, nativeOutputPath: `$.prepared.findings[${index}]`, ...Object.fromEntries(["sourceGroup", "origin", "valuation", "developmentAge", "measureId", "instanceId"].flatMap((key) => { const value = (finding as unknown as Record)[key]; return typeof value === "string" || typeof value === "number" ? [[key, value]] : []; })) }, remedies: ["Inspect the retained native preparation finding and source evidence before interpreting metrics"] })); if (prepared.cells.length === 0) findings.push({ code: "NO_DIAGNOSTIC_SOURCE_CELLS", path: "$.source", message: "No native source cells remain after preparation and selection; no empty review is certified as complete", remedies: ["Supply eligible observations or inspect the explicit filters and structural exclusions"] }); return { input, preflight: snapshotDiagnosticJson({ storage, work: { inputRows, preparationPositionUpperBound, preparedCells: prepared.cells.length, metricPositionUpperBound, reviewEvaluationUpperBound }, policy: input.policy, findings, assurance: "prepared-input-only" as const }) }; } /** Prepares eager inputs and bounds native expansion; does not run review/metric gates. */ export function validateDiagnosticExecutionRequest(value: unknown): DiagnosticExecutionPreflight { return boundedDiagnosticPreparation(value, "eager").preflight; } /** Prepares compact inputs without materializing preparation identity or review evidence. */ export function validateCompactDiagnosticExecutionRequest(value: unknown): DiagnosticExecutionPreflight { return boundedDiagnosticPreparation(value, "compact").preflight; } /** Returns the original native outcome; completed-run authority survives this gateway. */ export function runMetricDiagnosticsFromInput(value: unknown): ValidatedMetricDiagnosticsOutcome { return runValidatedMetricDiagnostics(boundedDiagnosticPreparation(value, "eager").input); } /** Returns the original compact outcome and its opaque stores; JSON copies lose authority. */ export function runMetricDiagnosticsCompactFromInput(value: unknown): CompactMetricDiagnosticsOutcome { return runValidatedMetricDiagnosticsCompact(boundedDiagnosticPreparation(value, "compact").input); }