@atolljs/core 0.1.6 → 0.1.8

package/dist/pool/dedicatedWorker.d.ts

@@ -0,0 +1,63 @@
+import type { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory.js';
+import type { MemoryPersistence, TaskContract, TaskMap, WorkerPoolConfig } from '../contract/types.js';
+import type { PoolStats, RunOptions } from './workerPool.js';
+/**
+ * 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'>;
+/**
+ * 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 declare 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;
+    private readonly spawn;
+    private readonly respawn;
+    private readonly taskTimeout?;
+    private readonly label?;
+    private worker;
+    private pending;
+    private nextMessageId;
+    private nextCallId;
+    private closed;
+    /** Dashboard fault injection (`pool.chaos`); null unless devtools set it. */
+    private chaos;
+    private devtoolsOff?;
+    private drainWaiters;
+    private statsAgg;
+    constructor(config: DedicatedWorkerConfig<S>);
+    private attach;
+    private detach;
+    private handleReply;
+    private handleError;
+    private rejectPending;
+    /** Abort/timeout: the caller rejects now; the worker's eventual reply is discarded. */
+    private cancel;
+    private checkDrained;
+    /** Post the call straight to the worker — no queue, no scheduler. */
+    dispatch<Args extends any[], Result>(contract: TaskContract<Args, Result>, args: Args, options?: RunOptions): Promise<Result>;
+    runTask<Args extends any[], Result>(contract: TaskContract<Args, Result>, ...args: Args): Promise<Result>;
+    /** The shared buffer handed to the worker via INIT_MEMORY; undefined when message-only. */
+    get sharedBuffer(): SharedArrayBuffer | undefined;
+    /** The worker, as a one-element snapshot (same shape as `WorkerPool.workers`). */
+    get workers(): readonly Worker[];
+    /** Same shape as `WorkerPool.stats()`; `queued` and `waitMs` stay zero (there is no queue). */
+    stats(): PoolStats;
+    /** Resolves once nothing is in flight, then terminates. */
+    close(): Promise<void>;
+    terminate(): void;
+}

package/dist/pool/devtoolsCommands.d.ts

