rea-agents 4.0.1 → 5.0.0

package/dist/browser/execution/CdpPreciseCoverage.js

@@ -0,0 +1,48 @@
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { preciseCoverageSchema } from "./CdpRuntimeProtocol.js";
+/** Validate source-range bounds against exact retained UTF-16 text without flattening nested counts. */
+export const normalizePreciseCoverage = (raw, sources, retained) => {
+    const parsed = preciseCoverageSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new AnalysisOutputError(sources.session.operation, `Malformed precise coverage: ${parsed.error.message}`);
+    const scripts = [];
+    let excluded = 0;
+    for (const script of parsed.data.result) {
+        if (!sources.belongsToDocument(script.scriptId)) {
+            excluded += 1;
+            continue;
+        }
+        const source = retained.find((item) => item.script_id === script.scriptId)?.source;
+        scripts.push({
+            script_id: script.scriptId,
+            reported_url: sources.sourceUrl(script.scriptId, script.url),
+            functions: script.functions.map((fn) => ({
+                name: fn.functionName,
+                is_block_coverage: fn.isBlockCoverage,
+                ranges: fn.ranges.map((range) => {
+                    if (range.endOffset < range.startOffset ||
+                        (source?.state === "captured" &&
+                            range.endOffset > source.utf16_units))
+                        throw new AnalysisOutputError(sources.session.operation, `Script ${script.scriptId} coverage range ${range.startOffset}:${range.endOffset} is outside retained source bounds.`);
+                    return {
+                        start_offset: range.startOffset,
+                        end_offset: range.endOffset,
+                        count: range.count,
+                        source_bounds: source?.state === "captured" ? "verified" : "unknown",
+                    };
+                }),
+            })),
+        });
+    }
+    return {
+        timestamp: parsed.data.timestamp,
+        coverage: {
+            state: "captured",
+            reason: null,
+            offset_units: "utf16-code-units",
+            end_offset: "exclusive",
+            scripts,
+            excluded_scripts: excluded,
+        },
+    };
+};

package/dist/browser/execution/CdpRuntimeInitiator.js

@@ -0,0 +1,18 @@
+import { sanitizeBrowserUrl } from "../../domain/browserObservation.js";
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Sanitize known transport fields while retaining declarations and every unknown producer field. */
+export const sanitizeRuntimeInitiator = (initiator, sources) => {
+    if (typeof initiator.url === "string")
+        initiator.url = sanitizeBrowserUrl(initiator.url).url;
+    let stack = initiator.stack;
+    while (isObject(stack)) {
+        if (Array.isArray(stack.callFrames))
+            for (const frame of stack.callFrames)
+                if (isObject(frame) &&
+                    typeof frame.url === "string" &&
+                    typeof frame.scriptId === "string")
+                    frame.url = sources.sourceUrl(frame.scriptId, frame.url);
+        stack = stack.parent;
+    }
+    return initiator;
+};

