@atolljs/core 0.1.0

package/src/reactive.ts

@@ -0,0 +1,161 @@
+import { createEffect, createMemo, createRoot, createSignal } from 'solid-js';
+import { Connector } from './contract/sharedMemory';
+import { scoped } from './log';
+
+const reactiveLog = scoped('reactive');
+
+/** Emission control for slices — return `true` when `next` should be treated
+ *  as unchanged (no emit). Defaults to `Object.is`. */
+export type EqualityFn<T> = (prev: T, next: T) => boolean;
+
+export interface SliceOptions<S> {
+  /** Distinct comparator for the selected slice: `true` = unchanged. */
+  equals?: EqualityFn<S>;
+}
+
+/** Reference-equality object comparator — emits when any own property value
+ *  changes. Handy for object slices: `{ equals: shallowEqual }`. */
+export function shallowEqual<T extends object>(prev: T | undefined, next: T | undefined): boolean {
+  if (prev === next) return true;
+  if (prev == null || next == null) return false;
+  const a = Object.keys(prev) as (keyof T)[];
+  const b = Object.keys(next) as (keyof T)[];
+  return a.length === b.length && a.every((k) => Object.is(prev[k], next[k]));
+}
+
+/**
+ * A reactive view over a shared memory connector. `get()` is signal-tracked,
+ * so Solid effects and memos re-run when the field changes. `set()` writes
+ * through the connector and notifies subscribers on this thread.
+ */
+export interface ReactiveConnector<T> {
+  get(): T;
+  set(value: T): void;
+  peek(): T;
+  /**
+   * Start observing writes made by the other thread (via the shared version
+   * counter). Returns a function to stop observing. Local writes already
+   * notify through `set()`, so this is only needed for remote changes.
+   */
+  observeRemote(): () => void;
+}
+
+export function reactive<T>(connector: Connector<T>): ReactiveConnector<T> {
+  const [value, setValue] = createSignal<T>(connector.read(), { equals: false });
+  const bump = () => setValue(() => connector.read());
+
+  return {
+    get: value,
+    peek: () => connector.read(),
+    set: (v) => {
+      connector.write(v);
+      bump();
+    },
+    observeRemote: () => {
+      const version = connector._version;
+      if (!version) {
+        throw new Error('This connector does not support remote observation.');
+      }
+      let stopped = false;
+      let last = Atomics.load(version.view, version.index);
+
+      if (typeof Atomics.waitAsync === 'function') {
+        reactiveLog.debug(`observing remote writes (offset ${connector.byteOffset}, waitAsync)`);
+        void (async () => {
+          while (!stopped) {
+            const result = Atomics.waitAsync(version.view, version.index, last);
+            if (result.async) {
+              await result.value;
+            }
+            last = Atomics.load(version.view, version.index);
+            if (!stopped) {
+              reactiveLog.trace(`remote write observed (offset ${connector.byteOffset})`);
+              bump();
+            }
+          }
+          reactiveLog.debug(`stopped observing (offset ${connector.byteOffset})`);
+        })();
+        return () => { stopped = true; };
+      }
+
+      // Fallback for environments without Atomics.waitAsync
+      reactiveLog.warn(`Atomics.waitAsync unavailable — observing via 50ms poll (offset ${connector.byteOffset})`);
+      const timer = setInterval(() => {
+        const current = Atomics.load(version.view, version.index);
+        if (current !== last) {
+          last = current;
+          bump();
+        }
+      }, 50);
+      return () => {
+        stopped = true;
+        clearInterval(timer);
+      };
+    },
+  };
+}
+
+/**
+ * Observe a shared-memory field and invoke `onChange` with its value on
+ * every write — local or remote (both bump the shared version counter).
+ * Fires once immediately with the current value unless the field has never
+ * been written (structured fields read `undefined` until then).
+ *
+ * Pass a selector to watch a slice: `watch(conn, m => m.critical, cb)` —
+ * the selected value is memoized, so the callback only runs when the slice
+ * itself changes, not on every field write. Slice equality defaults to
+ * `Object.is`; pass `options.equals` to decide what emits — e.g.
+ * `{ equals: shallowEqual }` for object slices, or a custom comparator like
+ * `(a, b) => Math.abs(a - b) < 0.01` to mute noise.
+ *
+ * Returns an unsubscribe function. Requires the contract to be bound on
+ * this thread (the pool binds it on construction).
+ */
+export function watch<T>(connector: Connector<T>, onChange: (value: T) => void): () => void;
+export function watch<T, S>(
+  connector: Connector<T>,
+  select: (value: T) => S,
+  onChange: (slice: S, previous: S | undefined) => void,
+  options?: SliceOptions<S>
+): () => void;
+export function watch<T, S = T>(
+  connector: Connector<T>,
+  selOrCb: ((value: T) => S) | ((slice: S, previous: S | undefined) => void),
+  onChange?: (slice: S, previous: S | undefined) => void,
+  options?: SliceOptions<S>
+): () => 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;
+
+  const sig = reactive(connector);
+  const stopRemote = sig.observeRemote();
+  const dispose = createRoot((d) => {
+    const slice = createMemo(
+      () => {
+        const v = sig.get() as T | null | undefined;
+        return v == null ? undefined : select(v);
+      },
+      undefined,
+      options?.equals
+        ? {
+            // The memo starts at `undefined` — guard so user comparators only
+            // ever see real slice values.
+            equals: (a: S | undefined, b: S | undefined) =>
+              a === undefined || b === undefined ? a === b : options.equals!(a, b),
+          }
+        : undefined
+    );
+    createEffect((prev: S | undefined) => {
+      const s = slice();
+      if (s !== undefined) cb(s, prev);
+      return s;
+    });
+    return d;
+  });
+  reactiveLog.debug(`watching connector at offset ${connector.byteOffset}`);
+  return () => {
+    reactiveLog.debug(`watch stopped (offset ${connector.byteOffset})`);
+    stopRemote();
+    dispose();
+  };
+}

