@netkitty/analysis 1.0.0

package/dist/lib/streaming/worker/AnalysisWorkerCore.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installAnalysisHandlers = installAnalysisHandlers;
+const codec_1 = require("@netkitty/codec");
+const pcap_core_1 = require("@netkitty/pcap-core");
+const ColumnarIndexStore_1 = require("../stores/ColumnarIndexStore");
+const FrameIndexer_1 = require("../indexer/FrameIndexer");
+const PcapIndexBuilder_1 = require("../indexer/PcapIndexBuilder");
+const FilterExpression_1 = require("../filter/FilterExpression");
+const BuiltinScans_1 = require("./BuiltinScans");
+const SyntheticFrame_1 = require("./SyntheticFrame");
+/**
+ * Environment-agnostic analysis-worker logic: owns the read backend, columnar index, indexer
+ * dictionaries and codec, and wires all request handlers plus watch tailing onto the given endpoint.
+ * `makeBackend` adapts the source (node: a path string → NodeFileReadBackend; browser: a Blob →
+ * BrowserFileReadBackend). node and browser worker entrypoints each call this with their endpoint and
+ * backend factory, so the handler logic lives in one place.
+ */
+function installAnalysisHandlers(endpoint, makeBackend) {
+    const store = new ColumnarIndexStore_1.ColumnarIndexStore();
+    const indexer = new FrameIndexer_1.FrameIndexer(store);
+    const codec = new codec_1.Codec();
+    let backend = null;
+    function frameRow(record) {
+        return {
+            index: record.index,
+            timestamp: record.timestamp,
+            length: record.capturedLength,
+            topProtocol: indexer.protocolName(record.protocolId),
+            conversationKey: indexer.conversationKey(record.conversationHash),
+            info: ''
+        };
+    }
+    async function materializeFrame(index, needs) {
+        const record = store.get(index);
+        if (!record || !backend)
+            return null;
+        const bytes = await backend.read(record.fileOffset, record.capturedLength);
+        const layers = await codec.decode(Buffer.from(bytes));
+        //JSON round-trip strips the FlexibleObject proxy / closures so the layer tree is structured-cloneable.
+        const plain = JSON.parse(JSON.stringify(layers));
+        //Projection: a reducer that declares `needs` only receives those layers, cutting cross-thread bytes.
+        const projected = needs ? plain.filter((layer) => needs.includes(layer.id)) : plain;
+        return { ...frameRow(record), capturedLength: record.capturedLength, layers: projected };
+    }
+    endpoint.handle('open', async (payload) => {
+        const { source } = payload;
+        backend = makeBackend(source);
+        const builder = new PcapIndexBuilder_1.PcapIndexBuilder(indexer, codec);
+        const frameCount = await builder.build(backend, {
+            onProgress: (bytesRead, totalBytes) => {
+                endpoint.notify('progress', { frames: store.count(), bytesRead: bytesRead, totalBytes: totalBytes });
+            }
+        });
+        endpoint.notify('complete', { frameCount: frameCount });
+        return { frameCount: frameCount };
+    });
+    endpoint.handle('frameCount', () => store.count());
+    //Built-in stats computed inside the worker by scanning the index columns (no decode, no frame
+    //transfer, main thread stays free). Results equal ConversationsReducer/EndpointsReducer.
+    endpoint.handle('conversations', () => (0, BuiltinScans_1.computeConversations)(store, (hash) => indexer.conversationKey(hash)));
+    endpoint.handle('endpoints', () => (0, BuiltinScans_1.computeEndpoints)(store, (hash) => indexer.conversationKey(hash)));
+    //Display filter with a column pre-filter: decide each frame from the index columns (conversation
+    //key + top protocol) first, and only re-decode the frames a predicate can't settle from columns
+    //(direction-sensitive fields, deeper protocols). Common filters (ip.addr / tcp.port / tcp|udp|arp)
+    //are answered entirely from the index — no decode.
+    endpoint.handle('filter', async (payload) => {
+        const { displayFilter } = payload;
+        const expression = (0, FilterExpression_1.parseFilter)(displayFilter);
+        const matches = [];
+        if (!backend)
+            return matches;
+        const first = store.firstIndex();
+        const end = first + store.count();
+        for (let index = first; index < end; index++) {
+            const record = store.get(index);
+            if (!record)
+                continue;
+            const conversationKey = indexer.conversationKey(record.conversationHash);
+            const topProtocol = indexer.protocolName(record.protocolId);
+            const decided = (0, FilterExpression_1.matchesIndexed)(expression, conversationKey, topProtocol, record.directionForward);
+            if (decided === true) {
+                matches.push(index);
+                continue;
+            }
+            if (decided === false)
+                continue;
+            const bytes = await backend.read(record.fileOffset, record.capturedLength);
+            const layers = await codec.decode(Buffer.from(bytes));
+            if ((0, FilterExpression_1.matchesFilter)(layers, expression))
+                matches.push(index);
+        }
+        return matches;
+    });
+    endpoint.handle('getFrames', (payload) => {
+        const { from, to } = payload;
+        return store.range(from, to).map(frameRow);
+    });
+    endpoint.handle('getFrame', async (payload) => {
+        const { index } = payload;
+        return materializeFrame(index);
+    });
+    //Batch of materialized frames (with layers, optionally projected to `needs`), for reducer replay.
+    //v1 re-decodes each frame; a v2 optimization runs built-in reducers inside the worker over columns.
+    endpoint.handle('getFrameBatch', async (payload) => {
+        const { from, to, needs, indexOnly } = payload;
+        const out = [];
+        for (let index = from; index < to; index++) {
+            if (indexOnly) {
+                //indexOnly reducer: synthesize the five-tuple frame from index columns, skip decode.
+                const record = store.get(index);
+                if (!record)
+                    continue;
+                const key = indexer.conversationKey(record.conversationHash);
+                const layers = key !== null ? (0, SyntheticFrame_1.synthesizeLayers)(key, record.directionForward) : [];
+                out.push({ ...frameRow(record), capturedLength: record.capturedLength, layers: layers });
+            }
+            else {
+                const frame = await materializeFrame(index, needs);
+                if (frame !== null)
+                    out.push(frame);
+            }
+        }
+        return out;
+    });
+    //--- watch (tail) ----------------------------------------------------------------------------
+    //Incremental tail: one long-lived parser, pread newly-appended bytes at a tracked position, index
+    //each new frame and push it (with layers) as a 'frame' notify for live reducer feeding. maxFrames
+    //caps the index via FIFO eviction so watch memory stays bounded.
+    let watchParser = null;
+    let watchPosition = 0;
+    let watchLastData = Buffer.alloc(0);
+    let watchPending = [];
+    let watchMaxFrames = Number.POSITIVE_INFINITY;
+    let pumping = false;
+    let pumpAgain = false;
+    let watchTimer = null;
+    async function drainWatch() {
+        for (const frame of watchPending) {
+            const layers = await codec.decode(frame.data);
+            const timestamp = frame.info.seconds + frame.info.microseconds / 1_000_000;
+            const index = indexer.add(layers, frame.info.packetOffset, frame.info.packetLength, frame.info.packetLength, timestamp);
+            const record = store.get(index);
+            if (record) {
+                endpoint.notify('frame', { ...frameRow(record), capturedLength: record.capturedLength, layers: JSON.parse(JSON.stringify(layers)) });
+            }
+            if (store.count() > watchMaxFrames)
+                store.evictOldest(store.count() - watchMaxFrames);
+        }
+        watchPending = [];
+    }
+    async function pumpWatch() {
+        if (pumping) {
+            pumpAgain = true;
+            return;
+        }
+        pumping = true;
+        do {
+            pumpAgain = false;
+            if (!backend || !watchParser)
+                break;
+            const size = await backend.size();
+            while (watchPosition < size) {
+                const length = Math.min(65536, size - watchPosition);
+                const bytes = await backend.read(watchPosition, length);
+                if (bytes.length === 0)
+                    break;
+                watchPosition += bytes.length;
+                watchParser.write(Buffer.from(bytes));
+                await drainWatch();
+            }
+        } while (pumpAgain);
+        pumping = false;
+    }
+    endpoint.handle('watch', async (payload) => {
+        const { source, maxFrames } = payload;
+        backend = makeBackend(source);
+        watchMaxFrames = maxFrames !== undefined ? maxFrames : Number.POSITIVE_INFINITY;
+        watchPosition = 0;
+        watchPending = [];
+        watchParser = new pcap_core_1.PcapParserCore({
+            onPacketData: (data) => { watchLastData = data; },
+            onPacket: (info) => { watchPending.push({ info: info, data: watchLastData }); }
+        });
+        await pumpWatch();
+        //Active polling rather than fs.watch events: a self-driven timer tails reliably even under load.
+        if (watchTimer !== null)
+            clearInterval(watchTimer);
+        watchTimer = setInterval(() => { void pumpWatch(); }, 100);
+        return { frameCount: store.count() };
+    });
+}

