rea-agents 6.3.0 → 6.5.0

package/dist/domain/javascript/electronWrappedCallPaths.js

@@ -0,0 +1,498 @@
+import * as t from "@babel/types";
+import { runtimeFunctionParameters } from "./javascriptAstValues.js";
+import { JavaScriptSymbolicBindings } from "./javascriptSymbolicBindings.js";
+import { symbolicVariants, symbolicTruth, symbolicUnknown, } from "./javascriptSymbolicValues.js";
+import { contextBridgeExposureArguments, } from "./javascriptContextBridgeExposure.js";
+import { boundedExpression } from "./electronStaticAnalysisValues.js";
+import { argumentNode } from "./javascriptStaticAnalysisHelpers.js";
+import { childNodes, traverseJavaScriptAst, } from "./javascriptSemanticTraversal.js";
+import { range, calleeName } from "./javascriptStaticAnalysisHelpers.js";
+import { ipcDescriptor } from "./electronStaticAnalysisIpc.js";
+import { symbolicDefiniteExit, symbolicLogicalRight, } from "./javascriptSymbolicControlFlow.js";
+import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
+const callLabel = (node) => t.isSequenceExpression(node)
+    ? callLabel(node.expressions.at(-1) ?? node)
+    : calleeName(node) || "local call";
+/** Substitutes inert wrapper syntax; every emitted path remains a candidate. */
+export const collectElectronWrappedCallPaths = (program, state, source, accumulator, identity) => {
+    // Bounds repeated interprocedural expansion independently of bundle bytes.
+    // Exhaustion is reported as unknown coverage, never as a negative finding.
+    let remainingVisits = 1_000_000;
+    const resolver = new JavaScriptSymbolicBindings(state, program, identity);
+    const paths = [];
+    const seen = new Set();
+    const step = (node, kind, label) => {
+        const module = accumulator.moduleRangeIndex.find(node.start);
+        return {
+            kind,
+            label,
+            location: range(node),
+            module_key: module?.key ?? null,
+            module_runtime: module?.runtime ?? null,
+        };
+    };
+    const condition = (context, node, positive = true) => {
+        const expression = source
+            .slice(node.start ?? 0, node.end ?? 0)
+            .slice(0, 512);
+        return {
+            ...context,
+            conditions: [
+                ...context.conditions,
+                {
+                    expression: positive === "nullish"
+                        ? `(${expression}) === null || (${expression}) === undefined`
+                        : positive === "not-nullish"
+                            ? `(${expression}) !== null && (${expression}) !== undefined`
+                            : positive
+                                ? expression
+                                : `!(${expression})`,
+                    location: range(node),
+                },
+            ],
+        };
+    };
+    const sequentialFallthrough = (statement, env, context) => {
+        if (symbolicDefiniteExit(statement))
+            return { continues: false, context };
+        if (!t.isIfStatement(statement))
+            return { continues: true, context };
+        const truth = symbolicTruth(resolver.evaluate(statement.test, env));
+        if (truth !== undefined)
+            return symbolicDefiniteExit(truth ? statement.consequent : statement.alternate)
+                ? { continues: false, context }
+                : { continues: true, context };
+        if (symbolicDefiniteExit(statement.consequent))
+            return {
+                continues: true,
+                context: condition(context, statement.test, false),
+            };
+        if (symbolicDefiniteExit(statement.alternate))
+            return {
+                continues: true,
+                context: condition(context, statement.test),
+            };
+        return { continues: true, context };
+    };
+    const metadataContext = (context, value) => {
+        if (value.conditionUnresolved) {
+            accumulator.unknownFindings += 1;
+            return null;
+        }
+        return (value.conditions?.reduce((current, branch) => condition(current, branch.node, branch.positive), context) ?? context);
+    };
+    const hasConditions = (value) => symbolicVariants(value).some((variant) => variant.conditions?.length);
+    function* bridgeMemberFunctions(value, segments = [], active = new Set()) {
+        if (active.has(value))
+            return;
+        if (active.size >= 128) {
+            accumulator.unknownFindings += 1;
+            accumulator.electronCallPathLimitReached = true;
+            return;
+        }
+        const nested = new Set(active);
+        nested.add(value);
+        for (const member of [...resolver.members(value)].sort()) {
+            if (--remainingVisits < 0)
+                return;
+            const path = [...segments, member];
+            const name = path.join(".");
+            for (const variant of symbolicVariants(resolver.property(value, member))) {
+                if (variant.kind === "function")
+                    yield { name, path, fn: variant };
+                else if (resolver.members(variant).length > 0)
+                    yield* bridgeMemberFunctions(variant, path, nested);
+            }
+            if (remainingVisits < 0)
+                return;
+        }
+    }
+    const isolatedBridgeCall = (node) => {
+        const env = resolver.environmentAt(node);
+        const callee = resolver.evaluate(node.callee, env);
+        return symbolicVariants(callee).some((callee) => callee.kind === "external" &&
+            identity.intactExport(callee.path) &&
+            callee.path.slice(1).join(".") ===
+                "contextBridge.exposeInIsolatedWorld")
+            ? { env, callee }
+            : undefined;
+    };
+    const electronStaticSymbolicValue = (value, node) => {
+        const variants = value === undefined ? [] : symbolicVariants(value);
+        const variant = variants.length === 1 ? variants[0] : undefined;
+        if (variant?.kind === "literal" && variant.value !== undefined)
+            return {
+                status: "literal",
+                value: variant.value,
+                expression: null,
+            };
+        return {
+            status: "dynamic",
+            value: null,
+            expression: boundedExpression(source, node),
+        };
+    };
+    const emit = (context, node, terminal, channel = context.channel) => {
+        if (context.entryKind === null)
+            return;
+        const path = {
+            entry_kind: context.entryKind,
+            entry: context.entry,
+            ...(context.entryKind !== "bridge-member" ||
+                context.entryPath === undefined
+                ? {}
+                : { entry_path: context.entryPath }),
+            channel,
+            terminal,
+            resolution: "candidate",
+            steps: [...context.steps, step(node, "terminal", terminal)],
+            conditions: context.conditions,
+        };
+        const key = JSON.stringify(path);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        paths.push(path);
+    };
+    const functionBody = (fn, args, context, invocationNode) => {
+        if (context.active.has(fn.node))
+            return;
+        if (fn.conditionUnresolved === true) {
+            accumulator.unknownFindings += 1;
+            return;
+        }
+        const name = (t.isFunctionExpression(fn.node) || t.isFunctionDeclaration(fn.node)) &&
+            fn.node.id
+            ? fn.node.id.name
+            : "closure";
+        walk(fn.node.body, resolver.bind(fn, args, invocationNode), {
+            ...context,
+            steps: [
+                ...context.steps,
+                ...fn.origins.map((n) => step(n, "factory", t.isCallExpression(n) ? callLabel(n.callee) : "factory")),
+                step(fn.node, "function", name),
+            ],
+            active: new Set([...context.active, fn.node]),
+        });
+    };
+    const ipc = (node, descriptor, args, context, endpoint, guardedDispatch) => {
+        const first = args[0];
+        if (first?.kind !== "literal" || typeof first.value !== "string") {
+            accumulator.unknownFindings += 1;
+            return;
+        }
+        const channelContext = metadataContext(context, first);
+        if (!channelContext)
+            return;
+        const handlerValue = args[1] ?? symbolicUnknown("missing handler");
+        const handlerContext = metadataContext(channelContext, handlerValue);
+        if (!handlerContext)
+            return;
+        const channel = first.value;
+        const location = range(node);
+        const invocationLocation = JSON.stringify(range(context.entryNode)) === JSON.stringify(location)
+            ? undefined
+            : range(context.entryNode);
+        const findingContext = {
+            module_key: null,
+            location,
+            ...(invocationLocation === undefined
+                ? {}
+                : { invocation_location: invocationLocation }),
+        };
+        const handlers = symbolicVariants(handlerValue);
+        // A channel registration must not acquire one arbitrary handler from a union.
+        // Keep the unresolved registration so it still competes with other handlers.
+        const fn = handlers.length === 1 && handlers[0]?.kind === "function"
+            ? handlers[0]
+            : undefined;
+        const handlerNode = node.arguments[1];
+        const finding = descriptor.mode === "send" || descriptor.mode === "invoke"
+            ? {
+                ...descriptor,
+                channel,
+                channel_expression: null,
+                handler_kind: null,
+                handler_location: null,
+                ...findingContext,
+            }
+            : fn
+                ? {
+                    ...descriptor,
+                    channel,
+                    channel_expression: null,
+                    handler_kind: "inline-function",
+                    handler_location: range(fn.node),
+                    ...findingContext,
+                }
+                : handlerNode
+                    ? {
+                        ...descriptor,
+                        channel,
+                        channel_expression: null,
+                        handler_kind: "dynamic-expression",
+                        handler_location: range(handlerNode),
+                        ...findingContext,
+                    }
+                    : {
+                        ...descriptor,
+                        channel,
+                        channel_expression: null,
+                        handler_kind: "missing",
+                        handler_location: null,
+                        ...findingContext,
+                    };
+        // A fully observed transmission stays one source fact when its callback is
+        // traced. Registrations retain invocation identity because handlers compete.
+        const duplicate = accumulator.ipc.some(({ value }) => value.side === finding.side &&
+            value.operation === finding.operation &&
+            value.channel === channel &&
+            JSON.stringify(value.location) === JSON.stringify(location) &&
+            ((value.resolution_basis === undefined &&
+                (value.mode === "send" || value.mode === "invoke")) ||
+                JSON.stringify(value.invocation_location) ===
+                    JSON.stringify(invocationLocation)));
+        const findingGuarded = context.conditions.length > 0 || hasConditions(first) || guardedDispatch;
+        if (!duplicate && !findingGuarded) {
+            accumulator.ipc.push({
+                offset: node.start ?? -1,
+                value: { ...finding, resolution_basis: "wrapper-substitution" },
+            });
+            if (descriptor.mode !== "send" && descriptor.mode !== "invoke" && !fn)
+                accumulator.unknownFindings += 1;
+        }
+        else if (findingGuarded)
+            accumulator.unknownFindings += 1;
+        if (descriptor.mode === "send" || descriptor.mode === "invoke") {
+            emit(channelContext, node, endpoint, channel);
+            return;
+        }
+        if (descriptor.side === "main" && fn)
+            functionBody(fn, [
+                { kind: "external", path: ["ipc-event"] },
+                symbolicUnknown("IPC payload"),
+            ], {
+                ...handlerContext,
+                entryKind: "ipc-handler",
+                entry: channel,
+                channel,
+                steps: [...context.steps, step(node, "ipc", endpoint)],
+            }, node);
+    };
+    const bridge = (node, exposure, context, guardedDispatch) => {
+        const key = exposure.apiKey;
+        const object = exposure.api;
+        const worldValue = exposure.worldId === null
+            ? null
+            : (exposure.worldId ?? symbolicUnknown("missing world id"));
+        const worldContext = worldValue === null ? context : metadataContext(context, worldValue);
+        if (!worldContext)
+            return;
+        const worldId = worldValue === null
+            ? null
+            : electronStaticSymbolicValue(worldValue, exposure.worldIdIndex === null
+                ? undefined
+                : argumentNode(node.arguments[exposure.worldIdIndex]));
+        if (worldId?.status === "dynamic")
+            accumulator.unknownFindings += 1;
+        if (key?.kind !== "literal" || typeof key.value !== "string" || !object) {
+            accumulator.unknownFindings += 1;
+            return;
+        }
+        const keyContext = metadataContext(worldContext, key);
+        if (!keyContext || !metadataContext(keyContext, object))
+            return;
+        const members = [...resolver.members(object)].sort();
+        const location = range(node);
+        const existing = accumulator.contextBridgeApis.find(({ value }) => JSON.stringify(value.location) === JSON.stringify(location));
+        const finding = {
+            world: exposure.world,
+            world_id: worldId,
+            api_key: key.value,
+            api_key_expression: null,
+            api_status: "dynamic",
+            resolution_basis: "wrapper-substitution",
+            // The direct syntax pass recursively retains literal dotted paths. The
+            // symbolic resolver enumerates only immediate object keys, so its
+            // replacement must not erase paths already established at this call.
+            members: [
+                ...new Set([...(existing?.value.members ?? []), ...members]),
+            ].sort(compareUnicodeCodePoints),
+            unknown_members: resolver.unknownMembers(object),
+            module_key: null,
+            location,
+        };
+        // This report shape has no predicate field, so a guarded world or object
+        // cannot be recorded as an unconditional exposure fact.
+        const guardedWorld = worldValue !== null && hasConditions(worldValue);
+        const guardedKey = hasConditions(key);
+        const guardedObject = hasConditions(object);
+        const guarded = context.conditions.length > 0 ||
+            guardedWorld ||
+            guardedKey ||
+            guardedObject ||
+            guardedDispatch;
+        if (guarded)
+            accumulator.unknownFindings += 1;
+        // Existing entries are raw syntax observations and remain valid even when
+        // symbolic substitution can only describe this call under a predicate.
+        if (!guarded && existing)
+            (existing.value.api_status !== "object-literal" ||
+                existing.value.unknown_members > 0) &&
+                accumulator.contextBridgeApis.splice(accumulator.contextBridgeApis.indexOf(existing), 1, { offset: node.start ?? -1, value: finding });
+        else if (!guarded)
+            accumulator.contextBridgeApis.push({
+                offset: node.start ?? -1,
+                value: finding,
+            });
+        for (const { name, path, fn } of bridgeMemberFunctions(object)) {
+            const memberContext = metadataContext(keyContext, fn);
+            if (!memberContext)
+                continue;
+            const entry = `${key.value}.${name}`;
+            functionBody(fn, runtimeFunctionParameters(fn.node).map(() => symbolicUnknown("public API argument")), {
+                ...memberContext,
+                entryNode: node,
+                entryKind: "bridge-member",
+                entry,
+                entryPath: [key.value, ...path],
+                channel: null,
+                steps: [step(node, "exposure", entry)],
+                active: new Set(),
+            }, node);
+        }
+    };
+    const call = (node, env, context, evaluatedCallee) => {
+        const value = evaluatedCallee ?? resolver.evaluate(node.callee, env);
+        const args = resolver.arguments(node, env);
+        for (const callee of symbolicVariants(value)) {
+            const branchContext = metadataContext(context, callee);
+            if (!branchContext)
+                continue;
+            if (callee.kind === "function") {
+                functionBody(callee, args, {
+                    ...branchContext,
+                    steps: [
+                        ...branchContext.steps,
+                        step(node, "call", callLabel(node.callee)),
+                    ],
+                }, node);
+            }
+            else if (callee.kind === "external") {
+                const path = callee.path;
+                const endpoint = path.join(".");
+                if (identity.intactExport(path)) {
+                    const descriptor = ipcDescriptor(path.slice(1));
+                    const exposure = path.length === 3 && path[1] === "contextBridge"
+                        ? contextBridgeExposureArguments(path[2] ?? "", args)
+                        : undefined;
+                    if (exposure)
+                        bridge(node, exposure, branchContext, hasConditions(callee));
+                    else if (descriptor)
+                        ipc(node, descriptor, args, branchContext, endpoint, hasConditions(callee));
+                    else if (path[1] === "clipboard")
+                        emit(branchContext, node, endpoint);
+                }
+                else if ((path[0] === "navigator" && path[1] === "clipboard") ||
+                    (path[0] === "ipc-event" && path[1] === "sender"))
+                    emit(branchContext, node, endpoint);
+            }
+        }
+    };
+    function walk(node, env, context) {
+        if (--remainingVisits < 0 || t.isFunction(node) || t.isClass(node))
+            return;
+        if (t.isBlockStatement(node)) {
+            let next = context;
+            for (const statement of node.body) {
+                walk(statement, env, next);
+                const fallthrough = sequentialFallthrough(statement, env, next);
+                if (!fallthrough.continues)
+                    break;
+                next = fallthrough.context;
+            }
+            return;
+        }
+        if (t.isIfStatement(node) || t.isConditionalExpression(node)) {
+            const truth = symbolicTruth(resolver.evaluate(node.test, env));
+            if (truth !== false)
+                walk(node.consequent, env, truth === undefined ? condition(context, node.test) : context);
+            if (truth !== true && node.alternate)
+                walk(node.alternate, env, truth === undefined ? condition(context, node.test, false) : context);
+            return;
+        }
+        if (t.isLogicalExpression(node)) {
+            walk(node.left, env, context);
+            const right = symbolicLogicalRight(node.operator, resolver.evaluate(node.left, env));
+            if (right === false)
+                return;
+            walk(node.right, env, right === undefined
+                ? condition(context, node.left, node.operator === "??" ? "nullish" : node.operator === "&&")
+                : context);
+            return;
+        }
+        if (t.isCallExpression(node) || t.isOptionalCallExpression(node))
+            call(node, env, context);
+        for (const child of childNodes(node))
+            walk(child, env, context);
+    }
+    traverseJavaScriptAst(program, {
+        enter: (node) => {
+            if (!t.isCallExpression(node) && !t.isOptionalCallExpression(node))
+                return;
+            const isolatedSeed = t.isStringLiteral(node.arguments[0])
+                ? undefined
+                : isolatedBridgeCall(node);
+            if (!t.isStringLiteral(node.arguments[0]) && isolatedSeed === undefined)
+                return;
+            const env = isolatedSeed?.env ?? resolver.environmentAt(node);
+            let context = {
+                entryNode: node,
+                entry: "",
+                entryKind: null,
+                channel: null,
+                steps: [],
+                conditions: [],
+                active: new Set(),
+            };
+            for (let child = node, parent = state.parentsByNode.get(child); parent && !t.isFunction(parent); child = parent, parent = state.parentsByNode.get(child)) {
+                if (t.isIfStatement(parent) || t.isConditionalExpression(parent)) {
+                    if (child === parent.test)
+                        continue;
+                    const truth = symbolicTruth(resolver.evaluate(parent.test, env));
+                    const positive = child === parent.consequent;
+                    if (truth !== undefined && truth !== positive)
+                        return;
+                    if (truth === undefined)
+                        context = condition(context, parent.test, positive);
+                }
+                else if (t.isLogicalExpression(parent) && child === parent.right) {
+                    const right = symbolicLogicalRight(parent.operator, resolver.evaluate(parent.left, env));
+                    if (right === false)
+                        return;
+                    if (right === undefined)
+                        context = condition(context, parent.left, parent.operator === "??" ? "nullish" : parent.operator === "&&");
+                }
+                else if (t.isBlockStatement(parent)) {
+                    const index = parent.body.findIndex((statement) => statement === child);
+                    if (index >= 0) {
+                        for (const statement of parent.body.slice(0, index)) {
+                            const fallthrough = sequentialFallthrough(statement, env, context);
+                            if (!fallthrough.continues)
+                                return;
+                            context = fallthrough.context;
+                        }
+                    }
+                }
+            }
+            call(node, env, context, isolatedSeed?.callee);
+        },
+    });
+    if (remainingVisits < 0 || resolver.truncated) {
+        accumulator.unknownFindings += 1;
+        accumulator.electronCallPathLimitReached = true;
+    }
+    if (resolver.unresolved)
+        accumulator.unknownFindings += 1;
+    return paths;
+};

