Files
reverse-engineering-anything/src/domain/analysisView/WebNetworkProjectionAccumulator.ts
T
morlutoandCursor Agent 6a2b690440 fix(environment): preserve capture evidence during state inference (#9897)
fix(environment): preserve evidence when inferring and serving state

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
2026-11-11 00:14:27 -05:00

232 lines
8.4 KiB
TypeScript

import { z } from "zod";
import { fixedAllowanceOptions } from "../fixedAllowanceRemediation.js";
import {
AnalysisResourceConstraintError,
AnalysisUnsupportedTargetError,
} from "../analysisErrorCore.js";
import type { AnalysisError } from "../analysisErrorBase.js";
import { compareUnicodeCodePoints as compare } from "../unicodeCodePointOrder.js";
import { err, ok, type Result } from "../result.js";
import {
safeParseOwnedWebNetworkCapture,
type WebNetworkCapture,
} from "../webNetworkCapture.js";
import { admitAnalysisViewData } from "./analysisViewDataAdmission.js";
import { analysisViewInputError } from "./analysisViewErrors.js";
import { analysisInputErrorFromIssues } from "../inputIssueProjection.js";
import type { AnalysisViewParent } from "./analysisViewParent.js";
import {
ENTRY_BYTES,
textBytes,
type Reserve,
} from "./webNetworkRouteTemplates.js";
/** Shared retained/temporary byte accounting for views that group retained HAR records. */
export abstract class WebNetworkProjectionAccumulator {
readonly #limitations = new Set<string>();
#retainedBytes = 0;
#temporaryBytes = 0;
/** Per-record scratch reservation handed to the shared record readers. */
protected readonly scratch: Reserve = (bytes) => this.temporary(bytes);
protected constructor(
readonly maximumBytes: number,
private readonly budgetSubject: string,
private readonly operation = "inspect_analysis_view",
) {}
protected retain(bytes: number): boolean {
if (this.#retainedBytes + this.#temporaryBytes + bytes > this.maximumBytes)
return false;
this.#retainedBytes += bytes;
return true;
}
protected temporary(bytes: number): boolean {
if (this.#retainedBytes + this.#temporaryBytes + bytes > this.maximumBytes)
return false;
this.#temporaryBytes += bytes;
return true;
}
/** Restore the enclosing synchronous parse's scratch after a nested body lease. */
protected temporaryCheckpoint(): () => void {
const held = this.#temporaryBytes;
return () => {
this.#temporaryBytes = held;
};
}
/** Mark the retained bytes; the returned call releases what was retained since, once none of it is held. */
protected retainedCheckpoint(): () => void {
const mark = this.#retainedBytes;
return () => {
this.#retainedBytes = Math.min(this.#retainedBytes, mark);
};
}
/** Per-record strings and descriptors never become cumulative scratch. */
protected releaseTemporary(): void {
this.#temporaryBytes = 0;
}
protected overBudget(): Result<never, AnalysisError> {
return err(
new AnalysisResourceConstraintError(
this.operation,
"memory",
`${this.budgetSubject} retained state and temporary work exceed the projection representation budget.`,
{ output_bytes: this.maximumBytes },
fixedAllowanceOptions(
"The analysis-view projection allowance",
"parser",
),
),
);
}
/** Reserve schema output and validation scratch while the borrowed parent stays live. */
admitCaptureClone(value: unknown): Result<void, AnalysisError> {
return admitAnalysisViewData(value, false, (bytes) =>
this.retain(bytes) ? ok(undefined) : this.overBudget(),
);
}
/** Reserve bytes a view derives from the borrowed parent before it allocates them. */
admitDerivedBytes(bytes: number): Result<void, AnalysisError> {
return this.retain(bytes) ? ok(undefined) : this.overBudget();
}
/** Admit the complete portable envelope before cloning or authenticating it. */
admitInlineEvidence(value: unknown): Result<void, AnalysisError> {
return admitAnalysisViewData(value, true, (bytes) =>
this.retain(bytes) ? ok(undefined) : this.overBudget(),
);
}
addLimitations(limitations: readonly string[]): Result<void, AnalysisError> {
const prepared = this.prepareLimitations(limitations);
if (!prepared.ok) return prepared;
prepared.value();
return ok(undefined);
}
/** Admit record qualifications without publishing them before the record commits. */
protected prepareLimitations(
limitations: readonly string[],
): Result<() => void, AnalysisError> {
const rollbackAdmission = this.retainedCheckpoint();
const pending = new Set<string>();
for (const limitation of limitations) {
if (this.#limitations.has(limitation) || pending.has(limitation))
continue;
if (!this.retain(ENTRY_BYTES + textBytes(limitation.length))) {
rollbackAdmission();
return this.overBudget();
}
pending.add(limitation);
}
return ok(() => {
for (const limitation of pending) this.#limitations.add(limitation);
});
}
/** Derive budgeted qualifications for this snapshot without retaining old snapshots. */
protected snapshotLimitations(
derived: readonly string[],
): Result<string[], AnalysisError> {
const release = this.temporaryCheckpoint();
if (
!this.scratch(
derived.reduce(
(bytes, limitation) =>
bytes + ENTRY_BYTES + textBytes(limitation.length),
0,
),
)
)
return this.overBudget();
try {
return ok([...new Set([...this.#limitations, ...derived])].sort(compare));
} finally {
release();
}
}
protected sortedLimitations(): string[] {
return [...this.#limitations].sort(compare);
}
}
/** Authenticate and gate a retained HAR parent before a grouping view reads any record. */
export const admitHarCaptureParent = (
parent: AnalysisViewParent,
viewKind: "api-surface" | "environment-manifest" | "environment-state",
accumulator: WebNetworkProjectionAccumulator,
context: { readonly operation?: string; readonly sourceField?: string } = {},
): Result<WebNetworkCapture, AnalysisError> => {
const operation = context.operation ?? "inspect_analysis_view";
const sourceField = context.sourceField ?? "source";
const unsupported = (reason: string, remediationAction?: string) =>
err(
new AnalysisUnsupportedTargetError(
operation,
parent.evidenceId,
reason,
remediationAction === undefined ? undefined : { remediationAction },
),
);
if (parent.operation !== "inspect_web_network_capture")
return unsupported(
`View ${viewKind} is unsupported for parent operation ${parent.operation}; ${viewKind} requires ${viewKind === "api-surface" ? "inspect_web_network_capture" : "inspect_web_network_capture or capture_browser_scenario"}.`,
);
const admitted = accumulator.admitCaptureClone(parent.normalizedResult);
if (!admitted.ok) return admitted;
const parsed = safeParseOwnedWebNetworkCapture(parent.normalizedResult);
if (!parsed.success)
return err(
analysisInputErrorFromIssues(
operation,
parsed.error.issues.map((issue) => ({
...issue,
path: [sourceField, "normalized_result", ...issue.path],
})),
{ [sourceField]: { normalized_result: parent.normalizedResult } },
{ cause: parsed.error },
),
);
if (parsed.data.format !== "har")
return unsupported(
`${viewKind} does not support capture format ${parsed.data.format}.`,
);
// Environment views preserve the recorded report path and authenticate its digest;
// the api-surface view keeps the admission its existing callers rely on.
const { artifact } = parsed.data;
const subject = parent.subject;
if (
viewKind !== "api-surface" &&
artifact.sha256 !== null &&
(subject == null || subject.digest.sha256 !== artifact.sha256)
)
return err(
analysisViewInputError([
{
path: ["source", "subject"],
reason: "invalid_value",
message: "Capture parent subject must identify the report's SHA-256.",
},
]),
);
// The view would write path templates it cannot check against declarations
// the parent does not retain, so the refusal does not repeat declaration text.
const declarations = z
.object({ sensitive_value_count: z.number().int().nonnegative() })
.safeParse(parent.parameters);
if (!declarations.success || declarations.data.sensitive_value_count > 0)
return unsupported(
"sensitive_values_unretained",
"This view cannot safely project this capture because sensitivity declarations are not retained. Use a compatible capture or summary view to inspect retained observations. Do not remove sensitivity declarations to bypass this restriction.",
);
return ok(parsed.data);
};