package/dist/lib/streaming/worker/BuiltinScans.d.ts

@@ -0,0 +1,23 @@
+import { IIndexStore } from '../interfaces/IIndexStore';
+import { ConversationSummary } from '../reducers/ConversationsReducer';
+import { EndpointSummary } from '../reducers/EndpointsReducer';
+/**
+ * Built-in Conversations/Endpoints computed by scanning the index columns directly — no re-decode, no
+ * cross-thread frame transfer. Everything these reducers need (the five-tuple via keyOf, captured
+ * length, timestamp, and the direction bit) is already in the index. Runs inside the worker; only the
+ * small result table crosses back to the main thread, so the main thread stays free. Results are
+ * identical to ConversationsReducer/EndpointsReducer, just derived from columns instead of layers.
+ *
+ * Hot loops key their caches on the numeric conversationHash (fast Map) and resolve/parse the string
+ * key only once per conversation, so cost is ~one Map lookup + a few field bumps per frame.
+ */
+export declare function computeConversations(store: IIndexStore, keyOf: (conversationHash: number) => string | null): ConversationSummary[];
+/**
+ * Built-in Endpoints table, computed by scanning the index columns directly (no re-decode). Groups
+ * every frame's two endpoints, accumulating per-address total/tx/rx packet and byte counts from the
+ * direction bit. Result matches EndpointsReducer.
+ * @param store index columns to scan.
+ * @param keyOf resolves a conversation hash to its `protocol|endpointA|endpointB` key, or null when unknown.
+ * @returns one summary per distinct endpoint address seen.
+ */
+export declare function computeEndpoints(store: IIndexStore, keyOf: (conversationHash: number) => string | null): EndpointSummary[];

