@atolljs/core 0.1.0 → 0.1.2

package/dist/observable.d.ts

@@ -0,0 +1,30 @@
+import type { Connector, PathConnector, SharedMemory, SharedSpec, SpecPath } from './contract/sharedMemory';
+import { type SliceOptions } from './reactive';
+/**
+ * A minimal subscribable snapshot — `get()` plus `subscribe()`. This is the
+ * interface every framework binding adapts (useSyncExternalStore, refs,
+ * signals, runes). `get()` must return a stable value between notifications.
+ */
+export interface ObservableValue<T> {
+    get(): T;
+    subscribe(onChange: (value: T) => void): () => void;
+}
+type FieldValue<C> = C extends Connector<infer T> ? T : never;
+/**
+ * Observe one field of a shared memory contract as a subscribable snapshot.
+ *
+ * Safe to call before the contract is bound — `get()` returns `undefined`
+ * until binding, and a subscriber registered early activates its watch when
+ * `bind()` lands (useful for SSR, where renders happen without a buffer).
+ * The underlying `watch` starts on the first subscriber and stops when the
+ * last one leaves.
+ */
+export declare function observe<S extends SharedSpec, K extends SpecPath<S>>(memory: SharedMemory<S>, key: K): ObservableValue<FieldValue<PathConnector<S, K>> | undefined>;
+/**
+ * Slice form: `observe(memory, 'metrics', m => m.critical)` — the observable
+ * emits only when the selected slice changes. Slice equality defaults to
+ * `Object.is`; pass `{ equals }` to define what counts as a change —
+ * `shallowEqual` for object slices, or any `(prev, next) => boolean`.
+ */
+export declare function observe<S extends SharedSpec, K extends SpecPath<S>, Sel>(memory: SharedMemory<S>, key: K, select: (value: FieldValue<PathConnector<S, K>>) => Sel, options?: SliceOptions<Sel>): ObservableValue<Sel | undefined>;
+export {};

package/dist/pool/errors.d.ts

@@ -0,0 +1,16 @@
+/** Task queue is at `maxQueue` — dispatch rejected without ever running. */
+export declare class PoolQueueFullError extends Error {
+    constructor(message?: string);
+}
+/** The task's AbortSignal fired — never dispatched, or reply discarded. */
+export declare class TaskAbortedError extends Error {
+    constructor(message?: string);
+}
+/** The task exceeded its `timeout` / pool `taskTimeout` budget. */
+export declare class TaskTimeoutError extends Error {
+    constructor(message?: string);
+}
+/** The worker errored/exited, or the pool was terminated mid-flight. */
+export declare class WorkerCrashedError extends Error {
+    constructor(message?: string);
+}

package/dist/pool/memory.d.ts

@@ -0,0 +1,19 @@
+import { MemoryConfig, ViewType } from '../contract/types';
+export declare class MemoryManager {
+    memory: WebAssembly.Memory;
+    private maxPages;
+    constructor(config?: MemoryConfig);
+    /**
+     * Automatically checks if memory needs to grow to accommodate new bytes,
+     * and expands via memory.grow() if necessary. Thread-safe.
+     */
+    ensureCapacity(requiredBytes: number): void;
+    /**
+     * Creates a typed view over the shared memory buffer at a specific byte offset.
+     */
+    getView<T extends Int32Array | Float64Array | BigInt64Array | Uint8Array>(type: ViewType, byteOffset?: number, length?: number): T;
+    /**
+     * Exposes the raw SharedArrayBuffer
+     */
+    getBuffer(): SharedArrayBuffer;
+}

package/dist/pool/workerClient.d.ts

