@atolljs/core 0.1.7 → 0.1.8

package/src/pool/dedicatedWorker.ts

@@ -0,0 +1,332 @@
+import type { MemoryManager } from './memory';
+import { TaskAbortedError, TaskTimeoutError, WorkerCrashedError } from './errors';
+import type { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
+import type { MemoryPersistence, TaskContract, TaskMap, TaskResult, WorkerPoolConfig } from '../contract/types';
+import { devtoolsEnabled, emitDevtools, estimateCloneBytes, nextDevtoolsId, type EmittedDevtoolsEvent } from '../devtools';
+import { fmtBytes, scoped } from '../log';
+import { measureTaskCall } from '../userTiming';
+import type { PoolStats, RunOptions } from './workerPool';
+import { forwardWorkerDevtools, sendInit, setupChannelMemory, type ChannelMemory } from './workerChannel';
+import { applyChaos, CHAOS_FAILURE, KILL_MESSAGE, registerDevtoolsRunner, type ChaosConfig } from './devtoolsCommands';
+
+const workerLog = scoped('worker');
+const taskLog = scoped('task');
+
+/**
+ * Config for a single dedicated worker: the WorkerPool config minus the
+ * pool-only knobs (size, per-worker concurrency cap, queue bound, task
+ * methods). Every call posts straight to the worker.
+ */
+export type DedicatedWorkerConfig<S extends SharedSpec = SharedSpec> = Omit<
+  WorkerPoolConfig<S, TaskMap>,
+  'poolSize' | 'concurrency' | 'maxQueue' | 'tasks'
+>;
+
+interface Call {
+  contract: TaskContract<any[], any>;
+  callId: number;
+  sentAt: number;
+  resolve: (v: any) => void;
+  reject: (e: unknown) => void;
+  /** Settled (or orphaned by abort/timeout): a late reply is discarded. */
+  done: boolean;
+  timer?: ReturnType<typeof setTimeout>;
+  signal?: AbortSignal;
+  onSignalAbort?: () => void;
+}
+
+const agg = () => ({
+  count: 0,
+  mean: 0,
+  max: 0,
+  add(v: number) {
+    this.count++;
+    this.mean += (v - this.mean) / this.count;
+    if (v > this.max) this.max = v;
+  },
+});
+
+/**
+ * One worker, no pool: what `connectWorker({ workers: 1 })` (the default)
+ * builds. Calls are posted to the worker immediately, with no queue and no
+ * scheduler; the worker's own message loop runs them in arrival order (a
+ * task that awaits lets the next message start, exactly as in a pool slot
+ * with a raised concurrency cap). Kept from the pool: per-call
+ * timeout/abort, crash respawn, `stats()`, and the same devtools events,
+ * with `pool:init` flagged `dedicated: true`.
+ */
+export class DedicatedWorker<S extends SharedSpec = SharedSpec> {
+  /**
+   * Devtools correlation id: '<name>-w' when the config has a `name`, else
+   * 'worker-N'. The same role a pool's id plays.
+   */
+  readonly poolId: string;
+  readonly sharedMemory: (SharedMemory<S> & SharedAccess<S>) | undefined;
+  readonly persistence: MemoryPersistence | undefined;
+  private readonly mem: ChannelMemory<S>;
+  private readonly spawn: () => Worker;
+  private readonly respawn: boolean;
+  private readonly taskTimeout?: number;
+  private readonly label?: string;
+  private worker: Worker | null = null;
+  private pending = new Map<number, Call>();
+  private nextMessageId = 0;
+  private nextCallId = 0;
+  private closed = false;
+  /** Dashboard fault injection (`pool.chaos`); null unless devtools set it. */
+  private chaos: ChaosConfig | null = null;
+  private devtoolsOff?: () => void;
+  private drainWaiters: Array<() => void> = [];
+  private statsAgg = { completed: 0, failed: 0, aborted: 0, runMs: agg() };
+
+  constructor(config: DedicatedWorkerConfig<S>) {
+    this.mem = setupChannelMemory(config, 'DedicatedWorker');
+    if (!config.workerUrl && !config.createWorker) {
+      throw new Error('DedicatedWorker requires either `workerUrl` or `createWorker` in its config.');
+    }
+    const url = config.workerUrl;
+    this.spawn = config.createWorker ?? (() => new Worker(url!, { type: 'module' }));
+    this.respawn = config.respawn ?? true;
+    this.taskTimeout = config.taskTimeout;
+    this.label = config.name;
+    this.poolId = nextDevtoolsId('worker', config.name);
+    this.sharedMemory = this.mem.sharedMemory;
+    this.persistence = this.mem.persistence;
+
+    const bytes = this.mem.sharedMemory?.totalBytes ?? this.mem.injectedBuffer?.byteLength;
+    workerLog.info(
+      bytes !== undefined ? `spawning 1 dedicated worker with ${fmtBytes(bytes)} shared buffer` : 'spawning 1 dedicated worker, message-only',
+    );
+    emitDevtools({
+      type: 'pool:init',
+      poolId: this.poolId,
+      label: this.label,
+      poolSize: 1,
+      concurrency: 0,
+      memoryBytes: bytes,
+      dedicated: true,
+    });
+    this.attach(this.spawn());
+    if (devtoolsEnabled()) {
+      this.devtoolsOff = registerDevtoolsRunner({
+        poolId: this.poolId,
+        label: this.label,
+        dedicated: true,
+        size: () => (this.worker ? 1 : 0),
+        stats: () => this.stats(),
+        kill: (slot) => {
+          if (slot !== 0 || !this.worker) throw new Error(`${this.poolId} has no live worker at slot ${slot}`);
+          this.handleError({ message: KILL_MESSAGE });
+        },
+        getChaos: () => this.chaos,
+        setChaos: (chaos) => { this.chaos = chaos; },
+      });
+    }
+  }
+
+  private attach(worker: Worker): void {
+    this.worker = worker;
+    worker.addEventListener('message', (event: MessageEvent) => {
+      if (this.worker !== worker) return;
+      const data = event.data as TaskResult & { messageId?: number; type?: string; event?: EmittedDevtoolsEvent };
+      if (data.type === 'ATOLL_DEVTOOLS' && data.event) {
+        forwardWorkerDevtools(this.poolId, 0, data.event);
+        return;
+      }
+      this.handleReply(data);
+    });
+    worker.addEventListener('error', (event: unknown) => {
+      if (this.worker === worker) this.handleError(event);
+    });
+    const init = sendInit(worker, this.mem);
+    workerLog.debug(`dedicated worker spawned, ${init} sent`);
+    emitDevtools({ type: 'worker:spawn', poolId: this.poolId, slot: 0 });
+  }
+
+  private detach(call: Call): void {
+    if (call.timer) clearTimeout(call.timer);
+    if (call.signal && call.onSignalAbort) call.signal.removeEventListener('abort', call.onSignalAbort);
+  }
+
+  private handleReply(data: TaskResult & { messageId?: number }): void {
+    const call = data.messageId !== undefined ? this.pending.get(data.messageId) : undefined;
+    if (!call) return;
+    this.pending.delete(data.messageId!);
+    this.detach(call);
+    if (!call.done) {
+      call.done = true;
+      const runMs = performance.now() - call.sentAt;
+      this.statsAgg.runMs.add(runMs);
+      if (data.success) {
+        this.statsAgg.completed++;
+        taskLog.debug(`← ${call.contract.taskId} ok`);
+        if (devtoolsEnabled()) {
+          emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: call.callId, taskId: call.contract.taskId, outcome: 'ok', runMs, resultBytes: estimateCloneBytes(data.result) });
+          measureTaskCall(this.poolId, call.contract.taskId, call.callId, 0, call.sentAt, call.sentAt + runMs, true);
+        }
+        call.resolve(data.result);
+      } else {
+        this.statsAgg.failed++;
+        taskLog.warn(`← ${call.contract.taskId} failed: ${data.error}`);
+        if (devtoolsEnabled()) {
+          emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: call.callId, taskId: call.contract.taskId, outcome: 'error', runMs, error: data.error });
+          measureTaskCall(this.poolId, call.contract.taskId, call.callId, 0, call.sentAt, call.sentAt + runMs, false);
+        }
+        call.reject(new Error(data.error));
+      }
+    }
+    this.checkDrained();
+  }
+
+  private handleError(event: unknown): void {
+    if (this.closed) return;
+    const e = event as { message?: string; error?: Error } | undefined;
+    const message = e?.message ?? (e?.error ? String(e.error) : 'worker error');
+    workerLog.warn(`worker error: ${message}`);
+    emitDevtools({ type: 'worker:error', poolId: this.poolId, slot: 0, message });
+    this.rejectPending(message);
+    this.worker?.terminate();
+    this.worker = null;
+    if (this.respawn) {
+      workerLog.info('respawning crashed worker');
+      this.attach(this.spawn());
+      emitDevtools({ type: 'worker:respawn', poolId: this.poolId, slot: 0 });
+    }
+    this.checkDrained();
+  }
+
+  private rejectPending(message: string): void {
+    const err = new WorkerCrashedError(message);
+    for (const call of this.pending.values()) {
+      this.detach(call);
+      if (call.done) continue;
+      call.done = true;
+      this.statsAgg.failed++;
+      emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: call.callId, taskId: call.contract.taskId, outcome: 'crashed', error: message });
+      call.reject(err);
+    }
+    this.pending.clear();
+  }
+
+  /** Abort/timeout: the caller rejects now; the worker's eventual reply is discarded. */
+  private cancel(call: Call, err: Error): void {
+    if (call.done) return;
+    call.done = true;
+    this.detach(call);
+    this.statsAgg.aborted++;
+    emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: call.callId, taskId: call.contract.taskId, outcome: err instanceof TaskTimeoutError ? 'timeout' : 'aborted' });
+    call.reject(err);
+  }
+
+  private checkDrained(): void {
+    if (this.pending.size > 0) return;
+    for (const w of this.drainWaiters.splice(0)) w();
+  }
+
+  /** Post the call straight to the worker — no queue, no scheduler. */
+  public dispatch<Args extends any[], Result>(
+    contract: TaskContract<Args, Result>,
+    args: Args,
+    options?: RunOptions,
+  ): Promise<Result> {
+    const worker = this.worker;
+    if (this.closed || worker === null) {
+      return Promise.reject(new WorkerCrashedError('DedicatedWorker has been terminated — no worker available.'));
+    }
+    if (options?.signal?.aborted) return Promise.reject(new TaskAbortedError());
+    return new Promise<Result>((resolve, reject) => {
+      const call: Call = {
+        contract,
+        callId: ++this.nextCallId,
+        sentAt: performance.now(),
+        resolve,
+        reject,
+        done: false,
+        signal: options?.signal,
+      };
+      if (options?.signal) {
+        call.onSignalAbort = () => this.cancel(call, new TaskAbortedError());
+        options.signal.addEventListener('abort', call.onSignalAbort, { once: true });
+      }
+      const timeout = options?.timeout ?? this.taskTimeout;
+      if (timeout !== undefined) call.timer = setTimeout(() => this.cancel(call, new TaskTimeoutError()), timeout);
+
+      const messageId = this.nextMessageId++;
+      this.pending.set(messageId, call);
+      taskLog.debug(`→ ${contract.taskId}`, { args });
+      emitDevtools({ type: 'task:enqueue', poolId: this.poolId, callId: call.callId, taskId: contract.taskId });
+      if (devtoolsEnabled()) {
+        emitDevtools({ type: 'task:dispatch', poolId: this.poolId, callId: call.callId, taskId: contract.taskId, slot: 0, waitMs: 0, argBytes: estimateCloneBytes(args) });
+      }
+      const msg = { type: 'EXECUTE_TASK', messageId, taskId: contract.taskId, args };
+      if (this.chaos) {
+        applyChaos(this.chaos, {
+          live: () => this.pending.get(messageId) === call,
+          fail: () => this.handleReply({ messageId, taskId: contract.taskId, success: false, error: CHAOS_FAILURE }),
+          timeout: () => this.cancel(call, new TaskTimeoutError()),
+          post: () => worker.postMessage(msg),
+        });
+      } else {
+        worker.postMessage(msg);
+      }
+    });
+  }
+
+  public runTask<Args extends any[], Result>(contract: TaskContract<Args, Result>, ...args: Args): Promise<Result> {
+    return this.dispatch(contract, args);
+  }
+
+  /** The shared buffer handed to the worker via INIT_MEMORY; undefined when message-only. */
+  public get sharedBuffer(): SharedArrayBuffer | undefined {
+    return (this.mem.memoryManager as MemoryManager | undefined)?.getBuffer() ?? this.mem.injectedBuffer;
+  }
+
+  /** The worker, as a one-element snapshot (same shape as `WorkerPool.workers`). */
+  public get workers(): readonly Worker[] {
+    return this.worker ? [this.worker] : [];
+  }
+
+  /** Same shape as `WorkerPool.stats()`; `queued` and `waitMs` stay zero (there is no queue). */
+  public stats(): PoolStats {
+    const live = this.worker ? 1 : 0;
+    const { runMs } = this.statsAgg;
+    return {
+      workers: live,
+      idle: live && this.pending.size === 0 ? 1 : 0,
+      inFlight: this.pending.size,
+      queued: 0,
+      completed: this.statsAgg.completed,
+      failed: this.statsAgg.failed,
+      aborted: this.statsAgg.aborted,
+      waitMs: { count: 0, mean: 0, max: 0 },
+      runMs: { count: runMs.count, mean: runMs.mean, max: runMs.max },
+    };
+  }
+
+  /** Resolves once nothing is in flight, then terminates. */
+  public close(): Promise<void> {
+    if (this.pending.size === 0) {
+      this.terminate();
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.drainWaiters.push(() => {
+        this.terminate();
+        resolve();
+      });
+    });
+  }
+
+  public terminate(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.devtoolsOff?.();
+    void this.persistence?.stop()?.catch?.((e: unknown) => workerLog.warn('memory persistence stop failed', e));
+    workerLog.info('terminating dedicated worker');
+    emitDevtools({ type: 'pool:terminate', poolId: this.poolId });
+    this.rejectPending('worker terminated');
+    this.worker?.terminate();
+    this.worker = null;
+    this.checkDrained();
+  }
+}

