@atolljs/core 0.1.6 → 0.1.8

package/src/contract/sharedMemory.ts

@@ -1,6 +1,8 @@
 import type { Prettify, Schema } from './types';
 import { msgpackrCodec } from './msgpackrCodec';
 import { memberToSpec, zodArrayInfo, zodObjectShape, zodStringBytes } from './listSchema';
+import { devtoolsEnabled, emitDevtools } from '../devtools';
+import { checkWatchOnWrite, ensureMemoryCommands, memoryWatches } from './memoryDevtools';
 import { fmtBytes, scoped } from '../log';
 import { z, fluent } from './zod';
 
@@ -101,6 +103,8 @@ export interface ConnectorContext {
   codec: Codec;
   /** Slot in the shared version counter — bump + notify on granular writes. */
   version?: { view: Int32Array; index: number };
+  /** The field's contract path — for devtools write events on granular commits. */
+  path?: string;
 }
 
 /**
@@ -141,6 +145,8 @@ export interface Connector<T> {
   write(value: T): void;
   /** Internal: slot in the shared version counter block, bumped on every write. */
   readonly _version?: { view: Int32Array; index: number };
+  /** Internal: the field's contract path — devtools node labels. */
+  readonly _path?: string;
 }
 
 /* ------------------------------------------------------------------ */
@@ -670,10 +676,13 @@ function listFactory(d: FieldDescriptor, ctx: ConnectorContext, byteOffset: numb
     writeAt: writeAt as ListConnector<any>['writeAt'],
     commit: () => {
       if (ctx.version) {
-        Atomics.add(ctx.version.view, ctx.version.index, 1);
+        const prev = Atomics.add(ctx.version.view, ctx.version.index, 1);
         // Wake EVERY waitAsync observer — several watchers may share this
         // field's counter; a bounded notify starves all but one.
         Atomics.notify(ctx.version.view, ctx.version.index);
+        if (ctx.path && devtoolsEnabled()) {
+          emitDevtools({ type: 'memory:write', path: ctx.path, version: prev + 1 });
+        }
       }
     },
     read: () => Array.from({ length: count }, (_, i) => readAt(i)),
@@ -803,8 +812,9 @@ export class SharedMemory<S extends SharedSpec = SharedSpec> {
         throw new Error(`Unknown shared memory field kind: ${descriptor.kind}`);
       }
       memLog.debug(`bind "${path}" (${descriptor.kind}, ${fmtBytes(descriptor.byteLength)}) via ${this.plugins?.[descriptor.kind] ? 'plugin' : 'built-in'} factory`);
-      const ctx: ConnectorContext = { buffer, codec: this.codec, version: { view: versionView, index } };
+      const ctx: ConnectorContext = { buffer, codec: this.codec, version: { view: versionView, index }, path };
       const raw = factory(descriptor, ctx, this.offsets.get(path)!);
+      const commit = (raw as Partial<ListConnector<unknown>>).commit;
       this.connectors.set(path, {
         ...raw,
         write: (v) => {
@@ -812,12 +822,35 @@ export class SharedMemory<S extends SharedSpec = SharedSpec> {
           // Bump the version counter and explicitly wake waitAsync observers —
           // V8 only resolves waitAsync waiters on notify, not on value changes.
           // No count bound: every watcher on this field must wake.
-          Atomics.add(versionView, index, 1);
+          const prev = Atomics.add(versionView, index, 1);
           Atomics.notify(versionView, index);
+          if (devtoolsEnabled()) {
+            emitDevtools({ type: 'memory:write', path, version: prev + 1 });
+            if (memoryWatches.size) checkWatchOnWrite(this, path, prev + 1);
+          }
         },
+        // List commits bump inside the factory — wrapped for watchpoints only
+        // when devtools is on at bind time, so the plain path stays direct.
+        ...(commit && devtoolsEnabled()
+          ? {
+              commit: () => {
+                commit();
+                if (memoryWatches.size) checkWatchOnWrite(this, path, Atomics.load(versionView, index));
+              },
+            }
+          : {}),
         _version: { view: versionView, index },
+        _path: path,
       });
     });
+    if (devtoolsEnabled()) {
+      ensureMemoryCommands(() => definedSharedMemories);
+      emitDevtools({
+        type: 'memory:bind',
+        fields: this.entries.map((e, i) => [i, e.path]),
+        totalBytes: this.totalBytes,
+      });
+    }
     this.isBound = true;
     this.boundBuffer = buffer;
     for (const cb of [...this.boundListeners]) cb();
@@ -854,15 +887,12 @@ export class SharedMemory<S extends SharedSpec = SharedSpec> {
   }
 
   /**
-   * Fires when the contract is bound on this thread — immediately if already
-   * bound. Returns an unsubscribe function.
+   * Fires when the contract is bound on this thread — on every bind, and
+   * immediately if already bound. Returns an unsubscribe function.
    */
   public onBound(cb: () => void): () => void {
-    if (this.isBound) {
-      cb();
-      return () => {};
-    }
     this.boundListeners.add(cb);
+    if (this.isBound) cb();
     return () => this.boundListeners.delete(cb);
   }
 

package/src/contract/types.ts

@@ -57,6 +57,17 @@ export interface WorkerPoolConfig<S extends SharedSpec = SharedSpec, T extends T
    * skipped and workers receive a plain `{ type: 'INIT' }` handshake.
    */
   sharedMemory?: SharedMemory<S> & Prettify<SharedAccess<S>>;
+  /**
+   * Hand an existing SharedArrayBuffer to every spawned worker instead of
+   * allocating a fresh `WebAssembly.Memory` — the worker-shell case: a worker
+   * already bound to a contract spawns sub-workers on the SAME buffer
+   * (`sharedBuffer: contract.buffer`), or a second pool shares the first
+   * pool's `pool.sharedBuffer`. A thunk is resolved once, when the pool
+   * constructs. With `sharedMemory` the contract binds locally to this
+   * buffer; without it the buffer still ships via INIT_MEMORY and the
+   * workers bind their own defined contracts.
+   */
+  sharedBuffer?: SharedArrayBuffer | (() => SharedArrayBuffer | undefined);
   /**
    * Persistence adapter for `sharedMemory` — invoked with the contract right
    * after the pool binds it, and its `stop()` runs on `terminate()`.
@@ -65,6 +76,8 @@ export interface WorkerPoolConfig<S extends SharedSpec = SharedSpec, T extends T
   persistence?: (memory: SharedMemory<S>) => MemoryPersistence | undefined;
   /** Worker count — a number, or 'auto' (the default) for navigator.hardwareConcurrency ?? 4. */
   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 tasks queue FIFO. */
   concurrency?: number;