@downdraft/engine 0.0.0 → 0.1.0

package/core/src/worker/sim-worker-host.ts

@@ -0,0 +1,358 @@
+// ============================================================================
+// SimWorkerHost — standard control surface for sim workers on BaseWorkerHost.
+//
+// Every game's XxxWorkerHost re-implemented the same methods on top of
+// BaseWorkerHost:
+//   - pause()/resume()/step()/setSpeed() fire-and-forget proxy wrappers
+//   - getStats() with a try/catch → null fallback
+//   - writeInput()/writeInputF32() into the SAB input region
+//   - per-game event callback fields (onCollected, onMatched, ...) — replaced
+//     here by a generic onSimEvent(kind, cb) registry + "*" wildcard
+//   - attachProfilingSAB() — forwards __profilingAttach to the worker proxy
+//   - save/load RPC wrappers with null-safe fallbacks — replaced by the
+//     generic apiCall()/apiSend() helpers
+//
+// Subclasses still MUST implement createWorker() with the inline
+// `new Worker(new URL("./xxx-worker.ts", import.meta.url), { type: "module" })`
+// pattern (Vite static analysis requirement — see base-worker-host.ts) and
+// onInit() to call the worker's init RPC.
+//
+// Example:
+//   class MyWorkerHost extends SimWorkerHost<MyApi> {
+//     constructor() {
+//       const sab = allocateSimBuffer();
+//       super(sab);
+//       this.setInputWriter(new MySimBufferWriter(sab, OFFSETS, W, H));
+//     }
+//     protected createWorker() {
+//       return new Worker(new URL("./my-worker.ts", import.meta.url), { type: "module" });
+//     }
+//     protected async onInit() {
+//       await this.getProxy()!.proxy.init(this.getSimBuffer());
+//     }
+//   }
+// ============================================================================
+
+import type { LoadOptions, SaveMeta, SaveOptions } from "../save/persist-types";
+import { createLogger } from "../util/logger";
+import { BaseWorkerHost } from "./base-worker-host";
+import type { WorkerApi } from "./rpc";
+import type { SimWorkerStats } from "./sim-worker-base";
+
+const log = createLogger();
+
+/**
+ * The standard control API createSimWorker() exposes worker-side.
+ * Workers created with `save:`/`onCommand:` options additionally expose
+ * save/load/initSaveStore/restoreFromState/captureState/sendCommand —
+ * reachable via the WorkerApi index signature since their presence depends
+ * on the worker's options.
+ */
+export interface SimWorkerControlApi extends WorkerApi {
+  pause(): Promise<void>;
+  resume(): Promise<void>;
+  shutdown(): Promise<void>;
+  setSpeed(speed: number): Promise<void>;
+  step(): Promise<void>;
+  getStats(): Promise<SimWorkerStats>;
+}
+
+/**
+ * Optional save/command verbs — exposed worker-side when the worker was
+ * created with createSimWorker({ save: {...}, onCommand }) or hand-rolled
+ * equivalents. Games declare this on their worker API type
+ * (`interface MyApi extends SimWorkerControlApi, SimWorkerSaveApi {...}`) to
+ * get typed captureState/restoreFromState calls through SimWorkerHost.
+ */
+export interface SimWorkerSaveApi {
+  save(
+    slotName: string,
+    opts?: SaveOptions,
+  ): Promise<{ slotName: string; stateJson: string; success: boolean; gen?: number; meta?: SaveMeta }>;
+  load(slotName: string, stateJson?: string, opts?: LoadOptions): Promise<boolean>;
+  initSaveStore(opts: unknown): Promise<void>;
+  restoreFromState(stateJson: string, blobs?: Record<string, ArrayBuffer>): Promise<void>;
+  captureState(): Promise<{ stateJson: string; blobs?: Record<string, ArrayBuffer> }>;
+  sendCommand(cmd: unknown): Promise<void>;
+}
+
+/**
+ * Minimal input-writer surface — satisfied by GridSimBufferWriter
+ * (library-sand) and RawInputRegionWriter (below), or any game writer with
+ * the same methods. `field` is a byte offset within the input region.
+ */
+export interface SimInputWriter {
+  writeInput(field: number, value: number): void;
+  writeInputF32(field: number, value: number): void;
+}
+
+/**
+ * Input writer over a raw SAB region — for games that don't use
+ * GridSimBufferWriter. Writes i32 via writeInput and f32 via writeInputF32,
+ * treating `field` as a byte offset relative to `byteOffset`.
+ */
+export class RawInputRegionWriter implements SimInputWriter {
+  private i32: Int32Array;
+  private f32: Float32Array;
+
+  constructor(sab: SharedArrayBuffer, byteOffset: number, byteLength: number) {
+    this.i32 = new Int32Array(sab, byteOffset, Math.floor(byteLength / 4));
+    this.f32 = new Float32Array(sab, byteOffset, Math.floor(byteLength / 4));
+  }
+
+  writeInput(field: number, value: number): void {
+    this.i32[field / 4] = value;
+  }
+
+  writeInputF32(field: number, value: number): void {
+    this.f32[field / 4] = value;
+  }
+}
+
+export abstract class SimWorkerHost<TApi extends WorkerApi = SimWorkerControlApi> extends BaseWorkerHost<TApi> {
+  private eventHandlers = new Map<string, Set<(data: unknown, kind: string) => void>>();
+  private inputWriter: SimInputWriter | null = null;
+
+  /**
+   * Set the SAB input writer (e.g. the game's GridSimBufferWriter or a
+   * RawInputRegionWriter). Typically called from the subclass constructor.
+   */
+  protected setInputWriter(writer: SimInputWriter): void {
+    this.inputWriter = writer;
+  }
+
+  // --- Standard control surface (fire-and-forget) ---
+
+  pause(): void {
+    this.apiSend((api) => api.pause());
+  }
+
+  resume(): void {
+    this.apiSend((api) => api.resume());
+  }
+
+  step(): void {
+    this.apiSend((api) => api.step());
+  }
+
+  setSpeed(speed: number): void {
+    this.apiSend((api) => api.setSpeed(speed));
+  }
+
+  async getStats(): Promise<SimWorkerStats | null> {
+    const proxy = this.getProxy();
+    if (!proxy?.proxy.getStats) return null;
+    try {
+      return await proxy.proxy.getStats();
+    } catch {
+      return null;
+    }
+  }
+
+  // --- Generic RPC helpers (replace per-game null-safe wrappers) ---
+
+  /**
+   * Await a worker RPC, returning null if the worker is not started or the
+   * call throws. Replaces the per-game `try { return await proxy.proxy.x() }
+   * catch { return null }` pattern.
+   */
+  protected async apiCall<R>(fn: (api: TApi) => Promise<R>): Promise<R | null> {
+    const proxy = this.getProxy();
+    if (!proxy) return null;
+    try {
+      return await fn(proxy.proxy);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Fire-and-forget worker RPC — swallows the "not started" and rejection
+   * cases. Replaces the per-game `this.getProxy()?.proxy.x().catch(() => {})`
+   * pattern.
+   */
+  protected apiSend(fn: (api: TApi) => unknown): void {
+    const proxy = this.getProxy();
+    if (!proxy) return;
+    try {
+      const result = fn(proxy.proxy);
+      if (result instanceof Promise) result.catch(() => {});
+    } catch {
+      // Worker call threw synchronously — ignore (worker may be dead).
+    }
+  }
+
+  // --- Standard save/command surface ---
+  // These wrappers call the RPC verbs createSimWorker() exposes when the
+  // worker was created with `save:`/`onCommand:` options (or hand-rolled
+  // equivalents). Workers without the verbs return null/false via apiCall.
+
+  /** Serialize + store sim state in the worker; null when not started or unsupported. */
+  async save(
+    slotName: string,
+    opts?: SaveOptions,
+  ): Promise<{ slotName: string; stateJson: string; success: boolean; gen?: number } | null> {
+    return this.apiCall((api) => api.save(slotName, opts));
+  }
+
+  /** Load sim state into the worker. Pass stateJson when the store lives renderer-side. */
+  async load(slotName: string, stateJson?: string, opts?: LoadOptions): Promise<boolean> {
+    return (await this.apiCall((api) => api.load(slotName, stateJson, opts))) ?? false;
+  }
+
+  /**
+   * Serialize the worker's save payload — without touching any store. For
+   * renderer-owned save flows (createGameSaveSystem) that embed the payload
+   * in their own SaveState. Binary data (typed arrays) arrives in `blobs`.
+   * Null when the worker wasn't started or doesn't expose captureState.
+   */
+  async captureState(): Promise<{ stateJson: string; blobs?: Record<string, ArrayBuffer> } | null> {
+    return this.apiCall((api) => api.captureState());
+  }
+
+  /** Initialize the worker's own save store (e.g. OPFS). Throws when not started. */
+  async initSaveStore(opts: unknown): Promise<void> {
+    const proxy = this.getProxy();
+    if (!proxy) throw new Error("Worker not started");
+    await proxy.proxy.initSaveStore(opts);
+  }
+
+  /**
+   * Restore the worker from a serialized state. Throws when not started.
+   * `blobs` carries binary payloads (grid/chunk data) for workers whose
+   * restore isn't JSON-expressible.
+   */
+  async restoreFromState(stateJson: string, blobs?: Record<string, ArrayBuffer>): Promise<void> {
+    const proxy = this.getProxy();
+    if (!proxy) throw new Error("Worker not started");
+    await proxy.proxy.restoreFromState(stateJson, blobs);
+  }
+
+  /** Fire-and-forget command dispatch. */
+  sendCommand(cmd: unknown): void {
+    this.apiSend((api) => api.sendCommand(cmd));
+  }
+
+  // --- SAB input writers ---
+
+  /** Write an i32 input field (byte offset within the input region). */
+  writeInput(field: number, value: number): void {
+    this.inputWriter?.writeInput(field, value);
+  }
+
+  /** Write an f32 input field (byte offset within the input region). */
+  writeInputF32(field: number, value: number): void {
+    this.inputWriter?.writeInputF32(field, value);
+  }
+
+  // --- Event subscriptions ---
+
+  /**
+   * Subscribe to a worker event kind (e.g. "collected", "matched"). Returns
+   * an unsubscribe function. Use "*" to subscribe to all events (replaces the
+   * per-game `onEvents(handler)` single-handler field); wildcard callbacks
+   * receive the event kind as the second argument.
+   */
+  onSimEvent(kind: string, cb: (data: unknown, kind: string) => void): () => void {
+    let set = this.eventHandlers.get(kind);
+    if (!set) {
+      set = new Set();
+      this.eventHandlers.set(kind, set);
+    }
+    set.add(cb);
+    return () => {
+      set.delete(cb);
+    };
+  }
+
+  /**
+   * GameSimWorker-compatible event subscription — the callback receives
+   * `{ kind, data }` messages. Lets a renderer-owned SimWorkerHost plug into
+   * startGame()'s declarative `events` routing via `module.simFromRenderer`.
+   * Returns an unsubscribe function.
+   */
+  subscribeEvents(cb: (msg: { kind: string; data: unknown }) => void): () => void {
+    return this.onSimEvent("*", (data, kind) => cb({ kind, data }));
+  }
+
+  /**
+   * GameSimWorker-compatible input-buffer accessor. Sim worker hosts share
+   * one SAB (input region lives inside the sim buffer); games with a
+   * separate input SAB override this.
+   */
+  getInputBuffer(): SharedArrayBuffer {
+    return this.getSimBuffer();
+  }
+
+  /**
+   * Dispatches the "ready" handshake to the base class, then fans out to
+   * per-kind subscribers and "*" wildcard subscribers. Subclasses that
+   * override onEvent should call super.onEvent(kind, data) to keep ready
+   * tracking + event dispatch working.
+   */
+  protected override onEvent(kind: string, data?: unknown): void {
+    super.onEvent(kind, data);
+    const specific = this.eventHandlers.get(kind);
+    if (specific) {
+      for (const cb of specific.values()) {
+        try {
+          cb(data, kind);
+        } catch (err) {
+          log.error(this.constructor.name, `Event handler for "${kind}" threw: ${err}`);
+        }
+      }
+    }
+    const wildcard = this.eventHandlers.get("*");
+    if (wildcard) {
+      for (const cb of wildcard.values()) {
+        try {
+          cb(data, kind);
+        } catch (err) {
+          log.error(this.constructor.name, `Wildcard event handler threw: ${err}`);
+        }
+      }
+    }
+  }
+
+  // --- Profiling ---
+
+  /**
+   * Attach the global ProfilingSAB to the sim worker. Called by the renderer
+   * after initDevTools({ profiling: true }) creates the ProfilingBridge.
+   * The worker's profiling prelude claims a slot + patches prototypes +
+   * initializes the warning engine + event-loop monitor.
+   *
+   * The worker must expose __profilingAttach (via exposeProfilingApi()).
+   */
+  async attachProfilingSAB(
+    sab: SharedArrayBuffer,
+    opts?: {
+      workerTag?: string;
+      runtime?: number;
+      opfs?: boolean;
+      idb?: boolean;
+      defaultWarningRules?: boolean;
+      layout?: {
+        maxSlots: number;
+        iopsRingCap: number;
+        warningRingCap: number;
+        stringTableCap: number;
+      };
+    },
+  ): Promise<void> {
+    const proxy = this.getProxy();
+    if (!proxy) return;
+    try {
+      await (proxy.proxy as any).__profilingAttach?.(sab, {
+        workerTag: opts?.workerTag ?? "sim",
+        runtime: opts?.runtime ?? 0,
+        opfs: opts?.opfs ?? true,
+        idb: opts?.idb ?? true,
+        defaultWarningRules: opts?.defaultWarningRules ?? true,
+        layout: opts?.layout,
+      });
+    } catch (err) {
+      log.warn(this.constructor.name, `Profiling SAB attach failed: ${err}`);
+    }
+  }
+}

package/core/src/worker/task-pool.ts

@@ -0,0 +1,256 @@
+// ============================================================================
+// TaskPool + createTaskWorker — pooled task-worker infrastructure.
+//
+// Generalized from to-the-ocean's terrain-mesh-pool.ts / terrain-mesh-worker.ts.
+//
+// Unlike the wrap()/expose() RPC layer, the __job protocol supports
+// TRANSFERABLES — task results may include an explicit transfer list
+// (mesh vertex/index buffers, etc.) so large payloads move zero-copy.
+//
+// Host side:
+//   const pool = new TaskPool({
+//     workerCount: 4,
+//     // CRITICAL: `new URL(...)` must be inlined inside `new Worker()` —
+//     // Vite only bundles worker modules when it sees this exact pattern.
+//     createWorker: () => new Worker(new URL("./my-worker.ts", import.meta.url), { type: "module" }),
+//   });
+//   await pool.init();
+//   const mesh = await pool.dispatch<MeshResult>("generateChunkMesh", [req], req.key);
+//
+// Worker side:
+//   createTaskWorker({ generateChunkMesh: (req) => ({ result, transfer: [buf] }) });
+//
+// Features: round-robin dispatch with optional per-key worker affinity,
+// synchronous-fallback flag when workers fail to spawn, pending-job map
+// with reject-on-destroy.
+// ============================================================================
+
+// --- Shared protocol ---
+
+export interface JobMessage {
+  __job: true;
+  id: number;
+  fn: string;
+  args: unknown[];
+}
+
+export interface JobResultMessage {
+  __jobResult: true;
+  id: number;
+  result?: unknown;
+  error?: string;
+}
+
+/** A task function. Return the result, or `{ result, transfer }` to transfer buffers. */
+export type TaskFn = (...args: any[]) => unknown | Promise<unknown>;
+
+/**
+ * Worker side: install the __job message handler dispatching to `tasks`.
+ * Call at module top level in the worker entry file.
+ *
+ * Task fns return either a plain result or `{ result, transfer }` where
+ * `transfer` is a Transferable[] passed to postMessage for zero-copy return.
+ */
+export function createTaskWorker(tasks: Record<string, TaskFn>): void {
+  self.onmessage = async (e: MessageEvent) => {
+    const msg = e.data as JobMessage;
+    if (!msg || msg.__job !== true) return;
+
+    const fn = tasks[msg.fn];
+    if (!fn) {
+      (self as any).postMessage({ __jobResult: true, id: msg.id, error: `Unknown function: ${msg.fn}` } satisfies JobResultMessage);
+      return;
+    }
+
+    try {
+      const out = await fn(...(msg.args ?? []));
+      const isWrapped = out != null && typeof out === "object" && "result" in out;
+      const result = isWrapped ? (out as any).result : out;
+      const transfer: Transferable[] = isWrapped ? ((out as any).transfer ?? []) : [];
+      (self as any).postMessage({ __jobResult: true, id: msg.id, result } satisfies JobResultMessage, transfer);
+    } catch (err) {
+      (self as any).postMessage({ __jobResult: true, id: msg.id, error: String(err) } satisfies JobResultMessage);
+    }
+  };
+}
+
+// --- Host side ---
+
+interface PendingJob {
+  resolve: (result: any) => void;
+  reject: (error: Error) => void;
+}
+
+export interface TaskPoolOptions {
+  /** Number of workers. Default: min(4, hardwareConcurrency - 1). */
+  workerCount?: number;
+  /**
+   * Worker factory — MUST contain the inline
+   * `new Worker(new URL("./xxx-worker.ts", import.meta.url), { type: "module" })`
+   * pattern (Vite static analysis — see base-worker-host.ts).
+   */
+  createWorker: () => Worker;
+  /** Optional worker error hook (default: logs via engine logger). */
+  onWorkerError?: (index: number, e: ErrorEvent) => void;
+}
+
+export class TaskPool {
+  private workers: Worker[] = [];
+  private pending = new Map<number, PendingJob>();
+  private keyWorkerMap = new Map<string, number>();
+  private nextJobId = 0;
+  private roundRobin = 0;
+  private readonly workerCount: number;
+  private readonly createWorker: () => Worker;
+  private readonly onWorkerError?: (index: number, e: ErrorEvent) => void;
+  private fallback = false;
+  private destroyed = false;
+
+  constructor(opts: TaskPoolOptions) {
+    const hw = (typeof navigator !== "undefined" && navigator.hardwareConcurrency) ? navigator.hardwareConcurrency : 4;
+    this.workerCount = opts.workerCount ?? Math.min(4, Math.max(1, hw - 1));
+    this.createWorker = opts.createWorker;
+    this.onWorkerError = opts.onWorkerError;
+  }
+
+  /** Spawn all workers. On failure, sets fallback mode (dispatch() rejects). */
+  async init(): Promise<void> {
+    if (this.destroyed) return;
+
+    try {
+      for (let i = 0; i < this.workerCount; i++) {
+        const worker = this.createWorker();
+        worker.onerror = (e: ErrorEvent) => {
+          if (this.onWorkerError) this.onWorkerError(i, e);
+          else log.error("TaskPool", `Worker ${i} error: ${e.message}`);
+        };
+        worker.addEventListener("message", (e: MessageEvent) => {
+          const msg = e.data as JobResultMessage;
+          if (!msg || msg.__jobResult !== true) return;
+          const pending = this.pending.get(msg.id);
+          if (!pending) return;
+          this.pending.delete(msg.id);
+          if (msg.error) {
+            pending.reject(new Error(msg.error));
+          } else {
+            pending.resolve(msg.result);
+          }
+        });
+        this.workers.push(worker);
+      }
+    } catch (err) {
+      log.warn("TaskPool", `Failed to spawn workers, falling back to synchronous: ${err}`);
+      this.fallback = true;
+    }
+  }
+
+  /** True when worker spawn failed — callers should run tasks in-line. */
+  isFallback(): boolean {
+    return this.fallback;
+  }
+
+  /** Number of live workers. */
+  get size(): number {
+    return this.workers.length;
+  }
+
+  /**
+   * Dispatch a task. `affinityKey` pins all calls with the same key to the
+   * same worker (e.g. an island key so field generation state is reused).
+   * Rejects when no workers are available (fallback mode).
+   */
+  dispatch<T>(taskName: string, args: unknown[], affinityKey?: string): Promise<T> {
+    if (this.fallback || this.workers.length === 0) {
+      return Promise.reject(new Error(`[TaskPool] No workers available for task: ${taskName}`));
+    }
+
+    const id = ++this.nextJobId;
+
+    let workerIndex: number;
+    if (affinityKey && this.keyWorkerMap.has(affinityKey)) {
+      workerIndex = this.keyWorkerMap.get(affinityKey)!;
+    } else {
+      workerIndex = this.roundRobin % this.workers.length;
+      this.roundRobin++;
+      if (affinityKey) {
+        this.keyWorkerMap.set(affinityKey, workerIndex);
+      }
+    }
+
+    const worker = this.workers[workerIndex];
+    const msg: JobMessage = { __job: true, id, fn: taskName, args };
+
+    return new Promise<T>((resolve, reject) => {
+      this.pending.set(id, { resolve: resolve as (r: any) => void, reject });
+      worker.postMessage(msg);
+    });
+  }
+
+  /** Terminate all workers and reject pending jobs. Safe to call twice. */
+  destroy(): void {
+    this.destroyed = true;
+    this.workers.forEach((worker) => {
+      worker.terminate();
+    });
+    this.workers = [];
+    for (const pending of this.pending.values()) {
+      pending.reject(new Error("TaskPool destroyed"));
+    }
+    this.pending.clear();
+    this.keyWorkerMap.clear();
+  }
+}
+
+// ============================================================================
+// PortChannel — RPC channel over a transferred MessagePort.
+//
+// Generalized from overburden's pathfinding-broker.ts: the renderer spawns a
+// task worker (so Vite can bundle it), creates a MessageChannel, and transfers
+// one port to each side. The sim-side broker wraps its port with this class —
+// attachPort() replaces any existing channel, dispose() shuts it down.
+// ============================================================================
+
+import { createLogger } from "../util/logger";
+import { wrap, type WorkerApi, type WorkerProxy } from "./rpc";
+
+const log = createLogger();
+
+export class PortChannel<TApi extends WorkerApi> {
+  protected proxy: WorkerProxy<TApi> | null = null;
+  private _ready = false;
+
+  /**
+   * Attach a MessagePort connected to the task worker. Replaces any existing
+   * channel (the old proxy is terminated).
+   */
+  attachPort(port: MessagePort): void {
+    if (this.proxy) {
+      this.proxy.terminate();
+    }
+    // timeoutMs: 0 — task calls may be long-running; no RPC timeout.
+    this.proxy = wrap<TApi>(port as any, { timeoutMs: 0 });
+    this._ready = true;
+  }
+
+  /** True once a port is attached. */
+  isReady(): boolean {
+    return this._ready;
+  }
+
+  /** The typed RPC proxy (null before attachPort / after dispose). */
+  getProxy(): WorkerProxy<TApi> | null {
+    return this.proxy;
+  }
+
+  /** Detach the port — sends shutdown() best-effort, then terminates. */
+  dispose(): void {
+    if (this.proxy) {
+      try {
+        this.proxy.proxy.shutdown?.().catch(() => { /* port may already be closed */ });
+      } catch { /* ignore */ }
+      this.proxy.terminate();
+    }
+    this.proxy = null;
+    this._ready = false;
+  }
+}

package/core/src/worker/task-worker.ts

@@ -0,0 +1,83 @@
+// ============================================================================
+// Generic Task Worker — receives job messages, executes registered functions,
+// and posts results back. Works in both Web Workers and Node.js worker_threads.
+// ============================================================================
+
+import { getWarningEngine, METRIC_TASK_LATENCY, recordTaskLatency } from "../profiling/worker-prelude";
+import { getWorkerHost } from "./rpc";
+
+// Function registry — workers register functions by string key
+const registry = new Map<string, (...args: unknown[]) => unknown>();
+
+// Message handler for job dispatch — installed lazily on the first
+// registerTask() call so that workers using other dispatch mechanisms (e.g.
+// createTaskWorker in task-pool.ts) don't get a second __job listener that
+// would post spurious "Unknown function" results.
+let dispatchInstalled = false;
+let unsubscribeDispatch: (() => void) | null = null;
+
+function ensureDispatchInstalled(): void {
+  if (dispatchInstalled) return;
+  dispatchInstalled = true;
+  const isWorkerContext =
+    (typeof self !== "undefined" && typeof (self as any).postMessage === "function") ||
+    (typeof (globalThis as any).process !== "undefined" && (globalThis as any).process.env?.NODE_CHANNEL_FD !== undefined);
+  if (!isWorkerContext) return;
+
+  try {
+    const host = getWorkerHost();
+    const unsub = host.onHostMessage((raw: any) => {
+      const msg = raw?.data ?? raw;
+      if (!msg || msg.__job !== true) return;
+
+      const { id, fn: fnKey, args } = msg;
+      const fn = registry.get(fnKey);
+
+      if (!fn) {
+        host.postToHost({ __jobResult: true, id, error: `Unknown function: ${fnKey}` });
+        return;
+      }
+
+      try {
+        const taskStart = performance.now();
+        const result = fn(...args);
+        const handleResult = (r: unknown) => {
+          const durationUs = (performance.now() - taskStart) * 1000;
+          recordTaskLatency("js", durationUs, fnKey);
+          getWarningEngine()?.checkInstant(METRIC_TASK_LATENCY, durationUs);
+          host.postToHost({ __jobResult: true, id, result: r });
+        };
+        if (result instanceof Promise) {
+          result
+            .then(handleResult)
+            .catch((e) => host.postToHost({ __jobResult: true, id, error: String(e) }));
+        } else {
+          handleResult(result);
+        }
+      } catch (e) {
+        host.postToHost({ __jobResult: true, id, error: String(e) });
+      }
+    });
+    unsubscribeDispatch = typeof unsub === "function" ? unsub : null;
+  } catch {
+    // Not in a worker context — module loaded in main process, skip setup
+  }
+}
+
+export function registerTask(name: string, fn: (...args: unknown[]) => unknown): void {
+  registry.set(name, fn);
+  ensureDispatchInstalled();
+}
+
+export function unregisterTask(name: string): void {
+  registry.delete(name);
+  if (registry.size === 0 && dispatchInstalled) {
+    unsubscribeDispatch?.();
+    unsubscribeDispatch = null;
+    dispatchInstalled = false;
+  }
+}
+
+export function hasTask(name: string): boolean {
+  return registry.has(name);
+}