package/src/pool/devtoolsCommands.ts

@@ -0,0 +1,165 @@
+/**
+ * Dashboard control over the live runners of this thread: `pool.list`,
+ * `pool.stats`, `worker.kill`, `pool.chaos`. Runners (`WorkerPool`,
+ * `DedicatedWorker`) register here from their constructor only when
+ * `devtoolsEnabled()`, and unregister on terminate — with devtools off
+ * nothing is registered and the runners' only cost is one `chaos` field
+ * check per dispatch.
+ *
+ * Scope: one registry per thread. Pools spawned inside workers (sub-pools,
+ * nested island clients) register in the worker's own registry, which the
+ * dashboard's control channel (main thread only) cannot reach.
+ */
+import { registerDevtoolsCommand } from '../devtools';
+import type { PoolStats } from './workerPool';
+
+/** Fault injection applied at dispatch. All rates are probabilities in 0..1. */
+export interface ChaosConfig {
+  /** Delay before the call is posted to the worker. */
+  delayMs?: number;
+  /** Share of calls rejected with `CHAOS_FAILURE` (settle outcome 'error'). */
+  failRate?: number;
+  /** Share of calls failed through the timeout path (settle outcome 'timeout'). */
+  timeoutRate?: number;
+}
+
+/** Error message of a chaos-injected failure. */
+export const CHAOS_FAILURE = 'chaos: injected failure';
+/** Crash message of a dashboard `worker.kill`. */
+export const KILL_MESSAGE = 'killed from devtools';
+
+/** What a runner exposes to the dashboard commands. */
+export interface DevtoolsRunnerHandle {
+  poolId: string;
+  label?: string;
+  dedicated: boolean;
+  /** Live worker count. */
+  size(): number;
+  stats(): PoolStats;
+  /** Run the runner's real crash handler for that slot (throws on a bad slot). */
+  kill(slot: number): void;
+  getChaos(): ChaosConfig | null;
+  setChaos(chaos: ChaosConfig | null): void;
+}
+
+const runners = new Map<string, DevtoolsRunnerHandle>();
+let uninstall: (() => void) | null = null;
+
+const runnerOf = (args: Record<string, unknown>): DevtoolsRunnerHandle => {
+  const id = args.poolId;
+  if (typeof id !== 'string') throw new Error('poolId (string) is required');
+  const r = runners.get(id);
+  if (!r) {
+    throw new Error(
+      id.includes('~')
+        ? `runner '${id}' lives inside a worker: nested pools are not controllable from the dashboard`
+        : `no live runner '${id}' on this thread`,
+    );
+  }
+  return r;
+};
+
+const rate = (v: unknown, name: string): number | undefined => {
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== 'number' || !Number.isFinite(v) || v < 0 || v > 1) {
+    throw new Error(`${name} must be a number in 0..1`);
+  }
+  return v || undefined;
+};
+
+/** Validate `pool.chaos` args into a config; null when nothing is active (clears). */
+export const parseChaos = (args: Record<string, unknown>): ChaosConfig | null => {
+  const { delayMs } = args;
+  if (delayMs !== undefined && delayMs !== null && (typeof delayMs !== 'number' || !Number.isFinite(delayMs) || delayMs < 0)) {
+    throw new Error('delayMs must be a non-negative number');
+  }
+  const failRate = rate(args.failRate, 'failRate');
+  const timeoutRate = rate(args.timeoutRate, 'timeoutRate');
+  if ((failRate ?? 0) + (timeoutRate ?? 0) > 1) throw new Error('failRate + timeoutRate must not exceed 1');
+  const chaos: ChaosConfig = {};
+  if (delayMs) chaos.delayMs = delayMs as number;
+  if (failRate) chaos.failRate = failRate;
+  if (timeoutRate) chaos.timeoutRate = timeoutRate;
+  return Object.keys(chaos).length ? chaos : null;
+};
+
+const listRunners = () =>
+  [...runners.values()].map((r) => ({
+    poolId: r.poolId,
+    label: r.label ?? r.poolId,
+    size: r.size(),
+    dedicated: r.dedicated,
+    chaos: r.getChaos(),
+  }));
+
+const install = (): (() => void) => {
+  const offs = [
+    registerDevtoolsCommand('pool.list', () => listRunners()),
+    registerDevtoolsCommand('pool.stats', (args) => runnerOf(args).stats()),
+    registerDevtoolsCommand('worker.kill', (args) => {
+      const r = runnerOf(args);
+      const slot = args.slot ?? 0;
+      if (typeof slot !== 'number' || !Number.isInteger(slot) || slot < 0) {
+        throw new Error('slot must be a non-negative integer');
+      }
+      r.kill(slot);
+      return { poolId: r.poolId, slot, killed: true };
+    }),
+    registerDevtoolsCommand('pool.chaos', (args) => {
+      const r = runnerOf(args);
+      r.setChaos(parseChaos(args));
+      return r.getChaos();
+    }),
+  ];
+  return () => offs.forEach((off) => off());
+};
+
+/**
+ * Register a live runner; returns its unregister. The pool commands are
+ * installed with the first runner and removed with the last, so the
+ * dashboard's `devtools.commands` only advertises them while there is
+ * something to control.
+ */
+export const registerDevtoolsRunner = (handle: DevtoolsRunnerHandle): (() => void) => {
+  runners.set(handle.poolId, handle);
+  uninstall ??= install();
+  return () => {
+    if (runners.get(handle.poolId) !== handle) return;
+    runners.delete(handle.poolId);
+    if (runners.size === 0 && uninstall) {
+      uninstall();
+      uninstall = null;
+    }
+  };
+};
+
+/** Hooks a runner supplies to `applyChaos` for one dispatched call. */
+export interface ChaosCall {
+  /** Still awaiting its reply (not crashed/terminated away during the delay). */
+  live(): boolean;
+  /** Settle as a worker-reported failure (the runner's reply path). */
+  fail(): void;
+  /** Settle through the runner's timeout path. */
+  timeout(): void;
+  /** Post the call to the worker. */
+  post(): void;
+}
+
+/**
+ * Apply an active chaos config to one dispatched call. An injected failure
+ * never reaches the worker; an injected timeout settles the caller through
+ * the timeout path and still posts the call, exactly like a real timeout
+ * (the worker runs it; its late reply frees the slot and is discarded).
+ */
+export const applyChaos = (chaos: ChaosConfig, call: ChaosCall): void => {
+  const r = Math.random();
+  const fail = r < (chaos.failRate ?? 0);
+  const timeout = !fail && r < (chaos.failRate ?? 0) + (chaos.timeoutRate ?? 0);
+  if (!chaos.delayMs && !fail && !timeout) return call.post();
+  setTimeout(() => {
+    if (!call.live()) return;
+    if (fail) return call.fail();
+    if (timeout) call.timeout();
+    call.post();
+  }, chaos.delayMs ?? 0);
+};

