rea-agents 6.3.0 → 6.5.0

package/dist/browser/CdpSnapshotStrings.js

@@ -0,0 +1,21 @@
+import { numberValue } from "./CdpCaptureValues.js";
+// DOMSnapshot interns an empty or null string as index -1 instead of a table
+// entry. Chrome uses it for element node values and empty attribute values.
+const CDP_EMPTY_STRING_INDEX = -1;
+/** Resolve a DOMSnapshot name index, which must reference a string entry. */
+export const cdpSnapshotString = (strings, index) => {
+    const integer = numberValue(index);
+    if (integer === undefined || !Number.isSafeInteger(integer) || integer < 0)
+        return undefined;
+    return strings[integer];
+};
+/** Resolve a DOMSnapshot value index, where -1 is the protocol's empty string. */
+export const cdpSnapshotValueString = (strings, index) => numberValue(index) === CDP_EMPTY_STRING_INDEX
+    ? ""
+    : cdpSnapshotString(strings, index);
+/** Whether flattened name/value attribute indexes all resolve. */
+export const cdpSnapshotAttributesResolve = (strings, attributes) => attributes.length % 2 === 0 &&
+    attributes.every((attribute, offset) => attribute !== undefined &&
+        (offset % 2 === 0
+            ? cdpSnapshotString(strings, attribute)
+            : cdpSnapshotValueString(strings, attribute)) !== undefined);

package/dist/browser/CdpTargetSession.js

@@ -1,13 +1,40 @@
 import { BrowserObservationError } from "../domain/browserObservationError.js";
-import {} from "../domain/browserObservationErrors.js";
 import { CdpConnection } from "./CdpConnection.js";
