@zhin.js/isolate 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @zhin.js/isolate
+
+下一代 Zhin Runtime 的可选 Node 隔离适配器。它为每个 `runtime: isolated` Plugin generation 创建独立 Worker 或 child process，并只通过 structured-clone RPC 与 Host 通信。
+
+> 当前包属于 `feature/next` 绿地实现，版本仍为 `0.0.0` 且未作为稳定 API 发布。
+
+## 为什么独立成包
+
+`@zhin.js/runtime` 只定义 `IsolatedPluginRuntimePort`，不强制默认 IM 安装携带隔离实现。需要故障或并发隔离的 Root 显式安装本包；trusted Plugin 的启动路径和生产闭包不变。
+
+本包没有第三方运行时依赖，只使用 Node 的 `worker_threads`、`child_process` 和 IPC。它不依赖 Vite、编译器、CSS 工具或 native/wasm 模块。
+
+## 使用
+
+```ts
+import { NodeIsolatedPluginRuntime } from '@zhin.js/isolate';
+import { RootRuntime } from '@zhin.js/runtime';
+
+const runtime = new RootRuntime({
+  projectRoot: process.cwd(),
+  modules,
+  environment,
+  isolation: new NodeIsolatedPluginRuntime({
+    mode: 'worker',
+    hostMethods: {
+      audit(input, { owner }) {
+        return auditLog.write({ owner, input });
+      },
+    },
+  }),
+});
+```
+
+child Plugin manifest 显式选择隔离：
+
+```json
+{
+  "name": "@acme/reports",
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "runtime": "isolated",
+    "entry": "./plugin.js"
+  }
+}
+```
+
+Root Plugin 负责整个进程生命周期，因此不能使用 `runtime: isolated`。
+
+## Plugin 通道
+
+隔离 Plugin 只能要求 `isolatedChannelToken` 和 `runtimeEnvironmentToken`。Host Scope、数据库、EnvStore 与自定义 Token 不会隐式复制到隔离侧；需要的数据应进入 owner config，操作应成为显式 allowlist RPC。
+
+```ts
+import { definePlugin } from '@zhin.js/plugin-runtime';
+import { isolatedChannelToken } from '@zhin.js/isolate';
+
+export default definePlugin({
+  name: 'reports',
+  requires: [isolatedChannelToken],
+  setup({ resources, config }) {
+    const channel = resources.use(isolatedChannelToken);
+    return channel.expose('render', async (input) => ({
+      report: await render(input, config.get()),
+    }));
+  },
+});
+```
+
+Host 从对应 owner 的 Resource snapshot 取得 `isolatedPluginToken`，再调用 `handle.call()`。输入、输出、事件与 config 都必须可 structured clone；函数、socket、数据库连接等对象会在发送前被拒绝。
+
+## 代际切换
+
+适配器参与 Runtime generation handoff：
+
+1. `prepare` 创建候选 isolate、import entry 并校验 definition，但不执行 setup。
+2. `quiescePrevious` 停止旧 handle 接收新调用，并等待所有已接收 RPC 完成。
+3. `activateNext` 在候选 isolate 内执行 setup；失败会清理候选并恢复旧 handle。
+4. Runtime 原子提交 snapshot 后，`openNext` 才开放新 handle。
+5. 旧 generation 的最后一个 lease 释放后，Scope disposer 终止旧 isolate。
+
+RPC 超时会把整个实例标记为 failed 并终止 transport，因为远端工作可能仍在运行，不能把超时伪装成安全 drain。Worker/进程意外退出会拒绝全部 pending RPC，并通过 `onCrash` 上报；当前 generation 内不静默重启。
+
+## 隔离边界
+
+这是故障和并发隔离，不是安全沙箱。Worker 与 child process 仍拥有启动用户授予 Node 进程的文件、网络和系统权限。运行不可信代码需要在 Host 外再叠加容器、OS account、permission model 或其他真正的 sandbox。
+
+普通 Feature definition 含函数、Endpoint 和闭包，不能安全 structured clone。因此 isolated Plugin 当前不能 mount Host Feature provider。未来跨边界 Feature 必须提供显式 codec/代理契约，不能序列化任意函数来绕过边界。
+
+## 开发验证
+
+```bash
+pnpm --filter @zhin.js/isolate test
+pnpm --filter @zhin.js/isolate build
+pnpm --filter @zhin.js/isolate check:size
+```
+
+## 相关文档
+
+- [隔离 Plugin Runtime ADR](../../../docs/adr/0049-isolated-plugin-runtime.md)
+- [Plugin Runtime](../runtime/README.md)
+- [Greenfield Bootstrap 状态](../../../docs/architecture/target-implementation/greenfield-bootstrap.md)