package/src/pool/subWorkerClient.ts

@@ -0,0 +1,70 @@
+import type { SharedSpec } from '../contract/sharedMemory';
+import type { WorkerDefinition } from '../worker/defineWorker';
+import { connectWorker, type ConnectWorkerConfig, type WorkerClient } from './workerClient';
+
+/**
+ * Worker-shell side of a nested pool: identical options to
+ * {@link ConnectWorkerConfig}, since the pool protocol (INIT / INIT_MEMORY /
+ * EXECUTE_TASK) doesn't care which side of the thread boundary spawned the
+ * workers. The distinguishing knob is `sharedBuffer` — inside a worker
+ * shell, a bound contract's `.buffer` (or the shell pool's `sharedBuffer`)
+ * lets sub-workers attach to the SAME shared memory instead of a fresh one.
+ */
+export interface ConnectSubWorkerConfig<S extends SharedSpec> extends ConnectWorkerConfig<S> {}
+
+/**
+ * Spawn a worker pool from INSIDE a worker — the worker-shell counterpart
+ * of {@link connectWorker}. The sub-worker entry is a normal `defineWorker`
+ * module; only the spawn site differs:
+ *
+ *   // shell.worker.ts — runs inside a dedicated worker
+ *   const sub = connectSubWorker<SubWorker>({
+ *     worker: () => new Worker(new URL('./sub.worker.ts', import.meta.url), { type: 'module' }),
+ *     sharedMemory: memory,                    // fresh buffer per sub-pool
+ *     // — or attach sub-workers to THIS worker's bound buffer:
+ *     // sharedBuffer: memory.buffer,
+ *     workers: 2,
+ *   });
+ *
+ *   methods: { fanOut: (chunks) => Promise.all(chunks.map((c) => sub.crunch(c))) }
+ *
+ * Memory modes (both supported, pick per config):
+ *  - `sharedMemory` without `sharedBuffer`: the sub-pool allocates its own
+ *    WebAssembly.Memory inside the worker and binds the contract to it —
+ *    a private buffer for this tier.
+ *  - `sharedBuffer: someContract.buffer`: no allocation — every sub-worker
+ *    binds the shell's existing buffer, so all three tiers (main, shell,
+ *    sub) read and write the same fields. Hub-and-spoke sharing.
+ *
+ * Nested workers need `new Worker` inside a worker context: Chrome and
+ * Firefox support it, Safari does not — feature-detect and fall back to
+ * dispatching on the main-thread pool. Node's `worker_threads` nests
+ * natively; use `worker: () => createNodeWorker(new Worker('./sub.js'))`
+ * (a sub-worker entry still needs `@atolljs/node/shim` first).
+ *
+ * Bundlers detect `new Worker(new URL(...))` inside a worker bundle too:
+ * the @atolljs/vite dev plugin rewrites nested entry URLs back onto its
+ * `?worker_file` bundling path, and `vite build` emits nested worker
+ * chunks. The same rules as the main thread apply — the URL must stay an
+ * inline literal, never hoisted or computed.
+ */
+export function connectSubWorker<
+  W extends WorkerDefinition,
+  S extends SharedSpec = W extends WorkerDefinition<infer X> ? X : SharedSpec,
+>(config: ConnectSubWorkerConfig<S>): WorkerClient<W, S> {
+  const guarded: ConnectSubWorkerConfig<S> = { ...config };
+  if (typeof config.worker !== 'function') {
+    // A URL config means we call `new Worker` ourselves — surface a clear
+    // error on engines without nested workers instead of a bare
+    // ReferenceError at spawn time.
+    guarded.worker = () => {
+      if (typeof Worker === 'undefined') {
+        throw new Error(
+          'connectSubWorker: no `Worker` global in this context — nested dedicated workers are unsupported here (e.g. Safari). Feature-detect and fall back to a main-thread pool.',
+        );
+      }
+      return new Worker(config.worker as URL, { type: 'module' });
+    };
+  }
+  return connectWorker<W, S>(guarded);
+}

