Files
reverse-engineering-anything/src/domain/analysisView/recordedArrayView.ts
T
morlutoandCursor Agent b40b0b8665 feat: page recorded Evidence arrays (#8863)
* feat(kuna): verify release 1.990

* feat(kuna): preserve stored pointer references

* fix(kuna): group image-wide reference coverage gaps

* fix(evidence): retain producer-required xref observations

* fix(mcp): clarify xref address page scope

* fix(kuna): preserve reference target aliases

* feat: page recorded evidence arrays

* fix(mcp): guide large evidence views to files

* fix: preserve source context in recorded views

* fix: keep recorded rows accessible with large context

* fix: disclose alias scope in recorded references

* test(kuna): identify pointer fixture version

* fix(view): keep deep recorded-array pages inside Evidence depth

Parent parameters are valid on the Evidence root and one level too deep
under a page result. Omit those parameters, and refuse a row that still
cannot be nested, instead of throwing from Evidence parsing.

* test(view): narrow recorded-array depth pages before reading parameters

* fix(view): validate recorded page rows once

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
2026-11-08 08:56:24 +08:00

188 lines
6.7 KiB
TypeScript

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<typeof recordedArrayViewSchema>,
) => {
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<string, unknown>)[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),
});
};