@atolljs/core 0.1.7 → 0.1.9

package/src/pool/workerClient.ts

@@ -2,6 +2,7 @@ import type { ServiceMethod, TaskRunner } from '../service';
 import type { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
 import type { MemoryConfig, Prettify } from '../contract/types';
 import { WorkerPool, type RunOptions } from './workerPool';
+import { DedicatedWorker } from './dedicatedWorker';
 import type {
   WorkerDefinition,
   WorkerMethodMap,
@@ -92,18 +93,33 @@ export function workerClient<W extends WorkerDefinition>(
 export interface ConnectWorkerConfig<S extends SharedSpec> {
   /** Omit for a message-only pool — the SharedArrayBuffer check is skipped. */
   sharedMemory?: SharedMemory<S> & Prettify<SharedAccess<S>>;
+  /**
+   * Ship an existing SharedArrayBuffer to every worker instead of
+   * allocating one — e.g. `sharedBuffer: anotherPool.sharedBuffer`, or a
+   * bound contract's `contract.buffer` inside a worker shell. A thunk is
+   * resolved once at pool construction.
+   */
+  sharedBuffer?: SharedArrayBuffer | (() => SharedArrayBuffer | undefined);
   /**
    * Bundler-detectable factory `() => new Worker(new URL('./x.worker.ts', import.meta.url), { type: 'module' })`,
    * or a URL.
    */
   worker: (() => Worker) | URL;
+  /**
+   * How many workers this client needs. `1` (the default) is a single
+   * dedicated worker with no pool: calls post straight to it, no queue or
+   * scheduler. `N > 1` builds a pool that spreads separate calls across N
+   * workers; `'auto'` sizes it to `navigator.hardwareConcurrency ?? 4`.
+   */
+  workers?: number | 'auto';
+  /** @deprecated Use `workers`. Read only when `workers` is absent. */
   poolSize?: number | 'auto';
   /** Display label for devtools/dashboards — falls back to a generated id. */
   name?: string;
   memory?: MemoryConfig;
-  /** Max in-flight tasks per worker (default 1); excess calls queue FIFO. */
+  /** Pool only: max in-flight tasks per worker (default 1); excess calls queue FIFO. */
   concurrency?: number;
-  /** Max queued calls (default Infinity); a full queue rejects with PoolQueueFullError. */
+  /** Pool only: max queued calls (default Infinity); a full queue rejects with PoolQueueFullError. */
   maxQueue?: number;
   /** Default true — a crashed worker is replaced and its in-flight calls reject. */
   respawn?: boolean;
@@ -113,13 +129,29 @@ export interface ConnectWorkerConfig<S extends SharedSpec> {
   lazy?: boolean;
 }
 
-/** A typed worker client plus pool lifecycle controls. */
+/** What a client runs on: a pool (`workers > 1`) or one dedicated worker. */
+export type WorkerRunner<S extends SharedSpec = SharedSpec> = WorkerPool<S> | DedicatedWorker<S>;
+
+/** Resolve a `workers` count: `'auto'` is one per core (4 when unknown). */
+export const resolveWorkerCount = (n: number | 'auto' | undefined): number =>
+  n === 'auto'
+    ? typeof navigator !== 'undefined'
+      ? (navigator.hardwareConcurrency ?? 4)
+      : 4
+    : Math.max(1, Math.floor(n ?? 1));
+
+/** A typed worker client plus lifecycle controls. */
 export type WorkerClient<W extends WorkerDefinition, S extends SharedSpec> = WorkerMethods<W> & {
-  /** Spawn the pool now (idempotent). */
+  /** Spawn the worker(s) now (idempotent). */
   start(): void;
-  /** Terminate the pool; the next method call re-spawns it. */
+  /** Terminate the worker(s); the next method call re-spawns. */
   terminate(): void;
-  readonly pool: WorkerPool<S> | null;
+  /**
+   * The runner once spawned: a `DedicatedWorker` for `workers: 1`, a
+   * `WorkerPool` otherwise. Both expose `stats()`, `close()`, `terminate()`,
+   * `workers`, `sharedBuffer` and `poolId`.
+   */
+  readonly pool: WorkerRunner<S> | null;
   readonly sharedMemory: ConnectWorkerConfig<S>['sharedMemory'] | undefined;
 };
 
@@ -132,12 +164,15 @@ export type WorkerClient<W extends WorkerDefinition, S extends SharedSpec> = Wor
  *   export const incidents = connectWorker<IncidentsWorker>({
  *     sharedMemory: incidentsMemory,
  *     worker: () => new Worker(new URL('./worker/incidents.worker.ts', import.meta.url), { type: 'module' }),
- *     poolSize: 1,
+ *     workers: 3,                         // omit for one dedicated worker
  *   });
  *
- *   await incidents.queryIncidents(q);   // typed dispatch to the pool
+ *   await incidents.queryIncidents(q);   // typed dispatch
  *   incidents.terminate();               // next call lazily re-spawns
  *
+ * `workers` states what the work needs and the client picks the runner:
+ * 1 (default) → a `DedicatedWorker`, no pool; more → a `WorkerPool`.
+ *
  * Lazy by default: no Worker is touched until the first method call (or
  * `start()`), so importing the client is SSR-safe.
  */
@@ -145,22 +180,33 @@ export function connectWorker<
   W extends WorkerDefinition,
   S extends SharedSpec = W extends WorkerDefinition<infer X> ? X : SharedSpec,
 >(config: ConnectWorkerConfig<S>): WorkerClient<W, S> {
-  let pool: WorkerPool<S> | null = null;
-  const spawn = (): WorkerPool<S> =>
-    (pool ??= new WorkerPool<S>({
+  let pool: WorkerRunner<S> | null = null;
+  const spawn = (): WorkerRunner<S> => {
+    if (pool) return pool;
+    const count = resolveWorkerCount(config.workers ?? config.poolSize);
+    const base = {
       sharedMemory: config.sharedMemory,
+      sharedBuffer: config.sharedBuffer,
       createWorker:
         typeof config.worker === 'function'
           ? config.worker
           : () => new Worker(config.worker as URL, { type: 'module' }),
-      poolSize: config.poolSize,
       name: config.name,
       memory: config.memory,
-      concurrency: config.concurrency,
-      maxQueue: config.maxQueue,
       respawn: config.respawn,
       taskTimeout: config.taskTimeout,
-    }));
+    };
+    pool =
+      count === 1
+        ? new DedicatedWorker<S>(base)
+        : new WorkerPool<S>({
+            ...base,
+            poolSize: count,
+            concurrency: config.concurrency,
+            maxQueue: config.maxQueue,
+          });
+    return pool;
+  };
 
   if (config.lazy === false) spawn();
 

package/src/pool/workerPool.ts

@@ -1,9 +1,12 @@
-import { MemoryManager } from './memory';
+import type { MemoryManager } from './memory';
 import { PoolQueueFullError, TaskAbortedError, TaskTimeoutError, WorkerCrashedError } from './errors';
 import { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
 import { MemoryPersistence, PoolTasks, TaskContract, TaskMap, TaskResult, WorkerPoolConfig } from '../contract/types';
-import { devtoolsEnabled, emitDevtools, forwardDevtools, nextDevtoolsId, type EmittedDevtoolsEvent } from '../devtools';
+import { devtoolsEnabled, emitDevtools, estimateCloneBytes, nextDevtoolsId, type EmittedDevtoolsEvent } from '../devtools';
+import { measureTaskCall } from '../userTiming';
+import { forwardWorkerDevtools, sendInit, setupChannelMemory, type ChannelMemory } from './workerChannel';
 import { fmtBytes, scoped } from '../log';
+import { applyChaos, CHAOS_FAILURE, KILL_MESSAGE, registerDevtoolsRunner, type ChaosConfig } from './devtoolsCommands';
 
 const poolLog = scoped('pool');
 const taskLog = scoped('task');
@@ -86,7 +89,10 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
   private pending = new Map<number, TaskEntry>();
   private nextMessageId = 0;
   private queue: TaskEntry[] = [];
+  private readonly mem: ChannelMemory<S>;
   private memoryManager?: MemoryManager;
+  /** A caller-supplied buffer shipped via INIT_MEMORY (sub-worker / second-pool sharing). */
+  private injectedBuffer?: SharedArrayBuffer;
   private workerUrl?: URL;
   private spawn: () => Worker;
   private readonly concurrency: number;
@@ -94,6 +100,9 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
   private readonly respawn: boolean;
   private readonly taskTimeout?: number;
   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,
@@ -103,8 +112,11 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     waitMs: agg(),
     runMs: agg(),
   };
-  /** Devtools correlation id ('pool-N') — stamped on every event this pool emits. */
-  readonly poolId = nextDevtoolsId('pool');
+  /**
+   * Devtools correlation id, stamped on every event this pool emits:
+   * '<name>-p' when the config has a `name`, else 'pool-N'.
+   */
+  readonly poolId: string;
   private readonly label?: string;
   private nextCallId = 0;
   public readonly sharedMemory: (SharedMemory<S> & SharedAccess<S>) | undefined;
@@ -112,13 +124,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
   public readonly persistence: MemoryPersistence | undefined;
 
   constructor(config: WorkerPoolConfig<S, TaskMap>) {
-    if (config.sharedMemory) {
-      if (typeof SharedArrayBuffer === 'undefined' || (typeof crossOriginIsolated !== 'undefined' && !crossOriginIsolated)) {
-        throw new Error(
-          'WorkerPool requires SharedArrayBuffer in a cross-origin isolated context — serve the page with COOP/COEP headers.'
-        );
-      }
-    }
+    const mem = setupChannelMemory(config, 'WorkerPool');
     if (!config.workerUrl && !config.createWorker) {
       throw new Error('WorkerPool requires either `workerUrl` or `createWorker` in its config.');
     }
@@ -129,23 +135,25 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     this.respawn = config.respawn ?? true;
     this.taskTimeout = config.taskTimeout;
     this.label = config.name;
-
-    if (config.sharedMemory) {
-      this.sharedMemory = config.sharedMemory;
-      this.memoryManager = new MemoryManager(config.memory);
-      this.memoryManager.ensureCapacity(this.sharedMemory.totalBytes);
-      this.sharedMemory.bind(this.memoryManager.getBuffer());
-      this.persistence = config.persistence?.(config.sharedMemory);
-    }
+    this.poolId = nextDevtoolsId('pool', config.name);
+    this.mem = mem;
+    this.sharedMemory = mem.sharedMemory;
+    this.memoryManager = mem.memoryManager;
+    this.injectedBuffer = mem.injectedBuffer;
+    this.persistence = mem.persistence;
 
     const requestedSize = config.poolSize ?? 'auto';
     const poolSize =
-      requestedSize === 'auto' ? (navigator.hardwareConcurrency ?? 4) : requestedSize;
+      requestedSize === 'auto'
+        ? (typeof navigator !== 'undefined' ? navigator.hardwareConcurrency ?? 4 : 4)
+        : requestedSize;
 
     poolLog.info(
       this.sharedMemory
         ? `spawning ${poolSize} worker(s) with ${fmtBytes(this.sharedMemory.totalBytes)} shared buffer`
-        : `spawning ${poolSize} worker(s), message-only`,
+        : this.injectedBuffer
+          ? `spawning ${poolSize} worker(s) with ${fmtBytes(this.injectedBuffer.byteLength)} inherited buffer`
+          : `spawning ${poolSize} worker(s), message-only`,
       { workerUrl: config.workerUrl ? String(config.workerUrl) : 'createWorker()' },
     );
     poolLog.debug(`tip: setLogLevel('trace') for per-task detail`);
@@ -156,12 +164,28 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
       label: this.label,
       poolSize,
       concurrency: this.concurrency,
-      memoryBytes: this.sharedMemory?.totalBytes,
+      memoryBytes: this.sharedMemory?.totalBytes ?? this.injectedBuffer?.byteLength,
     });
 
     for (let i = 0; i < poolSize; i++) {
       this.addWorker(this.spawn());
     }
+    if (devtoolsEnabled()) {
+      this.devtoolsOff = registerDevtoolsRunner({
+        poolId: this.poolId,
+        label: this.label,
+        dedicated: false,
+        size: () => this.slots.length,
+        stats: () => this.stats(),
+        kill: (slot) => {
+          const s = this.slots[slot];
+          if (!s) throw new Error(`${this.poolId} has no worker slot ${slot}`);
+          this.handleWorkerError(s, { message: KILL_MESSAGE });
+        },
+        getChaos: () => this.chaos,
+        setChaos: (chaos) => { this.chaos = chaos; },
+      });
+    }
 
     // Install first-class task methods: pool.queryIncidents(q) →
     // runTask(QueryIncidents, q). Typed through PoolTasks<T> at the
@@ -190,10 +214,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
       // slot produced it so worker-side fetches/heap/memory writes
       // attribute to a specific worker.
       if (data.type === 'ATOLL_DEVTOOLS' && data.event) {
-        forwardDevtools({
-          ...data.event,
-          worker: { poolId: this.poolId, slot: this.slots.indexOf(slot) },
-        });
+        forwardWorkerDevtools(this.poolId, this.slots.indexOf(slot), data.event);
         return;
       }
       this.handleReply(slot, data);
@@ -201,15 +222,9 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     worker.addEventListener('error', (event: unknown) => {
       this.handleWorkerError(slot, event);
     });
-    // `devtools` tells the worker to forward its instrumentation events back
-    // on this channel (ATOLL_DEVTOOLS) — only when a sink is live at spawn.
-    if (this.memoryManager) {
-      worker.postMessage({ type: 'INIT_MEMORY', memory: this.memoryManager.memory, devtools: devtoolsEnabled() });
-    } else {
-      worker.postMessage({ type: 'INIT', devtools: devtoolsEnabled() });
-    }
+    const init = sendInit(worker, this.mem);
     this.slots.push(slot);
-    poolLog.debug(`worker spawned, ${this.memoryManager ? 'INIT_MEMORY' : 'INIT'} sent`);
+    poolLog.debug(`worker spawned, ${init} sent`);
     emitDevtools({ type: 'worker:spawn', poolId: this.poolId, slot: this.slots.indexOf(slot) });
     return slot;
   }
@@ -224,17 +239,24 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     // stats and settlement — the caller was already rejected.
     if (!entry.done) {
       entry.done = true;
-      const runMs = performance.now() - (entry.sentAt ?? entry.enqueuedAt);
+      const start = entry.sentAt ?? entry.enqueuedAt;
+      const runMs = performance.now() - start;
       this.statsAgg.runMs.add(runMs);
       if (data.success) {
         this.statsAgg.completed++;
         taskLog.debug(`← ${entry.contract.taskId} ok`);
-        emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, outcome: 'ok', runMs });
+        if (devtoolsEnabled()) {
+          emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, outcome: 'ok', runMs, resultBytes: estimateCloneBytes(data.result) });
+          measureTaskCall(this.poolId, entry.contract.taskId, entry.callId, this.slots.indexOf(slot), start, start + runMs, true);
+        }
         entry.resolve(data.result);
       } else {
         this.statsAgg.failed++;
         taskLog.warn(`← ${entry.contract.taskId} failed: ${data.error}`);
-        emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, outcome: 'error', runMs, error: data.error });
+        if (devtoolsEnabled()) {
+          emitDevtools({ type: 'task:settle', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, outcome: 'error', runMs, error: data.error });
+          measureTaskCall(this.poolId, entry.contract.taskId, entry.callId, this.slots.indexOf(slot), start, start + runMs, false);
+        }
         entry.reject(new Error(data.error));
       }
     }
