diff --git a/scripts/verify/architecture-guards.mjs b/scripts/verify/architecture-guards.mjs index e4dd6ec69b..64f206074a 100644 --- a/scripts/verify/architecture-guards.mjs +++ b/scripts/verify/architecture-guards.mjs @@ -9,6 +9,7 @@ import { } from "./counted-baseline.mjs"; import { localCompletenessEnumCount } from "./completeness-enum-guard.mjs"; import { countKeyedFirstMatches } from "./keyed-first-match.mjs"; +import { budgetArithmeticCount } from "./budget-arithmetic-guard.mjs"; import { localLimitErrorClassCount } from "./limit-class-guard.mjs"; // Architecture guards for the strict-identity / best-effort-inference split. @@ -367,7 +368,7 @@ checkCounted( "hand-written budget arithmetic (use Budget from src/domain/budget)", "budget-arithmetic", files, - /this\.#?\w*(?:[Rr]emaining|[Rr]etained|[Uu]sed)\w*\s*[-+]=/gu, + budgetArithmeticCount, ["src/domain/budget.ts"], ); diff --git a/scripts/verify/baselines/budget-arithmetic.json b/scripts/verify/baselines/budget-arithmetic.json index edf0f99517..dd218c51ee 100644 --- a/scripts/verify/baselines/budget-arithmetic.json +++ b/scripts/verify/baselines/budget-arithmetic.json @@ -1,19 +1,3 @@ { - "src/application/investigation/EvidenceLedger.ts": 1, - "src/artifacts/UnityFsArtifactReader.ts": 1, - "src/artifacts/apple/InterfaceBuilderDecodeBudget.ts": 2, - "src/artifacts/bun/BunModuleGraphLayout.ts": 2, - "src/browser/PlaywrightScenarioEvents.ts": 3, - "src/browser/WebBundleAnalysisWorker.ts": 2, - "src/browser/execution/CdpRuntimeSources.ts": 2, - "src/desktop/DesktopContentStore.ts": 1, - "src/domain/analysisView/WebNetworkProjectionAccumulator.ts": 1, - "src/domain/apiContract/parseApiContract.ts": 1, - "src/domain/firmware/hexRecords.ts": 1, - "src/domain/firmware/uf2.ts": 1, - "src/domain/javascript/javascriptSemanticWorkAllowance.ts": 1, - "src/domain/javascript/javascriptSymbolicBindings.ts": 4, - "src/dotnet/ManagedDecodeBudget.ts": 1, - "src/javascript/analysis/JavaScriptAnalysisWorker.ts": 4, - "src/python/PythonPycParser.ts": 2 + "src/javascript/analysis/JavaScriptAnalysisWorker.ts": 4 } diff --git a/scripts/verify/budget-arithmetic-guard.d.mts b/scripts/verify/budget-arithmetic-guard.d.mts new file mode 100644 index 0000000000..1a603facc2 --- /dev/null +++ b/scripts/verify/budget-arithmetic-guard.d.mts @@ -0,0 +1 @@ +export function budgetArithmeticCount(content: string): number; diff --git a/scripts/verify/budget-arithmetic-guard.mjs b/scripts/verify/budget-arithmetic-guard.mjs new file mode 100644 index 0000000000..8c328fefbe --- /dev/null +++ b/scripts/verify/budget-arithmetic-guard.mjs @@ -0,0 +1,45 @@ +// Counts hand-written allowance arithmetic that `Budget` (src/domain/budget) +// owns. Two shapes are counted: +// +// 1. A field named for an allowance (`…remaining…`, `…retained…`, `…used…`) +// adjusted with `+=` or `-=`. +// 2. Inside a hand-written `…Budget` class, any field that is both adjusted +// by hand (`+=`, `-=`, `++`, `--`) and compared with `<` or `>`: that is a +// limit check, whatever the field is called (`#bytes`, `#visits`). +// +// Write cursors (`#arenaWriteOffset`) and observation tallies are not +// allowances; outside a `…Budget` class they are not counted unless named as +// one. +const namedAllowance = + /this\.#?\w*(?:[Rr]emaining|[Rr]etained|[Uu]sed)\w*\s*[-+]=/gu; + +const budgetClass = + /^(?:export\s+)?class\s+\w*Budget\b[^\n]*\{\n([\s\S]*?)^\}/gmu; + +const adjusted = /(?:\+\+|--)this\.(#?\w+)|this\.(#?\w+)\s*(?:[-+]=|\+\+|--)/gu; + +const escape = (name) => name.replaceAll("$", "\\$"); + +// `<` or `>` near the field on one line, excluding `=>` and shifts. +const comparedIn = (body, name) => { + const field = `this\\.${escape(name)}\\b`; + const comparison = "(?])[<>](?![<>])"; + return new RegExp( + `${field}[^;\\n]*${comparison}|${comparison}[^;\\n]*${field}`, + "u", + ).test(body); +}; + +/** @param {string} content comment-stripped source */ +export const budgetArithmeticCount = (content) => { + let count = content.match(namedAllowance)?.length ?? 0; + for (const [, body] of content.matchAll(budgetClass)) { + for (const match of body.matchAll(adjusted)) { + // Already counted as a named allowance. + if (new RegExp(`^${namedAllowance.source}$`, "u").test(match[0])) + continue; + if (comparedIn(body, match[1] ?? match[2])) count += 1; + } + } + return count; +}; diff --git a/src/application/investigation/EvidenceLedger.ts b/src/application/investigation/EvidenceLedger.ts index bc75fe68e2..ae589ac16e 100644 --- a/src/application/investigation/EvidenceLedger.ts +++ b/src/application/investigation/EvidenceLedger.ts @@ -1,5 +1,7 @@ import { InvalidResidualUnknownGraphError } from "../../domain/residualUnknownGraphError.js"; import { z } from "zod"; +import { Budget } from "../../domain/budget.js"; +import { invariantViolation } from "../../domain/internalInvariant.js"; import { createEvidenceBundle, @@ -76,14 +78,14 @@ export class EvidenceLedger { #records = new Map(); #unknownRevisions = new Map(); #unknownHeads = new Map(); - #retainedBytes = 0; #recordBytes = new Map(); - readonly #maximumBytes: number; + readonly #retained: Budget; constructor( private readonly retentionPolicy: InvestigationRetentionPolicy = {}, ) { - this.#maximumBytes = - investigationMaximumRepresentationBytes(retentionPolicy); + this.#retained = new Budget( + investigationMaximumRepresentationBytes(retentionPolicy), + ); } /** Read committed counts without constructing or hashing a bundle. */ @@ -92,8 +94,8 @@ export class EvidenceLedger { evidenceRecords: this.#records.size, unknownRevisions: this.#unknownRevisions.size, unknownHeads: this.#unknownHeads.size, - retainedRepresentationBytes: this.#retainedBytes, - maximumRepresentationBytes: this.#maximumBytes, + retainedRepresentationBytes: this.#retained.used, + maximumRepresentationBytes: this.#retained.maximum, }; } @@ -512,7 +514,7 @@ export class EvidenceLedger { this.#records.clear(); this.#unknownRevisions.clear(); this.#unknownHeads.clear(); - this.#retainedBytes = 0; + this.#retained.restore(0); this.#recordBytes.clear(); } @@ -658,7 +660,7 @@ export class EvidenceLedger { delta -= LEDGER_ENTRY_BYTES + previousBytes; } for (const record of records.values()) { - const remaining = this.#maximumBytes - this.#retainedBytes - delta; + const remaining = this.#retained.remaining - delta; const bytes = investigationValueBytes( record, remaining - LEDGER_ENTRY_BYTES, @@ -666,9 +668,9 @@ export class EvidenceLedger { delta += LEDGER_ENTRY_BYTES + bytes; const admitted = admitInvestigationRetention( operation, - this.#retainedBytes, + this.#retained.used, delta, - this.#maximumBytes, + this.#retained.maximum, ); if (!admitted.ok) return admitted; recordBytes.set(record.evidence_id, bytes); @@ -683,16 +685,16 @@ export class EvidenceLedger { ? 0 : LEDGER_ENTRY_BYTES; newHeads.add(unknown.unknown_id); - const remaining = this.#maximumBytes - this.#retainedBytes - delta; + const remaining = this.#retained.remaining - delta; delta += indexBytes + headBytes + investigationValueBytes(unknown, remaining - indexBytes - headBytes); const admitted = admitInvestigationRetention( operation, - this.#retainedBytes, + this.#retained.used, delta, - this.#maximumBytes, + this.#retained.maximum, ); if (!admitted.ok) return admitted; } @@ -702,7 +704,12 @@ export class EvidenceLedger { #commitAccounting(changes: RetentionChanges): void { for (const [id, bytes] of changes.recordBytes) this.#recordBytes.set(id, bytes); - this.#retainedBytes += changes.deltaBytes; + // #admitChanges admitted the delta against the same, unchanged allowance. + if (changes.deltaBytes < 0) this.#retained.refund(-changes.deltaBytes); + else + this.#retained.charge(changes.deltaBytes, () => + invariantViolation("Admitted investigation retention no longer fits"), + ); } } diff --git a/src/artifacts/UnityFsArtifactReader.ts b/src/artifacts/UnityFsArtifactReader.ts index e713a650e3..efeefb9288 100644 --- a/src/artifacts/UnityFsArtifactReader.ts +++ b/src/artifacts/UnityFsArtifactReader.ts @@ -1,4 +1,5 @@ import { ArtifactPreparation } from "./ArtifactPreparation.js"; +import { Budget } from "../domain/budget.js"; import { artifactExpansionBudgetBytes } from "../domain/artifactExpansionBudget.js"; import type { FileHandle } from "node:fs/promises"; import { setImmediate } from "node:timers/promises"; @@ -61,7 +62,7 @@ export class UnityFsArtifactReader implements ArtifactReader { #header: UnityFsMetadata | undefined; #blocks: readonly UnityFsBlock[] = []; #dataStart = 0; - #remainingDecodeBytes = 0; + #decodeBytes = new Budget(0); #remainingReadOperations = 0; #cachedBlock: { readonly index: number; readonly bytes: Buffer } | undefined; #closing = false; @@ -261,7 +262,7 @@ export class UnityFsArtifactReader implements ArtifactReader { this.#header = preparedMetadata; this.#dataStart = dataStart; this.#blocks = readableBlocks; - this.#remainingDecodeBytes = budget; + this.#decodeBytes = new Budget(budget); this.#entries = registered.entries; this.#remainingReadOperations = registered.remainingReadOperations; } @@ -399,15 +400,16 @@ export class UnityFsArtifactReader implements ArtifactReader { ): Promise { if (this.#cachedBlock?.index === index) return this.#cachedBlock.bytes; const block = this.#blocks[index]!; - if (block.uncompressedSize > this.#remainingDecodeBytes) - throw expansionLimit( + const exhausted = () => + expansionLimit( "cumulative block decoding", BigInt(block.uncompressedSize), - this.#remainingDecodeBytes, + this.#decodeBytes.remaining, ); + if (block.uncompressedSize > this.#decodeBytes.remaining) throw exhausted(); // Charge attempts too, before I/O/allocation; failed/cancelled work is not free. this.#reserveMemberRead(); - this.#remainingDecodeBytes -= block.uncompressedSize; + this.#decodeBytes.charge(block.uncompressedSize, exhausted); const encoded = await readArtifactFileBytes( handle, this.#dataStart + block.compressedStart, diff --git a/src/artifacts/apple/InterfaceBuilderDecodeBudget.ts b/src/artifacts/apple/InterfaceBuilderDecodeBudget.ts index 7a713c7e9e..570385044a 100644 --- a/src/artifacts/apple/InterfaceBuilderDecodeBudget.ts +++ b/src/artifacts/apple/InterfaceBuilderDecodeBudget.ts @@ -1,3 +1,4 @@ +import { Budget } from "../../domain/budget.js"; import { decodeLimit, type ParseFailureError, @@ -22,45 +23,36 @@ export const interfaceBuilderDecodeBudgetExceeded = ( /** Shared byte budget for decoder records and projected archive data. */ export class InterfaceBuilderDecodeBudget { - readonly #initialBytes: number; - #remainingBytes: number; + readonly #bytes: Budget; constructor(maxBytes: number) { - this.#initialBytes = maxBytes; - this.#remainingBytes = maxBytes; + this.#bytes = new Budget(maxBytes); } /** Representation bytes still available for the current inspection. */ get remainingBytes(): number { - return this.#remainingBytes; + return this.#bytes.remaining; } /** Representation bytes reserved so far. */ get usedBytes(): number { - return this.#initialBytes - this.#remainingBytes; + return this.#bytes.used; } /** Reserve representation bytes before allocation, or report exhaustion. */ reserve(bytes: number, message: string): void { - if ( - !Number.isSafeInteger(bytes) || - bytes < 0 || - bytes > this.#remainingBytes - ) - throw interfaceBuilderDecodeBudgetExceeded( + this.#bytes.charge(bytes, () => + interfaceBuilderDecodeBudgetExceeded( "interface-builder", message, - this.#initialBytes, - ); - this.#remainingBytes -= bytes; + this.#bytes.maximum, + ), + ); } /** Return a reservation whose representation was rejected and not retained. */ release(bytes: number): void { - this.#remainingBytes = Math.min( - this.#initialBytes, - this.#remainingBytes + bytes, - ); + this.#bytes.refund(bytes); } /** Reserve an upper bound for one JSON-serialized string occurrence. */ @@ -92,13 +84,6 @@ export class InterfaceBuilderDecodeBudget { /** Reserve bytes for an optional projection without throwing on exhaustion. */ tryReserve(bytes: number): boolean { - if ( - !Number.isSafeInteger(bytes) || - bytes < 0 || - bytes > this.#remainingBytes - ) - return false; - this.#remainingBytes -= bytes; - return true; + return this.#bytes.tryCharge(bytes); } } diff --git a/src/artifacts/bun/BunModuleGraphLayout.ts b/src/artifacts/bun/BunModuleGraphLayout.ts index f465485c9d..5999f9398f 100644 --- a/src/artifacts/bun/BunModuleGraphLayout.ts +++ b/src/artifacts/bun/BunModuleGraphLayout.ts @@ -1,4 +1,5 @@ import { LC } from "../../domain/apple/machoLoadCommandCodes.js"; +import { Budget } from "../../domain/budget.js"; import { readFatContainerHeader, readMachoHeaderPrefixFacts, @@ -210,15 +211,26 @@ const METADATA_CACHE_ENTRIES = 1024; /** Exact-range caching avoids page amplification from file-controlled pointers. */ class BunGraphRangeReader implements BunGraphData { readonly #ranges = new Map(); - #retainedBytes = 0; - #readBytes = 0; + readonly #retained = new Budget(METADATA_CACHE_BYTES); + readonly #read: Budget; constructor( private readonly handle: FileHandle, private readonly start: number, readonly length: number, private readonly signal: AbortSignal | undefined, - private readonly maximumReadBytes: number, - ) {} + maximumReadBytes: number, + ) { + this.#read = new Budget(maximumReadBytes); + } + + /** Drop the least recently used range and return its retained size. */ + readonly #evictOldest = (): number | undefined => { + const oldest = this.#ranges.keys().next(); + if (oldest.done === true) return undefined; + const bytes = this.#ranges.get(oldest.value)?.length ?? 0; + this.#ranges.delete(oldest.value); + return bytes; + }; async read(offset: number, length: number): Promise { abortIfNeeded(this.signal); @@ -239,15 +251,15 @@ class BunGraphRangeReader implements BunGraphData { this.#ranges.set(key, existing); return Buffer.from(existing); } - if (length > this.maximumReadBytes - this.#readBytes) - throw artifactReaderLimitFailure( - "artifact_limits.bun.metadata_read_bytes", - this.maximumReadBytes, - "bytes", - this.#readBytes + length, - ); // Charge physical work before allocation or I/O, including uncached large names. - this.#readBytes += length; + this.#read.charge(length, () => + artifactReaderLimitFailure( + "artifact_limits.bun.metadata_read_bytes", + this.#read.maximum, + "bytes", + this.#read.used + length, + ), + ); const bytes = await readExact( this.handle, this.start + offset, @@ -255,16 +267,10 @@ class BunGraphRangeReader implements BunGraphData { this.signal, ); if (length > METADATA_CACHE_BYTES) return bytes; - while ( - this.#ranges.size >= METADATA_CACHE_ENTRIES || - this.#retainedBytes + length > METADATA_CACHE_BYTES - ) { - const oldest = this.#ranges.keys().next().value!; - this.#retainedBytes -= this.#ranges.get(oldest)!.length; - this.#ranges.delete(oldest); - } + while (this.#ranges.size >= METADATA_CACHE_ENTRIES) + this.#retained.refund(this.#evictOldest() ?? 0); + if (!this.#retained.chargeEvicting(length, this.#evictOldest)) return bytes; this.#ranges.set(key, bytes); - this.#retainedBytes += length; return Buffer.from(bytes); } } diff --git a/src/browser/PlaywrightScenarioEvents.ts b/src/browser/PlaywrightScenarioEvents.ts index 891f7ed4cc..af7e6903c8 100644 --- a/src/browser/PlaywrightScenarioEvents.ts +++ b/src/browser/PlaywrightScenarioEvents.ts @@ -11,6 +11,7 @@ import type { } from "playwright-core"; import type { SanitizedBrowserUrl } from "../domain/browserObservation.js"; +import { Budget } from "../domain/budget.js"; import { browserScenarioEventSchema, type BrowserScenarioEvent, @@ -100,7 +101,7 @@ type EventKind = BrowserScenarioEvent["kind"]; /** Arrival-ordered Playwright event capture with current-step attribution. */ export class PlaywrightScenarioEvents { private readonly items: BrowserScenarioEvent[] = []; - private retainedCost = 0; + private readonly retained: Budget; private dropped = 0; private readonly omittedKinds = new Map< EventKind, @@ -140,6 +141,7 @@ export class PlaywrightScenarioEvents { this.enabled = new Set([...this.enabled, "network"]); this.secrets = options.secrets; this.limits = options.limits ?? DEFAULT_BROWSER_SCENARIO_CAPTURE_LIMITS; + this.retained = new Budget(this.limits.max_total_event_allocation_bytes); this.ownsContext = options.ownsContext === true; this.pages.add(options.page); if (this.ownsContext && this.enabled.size > 0) { @@ -323,10 +325,10 @@ export class PlaywrightScenarioEvents { original, this.limits.max_event_allocation_bytes, ); - this.retainedCost -= oldCost; + this.retained.refund(oldCost); const available = Math.min( this.limits.max_event_allocation_bytes, - this.limits.max_total_event_allocation_bytes - this.retainedCost, + this.retained.remaining, ); const extra = eventTextUnits( original.kind === "network-content" @@ -384,11 +386,10 @@ export class PlaywrightScenarioEvents { reason = cost > this.limits.max_event_allocation_bytes ? "max-event-allocation-bytes" - : cost > available - ? "max-total-event-allocation-bytes" - : undefined; + : this.retained.tryCharge(cost) + ? undefined + : "max-total-event-allocation-bytes"; if (reason === undefined) { - this.retainedCost += cost; this.items[retained++] = event; continue; } @@ -578,17 +579,15 @@ export class PlaywrightScenarioEvents { this.sequence += 1; const cost = allocationCost(event, this.limits.max_event_allocation_bytes) + 128; - const reason = this.admissionReason(cost); - if (this.sealed || reason !== undefined) { - const finalReason = reason ?? "max-events"; - this.omitEvent(event.kind, finalReason); - return { - status: "omitted", - sequence: this.sequence, - reason: finalReason, - }; + const reason = + this.admissionReason(cost) ?? + (this.retained.tryCharge(cost) + ? undefined + : "max-total-event-allocation-bytes"); + if (reason !== undefined) { + this.omitEvent(event.kind, reason); + return { status: "omitted", sequence: this.sequence, reason }; } - this.retainedCost += cost; const parsed = browserScenarioEventSchema.parse({ ...event, sequence: this.sequence, @@ -632,7 +631,7 @@ export class PlaywrightScenarioEvents { return "max-events"; if (cost > this.limits.max_event_allocation_bytes) return "max-event-allocation-bytes"; - if (cost > this.limits.max_total_event_allocation_bytes - this.retainedCost) + if (cost > this.retained.remaining) return "max-total-event-allocation-bytes"; return undefined; } diff --git a/src/browser/WebBundleAnalysisWorker.ts b/src/browser/WebBundleAnalysisWorker.ts index e914339be9..d79f7bf2e9 100644 --- a/src/browser/WebBundleAnalysisWorker.ts +++ b/src/browser/WebBundleAnalysisWorker.ts @@ -1,4 +1,6 @@ +import { Budget } from "../domain/budget.js"; import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js"; +import { invariantViolation } from "../domain/internalInvariant.js"; import { DEFAULT_JAVASCRIPT_MEMBER_MUTATION_ALLOWANCE, javaScriptMemberMutationAllowanceField, @@ -193,7 +195,7 @@ export class WebBundleAnalysisWorker { #activeJob: WebBundleActiveJob | undefined; #activeTerminalResponseObserved = false; readonly #frameSignal = new WorkerFrameSignal(); - #retainedResultBytes = 0; + readonly #retainedResult = new Budget(WEB_BUNDLE_WORKER_LIMITS.resultBytes); #ready = false; readonly #stdout = (chunk: Buffer | string): void => { if (this.#activeDeadline?.interruption !== undefined) return; @@ -484,7 +486,10 @@ export class WebBundleAnalysisWorker { script, memberMutationAllowance, ); - this.#retainedResultBytes += descriptor.bytes; + // The descriptor was admitted against this remainder before the read. + this.#retainedResult.charge(descriptor.bytes, () => + invariantViolation("Admitted web analysis result no longer fits"), + ); completed = facts; result = ok(facts); } catch (cause) { @@ -492,13 +497,15 @@ export class WebBundleAnalysisWorker { const snapshot = completedStableArtifact(cause); if (snapshot !== undefined && resultDescriptor !== undefined) { try { - completed = this.#validateCompletedResult( + const validated = this.#validateCompletedResult( snapshot, resultDescriptor, script, memberMutationAllowance, ); - this.#retainedResultBytes += resultDescriptor.bytes; + // Retain the completed facts only when they fit what remains. + if (this.#retainedResult.tryCharge(resultDescriptor.bytes)) + completed = validated; } catch { // The physical read completed, but only validated facts are retained. } @@ -616,8 +623,7 @@ export class WebBundleAnalysisWorker { #admittedResultBudget(): | { readonly ok: true; readonly bytes: number } | { readonly ok: false; readonly error: AnalysisResourceConstraintError } { - const fixedRemaining = - WEB_BUNDLE_WORKER_LIMITS.resultBytes - this.#retainedResultBytes; + const fixedRemaining = this.#retainedResult.remaining; const hostCapacity = Math.max( 0, Math.floor( diff --git a/src/browser/execution/CdpRuntimeRequests.ts b/src/browser/execution/CdpRuntimeRequests.ts index ecdf6bd16a..c167526c95 100644 --- a/src/browser/execution/CdpRuntimeRequests.ts +++ b/src/browser/execution/CdpRuntimeRequests.ts @@ -7,7 +7,10 @@ import type { CdpReceivedEvent } from "../CdpConnection.js"; import { runtimeStackSchema } from "./CdpRuntimeProtocol.js"; import type { CdpRuntimeSources } from "./CdpRuntimeSources.js"; import { sanitizeRuntimeInitiator } from "./CdpRuntimeInitiator.js"; -import { assertRuntimeRetention } from "./CdpRuntimeRetention.js"; +import { + assertRuntimeRetention, + RuntimeRetention, +} from "./CdpRuntimeRetention.js"; type RuntimeRequestSources = Pick< CdpRuntimeSources, @@ -25,9 +28,14 @@ type RuntimeRequestSources = Pick< export class CdpRuntimeRequests { readonly items: WebExecution["requests"] = []; excluded = 0; - #bytes = 0; + readonly #retention: RuntimeRetention; #failure: AnalysisError | undefined; - constructor(readonly sources: RuntimeRequestSources) {} + constructor(readonly sources: RuntimeRequestSources) { + this.#retention = new RuntimeRetention( + sources.session.operation, + "requests", + ); + } /** Retain only armed-window requests from the selected main frame and selected origins. */ ingest(event: CdpReceivedEvent): void { @@ -98,12 +106,7 @@ export class CdpRuntimeRequests { async_parent_ids: parents, causal_attribution: "unknown", }; - this.#bytes += Buffer.byteLength(JSON.stringify(retained)); - assertRuntimeRetention( - this.sources.session.operation, - "requests", - this.#bytes, - ); + this.#retention.charge(Buffer.byteLength(JSON.stringify(retained))); this.items.push(retained); } catch (cause: unknown) { this.#failure = diff --git a/src/browser/execution/CdpRuntimeRetention.test.ts b/src/browser/execution/CdpRuntimeRetention.test.ts new file mode 100644 index 0000000000..3c22d65b95 --- /dev/null +++ b/src/browser/execution/CdpRuntimeRetention.test.ts @@ -0,0 +1,48 @@ +import { describe, expect, it } from "vitest"; + +import { WEB_RUNTIME_LIMITS } from "../../domain/webRuntime.js"; +import { RuntimeRetention } from "./CdpRuntimeRetention.js"; + +describe("RuntimeRetention", () => { + it("admits retention up to the limit and reports the total a refused charge would reach", () => { + const retention = new RuntimeRetention("observe_web_runtime", "metadata"); + retention.charge(WEB_RUNTIME_LIMITS.retainedEventBytes - 1); + retention.charge(1); + expect(() => retention.charge(5)).toThrow( + expect.objectContaining({ + reportedLimits: expect.objectContaining({ + kind: "metadata", + retained_bytes: WEB_RUNTIME_LIMITS.retainedEventBytes + 5, + limit_bytes: WEB_RUNTIME_LIMITS.retainedEventBytes, + }), + }), + ); + }); + + it("charges nothing for a refused retention", () => { + const retention = new RuntimeRetention("observe_web_runtime", "requests"); + retention.charge(10); + const room = WEB_RUNTIME_LIMITS.retainedEventBytes - 10; + expect(() => retention.charge(room + 1)).toThrow( + expect.objectContaining({ + reportedLimits: expect.objectContaining({ + retained_bytes: WEB_RUNTIME_LIMITS.retainedEventBytes + 1, + }), + }), + ); + // The refused charge left the remaining room intact. + expect(() => retention.charge(room)).not.toThrow(); + }); + + it("keeps the source-text limit separate from metadata", () => { + const retention = new RuntimeRetention("observe_web_runtime", "sources"); + expect(() => retention.charge(WEB_RUNTIME_LIMITS.sourceBytes + 1)).toThrow( + expect.objectContaining({ + reportedLimits: expect.objectContaining({ + kind: "sources", + limit_bytes: WEB_RUNTIME_LIMITS.sourceBytes, + }), + }), + ); + }); +}); diff --git a/src/browser/execution/CdpRuntimeRetention.ts b/src/browser/execution/CdpRuntimeRetention.ts index 7143fbde7c..583505807f 100644 --- a/src/browser/execution/CdpRuntimeRetention.ts +++ b/src/browser/execution/CdpRuntimeRetention.ts @@ -1,20 +1,23 @@ import { AnalysisResourceConstraintError } from "../../domain/analysisErrorCore.js"; +import { Budget } from "../../domain/budget.js"; import { fixedAllowanceOptions } from "../../domain/fixedAllowanceRemediation.js"; import { WEB_RUNTIME_LIMITS } from "../../domain/webRuntime.js"; -/** Enforce the retained runtime representation, separately from wire payloads. */ -export const assertRuntimeRetention = ( +type RuntimeRetentionKind = "metadata" | "requests" | "sources"; + +const retentionLimit = (kind: RuntimeRetentionKind): number => + kind === "sources" + ? WEB_RUNTIME_LIMITS.sourceBytes + : WEB_RUNTIME_LIMITS.retainedEventBytes; + +const retentionExceeded = ( operation: string, - kind: "metadata" | "requests" | "sources", + kind: RuntimeRetentionKind, retainedBytes: number, -): void => { - const limit = - kind === "sources" - ? WEB_RUNTIME_LIMITS.sourceBytes - : WEB_RUNTIME_LIMITS.retainedEventBytes; - if (retainedBytes <= limit) return; +): AnalysisResourceConstraintError => { + const limit = retentionLimit(kind); const allowance = `Complete browser runtime ${kind} retention (${String(limit)} bytes)`; - throw new AnalysisResourceConstraintError( + return new AnalysisResourceConstraintError( operation, "capacity", `${allowance} exceeded; no partial runtime result is returned.`, @@ -27,3 +30,32 @@ export const assertRuntimeRetention = ( fixedAllowanceOptions(allowance, "live"), ); }; + +/** Enforce the retained runtime representation, separately from wire payloads. */ +export const assertRuntimeRetention = ( + operation: string, + kind: RuntimeRetentionKind, + retainedBytes: number, +): void => { + if (retainedBytes > retentionLimit(kind)) + throw retentionExceeded(operation, kind, retainedBytes); +}; + +/** Cumulative retention of one runtime kind across a capture. */ +export class RuntimeRetention { + readonly #bytes: Budget; + + constructor( + readonly operation: string, + readonly kind: RuntimeRetentionKind, + ) { + this.#bytes = new Budget(retentionLimit(kind)); + } + + /** Charge `bytes` before retaining them, or throw the retention failure. */ + charge(bytes: number): void { + this.#bytes.charge(bytes, () => + retentionExceeded(this.operation, this.kind, this.#bytes.used + bytes), + ); + } +} diff --git a/src/browser/execution/CdpRuntimeSources.ts b/src/browser/execution/CdpRuntimeSources.ts index 3f3118069c..98db8f0e6c 100644 --- a/src/browser/execution/CdpRuntimeSources.ts +++ b/src/browser/execution/CdpRuntimeSources.ts @@ -16,7 +16,7 @@ import { cdpContextFrameClaim, selectCdpScriptFrame, } from "../CdpScriptContextFacts.js"; -import { assertRuntimeRetention } from "./CdpRuntimeRetention.js"; +import { RuntimeRetention } from "./CdpRuntimeRetention.js"; /** Source ownership is proven by execution context/frame metadata, independently of URL aliases. */ export class CdpRuntimeSources { @@ -31,10 +31,13 @@ export class CdpRuntimeSources { readonly #changed = new Set(); readonly #changedContexts = new Set(); readonly #sources = new Map(); - #retainedBytes = 0; - #sourceBytes = 0; + readonly #metadata: RuntimeRetention; + readonly #sourceText: RuntimeRetention; #failure: AnalysisError | undefined; - constructor(readonly session: CdpRuntimeSession) {} + constructor(readonly session: CdpRuntimeSession) { + this.#metadata = new RuntimeRetention(session.operation, "metadata"); + this.#sourceText = new RuntimeRetention(session.operation, "sources"); + } /** Subscribe before enabling Debugger; existing uncollected scripts are replayed by the producer. */ ingest(event: CdpReceivedEvent, retainNewMetadata = true): void { @@ -44,12 +47,7 @@ export class CdpRuntimeSources { if (registered?.method === "Runtime.executionContextCreated") { const bytes = registered.payload.declarationBytes; if (!bytes.ok) throw bytes.error; - this.#retainedBytes += bytes.value; - assertRuntimeRetention( - this.session.operation, - "metadata", - this.#retainedBytes, - ); + this.#metadata.charge(bytes.value); const declaration = registered.payload.runtime; if (!declaration.success) throw declaration.error; const context = declaration.data.context; @@ -66,12 +64,7 @@ export class CdpRuntimeSources { } else if (registered?.method === "Debugger.scriptParsed") { const bytes = registered.payload.declarationBytes; if (!bytes.ok) throw bytes.error; - this.#retainedBytes += bytes.value; - assertRuntimeRetention( - this.session.operation, - "metadata", - this.#retainedBytes, - ); + this.#metadata.charge(bytes.value); const declaration = registered.payload.runtime; if (!declaration.success) throw declaration.error; const script = declaration.data; @@ -266,12 +259,7 @@ export class CdpRuntimeSources { reason: cause.userMessage ?? cause.message, }; } - this.#sourceBytes += Buffer.byteLength(text); - assertRuntimeRetention( - this.session.operation, - "sources", - this.#sourceBytes, - ); + this.#sourceText.charge(Buffer.byteLength(text)); const facts = webTextFacts(text); return { state: "captured", diff --git a/src/desktop/DesktopContentStore.test.ts b/src/desktop/DesktopContentStore.test.ts index 443a34c9af..dd947945f3 100644 --- a/src/desktop/DesktopContentStore.test.ts +++ b/src/desktop/DesktopContentStore.test.ts @@ -49,6 +49,19 @@ it("DesktopContentStore leaves an occupied partial filename unowned", async () = expect(await readFile(partial, "utf8")).toBe("foreign content"); }); +it("DesktopContentStore charges nothing for a write that fails", async () => { + const root = await createTestTempDirectory("desktop-content-failed-charge-"); + const content = await store(root, 1024, 8); + await mkdir(join(content.directory, sha256("12345678"))); + await expect(content.retainBytes(Buffer.from("12345678"))).rejects.toThrow(); + // The whole budget is still available to the next content. + await expect(content.retainBytes(Buffer.from("abcdefgh"))).resolves.toEqual({ + kind: "retained", + sha256: sha256("abcdefgh"), + size: 8, + }); +}); + it("DesktopContentStore retains every unpublished file until discard", async () => { const root = await createTestTempDirectory("desktop-content-unpublished-"); const content = await store(root, 1024, 1024); diff --git a/src/desktop/DesktopContentStore.ts b/src/desktop/DesktopContentStore.ts index a1d8823342..0ca947fcc5 100644 --- a/src/desktop/DesktopContentStore.ts +++ b/src/desktop/DesktopContentStore.ts @@ -4,6 +4,7 @@ import { mkdir, open, rename, rm, rmdir } from "node:fs/promises"; import { join } from "node:path"; import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js"; +import { Budget } from "../domain/budget.js"; import type { DesktopApplicationCapture } from "../domain/desktop/desktopCapture.js"; import type { DesktopPathState } from "../domain/desktop/desktopStateDiff.js"; import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js"; @@ -50,7 +51,7 @@ export class DesktopContentStore { readonly #unclosed = new ArtifactResourceScope(); /** Every partial file this store created but has not published or removed. */ readonly #unpublished = new Set(); - #remainingBytes: number; + readonly #bytes: Budget; constructor( captureDirectory: string, @@ -59,7 +60,7 @@ export class DesktopContentStore { ) { this.#directory = join(captureDirectory, "content"); this.#maxFileBytes = maxFileBytes; - this.#remainingBytes = maxBytes; + this.#bytes = new Budget(maxBytes); } /** Create the private content directory; it must not exist yet. */ @@ -145,8 +146,21 @@ export class DesktopContentStore { if (size > this.#maxFileBytes) return { kind: "omitted", reason: "too_large" }; if (this.#stored.has(sha256)) return { kind: "retained", sha256, size }; - if (size > this.#remainingBytes) + // Reserve before writing; a write that fails retains nothing. + if (!this.#bytes.tryCharge(size)) return { kind: "omitted", reason: "budget_exhausted" }; + try { + await this.#publish(sha256, bytes); + } catch (error) { + this.#bytes.refund(size); + throw error; + } + this.#stored.set(sha256, size); + this.#storedSizes.add(size); + return { kind: "retained", sha256, size }; + } + + async #publish(sha256: string, bytes: Buffer): Promise { const target = join(this.#directory, sha256); const partial = `${target}.partial`; const owner = new OwnedFileHandle(await open(partial, "wx", 0o600)); @@ -167,10 +181,6 @@ export class DesktopContentStore { ); await rename(partial, target); this.#unpublished.delete(partial); - this.#stored.set(sha256, size); - this.#storedSizes.add(size); - this.#remainingBytes -= size; - return { kind: "retained", sha256, size }; } async #read( @@ -187,7 +197,7 @@ export class DesktopContentStore { return { kind: "omitted", reason: "too_large" }; // Over budget, only a size some stored content has can still be a duplicate. if ( - expected.size > this.#remainingBytes && + expected.size > this.#bytes.remaining && !this.#storedSizes.has(expected.size) ) return { kind: "omitted", reason: "budget_exhausted" }; diff --git a/src/domain/analysisView/WebNetworkProjectionAccumulator.ts b/src/domain/analysisView/WebNetworkProjectionAccumulator.ts index e503a8c857..66e13ad1a9 100644 --- a/src/domain/analysisView/WebNetworkProjectionAccumulator.ts +++ b/src/domain/analysisView/WebNetworkProjectionAccumulator.ts @@ -1,4 +1,5 @@ import { z } from "zod"; +import { Budget } from "../budget.js"; import { fixedAllowanceOptions } from "../fixedAllowanceRemediation.js"; import { AnalysisResourceConstraintError, @@ -24,8 +25,11 @@ import { /** Shared retained/temporary byte accounting for views that group retained HAR records. */ export abstract class WebNetworkProjectionAccumulator { readonly #limitations = new Set(); - #retainedBytes = 0; - #temporaryBytes = 0; + /** Retained state and temporary work share one allowance. */ + readonly #bytes: Budget; + /** The retained and temporary shares of `#bytes`, for their checkpoints. */ + readonly #retained: Budget; + readonly #temporary: Budget; /** Per-record scratch reservation handed to the shared record readers. */ protected readonly scratch: Reserve = (bytes) => this.temporary(bytes); @@ -33,41 +37,53 @@ export abstract class WebNetworkProjectionAccumulator { readonly maximumBytes: number, private readonly budgetSubject: string, private readonly operation = "inspect_analysis_view", - ) {} + ) { + this.#bytes = new Budget(maximumBytes); + this.#retained = new Budget(maximumBytes); + this.#temporary = new Budget(maximumBytes); + } + + #charge(share: Budget, bytes: number): boolean { + if (!this.#bytes.tryCharge(bytes)) return false; + // A share never exceeds the whole, so it always fits. + return share.tryCharge(bytes); + } + + #restore(share: Budget, mark: number): void { + this.#bytes.refund(share.restore(mark)); + } protected retain(bytes: number): boolean { - if (this.#retainedBytes + this.#temporaryBytes + bytes > this.maximumBytes) - return false; - this.#retainedBytes += bytes; - return true; + return this.#charge(this.#retained, bytes); } protected temporary(bytes: number): boolean { - if (this.#retainedBytes + this.#temporaryBytes + bytes > this.maximumBytes) - return false; - this.#temporaryBytes += bytes; - return true; + return this.#charge(this.#temporary, bytes); } - /** Restore the enclosing synchronous parse's scratch after a nested body lease. */ + /** + * Release the scratch charged by a nested body lease. Leases end in LIFO + * order and `releaseTemporary` never runs inside one, so the enclosing + * parse's scratch is still charged when this runs. + */ protected temporaryCheckpoint(): () => void { - const held = this.#temporaryBytes; + const mark = this.#temporary.used; return () => { - this.#temporaryBytes = held; + this.#restore(this.#temporary, mark); }; } /** 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; + const mark = this.#retained.used; return () => { - this.#retainedBytes = Math.min(this.#retainedBytes, mark); + this.#restore(this.#retained, mark); }; } /** Per-record strings and descriptors never become cumulative scratch. */ protected releaseTemporary(): void { - this.#temporaryBytes = 0; + this.#restore(this.#temporary, 0); } protected overBudget(): Result { diff --git a/src/domain/apiContract/parseApiContract.ts b/src/domain/apiContract/parseApiContract.ts index e98446a42d..a846d27108 100644 --- a/src/domain/apiContract/parseApiContract.ts +++ b/src/domain/apiContract/parseApiContract.ts @@ -1,3 +1,4 @@ +import { Budget } from "../budget.js"; import { escapeJsonPointerToken } from "../jsonPointer.js"; import { AnalysisCancelledError, @@ -60,14 +61,13 @@ class ContractInventory { readonly operations: ApiContract["operations"] = []; readonly references: ApiContract["path_item_references"] = []; readonly diagnostics: ApiContractDiagnostic[] = []; - #retainedBytes = 0; + readonly #retainedBytes = new Budget(API_CONTRACT_FACT_BYTES); constructor(readonly artifact: ApiContractArtifact) {} reserve(bytes: number): Result { // Includes object/index overhead and repeated escaped Evidence delivery, not just source bytes. - this.#retainedBytes += bytes; - return this.#retainedBytes <= API_CONTRACT_FACT_BYTES + return this.#retainedBytes.tryCharge(bytes) ? ok(undefined) : err( new AnalysisResourceConstraintError( diff --git a/src/domain/budget.test.ts b/src/domain/budget.test.ts index 0ea67be1aa..cb2622bd83 100644 --- a/src/domain/budget.test.ts +++ b/src/domain/budget.test.ts @@ -37,6 +37,43 @@ describe("Budget", () => { }).toThrow(/refund/u); }); + it("evicts the oldest entries until a charge fits", () => { + const budget = new Budget(10); + const entries = [4, 3, 2]; + for (const size of entries) budget.charge(size, exhausted); + const evict = () => { + const oldest = entries.shift(); + return oldest; + }; + expect(budget.chargeEvicting(6, evict)).toBe(true); + // 9 used: evicting 4 frees 5, still short of 6; evicting 3 makes room. + expect(entries).toEqual([2]); + expect(budget.used).toBe(8); + // Larger than the maximum: nothing is evicted. + expect(budget.chargeEvicting(11, evict)).toBe(false); + expect(entries).toEqual([2]); + expect(budget.used).toBe(8); + }); + + it("refuses an evicting charge when nothing is left to evict", () => { + const budget = new Budget(10); + budget.charge(8, exhausted); + expect(budget.chargeEvicting(5, () => undefined)).toBe(false); + expect(budget.used).toBe(8); + }); + + it("restores a checkpoint by refunding, never by re-charging", () => { + const budget = new Budget(10); + budget.charge(3, exhausted); + const mark = budget.used; + budget.charge(5, exhausted); + expect(budget.restore(mark)).toBe(5); + expect(budget.used).toBe(3); + budget.refund(3); + expect(budget.restore(mark)).toBe(0); + expect(budget.used).toBe(0); + }); + it("rejects a malformed maximum", () => { expect(() => new Budget(-1)).toThrow(/maximum/u); }); diff --git a/src/domain/budget.ts b/src/domain/budget.ts index 3f88e0bf7a..2f989fdf53 100644 --- a/src/domain/budget.ts +++ b/src/domain/budget.ts @@ -44,6 +44,33 @@ export class Budget { if (!this.tryCharge(amount)) throw exhausted(); } + /** + * Charge `amount` into a cache, evicting entries until it fits. `evict` + * discards the oldest entry and returns its charged amount, or `undefined` + * when nothing is left to evict. An amount above the maximum evicts nothing + * and returns false. + */ + chargeEvicting(amount: number, evict: () => number | undefined): boolean { + if (!isAmount(amount) || amount > this.maximum) return false; + while (amount > this.remaining) { + const freed = evict(); + if (freed === undefined) return false; + this.refund(freed); + } + return this.tryCharge(amount); + } + + /** + * Refund everything charged since `mark`, a value of `used` taken earlier, + * and return the refunded amount. A mark at or above the current use refunds + * nothing: restoring never re-charges, because a re-charge could fail. + */ + restore(mark: number): number { + const released = Math.max(0, this.#used - mark); + this.refund(released); + return released; + } + /** Return a reservation that was not retained. */ refund(amount: number): void { if (!isAmount(amount)) diff --git a/src/domain/firmware/hexRecords.ts b/src/domain/firmware/hexRecords.ts index d1e8fdd690..338d51d9c4 100644 --- a/src/domain/firmware/hexRecords.ts +++ b/src/domain/firmware/hexRecords.ts @@ -108,7 +108,7 @@ class StreamingHexRecordDecoder implements RegionDecoder { readonly #line: Uint8Array; readonly #runs: RecordRun[] = []; #arena: Uint8Array; - #arenaUsed = 0; + #arenaWriteOffset = 0; #lineLength = 0; #lineNumber = 0; #recordCount = 0; @@ -330,7 +330,7 @@ class StreamingHexRecordDecoder implements RegionDecoder { data: Uint8Array, ): Result { if (data.length === 0) return ok(undefined); - if (this.#arenaUsed + data.length > this.#arena.length) + if (this.#arenaWriteOffset + data.length > this.#arena.length) return err({ kind: "limit", boundary: "file-size", @@ -350,15 +350,15 @@ class StreamingHexRecordDecoder implements RegionDecoder { }); this.#runs.push({ address, - offset: this.#arenaUsed, + offset: this.#arenaWriteOffset, length: data.length, recordCount: 1, firstLine: this.#lineNumber, lastLine: this.#lineNumber, }); } - this.#arena.set(data, this.#arenaUsed); - this.#arenaUsed += data.length; + this.#arena.set(data, this.#arenaWriteOffset); + this.#arenaWriteOffset += data.length; return ok(undefined); } diff --git a/src/domain/firmware/uf2.ts b/src/domain/firmware/uf2.ts index d5ea5a4b76..5329dfe3ab 100644 --- a/src/domain/firmware/uf2.ts +++ b/src/domain/firmware/uf2.ts @@ -161,7 +161,7 @@ class StreamingUf2Decoder implements RegionDecoder { readonly #groups = new Map(); readonly #families = new Set(); #arena: Uint8Array; - #arenaUsed = 0; + #arenaWriteOffset = 0; #blockLength = 0; #blockCount = 0; #invalid = 0; @@ -325,7 +325,7 @@ class StreamingUf2Decoder implements RegionDecoder { data: Uint8Array, ): Result { if (data.length === 0) return ok(undefined); - if (this.#arenaUsed + data.length > this.#arena.length) + if (this.#arenaWriteOffset + data.length > this.#arena.length) return err({ kind: "limit", boundary: "file-size", @@ -344,14 +344,14 @@ class StreamingUf2Decoder implements RegionDecoder { this.#runs.push({ familyId, address, - offset: this.#arenaUsed, + offset: this.#arenaWriteOffset, length: data.length, blockCount: 1, firstFileBlock: block, lastFileBlock: block, }); - this.#arena.set(data, this.#arenaUsed); - this.#arenaUsed += data.length; + this.#arena.set(data, this.#arenaWriteOffset); + this.#arenaWriteOffset += data.length; return ok(undefined); } diff --git a/src/domain/javascript/javascriptSemanticWorkAllowance.ts b/src/domain/javascript/javascriptSemanticWorkAllowance.ts index 0aa5b4428b..ea6c7f477d 100644 --- a/src/domain/javascript/javascriptSemanticWorkAllowance.ts +++ b/src/domain/javascript/javascriptSemanticWorkAllowance.ts @@ -1,4 +1,5 @@ import { z } from "zod"; +import { Budget } from "../budget.js"; import type { AnalysisCapturedOutput } from "../analysisErrorBase.js"; import { AnalysisResourceConstraintError } from "../analysisErrorCore.js"; import { @@ -123,18 +124,20 @@ export const reportsJavaScriptMemberMutationRefusal = ( * mutation index would let later reads keep stale values. */ export class JavaScriptSemanticWorkMeter { - #used = 0; + readonly #aliasStates: Budget; constructor( readonly allowance: JavaScriptMemberMutationAllowance = DEFAULT_JAVASCRIPT_MEMBER_MUTATION_ALLOWANCE, - ) {} + ) { + this.#aliasStates = new Budget(allowance.aliasStates); + } charge(units = 1): void { - this.#used += units; - if (this.#used <= this.allowance.aliasStates) return; - throw javaScriptMemberMutationRefusal( - "analyze_javascript_semantics", - this.allowance, + this.#aliasStates.charge(units, () => + javaScriptMemberMutationRefusal( + "analyze_javascript_semantics", + this.allowance, + ), ); } } diff --git a/src/domain/javascript/javascriptSymbolicBindings.ts b/src/domain/javascript/javascriptSymbolicBindings.ts index 419253ca19..11378984b2 100644 --- a/src/domain/javascript/javascriptSymbolicBindings.ts +++ b/src/domain/javascript/javascriptSymbolicBindings.ts @@ -1,4 +1,5 @@ import * as t from "@babel/types"; +import { Budget } from "../budget.js"; import { staticObjectPropertyReader, readExactJavaScriptLiteral, @@ -122,7 +123,7 @@ export class JavaScriptSymbolicBindings { readonly tableAliases: ReadonlySet; readonly modules: Map; }> = []; - #remainingEvaluations: number; + readonly #wrapperVisits: Budget; #depth = 0; readonly resourceLimits = new Set<"wrapper_visits" | "wrapper_depth">(); @@ -138,7 +139,7 @@ export class JavaScriptSymbolicBindings { indexJavaScriptElectronIdentitySteps(program, state), ), ) { - this.#remainingEvaluations = state.precision.wrapper_visits; + this.#wrapperVisits = new Budget(state.precision.wrapper_visits); this.#electronIdentity = electronIdentity; const shapes = createSemanticExpressionShapeResolver(state); const defineProperty = createGlobalReferenceReader(state, [ @@ -229,18 +230,22 @@ export class JavaScriptSymbolicBindings { /** Shared admission; cache hits keep their existing depth-free fast path. */ #admitEvaluation(): boolean { - if ( - --this.#remainingEvaluations < 0 || - this.#depth >= this.state.precision.wrapper_depth - ) { - this.resourceLimits.add( - this.#remainingEvaluations < 0 ? "wrapper_visits" : "wrapper_depth", - ); + if (!this.#spendWrapperVisits(1)) return false; + if (this.#depth >= this.state.precision.wrapper_depth) { + this.resourceLimits.add("wrapper_depth"); return false; } return true; } + /** Spend `cost` wrapper visits; past the allowance, spend the rest and record the limit. */ + #spendWrapperVisits(cost: number): boolean { + if (this.#wrapperVisits.tryCharge(cost)) return true; + this.#wrapperVisits.tryCharge(this.#wrapperVisits.remaining); + this.resourceLimits.add("wrapper_visits"); + return false; + } + evaluate( input: t.Node | null | undefined, environment?: SymbolicEnvironment, @@ -282,12 +287,8 @@ export class JavaScriptSymbolicBindings { (conditions.length ? conditions.length + (variant.conditions?.length ?? 0) : 0); - if (cost > this.#remainingEvaluations) { - this.#remainingEvaluations = 0; - this.resourceLimits.add("wrapper_visits"); + if (!this.#spendWrapperVisits(cost)) return symbolicUnknown("symbolic condition resource limit"); - } - this.#remainingEvaluations -= cost; } return symbolicUnion( variants.map((variant) => ({ @@ -333,12 +334,7 @@ export class JavaScriptSymbolicBindings { const group = first === undefined ? undefined : this.#completionGroups.get(first); if (group === undefined || group.members.size !== values.length) return []; - if (values.length > this.#remainingEvaluations) { - this.resourceLimits.add("wrapper_visits"); - this.#remainingEvaluations = 0; - return []; - } - this.#remainingEvaluations -= values.length; + if (!this.#spendWrapperVisits(values.length)) return []; // Only the complete, original partition proves an unconditional fact. // Added predicates or a subset of exits cannot borrow this proof. if (!values.every((value) => group.members.has(value))) return []; @@ -1000,10 +996,7 @@ export class JavaScriptSymbolicBindings { current; current = current.parent ) { - if (--this.#remainingEvaluations < 0) { - this.resourceLimits.add("wrapper_visits"); - return false; - } + if (!this.#spendWrapperVisits(1)) return false; if (current.activation === activation) return true; } return false; @@ -1019,10 +1012,7 @@ export class JavaScriptSymbolicBindings { current.caller !== undefined; current = current.caller ) { - if (--this.#remainingEvaluations < 0) { - this.resourceLimits.add("wrapper_visits"); - return undefined; - } + if (!this.#spendWrapperVisits(1)) return undefined; const point = current.point; if ( point !== undefined && @@ -1050,7 +1040,7 @@ export class JavaScriptSymbolicBindings { const completedAt = value.environment.completedAt; const boundary = read === undefined ? undefined : this.#namespaceReadBoundary(value, read); - if (this.#remainingEvaluations <= 0) { + if (this.#wrapperVisits.remaining === 0) { this.resourceLimits.add("wrapper_visits"); return undefined; } @@ -1069,12 +1059,7 @@ export class JavaScriptSymbolicBindings { const commonThrough = value.environment.commonThrough?.end; const changed = new Set(); if (commonThrough != null) { - if (writes.length > this.#remainingEvaluations) { - this.#remainingEvaluations = 0; - this.resourceLimits.add("wrapper_visits"); - return undefined; - } - this.#remainingEvaluations -= writes.length; + if (!this.#spendWrapperVisits(writes.length)) return undefined; for (const write of writes) { if (write.site.end == null) return undefined; if ( @@ -1234,11 +1219,7 @@ export class JavaScriptSymbolicBindings { !variant.conditionUnresolved, ) ) { - if (variants.length > this.#remainingEvaluations) { - this.#remainingEvaluations = 0; - this.resourceLimits.add("wrapper_visits"); - } else { - this.#remainingEvaluations -= variants.length; + if (this.#spendWrapperVisits(variants.length)) { const exits = variants as readonly SymbolicNamespace[]; let first = exits[0]!.environment.completedAt!; let last = first; @@ -1366,13 +1347,9 @@ export class JavaScriptSymbolicBindings { ...(unresolvedFallthrough ? { conditionUnresolved: true } : {}), }); for (const statement of statements) { - if ( - --this.#remainingEvaluations < 0 || - depth >= this.state.precision.wrapper_depth - ) { - this.resourceLimits.add( - this.#remainingEvaluations < 0 ? "wrapper_visits" : "wrapper_depth", - ); + const visited = this.#spendWrapperVisits(1); + if (!visited || depth >= this.state.precision.wrapper_depth) { + if (visited) this.resourceLimits.add("wrapper_depth"); return { values: [...possible, symbolicUnknown("symbolic resource limit")], fallsThrough: false, diff --git a/src/domain/native/nativeAotPe.ts b/src/domain/native/nativeAotPe.ts index 4c63988dee..211472463c 100644 --- a/src/domain/native/nativeAotPe.ts +++ b/src/domain/native/nativeAotPe.ts @@ -1,3 +1,4 @@ +import { Budget } from "../budget.js"; import { observeMzWindowsHeader } from "../dosMz.js"; import { createHash } from "node:crypto"; import { readPeOptionalHeaderFixedFields } from "../peOptionalHeader.js"; @@ -63,8 +64,8 @@ export const DEFAULT_NATIVE_AOT_PARSER_LIMITS: NativeAotParserLimits = nativeAotParserLimitsFor(NATIVE_AOT_MAX_SOURCE_BYTES); class NativeAotParserBudget { - workUnits = 0; - workingMemoryBytes = 0; + readonly #work: Budget; + readonly #workingMemory: Budget; workingMemoryBytesPeak = 0; truncationReason: | "work-unit-budget" @@ -72,40 +73,41 @@ class NativeAotParserBudget { | "response-budget" | undefined; - constructor(readonly limits: NativeAotParserLimits) {} + constructor(readonly limits: NativeAotParserLimits) { + this.#work = new Budget(limits.workUnits); + this.#workingMemory = new Budget(limits.workingMemoryBytes); + } + + /** Work units consumed so far. */ + get workUnits(): number { + return this.#work.used; + } + + /** Working-memory bytes still available. */ + get remainingWorkingMemoryBytes(): number { + return this.#workingMemory.remaining; + } consumeWork(bytes: number): boolean { - if ( - !Number.isSafeInteger(bytes) || - bytes < 0 || - bytes > this.limits.workUnits - this.workUnits - ) { - this.truncationReason ??= "work-unit-budget"; - return false; - } - this.workUnits += bytes; - return true; + if (this.#work.tryCharge(bytes)) return true; + this.truncationReason ??= "work-unit-budget"; + return false; } reserveWorkingMemory(bytes: number): boolean { - if ( - !Number.isSafeInteger(bytes) || - bytes < 0 || - bytes > this.limits.workingMemoryBytes - this.workingMemoryBytes - ) { + if (!this.#workingMemory.tryCharge(bytes)) { this.truncationReason ??= "working-memory-budget"; return false; } - this.workingMemoryBytes += bytes; this.workingMemoryBytesPeak = Math.max( this.workingMemoryBytesPeak, - this.workingMemoryBytes, + this.#workingMemory.used, ); return true; } releaseWorkingMemory(bytes: number): void { - this.workingMemoryBytes = Math.max(0, this.workingMemoryBytes - bytes); + this.#workingMemory.refund(bytes); } } @@ -1103,7 +1105,7 @@ const hydrate = ( const initialCapacity = Math.min( outputLimit, 64 * 1024, - budget.limits.workingMemoryBytes - budget.workingMemoryBytes, + budget.remainingWorkingMemoryBytes, ); if (!budget.reserveWorkingMemory(initialCapacity)) parserBudgetExhausted(budget, "working-memory"); diff --git a/src/dotnet/ManagedDecodeBudget.ts b/src/dotnet/ManagedDecodeBudget.ts index 36082f44b1..ed2428ecb6 100644 --- a/src/dotnet/ManagedDecodeBudget.ts +++ b/src/dotnet/ManagedDecodeBudget.ts @@ -1,4 +1,5 @@ import { createHash } from "node:crypto"; +import { Budget } from "../domain/budget.js"; import { invariantViolation } from "../domain/internalInvariant.js"; import { jsonStringByteLength } from "../domain/jsonStringByteLength.js"; @@ -26,7 +27,8 @@ interface CachedString { /** The layout owns decoding capacity and heap identity for all of its consumers. */ export class ManagedDecodeBudget { - #remaining: number; + readonly #bytes: Budget; + /** Part of the charge that `releaseTransient` refunds. */ #transient = 0; readonly #rows = new Map>(); readonly #strings = new Map(); @@ -38,12 +40,14 @@ export class ManagedDecodeBudget { throw invariantViolation( "max_metadata_representation_bytes must be a positive safe integer", ); - this.#remaining = maximumBytes; + this.#bytes = new Budget(maximumBytes); } reserve(bytes: number, offset: number | null): void { - this.#admit(bytes, offset); - this.#remaining -= bytes; + this.#bytes.charge( + bytes, + () => new ManagedRepresentationFailure(offset, this.maximumBytes), + ); } /** Retain one bookkeeping reservation per physical row, independently of lookup replay. */ @@ -60,24 +64,16 @@ export class ManagedDecodeBudget { /** Bound a decoding allocation that stays live until `releaseTransient`; only retained output is reserved. */ admitTransient(bytes: number, offset: number | null): void { - this.#admit(bytes, offset); + this.reserve(bytes, offset); this.#transient += bytes; } /** End the current item's decoding; its bookkeeping is unreachable and only reserved output remains. */ releaseTransient(): void { + this.#bytes.refund(this.#transient); this.#transient = 0; } - #admit(bytes: number, offset: number | null): void { - if ( - !Number.isSafeInteger(bytes) || - bytes < 0 || - bytes > this.#remaining - this.#transient - ) - throw new ManagedRepresentationFailure(offset, this.maximumBytes); - } - /** UTF-8 cannot decode to more UTF-16 units than bytes; JSON uses at most six bytes per unit. */ reserveString(encodedBytes: number, offset: number | null): void { this.reserve(encodedBytes * 6 + 2, offset); diff --git a/src/gpu/CudaInfo.ts b/src/gpu/CudaInfo.ts index 67a12a4dbf..128844d9a4 100644 --- a/src/gpu/CudaInfo.ts +++ b/src/gpu/CudaInfo.ts @@ -3,40 +3,47 @@ import { BinaryResourceFailure, } from "../native/metadata/BinaryContainer.js"; import { GPU_OBJECT_BYTES, GPU_REPORT_BYTES, rejectGpu } from "./GpuSource.js"; +import { Budget } from "../domain/budget.js"; import { jsonValueByteLength } from "../domain/jsonValueByteLength.js"; import type { JsonValue } from "../domain/jsonValue.js"; /** Shared by every metadata record, symbol and temporary index in one CUDA ELF. */ export class CudaMetadataBudget { - #visits = 0; - #readBytes = 0; - #indexBytes = 0; + readonly #visits = new Budget(262144); + readonly #readBytes = new Budget(GPU_OBJECT_BYTES); + readonly #indexBytes = new Budget(GPU_REPORT_BYTES); visit(): void { - if (++this.#visits > 262144) - throw new BinaryResourceFailure( - "structure", - 262144, - "CUDA metadata exceeds 262144 aggregate record/symbol visits", - ); + this.#visits.charge( + 1, + () => + new BinaryResourceFailure( + "structure", + 262144, + "CUDA metadata exceeds 262144 aggregate record/symbol visits", + ), + ); } read(size: number): void { - if (size > GPU_OBJECT_BYTES - this.#readBytes) - throw new BinaryResourceFailure( - "structure", - GPU_OBJECT_BYTES, - "CUDA metadata exceeds 128 MiB aggregate section reads", - ); - this.#readBytes += size; + this.#readBytes.charge( + size, + () => + new BinaryResourceFailure( + "structure", + GPU_OBJECT_BYTES, + "CUDA metadata exceeds 128 MiB aggregate section reads", + ), + ); } retain(value: JsonValue): void { - const size = jsonValueByteLength(value, GPU_REPORT_BYTES) + 2; - if (size > GPU_REPORT_BYTES - this.#indexBytes) - throw new BinaryResourceFailure( - "structure", - GPU_REPORT_BYTES, - "CUDA metadata exceeds the 16 MiB temporary index budget", - ); - this.#indexBytes += size; + this.#indexBytes.charge( + jsonValueByteLength(value, GPU_REPORT_BYTES) + 2, + () => + new BinaryResourceFailure( + "structure", + GPU_REPORT_BYTES, + "CUDA metadata exceeds the 16 MiB temporary index budget", + ), + ); } } interface CudaInfoRecord { diff --git a/src/python/PythonPycParser.ts b/src/python/PythonPycParser.ts index e54334562c..a82b7745dd 100644 --- a/src/python/PythonPycParser.ts +++ b/src/python/PythonPycParser.ts @@ -25,6 +25,7 @@ import { type PythonPycCodeObject, type PythonPycConst, } from "../domain/python/pythonPyc.js"; +import { Budget } from "../domain/budget.js"; import { malformedInput, unsupportedInput } from "../domain/parseFailure.js"; import { BinaryReader } from "../native/metadata/BinaryContainer.js"; import { @@ -342,8 +343,9 @@ class PycMarshalReader extends MarshalReader { * bound. Absent while a container is still on the explicit walk stack. */ readonly #nestedCache = new WeakMap(); - #nestedSteps = 0; - #nestedRetained = 0; + /** Walk steps and retained code references share max_objects * max_depth. */ + readonly #nestedSteps: Budget; + readonly #nestedRetained: Budget; constructor( bytes: Buffer, @@ -364,6 +366,8 @@ class PycMarshalReader extends MarshalReader { previewLimit: PYTHON_PYC_CONST_PREVIEW_LIMIT, publishContainers: "before-items", }); + this.#nestedSteps = new Budget(input.max_objects * input.max_depth); + this.#nestedRetained = new Budget(input.max_objects * input.max_depth); } protected wrap(value: MarshalCoreValue): MarshalValue { @@ -756,7 +760,7 @@ class PycMarshalReader extends MarshalReader { if (this.#memoizeNested(value, added)) { for (const entry of added) { this.#nestedCache.delete(entry.value); - this.#nestedRetained -= entry.retained; + this.#nestedRetained.refund(entry.retained); } const walked = this.#walkNested(value); this.#nestedCache.set(value, walked); @@ -801,12 +805,12 @@ class PycMarshalReader extends MarshalReader { }); continue; } - const retainedBefore = this.#nestedRetained; + const retainedBefore = this.#nestedRetained.used; const codes = this.#combineNested(frame.children); this.#nestedCache.set(frame.value, codes); added.push({ value: frame.value, - retained: this.#nestedRetained - retainedBefore, + retained: this.#nestedRetained.used - retainedBefore, }); gray.delete(frame.value); frames.pop(); @@ -882,31 +886,33 @@ class PycMarshalReader extends MarshalReader { } #takeNestedStep(): void { - this.#nestedSteps += 1; - const limit = this.input.max_objects * this.input.max_depth; - if (this.#nestedSteps > limit) - throw new PythonPycResourceFailure( - "objects", - { - max_objects: this.input.max_objects, - max_depth: this.input.max_depth, - }, - `Nested code walk exceeds ${limit} steps (max_objects * max_depth).`, - ); + this.#nestedSteps.charge( + 1, + () => + new PythonPycResourceFailure( + "objects", + { + max_objects: this.input.max_objects, + max_depth: this.input.max_depth, + }, + `Nested code walk exceeds ${String(this.#nestedSteps.maximum)} steps (max_objects * max_depth).`, + ), + ); } #retainNested(codes: readonly CodeNode[]): void { - this.#nestedRetained += codes.length; - const limit = this.input.max_objects * this.input.max_depth; - if (this.#nestedRetained > limit) - throw new PythonPycResourceFailure( - "objects", - { - max_objects: this.input.max_objects, - max_depth: this.input.max_depth, - }, - `Nested code walk retains more than ${limit} code references.`, - ); + this.#nestedRetained.charge( + codes.length, + () => + new PythonPycResourceFailure( + "objects", + { + max_objects: this.input.max_objects, + max_depth: this.input.max_depth, + }, + `Nested code walk retains more than ${String(this.#nestedRetained.maximum)} code references.`, + ), + ); } /** diff --git a/src/sqlite/SqliteDatabaseInspection.ts b/src/sqlite/SqliteDatabaseInspection.ts index 596f8269fa..93bb8bd63d 100644 --- a/src/sqlite/SqliteDatabaseInspection.ts +++ b/src/sqlite/SqliteDatabaseInspection.ts @@ -1,5 +1,6 @@ import { DatabaseSync } from "node:sqlite"; import { z } from "zod"; +import { Budget } from "../domain/budget.js"; import { jsonParts } from "../domain/jsonSerialization.js"; import { SQLITE_ROW_LIMIT_DEFAULT, @@ -80,26 +81,30 @@ type SelectedTableFacts = Pick< readonly orderKey?: RowKeyFacts; }; +const replyExhausted = (): SqliteInspectionFailure => + new SqliteInspectionFailure( + "output-limit", + "Complete SQLite evidence exceeds the 16 MiB JSON reply budget; no partial success was returned.", + ); + class OutputBudget { - #bytes = 1024; + readonly #bytes = new Budget(SQLITE_DATABASE_LIMITS.outputBytes); + constructor() { + // The reply envelope's fixed cost. + this.#bytes.charge(1024, replyExhausted); + } retain(value: unknown): void { // Count bounded encoded parts, including escapes, without allocating a // document-sized string just to decide whether it fits the reply. - this.#bytes += 1; - for (const part of jsonParts(value)) { - this.#bytes += Buffer.byteLength(part); - if (this.#bytes > SQLITE_DATABASE_LIMITS.outputBytes) - throw new SqliteInspectionFailure( - "output-limit", - "Complete SQLite evidence exceeds the 16 MiB JSON reply budget; no partial success was returned.", - ); - } + this.#bytes.charge(1, replyExhausted); + for (const part of jsonParts(value)) + this.#bytes.charge(Buffer.byteLength(part), replyExhausted); } beforeDecode(row: z.output): void { - let minimumBytes = this.#bytes; + let minimumBytes = 0; for (const value of row) if (typeof value === "string") minimumBytes += Buffer.byteLength(value); - if (minimumBytes > SQLITE_DATABASE_LIMITS.outputBytes) + if (minimumBytes > this.#bytes.remaining) throw new SqliteInspectionFailure( "output-limit", "Selected cells exceed the 16 MiB reply budget before text/hex expansion.", @@ -110,10 +115,7 @@ class OutputBudget { (total, length) => total + length * 2n, BigInt(lengths.length * 64), ); - if ( - encodedBytes + BigInt(this.#bytes) > - BigInt(SQLITE_DATABASE_LIMITS.outputBytes) - ) + if (encodedBytes > BigInt(this.#bytes.remaining)) throw new SqliteInspectionFailure( "output-limit", "Selected row byte lengths exceed the 16 MiB reply budget before hex projection.", diff --git a/tests/evaluation/budgetArithmeticGuard.test.ts b/tests/evaluation/budgetArithmeticGuard.test.ts new file mode 100644 index 0000000000..914a19aab4 --- /dev/null +++ b/tests/evaluation/budgetArithmeticGuard.test.ts @@ -0,0 +1,44 @@ +import { expect, it } from "vitest"; +import { budgetArithmeticCount } from "../../scripts/verify/budget-arithmetic-guard.mjs"; + +it("counts arithmetic on fields named for an allowance", () => { + expect(budgetArithmeticCount("this.#remainingBytes -= size;")).toBe(1); + expect(budgetArithmeticCount("this.retained += size;")).toBe(1); + expect(budgetArithmeticCount("this.#arenaWriteOffset += size;")).toBe(0); +}); + +it("counts hand-checked fields inside a hand-written Budget class", () => { + const cuda = [ + "export class CudaMetadataBudget {", + " #visits = 0;", + " #readBytes = 0;", + " visit(): void {", + " if (++this.#visits > 262144) throw failure();", + " }", + " read(size: number): void {", + " if (size > LIMIT - this.#readBytes) throw failure();", + " this.#readBytes += size;", + " }", + "}", + ].join("\n"); + expect(budgetArithmeticCount(cuda)).toBe(2); +}); + +it("ignores unchecked tallies and fields outside Budget classes", () => { + const tallies = [ + "class ProtobufBudget {", + " async checkpoint(): Promise {", + " if (++this.#work % 256 === 0) await yieldTurn();", + " this.#transient += bytes;", + " const done = () => this.#transient;", + " }", + "}", + "class Reader {", + " read(size: number): void {", + " if (this.#bytes + size > LIMIT) throw failure();", + " this.#bytes += size;", + " }", + "}", + ].join("\n"); + expect(budgetArithmeticCount(tallies)).toBe(0); +});