@@ -0,0 +1,80 @@
+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 type { WorkerDefinition, WorkerMethodMap } from '../worker/defineWorker';
+/** 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 {
+    run: (...args: infer A extends any[]) => infer R;
+} ? (...args: A) => Promise<Awaited<R>> : F extends (...args: infer A extends any[]) => infer R ? (...args: A) => Promise<Awaited<R>> : never;
+/** Flat method map → client signatures. */
+export type ClientMethods<M extends WorkerMethodMap> = {
+    [K in keyof M]: Sig<M[K]>;
+};
+/**
+ * The typed client surface a {@link WorkerDefinition} exposes: flat methods
+ * plus one nested client per service namespace.
+ */
+export type WorkerMethods<W extends WorkerDefinition> = ClientMethods<W['methods']> & {
+    [K in keyof W['services']]: W['services'][K] extends infer M extends WorkerMethodMap ? ClientMethods<M> : never;
+} & {
+    /** Per-call options — `client.with({ signal, timeout }).method(args)`. */
+    with(options: RunOptions): WorkerMethods<W>;
+};
+/**
+ * Typed Proxy over any {@link TaskRunner} (WorkerPool, SharedWorkerClient,
+ * test stub). The path joins with '.', so `client.query(q)` dispatches
+ * taskId "query" and `client.pricing.reprice(x)` dispatches
+ * "pricing.reprice" — no runtime knowledge of the shape needed.
+ */
+export declare function workerClient<W extends WorkerDefinition>(runner: TaskRunner | (() => TaskRunner)): WorkerMethods<W>;
+export interface ConnectWorkerConfig<S extends SharedSpec> {
+    /** Omit for a message-only pool — the SharedArrayBuffer check is skipped. */
+    sharedMemory?: SharedMemory<S> & Prettify<SharedAccess<S>>;
+    /**
+     * Bundler-detectable factory `() => new Worker(new URL('./x.worker.ts', import.meta.url), { type: 'module' })`,
+     * or a URL.
+     */
+    worker: (() => Worker) | URL;
+    poolSize?: number | 'auto';
+    memory?: MemoryConfig;
+    /** 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. */
+    maxQueue?: number;
+    /** Default true — a crashed worker is replaced and its in-flight calls reject. */
+    respawn?: boolean;
+    /** Default per-call timeout ms (`client.with({ timeout })` overrides). */
+    taskTimeout?: number;
+    /** Default true: pool spawns on first method call (or start()). False spawns immediately. */
+    lazy?: boolean;
+}
+/** A typed worker client plus pool lifecycle controls. */
+export type WorkerClient<W extends WorkerDefinition, S extends SharedSpec> = WorkerMethods<W> & {
+    /** Spawn the pool now (idempotent). */
+    start(): void;
+    /** Terminate the pool; the next method call re-spawns it. */
+    terminate(): void;
+    readonly pool: WorkerPool<S> | null;
+    readonly sharedMemory: ConnectWorkerConfig<S>['sharedMemory'] | undefined;
+};
+/**
+ * One-line worker hookup for the main thread — the WorkerPool boilerplate
+ * (worker factory, shared memory, sizing) collapses into the client itself:
+ *
+ *   import type { IncidentsWorker } from './worker/incidents.worker';
+ *
+ *   export const incidents = connectWorker<IncidentsWorker>({
+ *     sharedMemory: incidentsMemory,
+ *     worker: () => new Worker(new URL('./worker/incidents.worker.ts', import.meta.url), { type: 'module' }),
+ *     poolSize: 1,
+ *   });
+ *
+ *   await incidents.queryIncidents(q);   // typed dispatch to the pool
+ *   incidents.terminate();               // next call lazily re-spawns
+ *
+ * Lazy by default: no Worker is touched until the first method call (or
+ * `start()`), so importing the client is SSR-safe.
+ */
+export declare function connectWorker<W extends WorkerDefinition, S extends SharedSpec = W extends WorkerDefinition<infer X> ? X : SharedSpec>(config: ConnectWorkerConfig<S>): WorkerClient<W, S>;
+export {};

package/dist/pool/workerPool.d.ts