package/dist/lib/streaming/worker/BuiltinScans.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeConversations = computeConversations;
+exports.computeEndpoints = computeEndpoints;
+/**
+ * Built-in Conversations/Endpoints computed by scanning the index columns directly — no re-decode, no
+ * cross-thread frame transfer. Everything these reducers need (the five-tuple via keyOf, captured
+ * length, timestamp, and the direction bit) is already in the index. Runs inside the worker; only the
+ * small result table crosses back to the main thread, so the main thread stays free. Results are
+ * identical to ConversationsReducer/EndpointsReducer, just derived from columns instead of layers.
+ *
+ * Hot loops key their caches on the numeric conversationHash (fast Map) and resolve/parse the string
+ * key only once per conversation, so cost is ~one Map lookup + a few field bumps per frame.
+ */
+function computeConversations(store, keyOf) {
+    const byHash = new Map();
+    const first = store.firstIndex();
+    const end = first + store.count();
+    for (let i = first; i < end; i++) {
+        const record = store.get(i);
+        if (!record)
+            continue;
+        let conversation = byHash.get(record.conversationHash);
+        if (conversation === undefined) {
+            const key = keyOf(record.conversationHash);
+            if (key === null) {
+                byHash.set(record.conversationHash, null);
+                continue;
+            }
+            const bar1 = key.indexOf('|');
+            const bar2 = key.indexOf('|', bar1 + 1);
+            conversation = {
+                protocol: key.slice(0, bar1),
+                endpointA: key.slice(bar1 + 1, bar2),
+                endpointB: key.slice(bar2 + 1),
+                packets: 0,
+                bytes: 0,
+                packetsAToB: 0,
+                packetsBToA: 0,
+                firstTimestamp: record.timestamp,
+                lastTimestamp: record.timestamp,
+                firstIndex: record.index,
+                lastIndex: record.index
+            };
+            byHash.set(record.conversationHash, conversation);
+        }
+        if (conversation === null)
+            continue;
+        conversation.packets++;
+        conversation.bytes += record.capturedLength;
+        if (record.directionForward)
+            conversation.packetsAToB++;
+        else
+            conversation.packetsBToA++;
+        if (record.timestamp < conversation.firstTimestamp)
+            conversation.firstTimestamp = record.timestamp;
+        if (record.timestamp > conversation.lastTimestamp)
+            conversation.lastTimestamp = record.timestamp;
+        if (record.index < conversation.firstIndex)
+            conversation.firstIndex = record.index;
+        if (record.index > conversation.lastIndex)
+            conversation.lastIndex = record.index;
+    }
+    const out = [];
+    for (const conversation of byHash.values())
+        if (conversation !== null)
+            out.push(conversation);
+    return out;
+}
+/**
+ * Built-in Endpoints table, computed by scanning the index columns directly (no re-decode). Groups
+ * every frame's two endpoints, accumulating per-address total/tx/rx packet and byte counts from the
+ * direction bit. Result matches EndpointsReducer.
+ * @param store index columns to scan.
+ * @param keyOf resolves a conversation hash to its `protocol|endpointA|endpointB` key, or null when unknown.
+ * @returns one summary per distinct endpoint address seen.
+ */
+function computeEndpoints(store, keyOf) {
+    const endpoints = new Map();
+    const byHash = new Map();
+    const first = store.firstIndex();
+    const end = first + store.count();
+    for (let i = first; i < end; i++) {
+        const record = store.get(i);
+        if (!record)
+            continue;
+        let pair = byHash.get(record.conversationHash);
+        if (pair === undefined) {
+            const key = keyOf(record.conversationHash);
+            if (key === null) {
+                byHash.set(record.conversationHash, null);
+                continue;
+            }
+            const bar1 = key.indexOf('|');
+            const bar2 = key.indexOf('|', bar1 + 1);
+            pair = { a: getOrCreate(endpoints, key.slice(bar1 + 1, bar2)), b: getOrCreate(endpoints, key.slice(bar2 + 1)) };
+            byHash.set(record.conversationHash, pair);
+        }
+        if (pair === null)
+            continue;
+        const source = record.directionForward ? pair.a : pair.b;
+        const destination = record.directionForward ? pair.b : pair.a;
+        source.packets++;
+        source.bytes += record.capturedLength;
+        source.txPackets++;
+        source.txBytes += record.capturedLength;
+        destination.packets++;
+        destination.bytes += record.capturedLength;
+        destination.rxPackets++;
+        destination.rxBytes += record.capturedLength;
+    }
+    return [...endpoints.values()];
+}
+function getOrCreate(endpoints, address) {
+    let endpoint = endpoints.get(address);
+    if (!endpoint) {
+        endpoint = { address: address, packets: 0, bytes: 0, txPackets: 0, txBytes: 0, rxPackets: 0, rxBytes: 0 };
+        endpoints.set(address, endpoint);
+    }
+    return endpoint;
+}