@@ -315,13 +337,20 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     this.pending.set(messageId, entry);
     const slotIndex = this.slots.indexOf(slot);
     taskLog.debug(`→ ${entry.contract.taskId}`, { worker: slotIndex, args: entry.args });
-    emitDevtools({ type: 'task:dispatch', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, slot: slotIndex, waitMs });
-    slot.worker.postMessage({
-      type: 'EXECUTE_TASK',
-      messageId,
-      taskId: entry.contract.taskId,
-      args: entry.args,
-    });
+    if (devtoolsEnabled()) {
+      emitDevtools({ type: 'task:dispatch', poolId: this.poolId, callId: entry.callId, taskId: entry.contract.taskId, slot: slotIndex, waitMs, argBytes: estimateCloneBytes(entry.args) });
+    }
+    const msg = { type: 'EXECUTE_TASK', messageId, taskId: entry.contract.taskId, args: entry.args };
+    if (this.chaos) {
+      applyChaos(this.chaos, {
+        live: () => this.pending.get(messageId) === entry,
+        fail: () => this.handleReply(slot, { messageId, taskId: msg.taskId, success: false, error: CHAOS_FAILURE }),
+        timeout: () => this.cancel(entry, new TaskTimeoutError()),
+        post: () => slot.worker.postMessage(msg),
+      });
+    } else {
+      slot.worker.postMessage(msg);
+    }
   }
 
   /** Detaches signal/timeout listeners from a finalized entry. */
