@netkitty/analysis 1.0.0

package/dist/lib/streaming/backends/NodeFileReadBackend.d.ts

@@ -0,0 +1,15 @@
+import { IReadBackend } from '../interfaces/IReadBackend';
+/**
+ * node IReadBackend over a filesystem path: positional pread for random single-frame access, a
+ * chunked async iterator for sequential index building, and fs.watch for tailing a growing capture.
+ * A single FileHandle is opened lazily and reused for size/read/stream; close() releases it.
+ */
+export declare class NodeFileReadBackend implements IReadBackend {
+    #private;
+    constructor(path: string, chunkSize?: number);
+    size(): Promise<number>;
+    read(offset: number, length: number): Promise<Uint8Array>;
+    createStream(): AsyncIterableIterator<Uint8Array>;
+    watch(onChange: () => void): () => void;
+    close(): Promise<void>;
+}

package/dist/lib/streaming/backends/NodeFileReadBackend.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeFileReadBackend = void 0;
+const promises_1 = require("node:fs/promises");
+const node_fs_1 = require("node:fs");
+/**
+ * node IReadBackend over a filesystem path: positional pread for random single-frame access, a
+ * chunked async iterator for sequential index building, and fs.watch for tailing a growing capture.
+ * A single FileHandle is opened lazily and reused for size/read/stream; close() releases it.
+ */
+class NodeFileReadBackend {
+    #path;
+    #chunkSize;
+    #handle = null;
+    constructor(path, chunkSize = 1 << 16) {
+        this.#path = path;
+        this.#chunkSize = chunkSize;
+    }
+    async #fileHandle() {
+        if (!this.#handle)
+            this.#handle = await (0, promises_1.open)(this.#path, 'r');
+        return this.#handle;
+    }
+    async size() {
+        return (await (0, promises_1.stat)(this.#path)).size;
+    }
+    async read(offset, length) {
+        const handle = await this.#fileHandle();
+        const buffer = Buffer.allocUnsafe(length);
+        const result = await handle.read(buffer, 0, length, offset);
+        return result.bytesRead === length ? buffer : buffer.subarray(0, result.bytesRead);
+    }
+    async *createStream() {
+        const handle = await this.#fileHandle();
+        let position = 0;
+        while (true) {
+            const buffer = Buffer.allocUnsafe(this.#chunkSize);
+            const result = await handle.read(buffer, 0, this.#chunkSize, position);
+            if (result.bytesRead <= 0)
+                break;
+            position += result.bytesRead;
+            yield result.bytesRead === this.#chunkSize ? buffer : buffer.subarray(0, result.bytesRead);
+        }
+    }
+    watch(onChange) {
+        //stat-polling (watchFile) rather than fs.watch: reliable across platforms for tailing a
+        //steadily growing capture, at the cost of a small polling latency.
+        const listener = (curr, prev) => {
+            if (curr.size !== prev.size || curr.mtimeMs !== prev.mtimeMs)
+                onChange();
+        };
+        (0, node_fs_1.watchFile)(this.#path, { interval: 100 }, listener);
+        return () => (0, node_fs_1.unwatchFile)(this.#path, listener);
+    }
+    async close() {
+        if (this.#handle) {
+            await this.#handle.close();
+            this.#handle = null;
+        }
+    }
+}
+exports.NodeFileReadBackend = NodeFileReadBackend;

package/dist/lib/streaming/filter/FilterExpression.d.ts

@@ -0,0 +1,35 @@
+import { CodecDecodeResult } from '@netkitty/codec';
+/**
+ * A single display-filter term: a bare protocol name (frame contains that layer) or a
+ * `<selector> == <value>` field test. v1 covers the common selectors; the expression is the AND of
+ * its predicates. Richer syntax (||, !=, ranges) is a later extension.
+ */
+export type FilterPredicate = {
+    kind: 'protocol';
+    name: string;
+} | {
+    kind: 'field';
+    selector: string;
+    value: string;
+};
+/**
+ * A parsed display filter: the list of predicates a frame must all satisfy (logical AND). Produced by
+ * {@link parseFilter} and consumed by {@link matchesFilter} / {@link matchesIndexed}.
+ */
+export type FilterExpression = FilterPredicate[];
+/** Parse a display filter into an AND-list of predicates. Empty input matches everything. */
+export declare function parseFilter(input: string): FilterExpression;
+/** True when the decoded layers satisfy every predicate (AND). */
+export declare function matchesFilter(layers: CodecDecodeResult[], expression: FilterExpression): boolean;
+/**
+ * Try to decide a predicate from the index columns alone — the conversation key (protocol + the two
+ * canonical endpoints) and the top protocol — with NO re-decode. Returns true/false when decidable,
+ * or null when the frame must be decoded: direction-sensitive fields (src/dst/srcport/dstport, since
+ * the key is canonicalized and loses direction), or protocols the key/topProtocol don't pin down.
+ */
+export declare function indexableEval(predicate: FilterPredicate, conversationKey: string | null, topProtocol: string, directionForward: number): boolean | null;
+/**
+ * AND over indexableEval: false as soon as any column predicate excludes the frame (no decode); true
+ * if every predicate is column-decided true; null if a predicate needs the decoded layers to confirm.
+ */
+export declare function matchesIndexed(expression: FilterExpression, conversationKey: string | null, topProtocol: string, directionForward: number): boolean | null;

package/dist/lib/streaming/filter/FilterExpression.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFilter = parseFilter;
+exports.matchesFilter = matchesFilter;
+exports.indexableEval = indexableEval;
+exports.matchesIndexed = matchesIndexed;
+/** Parse a display filter into an AND-list of predicates. Empty input matches everything. */
+function parseFilter(input) {
+    return input
+        .split('&&')
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0)
+        .map(parsePredicate);
+}
+function parsePredicate(part) {
+    const equals = part.indexOf('==');
+    if (equals < 0)
+        return { kind: 'protocol', name: part.toLowerCase() };
+    const selector = part.slice(0, equals).trim().toLowerCase();
+    let value = part.slice(equals + 2).trim();
+    if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith('\'') && value.endsWith('\'')))) {
+        value = value.slice(1, -1);
+    }
+    return { kind: 'field', selector: selector, value: value };
+}
+/** True when the decoded layers satisfy every predicate (AND). */
+function matchesFilter(layers, expression) {
+    return expression.every((predicate) => matchesPredicate(layers, predicate));
+}
+function layerOf(layers, ...ids) {
+    return layers.find((l) => ids.includes(l.id));
+}
+function field(layer, name) {
+    if (!layer)
+        return null;
+    const value = layer.data[name];
+    return value === undefined || value === null ? null : String(value);
+}
+function matchesPredicate(layers, predicate) {
+    if (predicate.kind === 'protocol')
+        return layers.some((l) => l.id === predicate.name);
+    const value = predicate.value;
+    switch (predicate.selector) {
+        case 'ip.addr': return anyEquals(value, field(layerOf(layers, 'ipv4', 'ipv6'), 'sip'), field(layerOf(layers, 'ipv4', 'ipv6'), 'dip'));
+        case 'ip.src': return field(layerOf(layers, 'ipv4', 'ipv6'), 'sip') === value;
+        case 'ip.dst': return field(layerOf(layers, 'ipv4', 'ipv6'), 'dip') === value;
+        case 'tcp.port': return anyEquals(value, field(layerOf(layers, 'tcp'), 'srcport'), field(layerOf(layers, 'tcp'), 'dstport'));
+        case 'tcp.srcport': return field(layerOf(layers, 'tcp'), 'srcport') === value;
+        case 'tcp.dstport': return field(layerOf(layers, 'tcp'), 'dstport') === value;
+        case 'udp.port': return anyEquals(value, field(layerOf(layers, 'udp'), 'srcport'), field(layerOf(layers, 'udp'), 'dstport'));
+        case 'udp.srcport': return field(layerOf(layers, 'udp'), 'srcport') === value;
+        case 'udp.dstport': return field(layerOf(layers, 'udp'), 'dstport') === value;
+        case 'eth.addr': return anyEquals(value, field(layerOf(layers, 'eth'), 'smac'), field(layerOf(layers, 'eth'), 'dmac'));
+        case 'eth.src': return field(layerOf(layers, 'eth'), 'smac') === value;
+        case 'eth.dst': return field(layerOf(layers, 'eth'), 'dmac') === value;
+        default: return false;
+    }
+}
+function anyEquals(value, a, b) {
+    return a === value || b === value;
+}
+/**
+ * Try to decide a predicate from the index columns alone — the conversation key (protocol + the two
+ * canonical endpoints) and the top protocol — with NO re-decode. Returns true/false when decidable,
+ * or null when the frame must be decoded: direction-sensitive fields (src/dst/srcport/dstport, since
+ * the key is canonicalized and loses direction), or protocols the key/topProtocol don't pin down.
+ */
+function indexableEval(predicate, conversationKey, topProtocol, directionForward) {
+    if (predicate.kind === 'protocol') {
+        if (predicate.name === 'tcp' || predicate.name === 'udp') {
+            if (conversationKey === null)
+                return false;
+            return conversationKey.slice(0, conversationKey.indexOf('|')) === predicate.name;
+        }
+        if (predicate.name === 'arp')
+            return topProtocol === 'arp';
+        return null;
+    }
+    if (conversationKey === null)
+        return false;
+    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);
+    //directionForward=1 → source is endpointA; else source is endpointB.
+    const source = directionForward ? endpointA : endpointB;
+    const destination = directionForward ? endpointB : endpointA;
+    switch (predicate.selector) {
+        case 'ip.addr':
+            if (proto !== 'tcp' && proto !== 'udp' && proto !== 'ip')
+                return false;
+            return anyEquals(predicate.value, ipOf(endpointA, proto), ipOf(endpointB, proto));
+        case 'ip.src':
+            if (proto !== 'tcp' && proto !== 'udp' && proto !== 'ip')
+                return false;
+            return ipOf(source, proto) === predicate.value;
+        case 'ip.dst':
+            if (proto !== 'tcp' && proto !== 'udp' && proto !== 'ip')
+                return false;
+            return ipOf(destination, proto) === predicate.value;
+        case 'tcp.port':
+            if (proto !== 'tcp')
+                return false;
+            return anyEquals(predicate.value, portOf(endpointA), portOf(endpointB));
+        case 'tcp.srcport':
+            if (proto !== 'tcp')
+                return false;
+            return portOf(source) === predicate.value;
+        case 'tcp.dstport':
+            if (proto !== 'tcp')
+                return false;
+            return portOf(destination) === predicate.value;
+        case 'udp.port':
+            if (proto !== 'udp')
+                return false;
+            return anyEquals(predicate.value, portOf(endpointA), portOf(endpointB));
+        case 'udp.srcport':
+            if (proto !== 'udp')
+                return false;
+            return portOf(source) === predicate.value;
+        case 'udp.dstport':
+            if (proto !== 'udp')
+                return false;
+            return portOf(destination) === predicate.value;
+        case 'eth.addr':
+            if (proto !== 'eth')
+                return false;
+            return anyEquals(predicate.value, endpointA, endpointB);
+        case 'eth.src':
+            if (proto !== 'eth')
+                return false;
+            return source === predicate.value;
+        case 'eth.dst':
+            if (proto !== 'eth')
+                return false;
+            return destination === predicate.value;
+        default:
+            return null;
+    }
+}
+/**
+ * AND over indexableEval: false as soon as any column predicate excludes the frame (no decode); true
+ * if every predicate is column-decided true; null if a predicate needs the decoded layers to confirm.
+ */
+function matchesIndexed(expression, conversationKey, topProtocol, directionForward) {
+    let needsDecode = false;
+    for (const predicate of expression) {
+        const decided = indexableEval(predicate, conversationKey, topProtocol, directionForward);
+        if (decided === false)
+            return false;
+        if (decided === null)
+            needsDecode = true;
+    }
+    return needsDecode ? null : true;
+}
+function ipOf(endpoint, proto) {
+    if (proto === 'ip')
+        return endpoint;
+    const colon = endpoint.lastIndexOf(':');
+    return colon < 0 ? endpoint : endpoint.slice(0, colon);
+}
+function portOf(endpoint) {
+    const colon = endpoint.lastIndexOf(':');
+    return colon < 0 ? '' : endpoint.slice(colon + 1);
+}

package/dist/lib/streaming/indexer/ConversationKey.d.ts

@@ -0,0 +1,18 @@
+import { CodecDecodeResult } from '@netkitty/codec';
+/** The directional n-tuple of a frame, before canonicalization. */
+export type ConversationFlow = {
+    protocol: string;
+    source: string;
+    destination: string;
+};
+/**
+ * Derive the conversation n-tuple from a frame's decoded layers. Prefers IP + transport (tcp/udp),
+ * falls back to bare IP, then Ethernet MACs.
+ */
+export declare function flowOf(layers: CodecDecodeResult[]): ConversationFlow | null;
+/** Canonical, direction-independent key so A→B and B→A collapse to one conversation. */
+export declare function canonicalConversationKey(flow: ConversationFlow): string;
+/** The innermost real protocol id (last layer with protocol === true), skipping RawData tails. */
+export declare function topProtocolOf(layers: CodecDecodeResult[]): string;
+/** FNV-1a 32-bit hash — a compact numeric key for the conversation column. */
+export declare function hash32(input: string): number;

package/dist/lib/streaming/indexer/ConversationKey.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flowOf = flowOf;
+exports.canonicalConversationKey = canonicalConversationKey;
+exports.topProtocolOf = topProtocolOf;
+exports.hash32 = hash32;
+/**
+ * Derive the conversation n-tuple from a frame's decoded layers. Prefers IP + transport (tcp/udp),
+ * falls back to bare IP, then Ethernet MACs.
+ */
+function flowOf(layers) {
+    const ip = layers.find((l) => l.id === 'ipv4' || l.id === 'ipv6');
+    if (ip) {
+        const source = String(ip.data.sip);
+        const destination = String(ip.data.dip);
+        const transport = layers.find((l) => l.id === 'tcp' || l.id === 'udp');
+        if (transport) {
+            return {
+                protocol: transport.id,
+                source: `${source}:${transport.data.srcport}`,
+                destination: `${destination}:${transport.data.dstport}`
+            };
+        }
+        return { protocol: 'ip', source: source, destination: destination };
+    }
+    const eth = layers.find((l) => l.id === 'eth');
+    if (eth)
+        return { protocol: 'eth', source: String(eth.data.smac), destination: String(eth.data.dmac) };
+    return null;
+}
+/** Canonical, direction-independent key so A→B and B→A collapse to one conversation. */
+function canonicalConversationKey(flow) {
+    const forward = flow.source <= flow.destination;
+    const a = forward ? flow.source : flow.destination;
+    const b = forward ? flow.destination : flow.source;
+    return `${flow.protocol}|${a}|${b}`;
+}
+/** The innermost real protocol id (last layer with protocol === true), skipping RawData tails. */
+function topProtocolOf(layers) {
+    for (let i = layers.length - 1; i >= 0; i--) {
+        if (layers[i].protocol)
+            return layers[i].id;
+    }
+    return layers.length > 0 ? layers[layers.length - 1].id : 'unknown';
+}
+/** FNV-1a 32-bit hash — a compact numeric key for the conversation column. */
+function hash32(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = (hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24))) >>> 0;
+    }
+    return hash >>> 0;
+}