-import { cdpTargetWebSocket, } from "./CdpEndpoint.js";
+import { cdpTargetWebSocket, discoverCdpBrowserSocket, discoverCdpEndpoint, withCdpDiscoveryDeadline, } from "./CdpEndpoint.js";
+/**
+ * Discover one passive browser endpoint through its selected transport. A
+ * browser socket's handshake and discovery share one discovery deadline.
+ */
+export const openCdpEndpoint = async (endpoint, operation, signal, timeoutMs) => {
+    if (endpoint.transport === "http_discovery")
+        return {
+            discovery: await discoverCdpEndpoint(endpoint.url, operation, signal),
+            connection: undefined,
+        };
+    return await withCdpDiscoveryDeadline(operation, signal, async (deadlineSignal) => {
+        const connection = await CdpConnection.connect(endpoint.url, operation, deadlineSignal);
+        try {
+            return {
+                discovery: await discoverCdpBrowserSocket(connection, endpoint.url, operation, deadlineSignal),
+                connection,
+            };
+        }
+        catch (cause) {
+            await connection.close();
+            throw cause;
+        }
+    }, timeoutMs);
+};
 /** Open one authorized target through its supported browser or page transport. */
 export const openCdpTargetSession = async (discovery, target, operation, signal, limits) => {
     const webSocket = cdpTargetWebSocket(discovery, target, operation);
     const connection = await CdpConnection.connect(webSocket.url, operation, signal, limits);
     if (webSocket.scope === "page")
         return { connection, sessionId: undefined };
+    return await attachCdpTargetSession(connection, target, operation, signal);
+};
+/** Attach one target through an open browser socket, which the session then owns. */
+export const attachCdpTargetSession = async (connection, target, operation, signal) => {
     try {
         const attached = await connection.send("Target.attachToTarget", { targetId: target.id, flatten: true }, undefined, signal);
         return { connection, sessionId: attachedSessionId(attached, operation) };
@@ -20,43 +47,39 @@ export const openCdpTargetSession = async (discovery, target, operation, signal,
 /** Disable enabled domains, detach browser sessions, and close REA's socket. */
 export const closeCdpTargetSession = async (targetSession, enabledDomains, signal) => {
     const { connection, sessionId } = targetSession;
-    for (const [index, domain] of enabledDomains.entries()) {
-        if (signal?.aborted === true) {
-            await closeCancelledTargetSession(targetSession, enabledDomains.slice(index));
-            return;
-        }
-        try {
-            await connection.send(`${domain}.disable`, {}, sessionId, signal);
-        }
-        catch (cause) {
-            // best-effort cleanup: domain disable continues to detach/close boundary.
-            void cause;
-        }
-    }
-    if (signal?.aborted === true) {
-        await closeCancelledTargetSession(targetSession, []);
-        return;
-    }
-    if (sessionId !== undefined)
-        try {
-            await connection.send("Target.detachFromTarget", { sessionId }, undefined, signal);
-        }
-        catch (cause) {
-            // best-effort cleanup: closing REA's socket is the final cleanup boundary.
-            void cause;
-        }
-    await connection.close();
-};
-const closeCancelledTargetSession = async ({ connection, sessionId }, enabledDomains) => {
-    const commands = enabledDomains.map((domain) => connection.send(`${domain}.disable`, {}, sessionId));
-    if (sessionId !== undefined)
-        commands.push(connection.send("Target.detachFromTarget", { sessionId }));
-    const settled = Promise.allSettled(commands);
+    const cleanup = new AbortController();
+    const domainSignal = signal === undefined
+        ? cleanup.signal
+        : AbortSignal.any([cleanup.signal, signal]);
+    const timeout = setTimeout(() => cleanup.abort(), 1_000);
+    timeout.unref();
     try {
-        await connection.close();
+        if (signal?.aborted !== true) {
+            for (const domain of enabledDomains) {
+                if (domainSignal.aborted)
+                    break;
+                try {
+                    await connection.send(`${domain}.disable`, {}, sessionId, domainSignal);
+                }
+                catch {
+                    // Best-effort domain cleanup; transport close is the definitive boundary.
+                }
+            }
+        }
+        // Cancellation skips optional domain shutdown but still releases the
+        // attached session using its independent, bounded cleanup signal.
+        if (!cleanup.signal.aborted && sessionId !== undefined)
+            try {
+                await connection.send("Target.detachFromTarget", { sessionId }, undefined, cleanup.signal);
+            }
+            catch {
+                // Best-effort detach; transport close is the definitive boundary.
+            }
     }
     finally {
-        await settled;
+        clearTimeout(timeout);
+        cleanup.abort();
+        await connection.close();
     }
 };
 const attachedSessionId = (value, operation) => {

package/dist/browser/CdpWebMcpDiscovery.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { digestCanonicalValue } from "../domain/canonicalDigest.js";
-import { compositeKey } from "../domain/unicodeCodePointOrder.js";
+import { compareUnicodeCodePoints, compositeKey, } from "../domain/unicodeCodePointOrder.js";
 import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { allowedSanitizedUrl, delayWithCancellation, numberValue, recordValue, recordsValue, cdpStringValue, } from "./CdpCaptureValues.js";
@@ -223,24 +223,29 @@ const assertStableAuthorizedFrame = async (context, initialUrl, origins) => {
 };
 const ingestWebMcpEvent = (options) => {
     const { event, input, frames, tools, completeness, transientFrames, resolvedTransientFrames, } = options;
+    if (event.method !== "WebMCP.toolsAdded" &&
+        event.method !== "WebMCP.toolsRemoved")
+        return;
     const params = recordValue(event.params);
-    if (params === undefined)
+    if (params === undefined) {
+        completeness.exclude("webmcp_tools", "invalid_protocol_value");
         return;
+    }
     if (event.method === "WebMCP.toolsRemoved") {
-        for (const removed of recordsValue(params.tools)) {
+        for (const removed of webMcpEventTools(params.tools, completeness)) {
             const name = cdpStringValue(removed.name);
             const frameId = cdpStringValue(removed.frameId);
-            if (name === undefined || frameId === undefined)
+            if (name === undefined || frameId === undefined) {
+                completeness.exclude("webmcp_tools", "invalid_protocol_value");
                 continue;
+            }
             for (const [key, tool] of tools)
                 if (tool.name === name && tool.frame_id === frameId)
                     tools.delete(key);
         }
         return;
     }
-    if (event.method !== "WebMCP.toolsAdded")
-        return;
-    for (const declared of recordsValue(params.tools)) {
+    for (const declared of webMcpEventTools(params.tools, completeness)) {
         const frameId = cdpStringValue(declared.frameId);
         if (frameId !== undefined && transientFrames.has(frameId)) {
             if (!resolvedTransientFrames.has(frameId))
@@ -254,19 +259,53 @@ const ingestWebMcpEvent = (options) => {
         tools.set(normalized.tool_key, normalized);
     }
 };
+const webMcpEventTools = (value, completeness) => {
+    if (!Array.isArray(value)) {
+        completeness.exclude("webmcp_tools", "invalid_protocol_value");
+        return [];
+    }
+    const records = [];
+    for (const item of value) {
+        const record = recordValue(item);
+        if (record === undefined) {
+            completeness.exclude("webmcp_tools", "invalid_protocol_value");
+            continue;
+        }
+        records.push(record);
+    }
+    return records;
+};
 const normalizeTool = (value, input, frames, completeness) => {
     const frameId = cdpStringValue(value.frameId);
     const name = cdpStringValue(value.name);
     const frame = frameId === undefined ? undefined : frames.get(frameId);
-    if (frameId === undefined ||
-        name === undefined ||
-        frame?.origin === null ||
-        frame === undefined) {
+    if (frameId === undefined || name === undefined) {
+        completeness.exclude("webmcp_tools", "invalid_protocol_value");
+        return undefined;
+    }
+    if (frame?.origin === null || frame === undefined) {
         completeness.exclude("webmcp_tools", "out_of_target_scope");
         return undefined;
     }
     const description = cdpStringValue(value.description) ?? "";
     const annotations = recordValue(value.annotations);
+    const malformedAnnotations = Object.hasOwn(value, "annotations") && annotations === undefined;
+    if (malformedAnnotations)
+        completeness.exclude("webmcp_tools", "invalid_protocol_value");
+    const annotation = (key) => {
+        if (annotations === undefined || !Object.hasOwn(annotations, key))
+            return null;
+        const hint = annotations[key];
+        if (typeof hint === "boolean")
+            return hint;
+        completeness.exclude("webmcp_tools", "invalid_protocol_value");
+        return null;
+    };
+    const consequential = annotation("consequential");
+    const unknownConsequential = malformedAnnotations ||
+        (annotations !== undefined &&
+            Object.hasOwn(annotations, "consequential") &&
+            typeof annotations.consequential !== "boolean");
     const declaration = jsonValueSchema.safeParse(value.inputSchema);
     if (!declaration.success)
         completeness.exclude("webmcp_tools", "invalid_protocol_value");
@@ -286,9 +325,10 @@ const normalizeTool = (value, input, frames, completeness) => {
             ? digestCanonicalValue(schema)
             : null,
         annotations: {
-            read_only: booleanOrNull(annotations?.readOnly),
-            untrusted_content: booleanOrNull(annotations?.untrustedContent),
-            autosubmit: booleanOrNull(annotations?.autosubmit),
+            read_only: annotation("readOnly"),
+            untrusted_content: annotation("untrustedContent"),
+            ...(unknownConsequential ? {} : { consequential }),
+            autosubmit: annotation("autosubmit"),
         },
         registration_source: registrationSource(recordValue(value.stackTrace), new Set(input.allowed_origins)),
         trust: "page-declared-untrusted",
@@ -319,7 +359,7 @@ const buildWebMcpResult = (options) => {
         status: available ? "available" : "unavailable",
         tools: {
             total: tools.size + completeness.droppedTotal,
-            items: [...tools.values()].sort((left, right) => left.tool_key.localeCompare(right.tool_key)),
+            items: [...tools.values()].sort((left, right) => compareUnicodeCodePoints(left.tool_key, right.tool_key)),
         },
         completeness: completeness.snapshot(),
         limitations,
@@ -332,7 +372,6 @@ const toolKey = (frameUrl, frameId, name) =>
 `webmcp_${createHash("sha256")
     .update(compositeKey([frameUrl, frameId, name]))
     .digest("hex")}`;
-const booleanOrNull = (value) => typeof value === "boolean" ? value : null;
 const integerOrNull = (value) => {
     const number = numberValue(value);
     return number === undefined ? null : Math.max(0, Math.trunc(number));

package/dist/browser/ElectronFileScope.js

@@ -1,6 +1,7 @@
-import { realpath, stat } from "node:fs/promises";
-import { isAbsolute } from "node:path";
+import { open, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { admitAsarHeader, MAX_ASAR_HEADER_BYTES, } from "../artifacts/AsarHeader.js";
 /** Resolve one local file URL while rejecting remote hosts and encoded separators. */
 export const authorizedElectronFile = async (value) => {
     if (/%(?:2f|5c)/iu.test(value))
@@ -30,16 +31,105 @@ export const authorizedElectronFile = async (value) => {
     }
     if (!isAbsolute(path) || path.includes("\0"))
         return undefined;
-    let canonical;
     try {
-        if (!(await stat(path)).isFile())
-            return undefined;
-        canonical = await realpath(path);
+        if ((await stat(path)).isFile())
+            return await realpath(path);
     }
     catch (cause) {
-        // Missing or unreadable files cannot authorize a local file.
+        // Electron serves packaged pages from inside app.asar, which the host
+        // filesystem cannot stat; resolve those through the archive header below.
         void cause;
-        return undefined;
     }
-    return canonical;
+    return await authorizedAsarMember(path);
+};
+/**
+ * Resolve `<archive>.asar/<member>` the way Electron's file protocol does: the
+ * first `.asar` path component that is a regular file is the archive, and the
+ * remainder must name a regular file in its header (packed or unpacked).
+ */
+const authorizedAsarMember = async (path) => {
+    const segments = path.split(sep);
+    for (let index = 1; index < segments.length - 1; index += 1) {
+        if (!(segments[index] ?? "").toLowerCase().endsWith(".asar"))
+            continue;
+        const archive = segments.slice(0, index + 1).join(sep);
+        const member = segments.slice(index + 1);
+        if (member.some((part) => part === "" || part === "." || part === ".."))
+            return undefined;
+        try {
+            const metadata = await stat(archive);
+            if (!metadata.isFile())
+                continue;
+            const canonical = await realpath(archive);
+            const files = await asarFiles(canonical, metadata);
+            return isAsarRegularFile(files, member)
+                ? join(canonical, ...member)
+                : undefined;
+        }
+        catch (cause) {
+            // An unreadable or malformed archive cannot authorize its members.
+            void cause;
+            return undefined;
+        }
+    }
+    return undefined;
+};
+// This is a retained-memory budget for JSON headers, shared across all archives.
+const MAX_CACHED_HEADERS = 8;
+const headerCache = new Map();
+const archiveIdentity = (metadata) => `${String(metadata.dev)}:${String(metadata.ino)}:${String(metadata.size)}:${String(metadata.mtimeMs)}`;
+/** Read the two Chromium pickle headers on one handle before allocating JSON. */
+const asarFiles = async (archive, metadata) => {
+    const identity = archiveIdentity(metadata);
+    const cached = headerCache.get(archive);
+    if (cached?.identity === identity)
+        return cached.files;
+    const handle = await open(archive, "r");
+    let files;
+    let jsonBytes;
+    try {
+        const opened = await handle.stat();
+        if (!opened.isFile() || archiveIdentity(opened) !== identity)
+            throw new Error("ASAR identity changed before header read");
+        const admitted = await admitAsarHeader(handle);
+        jsonBytes = admitted.jsonBytes;
+        const json = Buffer.alloc(jsonBytes);
+        let offset = 0;
+        while (offset < json.length) {
+            const part = await handle.read(json, offset, json.length - offset, 16 + offset);
+            if (part.bytesRead === 0)
+                throw new Error("Truncated ASAR JSON header");
+            offset += part.bytesRead;
+        }
+        if (archiveIdentity(await handle.stat()) !== identity)
+            throw new Error("ASAR identity changed during header read");
+        const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(json));
+        if (!isRecord(parsed) || !isRecord(parsed.files))
+            throw new Error("ASAR header has no file tree");
+        files = parsed.files;
+    }
+    finally {
+        await handle.close();
+    }
+    headerCache.delete(archive);
+    headerCache.set(archive, { identity, files, bytes: jsonBytes });
+    const retainedBytes = () => [...headerCache.values()].reduce((sum, entry) => sum + entry.bytes, 0);
+    while (headerCache.size > MAX_CACHED_HEADERS ||
+        retainedBytes() > MAX_ASAR_HEADER_BYTES)
+        headerCache.delete(headerCache.keys().next().value ?? archive);
+    return files;
+};
+const isAsarRegularFile = (files, member) => {
+    let node = { files };
+    for (const part of member) {
+        const children = isRecord(node) ? node.files : undefined;
+        if (!isRecord(children) || !Object.hasOwn(children, part))
+            return false;
+        node = children[part];
+    }
+    return (isRecord(node) &&
+        typeof node.size === "number" &&
+        !("files" in node) &&
+        !("link" in node));
 };
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/browser/PlaywrightBrowserScenarioProvider.js

@@ -89,7 +89,7 @@ const executeStep = async (input) => {
             eventEnd: session.lastEventSequence(),
             artifacts: unavailableArtifacts(requested, "action was not executed after an earlier failure"),
         });
-    const actionStartedAt = Date.now();
+    const actionStartedAt = performance.now();
     session.setStep(stepIndex);
     const requestCancelled = () => signal?.aborted === true;
     let outcome = {
@@ -118,7 +118,7 @@ const executeStep = async (input) => {
         stepId: action.step_id,
         action: action.action,
         ...outcome,
-        elapsedMs: Date.now() - actionStartedAt,
+        elapsedMs: Math.max(0, Math.round(performance.now() - actionStartedAt)),
         beforeUrl,
         afterUrl: session.sanitizeUrl(session.currentUrl()),
         eventStart,
@@ -135,18 +135,21 @@ const globalCompleteness = (scenario, session, steps) => {
         missing.push("events");
     return classifyBrowserScenarioCompleteness(missing, truncated);
 };
-const runScenario = async (openSession, scenario, options) => {
+const runScenario = async (openSession, scenario, options, retainCleanup) => {
     if (options.signal?.aborted === true)
         throw new BrowserObservationError(OPERATION, "cancelled");
-    const startedAt = Date.now();
-    const session = await openSession(scenario, options.signal === undefined ? {} : { signal: options.signal });
+    const startedAt = performance.now();
+    const session = await openSession(scenario, {
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        retainCleanup,
+    });
     const steps = [];
     let operationOutcome = { ok: true };
     try {
         steps.push(await initialStep({
             session,
             scenario,
-            elapsedMs: Date.now() - startedAt,
+            elapsedMs: Math.max(0, Math.round(performance.now() - startedAt)),
             signal: options.signal,
         }));
         let failed = false;
@@ -172,6 +175,7 @@ const runScenario = async (openSession, scenario, options) => {
     }
     catch (cause) {
         cleanupOutcome = { ok: false, cause };
+        retainCleanup(() => session.close());
     }
     if (!cleanupOutcome.ok) {
         const cleanup = browserScenarioCleanupObservation(cleanupOutcome.cause);
@@ -226,15 +230,33 @@ const runScenario = async (openSession, scenario, options) => {
 /** Controlled Playwright/CDP scenario driver with exact process ownership. */
 export class PlaywrightBrowserScenarioProvider {
     openSession;
+    #tail = Promise.resolve();
+    #closing = false;
+    #closePromise;
+    #pendingCleanup = new Set();
     constructor(openSession) {
         this.openSession = openSession;
     }
     identity() {
         return PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY;
     }
-    async captureScenario(scenario, options = {}) {
+    captureScenario(scenario, options = {}) {
+        if (this.#closing)
+            return Promise.resolve(err(this.#closedError()));
+        const operation = this.#tail.then(() => this.#closing
+            ? err(this.#closedError())
+            : this.#captureScenario(scenario, options));
+        this.#tail = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+    async #captureScenario(scenario, options) {
+        const pending = await this.#retryCleanup();
+        if (pending !== undefined)
+            return err(pending);
         try {
-            return ok(await runScenario(this.openSession, scenario, options));
+            return ok(await runScenario(this.openSession, scenario, options, (close) => {
+                this.#pendingCleanup.add(close);
+            }));
         }
         catch (cause) {
             if (cause instanceof AnalysisError)
@@ -242,4 +264,38 @@ export class PlaywrightBrowserScenarioProvider {
             return err(new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, OPERATION, { cause }));
         }
     }
+    async close() {
+        this.#closing = true;
+        this.#closePromise ??= this.#tail
+            .then(async () => {
+            const failure = await this.#retryCleanup();
+            if (failure !== undefined)
+                throw failure;
+        })
+            .catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
+        return this.#closePromise;
+    }
+    #closedError() {
+        return new BrowserObservationError(OPERATION, "cleanup_failed", {
+            detail: "Browser scenario provider is closing.",
+            cleanup: { reason: "Provider is closing", resources: [] },
+        });
+    }
+    async #retryCleanup() {
+        for (const pending of this.#pendingCleanup) {
+            try {
+                await pending();
+                this.#pendingCleanup.delete(pending);
+            }
+            catch (cause) {
+                return cause instanceof AnalysisError
+                    ? cause
+                    : new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, OPERATION, { cause });
+            }
+        }
+        return undefined;
+    }
 }

package/dist/browser/PlaywrightElectronActiveActions.js

@@ -42,7 +42,7 @@ const windowMetadataSchema = z.strictObject({
 export const runElectronActions = async (application, input, options) => {
     const actions = [];
     for (const action of input.actions) {
-        const actionStartedAt = Date.now();
+        const actionStartedAt = performance.now();
         const windowIndex = actionWindowIndex(action);
         let selectedWindow;
         try {
@@ -73,7 +73,7 @@ export const runElectronActions = async (application, input, options) => {
                 window_index: windowIndex,
                 target: selectedWindow === undefined ? null : `window:${String(windowIndex)}`,
                 status: "completed",
-                elapsed_ms: Date.now() - actionStartedAt,
+                elapsed_ms: Math.max(0, Math.round(performance.now() - actionStartedAt)),
                 error: null,
             });
         }
@@ -84,7 +84,7 @@ export const runElectronActions = async (application, input, options) => {
                 window_index: windowIndex,
                 target: selectedWindow === undefined ? null : `window:${String(windowIndex)}`,
                 status: options.signal?.aborted ? "cancelled" : "failed",
-                elapsed_ms: Date.now() - actionStartedAt,
+                elapsed_ms: Math.max(0, Math.round(performance.now() - actionStartedAt)),
                 error: safeActionErrorMessage(cause),
             });
             break;
@@ -233,7 +233,7 @@ export const runWithExecutionLimits = async (operation, signal, deadline) => {
     const interruptions = [];
     if (deadline !== undefined)
         interruptions.push(new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new BrowserObservationError(OPERATION, "timeout")), Math.max(1, deadline - Date.now()));
+            timer = setTimeout(() => reject(new BrowserObservationError(OPERATION, "timeout")), Math.max(1, deadline - performance.now()));
         }));
     if (signal !== undefined)
         interruptions.push(new Promise((_, reject) => {

package/dist/browser/PlaywrightElectronActiveProjection.js

@@ -37,14 +37,13 @@ const eventFamily = (kind, processType) => {
         return processType === "renderer" ? "renderer-ipc" : "ipc";
     return ipcEventKinds.has(kind) ? "ipc" : kind;
 };
-const createCoverage = (hookSnapshot) => {
+const normalizeObservations = (hookSnapshot) => {
     const observedEventFamilies = [
         ...new Set([
             ...hookSnapshot.events.map(({ kind, process_type }) => eventFamily(kind, process_type)),
             ...hookSnapshot.dropped_event_families.map(({ family }) => family),
         ]),
     ].sort();
-    const unavailableEventFamilies = new Set(observableEventFamilies.filter((family) => !observedEventFamilies.includes(family)));
     const observedRoles = [
         ...new Set([
             ...hookSnapshot.events.flatMap(({ process_type, kind }) => [
@@ -63,6 +62,11 @@ const createCoverage = (hookSnapshot) => {
             ...hookSnapshot.dropped_event_roles.map(({ role }) => role),
         ]),
     ].sort();
+    return { observedEventFamilies, observedRoles };
+};
+const createCoverage = (hookSnapshot, observations) => {
+    const { observedEventFamilies, observedRoles } = observations;
+    const unavailableEventFamilies = new Set(observableEventFamilies.filter((family) => !observedEventFamilies.includes(family)));
     if (!observedRoles.includes("preload"))
         unavailableEventFamilies.add("preload");
     if (!observedRoles.includes("renderer"))
@@ -75,9 +79,12 @@ const createCoverage = (hookSnapshot) => {
         pre_capture_activity: "unavailable",
     };
 };
+const hasUnattributedDroppedPreloadFamily = (hookSnapshot) => hookSnapshot.dropped_event_families.some(({ family, count }) => family === "preload" && count > 0);
+const hasObservedPreloadConfiguration = (observations) => observations.observedEventFamilies.includes("preload-configuration");
 /** Project one provider hook snapshot into the canonical public result. */
 export const projectElectronActiveCapture = (paths, actions, state) => {
     const { hookSnapshot } = state;
+    const observations = normalizeObservations(hookSnapshot);
     const ipcEvents = hookSnapshot.events.filter(({ kind }) => ipcEventKinds.has(kind));
     return electronActiveObservationResultSchema.parse({
         application: {
@@ -115,17 +122,22 @@ export const projectElectronActiveCapture = (paths, actions, state) => {
             observed_runtime: hookSnapshot.observed_runtime,
             dropped_runtime: hookSnapshot.dropped_runtime,
         },
-        coverage: createCoverage(hookSnapshot),
+        coverage: createCoverage(hookSnapshot, observations),
         limitations: [
             "IPC payloads are represented by value shapes; payload values are never retained.",
             "IPC direction and sender/receiver identifiers are observed only where Electron exposes them at the hooked boundary.",
             "The runtime timeline records lifecycle, navigation, shell, permission, popup, download, protocol, preload, native-addon, process, and IPC events; activity before hook installation is unavailable.",
             "The preload and renderer process contexts are not instrumented by the main-process -r hook; preload configuration and contextBridge API-shape events are main-boundary observations, not proof of renderer-side execution.",
-            ...(!hookSnapshot.events.some(({ kind }) => kind === "preload")
+            ...(!hasObservedPreloadConfiguration(observations)
                 ? [
                     "Preload configuration was not exposed by the observed Electron window metadata. Preload paths and execution remain unavailable.",
                 ]
                 : []),
+            ...(hasUnattributedDroppedPreloadFamily(hookSnapshot)
+                ? [
+                    "Dropped preload-family events were not attributed to preload configuration; independently aggregated event families and roles cannot establish that relationship.",
+                ]
+                : []),
             "Process metrics are an Electron API snapshot and do not prove hostile-local-user isolation.",
             ...(hookSnapshot.dropped > 0
                 ? [