@@ -422,7 +451,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
    * (e.g. a second pool of HTTP workers via withSharedBuffer).
    */
   public get sharedBuffer(): SharedArrayBuffer | undefined {
-    return this.memoryManager?.getBuffer();
+    return this.memoryManager?.getBuffer() ?? this.injectedBuffer;
   }
 
   /**
@@ -466,6 +495,7 @@ class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
 
   public terminate(): void {
     this.closed = true;
+    this.devtoolsOff?.();
     // Final flush + release — fire-and-forget; terminate() stays synchronous.
     void this.persistence?.stop()?.catch?.((e: unknown) =>
       poolLog.warn('memory persistence stop failed', e),

package/src/reactive.ts

@@ -1,6 +1,7 @@
 import { createEffect, createMemo, createRenderEffect, createRoot, createSignal } from 'solid-js';
 import { Connector } from './contract/sharedMemory';
 import { scoped } from './log';
+import { disposeNodes, graphNode, graphSource } from './reactiveGraph';
 
 const reactiveLog = scoped('reactive');
 
@@ -45,11 +46,39 @@ export interface ReactiveConnector<T> {
  * write — local or remote, both bump it. waitAsync when available, 50ms poll
  * otherwise. No solid-js involved: this is the whole remote-write mechanism.
  */
