@actuarial-ts/data 0.6.0 → 0.7.0

package/dist/diagnosticPreparedReview.js

@@ -1,58 +1,769 @@
-import { canonicalJson, evaluateDiagnosticReviewRules, fnv1a64 } from "@actuarial-ts/core";
-import { createNotEvaluatedDataCheck, createStructuredDataCheck, summarizeDataChecks } from "./review.js";
+import { DiagnosticValidationError, diagnosticJsonPreflight, isDiagnosticToken, assertPreparedDiagnosticData, assertCompactPreparedDiagnosticData, evaluateDiagnosticReviewRulesCompact, getDiagnosticReviewEvaluation, getDiagnosticReviewEvaluationSummary, getCompactDiagnosticReviewEvaluationsIdentityDocument, getCompactPreparedDiagnosticDataFingerprint, createDiagnosticIdentityArray, createDiagnosticIdentityObject, createDiagnosticIdentityValue, fingerprintDiagnosticIdentity, canonicalJson, evaluateDiagnosticReviewRules, fnv1a64, compareDiagnosticSourceLocations, compareDiagnosticIdentityValues, normalizeDiagnosticSourceLocations, projectDiagnosticIdentity, } from "@actuarial-ts/core";
+import { CompactDiagnosticJson } from "./compactDiagnosticJson.js";
+import { z } from "zod";
+import { createNotEvaluatedDataCheck, createStructuredDataCheck, summarizeDataChecks, } from "./review.js";
 const fixed = [
     ["diagnostic/structural/loss-identity", "Loss identities are unique", "fail"],
-    ["diagnostic/structural/exposure-identity", "Exposure identities are coherent", "fail"],
+    [
+        "diagnostic/structural/exposure-identity",
+        "Exposure identities are coherent",
+        "fail",
+    ],
     ["diagnostic/structural/period-validity", "Periods are valid", "fail"],
-    ["diagnostic/structural/measure-contract", "Measure keys match their declared sources", "fail"],
-    ["diagnostic/structural/loss-completeness", "Loss records are complete", "fail"],
-    ["diagnostic/structural/exposure-completeness", "Exposure records are complete and finite", "fail"],
-    ["diagnostic/structural/loss-without-exposure", "Loss cells have required exposure", "warning"],
-    ["diagnostic/structural/exposure-without-loss", "Exposures attach to retained loss cells", "warning"],
-    ["diagnostic/structural/expected-cell-coverage", "Expected cells are present", "fail"],
-    ["diagnostic/structural/grouping-consistency", "Grouping assignments are consistent", "fail"],
-    ["diagnostic/structural/cached-formula-provenance", "Cached formulas retain provenance", "warning"],
+    [
+        "diagnostic/structural/measure-contract",
+        "Measure keys match their declared sources",
+        "fail",
+    ],
+    [
+        "diagnostic/structural/loss-completeness",
+        "Loss records are complete",
+        "fail",
+    ],
+    [
+        "diagnostic/structural/exposure-completeness",
+        "Exposure records are complete and finite",
+        "fail",
+    ],
+    [
+        "diagnostic/structural/loss-without-exposure",
+        "Loss cells have required exposure",
+        "warning",
+    ],
+    [
+        "diagnostic/structural/exposure-without-loss",
+        "Exposures attach to retained loss cells",
+        "warning",
+    ],
+    [
+        "diagnostic/structural/expected-cell-coverage",
+        "Expected cells are present",
+        "fail",
+    ],
+    [
+        "diagnostic/structural/grouping-consistency",
+        "Grouping assignments are consistent",
+        "fail",
+    ],
+    [
+        "diagnostic/structural/cached-formula-provenance",
+        "Cached formulas retain provenance",
+        "warning",
+    ],
 ];