@@ -0,0 +1,54 @@
+import type { PoolStats } from './workerPool.js';
+/** 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 declare const CHAOS_FAILURE = "chaos: injected failure";
+/** Crash message of a dashboard `worker.kill`. */
+export declare 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;
+}
+/** Validate `pool.chaos` args into a config; null when nothing is active (clears). */
+export declare const parseChaos: (args: Record<string, unknown>) => ChaosConfig | null;
+/**
+ * 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 declare const registerDevtoolsRunner: (handle: DevtoolsRunnerHandle) => (() => void);
+/** 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 declare const applyChaos: (chaos: ChaosConfig, call: ChaosCall) => void;

package/dist/pool/subWorkerClient.d.ts

@@ -0,0 +1,50 @@
+import type { SharedSpec } from '../contract/sharedMemory.js';
+import type { WorkerDefinition } from '../worker/defineWorker.js';
+import { type ConnectWorkerConfig, type WorkerClient } from './workerClient.js';
+/**
+ * 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 declare function connectSubWorker<W extends WorkerDefinition, S extends SharedSpec = W extends WorkerDefinition<infer X> ? X : SharedSpec>(config: ConnectSubWorkerConfig<S>): WorkerClient<W, S>;

package/dist/pool/workerChannel.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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.js';
+import type { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory.js';
+import type { MemoryPersistence, TaskMap, WorkerPoolConfig } from '../contract/types.js';
+import { type EmittedDevtoolsEvent } from '../devtools.js';
+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 declare function setupChannelMemory<S extends SharedSpec>(config: WorkerPoolConfig<S, TaskMap>, owner: string): ChannelMemory<S>;
+/**
+ * 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 declare function sendInit<S extends SharedSpec>(worker: Worker, mem: ChannelMemory<S>): 'INIT' | 'INIT_MEMORY';
+/**
+ * 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 declare function forwardWorkerDevtools(runnerId: string, slot: number, ev: EmittedDevtoolsEvent & {
+    poolId?: string;
+}): void;

package/dist/pool/workerClient.d.ts

@@ -2,6 +2,7 @@ import type { ServiceMethod, TaskRunner } from '../service.js';
 import type { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory.js';
 import type { MemoryConfig, Prettify } from '../contract/types.js';
 import { WorkerPool, type RunOptions } from './workerPool.js';
+import { DedicatedWorker } from './dedicatedWorker.js';
 import type { WorkerDefinition, WorkerMethodMap } from '../worker/defineWorker.js';
 /** Maps a worker method's declared type to its async client signature. */
 type Sig<F> = F extends ServiceMethod<infer A extends any[], infer R> ? (...args: A) => Promise<R> : F extends {
@@ -31,16 +32,33 @@ export declare function workerClient<W extends WorkerDefinition>(runner: TaskRun
 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;
@@ -49,13 +67,22 @@ export interface ConnectWorkerConfig<S extends SharedSpec> {
     /** Default true: pool spawns on first method call (or start()). False spawns immediately. */
     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 declare const resolveWorkerCount: (n: number | 'auto' | undefined) => number;
+/** 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;
 };
 /**
@@ -67,12 +94,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.
  */

package/dist/pool/workerPool.d.ts

@@ -42,7 +42,10 @@ declare class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     private pending;
     private nextMessageId;
     private queue;
+    private readonly mem;
     private memoryManager?;
+    /** A caller-supplied buffer shipped via INIT_MEMORY (sub-worker / second-pool sharing). */
+    private injectedBuffer?;
     private workerUrl?;
     private spawn;
     private readonly concurrency;
@@ -50,8 +53,18 @@ declare class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
     private readonly respawn;
     private readonly taskTimeout?;
     private closed;
+    /** Dashboard fault injection (`pool.chaos`); null unless devtools set it. */
+    private chaos;
+    private devtoolsOff?;
     private drainWaiters;
     private statsAgg;
+    /**
+     * 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?;
+    private nextCallId;
     readonly sharedMemory: (SharedMemory<S> & SharedAccess<S>) | undefined;
     /** The attached memory-persistence adapter, if the config supplied one. */
     readonly persistence: MemoryPersistence | undefined;

package/dist/reactive.d.ts

@@ -44,3 +44,18 @@ export declare function reactive<T>(connector: Connector<T>): ReactiveConnector<
  */
 export declare function watch<T>(connector: Connector<T>, onChange: (value: T) => void): () => void;
 export declare function watch<T, S>(connector: Connector<T>, select: (value: T) => S, onChange: (slice: S, previous: S | undefined) => void, options?: SliceOptions<S>): () => void;
+/** 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 declare 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;
+};

package/dist/reactiveGraph.d.ts

@@ -0,0 +1,9 @@
+export type ReactiveKind = 'source' | 'derived' | 'effect' | 'bridge';
+/** The source node for a shared-memory field — emitted once per thread. */
+export declare const graphSource: (path: string | undefined) => string | null;
+/** Create a node; returns its id, or null while devtools is off. */
+export declare const graphNode: (kind: ReactiveKind, label: string, deps: (string | null)[]) => string | null;
+/** Re-emit a node with a new label (same id — the dashboard replaces it). */
+export declare const relabelNode: (id: string | null, label: string) => void;
+/** Mark nodes disposed (null ids are skipped). */
+export declare const disposeNodes: (...ids: (string | null)[]) => void;

package/dist/userTiming.d.ts

@@ -0,0 +1,27 @@
+/**
+ * User Timing bridge: `performance.measure` entries for atoll work, so the
+ * browser's own Performance panel shows tasks next to the app's frames.
+ * Callers gate on `devtoolsEnabled()`; this module never checks it itself.
+ *
+ * `detail.devtools` is Chrome's extensibility payload: entries land on a
+ * custom track inside an 'atoll' track group. Other engines ignore the
+ * detail and record a plain measure.
+ */
+/** Chrome's extensibility palette names. */
+export type TimingColor = 'primary' | 'primary-light' | 'secondary' | 'tertiary' | 'error' | 'warning';
+export interface TimingTrack {
+    /** Track label inside the 'atoll' group, e.g. a pool id. */
+    track: string;
+    color?: TimingColor;
+    properties?: [string, string | number][];
+    tooltipText?: string;
+}
+/**
+ * Record `[start, end]` (performance.now() ms on this thread) as `name`.
+ * The entry is cleared from the timeline buffer right away: the Performance
+ * panel captures it at measure time, and per-task measures would otherwise
+ * grow the buffer without bound (and trip Node's buffer-size warning).
+ */
+export declare const measureAtoll: (name: string, start: number, end: number, t: TimingTrack) => void;
+/** Main-thread span of one call, dispatch → settle, on the runner's track. */
+export declare const measureTaskCall: (runnerId: string, taskId: string, callId: number, slot: number, start: number, end: number, ok: boolean) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolljs/core",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Typed shared-memory worker pools — defineWorker/connectWorker, SharedArrayBuffer contracts, cross-thread reactivity",
   "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
   "type": "module",
@@ -38,6 +38,7 @@
     "stats": "node scripts/bundle-stats.mjs",
     "stats:islands": "node scripts/island-perf.mjs",
     "build:pages": "node scripts/build-pages.mjs",
+    "build:extension": "node packages/devtools-extension/scripts/build.mjs",
     "assemble:pages": "node scripts/assemble-pages.mjs",
     "serve:pages": "node scripts/serve-pages.mjs",
     "serve:static": "node scripts/serve-static.mjs"

package/src/contract/memoryDevtools.ts

@@ -0,0 +1,249 @@
+/**
+ * Dashboard commands over shared memory: `memory.read` (live values) and
+ * watchpoints (`memory.watch` / `memory.unwatch` / `memory.watches`).
+ * Registered by `SharedMemory.bind()` the first time a contract binds
+ * while devtools is enabled, so apps without devtools never load them
+ * into the command table.
+ *
+ * Watchpoints fire `memory:watch-hit` from two places on the thread that
+ * set them (the main thread: commands arrive over its transport):
+ * - the connector write path, synchronously, for writes made on this
+ *   thread (guarded by `memoryWatches.size`, behind the existing
+ *   `devtoolsEnabled()` check: zero cost with no watches);
+ * - a version observer on each watched field, for writes from other
+ *   threads (workers share the buffer, so the main thread reads their
+ *   values). Remote bursts between two observations coalesce: only the
+ *   latest value is checked.
+ */
+import { emitDevtools, previewValue, registerDevtoolsCommand } from '../devtools';
+import type { Connector, SharedMemory } from './sharedMemory';
+
+export type WatchRule = { text: string; test: (value: unknown) => boolean };
+
+interface WatchState {
+  rule: WatchRule;
+  /** Per contract: last version checked and last value preview ('change'). */
+  seen: WeakMap<SharedMemory<any>, { version: number; preview: string }>;
+  stop: () => void;
+  hits: number;
+}
+
+/** path → watch. Read by the write path — keep `.size` the only hot check. */
+export const memoryWatches = new Map<string, WatchState>();
+
+let contractsOf: () => readonly SharedMemory<any>[] = () => [];
+let registered = false;
+
+/* ── value previews ──────────────────────────────────────────────────────── */
+
+const LIST_HEAD = 5;
+const ARRAY_HEAD = 16;
+
+/** Bounded preview of a field's current value — lists/typed arrays read only a head. */
+export const fieldPreview = (connector: Connector<any>): string => {
+  const list = connector as Connector<any> & { readAt?: (i: number) => unknown; recordCount?: number };
+  if (typeof list.readAt === 'function' && typeof list.recordCount === 'number') {
+    const head = Array.from({ length: Math.min(LIST_HEAD, list.recordCount) }, (_, i) => list.readAt!(i));
+    return previewValue({ records: list.recordCount, head }, 1024);
+  }
+  const value = connector.read();
+  if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+    const arr = value as unknown as ArrayLike<number | bigint>;
+    const head = Array.from({ length: Math.min(ARRAY_HEAD, arr.length) }, (_, i) =>
+      typeof arr[i] === 'bigint' ? `${arr[i]}n` : arr[i],
+    );
+    return `${value.constructor.name}(${arr.length}) ${JSON.stringify(head)}${arr.length > ARRAY_HEAD ? '…' : ''}`;
+  }
+  return previewValue(value, 1024);
+};
+
+/** Path lookup without the typed flat-key overload. */
+const conn = (memory: SharedMemory<any>, path: string): Connector<any> =>
+  (memory as unknown as { connector(p: string): Connector<any> }).connector(path);
+
+const versionOf = (connector: Connector<any>): number =>
+  connector._version ? Atomics.load(connector._version.view, connector._version.index) : 0;
+
+/* ── rules ───────────────────────────────────────────────────────────────── */
+
+const parseLiteral = (s: string): unknown => {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return s;
+  }
+};
+
+const asNumber = (v: unknown): number | null =>
+  typeof v === 'number' ? v : typeof v === 'bigint' ? Number(v) : null;
+
+/**
+ * Parse a watch rule: 'change' | '> n' | '< n' | '>= n' | '<= n' | '== v' |
+ * '!= v'. `v` is JSON when it parses ('"down"', 'true', '3'), else a bare
+ * string. Numeric comparisons only match number/bigint fields.
+ */
+export const parseWatchRule = (raw: string): WatchRule => {
+  const text = raw.trim();
+  if (text === 'change') return { text, test: () => true };
+  const m = /^(>=|<=|==|!=|>|<)\s*(.+)$/.exec(text);
+  if (!m) throw new Error(`memory.watch: bad rule '${raw}' — use change, > n, < n, >= n, <= n, == v, != v`);
+  const [, op, operand] = m;
+  if (op === '==' || op === '!=') {
+    const lit = parseLiteral(operand);
+    const eq = (v: unknown) =>
+      v !== null && typeof v === 'object' ? previewValue(v) === previewValue(lit) : Object.is(v, lit) || (typeof v === 'bigint' && Number(v) === lit);
+    return { text, test: op === '==' ? eq : (v) => !eq(v) };
+  }
+  const n = Number(operand);
+  if (!Number.isFinite(n)) throw new Error(`memory.watch: '${operand}' is not a number`);
+  const cmp: Record<string, (a: number) => boolean> = {
+    '>': (a) => a > n, '<': (a) => a < n, '>=': (a) => a >= n, '<=': (a) => a <= n,
+  };
+  return {
+    text,
+    test: (v) => {
+      const a = asNumber(v);
+      return a !== null && cmp[op](a);
+    },
+  };
+};
+
+/* ── matching ────────────────────────────────────────────────────────────── */
+
+const check = (memory: SharedMemory<any>, path: string, w: WatchState, connector: Connector<any>, version: number): void => {
+  const last = w.seen.get(memory);
+  if (last && last.version >= version) return;
+  const change = w.rule.text === 'change';
+  // List fields only support 'change' — read() would decode every record.
+  const isList = typeof (connector as { readAt?: unknown }).readAt === 'function';
+  let value: unknown;
+  let preview: string;
+  try {
+    preview = fieldPreview(connector);
+    value = change || isList ? undefined : connector.read();
+  } catch {
+    return;
+  }
+  w.seen.set(memory, { version, preview });
+  const hit = change ? preview !== last?.preview : !isList && w.rule.test(value);
+  if (!hit) return;
+  w.hits++;
+  emitDevtools({ type: 'memory:watch-hit', path, version, value: preview, rule: w.rule.text });
+};
+
+/** Write-path hook — only called when `memoryWatches.size > 0`. */
+export const checkWatchOnWrite = (memory: SharedMemory<any>, path: string, version: number): void => {
+  const w = memoryWatches.get(path);
+  if (!w) return;
+  check(memory, path, w, conn(memory, path), version);
+};
+
+/**
+ * Observe the field's version counter on this thread so other threads'
+ * writes are checked too. Re-resolves the connector each wake (contracts
+ * can rebind to another buffer) and waits with a timeout so a rebind is
+ * picked up without a write. Falls back to a 50ms poll without waitAsync.
+ */
+const observeRemote = (path: string, w: WatchState): (() => void) => {
+  let stopped = false;
+  const sweep = (): void => {
+    for (const memory of contractsOf()) {
+      if (!memory.bound) continue;
+      let connector: Connector<any>;
+      try {
+        connector = conn(memory, path);
+      } catch {
+        continue;
+      }
+      check(memory, path, w, connector, versionOf(connector));
+    }
+  };
+  if (typeof Atomics.waitAsync === 'function') {
+    void (async () => {
+      while (!stopped) {
+        const first = contractsOf().find((m) => {
+          try {
+            return m.bound && conn(m, path)._version !== undefined;
+          } catch {
+            return false;
+          }
+        });
+        const slot = first ? conn(first, path)._version : undefined;
+        if (slot) {
+          const res = Atomics.waitAsync(slot.view, slot.index, Atomics.load(slot.view, slot.index), 250);
+          if (res.async) await res.value;
+        } else {
+          await new Promise((r) => setTimeout(r, 250));
+        }
+        if (!stopped) sweep();
+      }
+    })();
+    return () => { stopped = true; };
+  }
+  const timer = setInterval(sweep, 50);
+  (timer as unknown as { unref?: () => void }).unref?.();
+  return () => {
+    stopped = true;
+    clearInterval(timer);
+  };
+};
+
+/* ── commands ────────────────────────────────────────────────────────────── */
+
+const watchList = () =>
+  [...memoryWatches.entries()].map(([path, w]) => ({ path, rule: w.rule.text, hits: w.hits }));
+
+/** Register the `memory.*` commands once; `contracts` lists every defined contract. */
+export const ensureMemoryCommands = (contracts: () => readonly SharedMemory<any>[]): void => {
+  contractsOf = contracts;
+  if (registered) return;
+  registered = true;
+
+  registerDevtoolsCommand('memory.read', () => {
+    const out: { path: string; value: string; version: number; contract: number }[] = [];
+    contractsOf().forEach((memory, contract) => {
+      if (!memory.bound) return;
+      for (const { path } of memory.fields()) {
+        try {
+          const connector = conn(memory, path);
+          out.push({ path, value: fieldPreview(connector), version: versionOf(connector), contract });
+        } catch (err) {
+          out.push({ path, value: `[unreadable: ${(err as Error).message}]`, version: -1, contract });
+        }
+      }
+    });
+    return out;
+  });
+
+  registerDevtoolsCommand('memory.watch', (args) => {
+    const path = String(args.path ?? '');
+    if (!path) throw new Error('memory.watch: `path` is required');
+    const known = contractsOf().some((m) => m.fields().some((f) => f.path === path));
+    if (!known) throw new Error(`memory.watch: no contract defines a field '${path}'`);
+    const rule = parseWatchRule(String(args.rule ?? 'change'));
+    memoryWatches.get(path)?.stop();
+    const w: WatchState = { rule, seen: new WeakMap(), stop: () => {}, hits: 0 };
+    // Baseline: the current value/version is not a hit.
+    for (const memory of contractsOf()) {
+      if (!memory.bound) continue;
+      try {
+        const c = conn(memory, path);
+        w.seen.set(memory, { version: versionOf(c), preview: fieldPreview(c) });
+      } catch {
+        /* contract without this field */
+      }
+    }
+    memoryWatches.set(path, w);
+    w.stop = observeRemote(path, w);
+    return watchList();
+  });
+
+  registerDevtoolsCommand('memory.unwatch', (args) => {
+    const path = String(args.path ?? '');
+    memoryWatches.get(path)?.stop();
+    memoryWatches.delete(path);
+    return watchList();
+  });
+
+  registerDevtoolsCommand('memory.watches', () => watchList());
+};