-const watchVersion = <T>(connector: Connector<T>, onBump: () => void): (() => void) => {
+interface VersionWatch {
+  stop: () => void;
+  /** Devtools graph id of the bridge node (null while devtools is off). */
+  node: string | null;
+}
+
+const watchVersionNode = <T>(connector: Connector<T>, onBump: () => void): VersionWatch => {
   const version = connector._version;
   if (!version) {
     throw new Error('This connector does not support remote observation.');
   }
+  const waits = typeof Atomics.waitAsync === 'function';
+  const node = graphNode('bridge', `${waits ? 'waitAsync' : 'poll'} ${connector._path ?? `@${connector.byteOffset}`}`, [
+    graphSource(connector._path),
+  ]);
+  const stop = watchVersionRaw(connector, version, onBump);
+  return {
+    node,
+    stop: () => {
+      stop();
+      disposeNodes(node);
+    },
+  };
+};
+
+const watchVersion = <T>(connector: Connector<T>, onBump: () => void): (() => void) =>
+  watchVersionNode(connector, onBump).stop;
+
+const watchVersionRaw = <T>(
+  connector: Connector<T>,
+  version: { view: Int32Array; index: number },
+  onBump: () => void,
+): (() => void) => {
   let stopped = false;
   let last = Atomics.load(version.view, version.index);
 
@@ -167,6 +196,39 @@ export function watch<T, S = T>(
 ): () => void {
   const select = onChange ? (selOrCb as (value: T) => S) : ((v: T) => v as unknown as S);
   const cb = (onChange ?? selOrCb) as (slice: S, previous: S | undefined) => void;
+  return watchNodes(connector, select, cb, options, { sliced: onChange !== undefined, label: 'watch' }).stop;
+}
+
+/** Graph labelling for {@link watchNodes} — `observe()` names its effect. */
+export interface WatchMeta {
+  /** A real selector was given (draws a derived node), not the identity. */
+  sliced: boolean;
+  /** Effect node label prefix: 'watch', 'observe'. */
+  label: string;
+}
+
+/**
+ * `watch()` plus its devtools graph wiring: bridge → [derived slice] →
+ * effect. Internal: `observe()` uses it to own the effect node's label.
+ */
+export function watchNodes<T, S>(
+  connector: Connector<T>,
+  select: (value: T) => S,
+  cb: (slice: S, previous: S | undefined) => void,
+  options: SliceOptions<S> | undefined,
+  meta: WatchMeta,
+): { stop: () => void; effect: string | null } {
+  const path = connector._path ?? `@${connector.byteOffset}`;
+  // Nodes are created around the version watch below; ids are null while
+  // devtools is off, and every graph call no-ops on null.
+  let bridge: string | null = null;
+  let derived: string | null = null;
+  let effect: string | null = null;
+  const graph = (): void => {
+    derived = meta.sliced ? graphNode('derived', `select(${path})`, [bridge]) : null;
+    effect = graphNode('effect', `${meta.label}(${path})`, [derived ?? bridge]);
+  };
+  const ungraph = (): void => disposeNodes(effect, derived);
 
   // SSR solid build (node/worker conditions): effects never re-run, so the
   // signal pipeline below would silently never emit. Same semantics, driven
@@ -184,20 +246,29 @@ export function watch<T, S = T>(
       cb(s, old);
     };
     emit();
-    const stop = watchVersion(connector, emit);
+    const remote = watchVersionNode(connector, emit);
+    bridge = remote.node;
+    graph();
     reactiveLog.debug(`watching connector at offset ${connector.byteOffset} (direct)`);
-    return () => {
-      reactiveLog.debug(`watch stopped (offset ${connector.byteOffset})`);
-      stop();
+    return {
+      effect,
+      stop: () => {
+        reactiveLog.debug(`watch stopped (offset ${connector.byteOffset})`);
+        remote.stop();
+        ungraph();
+      },
     };
   }
 
-  const sig = reactive(connector);
-  const stopRemote = sig.observeRemote();
+  // reactive(connector) + observeRemote(), inlined to keep the bridge id.
+  const [value, setValue] = createSignal<T>(connector.read(), { equals: false });
+  const remote = watchVersionNode(connector, () => setValue(() => connector.read()));
+  bridge = remote.node;
+  graph();
   const dispose = createRoot((d) => {
     const slice = createMemo(
       () => {
-        const v = sig.get() as T | null | undefined;
+        const v = value() as T | null | undefined;
         return v == null ? undefined : select(v);
       },
       undefined,
@@ -218,9 +289,13 @@ export function watch<T, S = T>(
     return d;
   });
   reactiveLog.debug(`watching connector at offset ${connector.byteOffset}`);
-  return () => {
-    reactiveLog.debug(`watch stopped (offset ${connector.byteOffset})`);
-    stopRemote();
-    dispose();
+  return {
+    effect,
+    stop: () => {
+      reactiveLog.debug(`watch stopped (offset ${connector.byteOffset})`);
+      remote.stop();
+      dispose();
+      ungraph();
+    },
   };
 }

package/src/reactiveGraph.ts

@@ -0,0 +1,91 @@
+/**
+ * `reactive:node` emission for the dashboard's reactivity graph. The SDK's
+ * reactivity is shallow, and the node kinds map onto it directly:
+ *
+ * - **source**: a shared-memory field, id `mem:<path>`, owner 'shared'.
+ *   The same id on every thread, so a worker-side writer and a main-thread
+ *   watcher meet at one node. Two contracts with the same field path
+ *   share the node (ids carry no contract identity across threads).
+ * - **bridge**: a version-counter watcher (`Atomics.waitAsync`, or the
+ *   50ms poll fallback): the only thing that crosses threads.
+ * - **derived**: a `watch`/`observe` selector slice.
+ * - **effect**: a `watch` callback, or an `observe` observable's
+ *   subscriber fan-out (label carries the subscriber count).
+ *
+ * Non-source ids are per-thread counters ('b3', 'e7'); the dashboard
+ * qualifies them by the event's thread/worker stamp. Everything here is
+ * a no-op returning null while devtools is off.
+ */
+import { devtoolsEnabled, emitDevtools, registerDevtoolsCommand } from './devtools';
+
+export type ReactiveKind = 'source' | 'derived' | 'effect' | 'bridge';
+
+interface NodeInfo {
+  id: string;
+  kind: ReactiveKind;
+  label?: string;
+  deps?: string[];
+  owner?: string;
+}
+
+const OWNER =
+  typeof WorkerGlobalScope !== 'undefined' && self instanceof WorkerGlobalScope ? 'worker' : 'main';
+
+let seq = 0;
+const live = new Map<string, NodeInfo>();
+let commandRegistered = false;
+
+const emit = (node: NodeInfo, disposed?: boolean): void => {
+  emitDevtools({ type: 'reactive:node', ...node, ...(disposed ? { disposed: true } : {}) });
+};
+
+const ensureCommand = (): void => {
+  if (commandRegistered) return;
+  commandRegistered = true;
+  // Snapshot for dashboards that joined after the creation events scrolled
+  // out of the replay tail. This thread's nodes only (commands run on the
+  // main thread; worker nodes arrive through the event stream).
+  registerDevtoolsCommand('reactive.nodes', () => [...live.values()]);
+};
+
+/** The source node for a shared-memory field — emitted once per thread. */
+export const graphSource = (path: string | undefined): string | null => {
+  if (!devtoolsEnabled() || path === undefined) return null;
+  ensureCommand();
+  const id = `mem:${path}`;
+  if (!live.has(id)) {
+    const node: NodeInfo = { id, kind: 'source', label: path, owner: 'shared' };
+    live.set(id, node);
+    emit(node);
+  }
+  return id;
+};
+
+/** Create a node; returns its id, or null while devtools is off. */
+export const graphNode = (kind: ReactiveKind, label: string, deps: (string | null)[]): string | null => {
+  if (!devtoolsEnabled()) return null;
+  ensureCommand();
+  const id = `${kind[0]}${++seq}`;
+  const node: NodeInfo = { id, kind, label, deps: deps.filter((d): d is string => d !== null), owner: OWNER };
+  live.set(id, node);
+  emit(node);
+  return id;
+};
+
+/** Re-emit a node with a new label (same id — the dashboard replaces it). */
+export const relabelNode = (id: string | null, label: string): void => {
+  const node = id === null ? undefined : live.get(id);
+  if (!node || node.label === label || !devtoolsEnabled()) return;
+  node.label = label;
+  emit(node);
+};
+
+/** Mark nodes disposed (null ids are skipped). */
+export const disposeNodes = (...ids: (string | null)[]): void => {
+  for (const id of ids) {
+    const node = id === null ? undefined : live.get(id);
+    if (!node) continue;
+    live.delete(id!);
+    if (devtoolsEnabled()) emit(node, true);
+  }
+};

package/src/testing/inProcessWorker.ts

@@ -72,9 +72,10 @@ export class InProcessWorker {
       return;
     }
     if (data.type === 'INIT_MEMORY') {
-      this.ready ??= this.boot().then(() =>
-        bindSharedMemories((data.memory as WebAssembly.Memory).buffer as unknown as SharedArrayBuffer),
-      );
+      const buffer = (data.memory as WebAssembly.Memory | undefined)?.buffer ?? data.buffer;
+      this.ready ??= this.boot().then(() => {
+        if (buffer) bindSharedMemories(buffer as SharedArrayBuffer);
+      });
       try {
         await this.ready;
       } catch (err) {