package/dist/domain/javascript/htmlArtifactReferences.js

@@ -1,10 +1,63 @@
 import { defaultTreeAdapter, parse, } from "parse5";
-/** Extract inert HTML script references and the first document base href. */
+/**
+ * Inline bodies whose exact locations are retained per HTML file. Every body
+ * is still counted; locations beyond this bound are reported as omitted.
+ */
+export const HTML_INLINE_SCRIPT_LOCATION_LIMIT = 100;
+// The JavaScript MIME type essences from the WHATWG MIME Sniffing standard.
+const JAVASCRIPT_MIME_TYPES = new Set([
+    "application/ecmascript",
+    "application/javascript",
+    "application/x-ecmascript",
+    "application/x-javascript",
+    "text/ecmascript",
+    "text/javascript",
+    "text/javascript1.0",
+    "text/javascript1.1",
+    "text/javascript1.2",
+    "text/javascript1.3",
+    "text/javascript1.4",
+    "text/javascript1.5",
+    "text/jscript",
+    "text/livescript",
+    "text/x-ecmascript",
+    "text/x-javascript",
+]);
+/**
+ * Classify a script element's type as HTML "prepare the script element" does.
+ * Only a type attribute is whitespace-stripped, and only for the JavaScript
+ * MIME check; `module` must match the type string exactly, ignoring ASCII
+ * case. Import maps, speculation rules and data blocks are not JavaScript.
+ */
+const inlineScriptType = (attrs) => {
+    const type = attrs.find(({ name }) => name === "type");
+    const language = attrs.find(({ name }) => name === "language");
+    const typeString = type !== undefined
+        ? type.value
+        : language !== undefined && language.value !== ""
+            ? `text/${language.value}`
+            : "";
+    if (typeString === "")
+        return "classic";
+    const mimeCandidate = type === undefined
+        ? typeString
+        : typeString.replace(/^[\t\n\f\r ]+|[\t\n\f\r ]+$/gu, "");
+    if (JAVASCRIPT_MIME_TYPES.has(asciiLowercase(mimeCandidate)))
+        return "classic";
+    return asciiLowercase(typeString) === "module" ? "module" : null;
+};
+const asciiLowercase = (value) => value.replace(/[A-Z]/gu, (letter) => letter.toLowerCase());
+/**
+ * Extract inert HTML script references, inline JavaScript bodies, and the
+ * first document base href.
+ */
 export const htmlArtifactReferences = (text) => {
     const pending = [
         parse(text, { sourceCodeLocationInfo: true }),
     ];
     const scripts = [];
+    const inlineScripts = [];
+    let inlineScriptCount = 0;
     let baseHref = null;
     while (pending.length > 0) {
         const node = pending.pop();
@@ -23,10 +76,19 @@ export const htmlArtifactReferences = (text) => {
                 if (src !== undefined && src.value !== "" && location !== undefined) {
                     scripts.push({
                         scriptPath: src.value,
-                        startOffset: location.startOffset,
-                        endOffset: location.endOffset,
+                        location: {
+                            start: sourcePoint(location.startLine, location.startCol),
+                            end: sourcePoint(location.endLine, location.endCol),
+                        },
                     });
                 }
+                const inline = src === undefined ? inlineScriptBody(node) : undefined;
+                const scriptType = inline === undefined ? null : inlineScriptType(node.attrs);
+                if (inline !== undefined && scriptType !== null) {
+                    inlineScriptCount += 1;
+                    if (inlineScripts.length < HTML_INLINE_SCRIPT_LOCATION_LIMIT)
+                        inlineScripts.push({ scriptType, location: inline });
+                }
             }
         }
         // Template content belongs to a separate inert document fragment. Only
@@ -36,5 +98,33 @@ export const htmlArtifactReferences = (text) => {
                 pending.push(child);
         }
     }