package/dist/lib/streaming/worker/IWorkerEndpoint.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The worker-side transport an analysis worker needs: register request handlers and push notifies.
+ * Implemented by WorkerEndpoint (node worker_threads) and WebWorkerEndpoint (browser Web Worker), so
+ * the worker handler logic (AnalysisWorkerCore) is written once against this interface.
+ */
+export interface IWorkerEndpoint {
+    handle(method: string, handler: (payload: unknown) => unknown | Promise<unknown>): void;
+    notify(method: string, payload?: unknown, transfer?: ArrayBuffer[]): void;
+}

package/dist/lib/streaming/worker/IWorkerEndpoint.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/streaming/worker/NodeWorkerChannel.d.ts

@@ -0,0 +1,16 @@
+import { Worker } from 'node:worker_threads';
+import { IWorkerChannel } from '../interfaces/IWorkerChannel';
+/**
+ * Main-thread side of the worker channel over a worker_threads Worker: correlated request/response
+ * (a monotonic id maps each reply to its promise), fire-and-forget notify, and notify handlers for
+ * worker→main pushes. terminate() kills the worker and rejects anything still in flight — this is how
+ * Analysis.close() releases the worker's whole heap in one shot.
+ */
+export declare class NodeWorkerChannel implements IWorkerChannel {
+    #private;
+    constructor(worker: Worker);
+    request<T>(method: string, payload?: unknown, transfer?: ArrayBuffer[]): Promise<T>;
+    notify(method: string, payload?: unknown, transfer?: ArrayBuffer[]): void;
+    on(method: string, handler: (payload: unknown) => void): void;
+    terminate(): void;
+}

