@lokvis/runtime 0.1.0

package/dist/worker-host.d.ts

@@ -0,0 +1,154 @@
+/**
+ * WorkerHost —— 主线程侧的 Worker 管理器
+ *
+ * 职责(对应 PROJECT_PLAN 1.6):
+ * - 生成 / 重启 Worker,完成 ready 握手。
+ * - Request/Response 按 id 关联,每请求独立超时。
+ * - 心跳(Heartbeat):周期 ping,超时未 pong 视为崩溃。
+ * - 崩溃重启:传输层 error / 心跳超时 → 终止并重建(最多 maxRestarts 次)。
+ * - 事件分发:Worker 主动 event + 生命周期事件(ready/restart/crash/dead)。
+ *
+ * 传输层抽象(WorkerTransport)使其与具体 Worker 实现解耦:
+ * - 浏览器:createBrowserWorkerTransport(url)
+ * - 测试:注入 Fake 传输,无需真实 Worker。
+ */
+/** 规范化的传输层错误 */
+export interface WorkerTransportError {
+    message: string;
+    filename?: string;
+    lineno?: number;
+    stack?: string;
+}
+/**
+ * 传输层接口:屏蔽 浏览器 Worker / Node worker_threads / Fake 差异。
+ * Host 仅依赖该接口,便于单测注入 Fake。
+ */
+export interface WorkerTransport {
+    /** 向 Worker 发消息(可附带可转移对象) */
+    send(message: unknown, transfer?: Transferable[]): void;
+    /** 监听 Worker → Host 消息,返回取消订阅 */
+    onMessage(handler: (data: unknown) => void): () => void;
+    /** 监听传输层错误(脚本加载失败 / 未捕获异常 / 异常退出),返回取消订阅 */
+    onError(handler: (err: WorkerTransportError) => void): () => void;
+    /** 终止 Worker */
+    terminate(): void;
+}
+/** Worker 崩溃(传输层错误或心跳超时) */
+export declare class WorkerCrashedError extends Error {
+    readonly reason: string;
+    readonly restartCount: number;
+    constructor(reason: string, restartCount: number);
+}
+/** Worker 正在重启,拒绝新请求 */
+export declare class WorkerRestartingError extends Error {
+    constructor();
+}
+/** Worker 已死亡(超过最大重启次数) */
+export declare class WorkerDeadError extends Error {
+    readonly restartCount: number;
+    constructor(restartCount: number);
+}
+/** 单个请求超时 */
+export declare class WorkerRequestTimeoutError extends Error {
+    readonly method: string;
+    constructor(method: string, timeoutMs: number);
+}
+/** ready 握手失败(协议版本不匹配或超时) */
+export declare class WorkerHandshakeError extends Error {
+    constructor(message: string);
+}
+export interface WorkerHostOptions {
+    /** 心跳发送间隔 */
+    heartbeatIntervalMs?: number;
+    /** 心跳超时(未收到 pong 视为崩溃) */
+    heartbeatTimeoutMs?: number;
+    /** 单个请求默认超时 */
+    requestTimeoutMs?: number;
+    /** 等待 Worker ready 的超时 */
+    readyTimeoutMs?: number;
+    /** 崩溃后最大重启次数 */
+    maxRestarts?: number;
+    /** 传输层工厂(重启时复用) */
+    createTransport: () => WorkerTransport;
+    /** 是否输出日志 */
+    enableLog?: boolean;
+}
+export type WorkerHostStatus = 'idle' | 'ready' | 'restarting' | 'dead' | 'disposed';
+/** 生命周期 + Worker 主动事件 */
+export interface WorkerHostEventMap {
+    ready: {
+        restartCount: number;
+    };
+    restart: {
+        reason: string;
+        restartCount: number;
+    };
+    crash: {
+        reason: string;
+        restartCount: number;
+    };
+    dead: {
+        reason: string;
+        restartCount: number;
+    };
+    event: {
+        event: string;
+        payload?: unknown;
+    };
+}
+export type WorkerHostEventType = keyof WorkerHostEventMap;
+type Listener<T> = (payload: T) => void;
+export declare class WorkerHost {
+    private opts;
+    private status;
+    private transport;
+    private pending;
+    private listeners;
+    private restartCount;
+    private heartbeatTimer;
+    private pongTimer;
+    private awaitingPong;
+    private offMessage;
+    private offError;
+    constructor(opts: WorkerHostOptions);
+    get currentStatus(): WorkerHostStatus;
+    /** 已发生的重启次数 */
+    get currentRestartCount(): number;
+    /** 订阅事件,返回取消订阅 */
+    on<K extends WorkerHostEventType>(type: K, handler: Listener<WorkerHostEventMap[K]>): () => void;
+    private emit;
+    private log;
+    /** 启动并完成 ready 握手 */
+    init(): Promise<void>;
+    /** 销毁:终止 Worker、清理定时器、拒绝所有 pending */
+    dispose(): Promise<void>;
+    /** 调用 Worker 方法并等待响应 */
+    request<T = unknown>(method: string, params?: unknown, options?: {
+        transfer?: Transferable[];
+        timeoutMs?: number;
+    }): Promise<T>;
+    /** 创建传输层、绑定监听、等待 ready */
+    private spawn;
+    private handleMessage;
+    /** 崩溃处理:拒绝 pending → 终止 → 重启(受 maxRestarts 限制) */
+    private handleCrash;
+    /**
+     * 重启尝试循环。spawn 失败(ready 超时)时,直接 teardown 并重试,
+     * 不经过 handleCrash 的 restarting 守卫——否则永远到不了 dead。
+     */
+    private tryRestart;
+    /** 解绑当前 transport 的监听并终止 */
+    private teardownTransport;
+    private startHeartbeat;
+    private sendPing;
+    private clearHeartbeat;
+    private send;
+    private rejectAllPending;
+}
+/**
+ * 创建浏览器 Web Worker 传输层。
+ * 仅在浏览器主线程可用(Node 测试应注入 Fake 传输)。
+ */
+export declare function createBrowserWorkerTransport(url: string | URL): WorkerTransport;
+export {};
+//# sourceMappingURL=worker-host.d.ts.map