package/dist/lib/streaming/indexer/FrameIndexer.d.ts

@@ -0,0 +1,16 @@
+import { CodecDecodeResult } from '@netkitty/codec';
+import { IIndexStore } from '../interfaces/IIndexStore';
+/**
+ * Turns a frame's decoded layers + capture metadata into a columnar index record, maintaining the two
+ * small side dictionaries the numeric columns reference: protocol name↔id and conversation hash→key.
+ * Both are per-protocol / per-conversation sized (far smaller than the frame count), so they stay in
+ * memory while the bulk per-frame data lives in the TypedArray columns. conversationHash 0 is reserved
+ * for frames with no derivable n-tuple.
+ */
+export declare class FrameIndexer {
+    #private;
+    constructor(store: IIndexStore);
+    add(layers: CodecDecodeResult[], fileOffset: number, capturedLength: number, originalLength: number, timestamp: number): number;
+    protocolName(id: number): string;
+    conversationKey(hash: number): string | null;
+}

package/dist/lib/streaming/indexer/FrameIndexer.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrameIndexer = void 0;
+const ConversationKey_1 = require("./ConversationKey");
+/**
+ * Turns a frame's decoded layers + capture metadata into a columnar index record, maintaining the two
+ * small side dictionaries the numeric columns reference: protocol name↔id and conversation hash→key.
+ * Both are per-protocol / per-conversation sized (far smaller than the frame count), so they stay in
+ * memory while the bulk per-frame data lives in the TypedArray columns. conversationHash 0 is reserved
+ * for frames with no derivable n-tuple.
+ */
+class FrameIndexer {
+    #store;
+    #protocolIds = new Map();
+    #protocolNames = [];
+    #conversationKeys = new Map();
+    constructor(store) {
+        this.#store = store;
+    }
+    add(layers, fileOffset, capturedLength, originalLength, timestamp) {
+        const flow = (0, ConversationKey_1.flowOf)(layers);
+        const key = flow ? (0, ConversationKey_1.canonicalConversationKey)(flow) : null;
+        const conversationHash = key !== null ? (0, ConversationKey_1.hash32)(key) : 0;
+        if (key !== null && !this.#conversationKeys.has(conversationHash))
+            this.#conversationKeys.set(conversationHash, key);
+        //Forward = the original source is the canonical endpointA (source <= destination), matching
+        //canonicalConversationKey. Lets src/dst filters recover direction from the key without decoding.
+        const directionForward = flow ? (flow.source <= flow.destination ? 1 : 0) : 1;
+        const record = {
+            index: -1,
+            fileOffset: fileOffset,
+            capturedLength: capturedLength,
+            originalLength: originalLength,
+            timestamp: timestamp,
+            protocolId: this.#protocolId((0, ConversationKey_1.topProtocolOf)(layers)),
+            conversationHash: conversationHash,
+            directionForward: directionForward
+        };
+        return this.#store.append(record);
+    }
+    protocolName(id) {
+        return id >= 0 && id < this.#protocolNames.length ? this.#protocolNames[id] : 'unknown';
+    }
+    conversationKey(hash) {
+        const key = this.#conversationKeys.get(hash);
+        return key !== undefined ? key : null;
+    }
+    #protocolId(name) {
+        const existing = this.#protocolIds.get(name);
+        if (existing !== undefined)
+            return existing;
+        const id = this.#protocolNames.length;
+        this.#protocolIds.set(name, id);
+        this.#protocolNames.push(name);
+        return id;
+    }
+}
+exports.FrameIndexer = FrameIndexer;

