@downdraft/engine 0.2.0 → 0.3.1

package/core/src/worker/rpc.ts

@@ -5,6 +5,7 @@
 // ============================================================================
 
 import { createLogger } from "../util/logger";
+import { untrackedTimeout } from "../util/session-timer";
 
 const log = createLogger();
 
@@ -91,6 +92,66 @@ interface EventMessage {
   data: any;
 }
 
+interface EventBatchMessage {
+  __eventBatch: true;
+  events: { kind: string; data: any }[];
+}
+
+// --- Event channel stats ---
+// Cheap counters the DOWNDRAFT_EVENT_STATS logger (and QA tooling) read to
+// verify batching is actually engaging: emitted events vs postMessage posts
+// on the worker side, messages vs delivered events on the host side.
+const eventChannelStats = {
+  /** Worker side: emit() calls. */
+  emitted: 0,
+  /** Worker side: postMessage calls carrying events (batch or single). */
+  posts: 0,
+  /** Host side: messages received carrying events. */
+  messages: 0,
+  /** Host side: events delivered to listeners. */
+  events: 0,
+  /** Host side: largest observed __eventBatch. */
+  maxBatch: 0,
+};
+
+export function getEventChannelStats(): Readonly<typeof eventChannelStats> {
+  return eventChannelStats;
+}
+
+function envFlag(name: string): boolean {
+  try {
+    return (
+      (globalThis as { process?: { env?: Record<string, string> } }).process?.env?.[name] === "1"
+    );
+  } catch {
+    return false;
+  }
+}
+
+let statsLoggerStarted = false;
+function startEventStatsLogger(): void {
+  if (statsLoggerStarted || !envFlag("DOWNDRAFT_EVENT_STATS")) return;
+  statsLoggerStarted = true;
+  let prev = { emitted: 0, posts: 0, messages: 0, events: 0 };
+  const t = setInterval(() => {
+    const s = eventChannelStats;
+    const d = {
+      emitted: s.emitted - prev.emitted,
+      posts: s.posts - prev.posts,
+      messages: s.messages - prev.messages,
+      events: s.events - prev.events,
+    };
+    prev = { emitted: s.emitted, posts: s.posts, messages: s.messages, events: s.events };
+    if (d.emitted || d.posts || d.messages || d.events) {
+      log.info(
+        "rpc-events",
+        `5s Δ emitted=${d.emitted} posts=${d.posts} msgs=${d.messages} events=${d.events} maxBatch=${s.maxBatch}`
+      );
+    }
+  }, 5000);
+  (t as { unref?: () => void }).unref?.();
+}
+
 function isRpcRequest(msg: any): msg is RpcRequest {
   return msg && msg.__rpc === true && typeof msg.method === "string";
 }
@@ -103,6 +164,10 @@ function isEventMessage(msg: any): msg is EventMessage {
   return msg && msg.__event === true;
 }
 
+function isEventBatchMessage(msg: any): msg is EventBatchMessage {
+  return msg && msg.__eventBatch === true;
+}
+
 // --- Worker side: expose an API object ---
 
 export type WorkerApi = Record<string, (...args: any[]) => any>;