@@ -0,0 +1,115 @@
+import { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
+import { MemoryPersistence, PoolTasks, TaskContract, TaskMap, WorkerPoolConfig } from '../contract/types';
+/** Per-call dispatch controls. */
+export interface RunOptions {
+    /**
+     * Cancels the call: a queued task is removed and rejects with
+     * TaskAbortedError; an in-flight task rejects immediately and the worker's
+     * eventual reply is discarded. JS cannot be interrupted — the worker keeps
+     * running, and the worker's slot is released only when its reply arrives.
+     * Callers needing a hard cancel should `terminate()`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Per-call timeout in ms — overrides the pool's `taskTimeout`. The timer
+     * starts at enqueue, so it bounds queue-wait + execution time together.
+     */
+    timeout?: number;
+}
+export interface PoolStats {
+    workers: number;
+    idle: number;
+    inFlight: number;
+    queued: number;
+    completed: number;
+    failed: number;
+    aborted: number;
+    /** queue→dispatch timings. */
+    waitMs: {
+        count: number;
+        mean: number;
+        max: number;
+    };
+    /** dispatch→reply timings. */
+    runMs: {
+        count: number;
+        mean: number;
+        max: number;
+    };
+}
+declare class WorkerPoolImpl<S extends SharedSpec = SharedSpec> {
+    private slots;
+    private pending;
+    private nextMessageId;
+    private queue;
+    private memoryManager?;
+    private workerUrl?;
+    private spawn;
+    private readonly concurrency;
+    private readonly maxQueue;
+    private readonly respawn;
+    private readonly taskTimeout?;
+    private closed;
+    private drainWaiters;
+    private statsAgg;
+    readonly sharedMemory: (SharedMemory<S> & SharedAccess<S>) | undefined;
+    /** The attached memory-persistence adapter, if the config supplied one. */
+    readonly persistence: MemoryPersistence | undefined;
+    constructor(config: WorkerPoolConfig<S, TaskMap>);
+    /** Adds a spawned worker: one message + one error listener, then the INIT handshake. */
+    private addWorker;
+    private handleReply;
+    private handleWorkerError;
+    /** Least-busy worker below its concurrency cap, if any. */
+    private pickWorker;
+    private drainQueue;
+    private send;
+    /** Detaches signal/timeout listeners from a finalized entry. */
+    private detach;
+    /**
+     * Abort/timeout path: a queued task is removed outright; an in-flight task
+     * stays in `pending` as an orphan — the worker is still running it, so the
+     * slot remains occupied until the reply arrives (handleReply frees it).
+     */
+    private cancel;
+    private checkDrained;
+    /**
+     * Full dispatch: least-busy scheduling, `concurrency` cap per worker,
+     * FIFO queue bounded by `maxQueue`, abort/timeout, and queue→reply timing.
+     */
+    dispatch<Args extends any[], Result>(contract: TaskContract<Args, Result>, args: Args, options?: RunOptions): Promise<Result>;
+    /**
+     * Dispatches a task to the least-busy worker in the pool.
+     * The task contract guarantees the argument and result types across the thread boundary.
+     */
+    runTask<Args extends any[], Result>(contract: TaskContract<Args, Result>, ...args: Args): Promise<Result>;
+    /**
+     * The shared buffer handed to workers via INIT_MEMORY — undefined on
+     * message-only pools. Useful for passing the same buffer to auxiliaries
+     * (e.g. a second pool of HTTP workers via withSharedBuffer).
+     */
+    get sharedBuffer(): SharedArrayBuffer | undefined;
+    /**
+     * Live snapshot of the pool's worker slots — for auxiliary messaging that
+     * isn't task dispatch (e.g. routing accepted sockets into workers). The
+     * array is a copy; respawned workers appear on the next read. Do NOT use
+     * this to dispatch tasks — runTask/dispatch own the scheduling protocol.
+     */
+    get workers(): readonly Worker[];
+    /** Running aggregates — no histograms, just counts and means. */
+    stats(): PoolStats;
+    /** Resolves once the queue is empty and nothing is in flight, then terminates. */
+    close(): Promise<void>;
+    terminate(): void;
+}
+/**
+ * A WorkerPool with first-class task methods baked in from `config.tasks`.
+ * Constructed as `new WorkerPool({ workerUrl, sharedMemory, tasks })` —
+ * `tasks: { queryIncidents: QueryIncidents }` exposes `pool.queryIncidents(q)`
+ * with the contract's declared args/result types.
+ */
+export type WorkerPool<S extends SharedSpec = SharedSpec, T extends TaskMap = TaskMap> = WorkerPoolImpl<S> & PoolTasks<T>;
+export declare const WorkerPool: {
+    new <S extends SharedSpec = SharedSpec, T extends TaskMap = TaskMap>(config: WorkerPoolConfig<S, T>): WorkerPool<S, T>;
+};
+export {};

package/dist/reactive.d.ts

@@ -0,0 +1,46 @@
+import { Connector } from './contract/sharedMemory';
+/** 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 declare function shallowEqual<T extends object>(prev: T | undefined, next: T | undefined): boolean;
+/**
+ * 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 declare function reactive<T>(connector: Connector<T>): ReactiveConnector<T>;
+/**
+ * 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 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;

package/dist/service.d.ts

@@ -0,0 +1,181 @@
+import type { Schema, TaskContract, ViewType } from './contract/types';
+/**
+ * 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 declare function rpc<Args extends any[] = any[], Result = any>(def?: RpcMethodDef<Args, Result>): RpcMethodDef<Args, Result>;
+/**
+ * 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 declare function serviceMethod<D extends RpcMethodDef, U extends {
+    def: D;
+}>(unit: U & {
+    run: (...args: DefArgs<D>) => DefResult<D> | Promise<DefResult<D>>;
+}): U;
+/** 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> : 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 declare function defineService<M extends RpcMethodInputMap>(name: string, methods: M): ServiceContract<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 declare function implementService<M extends RpcMethodInputMap>(service: ServiceContract<M>, handlers: ServiceHandlers<M>): ServiceImpl<M>;
+/** 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 declare function createClient<M extends RpcMethodMap>(service: ServiceContract<M>, runner: TaskRunner): ServiceClient<M>;
+export {};

package/dist/shared/sharedWorkerClient.d.ts

@@ -0,0 +1,35 @@
+import { SharedAccess, SharedMemory, SharedSpec } from '../contract/sharedMemory';
+import { PoolTasks, TaskContract, TaskMap, SharedWorkerConfig } from '../contract/types';
+declare class SharedWorkerClientImpl<S extends SharedSpec = SharedSpec> {
+    readonly clientIndex: number;
+    readonly sharedMemory: SharedMemory<S> & SharedAccess<S>;
+    private readonly port;
+    constructor(port: MessagePort, clientIndex: number, config: SharedWorkerConfig<S, TaskMap>);
+    /** Dispatches a task to the shared worker; the reply comes back on this client's port. */
+    runTask<Args extends any[], Result>(contract: TaskContract<Args, Result>, ...args: Args): Promise<Result>;
+    /** Detaches this client. The shared worker (and its buffer) stay alive for other clients. */
+    disconnect(): void;
+}
+/**
+ * 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 declare function connectSharedWorker<S extends SharedSpec = SharedSpec, T extends TaskMap = TaskMap>(config: SharedWorkerConfig<S, T>): Promise<SharedWorkerClient<S, T>>;
+export {};

package/dist/shared/sharedWorkerHost.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Attaches the shared-worker protocol to one client port. Exported separately
+ * so tests can drive it with a `MessageChannel` without a real SharedWorker.
+ */
+export declare function attachSharedPort(port: MessagePort): void;
+/**
+ * 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 declare function sharedWorkerHost(): void;

package/dist/task.d.ts

@@ -0,0 +1,40 @@
+import type { ObservableValue } from './observable';
+/**
+ * Point-in-time state of an {@link AsyncTask}. Replaced wholesale on every
+ * transition so `get()` stays stable for `useSyncExternalStore`-style
+ * adapters.
+ */
+export interface TaskSnapshot<R> {
+    /** Result of the last completed run; kept while a newer run is in flight. */
+    data: R | null;
+    pending: boolean;
+    /** True once any run has completed (success or failure). */
+    settled: boolean;
+    /** Wall-clock duration of the last completed run. */
+    elapsedMs: number | null;
+    error: unknown;
+}
+/**
+ * An async function turned into a subscribable task: `run` starts an
+ * invocation, and concurrent runs are latest-wins — a stale result is
+ * discarded rather than applied. Framework bindings subscribe to the
+ * snapshot; callers trigger `run`.
+ */
+export interface AsyncTask<A, R> extends ObservableValue<TaskSnapshot<R>> {
+    run(input: A): void;
+    /** No-op if a run is pending or has already settled — for init-style tasks. */
+    runOnce(input: A): void;
+}
+export declare function defineTask<A, R>(fn: (input: A) => Promise<R>): AsyncTask<A, R>;
+/** Structural check: run/runOnce triggers plus the observable contract. */
+export declare function isAsyncTask(x: unknown): x is AsyncTask<any, any>;
+/**
+ * Accepts an {@link AsyncTask} or a plain async function and always returns
+ * a task — framework bindings (useTask, taskState, …) take either, so a
+ * worker client's method drops straight in:
+ *
+ *   const seed = useTask(initIncidents);            // async fn → defineTask
+ *   const page = useTask(incidents.queryIncidents); // client method → task
+ */
+export declare function toTask<R>(source: AsyncTask<void, R> | (() => Promise<R>)): AsyncTask<void, R>;
+export declare function toTask<A, R>(source: AsyncTask<A, R> | ((input: A) => Promise<R>)): AsyncTask<A, R>;