-    return { baseHref, scripts };
+    return { baseHref, scripts, inlineScripts, inlineScriptCount };
+};
+/** Locate a script element's non-blank body; browsers ignore it when src is set. */
+const inlineScriptBody = (node) => {
+    const startTag = node.sourceCodeLocation?.startTag;
+    if (startTag === undefined)
+        return undefined;
+    let blank = true;
+    let end;
+    for (const child of node.childNodes) {
+        if (!defaultTreeAdapter.isTextNode(child))
+            continue;
+        if (blank && /\S/u.test(child.value))
+            blank = false;
+        end = child.sourceCodeLocation ?? end;
+    }
+    // An unclosed script's element range ends at its opening tag, so the body's
+    // own text location bounds it.
+    if (blank || end == null)
+        return undefined;
+    return {
+        start: sourcePoint(startTag.endLine, startTag.endCol),
+        end: sourcePoint(end.endLine, end.endCol),
+    };
 };
+/** parse5 lines and UTF-16 columns are one-based; ranges use zero-based columns. */
+const sourcePoint = (line, column) => ({
+    line,
+    column: column - 1,
+});

package/dist/domain/javascript/javascriptAnalysisResourceControls.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+/** Shared operational defaults for the isolated source-analysis boundary. */
+export const JAVASCRIPT_ANALYSIS_RESOURCE_DEFAULTS = {
+    heapMb: 1024,
+    timeoutMs: 300_000,
+    semanticNodes: 100_000,
+    semanticNodesPerFile: 20_000,
+};
+/** Maximum caller-selected node capacity; heap and transfer admission still apply. */
+export const JAVASCRIPT_SEMANTIC_NODE_MAXIMUM = 1_000_000;
+/** Project observed execution limits without inventing unmeasured values. */
+export const javaScriptAnalysisCoverageLimits = (limits) => {
+    const result = [];
+    for (const key of [
+        "worker_heap_limit_bytes",
+        "worker_process_memory_limit_bytes",
+        "worker_timeout_ms",
+        "parent_result_budget_bytes",
+        "parent_available_result_budget_bytes",
+        "semantic_result_budget_bytes",
+        "transfer_record_bytes",
+        "transfer_file_bytes",
+    ]) {
+        const value = limits?.[key];
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+            continue;
+        result.push({
+            name: `javascript_analysis_${key}`,
+            value,
+            unit: key.endsWith("_ms") ? "milliseconds" : "bytes",
+        });
+    }
+    return result;
+};
+/** Optional operational choices; omission keeps them out of Evidence parameters. */
+export const javaScriptAnalysisResourceControlsSchema = z.strictObject({
+    max_semantic_nodes: z
+        .number()
+        .int()
+        .min(1)
+        .max(JAVASCRIPT_SEMANTIC_NODE_MAXIMUM)
+        .optional()
+        .describe("Maximum retained semantic nodes across the application; defaults to 100000. Worker heap and parent result admission remain enforced."),
+    max_semantic_nodes_per_file: z
+        .number()
+        .int()
+        .min(1)
+        .max(JAVASCRIPT_SEMANTIC_NODE_MAXIMUM)
+        .optional()
+        .describe("Maximum retained semantic nodes per source file; defaults to 20000, additionally bounded by max_semantic_nodes and memory/transfer limits."),
+    max_heap_mb: z
+        .number()
+        .int()
+        .min(128)
+        .max(16_384)
+        .optional()
+        .describe("Maximum V8 old-space heap in MiB for the isolated JavaScript source analyzer; defaults to 1024. This does not change the CLI/MCP process heap. When REA runs on Bun, which ignores V8 heap flags, Windows instead limits the analyzer's committed memory to this budget plus a 512 MiB runtime reserve; other Bun hosts enforce no limit."),
+    analysis_timeout_ms: z
+        .number()
+        .int()
+        .min(1)
+        .max(2_147_483_647)
+        .optional()
+        .describe("Maximum startup, analysis and transfer time per JavaScript source, in milliseconds; defaults to 300000. On timeout, return collected partial Evidence and stop the analysis."),
+});