package/dist/browser/execution/CdpRuntimeProtocol.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+const integer = z.number().int().min(0);
+const contextAuxDataSchema = z
+    .object({
+    frameId: z.string().optional(),
+    isDefault: z.boolean().optional(),
+    type: z.string().optional(),
+})
+    .passthrough();
+/** Validated producer script metadata; optional declarations remain unknown when absent. */
+export const runtimeScriptParsedSchema = z.object({
+    scriptId: z.string().min(1),
+    url: z.string(),
+    executionContextId: integer,
+    startLine: integer,
+    startColumn: integer,
+    endLine: integer,
+    endColumn: integer,
+    hash: z.string().optional(),
+    sourceMapURL: z.string().optional(),
+    hasSourceURL: z.boolean().optional(),
+    scriptLanguage: z.string().optional(),
+    executionContextAuxData: contextAuxDataSchema.optional(),
+});
+/** Frame ownership is taken from producer context metadata, independently of source URLs. */
+export const runtimeContextSchema = z.object({
+    context: z
+        .object({
+        id: integer,
+        origin: z.string().optional(),
+        name: z.string().optional(),
+        uniqueId: z.string().optional(),
+        auxData: contextAuxDataSchema.optional(),
+    })
+        .passthrough(),
+});
+const range = z.object({
+    startOffset: integer,
+    endOffset: integer,
+    count: integer,
+});
+/** CDP precise coverage preserves every nested producer range. */
+export const preciseCoverageSchema = z.object({
+    timestamp: z.number().min(0),
+    result: z.array(z.object({
+        scriptId: z.string().min(1),
+        url: z.string(),
+        functions: z.array(z.object({
+            functionName: z.string(),
+            isBlockCoverage: z.boolean(),
+            ranges: z.array(range),
+        })),
+    })),
+});
+/** The full reported synchronous and embedded asynchronous stack is retained. */
+export const runtimeStackSchema = z.object({
+    callFrames: z.array(z.object({
+        scriptId: z.string(),
+        url: z.string(),
+        lineNumber: integer,
+        columnNumber: integer,
+        functionName: z.string(),
+    })),
+    parent: z.unknown().optional(),
+    parentId: z
+        .object({ id: z.string(), debuggerId: z.string().optional() })
+        .optional(),
+});
+/** Request evidence contains metadata and producer initiators; bodies and headers are outside this tool. */
+export const runtimeRequestSchema = z.object({
+    requestId: z.string().min(1),
+    frameId: z.string().optional(),
+    timestamp: z.number().min(0),
+    request: z.object({ url: z.string(), method: z.string() }),
+    initiator: z
+        .object({
+        type: z.string(),
+        stack: z.unknown().optional(),
+        url: z.string().optional(),
+        lineNumber: integer.optional(),
+        columnNumber: integer.optional(),
+    })
+        .passthrough(),
+});
+/** Native listener descriptors omit live remote handles from portable evidence. */
+export const runtimeListenersSchema = z.object({
+    listeners: z.array(z.object({
+        type: z.string(),
+        useCapture: z.boolean(),
+        passive: z.boolean(),
+        once: z.boolean(),
+        scriptId: z.string(),
+        lineNumber: integer,
+        columnNumber: integer,
+    })),
+});
+/** Current main frame identity protects same-URL reloads as well as URL changes. */
+export const runtimeFrameTreeSchema = z.object({
+    frameTree: z.object({
+        frame: z.object({
+            id: z.string().min(1),
+            url: z.string(),
+            loaderId: z.string().optional(),
+        }),
+    }),
+});

package/dist/browser/execution/CdpRuntimeRequests.js