package/dist/lib/streaming/worker/NodeWorkerChannel.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeWorkerChannel = void 0;
+/**
+ * Main-thread side of the worker channel over a worker_threads Worker: correlated request/response
+ * (a monotonic id maps each reply to its promise), fire-and-forget notify, and notify handlers for
+ * worker→main pushes. terminate() kills the worker and rejects anything still in flight — this is how
+ * Analysis.close() releases the worker's whole heap in one shot.
+ */
+class NodeWorkerChannel {
+    #worker;
+    #nextId = 1;
+    #pending = new Map();
+    #handlers = new Map();
+    constructor(worker) {
+        this.#worker = worker;
+        this.#worker.on('message', (message) => this.#onMessage(message));
+        this.#worker.on('error', (error) => this.#failAll(error));
+    }
+    request(method, payload, transfer) {
+        const id = this.#nextId++;
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, { resolve: resolve, reject: reject });
+            this.#worker.postMessage({ kind: 'request', id: id, method: method, payload: payload }, transfer ? transfer : []);
+        });
+    }
+    notify(method, payload, transfer) {
+        this.#worker.postMessage({ kind: 'notify', method: method, payload: payload }, transfer ? transfer : []);
+    }
+    on(method, handler) {
+        this.#handlers.set(method, handler);
+    }
+    terminate() {
+        void this.#worker.terminate();
+        this.#failAll(new Error('worker channel terminated'));
+    }
+    #onMessage(message) {
+        if (message.kind === 'response') {
+            const pending = this.#pending.get(message.id);
+            if (!pending)
+                return;
+            this.#pending.delete(message.id);
+            if (message.ok)
+                pending.resolve(message.payload);
+            else
+                pending.reject(new Error(message.error !== undefined ? message.error : 'worker request failed'));
+        }
+        else if (message.kind === 'notify') {
+            const handler = this.#handlers.get(message.method);
+            if (handler)
+                handler(message.payload);
+        }
+    }
+    #failAll(error) {
+        for (const pending of this.#pending.values())
+            pending.reject(error);
+        this.#pending.clear();
+    }
+}
+exports.NodeWorkerChannel = NodeWorkerChannel;

package/dist/lib/streaming/worker/SyntheticFrame.d.ts

@@ -0,0 +1,8 @@
+import { CodecDecodeResult } from '@netkitty/codec';
+/**
+ * Rebuild the five-tuple layers of a frame from its index columns (conversation key + direction bit),
+ * without decoding the packet. Feeds indexOnly reducers on replay so they skip re-decode entirely.
+ * Only the fields flowOf reads are reconstructed (sip/dip/srcport/dstport or smac/dmac); deep fields
+ * are absent by design — that is why only reducers that declare indexOnly may be fed these frames.
+ */
+export declare function synthesizeLayers(conversationKey: string, directionForward: number): CodecDecodeResult[];