package/dist/worker-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-host.d.ts","sourceRoot":"","sources":["../src/worker-host.ts"],"names":[],"mappings":"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"}

package/dist/worker-host.js

@@ -0,0 +1,394 @@
+/**
+ * WorkerHost —— 主线程侧的 Worker 管理器
+ *
+ * 职责(对应 PROJECT_PLAN 1.6):
+ * - 生成 / 重启 Worker,完成 ready 握手。
+ * - Request/Response 按 id 关联,每请求独立超时。
+ * - 心跳(Heartbeat):周期 ping,超时未 pong 视为崩溃。
+ * - 崩溃重启:传输层 error / 心跳超时 → 终止并重建(最多 maxRestarts 次)。
+ * - 事件分发:Worker 主动 event + 生命周期事件(ready/restart/crash/dead)。
+ *
+ * 传输层抽象(WorkerTransport)使其与具体 Worker 实现解耦:
+ * - 浏览器:createBrowserWorkerTransport(url)
+ * - 测试:注入 Fake 传输,无需真实 Worker。
+ */
+import { WORKER_PROTOCOL_VERSION, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_HEARTBEAT_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_MAX_RESTARTS, DEFAULT_READY_TIMEOUT_MS, createRequestId, isWorkerResponse, isWorkerPong, isWorkerReady, isWorkerEvent, isWorkerFatalError, } from './worker-protocol.js';
+// ─── 错误类型 ───────────────────────────────────────────────────
+/** Worker 崩溃(传输层错误或心跳超时) */
+export class WorkerCrashedError extends Error {
+    reason;
+    restartCount;
+    constructor(reason, restartCount) {
+        super(`Worker crashed: ${reason}`);
+        this.name = 'WorkerCrashedError';
+        this.reason = reason;
+        this.restartCount = restartCount;
+    }
+}
+/** Worker 正在重启,拒绝新请求 */
+export class WorkerRestartingError extends Error {
+    constructor() {
+        super('Worker is restarting');
+        this.name = 'WorkerRestartingError';
+    }
+}
+/** Worker 已死亡(超过最大重启次数) */
+export class WorkerDeadError extends Error {
+    restartCount;
+    constructor(restartCount) {
+        super(`Worker is dead after ${restartCount} restart attempts`);
+        this.name = 'WorkerDeadError';
+        this.restartCount = restartCount;
+    }
+}
+/** 单个请求超时 */
+export class WorkerRequestTimeoutError extends Error {
+    method;
+    constructor(method, timeoutMs) {
+        super(`Request "${method}" timed out after ${timeoutMs}ms`);
+        this.name = 'WorkerRequestTimeoutError';
+        this.method = method;
+    }
+}
+/** ready 握手失败(协议版本不匹配或超时) */
+export class WorkerHandshakeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WorkerHandshakeError';
+    }
+}
+// ─── WorkerHost ─────────────────────────────────────────────────
+export class WorkerHost {
+    opts;
+    status = 'idle';
+    transport = null;
+    pending = new Map();
+    listeners = new Map();
+    restartCount = 0;
+    heartbeatTimer = null;
+    pongTimer = null;
+    awaitingPong = false;
+    offMessage = null;
+    offError = null;
+    constructor(opts) {
+        this.opts = {
+            heartbeatIntervalMs: opts.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS,
+            heartbeatTimeoutMs: opts.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS,
+            requestTimeoutMs: opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+            readyTimeoutMs: opts.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+            maxRestarts: opts.maxRestarts ?? DEFAULT_MAX_RESTARTS,
+            createTransport: opts.createTransport,
+            enableLog: opts.enableLog ?? false,
+        };
+    }
+    get currentStatus() {
+        return this.status;
+    }
+    /** 已发生的重启次数 */
+    get currentRestartCount() {
+        return this.restartCount;
+    }
+    /** 订阅事件,返回取消订阅 */
+    on(type, handler) {
+        let set = this.listeners.get(type);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(type, set);
+        }
+        set.add(handler);
+        return () => set.delete(handler);
+    }
+    emit(type, payload) {
+        const set = this.listeners.get(type);
+        if (!set)
+            return;
+        for (const h of set)
+            h(payload);
+    }
+    log(message) {
+        if (this.opts.enableLog)
+            console.debug(`[WorkerHost] ${message}`);
+    }
+    // ─── 生命周期 ───────────────────────────────────────────────
+    /** 启动并完成 ready 握手 */
+    async init() {
+        if (this.status === 'disposed')
+            throw new Error('WorkerHost is disposed');
+        if (this.status !== 'idle')
+            return; // 已启动
+        await this.spawn();
+    }
+    /** 销毁:终止 Worker、清理定时器、拒绝所有 pending */
+    async dispose() {
+        if (this.status === 'disposed')
+            return;
+        this.status = 'disposed';
+        this.clearHeartbeat();
+        this.rejectAllPending(new Error('WorkerHost disposed'));
+        this.offMessage?.();
+        this.offError?.();
+        this.offMessage = null;
+        this.offError = null;
+        this.transport?.terminate();
+        this.transport = null;
+        this.listeners.clear();
+    }
+    // ─── 请求 ───────────────────────────────────────────────────
+    /** 调用 Worker 方法并等待响应 */
+    async request(method, params, options) {
+        if (this.status === 'disposed')
+            throw new Error('WorkerHost is disposed');
+        if (this.status === 'dead')
+            throw new WorkerDeadError(this.restartCount);
+        if (this.status === 'restarting' || this.status === 'idle') {
+            throw new WorkerRestartingError();
+        }
+        const id = createRequestId();
+        const timeoutMs = options?.timeoutMs ?? this.opts.requestTimeoutMs;
+        const msg = { id, type: 'request', method, params };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (this.pending.delete(id)) {
+                    reject(new WorkerRequestTimeoutError(method, timeoutMs));
+                }
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (v) => resolve(v),
+                reject,
+                timer,
+                method,
+            });
+            this.send(msg, options?.transfer);
+        });
+    }
+    // ─── 内部:spawn / 消息处理 / 崩溃 ──────────────────────────
+    /** 创建传输层、绑定监听、等待 ready */
+    async spawn() {
+        const transport = this.opts.createTransport();
+        this.transport = transport;
+        this.offMessage = transport.onMessage((data) => this.handleMessage(data));
+        this.offError = transport.onError((err) => this.handleCrash(`transport error: ${err.message}`));
+        // 等待 ready 握手(超时或协议不匹配则拒绝,由 catch 清理 transport)
+        let readyTimer;
+        try {
+            await new Promise((resolve, reject) => {
+                let done = false;
+                readyTimer = setTimeout(() => {
+                    if (done)
+                        return;
+                    done = true;
+                    reject(new WorkerHandshakeError(`Worker did not send ready within ${this.opts.readyTimeoutMs}ms`));
+                }, this.opts.readyTimeoutMs);
+                readyTimer.unref?.();
+                const off = this.on('ready', () => {
+                    if (done)
+                        return;
+                    done = true;
+                    clearTimeout(readyTimer);
+                    off();
+                    resolve();
+                });
+            });
+        }
+        catch (err) {
+            clearTimeout(readyTimer);
+            this.offMessage?.();
+            this.offError?.();
+            this.offMessage = null;
+            this.offError = null;
+            transport.terminate();
+            this.transport = null;
+            throw err;
+        }
+        this.status = 'ready';
+        this.startHeartbeat();
+    }
+    handleMessage(data) {
+        // ready(可能在握手期间或重启后)
+        if (isWorkerReady(data)) {
+            if (!data.protocolVersion || data.protocolVersion !== WORKER_PROTOCOL_VERSION) {
+                this.handleCrash(`protocol mismatch: worker=${data.protocolVersion} host=${WORKER_PROTOCOL_VERSION}`);
+                return;
+            }
+            // ready 事件由 spawn() 的监听器消费;重启后再次 ready 也触发
+            this.emit('ready', { restartCount: this.restartCount });
+            return;
+        }
+        if (isWorkerPong(data)) {
+            this.awaitingPong = false;
+            if (this.pongTimer) {
+                clearTimeout(this.pongTimer);
+                this.pongTimer = null;
+            }
+            return;
+        }
+        if (isWorkerResponse(data)) {
+            const pending = this.pending.get(data.id);
+            if (!pending)
+                return; // 已超时或已取消
+            this.pending.delete(data.id);
+            clearTimeout(pending.timer);
+            if (data.ok)
+                pending.resolve(data.result);
+            else {
+                const e = data.error;
+                const err = new Error(e.message);
+                err.name = e.code ?? 'WorkerError';
+                if (e.stack)
+                    err.stack = e.stack;
+                pending.reject(err);
+            }
+            return;
+        }
+        if (isWorkerEvent(data)) {
+            this.emit('event', { event: data.event, payload: data.payload });
+            return;
+        }
+        if (isWorkerFatalError(data)) {
+            // Worker 主动上报致命错误 → 视为崩溃
+            this.handleCrash(`worker fatal: ${data.message}`);
+            return;
+        }
+    }
+    /** 崩溃处理:拒绝 pending → 终止 → 重启(受 maxRestarts 限制) */
+    handleCrash(reason) {
+        // 正在重启/已死亡/已销毁时,忽略额外的崩溃信号(避免重入)
+        if (this.status === 'disposed' ||
+            this.status === 'dead' ||
+            this.status === 'restarting') {
+            return;
+        }
+        this.log(`crash: ${reason}`);
+        this.status = 'restarting';
+        this.teardownTransport();
+        this.rejectAllPending(new WorkerCrashedError(reason, this.restartCount));
+        this.emit('crash', { reason, restartCount: this.restartCount });
+        this.tryRestart(reason);
+    }
+    /**
+     * 重启尝试循环。spawn 失败(ready 超时)时,直接 teardown 并重试,
+     * 不经过 handleCrash 的 restarting 守卫——否则永远到不了 dead。
+     */
+    tryRestart(reason) {
+        if (this.status === 'disposed')
+            return;
+        if (this.restartCount >= this.opts.maxRestarts) {
+            this.status = 'dead';
+            this.emit('dead', { reason, restartCount: this.restartCount });
+            return;
+        }
+        this.restartCount++;
+        this.log(`restarting (attempt ${this.restartCount}/${this.opts.maxRestarts})`);
+        this.spawn()
+            .then(() => {
+            this.emit('restart', { reason, restartCount: this.restartCount });
+        })
+            .catch((err) => {
+            // 重启失败:终止本次(未握手成功的)transport,继续下一轮重试
+            this.teardownTransport();
+            this.tryRestart(`restart failed: ${err.message}`);
+        });
+    }
+    /** 解绑当前 transport 的监听并终止 */
+    teardownTransport() {
+        this.clearHeartbeat();
+        this.offMessage?.();
+        this.offError?.();
+        this.offMessage = null;
+        this.offError = null;
+        this.transport?.terminate();
+        this.transport = null;
+    }
+    // ─── 心跳 ───────────────────────────────────────────────────
+    startHeartbeat() {
+        this.clearHeartbeat();
+        this.awaitingPong = false;
+        this.heartbeatTimer = setInterval(() => {
+            this.sendPing();
+        }, this.opts.heartbeatIntervalMs);
+        this.heartbeatTimer.unref?.();
+    }
+    sendPing() {
+        if (this.awaitingPong)
+            return; // 上一轮 pong 未回,等超时触发崩溃
+        this.awaitingPong = true;
+        const msg = {
+            id: createRequestId(),
+            type: 'ping',
+            ts: Date.now(),
+        };
+        this.send(msg);
+        this.pongTimer = setTimeout(() => {
+            this.handleCrash(`heartbeat timeout (no pong in ${this.opts.heartbeatTimeoutMs}ms)`);
+        }, this.opts.heartbeatTimeoutMs);
+        this.pongTimer.unref?.();
+    }
+    clearHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.pongTimer) {
+            clearTimeout(this.pongTimer);
+            this.pongTimer = null;
+        }
+        this.awaitingPong = false;
+    }
+    // ─── 工具 ───────────────────────────────────────────────────
+    send(message, transfer) {
+        if (!this.transport)
+            return;
+        this.transport.send(message, transfer);
+    }
+    rejectAllPending(error) {
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(error);
+        }
+        this.pending.clear();
+    }
+}
+// ─── 浏览器默认传输层 ───────────────────────────────────────────
+/**
+ * 创建浏览器 Web Worker 传输层。
+ * 仅在浏览器主线程可用(Node 测试应注入 Fake 传输)。
+ */
+export function createBrowserWorkerTransport(url) {
+    const worker = new Worker(url, { type: 'module' });
+    const messageHandlers = new Set();
+    const errorHandlers = new Set();
+    worker.addEventListener('message', (ev) => {
+        for (const h of messageHandlers)
+            h(ev.data);
+    });
+    worker.addEventListener('error', (ev) => {
+        const err = {
+            message: ev.message || 'Worker error',
+            filename: ev.filename,
+            lineno: ev.lineno,
+            stack: ev.error instanceof Error ? ev.error.stack : undefined,
+        };
+        for (const h of errorHandlers)
+            h(err);
+    });
+    return {
+        send(message, transfer) {
+            if (transfer && transfer.length > 0)
+                worker.postMessage(message, transfer);
+            else
+                worker.postMessage(message);
+        },
+        onMessage(handler) {
+            messageHandlers.add(handler);
+            return () => messageHandlers.delete(handler);
+        },
+        onError(handler) {
+            errorHandlers.add(handler);
+            return () => errorHandlers.delete(handler);
+        },
+        terminate() {
+            worker.terminate();
+        },
+    };
+}
+//# sourceMappingURL=worker-host.js.map