package/lib/bootstrap.d.ts

@@ -0,0 +1,5 @@
+/**
+ * This function is serialized into Worker and child-process entry scripts.
+ * It must remain self-contained: every dependency belongs inside the function.
+ */
+export declare function isolateBootstrap(): void;

package/lib/bootstrap.js

@@ -0,0 +1,188 @@
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-require-imports --
+ * The serialized bootstrap cannot retain imported runtime values or external types. */
+/**
+ * This function is serialized into Worker and child-process entry scripts.
+ * It must remain self-contained: every dependency belongs inside the function.
+ */
+export function isolateBootstrap() {
+    const processSend = process.send?.bind(process);
+    const workerThreads = processSend ? undefined : require('node:worker_threads');
+    const endpoint = processSend
+        ? {
+            send: (message) => processSend(message),
+            receive: (listener) => process.on('message', listener),
+        }
+        : {
+            send: (message) => workerThreads.parentPort.postMessage(message),
+            receive: (listener) => workerThreads.parentPort.on('message', listener),
+        };
+    let definition;
+    let preparePayload;
+    let state = 'empty';
+    const disposers = [];
+    const handlers = new Map();
+    const hostCalls = new Map();
+    let nextHostCall = 1;
+    const errorValue = (error) => {
+        const value = error instanceof Error ? error : new Error(String(error));
+        return { name: value.name, message: value.message, stack: value.stack };
+    };
+    const fromErrorValue = (error) => {
+        const value = new Error(error?.message ?? 'Unknown Host RPC error');
+        value.name = error?.name ?? 'Error';
+        if (error?.stack)
+            value.stack = error.stack;
+        return value;
+    };
+    const clone = (value) => structuredClone(value);
+    // Construct native import inside the isolate so test runners and future
+    // Host compilers cannot rewrite it to a Host-only helper.
+    const importModule = new Function('specifier', 'return import(specifier)');
+    const channel = {
+        expose(method, handler) {
+            if (!method || handlers.has(method))
+                throw new Error(`Duplicate isolated method: ${method}`);
+            handlers.set(method, handler);
+            return () => handlers.delete(method);
+        },
+        call(method, input) {
+            const id = nextHostCall++;
+            endpoint.send({ type: 'host-call', id, method, input: clone(input) });
+            return new Promise((resolve, reject) => hostCalls.set(id, { resolve, reject }));
+        },
+        emit(name, payload) {
+            endpoint.send({ type: 'event', name, payload: clone(payload) });
+        },
+    };
+    const disposeSetup = async () => {
+        const errors = [];
+        for (const dispose of disposers.splice(0).reverse()) {
+            try {
+                await dispose();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        handlers.clear();
+        if (errors.length > 0)
+            throw new AggregateError(errors, 'Isolated Plugin disposal failed');
+    };
+    const methods = {
+        async prepare(payload) {
+            if (state !== 'empty')
+                throw new Error('Isolated Plugin has already been prepared');
+            preparePayload = payload;
+            const namespace = await importModule(payload.entry);
+            definition = namespace.default;
+            if (!definition || typeof definition.name !== 'string') {
+                throw new TypeError(`${payload.packageName} does not default-export a Plugin definition`);
+            }
+            const allowed = new Set(['zhin.isolate.channel', 'zhin.runtime-environment']);
+            for (const token of definition.requires ?? []) {
+                if (!allowed.has(token.id))
+                    throw new Error(`Host resource cannot cross isolation boundary: ${token.id}`);
+            }
+            const descriptor = { name: definition.name, metadata: definition.metadata };
+            clone(descriptor);
+            state = 'prepared';
+            return descriptor;
+        },
+        async activate() {
+            if (state !== 'prepared')
+                throw new Error(`Cannot activate isolated Plugin from ${state}`);
+            const local = new Map([
+                ['zhin.isolate.channel', channel],
+                ['zhin.runtime-environment', Object.freeze(preparePayload.environment)],
+            ]);
+            const lifecycle = {
+                add(dispose) { disposers.push(dispose); return dispose; },
+                seal() { },
+                dispose: disposeSetup,
+            };
+            const resources = {
+                use(token) {
+                    if (!local.has(token.id))
+                        throw new Error(`Missing isolated resource ${token.id}`);
+                    return local.get(token.id);
+                },
+                has(token) { return local.has(token.id); },
+                provide(token, value, dispose) {
+                    if (local.has(token.id))
+                        throw new Error(`Duplicate isolated resource ${token.id}`);
+                    local.set(token.id, value);
+                    if (dispose)
+                        disposers.push(dispose);
+                },
+            };
+            const plugin = Object.freeze({
+                id: preparePayload.owner,
+                instanceKey: preparePayload.owner.split('/').at(-1),
+                parent: preparePayload.parent,
+                root: 'root',
+                role: 'child',
+            });
+            try {
+                const returned = await definition.setup?.({
+                    plugin,
+                    config: { get: () => Object.freeze(preparePayload.config) },
+                    resources,
+                    lifecycle,
+                    handoff: { add() { throw new Error('Nested generation handoff is unavailable in isolation'); } },
+                });
+                if (returned)
+                    disposers.push(returned);
+                state = 'active';
+            }
+            catch (error) {
+                await disposeSetup();
+                state = 'prepared';
+                throw error;
+            }
+        },
+        async deactivate() {
+            if (state === 'active')
+                await disposeSetup();
+            if (state !== 'closed')
+                state = 'prepared';
+        },
+        async call(payload) {
+            if (state !== 'active')
+                throw new Error(`Isolated Plugin is not active: ${state}`);
+            const handler = handlers.get(payload.method);
+            if (!handler)
+                throw new Error(`Unknown isolated method: ${payload.method}`);
+            return clone(await handler(payload.input));
+        },
+        async dispose() {
+            if (state === 'active')
+                await disposeSetup();
+            state = 'closed';
+            for (const pending of hostCalls.values())
+                pending.reject(new Error('Isolated Plugin closed'));
+            hostCalls.clear();
+        },
+    };
+    endpoint.receive(async (message) => {
+        if (message?.type === 'host-result') {
+            const pending = hostCalls.get(message.id);
+            if (!pending)
+                return;
+            hostCalls.delete(message.id);
+            if (message.ok)
+                pending.resolve(message.value);
+            else
+                pending.reject(fromErrorValue(message.error));
+            return;
+        }
+        if (message?.type !== 'request')
+            return;
+        try {
+            const value = await methods[message.method](message.payload);
+            endpoint.send({ type: 'response', id: message.id, ok: true, value: clone(value) });
+        }
+        catch (error) {
+            endpoint.send({ type: 'response', id: message.id, ok: false, error: errorValue(error) });
+        }
+    });
+}

package/lib/contracts.d.ts

@@ -0,0 +1,21 @@
+import { type Dispose, type PluginId } from '@zhin.js/plugin-runtime';
+export type IsolatedPluginStatus = 'prepared' | 'active' | 'quiesced' | 'failed' | 'closed';
+export interface IsolatedPluginEvent {
+    readonly name: string;
+    readonly payload: unknown;
+}
+/** Host-side capability for an isolated Plugin instance. */
+export interface IsolatedPluginHandle {
+    readonly owner: PluginId;
+    readonly status: IsolatedPluginStatus;
+    call<TResult = unknown>(method: string, input?: unknown): Promise<TResult>;
+    onEvent(listener: (event: IsolatedPluginEvent) => void): Dispose;
+}
+/** Plugin-side boundary. Imported by isolated Plugin entry modules. */
+export interface IsolatedChannel {
+    expose(method: string, handler: (input: unknown) => unknown | Promise<unknown>): Dispose;
+    call<TResult = unknown>(method: string, input?: unknown): Promise<TResult>;
+    emit(name: string, payload?: unknown): void;
+}
+export declare const isolatedPluginToken: import("@zhin.js/plugin-runtime").Token<IsolatedPluginHandle>;
+export declare const isolatedChannelToken: import("@zhin.js/plugin-runtime").Token<IsolatedChannel>;

package/lib/contracts.js

@@ -0,0 +1,3 @@
+import { createToken } from '@zhin.js/plugin-runtime';
+export const isolatedPluginToken = createToken('zhin.isolated-plugin', 'Owner-scoped handle for an isolated Plugin instance');
+export const isolatedChannelToken = createToken('zhin.isolate.channel', 'Structured-clone RPC boundary available inside an isolated Plugin');

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from './contracts.js';
+export * from './runtime.js';
+export type { IsolateMode } from './transport.js';

package/lib/index.js

@@ -0,0 +1,2 @@
+export * from './contracts.js';
+export * from './runtime.js';

package/lib/protocol.d.ts

@@ -0,0 +1,40 @@
+export interface RequestMessage {
+    readonly type: 'request';
+    readonly id: number;
+    readonly method: 'prepare' | 'activate' | 'deactivate' | 'call' | 'dispose';
+    readonly payload?: unknown;
+}
+export interface ResponseMessage {
+    readonly type: 'response';
+    readonly id: number;
+    readonly ok: boolean;
+    readonly value?: unknown;
+    readonly error?: SerializedError;
+}
+export interface HostCallMessage {
+    readonly type: 'host-call';
+    readonly id: number;
+    readonly method: string;
+    readonly input?: unknown;
+}
+export interface HostResultMessage {
+    readonly type: 'host-result';
+    readonly id: number;
+    readonly ok: boolean;
+    readonly value?: unknown;
+    readonly error?: SerializedError;
+}
+export interface EventMessage {
+    readonly type: 'event';
+    readonly name: string;
+    readonly payload?: unknown;
+}
+export interface SerializedError {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+}
+export type HostMessage = ResponseMessage | HostCallMessage | EventMessage;
+export type IsolateMessage = RequestMessage | HostResultMessage;
+export declare function serializeError(error: unknown): SerializedError;
+export declare function deserializeError(error?: SerializedError): Error;

package/lib/protocol.js

@@ -0,0 +1,13 @@
+export function serializeError(error) {
+    if (error instanceof Error) {
+        return { name: error.name, message: error.message, stack: error.stack };
+    }
+    return { name: 'Error', message: String(error) };
+}
+export function deserializeError(error) {
+    const result = new Error(error?.message ?? 'Unknown isolated runtime error');
+    result.name = error?.name ?? 'Error';
+    if (error?.stack)
+        result.stack = error.stack;
+    return result;
+}

package/lib/runtime.d.ts

@@ -0,0 +1,19 @@
+import type { PluginId } from '@zhin.js/plugin-runtime';
+import type { IsolatedPluginPrepareRequest, IsolatedPluginRuntimePort, PreparedIsolatedPlugin } from '@zhin.js/runtime';
+import { type IsolateMode } from './transport.js';
+export interface IsolatedHostCallContext {
+    readonly owner: PluginId;
+}
+export type IsolatedHostMethod = (input: unknown, context: IsolatedHostCallContext) => unknown | Promise<unknown>;
+export interface NodeIsolatedPluginRuntimeOptions {
+    readonly mode?: IsolateMode;
+    readonly requestTimeoutMs?: number;
+    readonly hostMethods?: Readonly<Record<string, IsolatedHostMethod>>;
+    readonly onCrash?: (owner: PluginId, error: Error) => void;
+}
+/** Node isolation adapter with one Worker/process per Plugin generation. */
+export declare class NodeIsolatedPluginRuntime implements IsolatedPluginRuntimePort {
+    #private;
+    constructor(options?: NodeIsolatedPluginRuntimeOptions);
+    prepare(request: IsolatedPluginPrepareRequest): Promise<PreparedIsolatedPlugin>;
+}

package/lib/runtime.js

@@ -0,0 +1,233 @@
+import { pathToFileURL } from 'node:url';
+import { isolatedPluginToken, } from './contracts.js';
+import { deserializeError, serializeError, } from './protocol.js';
+import { createTransport } from './transport.js';
+/** Node isolation adapter with one Worker/process per Plugin generation. */
+export class NodeIsolatedPluginRuntime {
+    #mode;
+    #requestTimeoutMs;
+    #hostMethods;
+    #onCrash;
+    #quiescedPrevious = new Map();
+    constructor(options = {}) {
+        this.#mode = options.mode ?? 'worker';
+        this.#requestTimeoutMs = options.requestTimeoutMs ?? 10_000;
+        this.#hostMethods = Object.freeze({ ...options.hostMethods });
+        this.#onCrash = options.onCrash;
+    }
+    async prepare(request) {
+        assertCloneable(request.config, `Config for ${request.owner}`);
+        const instance = new IsolatedInstance(request.owner, createTransport(this.#mode), this.#requestTimeoutMs, this.#hostMethods, this.#onCrash);
+        try {
+            const descriptor = await instance.request('prepare', {
+                ...request,
+                entry: pathToFileURL(request.entry).href,
+            });
+            return {
+                descriptor,
+                resources: [{ token: isolatedPluginToken, value: instance }],
+                handoff: {
+                    quiescePrevious: async (previous) => {
+                        const handle = previous.resources.get(request.owner)?.get(isolatedPluginToken.id);
+                        if (!(handle instanceof IsolatedInstance))
+                            return;
+                        await handle.quiesce();
+                        this.#quiescedPrevious.set(request.owner, handle);
+                    },
+                    activateNext: () => instance.activate(),
+                    deactivateNext: () => instance.deactivate(),
+                    resumePrevious: () => {
+                        const previous = this.#quiescedPrevious.get(request.owner);
+                        this.#quiescedPrevious.delete(request.owner);
+                        previous?.resume();
+                    },
+                    openNext: () => {
+                        instance.open();
+                        this.#quiescedPrevious.delete(request.owner);
+                    },
+                },
+                dispose: () => instance.close(),
+            };
+        }
+        catch (error) {
+            await instance.close();
+            throw error;
+        }
+    }
+}
+class IsolatedInstance {
+    owner;
+    transport;
+    timeoutMs;
+    hostMethods;
+    onCrash;
+    #status = 'prepared';
+    #nextRequest = 1;
+    #inFlight = 0;
+    #drainWaiters = [];
+    #closed = false;
+    #pending = new Map();
+    #listeners = new Set();
+    constructor(owner, transport, timeoutMs, hostMethods, onCrash) {
+        this.owner = owner;
+        this.transport = transport;
+        this.timeoutMs = timeoutMs;
+        this.hostMethods = hostMethods;
+        this.onCrash = onCrash;
+        transport.onMessage((message) => this.#onMessage(message));
+        transport.onExit((error) => this.#fail(error));
+    }
+    get status() { return this.#status; }
+    async activate() {
+        await this.request('activate');
+    }
+    async deactivate() {
+        if (this.#closed || this.#status === 'failed')
+            return;
+        await this.request('deactivate');
+        this.#status = 'prepared';
+    }
+    open() {
+        if (this.#closed || this.#status === 'failed')
+            throw new Error(`Cannot open ${this.owner}`);
+        this.#status = 'active';
+    }
+    async quiesce() {
+        if (this.#status !== 'active')
+            return;
+        this.#status = 'quiesced';
+        if (this.#inFlight === 0)
+            return;
+        await new Promise((resolve) => this.#drainWaiters.push(resolve));
+    }
+    resume() {
+        if (this.#status === 'quiesced')
+            this.#status = 'active';
+    }
+    async call(method, input) {
+        if (this.#status !== 'active') {
+            throw new Error(`Isolated Plugin ${this.owner} is not accepting calls: ${this.#status}`);
+        }
+        assertMethod(method);
+        assertCloneable(input, `Input for ${method}`);
+        this.#inFlight += 1;
+        try {
+            return await this.request('call', { method, input });
+        }
+        finally {
+            this.#inFlight -= 1;
+            if (this.#inFlight === 0) {
+                for (const resolve of this.#drainWaiters.splice(0))
+                    resolve();
+            }
+        }
+    }
+    onEvent(listener) {
+        this.#listeners.add(listener);
+        return () => { this.#listeners.delete(listener); };
+    }
+    request(method, payload) {
+        if (this.#closed)
+            return Promise.reject(new Error(`Isolated Plugin ${this.owner} is closed`));
+        const id = this.#nextRequest++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                const error = new Error(`Isolated request timed out after ${this.timeoutMs}ms: ${method}`);
+                reject(error);
+                // A timed-out remote call may still mutate state. Retiring the whole
+                // instance preserves the generation boundary instead of faking drain.
+                this.#fail(error);
+                void this.transport.close();
+            }, this.timeoutMs);
+            this.#pending.set(id, {
+                resolve: (value) => resolve(value),
+                reject,
+                timer,
+            });
+            this.transport.send({ type: 'request', id, method, payload });
+        });
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        try {
+            if (this.#status !== 'failed')
+                await this.request('dispose');
+        }
+        finally {
+            this.#closed = true;
+            this.#status = 'closed';
+            this.#rejectPending(new Error(`Isolated Plugin ${this.owner} closed`));
+            await this.transport.close();
+        }
+    }
+    #onMessage(message) {
+        if (message.type === 'response') {
+            const pending = this.#pending.get(message.id);
+            if (!pending)
+                return;
+            this.#pending.delete(message.id);
+            clearTimeout(pending.timer);
+            if (message.ok)
+                pending.resolve(message.value);
+            else
+                pending.reject(deserializeError(message.error));
+            return;
+        }
+        if (message.type === 'event') {
+            const event = Object.freeze({ name: message.name, payload: message.payload });
+            for (const listener of this.#listeners)
+                listener(event);
+            return;
+        }
+        void this.#handleHostCall(message);
+    }
+    async #handleHostCall(message) {
+        const method = this.hostMethods[message.method];
+        try {
+            if (!method)
+                throw new Error(`Host RPC method is not allowed: ${message.method}`);
+            const value = await method(message.input, { owner: this.owner });
+            assertCloneable(value, `Host RPC result for ${message.method}`);
+            this.transport.send({ type: 'host-result', id: message.id, ok: true, value });
+        }
+        catch (error) {
+            this.transport.send({
+                type: 'host-result',
+                id: message.id,
+                ok: false,
+                error: serializeError(error),
+            });
+        }
+    }
+    #fail(error) {
+        if (this.#closed || this.#status === 'closed' || this.#status === 'failed')
+            return;
+        this.#status = 'failed';
+        this.#rejectPending(error);
+        for (const resolve of this.#drainWaiters.splice(0))
+            resolve();
+        this.onCrash?.(this.owner, error);
+    }
+    #rejectPending(error) {
+        for (const pending of this.#pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.#pending.clear();
+    }
+}
+function assertCloneable(value, label) {
+    try {
+        structuredClone(value);
+    }
+    catch (error) {
+        throw new TypeError(`${label} is not structured-cloneable`, { cause: error });
+    }
+}
+function assertMethod(method) {
+    if (!method || method === '__proto__' || method === 'constructor' || method === 'prototype') {
+        throw new TypeError(`Invalid isolated RPC method: ${method}`);
+    }
+}

package/lib/transport.d.ts

@@ -0,0 +1,9 @@
+import type { HostMessage, IsolateMessage } from './protocol.js';
+export type IsolateMode = 'worker' | 'process';
+export interface MessageTransport {
+    send(message: IsolateMessage): void;
+    onMessage(listener: (message: HostMessage) => void): void;
+    onExit(listener: (error: Error) => void): void;
+    close(): Promise<void>;
+}
+export declare function createTransport(mode: IsolateMode): MessageTransport;

package/lib/transport.js

@@ -0,0 +1,53 @@
+import { spawn } from 'node:child_process';
+import { Worker } from 'node:worker_threads';
+import { isolateBootstrap } from './bootstrap.js';
+export function createTransport(mode) {
+    const source = `(${isolateBootstrap.toString()})()`;
+    return mode === 'worker'
+        ? new WorkerTransport(new Worker(source, { eval: true }))
+        : new ProcessTransport(spawn(process.execPath, ['-e', source], {
+            stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+            serialization: 'advanced',
+        }));
+}
+class WorkerTransport {
+    worker;
+    constructor(worker) {
+        this.worker = worker;
+    }
+    send(message) { this.worker.postMessage(message); }
+    onMessage(listener) { this.worker.on('message', listener); }
+    onExit(listener) {
+        this.worker.once('error', listener);
+        this.worker.once('exit', (code) => {
+            if (code !== 0)
+                listener(new Error(`Isolated Worker exited with code ${code}`));
+        });
+    }
+    async close() { await this.worker.terminate(); }
+}
+class ProcessTransport {
+    child;
+    constructor(child) {
+        this.child = child;
+    }
+    send(message) {
+        if (!this.child.send)
+            throw new Error('Isolated process IPC is unavailable');
+        this.child.send(message);
+    }
+    onMessage(listener) { this.child.on('message', listener); }
+    onExit(listener) {
+        this.child.once('error', listener);
+        this.child.once('exit', (code, signal) => {
+            if (code !== 0)
+                listener(new Error(`Isolated process exited (${code ?? signal})`));
+        });
+    }
+    async close() {
+        if (this.child.exitCode !== null || this.child.signalCode !== null)
+            return;
+        this.child.kill();
+        await new Promise((resolve) => this.child.once('exit', () => resolve()));
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@zhin.js/isolate",
+  "version": "1.0.0",
+  "description": "Worker and child-process isolation adapter for the Zhin Plugin Runtime",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "dependencies": {
+    "@zhin.js/plugin-runtime": "1.0.0",
+    "@zhin.js/runtime": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/im/isolate"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/im/isolate/tests",
+    "check:size": "node ../../../scripts/check-plugin-runtime-install-size.mjs @zhin.js/isolate"
+  }
+}