From fd555be8b4d06422170d83c03c3d6858cab1302a Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 15 Nov 2026 08:00:38 +0800 Subject: [PATCH] refactor(errors): type 14 baselined resource refusals as fixed ceilings or measured exhaustion (#10639) * refactor(errors): type 14 baselined resource refusals as fixed ceilings or measured exhaustion Fixed ceilings (NTFS journal file, web-bundle worker transfer, Playwright trace parser, lipo field retention, exactly representable file sizes) now name their allowance; observed heap or result-capacity exhaustion and occupied admission declare measuredExhaustion. The typed-resource-refusal baseline drops from 24 sites in 19 files to 10 in 10. * fix(browser): name the trace parser allowance the record actually exhausted * test(ntfs): compare the oversized-acquisition recovery with its owning formatter --- .../typed-resource-refusal-baseline.json | 9 ----- src/application/JsonAuthenticationHeadroom.ts | 1 + .../ntfs/NtfsJournalService.test.ts | 36 +++++++++++++++++++ src/application/ntfs/NtfsJournalService.ts | 9 ++++- src/browser/WebBundleAnalysisWorker.ts | 10 +++++- src/browser/history/CaptureFormatError.ts | 9 +++++ src/browser/history/CaptureJson.ts | 9 +++++ .../PlaywrightTraceDecoder.test.ts | 25 +++++++++++++ .../history/playwrightTrace/TraceStream.ts | 28 +++++++++++++-- .../javascriptAnalysisWorkerProcess.ts | 2 ++ src/ghidra/GhidraExecutableHeader.ts | 7 +++- src/native/SignatureTargetBinding.ts | 5 +++ src/native/parsers/lipo.ts | 11 +++++- src/process/ArtifactAnalysisResources.ts | 1 + .../typedResourceRefusalRule.test.ts | 6 ++-- 15 files changed, 149 insertions(+), 19 deletions(-) diff --git a/scripts/lint/rules/typed-resource-refusal-baseline.json b/scripts/lint/rules/typed-resource-refusal-baseline.json index e6e3ada12b..3c1cc24e4d 100644 --- a/scripts/lint/rules/typed-resource-refusal-baseline.json +++ b/scripts/lint/rules/typed-resource-refusal-baseline.json @@ -1,21 +1,12 @@ { - "src/application/JsonAuthenticationHeadroom.ts": 1, "src/application/desktop/DesktopBuildSolves.ts": 1, - "src/application/ntfs/NtfsJournalService.ts": 1, - "src/browser/WebBundleAnalysisWorker.ts": 4, - "src/browser/history/playwrightTrace/TraceStream.ts": 2, - "src/composition/javascriptAnalysisWorkerProcess.ts": 2, "src/domain/apiContract/parseGraphqlContract.ts": 1, "src/domain/native/nativeAotPe.ts": 1, - "src/ghidra/GhidraExecutableHeader.ts": 1, "src/ghidra/GhidraFileArtifacts.ts": 1, "src/il2cpp/Il2cppGhidraSeedWriter.ts": 1, "src/model/ModelArtifactProvider.ts": 1, "src/native/NativeMacOSProvider.ts": 1, "src/native/NativePlistSource.ts": 1, - "src/native/SignatureTargetBinding.ts": 1, - "src/native/parsers/lipo.ts": 1, - "src/process/ArtifactAnalysisResources.ts": 1, "src/server/http/NodeHttpRequestOwner.ts": 1, "src/sqlite/SqliteDatabaseWorkerExecution.ts": 1 } diff --git a/src/application/JsonAuthenticationHeadroom.ts b/src/application/JsonAuthenticationHeadroom.ts index e42fb26607..7c2652b8b6 100644 --- a/src/application/JsonAuthenticationHeadroom.ts +++ b/src/application/JsonAuthenticationHeadroom.ts @@ -144,6 +144,7 @@ export const requireAuthenticationHeadroom = ( authentication_bytes: requiredBytes, available_heap_bytes: availableBytes, }, + { measuredExhaustion: true }, ), ); }; diff --git a/src/application/ntfs/NtfsJournalService.test.ts b/src/application/ntfs/NtfsJournalService.test.ts index b89598948c..cbf7e557b5 100644 --- a/src/application/ntfs/NtfsJournalService.test.ts +++ b/src/application/ntfs/NtfsJournalService.test.ts @@ -1,3 +1,4 @@ +import { fixedAllowanceRemediation } from "../../domain/fixedAllowanceRemediation.js"; import { createHash } from "node:crypto"; import { lstat, open, realpath, writeFile } from "node:fs/promises"; import { join } from "node:path"; @@ -73,6 +74,41 @@ it("preserves the completed file identity when MFT interpretation fails", async } }); +it("refuses an oversized acquisition as a fixed ceiling, not host memory", async () => { + const resources = new ArtifactResourceScope(); + const directory = await createTestTempDirectory("rea-ntfs-oversized-"); + const mftPath = join(directory, "mft"); + const file = await open(mftPath, "w"); + await file.truncate(64 * 1024 * 1024 + 1); + await file.close(); + try { + const result = await inspectNtfsJournalEvidence( + { mft_path: mftPath, journal_path: "/fixture/journal" }, + resources, + ); + if (result.ok) throw new Error("expected a size refusal"); + const projected = projectAnalysisError(result.error); + expect(projected).toMatchObject({ + code: "resource_constraint", + retryable: false, + details: { + refusal: { + kind: "fixed_ceiling", + allowance: "The NTFS journal file allowance", + limit: 64 * 1024 * 1024, + unit: "bytes", + }, + }, + }); + // Recovery comes from the fixed-allowance owner, not host-memory advice. + expect(projected.remediation.action).toBe( + fixedAllowanceRemediation("The NTFS journal file allowance", "input"), + ); + } finally { + await resources.close(); + } +}); + it("retains both acquisitions through a failed journal close and cleanup retry", async () => { const directory = await createTestTempDirectory("rea-ntfs-partial-"); const mftPath = join(directory, "mft"); diff --git a/src/application/ntfs/NtfsJournalService.ts b/src/application/ntfs/NtfsJournalService.ts index 0a69cda116..379e7b5ad8 100644 --- a/src/application/ntfs/NtfsJournalService.ts +++ b/src/application/ntfs/NtfsJournalService.ts @@ -1,3 +1,4 @@ +import { fixedAllowanceOptions } from "../../domain/fixedAllowanceRemediation.js"; import type { BigIntStats } from "node:fs"; import { ntfsJournalCacheFor, @@ -90,7 +91,13 @@ const readFailure = ( { maximum_file_bytes: NTFS_JOURNAL_FILE_BYTES, }, - { cause, retryable: false }, + { + cause, + ...fixedAllowanceOptions("The NTFS journal file allowance", "input", { + limit: NTFS_JOURNAL_FILE_BYTES, + unit: "bytes", + }), + }, ); } if ( diff --git a/src/browser/WebBundleAnalysisWorker.ts b/src/browser/WebBundleAnalysisWorker.ts index 167a0fef98..36026089f0 100644 --- a/src/browser/WebBundleAnalysisWorker.ts +++ b/src/browser/WebBundleAnalysisWorker.ts @@ -1,3 +1,4 @@ +import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js"; import { retainProcessInspectionCleanup, processInspectionCancellationError, @@ -390,6 +391,7 @@ export class WebBundleAnalysisWorker { "memory", response.message, { result_budget_bytes: resultBudget }, + { measuredExhaustion: true }, ); throw new AnalysisOutputError( OPERATION, @@ -414,6 +416,7 @@ export class WebBundleAnalysisWorker { "memory", "Completed script facts exceed the host's remaining reserved result capacity", { result_budget_bytes: resultBudget }, + { measuredExhaustion: true }, ); const stored = await this.#files .run(() => @@ -624,6 +627,11 @@ export class WebBundleAnalysisWorker { "worker transfer budget", ), { source_bytes: WEB_BUNDLE_WORKER_LIMITS.sourceBytes }, + fixedAllowanceOptions( + "The web-bundle worker transfer allowance", + "bytes", + { limit: WEB_BUNDLE_WORKER_LIMITS.sourceBytes, unit: "bytes" }, + ), ); await handle.writeFile(chunk); bytes += chunk.length; @@ -826,7 +834,7 @@ export class WebBundleAnalysisWorker { { result_budget_bytes: failure.resultBudgetBytes, }, - { capturedOutput }, + { capturedOutput, measuredExhaustion: true }, ) : new AnalysisOutputError( OPERATION, diff --git a/src/browser/history/CaptureFormatError.ts b/src/browser/history/CaptureFormatError.ts index 0fdc026909..17ce16a86f 100644 --- a/src/browser/history/CaptureFormatError.ts +++ b/src/browser/history/CaptureFormatError.ts @@ -1,3 +1,10 @@ +/** The fixed parser allowance an `input-limit` refusal exhausted. */ +export interface CaptureInputAllowance { + readonly kind: "parser-nodes" | "nesting-depth"; + readonly limit: number; + readonly unit: "parser nodes" | "nesting levels"; +} + /** Expected malformed, unsupported or oversized producer data at a historical decoder boundary. */ export class CaptureFormatError extends Error { constructor( @@ -10,6 +17,8 @@ export class CaptureFormatError extends Error { message: string, readonly pointer = "", cause?: unknown, + /** Which allowance an `input-limit` exhausted, when the parser knows it. */ + readonly allowance?: CaptureInputAllowance, ) { super(message, cause === undefined ? undefined : { cause }); } diff --git a/src/browser/history/CaptureJson.ts b/src/browser/history/CaptureJson.ts index b6333843b1..8c097724e3 100644 --- a/src/browser/history/CaptureJson.ts +++ b/src/browser/history/CaptureJson.ts @@ -23,6 +23,9 @@ const captureNodeAdmission = (maximumNodes: number | undefined) => { throw new CaptureFormatError( "input-limit", "JSON exceeds its parser node representation allowance.", + "", + undefined, + { kind: "parser-nodes", limit: maximumNodes, unit: "parser nodes" }, ); }; }; @@ -71,6 +74,12 @@ export const parseCaptureJson = ( "input-limit", `${format} exceeds max_nesting_depth (${String(captureBudgets().depth)} levels).`, valuePointer(), + undefined, + { + kind: "nesting-depth", + limit: captureBudgets().depth, + unit: "nesting levels", + }, ); }; const append = (value: unknown): void => { diff --git a/src/browser/history/playwrightTrace/PlaywrightTraceDecoder.test.ts b/src/browser/history/playwrightTrace/PlaywrightTraceDecoder.test.ts index de5292aafe..342ad4d4a4 100644 --- a/src/browser/history/playwrightTrace/PlaywrightTraceDecoder.test.ts +++ b/src/browser/history/playwrightTrace/PlaywrightTraceDecoder.test.ts @@ -1,3 +1,4 @@ +import { projectAnalysisError } from "../../../domain/analysisErrorProjection.js"; import { createHash } from "node:crypto"; import { readFile, writeFile, open } from "node:fs/promises"; import { expect, it } from "vitest"; @@ -380,6 +381,30 @@ it("bounds JSON node expansion even when many tokens fit inside a small physical ); if (result.ok) throw new Error("Expected node admission refusal"); expect(result.error._tag).toBe("AnalysisResourceConstraintError"); + expect(projectAnalysisError(result.error).details).toMatchObject({ + refusal: { limit: 131072, unit: "parser nodes" }, + }); + expect(resources.hasPending).toBe(false); + } finally { + await resources.close(); + } +}); + +it("names the nesting allowance, not the node allowance, for a deeply nested small record", async () => { + const trace = + header + + `{"type":"console","args":${"[".repeat(80)}${"]".repeat(80)},"time":1}\n`; + const fixture = await playwrightTraceFixture({ trace, network: "" }); + const resources = new ArtifactResourceScope(); + try { + const result = await new PlaywrightTraceDecoder(resources).inspect( + fixture.path, + ); + if (result.ok) throw new Error("Expected nesting refusal"); + expect(result.error._tag).toBe("AnalysisResourceConstraintError"); + expect(projectAnalysisError(result.error).details).toMatchObject({ + refusal: { limit: 64, unit: "nesting levels" }, + }); expect(resources.hasPending).toBe(false); } finally { await resources.close(); diff --git a/src/browser/history/playwrightTrace/TraceStream.ts b/src/browser/history/playwrightTrace/TraceStream.ts index ba5b5905a5..a3b67a94d2 100644 --- a/src/browser/history/playwrightTrace/TraceStream.ts +++ b/src/browser/history/playwrightTrace/TraceStream.ts @@ -1,3 +1,4 @@ +import { fixedAllowanceOptions } from "../../../domain/fixedAllowanceRemediation.js"; import { getHeapStatistics } from "node:v8"; import { LosslessNumber, isSafeNumber } from "lossless-json"; import type { @@ -36,6 +37,7 @@ const readRecord = (bytes: Buffer): unknown => { "memory", "Insufficient heap headroom for trace record expansion.", { input_bytes: bytes.length, required_headroom_bytes: required }, + { measuredExhaustion: true }, ); let value: string; try { @@ -141,14 +143,34 @@ class TraceStreamRead { raw = readRecord(line.bytes); } catch (cause) { if (!(cause instanceof CaptureFormatError)) throw cause; - if (cause.reason === "input-limit") + if (cause.reason === "input-limit") { + // The parser names the allowance it exhausted: node count or depth. + const allowance = cause.allowance; throw new AnalysisResourceConstraintError( PLAYWRIGHT_TRACE_OPERATION, "memory", cause.message, - { parser_nodes: PLAYWRIGHT_TRACE_LIMITS.factsBytes / 256 }, - { cause }, + allowance === undefined + ? null + : { + [allowance.kind === "parser-nodes" + ? "parser_nodes" + : "nesting_levels"]: allowance.limit, + }, + { + cause, + ...fixedAllowanceOptions( + allowance?.kind === "nesting-depth" + ? "The Playwright trace record nesting allowance" + : "The Playwright trace record parser allowance", + "parser", + allowance === undefined + ? {} + : { limit: allowance.limit, unit: allowance.unit }, + ), + }, ); + } this.diagnostic(line.line, "malformed-record", cause.message); this.#headerSeen = true; return; diff --git a/src/composition/javascriptAnalysisWorkerProcess.ts b/src/composition/javascriptAnalysisWorkerProcess.ts index 855443ba37..ac81e41883 100644 --- a/src/composition/javascriptAnalysisWorkerProcess.ts +++ b/src/composition/javascriptAnalysisWorkerProcess.ts @@ -68,6 +68,7 @@ const analyze: JavaScriptSourceWorkerAnalyzer = async ( "memory", `The parent reserved its remaining result capacity for static observations; semantic analysis of ${file.path} was not started`, { semantic_result_budget_bytes: 0 }, + { measuredExhaustion: true }, ); await callbacks.phase("semantic"); const ir = await completeJavaScriptAnalysisSteps( @@ -93,6 +94,7 @@ const analyze: JavaScriptSourceWorkerAnalyzer = async ( semantic_result_budget_bytes: resultBudgetBytes, module_transfer_bytes: measured.bytes, }, + { measuredExhaustion: true }, ); await callbacks.phase("projection"); const projection = await completeJavaScriptAnalysisSteps( diff --git a/src/ghidra/GhidraExecutableHeader.ts b/src/ghidra/GhidraExecutableHeader.ts index bd27c3e62b..c042be6f0c 100644 --- a/src/ghidra/GhidraExecutableHeader.ts +++ b/src/ghidra/GhidraExecutableHeader.ts @@ -1,3 +1,4 @@ +import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js"; import { createHash } from "node:crypto"; import type { GhidraExecutableHeaderProbe } from "./GhidraInstallation.js"; import type { GhidraInstallationFileOptions } from "./GhidraInstallationProperties.js"; @@ -53,7 +54,11 @@ export const readGhidraExecutableHeader = async ( }, { diagnostics: { path, stage: "native_decompiler_header" }, - retryable: false, + ...fixedAllowanceOptions( + "The header parser's exactly representable executable extent", + "parser", + { limit: Number.MAX_SAFE_INTEGER, unit: "bytes" }, + ), }, ); completedHeader = { diff --git a/src/native/SignatureTargetBinding.ts b/src/native/SignatureTargetBinding.ts index 559e85a0d4..f23710b1eb 100644 --- a/src/native/SignatureTargetBinding.ts +++ b/src/native/SignatureTargetBinding.ts @@ -1,3 +1,4 @@ +import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js"; import { createHash } from "node:crypto"; import { constants, type BigIntStats } from "node:fs"; import { lstat, open, type FileHandle } from "node:fs/promises"; @@ -304,6 +305,10 @@ const copySignatureBytes = async ( "file-size", `Signature target size is not exactly representable: ${target.path}`, null, + fixedAllowanceOptions("The exactly representable file size", "input", { + limit: Number.MAX_SAFE_INTEGER, + unit: "bytes", + }), ); const hash = createHash("sha256"); const chunk = Buffer.alloc(64 * 1024); diff --git a/src/native/parsers/lipo.ts b/src/native/parsers/lipo.ts index fd64804322..72ca871670 100644 --- a/src/native/parsers/lipo.ts +++ b/src/native/parsers/lipo.ts @@ -1,3 +1,4 @@ +import { fixedAllowanceOptions } from "../../domain/fixedAllowanceRemediation.js"; import { z } from "zod"; import { AnalysisOutputError, @@ -289,7 +290,15 @@ export const parseLipoCapture = ( maximum_retained_bytes: NATIVE_COMMAND_OUTPUT_BUDGET_BYTES, required_retained_bytes: parsed.error.requiredBytes, }, - { cause: parsed.error, retryable: false, capturedOutput }, + { + cause: parsed.error, + capturedOutput, + ...fixedAllowanceOptions( + "The lipo field retention allowance", + "capture", + { limit: NATIVE_COMMAND_OUTPUT_BUDGET_BYTES, unit: "bytes" }, + ), + }, ), ); return err( diff --git a/src/process/ArtifactAnalysisResources.ts b/src/process/ArtifactAnalysisResources.ts index 536c2a8127..7dc07a2dc3 100644 --- a/src/process/ArtifactAnalysisResources.ts +++ b/src/process/ArtifactAnalysisResources.ts @@ -127,6 +127,7 @@ export class ArtifactAnalysisResources { "capacity", this.capacity.message, this.capacity.details, + { measuredExhaustion: true }, ), ), ); diff --git a/tests/evaluation/typedResourceRefusalRule.test.ts b/tests/evaluation/typedResourceRefusalRule.test.ts index 68f7bb703b..58f479f73e 100644 --- a/tests/evaluation/typedResourceRefusalRule.test.ts +++ b/tests/evaluation/typedResourceRefusalRule.test.ts @@ -17,7 +17,7 @@ new RuleTester({ languageOptions: { parserOptions: { lang: "ts" } } }).run( valid: [ { code: construct(""), - filename: resolve("src/application/JsonAuthenticationHeadroom.ts"), + filename: resolve("src/model/ModelArtifactProvider.ts"), }, construct(', fixedAllowanceOptions("The allowance", "count")'), construct( @@ -32,12 +32,12 @@ new RuleTester({ languageOptions: { parserOptions: { lang: "ts" } } }).run( invalid: [ { code: construct("") + construct(""), - filename: resolve("src/application/JsonAuthenticationHeadroom.ts"), + filename: resolve("src/model/ModelArtifactProvider.ts"), errors: [{ messageId: "untyped" }, { messageId: "untyped" }], }, { code: "const value = 1;", - filename: resolve("src/application/JsonAuthenticationHeadroom.ts"), + filename: resolve("src/model/ModelArtifactProvider.ts"), errors: [{ messageId: "stale", data: { allowed: "1", actual: "0" } }], }, { code: construct(""), errors: [{ messageId: "untyped" }] },