package/dist/lib/streaming/indexer/PcapIndexBuilder.d.ts

@@ -0,0 +1,20 @@
+import { Codec } from '@netkitty/codec';
+import { IPcapPacketInfo } from '@netkitty/pcap-core';
+import { IReadBackend } from '../interfaces/IReadBackend';
+import { FrameIndexer } from './FrameIndexer';
+/** Callbacks fired while building the index, for progress reporting and per-frame notification. */
+export type IndexBuildHooks = {
+    onFrame?: (index: number, info: IPcapPacketInfo) => void;
+    onProgress?: (bytesRead: number, totalBytes: number) => void;
+};
+/**
+ * Drives the index build: pulls bytes from an IReadBackend stream, feeds PcapParserCore, and for each
+ * emitted frame runs codec.decode to extract the n-tuple and append a columnar record via FrameIndexer.
+ * Frames produced by one chunk are drained (decoded + indexed) before the next chunk is read, so memory
+ * stays bounded to one chunk's worth of frames and the async decode naturally back-pressures the reader.
+ */
+export declare class PcapIndexBuilder {
+    #private;
+    constructor(indexer: FrameIndexer, codec: Codec);
+    build(backend: IReadBackend, hooks?: IndexBuildHooks): Promise<number>;
+}

package/dist/lib/streaming/indexer/PcapIndexBuilder.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PcapIndexBuilder = void 0;
+const pcap_core_1 = require("@netkitty/pcap-core");
+/**
+ * Drives the index build: pulls bytes from an IReadBackend stream, feeds PcapParserCore, and for each
+ * emitted frame runs codec.decode to extract the n-tuple and append a columnar record via FrameIndexer.
+ * Frames produced by one chunk are drained (decoded + indexed) before the next chunk is read, so memory
+ * stays bounded to one chunk's worth of frames and the async decode naturally back-pressures the reader.
+ */
+class PcapIndexBuilder {
+    #indexer;
+    #codec;
+    constructor(indexer, codec) {
+        this.#indexer = indexer;
+        this.#codec = codec;
+    }
+    async build(backend, hooks = {}) {
+        const total = await backend.size();
+        let bytesRead = 0;
+        let count = 0;
+        const pending = [];
+        let lastData = Buffer.alloc(0);
+        const parser = new pcap_core_1.PcapParserCore({
+            onPacketData: (data) => { lastData = data; },
+            onPacket: (info) => { pending.push({ info: info, data: lastData }); }
+        });
+        const drain = async () => {
+            for (const frame of pending) {
+                const layers = await this.#codec.decode(frame.data);
+                const timestamp = frame.info.seconds + frame.info.microseconds / 1_000_000;
+                const index = this.#indexer.add(layers, frame.info.packetOffset, frame.info.packetLength, frame.info.packetLength, timestamp);
+                if (hooks.onFrame)
+                    hooks.onFrame(index, frame.info);
+                count++;
+            }
+            pending.length = 0;
+        };
+        for await (const chunk of backend.createStream()) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            parser.write(buffer);
+            await drain();
+            bytesRead += buffer.length;
+            if (hooks.onProgress)
+                hooks.onProgress(bytesRead, total);
+        }
+        parser.end();
+        await drain();
+        return count;
+    }
+}
+exports.PcapIndexBuilder = PcapIndexBuilder;