@@ -138,13 +203,55 @@ export interface WorkerEventEmitter {
 
 export function exposeEvents(host?: WorkerHost): WorkerEventEmitter {
   const h = host ?? getWorkerHost();
+  startEventStatsLogger();
   return {
     emit: (kind: string, data: any) => {
+      eventChannelStats.emitted++;
+      eventChannelStats.posts++;
       h.postToHost({ __event: true, kind, data } as EventMessage);
     },
   };
 }
 
+export interface BatchedWorkerEventEmitter extends WorkerEventEmitter {
+  /** Post any queued events immediately. */
+  flush: () => void;
+}
+
+/**
+ * Event emitter that coalesces emit() calls into a single `__eventBatch`
+ * postMessage per macrotask. A sim emitting per-tick or per-entity events
+ * otherwise produces one structured clone + one main-thread task per event,
+ * and the task burst competes with rAF. Events emitted during a tick batch
+ * (the worker never yields to timers mid-tick) all land in one message;
+ * events emitted between ticks flush on the next macrotask, so latency for
+ * isolated events is unchanged.
+ */
+export function exposeBatchedEvents(host?: WorkerHost): BatchedWorkerEventEmitter {
+  const h = host ?? getWorkerHost();
+  startEventStatsLogger();
+  let queue: { kind: string; data: any }[] = [];
+  let flushScheduled = false;
+  const flush = () => {
+    flushScheduled = false;
+    if (queue.length === 0) return;
+    eventChannelStats.posts++;
+    h.postToHost({ __eventBatch: true, events: queue } as EventBatchMessage);
+    queue = [];
+  };
+  return {
+    emit: (kind: string, data: any) => {
+      eventChannelStats.emitted++;
+      queue.push({ kind, data });
+      if (!flushScheduled) {
+        flushScheduled = true;
+        setTimeout(flush, 0);
+      }
+    },
+    flush,
+  };
+}
+
 // --- Main side: wrap a worker as a typed async proxy ---
 
 type AnyWorker = {
@@ -171,6 +278,7 @@ export interface WrapOptions {
 const DEFAULT_TIMEOUT_MS = 30_000;
 
 export function wrap<T extends WorkerApi>(worker: AnyWorker, options?: WrapOptions): WorkerProxy<T> {
+  startEventStatsLogger();
   const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   // A worker nobody terminates must not pin the runtime after the host's
   // window closes — in-flight RPCs still hold the loop via their timeout.
@@ -196,10 +304,16 @@ export function wrap<T extends WorkerApi>(worker: AnyWorker, options?: WrapOptio
       return;
     }
 
-    if (isEventMessage(msg)) {
-      for (const cb of eventListeners.values()) {
-        try { cb(msg.kind, msg.data); } catch (err) {
-          log.error("worker-proxy", `Event listener error: ${err}`);
+    if (isEventMessage(msg) || isEventBatchMessage(msg)) {
+      const events = isEventBatchMessage(msg) ? msg.events : [msg];
+      eventChannelStats.messages++;
+      eventChannelStats.events += events.length;
+      if (events.length > eventChannelStats.maxBatch) eventChannelStats.maxBatch = events.length;
+      for (const ev of events) {
+        for (const cb of eventListeners.values()) {
+          try { cb(ev.kind, ev.data); } catch (err) {
+            log.error("worker-proxy", `Event listener error: ${err}`);
+          }
         }
       }
     }
@@ -248,7 +362,7 @@ export function wrap<T extends WorkerApi>(worker: AnyWorker, options?: WrapOptio
           const id = ++reqId;
           const entry: { resolve: (v: unknown) => void; reject: (e: Error) => void; timer?: ReturnType<typeof setTimeout> } = { resolve, reject };
           if (timeoutMs > 0) {
-            entry.timer = setTimeout(() => {
+            entry.timer = untrackedTimeout(() => {
               if (pending.delete(id)) {
                 reject(new Error(`RPC '${method}' timed out after ${timeoutMs}ms`));
               }

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

@@ -52,7 +52,7 @@ import type {
     GCController
 } from "../telemetry/gc-controller";
 import { createLogger } from "../util/logger";
-import { expose, exposeEvents, type WorkerApi } from "./rpc";
+import { expose, exposeBatchedEvents, type WorkerApi } from "./rpc";
 
 const log = createLogger();
 
@@ -465,7 +465,7 @@ export function createSimWorker(opts: CreateSimWorkerOptions): SimWorkerControl
   // Serializes withLoopStopped critical sections.
   let stopChain: Promise<unknown> = Promise.resolve();
 
-  const events = exposeEvents();
+  const events = exposeBatchedEvents();
 
   // Deterministic RNG — reseedable via control.setSeed(); the stable `rng`
   // closure is what ctx.rng and the Math.random shim draw from.
@@ -750,6 +750,9 @@ export function createSimWorker(opts: CreateSimWorkerOptions): SimWorkerControl
       syncWorker = null; // release sync worker reference
       saveStore = null;
       await opts.onShutdown?.();
+      // Drain any events queued during onShutdown so they aren't lost to
+      // a flush timer the terminating worker never runs.
+      events.flush();
     },
 
     async setSpeed(speed: number): Promise<void> {

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

@@ -121,6 +121,10 @@ export class TaskPool {
       for (let i = 0; i < this.workerCount; i++) {
         const worker = this.createWorker();
         worker.onerror = (e: ErrorEvent) => {
+          // Session teardown tags tracked workers __ddExpectTerminate and
+          // fires synthetic error events to settle waiters — not faults
+          // (see session-tracker.ts terminateTrackedWorker).
+          if ((worker as any).__ddExpectTerminate || this.destroyed) return;
           if (this.onWorkerError) this.onWorkerError(i, e);
           else log.error("task-pool", `Worker ${i} error: ${e.message}`);
         };