package/src/pool/workerChannel.ts

@@ -0,0 +1,99 @@
+/**
+ * The per-worker plumbing both runners share: `WorkerPool` (N workers,
+ * queue + least-busy scheduling) and `DedicatedWorker` (one worker, no
+ * pool). Memory setup, the INIT handshake, and devtools forwarding are the
+ * same protocol whichever runner owns the worker.
+ */
+import { MemoryManager } from './memory';
+import type { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
+import type { MemoryPersistence, TaskMap, WorkerPoolConfig } from '../contract/types';
+import { devtoolsEnabled, forwardDevtools, type EmittedDevtoolsEvent } from '../devtools';
+
+export interface ChannelMemory<S extends SharedSpec> {
+  sharedMemory: (SharedMemory<S> & SharedAccess<S>) | undefined;
+  memoryManager?: MemoryManager;
+  /** A caller-supplied buffer shipped via INIT_MEMORY (sub-worker / second-runner sharing). */
+  injectedBuffer?: SharedArrayBuffer;
+  persistence: MemoryPersistence | undefined;
+}
+
+/**
+ * Resolve the runner's memory once, at construction: a caller-supplied
+ * buffer binds the contract to those bytes, otherwise a fresh
+ * WebAssembly.Memory is allocated. Message-only runners get neither.
+ */
+export function setupChannelMemory<S extends SharedSpec>(
+  config: WorkerPoolConfig<S, TaskMap>,
+  owner: string,
+): ChannelMemory<S> {
+  if (config.sharedMemory || config.sharedBuffer !== undefined) {
+    if (typeof SharedArrayBuffer === 'undefined' || (typeof crossOriginIsolated !== 'undefined' && !crossOriginIsolated)) {
+      throw new Error(
+        `${owner} requires SharedArrayBuffer in a cross-origin isolated context — serve the page with COOP/COEP headers.`
+      );
+    }
+  }
+  let injectedBuffer: SharedArrayBuffer | undefined;
+  if (config.sharedBuffer !== undefined) {
+    injectedBuffer = typeof config.sharedBuffer === 'function' ? config.sharedBuffer() : config.sharedBuffer;
+    if (!injectedBuffer) {
+      throw new Error(
+        `${owner}: \`sharedBuffer\` resolved to an empty buffer — the producing pool or contract has no bound memory yet.`
+      );
+    }
+  }
+  if (!config.sharedMemory) return { sharedMemory: undefined, injectedBuffer, persistence: undefined };
+
+  const sharedMemory = config.sharedMemory;
+  let memoryManager: MemoryManager | undefined;
+  if (injectedBuffer) {
+    sharedMemory.bind(injectedBuffer);
+  } else {
+    memoryManager = new MemoryManager(config.memory);
+    memoryManager.ensureCapacity(sharedMemory.totalBytes);
+    sharedMemory.bind(memoryManager.getBuffer());
+  }
+  return { sharedMemory, memoryManager, injectedBuffer, persistence: config.persistence?.(sharedMemory) };
+}
+
+/**
+ * The INIT handshake: INIT_MEMORY with the runner's memory (or the injected
+ * buffer), bare INIT for message-only runners. `devtools` tells the worker
+ * to forward its instrumentation back only when a sink is live at spawn.
+ */
+export function sendInit<S extends SharedSpec>(worker: Worker, mem: ChannelMemory<S>): 'INIT' | 'INIT_MEMORY' {
+  if (mem.memoryManager) {
+    worker.postMessage({ type: 'INIT_MEMORY', memory: mem.memoryManager.memory, devtools: devtoolsEnabled() });
+    return 'INIT_MEMORY';
+  }
+  if (mem.injectedBuffer) {
+    worker.postMessage({ type: 'INIT_MEMORY', buffer: mem.injectedBuffer, devtools: devtoolsEnabled() });
+    return 'INIT_MEMORY';
+  }
+  worker.postMessage({ type: 'INIT', devtools: devtoolsEnabled() });
+  return 'INIT';
+}
+
+/**
+ * Re-emit a worker-forwarded devtools event into this thread's sink.
+ *
+ * A runner constructed inside a worker mints ids ('pool-1', 'worker-1') on
+ * that context's own counters, which collide textually with ids minted on
+ * the parent thread. Every id arriving from a worker refers to the worker's
+ * local id space, so it is qualified unconditionally as
+ * `${runnerId}#${slot}~${id}`: the id then encodes the spawn path and
+ * dashboards can draw parent→child edges. Existing `worker` stamps
+ * (multi-hop forwarding) are qualified the same way so attribution stays
+ * pinned to the deepest emitting worker.
+ */
+export function forwardWorkerDevtools(runnerId: string, slot: number, ev: EmittedDevtoolsEvent & { poolId?: string }): void {
+  const qualify = (id: string): string => `${runnerId}#${slot}~${id}`;
+  forwardDevtools({
+    ...ev,
+    ...(ev.poolId !== undefined ? { poolId: qualify(ev.poolId) } : {}),
+    worker:
+      ev.worker === undefined
+        ? { poolId: runnerId, slot }
+        : { poolId: qualify(ev.worker.poolId), slot: ev.worker.slot },
+  });
+}