package/dist/lib/streaming/interfaces/IAnalysisReducer.d.ts

@@ -0,0 +1,14 @@
+import { Frame } from '../types/Frame';
+import { UpdateContext } from '../types/UpdateContext';
+/**
+ * A pluggable rolling analysis over the frame stream. Fed every frame (replay backlog first, then
+ * live) via update(); result() returns the current snapshot at any time — there is no finalize. A
+ * reducer may additionally extend an event emitter to push progress/update notifications of its own.
+ */
+export interface IAnalysisReducer<TResult> {
+    readonly needs?: string[];
+    readonly indexOnly?: boolean;
+    update(frame: Frame, context: UpdateContext): void;
+    result(): TResult;
+    reset(): void;
+}

package/dist/lib/streaming/interfaces/IAnalysisReducer.js

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

package/dist/lib/streaming/interfaces/IIndexStore.d.ts

@@ -0,0 +1,16 @@
+import { FrameIndexRecord } from '../types/FrameIndexRecord';
+/**
+ * Append-only frame index with random access, range slicing, predicate scan, and FIFO eviction. The
+ * v1 implementation is columnar TypedArray (heap-external, shared by node and browser); a SQLite
+ * backend is a v2 seam for when the index outgrows memory or needs persistence.
+ */
+export interface IIndexStore {
+    append(record: FrameIndexRecord): number;
+    get(index: number): FrameIndexRecord | null;
+    range(from: number, to: number): FrameIndexRecord[];
+    scan(predicate: (record: FrameIndexRecord) => boolean): number[];
+    count(): number;
+    firstIndex(): number;
+    evictOldest(count: number): void;
+    clear(): void;
+}