package/src/service.ts

@@ -0,0 +1,283 @@
+// Framework-neutral RPC layer. A service contract is declared ONCE and
+// imported by both threads: the worker binds handlers via implementService
+// (higher-order functions, no decorators), and the main thread dispatches
+// through createClient or by passing service.tasks straight into a
+// WorkerPool/SharedWorker config. Method names and wire ids can never drift
+// because every surface derives from the same object.
+import type { Schema, TaskContract, ViewType } from './contract/types';
+import { scoped } from './log';
+import { TaskRegistry } from './worker/registry';
+
+const svcLog = scoped('service');
+
+/**
+ * One RPC method's declaration. Identical fields to {@link TaskContract}
+ * except `taskId` is optional — when omitted the wire id is derived as
+ * `${serviceName}.${methodName}` so it can't drift between threads.
+ *
+ * Most methods need no wrapper — write the object inline and defineService
+ * infers Args/Result from the schemas:
+ *
+ *   seedIncidents: { resultSchema: z.number() },          // → () => number
+ *   queryIncidents: { argsSchema, resultSchema },          // → (q) => Result
+ *
+ * Use {@link rpc} only to declare types a method's schemas can't carry —
+ * e.g. typed args with no validation: `rpc<[QueryArgs], QueryResult>()`.
+ */
+export interface RpcMethodDef<Args extends any[] = any[], Result = any> {
+  /** Explicit wire id — only needed to interop with pre-existing taskIds. */
+  taskId?: string;
+  /** Element datatype of the shared-memory region this method operates on. */
+  dataType?: ViewType;
+  /** Validates args as they cross the thread boundary. */
+  argsSchema?: Schema<Args>;
+  /** Validates the handler's return value. */
+  resultSchema?: Schema<Result>;
+}
+
+/**
+ * Explicit type carrier for method declarations — an identity function.
+ * Needed only when schemas are absent or don't express the full signature;
+ * schema-typed methods infer automatically inside defineService.
+ */
+export function rpc<Args extends any[] = any[], Result = any>(
+  def: RpcMethodDef<Args, Result> = {},
+): RpcMethodDef<Args, Result> {
+  return def;
+}
+
+/**
+ * One method's whole unit — the pattern for one-file-per-task modules. The
+ * file's top-level export satisfies this interface: `def` is the wire
+ * declaration {@link defineService} composes, `run` is the worker-side
+ * implementation {@link implementService} registers. Both entry points
+ * accept the unit directly and unwrap the part they need:
+ *
+ *   // service/seedIncidents.ts — one file, the whole stack
+ *   export const seedIncidents = {
+ *     def: { resultSchema: z.number() },
+ *     run() { …; return ms; },
+ *   } satisfies ServiceMethod<[], number>;
+ */
+export interface ServiceMethod<Args extends any[] = any[], Result = any> {
+  /** The wire declaration fed into {@link defineService}. */
+  def: RpcMethodDef<Args, Result>;
+  /** The worker-side implementation fed into {@link implementService}. */
+  run(...args: Args): Result | Promise<Result>;
+}
+
+/** The args a method def declares — argsSchema's tuple, else an rpc<A,R>() declaration's type args, else []. */
+type DefArgs<D> =
+  D extends { argsSchema: Schema<infer A extends any[]> }
+    ? A
+    : D extends { resultSchema: Schema<any> }
+      ? []
+      : D extends RpcMethodDef<infer A extends any[], any>
+        ? A
+        : [];
+
+/** The result a method def declares — resultSchema's output, else an rpc<A,R>() declaration's type args, else unknown. */
+type DefResult<D> =
+  D extends { resultSchema: Schema<infer R> }
+    ? R
+    : D extends RpcMethodDef<any[], infer R>
+      ? R
+      : unknown;
+
+/**
+ * Builds a {@link ServiceMethod} unit — the factory form of
+ * `{ def, run } satisfies ServiceMethod<…>`. The def's schemas (or an
+ * `rpc<A,R>()` declaration's type args) supply the signature, so `run`
+ * gets contextual parameter types with nothing to annotate:
+ *
+ *   export const queryIncidents = serviceMethod({
+ *     def: { argsSchema: z.tuple([queryArgsSchema]), resultSchema: queryResultSchema },
+ *     run(q) { … },                     // q: QueryArgs — inferred
+ *   });
+ *
+ * The unit's exact type is returned unchanged, so extra fields (config,
+ * counters) ride along for implementService's `this`-binding — `run`'s
+ * `this` is the unit; annotate it to type extra fields:
+ * `run(this: { prefix: string }, name) { … }`.
+ */
+export function serviceMethod<
+  D extends RpcMethodDef,
+  U extends { def: D },
+>(
+  unit: U & {
+    run: (...args: DefArgs<D>) => DefResult<D> | Promise<DefResult<D>>;
+  },
+): U {
+  return unit;
+}
+
+/** A service method entry: a bare RpcMethodDef or a full {@link ServiceMethod} unit. */
+export type RpcMethodInput = RpcMethodDef<any[], any> | ServiceMethod<any[], any>;
+export type RpcMethodMap = Record<string, RpcMethodDef<any[], any>>;
+export type RpcMethodInputMap = Record<string, RpcMethodInput>;
+
+/**
+ * Resolves a method declaration to its TaskContract type. Schemas win when
+ * present (argsSchema+resultSchema → full signature; resultSchema alone →
+ * a no-arg method); an rpc<A,R>() declaration's type args carry the rest.
+ */
+type MethodContract<D> =
+  D extends { def: infer Def }
+    ? MethodContract<Def>   // ServiceMethod unit — unwrap the def
+    : D extends { argsSchema: Schema<infer A extends any[]> }
+    ? D extends { resultSchema: Schema<infer R> }
+      ? TaskContract<A, R>
+      : TaskContract<A, any>
+    : D extends { resultSchema: Schema<infer R> }
+      ? TaskContract<[], R>
+      : D extends RpcMethodDef<infer A extends any[], infer R>
+        ? TaskContract<A, R>
+        : TaskContract<any[], any>;
+
+type MethodsToContracts<M extends RpcMethodInputMap> = {
+  [K in keyof M]: MethodContract<M[K]>;
+};
+
+/**
+ * A named bundle of RPC method contracts shared by both threads. `tasks` is
+ * a fully-typed {@link TaskMap} — hand it to `WorkerPool`/`SharedWorker`
+ * config or iterate it for registration.
+ */
+export interface ServiceContract<M extends RpcMethodInputMap = RpcMethodInputMap> {
+  readonly name: string;
+  readonly tasks: MethodsToContracts<M>;
+}
+
+/**
+ * Declares a worker service's RPC surface. The same object is imported by
+ * the worker entry (for `implementService`) and the main thread (for
+ * `createClient` / pool config):
+ *
+ *   export const incidentsService = defineService('incidents', {
+ *     seedIncidents: { resultSchema: z.number() },
+ *     queryIncidents: {
+ *       argsSchema: z.tuple([queryArgsSchema]),
+ *       resultSchema: queryResultSchema,
+ *     },
+ *   });
+ */
+export function defineService<M extends RpcMethodInputMap>(
+  name: string,
+  methods: M,
+): ServiceContract<M> {
+  const tasks = {} as Record<string, TaskContract>;
+  for (const [method, input] of Object.entries(methods)) {
+    const def = 'def' in input ? input.def : input;
+    tasks[method] = {
+      taskId: def.taskId ?? `${name}.${method}`,
+      ...(def.dataType ? { dataType: def.dataType } : {}),
+      ...(def.argsSchema ? { argsSchema: def.argsSchema } : {}),
+      ...(def.resultSchema ? { resultSchema: def.resultSchema } : {}),
+    };
+  }
+  return { name, tasks: tasks as MethodsToContracts<M> };
+}
+
+type ServiceHandlerFn<A extends any[], R> = (...args: A) => R | Promise<R>;
+
+/** The handler signatures a service implementation must provide. */
+export type ServiceHandlers<M extends RpcMethodInputMap> = {
+  [K in keyof M]: MethodContract<M[K]> extends TaskContract<infer A, infer R>
+    ? ServiceHandlerFn<A, R> | { run: ServiceHandlerFn<A, R> }
+    : never;
+};
+
+/**
+ * A service contract bound to handler implementations — the worker-side
+ * "service" that owns the RPC methods. Registration happens eagerly inside
+ * {@link implementService}; the returned handle is for composition/testing.
+ */
+export interface ServiceImpl<M extends RpcMethodInputMap = RpcMethodInputMap> {
+  readonly service: ServiceContract<M>;
+  readonly handlers: ServiceHandlers<M>;
+}
+
+/**
+ * Binds a service contract to handler functions and registers every method
+ * with the {@link TaskRegistry} — the worker-side half of the contract:
+ *
+ *   export const incidentsImpl = implementService(incidentsService, {
+ *     seedIncidents: () => { …; return ms; },
+ *     queryIncidents: (q) => { …; return page; },
+ *   });
+ *
+ * Missing methods throw at bind time (a silent omission would surface as a
+ * runtime "handler not found" on the far thread). Handlers are invoked with
+ * `this` bound to the handlers object, so methods may call siblings via
+ * `this`. When `handlers` is a class instance (e.g. a DI-resolved provider
+ * whose methods match the service surface), binding preserves its `this`.
+ */
+export function implementService<M extends RpcMethodInputMap>(
+  service: ServiceContract<M>,
+  handlers: ServiceHandlers<M>,
+): ServiceImpl<M> {
+  const missing = Object.keys(service.tasks).filter((k) => {
+    const h = handlers[k] as unknown;
+    return typeof h !== 'function' && typeof (h as { run?: unknown })?.run !== 'function';
+  });
+  if (missing.length > 0) {
+    throw new Error(
+      `implementService("${service.name}"): missing handlers for ${missing.join(', ')}`,
+    );
+  }
+  for (const [method, contract] of Object.entries(service.tasks)) {
+    const h = handlers[method] as ServiceHandlerFn<any[], any> | { run: ServiceHandlerFn<any[], any> };
+    // Function form binds to the handlers object (sibling calls, DI
+    // instances); unit form binds `run` to the unit itself.
+    TaskRegistry.register(
+      contract,
+      typeof h === 'function' ? h.bind(handlers) : h.run.bind(h),
+    );
+  }
+  svcLog.info(
+    `service "${service.name}" implemented — ${Object.keys(service.tasks).join(', ')}`,
+  );
+  return { service, handlers };
+}
+
+/** Anything that can dispatch a TaskContract — WorkerPool, SharedWorkerClient. */
+export interface TaskRunner {
+  runTask<Args extends any[], Result>(
+    contract: TaskContract<Args, Result>,
+    ...args: Args
+  ): Promise<Result>;
+  /**
+   * Options-aware dispatch (abort/timeout). When present, `workerClient`
+   * `client.with(options)` calls route through it; otherwise they fall back
+   * to runTask and the options are ignored.
+   */
+  dispatch?<Args extends any[], Result>(
+    contract: TaskContract<Args, Result>,
+    args: Args,
+    options?: { signal?: AbortSignal; timeout?: number },
+  ): Promise<Result>;
+}
+
+/** The callable RPC surface a service client exposes. */
+export type ServiceClient<M extends RpcMethodMap> = {
+  [K in keyof M]: MethodContract<M[K]> extends TaskContract<infer A, infer R>
+    ? (...args: A) => Promise<R>
+    : never;
+};
+
+/**
+ * The main-thread half of a service contract: a typed proxy that turns
+ * `client.seedIncidents()` into `runner.runTask(contract)`. Works over any
+ * {@link TaskRunner} — a WorkerPool, a SharedWorkerClient, or a test stub.
+ */
+export function createClient<M extends RpcMethodMap>(
+  service: ServiceContract<M>,
+  runner: TaskRunner,
+): ServiceClient<M> {
+  const client = {} as Record<string, unknown>;
+  for (const [method, contract] of Object.entries(service.tasks)) {
+    client[method] = (...args: unknown[]) =>
+      runner.runTask(contract as TaskContract<any[], any>, ...(args as any[]));
+  }
+  return client as ServiceClient<M>;
+}