@@ -0,0 +1,81 @@
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { sanitizeBrowserUrl } from "../../domain/browserObservation.js";
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { WEB_RUNTIME_LIMITS } from "../../domain/webRuntime.js";
+import { runtimeRequestSchema, runtimeStackSchema, } from "./CdpRuntimeProtocol.js";
+import { sanitizeRuntimeInitiator } from "./CdpRuntimeInitiator.js";
+/** Join producer initiators by script ID while preserving unresolved async parent identities. */
+export class CdpRuntimeRequests {
+    sources;
+    items = [];
+    excluded = 0;
+    #bytes = 0;
+    #failure;
+    constructor(sources) {
+        this.sources = sources;
+    }
+    /** Retain only armed-window requests from the selected main frame and selected origins. */
+    ingest(event) {
+        if (event.method !== "Network.requestWillBeSent" ||
+            this.#failure !== undefined)
+            return;
+        try {
+            const request = runtimeRequestSchema.parse(event.params);
+            const url = sanitizeBrowserUrl(request.request.url);
+            if (request.frameId !== this.sources.session.target.frame_id ||
+                url.origin === null ||
+                !this.sources.session.allowedOrigins.has(url.origin)) {
+                this.excluded += 1;
+                return;
+            }
+            this.#bytes += Buffer.byteLength(JSON.stringify(event.params));
+            if (this.#bytes > WEB_RUNTIME_LIMITS.retainedEventBytes)
+                throw new Error("Request initiator evidence exceeds its complete 8 MiB event budget.");
+            const callsites = [];
+            const parents = [];
+            let current = request.initiator.stack;
+            while (current !== undefined) {
+                const stack = runtimeStackSchema.parse(current);
+                for (const frame of stack.callFrames)
+                    callsites.push(this.sources.location(frame.scriptId, frame.url, frame.lineNumber, frame.columnNumber, frame.functionName));
+                if (stack.parentId !== undefined)
+                    parents.push({
+                        id: stack.parentId.id,
+                        debugger_id: stack.parentId.debuggerId ?? null,
+                    });
+                current = stack.parent;
+            }
+            if (request.initiator.url !== undefined &&
+                request.initiator.lineNumber !== undefined)
+                callsites.push(this.sources.location("", sanitizeBrowserUrl(request.initiator.url).url, request.initiator.lineNumber, request.initiator.columnNumber ?? null));
+            this.items.push({
+                request_id: request.requestId,
+                url: url.url,
+                method: request.request.method,
+                timestamp_seconds: request.timestamp,
+                initiator_type: request.initiator.type,
+                reported_initiator: sanitizeRuntimeInitiator(jsonObjectSchema.parse(request.initiator), this.sources),
+                callsites,
+                async_parent_ids: parents,
+                causal_attribution: "unknown",
+            });
+        }
+        catch (cause) {
+            this.#failure = new AnalysisOutputError(this.sources.session.operation, cause instanceof Error ? cause.message : String(cause));
+        }
+    }
+    /** Preserve all repeated/redirect requests and bind callsites after metadata collection ends. */
+    result() {
+        this.check();
+        return this.items.map((request) => ({
+            ...request,
+            reported_initiator: sanitizeRuntimeInitiator(jsonObjectSchema.parse(request.reported_initiator), this.sources),
+            callsites: request.callsites.map((site) => this.sources.location(site.script_id, site.url, site.line_number, site.column_number, site.function_name)),
+        }));
+    }
+    /** Report malformed or oversized producer evidence without partial success. */
+    check() {
+        if (this.#failure !== undefined)
+            throw this.#failure;
+    }
+}

package/dist/browser/execution/CdpRuntimeSession.js

@@ -0,0 +1,163 @@
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisTimeoutError } from "../../domain/analysisErrorCore.js";
+import { BrowserObservationError } from "../../domain/browserObservationError.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { sanitizeBrowserUrl } from "../../domain/browserObservation.js";
+import { WEB_RUNTIME_LIMITS, } from "../../domain/webRuntime.js";
+import { authorizeCdpTarget } from "../CdpAuthorizedTarget.js";
+import { authorizedMainFrame } from "../CdpAuthorizedMainFrame.js";
+import { discoverCdpEndpoint, } from "../CdpEndpoint.js";
+import { openCdpTargetSession, } from "../CdpTargetSession.js";
+import { runtimeFrameTreeSchema } from "./CdpRuntimeProtocol.js";
+/** Owned transport and instrumentation; the selected browser/page remain externally owned. */
+export class CdpRuntimeSession {
+    transport;
+    discovery;
+    target;
+    allowedOrigins;
+    operation;
+    options;
+    enabledDomains = [];
+    preciseCoverageMayBeActive = false;
+    #completion;
+    #completionTimer;
+    constructor(transport, discovery, target, allowedOrigins, operation, options) {
+        this.transport = transport;
+        this.discovery = discovery;
+        this.target = target;
+        this.allowedOrigins = allowedOrigins;
+        this.operation = operation;
+        this.options = options;
+    }
+    /** Acquire a validated target; failed setup releases its owned socket. */
+    static async open(input, operation, options) {
+        return runtimeDeadline(operation, options.signal, async (signal) => {
+            const discovery = await discoverCdpEndpoint(input.cdp_endpoint, operation, signal);
+            const { target, allowedOrigins } = authorizeCdpTarget(discovery, input, operation);
+            const transport = await openCdpTargetSession(discovery, target, operation, signal, { maxPayloadBytes: WEB_RUNTIME_LIMITS.protocolBytes });
+            try {
+                const tree = runtimeFrameTreeSchema.parse(await authorizedMainFrame({
+                    ...transport,
+                    allowedOrigins,
+                    signal,
+                    operation,
+                }));
+                const frame = tree.frameTree.frame;
+                const url = sanitizeBrowserUrl(frame.url);
+                if (url.origin === null)
+                    throw new BrowserObservationError(operation, "target_not_allowed");
+                return new CdpRuntimeSession(transport, discovery, {
+                    target_id: target.id,
+                    initial_url: url.url,
+                    origin: url.origin,
+                    frame_id: frame.id,
+                    loader_id: frame.loaderId ?? null,
+                }, allowedOrigins, operation, options);
+            }
+            catch (cause) {
+                await transport.connection.close();
+                throw cause;
+            }
+        });
+    }
+    /** Bound each command separately from the caller-selected observation duration. */
+    async command(method, params = {}) {
+        const signals = [this.options.signal, this.#completion?.signal].filter((signal) => signal !== undefined);
+        try {
+            return await runtimeDeadline(this.operation, signals.length === 0 ? undefined : AbortSignal.any(signals), (signal) => this.transport.connection.send(method, params, this.transport.sessionId, signal));
+        }
+        catch (cause) {
+            if (this.#completion?.signal.aborted && !this.options.signal?.aborted)
+                throw new AnalysisTimeoutError(this.operation, WEB_RUNTIME_LIMITS.commandTimeoutMs);
+            throw cause;
+        }
+    }
+    /** Bound the complete inspection/source-join phase as well as each individual command. */
+    beginCompletion() {
+        if (this.#completion !== undefined)
+            return;
+        this.#completion = new AbortController();
+        this.#completionTimer = setTimeout(() => this.#completion?.abort(), WEB_RUNTIME_LIMITS.commandTimeoutMs);
+    }
+    /** Register cleanup before sending: cancellation can occur after producer acceptance. */
+    async enable(domain) {
+        this.enabledDomains.push(domain);
+        await this.command(`${domain}.enable`);
+    }
+    /** Check document identity before joining any live node or final coverage evidence. */
+    async assertDocument() {
+        const frame = runtimeFrameTreeSchema.parse(await this.command("Page.getFrameTree")).frameTree.frame;
+        const url = sanitizeBrowserUrl(frame.url);
+        if (frame.id !== this.target.frame_id ||
+            (frame.loaderId ?? null) !== this.target.loader_id ||
+            (this.target.loader_id === null && url.url !== this.target.initial_url))
+            throw new BrowserObservationError(this.operation, "target_changed", {
+                detail: `Selected target ${this.target.target_id} changed document during ${this.operation}.`,
+            });
+        if (url.origin === null || !this.allowedOrigins.has(url.origin))
+            throw new BrowserObservationError(this.operation, "target_not_allowed", {
+                detail: `Selected target ${this.target.target_id} moved to an unselected origin during ${this.operation}.`,
+            });
+    }
+    /** Cleanup uses its own deadline after caller cancellation, then closes REA's transport. */
+    async close(previousError, objectGroup) {
+        if (this.#completionTimer !== undefined)
+            clearTimeout(this.#completionTimer);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), WEB_RUNTIME_LIMITS.cleanupTimeoutMs);
+        const failures = [];
+        const send = async (method, params = {}) => {
+            try {
+                await this.transport.connection.send(method, params, this.transport.sessionId, controller.signal);
+            }
+            catch (cause) {
+                failures.push(`${method}: ${cause instanceof AnalysisError ? (cause.userMessage ?? cause.message) : cause instanceof Error ? cause.message : String(cause)}`);
+            }
+        };
+        try {
+            if (this.preciseCoverageMayBeActive)
+                await send("Profiler.stopPreciseCoverage");
+            if (objectGroup !== undefined)
+                await send("Runtime.releaseObjectGroup", { objectGroup });
+            for (const domain of [...this.enabledDomains].reverse())
+                await send(`${domain}.disable`);
+            if (this.transport.sessionId !== undefined) {
+                try {
+                    await this.transport.connection.send("Target.detachFromTarget", { sessionId: this.transport.sessionId }, undefined, controller.signal);
+                }
+                catch (cause) {
+                    failures.push(`Target.detachFromTarget: ${cause instanceof AnalysisError ? (cause.userMessage ?? cause.message) : cause instanceof Error ? cause.message : String(cause)}`);
+                }
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            await this.transport.connection.close();
+        }
+        return failures.length === 0
+            ? undefined
+            : new ProviderCleanupError("rea-cdp-browser", [this.target.target_id, "runtime-instrumentation"], {
+                target_id: this.target.target_id,
+                cleanup_failures: failures,
+                previous_error: previousError?.userMessage ?? previousError?.message ?? null,
+            }, { operation: this.operation });
+    }
+}
+/** Apply a disposable command deadline without turning timeout into caller cancellation. */
+export const runtimeDeadline = async (operation, signal, run) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), WEB_RUNTIME_LIMITS.commandTimeoutMs);
+    try {
+        return await run(signal === undefined
+            ? controller.signal
+            : AbortSignal.any([signal, controller.signal]));
+    }
+    catch (cause) {
+        if (controller.signal.aborted && signal?.aborted !== true)
+            throw new AnalysisTimeoutError(operation, WEB_RUNTIME_LIMITS.commandTimeoutMs);
+        throw cause;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};

package/dist/browser/execution/CdpRuntimeSources.js

@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { sanitizeBrowserUrl } from "../../domain/browserObservation.js";
+import { jsonObjectSchema } from "../../domain/jsonValue.js";
+import { WEB_RUNTIME_LIMITS, } from "../../domain/webRuntime.js";
+import { runtimeContextSchema, runtimeScriptParsedSchema, } from "./CdpRuntimeProtocol.js";
+const scriptIdentitySchema = runtimeScriptParsedSchema.pick({ scriptId: true });
+const contextIdentitySchema = z.object({
+    context: runtimeContextSchema.shape.context.pick({ id: true }),
+});
+/** Source ownership is proven by execution context/frame metadata, independently of URL aliases. */
+export class CdpRuntimeSources {
+    session;
+    scripts = new Map();
+    #contexts = new Map();
+    #changed = new Set();
+    #changedContexts = new Set();
+    #sources = new Map();
+    #retainedBytes = 0;
+    #sourceBytes = 0;
+    #failure;
+    constructor(session) {
+        this.session = session;
+    }
+    /** Subscribe before enabling Debugger; existing uncollected scripts are replayed by the producer. */
+    ingest(event, retainNewMetadata = true) {
+        if (event.sessionId !== this.session.transport.sessionId ||
+            this.#failure !== undefined)
+            return;
+        try {
+            if (event.method === "Runtime.executionContextCreated") {
+                this.#retainedBytes += Buffer.byteLength(JSON.stringify(event.params));
+                if (this.#retainedBytes > WEB_RUNTIME_LIMITS.retainedEventBytes)
+                    throw new Error("Context/script metadata exceeds the complete 8 MiB event budget.");
+                const context = runtimeContextSchema.parse(event.params).context;
+                const previous = this.#contexts.get(context.id);
+                if (previous !== undefined &&
+                    JSON.stringify(previous) !== JSON.stringify(context)) {
+                    this.#changedContexts.add(context.id);
+                    for (const item of this.#sources.values())
+                        if (item.execution_context_id === context.id)
+                            this.revalidate(item);
+                }
+                if (retainNewMetadata)
+                    this.#contexts.set(context.id, context);
+            }
+            else if (event.method === "Debugger.scriptParsed") {
+                this.#retainedBytes += Buffer.byteLength(JSON.stringify(event.params));
+                if (this.#retainedBytes > WEB_RUNTIME_LIMITS.retainedEventBytes)
+                    throw new Error("Script metadata exceeds the complete 8 MiB event budget.");
+                const script = runtimeScriptParsedSchema.parse(event.params);
+                const previous = this.scripts.get(script.scriptId);
+                if (previous !== undefined &&
+                    JSON.stringify(previous) !== JSON.stringify(script)) {
+                    this.#changed.add(script.scriptId);
+                    const retained = this.#sources.get(script.scriptId);
+                    if (retained !== undefined)
+                        this.revalidate(retained);
+                }
+                if (retainNewMetadata)
+                    this.scripts.set(script.scriptId, script);
+            }
+        }
+        catch (cause) {
+            this.#failure = new AnalysisOutputError(this.session.operation, cause instanceof Error ? cause.message : String(cause));
+        }
+    }
+    /** Producer parse/resource failures are surfaced outside the transport event callback. */
+    check() {
+        if (this.#failure !== undefined)
+            throw this.#failure;
+    }
+    /** Frozen inventories still monitor known identities through asynchronous source reads. */
+    verifyKnownIdentity(event) {
+        if (event.method === "Debugger.scriptParsed") {
+            const id = scriptIdentitySchema.safeParse(event.params);
+            if (id.success && this.scripts.has(id.data.scriptId))
+                this.ingest(event, false);
+        }
+        else if (event.method === "Runtime.executionContextCreated") {
+            const id = contextIdentitySchema.safeParse(event.params);
+            if (id.success && this.#contexts.has(id.data.context.id))
+                this.ingest(event, false);
+        }
+    }
+    /** Only proven default worlds of the selected main frame establish website source ownership. */
+    belongsToDocument(scriptId) {
+        const script = this.scripts.get(scriptId);
+        if (script === undefined ||
+            this.#changed.has(scriptId) ||
+            this.#changedContexts.has(script.executionContextId))
+            return false;
+        const scriptContext = script.executionContextAuxData;
+        const context = this.#contexts.get(script.executionContextId)?.auxData;
+        const worlds = [scriptContext, context];
+        if (worlds.some((world) => world?.isDefault === false ||
+            (world?.type !== undefined && world.type !== "default")) ||
+            !worlds.some((world) => world?.isDefault === true || world?.type === "default"))
+            return false;
+        const reported = scriptContext?.frameId;
+        const contextFrame = context?.frameId;
+        return ((reported === undefined ||
+            contextFrame === undefined ||
+            reported === contextFrame) &&
+            (reported ?? contextFrame) === this.session.target.frame_id);
+    }
+    /** Retain complete script text and compute a digest distinct from the producer hash. */
+    async read(scriptIds) {
+        this.check();
+        for (const scriptId of new Set(scriptIds)) {
+            if (this.#sources.has(scriptId))
+                continue;
+            const script = this.scripts.get(scriptId);
+            const owned = this.belongsToDocument(scriptId);
+            const context = script === undefined
+                ? undefined
+                : this.#contexts.get(script.executionContextId);
+            const item = {
+                script_id: scriptId,
+                url: this.sourceUrl(scriptId, script?.url ?? ""),
+                execution_context_id: script?.executionContextId ?? null,
+                reported_execution_context: context === undefined ? null : jsonObjectSchema.parse(context),
+                reported_script_context_aux_data: script?.executionContextAuxData === undefined
+                    ? null
+                    : jsonObjectSchema.parse(script.executionContextAuxData),
+                frame_id: owned ? this.session.target.frame_id : null,
+                producer_hash: script?.hash ?? null,
+                source_map_url: script?.sourceMapURL ?? null,
+                has_source_url: script?.hasSourceURL ?? null,
+                language: script?.scriptLanguage ?? null,
+                resource_start: script !== undefined
+                    ? {
+                        line_number: script.startLine,
+                        column_number: script.startColumn,
+                    }
+                    : null,
+                source: {
+                    state: "excluded",
+                    reason: this.#changed.has(scriptId)
+                        ? "The script changed identity during observation; source attribution is unknown."
+                        : "Selected main-document default-world ownership was not established.",
+                },
+            };
+            if (owned && script?.scriptLanguage !== "WebAssembly")
+                item.source = await this.capture(scriptId);
+            else if (owned)
+                item.source = {
+                    state: "excluded",
+                    reason: "WebAssembly bytecode is outside this JavaScript source operation.",
+                };
+            this.revalidate(item);
+            this.#sources.set(scriptId, item);
+        }
+        this.check();
+        return [...this.#sources.values()];
+    }
+    /** Resolve an exact producer script ID; URL equality is never an identity fallback. */
+    location(scriptId, url, line, column, functionName = null) {
+        return {
+            script_id: scriptId,
+            url: url === null ? null : this.sourceUrl(scriptId, url),
+            line_number: line,
+            column_number: column,
+            function_name: functionName,
+            source_association: this.belongsToDocument(scriptId)
+                ? "script_id"
+                : "unknown",
+        };
+    }
+    /** Declared script names are inert evidence; known resource URLs omit transport userinfo. */
+    sourceUrl(scriptId, url) {
+        return !this.#changed.has(scriptId) &&
+            this.scripts.get(scriptId)?.hasSourceURL === false
+            ? sanitizeBrowserUrl(url).url
+            : url;
+    }
+    revalidate(item) {
+        if (item.frame_id === null || this.belongsToDocument(item.script_id))
+            return;
+        const previous = item.source.state === "unavailable"
+            ? ` Previous source read failure: ${item.source.reason}`
+            : "";
+        item.frame_id = null;
+        item.source = {
+            state: "excluded",
+            reason: `The script or context changed identity during source collection; attribution is unknown.${previous}`,
+        };
+    }
+    async capture(scriptId) {
+        let raw;
+        try {
+            raw = await this.session.command("Debugger.getScriptSource", {
+                scriptId,
+            });
+        }
+        catch (cause) {
+            if (this.session.options.signal?.aborted ||
+                !(cause instanceof AnalysisError))
+                throw cause;
+            return {
+                state: "unavailable",
+                reason: cause.userMessage ?? cause.message,
+            };
+        }
+        const source = z.object({ scriptSource: z.string() }).safeParse(raw);
+        if (!source.success)
+            throw new AnalysisOutputError(this.session.operation, "Debugger.getScriptSource returned malformed source text.");
+        const text = source.data.scriptSource;
+        const bytes = Buffer.byteLength(text);
+        this.#sourceBytes += bytes;
+        if (this.#sourceBytes > WEB_RUNTIME_LIMITS.sourceBytes)
+            throw new AnalysisOutputError(this.session.operation, "Complete runtime source evidence exceeds its 32 MiB budget; no partial evidence is returned.");
+        return {
+            state: "captured",
+            text,
+            sha256: createHash("sha256").update(text).digest("hex"),
+            utf8_bytes: bytes,
+            utf16_units: text.length,
+        };
+    }
+}