package/dist/worker/defineWorker.d.ts

@@ -0,0 +1,63 @@
+import './workerBootstrap';
+import type { ServiceMethod } from '../service';
+import type { SharedMemory, SharedSpec } from '../contract/sharedMemory';
+/**
+ * One worker-exposed method: a plain function (siblings reachable via `this`)
+ * or a {@link ServiceMethod} unit (`{ def, run }` — schemas enforced on the
+ * wire).
+ */
+export type WorkerMethod = ((...args: any[]) => any) | ServiceMethod<any[], any>;
+export type WorkerMethodMap = Record<string, WorkerMethod>;
+export type WorkerServiceMap = Record<string, WorkerMethodMap>;
+type ReservedKey = (typeof RESERVED_CLIENT_KEYS)[number];
+/** Turns any reserved keys in M into `never`-typed members — a compile error. */
+type NoReserved<M> = [Extract<keyof M, ReservedKey>] extends [never] ? M : M & {
+    [K in Extract<keyof M, ReservedKey>]: never;
+};
+export interface DefineWorkerConfig<S extends SharedSpec, M extends WorkerMethodMap, Svc extends WorkerServiceMap> {
+    /**
+     * Optional — carried in the type so connectWorker can check the main-side
+     * contract matches. Binding is global via workerBootstrap.
+     */
+    sharedMemory?: SharedMemory<S>;
+    /** Flat methods → taskId = method name. */
+    methods?: NoReserved<M>;
+    /** Namespaced methods → taskId = `${service}.${method}`. */
+    services?: NoReserved<Svc>;
+}
+export interface WorkerDefinition<S extends SharedSpec = SharedSpec, M extends WorkerMethodMap = {}, Svc extends WorkerServiceMap = {}> {
+    readonly methods: M;
+    readonly services: Svc;
+    readonly sharedMemory?: SharedMemory<S>;
+}
+/**
+ * Client-surface keys a worker method must not claim — a method named
+ * `pool` or `then` would collide with {@link connectWorker}'s API (or make
+ * the client look like a thenable).
+ */
+export declare const RESERVED_CLIENT_KEYS: readonly ['start', 'terminate', 'pool', 'sharedMemory', 'then', 'with'];
+/**
+ * The worker-side half of the tRPC-style pair: the worker script owns the
+ * runtime (importing this module wires `self.onmessage` via workerBootstrap)
+ * and the method list — the main thread imports only `typeof` the returned
+ * definition and drives it through a {@link connectWorker} Proxy client.
+ *
+ *   // incidents.worker.ts — the whole worker entry
+ *   export const incidentsWorker = defineWorker({
+ *     sharedMemory: incidentsMemory,
+ *     methods: { seedIncidents, queryIncidents, computeMetrics },
+ *   });
+ *   export type IncidentsWorker = typeof incidentsWorker;
+ *
+ * Flat methods register under their own name; `services: { svc: { m } }`
+ * registers `svc.m`. Plain functions are invoked with `this` bound to the
+ * methods object (sibling calls); ServiceMethod units contribute their
+ * `def` schemas (and a `def.taskId` override) and run bound to the unit.
+ *
+ * BOOTSTRAP ORDERING (Node): the `@atolljs/node/shim` import must
+ * evaluate before this module — it binds `self = parentPort`, which
+ * workerBootstrap needs at import time. Keep `import '@atolljs/node/shim'`
+ * first in the worker entry.
+ */
+export declare function defineWorker<S extends SharedSpec, M extends WorkerMethodMap = {}, Svc extends WorkerServiceMap = {}>(config: DefineWorkerConfig<S, M, Svc>): WorkerDefinition<S, M, Svc>;
+export {};

package/dist/worker/registry.d.ts

@@ -0,0 +1,8 @@
+import { TaskContract } from '../contract/types';
+export type TaskHandler<Args extends any[] = any[], Result = any> = (...args: Args) => Result | Promise<Result>;
+export declare class TaskRegistry {
+    private static tasks;
+    static register<Args extends any[], Result>(contract: TaskContract<Args, Result>, handler: TaskHandler<Args, Result>): void;
+    static getContract(taskId: string): TaskContract | undefined;
+    static execute(taskId: string, ...args: any[]): Promise<any>;
+}