-const codeToCheck = { "duplicate-loss-record-id": fixed[0][0], "duplicate-claim-snapshot": fixed[0][0], "claim-identity-conflict": fixed[0][0], "duplicate-aggregate-snapshot": fixed[0][0], "duplicate-exposure-identity": fixed[1][0], "conflicting-exposure-identity": fixed[1][0], "unknown-origin-period": fixed[2][0], "unknown-valuation-period": fixed[2][0], "valuation-before-origin": fixed[2][0], "unsafe-development-age": fixed[2][0], "undeclared-loss-measure": fixed[3][0], "wrong-source-loss-measure": fixed[3][0], "undeclared-exposure-measure": fixed[3][0], "wrong-source-exposure-measure": fixed[3][0], "incomplete-loss-record": fixed[4][0], "missing-exposure-value": fixed[5][0], "incomplete-exposure": fixed[5][0], "non-finite-exposure": fixed[5][0], "loss-without-exposure": fixed[6][0], "exposure-without-loss": fixed[7][0], "missing-expected-cell": fixed[8][0] };
-function freeze(value) { if (value && typeof value === "object") {
+const codeToCheck = {
+    "duplicate-loss-record-id": fixed[0][0],
+    "duplicate-claim-snapshot": fixed[0][0],
+    "claim-identity-conflict": fixed[0][0],
+    "duplicate-aggregate-snapshot": fixed[0][0],
+    "duplicate-exposure-identity": fixed[1][0],
+    "conflicting-exposure-identity": fixed[1][0],
+    "unknown-origin-period": fixed[2][0],
+    "unknown-valuation-period": fixed[2][0],
+    "valuation-before-origin": fixed[2][0],
+    "unsafe-development-age": fixed[2][0],
+    "undeclared-loss-measure": fixed[3][0],
+    "wrong-source-loss-measure": fixed[3][0],
+    "undeclared-exposure-measure": fixed[3][0],
+    "wrong-source-exposure-measure": fixed[3][0],
+    "incomplete-loss-record": fixed[4][0],
+    "missing-exposure-value": fixed[5][0],
+    "incomplete-exposure": fixed[5][0],
+    "non-finite-exposure": fixed[5][0],
+    "loss-without-exposure": fixed[6][0],
+    "exposure-without-loss": fixed[7][0],
+    "missing-expected-cell": fixed[8][0],
+};
+const sourceSchema = z
+    .object({
+    artifactId: z.string().min(1),
+    sourceFile: z.string().min(1).optional(),
+    sourceSheet: z.string().min(1).optional(),
+    sourceRow: z.number().int().nonnegative().optional(),
+    sourceCell: z.string().min(1).optional(),
+})
+    .strict();
+const evidenceSchema = z
+    .object({
+    groupingAssignments: z.array(z
+        .object({
+        key: z.string().min(1),
+        group: z.string().min(1),
+        source: sourceSchema.optional(),
+    })
+        .strict()),
+    cachedFormulas: z.array(z
+        .object({
+        id: z.string().min(1),
+        source: sourceSchema.optional(),
+        formula: z
+            .string()
+            .min(1)
+            .refine((value) => value.trim().length > 0, "Formula must contain non-whitespace text")
+            .optional(),
+        cachedValue: z.number().finite().nullable().optional(),
+        declaredFormulaSource: z.boolean(),
+    })
+        .strict()),
+})
+    .strict();
+function freeze(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== "object" || seen.has(value))
+        return value;
+    seen.add(value);
     for (const child of Object.values(value))
-        freeze(child);
-    Object.freeze(value);
-} return value; }
-export function reviewPreparedDiagnosticData(input) {
-    // Authenticity is enforced by the core evaluator before evidence can affect a receipt.
-    const evaluations = evaluateDiagnosticReviewRules(input.prepared);
-    const evidence = input.evidence === null ? null : freeze(structuredClone(input.evidence));
+        freeze(child, seen);
+    return Object.freeze(value);
+}
+function issuePath(root, path) {
+    return `${root}${path.map((part) => (typeof part === "number" ? `[${part}]` : /^[A-Za-z_$][\w$]*$/.test(String(part)) ? `.${String(part)}` : `[${JSON.stringify(String(part))}]`)).join("")}`;
+}
+function compareOptional(left, right, compare) {
+    if (left === undefined)
+        return right === undefined ? 0 : -1;
+    if (right === undefined)
+        return 1;
+    return compare(left, right);
+}
+function compareSourceArrays(left, right) {
+    for (let index = 0; index < Math.min(left.length, right.length); index++) {
+        const compared = compareDiagnosticSourceLocations(left[index], right[index]);
+        if (compared !== 0)
+            return compared;
+    }
+    return left.length - right.length;
+}
+function findingMergeSkeleton(finding) {
+    const context = finding.context;
+    const reviewScope = context?.reviewScope;
+    return {
+        ...finding,
+        ...(context === undefined
+            ? {}
+            : {
+                context: {
+                    ...context,
+                    sources: [],
+                    ...(reviewScope === undefined
+                        ? {}
+                        : { reviewScope: { ...reviewScope, sources: [] } }),
+                },
+            }),
+    };
+}
+function findingMergeKey(finding) {
+    return canonicalJson(findingMergeSkeleton(finding));
+}
+function normalizeDataFindings(values) {
+    const merged = new Map();
+    for (const finding of values) {
+        const context = finding.context;
+        const reviewScope = context?.reviewScope;
+        const key = findingMergeKey(finding);
+        const previous = merged.get(key);
+        const previousContext = previous?.context;
+        const normalizedContext = context === undefined
+            ? undefined
+            : {
+                ...context,
+                ...(context.sources === undefined &&
+                    previousContext?.sources === undefined
+                    ? {}
+                    : {
+                        sources: normalizeDiagnosticSourceLocations([
+                            ...(previousContext?.sources ?? []),
+                            ...(context.sources ?? []),
+                        ]),
+                    }),
+                ...(reviewScope === undefined
+                    ? {}
+                    : {
+                        reviewScope: {
+                            ...reviewScope,
+                            sources: normalizeDiagnosticSourceLocations([
+                                ...(previousContext?.reviewScope?.sources ?? []),
+                                ...reviewScope.sources,
+                            ]),
+                        },
+                    }),
+            };
+        merged.set(key, {
+            ...finding,
+            ...(normalizedContext === undefined
+                ? {}
+                : { context: normalizedContext }),
+        });
+    }
+    return [...merged.values()].sort(compareDataFindings);
+}
+function compareDataFindings(left, right) {
+    const text = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+    const field = (finding, key) => finding.context?.[key];
+    const textField = (left, right, key) => compareOptional(field(left, key), field(right, key), text);
+    return (text(left.code, right.code) ||
+        textField(left, right, "ruleId") ||
+        textField(left, right, "measureId") ||
+        textField(left, right, "offendingKey") ||
+        textField(left, right, "groupingKey") ||
+        textField(left, right, "cachedEvidenceId") ||
+        textField(left, right, "sourceGroup") ||
+        textField(left, right, "group") ||
+        textField(left, right, "origin") ||
+        textField(left, right, "valuation") ||
+        compareOptional(field(left, "developmentAge"), field(right, "developmentAge"), (a, b) => a - b) ||
+        textField(left, right, "ageUnit") ||
+        textField(left, right, "recordId") ||
+        textField(left, right, "claimId") ||
+        textField(left, right, "exposureKey") ||
+        text(canonicalJson(left.context?.reviewScope === undefined
+            ? null
+            : { ...left.context.reviewScope, sources: [] }), canonicalJson(right.context?.reviewScope === undefined
+            ? null
+            : { ...right.context.reviewScope, sources: [] })) ||
+        textField(left, right, "sourceFile") ||
+        compareOptional(field(left, "sourceRow"), field(right, "sourceRow"), (a, b) => a - b) ||
+        text(left.message, right.message) ||
+        compareSourceArrays(left.context?.sources ?? [], right.context?.sources ?? []));
+}
+export function validateDiagnosticReviewEvidence(value, root = "$.evidence") {
+    const undefinedPaths = [];
+    const stack = [
+        { value, path: root },
+    ];
+    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);
+        for (const [key, child] of Object.entries(current.value)) {
+            const path = Array.isArray(current.value)
+                ? `${current.path}[${key}]`
+                : issuePath(current.path, [key]);
+            if (child === undefined)
+                undefinedPaths.push(path);
+            else
+                stack.push({ value: child, path });
+        }
+    }
+    if (undefinedPaths.length > 0)
+        throw new DiagnosticValidationError(undefinedPaths.sort().map((path) => ({
+            domain: "input",
+            code: "invalid-type",
+            path,
+            message: "Explicit undefined is not allowed",
+        })));
+    const parsed = evidenceSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new DiagnosticValidationError(parsed.error.issues.map((issue) => ({
+            domain: "input",
+            code: issue.code === "unrecognized_keys"
+                ? "unknown-key"
+                : issue.code === "too_small"
+                    ? "invalid-string"
+                    : "invalid-type",
+            path: issuePath(root, issue.path),
+            message: issue.message,
+        })));
+    }
+    const codeUnit = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+    parsed.data.groupingAssignments.sort((left, right) => codeUnit(left.key, right.key) ||
+        codeUnit(left.group, right.group) ||
+        compareOptional(left.source, right.source, compareDiagnosticSourceLocations));
+    parsed.data.cachedFormulas.sort((left, right) => codeUnit(left.id, right.id) ||
+        compareOptional(left.source, right.source, compareDiagnosticSourceLocations) ||
+        compareDiagnosticIdentityValues([left.formula, left.cachedValue, left.declaredFormulaSource], [right.formula, right.cachedValue, right.declaredFormulaSource]));
+    return freeze(parsed.data);
+}
+function findingContext(finding) {
+    return {
+        ...(finding.ruleId === undefined ? {} : { ruleId: finding.ruleId }),
+        ...(finding.measureId === undefined
+            ? {}
+            : { measureId: finding.measureId }),
+        ...(finding.expressionPath === undefined
+            ? {}
+            : { expressionPath: finding.expressionPath }),
+        ...(finding.offendingKey === undefined
+            ? {}
+            : { offendingKey: finding.offendingKey }),
+        ...(finding.sourceGroup === undefined
+            ? {}
+            : { sourceGroup: finding.sourceGroup }),
+        ...(finding.group === undefined ? {} : { group: finding.group }),
+        ...(finding.origin === undefined ? {} : { origin: finding.origin }),
+        ...(finding.valuation === undefined
+            ? {}
+            : { valuation: finding.valuation }),
+        ...(finding.developmentAge === undefined
+            ? {}
+            : { developmentAge: finding.developmentAge }),
+        ...(finding.ageUnit === undefined ? {} : { ageUnit: finding.ageUnit }),
+        ...(finding.recordId === undefined ? {} : { recordId: finding.recordId }),
+        ...(finding.claimId === undefined ? {} : { claimId: finding.claimId }),
+        ...(finding.exposureKey === undefined
+            ? {}
+            : { exposureKey: finding.exposureKey }),
+        sources: finding.sources,
+    };
+}
+function structuralChecks(prepared, evidence) {
     const findingsByCheck = new Map(fixed.map(([id]) => [id, []]));
-    for (const finding of input.prepared.findings) {
+    for (const finding of prepared.findings) {
         const id = codeToCheck[finding.code];
         if (id)
-            findingsByCheck.get(id).push({ code: finding.code, message: finding.message, context: { measureId: finding.measureId, sourceGroup: finding.sourceGroup, origin: finding.origin, valuation: finding.valuation, developmentAge: finding.developmentAge, ageUnit: finding.ageUnit, sources: finding.sources } });
+            findingsByCheck.get(id).push({
+                code: finding.code,
+                message: finding.message,
+                context: findingContext(finding),
+            });
     }
     if (evidence) {
         const assignments = new Map();
         for (const item of evidence.groupingAssignments) {
-            const values = assignments.get(item.key) ?? new Set();
-            values.add(item.group);
+            const values = assignments.get(item.key) ?? [];
+            values.push(item);
             assignments.set(item.key, values);
         }
-        for (const [key, groups] of assignments)
-            if (groups.size > 1)
-                findingsByCheck.get(fixed[9][0]).push({ code: "inconsistent-group-mapping", message: "Grouping evidence assigns one key to multiple groups", context: { groupingKey: key, sources: [] } });
-        for (const item of evidence.cachedFormulas)
-            if (item.declaredFormulaSource && (item.formula === undefined || item.formula.length === 0 || item.cachedValue === undefined || item.source === undefined))
-                findingsByCheck.get(fixed[10][0]).push({ code: "cached-formula-provenance", message: "Declared formula-derived value lacks complete formula provenance", context: { cachedEvidenceId: item.id, sources: item.source ? [item.source] : [] } });
-    }
-    const checks = fixed.map(([id, description, severity], index) => { if ((index === 9 || index === 10) && evidence === null)
-        return createNotEvaluatedDataCheck(id, description, "review evidence was omitted"); return createStructuredDataCheck(id, description, severity, findingsByCheck.get(id)); });
+        for (const [key, values] of assignments) {
+            if (new Set(values.map((item) => item.group)).size > 1)
+                findingsByCheck.get(fixed[9][0]).push({
+                    code: "inconsistent-group-mapping",
+                    message: "Grouping evidence assigns one key to multiple groups",
+                    context: {
+                        groupingKey: key,
+                        sources: normalizeDiagnosticSourceLocations(values.map((item) => item.source)),
+                    },
+                });
+        }
+        const failingCached = new Map();
+        for (const item of evidence.cachedFormulas) {
+            const hasOwnCachedValue = Object.prototype.hasOwnProperty.call(item, "cachedValue");
+            if (item.declaredFormulaSource &&
+                (item.formula === undefined ||
+                    !hasOwnCachedValue ||
+                    item.cachedValue === null ||
+                    item.source === undefined)) {
+                const values = failingCached.get(item.id) ?? [];
+                values.push(item);
+                failingCached.set(item.id, values);
+            }
+        }
+        for (const [id, values] of failingCached)
+            findingsByCheck.get(fixed[10][0]).push({
+                code: "cached-formula-provenance",
+                message: "Declared formula-derived value lacks complete formula provenance",
+                context: {
+                    cachedEvidenceId: id,
+                    sources: normalizeDiagnosticSourceLocations(values.map((item) => item.source)),
+                },
+            });
+    }
+    const hasExposureMeasures = prepared.definition.definition.measures.some((measure) => measure.source === "exposure");
+    const checks = fixed.map(([id, description, severity], index) => {
+        if ([1, 5, 6, 7].includes(index) && !hasExposureMeasures)
+            return createNotEvaluatedDataCheck(id, description, "the definition declares no exposure measures");
+        if (index === 8 && !prepared.expectedCellsProvided)
+            return createNotEvaluatedDataCheck(id, description, "the expected-cell grid was omitted");
+        if ((index === 9 || index === 10) && evidence === null)
+            return createNotEvaluatedDataCheck(id, description, "review evidence was omitted");
+        return createStructuredDataCheck(id, description, severity, normalizeDataFindings(findingsByCheck.get(id)));
+    });
+    return checks;
+}
+function evaluationFindings(item, rule) {
+    return [
+        ...item.expressionOverflows.map((overflowItem) => ({
+            code: "diagnostic-expression-overflow",
+            message: "Measure expression overflowed",
+            context: {
+                ruleId: rule.id,
+                expressionPath: overflowItem.expressionPath,
+                reviewScope: item.scope,
+                ...(overflowItem.coordinate === null ? {} : overflowItem.coordinate),
+                sources: overflowItem.sources,
+            },
+        })),
+        ...(item.status === "triggered"
+            ? [
+                {
+                    code: rule.code,
+                    message: rule.description,
+                    context: {
+                        ruleId: rule.id,
+                        reviewScope: item.scope,
+                        sources: item.scope.sources,
+                    },
+                },
+            ]
+            : []),
+        ...(item.status === "not-evaluated"
+            ? [
+                {
+                    code: "diagnostic-review-rule-not-evaluated",
+                    message: "Diagnostic review rule was not evaluated",
+                    context: {
+                        ruleId: rule.id,
+                        reviewScope: item.scope,
+                        sources: item.scope.sources,
+                    },
+                },
+            ]
+            : []),
+    ];
+}
+export function reviewPreparedDiagnosticData(input) {
+    assertPreparedDiagnosticData(input.prepared);
+    const evidence = input.evidence === null
+        ? null
+        : validateDiagnosticReviewEvidence(input.evidence);
+    const evaluations = evaluateDiagnosticReviewRules(input.prepared);
+    const checks = structuralChecks(input.prepared, evidence);
     for (const rule of input.prepared.definition.definition.reviewRules) {
         const matching = evaluations.filter((item) => item.ruleId === rule.id);
-        const status = matching.some((item) => item.status === "triggered" && item.severity === "fail") ? "fail" : matching.some((item) => item.status === "triggered") ? "warning" : matching.some((item) => item.status === "not-evaluated") ? "not-evaluated" : "pass";
-        const findings = matching.filter((item) => item.status === "triggered").map((item) => ({ code: rule.code, message: rule.description, context: { ruleId: rule.id, reviewScope: item.reviewScope, sources: item.reviewScope.sources } }));
-        checks.push({ id: rule.id, description: rule.description, status, details: findings.slice(0, 20).map((item) => item.message), findings });
+        const overflow = matching.some((item) => item.expressionOverflows.length > 0);
+        const status = overflow ||
+            matching.some((item) => item.status === "triggered" && item.severity === "fail")
+            ? "fail"
+            : matching.some((item) => item.status === "triggered")
+                ? "warning"
+                : matching.some((item) => item.status === "not-evaluated")
+                    ? "not-evaluated"
+                    : "pass";
+        const findings = matching.flatMap((item) => evaluationFindings(item, rule));
+        const normalizedFindings = normalizeDataFindings(findings);
+        checks.push({
+            id: rule.id,
+            description: rule.description,
+            status,
+            details: normalizedFindings.slice(0, 20).map((item) => item.message),
+            findings: normalizedFindings,
+        });
     }
     const report = freeze(summarizeDataChecks(checks));
-    const identityBody = freeze({ definitionIntegrity: input.prepared.definition.definitionIntegrity, preparationFingerprint: input.prepared.preparationFingerprint, evidence, checks: report.checks.map((check) => ({ id: check.id, status: check.status, findings: check.findings })), summary: report.summary, evaluations });
-    return freeze({ report, evaluations, evidence, identityBody, reportFingerprint: `fnv1a64-jcs-v1:${fnv1a64(canonicalJson({ identityVersion: 1, kind: "diagnostic-review", review: identityBody }))}` });
+    const identityBody = projectDiagnosticIdentity({
+        definitionIntegrity: input.prepared.definition.definitionIntegrity,
+        preparationFingerprint: input.prepared.preparationFingerprint,
+        evidence,
+        checks: report.checks.map((check) => ({
+            id: check.id,
+            status: check.status,
+            findings: check.findings,
+        })),
+        summary: report.summary,
+        evaluations,
+    });
+    return freeze({
+        definitionIntegrity: input.prepared.definition.definitionIntegrity,
+        preparationFingerprint: input.prepared.preparationFingerprint,
+        report,
+        evaluations,
+        evidence,
+        identityBody,
+        reportFingerprint: `fnv1a64-jcs-v1:${fnv1a64(canonicalJson({ identityVersion: 1, kind: "diagnostic-review-report", review: identityBody }))}`,
+    });
+}
+const findingStates = new WeakMap();
+const compactReceipts = new WeakSet();
+const compactReceiptPreparations = new WeakMap();
+const compactReceiptFingerprints = new WeakMap();
+function compactError(message, path = "$") {
+    throw new DiagnosticValidationError([
+        { domain: "input", code: "invalid-input-relationship", path, message },
+    ]);
+}
+export function assertCompactDiagnosticReviewReceipt(value) {
+    if (value === null ||
+        typeof value !== "object" ||
+        !compactReceipts.has(value))
+        compactError("Value is not an authentic compact diagnostic review receipt");
+}
+function findingState(store) {
+    if (store === null || typeof store !== "object" || !findingStates.has(store))
+        compactError("Value is not an authentic compact diagnostic finding store");
+    return findingStates.get(store);
+}
+function findingLocation(state, index) {
+    if (!Number.isSafeInteger(index) || index < 0 || index >= state.count)
+        compactError("Finding index is outside this review", "$.index");
+    const block = state.blocks.find((block) => index >= block.start && index < block.start + block.ids.length);
+    return { block, id: block.ids[index - block.start] };
+}
+const findingQuerySchema = z
+    .object({
+    checkId: z.string().refine(isDiagnosticToken).optional(),
+    offset: z.number().int().nonnegative().safe().optional(),
+    limit: z.number().int().min(1).max(1000).optional(),
+})
+    .strict();
+const findingSourceQuerySchema = z
+    .object({
+    location: z.enum(["context", "scope"]).optional(),
+    offset: z.number().int().nonnegative().safe().optional(),
+    limit: z.number().int().min(1).max(1000).optional(),
+})
+    .strict();
+function pageResult(items, total, offset) {
+    return Object.freeze({
+        total,
+        offset,
+        items: Object.freeze(items),
+        nextOffset: offset + items.length < total ? offset + items.length : null,
+    });
+}
+export function getDiagnosticReviewFinding(store, index) {
+    const state = findingState(store);
+    const { block, id } = findingLocation(state, index);
+    return Object.freeze({
+        index,
+        checkId: block.checkId,
+        finding: state.table.read(id),
+    });
+}
+/** Full ordered evidence, including every finding's source lists. */
+export function iterateDiagnosticReviewFindings(store) {
+    const state = findingState(store);
+    return (function* () {
+        for (let index = 0; index < state.count; index++)
+            yield getDiagnosticReviewFinding(store, index);
+    })();
+}
+/** Summary pages never expand source lists, including high-fanout control totals. */
+export function pageDiagnosticReviewFindings(store, query = {}) {
+    const state = findingState(store);
+    const issues = diagnosticJsonPreflight(query, "input");
+    if (issues.length)
+        throw new DiagnosticValidationError(issues);
+    const parsed = findingQuerySchema.safeParse(query);
+    if (!parsed.success)
+        compactError("Invalid finding page query");
+    const { checkId, offset = 0, limit = 100 } = parsed.data;
+    const blocks = state.blocks.filter((block) => checkId === undefined || block.checkId === checkId);
+    const total = blocks.reduce((sum, block) => sum + block.ids.length, 0);
+    const items = [];
+    let position = 0;
+    for (const block of blocks) {
+        for (let local = Math.max(0, offset - position); local < block.ids.length && items.length < limit; local++)
+            items.push(Object.freeze({
+                index: block.start + local,
+                checkId: block.checkId,
+                finding: state.table.read(block.ids[local], true),
+            }));
+        position += block.ids.length;
+        if (items.length >= limit)
+            break;
+    }
+    return pageResult(items, total, offset);
+}
+export function pageDiagnosticReviewFindingSources(store, index, query = {}) {
+    const state = findingState(store);
+    const { id } = findingLocation(state, index);
+    const issues = diagnosticJsonPreflight(query, "input");
+    if (issues.length)
+        throw new DiagnosticValidationError(issues);
+    const parsed = findingSourceQuerySchema.safeParse(query);
+    if (!parsed.success)
+        compactError("Invalid finding source-page query");
+    const { location = "context", offset = 0, limit = 100 } = parsed.data;
+    const context = state.table.property(id, "context");
+    const parent = location === "scope"
+        ? state.table.property(context, "reviewScope")
+        : context;
+    const sources = state.table.property(parent, "sources");
+    if (sources === undefined)
+        return pageResult([], 0, offset);
+    const count = state.table.length(sources);
+    return pageResult(Array.from({ length: Math.max(0, Math.min(limit, count - offset)) }, (_, local) => state.table.read(state.table.arrayItem(sources, offset + local))), count, offset);
+}
+/** Compact owner receipt; identity projection/hash are deliberately deferred. */
+export function reviewPreparedDiagnosticDataCompact(input) {
+    assertCompactPreparedDiagnosticData(input.prepared);
+    const evidence = input.evidence === null
+        ? null
+        : validateDiagnosticReviewEvidence(input.evidence);
+    const evaluations = evaluateDiagnosticReviewRulesCompact(input.prepared);
+    const table = new CompactDiagnosticJson();
+    const blocks = [];
+    const checks = [];
+    let findingCount = 0;
+    const appendFindings = (checkId, values) => {
+        const pending = [];
+        const sources = [];
+        const sourceIds = new Map();
+        const candidates = new Map();
+        const mergeSources = (previous, incoming) => {
+            if (incoming === undefined)
+                return previous;
+            const ids = incoming.map((source) => {
+                const key = canonicalJson(source);
+                let id = sourceIds.get(key);
+                if (id === undefined) {
+                    id = sources.length;
+                    sources.push(source);
+                    sourceIds.set(key, id);
+                }
+                return id;
+            });
+            if (previous === undefined)
+                return ids;
+            if (ids.every((id) => previous instanceof Set ? previous.has(id) : previous.includes(id)))
+                return previous;
+            const union = previous instanceof Set ? previous : new Set(previous);
+            for (const id of ids)
+                union.add(id);
+            return union;
+        };
+        const sourceValues = (union) => [...(union ?? [])]
+            .map((id) => sources[id])
+            .sort(compareDiagnosticSourceLocations);
+        for (const value of values) {
+            const finding = normalizeDataFindings([value])[0];
+            const key = findingMergeKey(finding);
+            // Hashes index candidates only. Exact source-free keys decide equality.
+            const hash = fnv1a64(key);
+            const bucket = candidates.get(hash);
+            const possible = bucket === undefined
+                ? []
+                : typeof bucket === "number"
+                    ? [bucket]
+                    : bucket;
+            const matching = possible.find((index) => canonicalJson(table.read(pending[index].keyId)) === key);
+            let entry;
+            if (matching === undefined) {
+                const index = pending.length;
+                entry = { keyId: table.add(findingMergeSkeleton(finding)) };
+                pending.push(entry);
+                candidates.set(hash, bucket === undefined ? index : [...possible, index]);
+            }
+            else {
+                entry = pending[matching];
+                entry.keyId = table.add(findingMergeSkeleton(finding));
+            }
+            entry.contextSources = mergeSources(entry.contextSources, finding.context?.sources);
+            entry.scopeSources = mergeSources(entry.scopeSources, finding.context?.reviewScope?.sources);
+        }
+        // Source-free fields decide nearly every comparison. Expand source IDs only
+        // for the contract's final tie-break, never for each ordinary comparison.
+        pending.sort((a, b) => compareDataFindings(table.read(a.keyId), table.read(b.keyId)) ||
+            compareSourceArrays(sourceValues(a.contextSources), sourceValues(b.contextSources)));
+        const ids = pending.map((entry) => {
+            const skeleton = table.read(entry.keyId);
+            if (skeleton.context === undefined)
+                return table.add(skeleton);
+            const context = { ...skeleton.context };
+            if (entry.contextSources === undefined)
+                delete context.sources;
+            else
+                context.sources = sourceValues(entry.contextSources);
+            if (context.reviewScope !== undefined)
+                context.reviewScope = {
+                    ...context.reviewScope,
+                    sources: sourceValues(entry.scopeSources),
+                };
+            // Each final source list is encoded once, after every duplicate was merged.
+            return table.add({ ...skeleton, context });
+        });
+        const block = { checkId, start: findingCount, ids: Uint32Array.from(ids) };
+        findingCount += ids.length;
+        blocks.push(block);
+        return block;
+    };
+    for (const check of structuralChecks(input.prepared, evidence)) {
+        const block = appendFindings(check.id, check.findings);
+        checks.push(Object.freeze({
+            id: check.id,
+            description: check.description,
+            status: check.status,
+            details: Object.freeze([...check.details]),
+            findingCount: block.ids.length,
+        }));
+    }
+    for (const [ruleIndex, rule,] of input.prepared.definition.definition.reviewRules.entries()) {
+        const range = evaluations.rules[ruleIndex];
+        const counts = range.summary;
+        const status = counts.fail > 0
+            ? "fail"
+            : counts.warning > 0
+                ? "warning"
+                : counts.notEvaluated > 0
+                    ? "not-evaluated"
+                    : "pass";
+        const values = function* () {
+            if (counts.pass === range.count)
+                return;
+            for (let index = range.start; index < range.start + range.count; index++) {
+                if (getDiagnosticReviewEvaluationSummary(evaluations, index)
+                    .effectiveStatus === "pass")
+                    continue;
+                yield* evaluationFindings(getDiagnosticReviewEvaluation(evaluations, index), rule);
+            }
+        };
+        const block = appendFindings(rule.id, values());
+        const details = Array.from(block.ids.subarray(0, 20), (id) => table.read(table.property(id, "message")));
+        checks.push(Object.freeze({
+            id: rule.id,
+            description: rule.description,
+            status,
+            details: Object.freeze(details),
+            findingCount: block.ids.length,
+        }));
+    }
+    table.seal();
+    const findings = Object.freeze({
+        count: findingCount,
+    });
+    findingStates.set(findings, { table, blocks, count: findingCount });
+    const summary = summarizeDataChecks(checks.map((check) => ({
+        ...check,
+        details: [...check.details],
+        findings: [],
+    }))).summary;
+    const receipt = Object.freeze({
+        definitionIntegrity: input.prepared.definition.definitionIntegrity,
+        report: Object.freeze({
+            checks: Object.freeze(checks),
+            summary: Object.freeze(summary),
+        }),
+        evaluations,
+        findings,
+        evidence,
+    });
+    compactReceipts.add(receipt);
+    compactReceiptPreparations.set(receipt, input.prepared);
+    return receipt;
+}
+/** Exact legacy review identity, available only from an authentic immutable owner. */
+export function getCompactDiagnosticReviewReceiptIdentityDocument(receipt) {
+    assertCompactDiagnosticReviewReceipt(receipt);
+    const state = findingState(receipt.findings);
+    const prepared = compactReceiptPreparations.get(receipt);
+    return createDiagnosticIdentityObject({
+        definitionIntegrity: createDiagnosticIdentityValue(receipt.definitionIntegrity),
+        preparationFingerprint: createDiagnosticIdentityValue(getCompactPreparedDiagnosticDataFingerprint(prepared)),
+        evidence: createDiagnosticIdentityValue(receipt.evidence),
+        checks: createDiagnosticIdentityArray(receipt.report.checks.length, (index) => {
+            const check = receipt.report.checks[index];
+            const block = state.blocks[index];
+            return createDiagnosticIdentityObject({
+                id: createDiagnosticIdentityValue(check.id),
+                status: createDiagnosticIdentityValue(check.status),
+                findings: createDiagnosticIdentityArray(block.ids.length, (local) => state.table.identityDocument(block.ids[local])),
+            });
+        }),
+        summary: createDiagnosticIdentityValue(receipt.report.summary),
+        evaluations: getCompactDiagnosticReviewEvaluationsIdentityDocument(receipt.evaluations),
+    });
+}
+/** Explicit evidence operation; caches only the small immutable-owner fingerprint. */
+export function getCompactDiagnosticReviewReceiptFingerprint(receipt) {
+    assertCompactDiagnosticReviewReceipt(receipt);
+    let fingerprint = compactReceiptFingerprints.get(receipt);
+    if (fingerprint === undefined) {
+        fingerprint = fingerprintDiagnosticIdentity(getCompactDiagnosticReviewReceiptIdentityDocument(receipt), { kind: "diagnostic-review-report", property: "review" });
+        compactReceiptFingerprints.set(receipt, fingerprint);
+    }
+    return fingerprint;
 }
 //# sourceMappingURL=diagnosticPreparedReview.js.map