package/dist/lib/streaming/worker/SyntheticFrame.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.synthesizeLayers = synthesizeLayers;
+/**
+ * Rebuild the five-tuple layers of a frame from its index columns (conversation key + direction bit),
+ * without decoding the packet. Feeds indexOnly reducers on replay so they skip re-decode entirely.
+ * Only the fields flowOf reads are reconstructed (sip/dip/srcport/dstport or smac/dmac); deep fields
+ * are absent by design — that is why only reducers that declare indexOnly may be fed these frames.
+ */
+function synthesizeLayers(conversationKey, directionForward) {
+    const bar1 = conversationKey.indexOf('|');
+    const bar2 = conversationKey.indexOf('|', bar1 + 1);
+    const proto = conversationKey.slice(0, bar1);
+    const endpointA = conversationKey.slice(bar1 + 1, bar2);
+    const endpointB = conversationKey.slice(bar2 + 1);
+    const source = directionForward ? endpointA : endpointB;
+    const destination = directionForward ? endpointB : endpointA;
+    if (proto === 'tcp' || proto === 'udp') {
+        const s = splitEndpoint(source);
+        const d = splitEndpoint(destination);
+        const ipId = s.ip.includes(':') ? 'ipv6' : 'ipv4';
+        return [layer('eth', {}), layer(ipId, { sip: s.ip, dip: d.ip }), layer(proto, { srcport: s.port, dstport: d.port })];
+    }
+    if (proto === 'ip') {
+        const ipId = source.includes(':') ? 'ipv6' : 'ipv4';
+        return [layer('eth', {}), layer(ipId, { sip: source, dip: destination })];
+    }
+    if (proto === 'eth')
+        return [layer('eth', { smac: source, dmac: destination })];
+    return [layer('eth', {})];
+}
+function layer(id, data) {
+    return { id: id, name: id, nickname: id, protocol: true, errors: [], data: data };
+}
+function splitEndpoint(endpoint) {
+    const colon = endpoint.lastIndexOf(':');
+    return colon < 0 ? { ip: endpoint, port: '' } : { ip: endpoint.slice(0, colon), port: endpoint.slice(colon + 1) };
+}

package/dist/lib/streaming/worker/WebWorkerChannel.d.ts

@@ -0,0 +1,23 @@
+import { IWorkerChannel } from '../interfaces/IWorkerChannel';
+/** Structural minimum of a DOM Worker — avoids pulling the dom lib (which clashes with node types). */
+export interface WebWorkerLike {
+    postMessage(message: unknown, transfer?: unknown[]): void;
+    terminate(): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+/**
+ * Browser side of the worker channel over a Web Worker: correlated request/response, fire-and-forget
+ * notify, notify handlers for worker→main pushes, terminate rejecting anything in flight. Mirrors
+ * NodeWorkerChannel exactly; only the transport (postMessage/onmessage vs worker_threads) differs.
+ */
+export declare class WebWorkerChannel implements IWorkerChannel {
+    #private;
+    constructor(worker: WebWorkerLike);
+    request<T>(method: string, payload?: unknown, transfer?: ArrayBuffer[]): Promise<T>;
+    notify(method: string, payload?: unknown, transfer?: ArrayBuffer[]): void;
+    on(method: string, handler: (payload: unknown) => void): void;
+    terminate(): void;
+}

package/dist/lib/streaming/worker/WebWorkerChannel.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebWorkerChannel = void 0;
+/**
+ * Browser side of the worker channel over a Web Worker: correlated request/response, fire-and-forget
+ * notify, notify handlers for worker→main pushes, terminate rejecting anything in flight. Mirrors
+ * NodeWorkerChannel exactly; only the transport (postMessage/onmessage vs worker_threads) differs.
+ */
+class WebWorkerChannel {
+    #worker;
+    #nextId = 1;
+    #pending = new Map();
+    #handlers = new Map();
+    constructor(worker) {
+        this.#worker = worker;
+        this.#worker.onmessage = (event) => this.#onMessage(event.data);
+        this.#worker.onerror = () => this.#failAll(new Error('web worker error'));
+    }
+    request(method, payload, transfer) {
+        const id = this.#nextId++;
+        return new Promise((resolve, reject) => {
+            this.#pending.set(id, { resolve: resolve, reject: reject });
+            this.#worker.postMessage({ kind: 'request', id: id, method: method, payload: payload }, transfer ? transfer : []);
+        });
+    }
+    notify(method, payload, transfer) {
+        this.#worker.postMessage({ kind: 'notify', method: method, payload: payload }, transfer ? transfer : []);
+    }
+    on(method, handler) {
+        this.#handlers.set(method, handler);
+    }
+    terminate() {
+        this.#worker.terminate();
+        this.#failAll(new Error('worker channel terminated'));
+    }
+    #onMessage(message) {
+        if (message.kind === 'response') {
+            const pending = this.#pending.get(message.id);
+            if (!pending)
+                return;
+            this.#pending.delete(message.id);
+            if (message.ok)
+                pending.resolve(message.payload);
+            else
+                pending.reject(new Error(message.error !== undefined ? message.error : 'worker request failed'));
+        }
+        else if (message.kind === 'notify') {
+            const handler = this.#handlers.get(message.method);
+            if (handler)
+                handler(message.payload);
+        }
+    }
+    #failAll(error) {
+        for (const pending of this.#pending.values())
+            pending.reject(error);
+        this.#pending.clear();
+    }
+}
+exports.WebWorkerChannel = WebWorkerChannel;