package/dist/lib/streaming/interfaces/IIndexStore.js

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

package/dist/lib/streaming/interfaces/IReadBackend.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Byte-I/O seam over a capture source. The only place node (FileHandle pread / fs.watch) and browser
+ * (File.slice / OPFS) diverge; everything above consumes bytes environment-agnostically.
+ */
+export interface IReadBackend {
+    size(): Promise<number>;
+    read(offset: number, length: number): Promise<Uint8Array>;
+    createStream(): AsyncIterable<Uint8Array>;
+    watch?(onChange: () => void): () => void;
+    close?(): void | Promise<void>;
+}

package/dist/lib/streaming/interfaces/IReadBackend.js

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

package/dist/lib/streaming/interfaces/IWorkerChannel.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Thin transport seam to the analysis worker: correlated request/response plus fire-and-forget
+ * notify, over worker_threads (node) or Web Worker (browser) postMessage. ArrayBuffers in the
+ * transfer list move without copying. Only the invoke/notify semantics are borrowed from capture's
+ * pipe layer — the transport itself is plain postMessage, not socket-ipc.
+ */
+export interface IWorkerChannel {
+    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/interfaces/IWorkerChannel.js

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

package/dist/lib/streaming/reducers/ConversationsReducer.d.ts

@@ -0,0 +1,34 @@
+import { Frame } from '../types/Frame';
+import { UpdateContext } from '../types/UpdateContext';
+import { IAnalysisReducer } from '../interfaces/IAnalysisReducer';
+/**
+ * A bidirectional conversation summary. Instead of holding the full member-frame list, it keeps only
+ * firstIndex/lastIndex — the member frames are recovered from the index layer (filter/range) on
+ * demand, so per-conversation state stays bounded no matter how many frames it spans.
+ */
+export type ConversationSummary = {
+    protocol: string;
+    endpointA: string;
+    endpointB: string;
+    packets: number;
+    bytes: number;
+    packetsAToB: number;
+    packetsBToA: number;
+    firstTimestamp: number;
+    lastTimestamp: number;
+    firstIndex: number;
+    lastIndex: number;
+};
+/**
+ * Rolling conversation table: groups frames direction-independently by n-tuple, tallying packets,
+ * bytes, per-direction counts and time/index spans. result() is a snapshot at any point; reset()
+ * clears it.
+ */
+export declare class ConversationsReducer implements IAnalysisReducer<ConversationSummary[]> {
+    #private;
+    readonly needs: string[];
+    readonly indexOnly: boolean;
+    update(frame: Frame, context: UpdateContext): void;
+    result(): ConversationSummary[];
+    reset(): void;
+}