package/dist/worker-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-host.js","sourceRoot":"","sources":["../src/worker-host.ts"],"names":[],"mappings":"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"}

package/dist/worker-protocol.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Worker 通信协议
+ *
+ * 定义 主线程(Host) ↔ Worker 之间的消息格式与握手/心跳规范。
+ * 协议本身与传输层解耦(纯类型 + 常量 + 校验助手),
+ * 既可用于浏览器 Web Worker,也可在测试中被 Fake 传输层复用。
+ *
+ * 设计目标(对应 whitepaper T1「浏览器内存/性能 ★★★★★」与 PROJECT_PLAN 1.6/1.7):
+ * - 每个请求有唯一 id,Response 按 id 关联,避免错配。
+ * - 心跳(Heartbeat):Host 周期性 ping,Worker 必须在超时内 pong,否则视为崩溃。
+ * - Ready 握手:Worker 启动后主动发 ready,Host 据此判定可用。
+ * - 错误通道:Worker 主动 error(可恢复) vs 传输层 error/exit(不可恢复,触发重启)。
+ *
+ * 消息流向:
+ *   Host → Worker:  request | ping
+ *   Worker → Host:  response | pong | event | ready | error
+ */
+/** 协议版本(Host 与 Worker 握手时校验,不一致则拒绝) */
+export declare const WORKER_PROTOCOL_VERSION = "0.1.0";
+/** 心跳发送间隔 */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
+/** 心跳超时:超过该时间未收到 pong 视为 Worker 无响应 */
+export declare const DEFAULT_HEARTBEAT_TIMEOUT_MS = 15000;
+/** 单个请求的默认超时 */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
+/** 崩溃后最大重启次数(超过则放弃,交由上层降级) */
+export declare const DEFAULT_MAX_RESTARTS = 3;
+/** Worker 启动后等待 ready 的超时 */
+export declare const DEFAULT_READY_TIMEOUT_MS = 10000;
+/** 请求:Host 调用 Worker 暴露的方法 */
+export interface WorkerRequest {
+    id: string;
+    type: 'request';
+    method: string;
+    params: unknown;
+}
+/** 心跳探测 */
+export interface WorkerPing {
+    id: string;
+    type: 'ping';
+    ts: number;
+}
+export type WorkerMessageToWorker = WorkerRequest | WorkerPing;
+/** 响应:成功 */
+export interface WorkerResponseOk {
+    id: string;
+    type: 'response';
+    ok: true;
+    result: unknown;
+}
+/** 响应:失败 */
+export interface WorkerResponseErr {
+    id: string;
+    type: 'response';
+    ok: false;
+    error: {
+        message: string;
+        code?: string;
+        stack?: string;
+    };
+}
+export type WorkerResponse = WorkerResponseOk | WorkerResponseErr;
+/** 心跳回应 */
+export interface WorkerPong {
+    id: string;
+    type: 'pong';
+    ts: number;
+}
+/** Worker 主动事件(进度、日志等,无需 ack) */
+export interface WorkerEvent {
+    type: 'event';
+    event: string;
+    payload?: unknown;
+}
+/** Worker 就绪(启动后主动发送,携带协议版本) */
+export interface WorkerReady {
+    type: 'ready';
+    protocolVersion: string;
+}
+/** Worker 主动上报的致命错误(自身仍存活但无法继续) */
+export interface WorkerFatalError {
+    type: 'error';
+    message: string;
+    stack?: string;
+}
+export type WorkerMessageToHost = WorkerResponse | WorkerPong | WorkerEvent | WorkerReady | WorkerFatalError;
+/** 生成唯一请求/心跳 id */
+export declare function createRequestId(): string;
+/** 类型守卫:是否为 Worker → Host 消息 */
+export declare function isWorkerMessageToHost(data: unknown): data is WorkerMessageToHost;
+/** 类型守卫:是否为响应消息 */
+export declare function isWorkerResponse(data: unknown): data is WorkerResponse;
+/** 类型守卫:是否为 pong */
+export declare function isWorkerPong(data: unknown): data is WorkerPong;
+/** 类型守卫:是否为 ready */
+export declare function isWorkerReady(data: unknown): data is WorkerReady;
+/** 类型守卫:是否为 Worker 主动事件 */
+export declare function isWorkerEvent(data: unknown): data is WorkerEvent;
+/** 类型守卫:是否为 Worker 主动上报错误 */
+export declare function isWorkerFatalError(data: unknown): data is WorkerFatalError;
+/** 协议版本是否兼容(目前采用严格相等) */
+export declare function isProtocolCompatible(version: string): boolean;
+//# sourceMappingURL=worker-protocol.d.ts.map