package/dist/lib/streaming/worker/WebWorkerEndpoint.d.ts

@@ -0,0 +1,19 @@
+import { IWorkerEndpoint } from './IWorkerEndpoint';
+/** Structural minimum of a Web Worker global scope (self) — avoids pulling the webworker/dom lib. */
+export interface WorkerScopeLike {
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    postMessage(message: unknown, transfer?: unknown[]): void;
+}
+/**
+ * Browser worker side of the channel: registers request handlers (their awaited return becomes the
+ * response) and pushes notify messages back to the main thread over the worker global scope. Same
+ * request/response wiring as WorkerEndpoint (node), only the transport differs.
+ */
+export declare class WebWorkerEndpoint implements IWorkerEndpoint {
+    #private;
+    constructor(scope: WorkerScopeLike);
+    handle(method: string, handler: (payload: unknown) => unknown | Promise<unknown>): void;
+    notify(method: string, payload?: unknown, transfer?: ArrayBuffer[]): void;
+}

package/dist/lib/streaming/worker/WebWorkerEndpoint.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebWorkerEndpoint = void 0;
+/**
+ * Browser worker side of the channel: registers request handlers (their awaited return becomes the
+ * response) and pushes notify messages back to the main thread over the worker global scope. Same
+ * request/response wiring as WorkerEndpoint (node), only the transport differs.
+ */
+class WebWorkerEndpoint {
+    #scope;
+    #handlers = new Map();
+    constructor(scope) {
+        this.#scope = scope;
+        this.#scope.onmessage = (event) => { void this.#onMessage(event.data); };
+    }
+    handle(method, handler) {
+        this.#handlers.set(method, handler);
+    }
+    notify(method, payload, transfer) {
+        this.#scope.postMessage({ kind: 'notify', method: method, payload: payload }, transfer ? transfer : []);
+    }
+    async #onMessage(message) {
+        if (message.kind === 'request') {
+            const handler = this.#handlers.get(message.method);
+            if (!handler) {
+                this.#scope.postMessage({ kind: 'response', id: message.id, ok: false, error: `no handler for method: ${message.method}` });
+                return;
+            }
+            try {
+                const result = await handler(message.payload);
+                this.#scope.postMessage({ kind: 'response', id: message.id, ok: true, payload: result });
+            }
+            catch (error) {
+                this.#scope.postMessage({ kind: 'response', id: message.id, ok: false, error: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        else if (message.kind === 'notify') {
+            const handler = this.#handlers.get(message.method);
+            if (handler)
+                void handler(message.payload);
+        }
+    }
+}
+exports.WebWorkerEndpoint = WebWorkerEndpoint;

package/dist/lib/streaming/worker/WorkerEndpoint.d.ts

@@ -0,0 +1,13 @@
+import { MessagePort } from 'node:worker_threads';
+/**
+ * Worker side of the channel: registers request handlers (their return value, awaited, becomes the
+ * response) and can push notify messages back to the main thread. Shared by the real analysis worker
+ * and test workers, so the request/response wiring lives in one place. A thrown/rejected handler is
+ * reported as an error response rather than crashing the worker.
+ */
+export declare class WorkerEndpoint {
+    #private;
+    constructor(port: MessagePort);
+    handle(method: string, handler: (payload: unknown) => unknown | Promise<unknown>): void;
+    notify(method: string, payload?: unknown, transfer?: ArrayBuffer[]): void;
+}