import type { z } from "zod"; import { jsonValueValidationIssue, MAX_JSON_DEPTH, type JsonValue, } from "../jsonValue.js"; import { jsonValueByteLength } from "../jsonValueByteLength.js"; import { AnalysisResourceConstraintError } from "../analysisErrorCore.js"; import { err, ok } from "../result.js"; import type { AnalysisViewParent } from "./analysisViewParent.js"; import { pageViewCoverage } from "./analysisViewCoverage.js"; import { analysisViewInputError } from "./analysisViewErrors.js"; import type { recordedArrayViewSchema } from "./analysisViewRequest.js"; const PAGE_BYTES = 1024 * 1024; /** * Parent parameters sit on the Evidence root. This page stores them under * `normalized_result.source_parameters`, one level deeper. A parent that used * the whole depth budget is valid and still cannot be copied unchanged. */ const exceedsEvidenceResultDepth = (result: JsonValue): boolean => jsonValueValidationIssue({ normalized_result: result }) !== undefined; /** A row is nested under normalized_result.rows in the output Evidence. */ const exceedsRecordedRowDepth = (row: JsonValue): boolean => jsonValueValidationIssue({ normalized_result: { rows: [row] } }) !== undefined; const recordedArrayDepthRefusal = () => err( new AnalysisResourceConstraintError( "inspect_analysis_view", "memory", `Recorded array view exceeds the maximum JSON nesting depth of ${MAX_JSON_DEPTH}.`, { maximum_json_depth: MAX_JSON_DEPTH }, { retryable: false, remediationAction: "A recorded value cannot be nested inside an Evidence page without exceeding the JSON depth limit. Retrieve or export the complete parent Evidence, or read it from the caller-supplied Evidence file or bundle.", }, ), ); /** Page an exact array within authenticated provider-recorded raw JSON. */ export const projectRecordedArrayView = ( parent: AnalysisViewParent, view: z.output, ) => { let value: unknown = parent.rawResult; for (const key of view.path) { if ( typeof value !== "object" || value === null || Array.isArray(value) || !Object.hasOwn(value, key) ) return err( analysisViewInputError([ { path: ["view", "path"], reason: "invalid_value", message: "The selected path does not identify an object member in recorded raw data.", }, ]), ); value = (value as Record)[key]; } if (!Array.isArray(value)) return err( analysisViewInputError([ { path: ["view", "path"], reason: "invalid_value", message: "The selected recorded raw value is not an array.", }, ]), ); const rows: JsonValue[] = []; let result = { parent_evidence_id: parent.evidenceId, parent_operation: parent.operation, parent_digest: parent.evidenceId.slice(3), source_provider: parent.provider ?? null, source_analysis_profile_digest: parent.analysisProfile?.digest ?? null, source_parameters: (parent.parameters ?? {}) as Record< string, JsonValue > | null, artifact: parent.artifact ?? null, kind: "recorded-array" as const, view, rows, coverage: pageViewCoverage(view.offset, 0, value.length), limitations: [ "These are raw provider-recorded values; interpretation and provider coverage require the parent Evidence.", "Raw rows may include values excluded from the parent operation's normalized result; use source parameters and parent caveats to interpret their scope.", ], unknowns: [], }; // Include the sealed digest and reserve the longest numeric coverage fields // before adding rows. Output transport may impose a smaller separate limit. const estimateBase = () => jsonValueByteLength( { ...result, view_digest: "0".repeat(64), coverage: { status: "complete-within-view", examined: Number.MAX_SAFE_INTEGER, total: Number.MAX_SAFE_INTEGER, next_offset: Number.MAX_SAFE_INTEGER, exhausted: false, }, }, PAGE_BYTES, ); const omitParameters = (reason: "bytes" | "depth") => { result = { ...result, source_parameters: null, limitations: [ ...result.limitations, reason === "depth" ? "Source parameters were omitted because nesting them under this Evidence page exceeds the maximum JSON depth; retrieve the parent Evidence for their complete values." : "Source parameters were omitted to fit the page allowance; retrieve the parent Evidence for their complete values.", ], }; }; if (result.source_parameters !== null && exceedsEvidenceResultDepth(result)) omitParameters("depth"); let bytes = estimateBase(); if (bytes > PAGE_BYTES) { omitParameters("bytes"); bytes = estimateBase(); } const tooLarge = () => err( new AnalysisResourceConstraintError( "inspect_analysis_view", "memory", "Recorded array view exceeds the 1 MiB page allowance.", { maximum_page_bytes: PAGE_BYTES }, { retryable: false, remediationAction: "The selected path or one recorded value exceeds the 1,048,576-byte analysis-view page allowance. Retrieve or export the complete parent Evidence, or read it from the caller-supplied Evidence file or bundle.", }, ), ); if (bytes > PAGE_BYTES) return tooLarge(); const end = Math.min(value.length, view.offset + view.limit); for (let i = view.offset; i < end; i++) { const row = value[i] as JsonValue; const comma = rows.length === 0 ? 0 : 1; let size = jsonValueByteLength(row, PAGE_BYTES - bytes - comma); if ( bytes + comma + size > PAGE_BYTES && rows.length === 0 && result.source_parameters !== null ) { omitParameters("bytes"); bytes = estimateBase(); if (bytes > PAGE_BYTES) return tooLarge(); size = jsonValueByteLength(row, PAGE_BYTES - bytes); } if (bytes + comma + size > PAGE_BYTES) { if (rows.length === 0) return tooLarge(); break; } // The fixed fields are checked separately. Validate only this row at its // final nesting depth; previously accepted rows cannot change, so walking // the growing page for every row repeats the same work quadratically. if (exceedsRecordedRowDepth(row)) { if (rows.length === 0) return recordedArrayDepthRefusal(); break; } bytes += comma + size; rows.push(row); } if (exceedsEvidenceResultDepth(result)) return recordedArrayDepthRefusal(); return ok({ ...result, coverage: pageViewCoverage(view.offset, rows.length, value.length), }); };