package/src/shared/sharedWorkerClient.ts

@@ -0,0 +1,142 @@
+import { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
+import { PoolTasks, TaskContract, TaskMap, TaskResult, SharedWorkerConfig } from '../contract/types';
+import { scoped } from '../log';
+
+const clientLog = scoped('shared-client');
+const taskLog = scoped('task');
+
+class SharedWorkerClientImpl<S extends SharedSpec = SharedSpec> {
+  public readonly sharedMemory: SharedMemory<S> & SharedAccess<S>;
+  private readonly port: MessagePort;
+
+  constructor(
+    port: MessagePort,
+    public readonly clientIndex: number,
+    config: SharedWorkerConfig<S, TaskMap>
+  ) {
+    this.port = port;
+    this.sharedMemory = config.sharedMemory;
+
+    // Install first-class task methods, same convention as WorkerPool.
+    const tasks = config.tasks ?? {};
+    for (const [name, contract] of Object.entries(tasks)) {
+      if (name in this) {
+        clientLog.warn(`task "${name}" collides with a SharedWorkerClient member — not installed`);
+        continue;
+      }
+      (this as Record<string, unknown>)[name] = (...args: unknown[]) =>
+        this.runTask(contract as TaskContract<any[], any>, ...(args as any[]));
+    }
+    if (Object.keys(tasks).length > 0) {
+      clientLog.info(`task methods: ${Object.keys(tasks).join(', ')}`);
+    }
+  }
+
+  /** Dispatches a task to the shared worker; the reply comes back on this client's port. */
+  public runTask<Args extends any[], Result>(contract: TaskContract<Args, Result>, ...args: Args): Promise<Result> {
+    return new Promise((resolve, reject) => {
+      const messageId = Math.random().toString(36).substring(2);
+      const t0 = performance.now();
+      taskLog.debug(`→ ${contract.taskId}`, { args });
+
+      const handleMessage = (event: MessageEvent) => {
+        const data = event.data as TaskResult & { messageId?: string };
+        if (data.messageId === messageId) {
+          this.port.removeEventListener('message', handleMessage);
+          const ms = (performance.now() - t0).toFixed(1);
+          if (data.success) {
+            taskLog.debug(`← ${contract.taskId} ok`, { ms: +ms });
+            resolve(data.result);
+          } else {
+            taskLog.warn(`← ${contract.taskId} failed: ${data.error}`, { ms: +ms });
+            reject(new Error(data.error));
+          }
+        }
+      };
+
+      this.port.addEventListener('message', handleMessage);
+      this.port.postMessage({ type: 'EXECUTE_TASK', messageId, taskId: contract.taskId, args });
+    });
+  }
+
+  /** Detaches this client. The shared worker (and its buffer) stay alive for other clients. */
+  public disconnect(): void {
+    try {
+      this.port.postMessage({ type: 'SHARED_DISCONNECT' });
+    } finally {
+      this.port.close();
+    }
+  }
+}
+
+/**
+ * A SharedWorkerClient with first-class task methods baked in from
+ * `config.tasks` — same shape as `WorkerPool`.
+ */
+export type SharedWorkerClient<S extends SharedSpec = SharedSpec, T extends TaskMap = TaskMap> =
+  SharedWorkerClientImpl<S> & PoolTasks<T>;
+
+/**
+ * Connects this page to a `SharedWorker`. The worker owns the SharedArrayBuffer
+ * and shares it with every connecting client — so every page/tab/iframe bound
+ * to the same contract reads and writes the same memory. State propagation
+ * needs no messaging: writes bump shared version counters via Atomics, which
+ * `observe`/`watch` subscribers in every context are already parked on.
+ * Ports carry only the connect handshake and task dispatch.
+ *
+ * ```ts
+ * const worker = await connectSharedWorker({
+ *   createWorker: () => new SharedWorker(new URL('./incidents.sharedWorker.ts', import.meta.url), { type: 'module' }),
+ *   sharedMemory: incidentsMemory,
+ *   tasks: { initIncidents: InitIncidents, queryIncidents: QueryIncidents },
+ * });
+ * ```
+ */
+export async function connectSharedWorker<S extends SharedSpec = SharedSpec, T extends TaskMap = TaskMap>(
+  config: SharedWorkerConfig<S, T>
+): Promise<SharedWorkerClient<S, T>> {
+  if (typeof SharedArrayBuffer === 'undefined' || (typeof crossOriginIsolated !== 'undefined' && !crossOriginIsolated)) {
+    throw new Error(
+      'connectSharedWorker requires SharedArrayBuffer in a cross-origin isolated context — serve the page with COOP/COEP headers.'
+    );
+  }
+  if (!config.port && !config.workerUrl && !config.createWorker) {
+    throw new Error('connectSharedWorker requires `workerUrl`, `createWorker`, or `port` in its config.');
+  }
+
+  const port =
+    config.port ??
+    (config.createWorker
+      ? config.createWorker().port
+      : new SharedWorker(config.workerUrl!, { type: 'module' }).port);
+  port.start();
+
+  const client = await new Promise<SharedWorkerClient<S, T>>((resolve, reject) => {
+    const timeout = setTimeout(
+      () => reject(new Error('connectSharedWorker: timed out waiting for the shared worker — is the host module calling sharedWorkerHost()?')),
+      config.connectTimeoutMs ?? 10_000
+    );
+
+    const handleMessage = (event: MessageEvent) => {
+      const data = event.data;
+      if (data?.type === 'SHARED_MEMORY') {
+        port.removeEventListener('message', handleMessage);
+        clearTimeout(timeout);
+        config.sharedMemory.bind(data.buffer as SharedArrayBuffer);
+        clientLog.info(`connected as client #${data.clientIndex}`, {
+          bytes: data.buffer.byteLength,
+        });
+        resolve(new SharedWorkerClientImpl<S>(port, data.clientIndex, config) as SharedWorkerClient<S, T>);
+      }
+    };
+
+    port.addEventListener('message', handleMessage);
+    port.postMessage({
+      type: 'SHARED_CONNECT',
+      memoryBytes: config.sharedMemory.totalBytes,
+      memory: config.memory,
+    });
+  });
+
+  return client;
+}

package/src/shared/sharedWorkerHost.ts

@@ -0,0 +1,104 @@
+import { bindSharedMemories } from '../contract/sharedMemory';
+import { MemoryManager } from '../pool/memory';
+import { TaskRegistry } from '../worker/registry';
+import { fmtBytes, scoped } from '../log';
+import type { MemoryConfig } from '../contract/types';
+
+const hostLog = scoped('shared-worker');
+
+// Minimal shape — lib.dom doesn't model SharedWorkerGlobalScope reliably.
+interface ConnectEvent {
+  ports: readonly MessagePort[];
+}
+interface SharedWorkerScope {
+  onconnect: ((event: ConnectEvent) => void) | null;
+}
+
+let memory: WebAssembly.Memory | null = null;
+let clientCount = 0;
+
+/**
+ * Lazily creates the shared buffer on first connect. Unlike WorkerPool — where
+ * the page allocates the buffer and pushes it to workers — the SharedWorker
+ * owns the memory so every connecting page/tab binds to the SAME buffer.
+ */
+function ensureMemory(memoryBytes: number, config?: MemoryConfig): WebAssembly.Memory {
+  if (memory) {
+    if (memory.buffer.byteLength < memoryBytes) {
+      hostLog.warn(
+        `client requested ${fmtBytes(memoryBytes)} but buffer is ${fmtBytes(memory.buffer.byteLength)} — first client's capacity wins`
+      );
+    }
+    return memory;
+  }
+  const manager = new MemoryManager(config);
+  manager.ensureCapacity(memoryBytes);
+  memory = manager.memory;
+  bindSharedMemories(manager.getBuffer());
+  hostLog.info(`shared buffer allocated (${fmtBytes(memory.buffer.byteLength)})`);
+  return memory;
+}
+
+/**
+ * Attaches the shared-worker protocol to one client port. Exported separately
+ * so tests can drive it with a `MessageChannel` without a real SharedWorker.
+ */
+export function attachSharedPort(port: MessagePort): void {
+  const index = ++clientCount;
+  hostLog.info(`client #${index} connected`);
+
+  port.onmessage = async (event: MessageEvent) => {
+    const data = event.data;
+
+    if (data?.type === 'SHARED_CONNECT') {
+      const mem = ensureMemory(data.memoryBytes ?? 0, data.memory);
+      port.postMessage({ type: 'SHARED_MEMORY', buffer: mem.buffer, clientIndex: index });
+      return;
+    }
+
+    if (data?.type === 'EXECUTE_TASK') {
+      const { messageId, taskId, args } = data;
+      if (!memory) {
+        port.postMessage({ messageId, success: false, error: 'Shared memory not initialized in worker.' });
+        return;
+      }
+      const t0 = performance.now();
+      try {
+        const result = await TaskRegistry.execute(taskId, ...(args || []));
+        hostLog.debug(`task ${taskId} → ${(performance.now() - t0).toFixed(1)}ms (client #${index})`);
+        port.postMessage({ messageId, success: true, result });
+      } catch (err: any) {
+        hostLog.warn(`task ${taskId} failed: ${err.message || String(err)}`);
+        port.postMessage({ messageId, success: false, error: err.message || String(err) });
+      }
+      return;
+    }
+
+    if (data?.type === 'SHARED_DISCONNECT') {
+      port.close();
+      hostLog.info(`client #${index} disconnected`);
+    }
+  };
+  port.start();
+}
+
+/**
+ * SharedWorker-side entry point — call once at the top of the shared worker
+ * module, after registering task handlers:
+ *
+ * ```ts
+ * import { sharedWorkerHost, TaskRegistry } from '@atolljs/core';
+ * import './tasks';            // TaskRegistry.register(...) calls
+ * sharedWorkerHost();
+ * ```
+ *
+ * Each page/tab/iframe that opens this SharedWorker gets a MessagePort here;
+ * all of them bind the same contract to the same SharedArrayBuffer. Ports are
+ * the control plane (handshake + task dispatch) — state itself never crosses
+ * them; clients observe shared fields directly via Atomics version counters.
+ */
+export function sharedWorkerHost(): void {
+  (self as unknown as SharedWorkerScope).onconnect = (event) => {
+    attachSharedPort(event.ports[0]);
+  };
+}