@oasys/oecs 0.5.3 → 0.6.0

package/dist/plugins/workers/pool.d.cts

@@ -0,0 +1,144 @@
+import { SystemContext } from '../../core/ecs/system_context.cjs';
+import { ParallelPlan } from './plan.cjs';
+/** What the pool needs from the world, and nothing more. */
+export interface PoolWorld {
+    /** The `WebAssembly.Memory` on the wasm backing, the `SharedArrayBuffer` on
+     * the shared backing. The two grow differently and the worker survives both,
+     * which is why the memory itself travels and not its current buffer. */
+    readonly store: SharedArrayBuffer | WebAssembly.Memory;
+    readonly storeBase: number;
+    /** Tell the store that a component's row ticks changed outside the dirty
+     * list, so the next entity-level drain scans the plane. */
+    noteScan(componentId: number): void;
+    /** Every parallel plan the world has registered so far. */
+    plans(): readonly ParallelPlan[];
+    /** The pool has stopped, so the world drops it and the schedule goes back to
+     * the sequential path. */
+    released(): void;
+}
+/**
+ * How long the host waits at the join before it gives up on a worker.
+ *
+ * A safety net, and not a budget. A pass that takes this long has already
+ * missed every frame the host meant to draw, so the value only has to sit above
+ * any pass a working kernel runs, on slow hardware and under load. It is far
+ * above that, and still short enough that a person watching a hung process gets
+ * an error instead of a dead prompt. Tune it down only to make a hang surface
+ * sooner, never to bound a frame.
+ */
+export declare const DEFAULT_JOIN_TIMEOUT_MS = 30000;
+export interface AttachWorkersOptions {
+    /** Workers to start. Defaults to one below the reported parallelism, floor
+     * one. One worker is always a loss against the sequential body, so a caller
+     * that wants a split gives more than one. */
+    readonly count?: number;
+    /** Where the engine's worker entry lives. Defaults to `@oasys/oecs/worker`,
+     * which the package ships one directory above the module this pool lands in.
+     *
+     * A bundler moves the pool into a chunk of its own and leaves the worker
+     * entry out of the graph, so the default resolves to a file the server does
+     * not hold. Pass the URL the bundler emits for `@oasys/oecs/worker`. */
+    readonly workerUrl?: string | URL;
+    /** Milliseconds the host waits at the join before it gives up on the pass.
+     * A positive integer. Defaults to `DEFAULT_JOIN_TIMEOUT_MS`.
+     *
+     * A kernel that throws is caught in the worker and reported. A worker that
+     * dies outright reports nothing, so without this the host parks for the life
+     * of the process. */
+    readonly joinTimeoutMs?: number;
+    /**
+     * Bytes of shadow stack one instance of a `wasm` kernel module gets. An
+     * integer, a multiple of `KERNEL_STACK_ALIGN`, at least
+     * `KERNEL_STACK_MIN_BYTES`.
+     *
+     * The regions are carved downward from the store base, so with this given
+     * everything below the lowest region stays the module's heap. Without it the
+     * pool divides the whole span between the module's `__heap_base` and the
+     * store base, and the module then has no heap.
+     *
+     * A wasm stack has no guard page. A kernel that runs deeper than its region
+     * writes into the region below it and nothing reports the overrun, so this is
+     * a number only the caller can pick.
+     */
+    readonly stackBytes?: number;
+}
+/**
+ * The pool a world attaches. One per world, started once, and the only thing
+ * that speaks to a worker.
+ */
+export declare class WorkerPool {
+    private readonly _world;
+    private readonly _workers;
+    private readonly _ctl;
+    private readonly _ctlF64;
+    private readonly _joinTimeoutMs;
+    private _state;
+    private _epoch;
+    private _nextSlot;
+    private _pending;
+    private _syncing;
+    private constructor();
+    /** How many workers the pool runs. */
+    get count(): number;
+    /**
+     * Start the workers, hand each the store and the control buffer, and load
+     * every kernel the world has declared. Resolves when each worker is parked on
+     * the barrier with its kernels in hand. Cold path, and a caller runs it once.
+     *
+     * Throws `WORKERS_ENTRY_UNREACHABLE` when a worker's script does not load,
+     * which is what a wrong `workerUrl` looks like from here.
+     */
+    static attach(world: PoolWorld, options?: AttachWorkersOptions): Promise<WorkerPool>;
+    /** Take one kernel. The system runs `fn` until every worker holds it. */
+    register(plan: ParallelPlan): void;
+    private _kick;
+    /** Resolves when every kernel registered so far is loaded on every worker.
+     * Rejects with `PARALLEL_KERNEL_FAILED` when one would not load. */
+    settled(): Promise<void>;
+    private _sync;
+    /** Release every worker out of the barrier loop, so each can take a message
+     * again. A parked worker runs no message callback. */
+    private _park;
+    private _resume;
+    /**
+     * Run one parallel system across the pool, or say no.
+     *
+     * Returns `false` when the kernel is not loaded yet, when the pool is not on
+     * the barrier, when an earlier pass timed out, or when the matched row count
+     * is below the system's threshold. The caller then runs the sequential body,
+     * which is the same answer.
+     *
+     * Throws `PARALLEL_KERNEL_FAILED` when a kernel throws, and when a worker
+     * misses the join inside `joinTimeoutMs`. The second case is a dead or hung
+     * worker, which reports nothing, so the pool fails the pass itself.
+     *
+     * Hot path. The host parks for the length of the pass, so no structural
+     * change can overlap it.
+     */
+    run(plan: ParallelPlan, ctx: SystemContext, deltaTime: number, runTick: number): boolean;
+    /**
+     * Stamp what the pass changed.
+     *
+     * The row tick plane and the dirty lists are main-thread JS, so the join does
+     * this and not the workers. `columnGroupMut` makes the same archetype stamp a
+     * system body makes, which is why that logic is not written twice here.
+     *
+     * The row ticks follow the same shape a chunk loop takes when it reads
+     * `cols.ticks`: fill the plane, then tell the store to scan it. Without the
+     * fill an entity-level `onSet` observer would see nothing, because the
+     * archetype stamp alone carries no row.
+     *
+     * Coarse on purpose: a parallel system reports every row of every matched
+     * archetype as changed. A finer stamp is open.
+     */
+    private _stamp;
+    /**
+     * Stop every worker and release the pool. Idempotent.
+     *
+     * `terminate` ends a worker that is spinning inside a kernel, so this is the
+     * way out of a pool a join timeout failed. A failed pool is never released
+     * back into the barrier, so no stop job is written for it.
+     */
+    detach(): Promise<void>;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/plugins/workers/pool.d.ts

@@ -0,0 +1,144 @@
+import { SystemContext } from '../../core/ecs/system_context.js';
+import { ParallelPlan } from './plan.js';
+/** What the pool needs from the world, and nothing more. */
+export interface PoolWorld {
+    /** The `WebAssembly.Memory` on the wasm backing, the `SharedArrayBuffer` on
+     * the shared backing. The two grow differently and the worker survives both,
+     * which is why the memory itself travels and not its current buffer. */
+    readonly store: SharedArrayBuffer | WebAssembly.Memory;
+    readonly storeBase: number;
+    /** Tell the store that a component's row ticks changed outside the dirty
+     * list, so the next entity-level drain scans the plane. */
+    noteScan(componentId: number): void;
+    /** Every parallel plan the world has registered so far. */
+    plans(): readonly ParallelPlan[];
+    /** The pool has stopped, so the world drops it and the schedule goes back to
+     * the sequential path. */
+    released(): void;
+}
+/**
+ * How long the host waits at the join before it gives up on a worker.
+ *
+ * A safety net, and not a budget. A pass that takes this long has already
+ * missed every frame the host meant to draw, so the value only has to sit above
+ * any pass a working kernel runs, on slow hardware and under load. It is far
+ * above that, and still short enough that a person watching a hung process gets
+ * an error instead of a dead prompt. Tune it down only to make a hang surface
+ * sooner, never to bound a frame.
+ */
+export declare const DEFAULT_JOIN_TIMEOUT_MS = 30000;
+export interface AttachWorkersOptions {
+    /** Workers to start. Defaults to one below the reported parallelism, floor
+     * one. One worker is always a loss against the sequential body, so a caller
+     * that wants a split gives more than one. */
+    readonly count?: number;
+    /** Where the engine's worker entry lives. Defaults to `@oasys/oecs/worker`,
+     * which the package ships one directory above the module this pool lands in.
+     *
+     * A bundler moves the pool into a chunk of its own and leaves the worker
+     * entry out of the graph, so the default resolves to a file the server does
+     * not hold. Pass the URL the bundler emits for `@oasys/oecs/worker`. */
+    readonly workerUrl?: string | URL;
+    /** Milliseconds the host waits at the join before it gives up on the pass.
+     * A positive integer. Defaults to `DEFAULT_JOIN_TIMEOUT_MS`.
+     *
+     * A kernel that throws is caught in the worker and reported. A worker that
+     * dies outright reports nothing, so without this the host parks for the life
+     * of the process. */
+    readonly joinTimeoutMs?: number;
+    /**
+     * Bytes of shadow stack one instance of a `wasm` kernel module gets. An
+     * integer, a multiple of `KERNEL_STACK_ALIGN`, at least
+     * `KERNEL_STACK_MIN_BYTES`.
+     *
+     * The regions are carved downward from the store base, so with this given
+     * everything below the lowest region stays the module's heap. Without it the
+     * pool divides the whole span between the module's `__heap_base` and the
+     * store base, and the module then has no heap.
+     *
+     * A wasm stack has no guard page. A kernel that runs deeper than its region
+     * writes into the region below it and nothing reports the overrun, so this is
+     * a number only the caller can pick.
+     */
+    readonly stackBytes?: number;
+}
+/**
+ * The pool a world attaches. One per world, started once, and the only thing
+ * that speaks to a worker.
+ */
+export declare class WorkerPool {
+    private readonly _world;
+    private readonly _workers;
+    private readonly _ctl;
+    private readonly _ctlF64;
+    private readonly _joinTimeoutMs;
+    private _state;
+    private _epoch;
+    private _nextSlot;
+    private _pending;
+    private _syncing;
+    private constructor();
+    /** How many workers the pool runs. */
+    get count(): number;
+    /**
+     * Start the workers, hand each the store and the control buffer, and load
+     * every kernel the world has declared. Resolves when each worker is parked on
+     * the barrier with its kernels in hand. Cold path, and a caller runs it once.
+     *
+     * Throws `WORKERS_ENTRY_UNREACHABLE` when a worker's script does not load,
+     * which is what a wrong `workerUrl` looks like from here.
+     */
+    static attach(world: PoolWorld, options?: AttachWorkersOptions): Promise<WorkerPool>;
+    /** Take one kernel. The system runs `fn` until every worker holds it. */
+    register(plan: ParallelPlan): void;
+    private _kick;
+    /** Resolves when every kernel registered so far is loaded on every worker.
+     * Rejects with `PARALLEL_KERNEL_FAILED` when one would not load. */
+    settled(): Promise<void>;
+    private _sync;
+    /** Release every worker out of the barrier loop, so each can take a message
+     * again. A parked worker runs no message callback. */
+    private _park;
+    private _resume;
+    /**
+     * Run one parallel system across the pool, or say no.
+     *
+     * Returns `false` when the kernel is not loaded yet, when the pool is not on
+     * the barrier, when an earlier pass timed out, or when the matched row count
+     * is below the system's threshold. The caller then runs the sequential body,
+     * which is the same answer.
+     *
+     * Throws `PARALLEL_KERNEL_FAILED` when a kernel throws, and when a worker
+     * misses the join inside `joinTimeoutMs`. The second case is a dead or hung
+     * worker, which reports nothing, so the pool fails the pass itself.
+     *
+     * Hot path. The host parks for the length of the pass, so no structural
+     * change can overlap it.
+     */
+    run(plan: ParallelPlan, ctx: SystemContext, deltaTime: number, runTick: number): boolean;
+    /**
+     * Stamp what the pass changed.
+     *
+     * The row tick plane and the dirty lists are main-thread JS, so the join does
+     * this and not the workers. `columnGroupMut` makes the same archetype stamp a
+     * system body makes, which is why that logic is not written twice here.
+     *
+     * The row ticks follow the same shape a chunk loop takes when it reads
+     * `cols.ticks`: fill the plane, then tell the store to scan it. Without the
+     * fill an entity-level `onSet` observer would see nothing, because the
+     * archetype stamp alone carries no row.
+     *
+     * Coarse on purpose: a parallel system reports every row of every matched
+     * archetype as changed. A finer stamp is open.
+     */
+    private _stamp;
+    /**
+     * Stop every worker and release the pool. Idempotent.
+     *
+     * `terminate` ends a worker that is spinning inside a kernel, so this is the
+     * way out of a pool a join timeout failed. A failed pool is never released
+     * back into the barrier, so no stop job is written for it.
+     */
+    detach(): Promise<void>;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/plugins/workers/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../../src/plugins/workers/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA8BK;AAIL,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAGnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAoB3C,4DAA4D;AAC5D,MAAM,WAAW,SAAS;IACzB;;4EAEwE;IACxE,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,WAAW,CAAC,MAAM,CAAC;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;+DAC2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,2DAA2D;IAC3D,KAAK,IAAI,SAAS,YAAY,EAAE,CAAC;IACjC;8BAC0B;IAC1B,QAAQ,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,MAAM,WAAW,oBAAoB;IACpC;;iDAE6C;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;4EAKwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAClC;;;;;yBAKqB;IACrB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAqMD;;;GAGG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,QAAQ,CAAoC;IAEpD,OAAO;IAaP,sCAAsC;IACtC,IAAW,KAAK,IAAI,MAAM,CAEzB;IAED;;;;;;;OAOG;WACiB,MAAM,CACzB,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,UAAU,CAAC;IAoEtB,yEAAyE;IAClE,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAMzC,OAAO,CAAC,KAAK;IAIb;wEACoE;IAC7D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAIjB,KAAK;IAqCnB;0DACsD;YACxC,KAAK;IASnB,OAAO,CAAC,OAAO;IAMf;;;;;;;;;;;;;;OAcG;IACI,GAAG,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IA+D/F;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,MAAM;IAgBd;;;;;;OAMG;IACU,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAuBpC"}

package/dist/plugins/workers/protocol.d.cts

@@ -0,0 +1,112 @@
+/***
+ * The words a host and a worker share, and the messages that cross once.
+ *
+ * The control buffer is one small `SharedArrayBuffer` beside the store. The
+ * host writes the job, bumps the epoch and wakes every worker. Each worker adds
+ * one to the done word when it finishes, and the worker that completes the
+ * count notifies it. Nothing else crosses during a frame, because `postMessage`
+ * is far slower than an `Atomics` release and a parked worker never runs a
+ * message callback anyway.
+ *
+ * The store buffer never travels here. A worker holds it from its start
+ * message and reads it directly.
+ *
+ * This module imports the ABI constants and nothing else. The worker entry runs
+ * outside the bundler, so every import in its chain names the file with its
+ * extension.
+ ***/
+/** The frame number, and the word every worker sleeps on. */
+export declare const CTL_EPOCH = 0;
+/**
+ * How many workers finished this epoch. The host clears it before it bumps the
+ * epoch, and every worker adds one when its pass ends, whether the kernel ran
+ * or threw.
+ *
+ * One worker notifies this word, and it is the one whose add carried the count
+ * to the worker count. An earlier notify only wakes a host that reads a short
+ * count and parks again. So the host wakes once for each pass and not once for
+ * each worker.
+ */
+export declare const CTL_DONE = 1;
+/** Which kernel slot to run, or one of the control jobs below. */
+export declare const CTL_KERNEL = 2;
+/** The first failing worker's index plus one. Zero means every worker ran. */
+export declare const CTL_FAILED = 3;
+/** The query's include mask, `COMPONENT_MASK_WORDS` little-endian words. */
+export declare const CTL_INCLUDE = 4;
+/** The query's exclude mask, read only when `CTL_HAS_EXCLUDE` is one. */
+export declare const CTL_EXCLUDE: number;
+export declare const CTL_HAS_EXCLUDE: number;
+/** `dt`, as an index into a `Float64Array` over the same bytes. It sits above
+ * every word above, on the next 8-byte boundary. */
+export declare const CTL_DT: number;
+export declare const CONTROL_BYTES: number;
+/** Leave the barrier loop and return to the event loop, so the worker can take
+ * a kernel registration. A parked worker runs no message callback, so the host
+ * has to release it first. */
+export declare const JOB_YIELD = -1;
+/** Leave the barrier loop and stop. */
+export declare const JOB_STOP = -2;
+/**
+ * The frame alignment an LLVM wasm target keeps for its shadow stack. A region
+ * that is a multiple of this needs no rounding at its top.
+ *
+ * The host validates `stackBytes` against it and the worker carves against it,
+ * so both live here rather than in either half.
+ */
+export declare const KERNEL_STACK_ALIGN = 16;
+/**
+ * The smallest stack region a worker accepts, one WASM page.
+ *
+ * A wasm stack has no guard page, so a kernel that runs past the bottom of its
+ * region writes into the region below it and nothing reports the overrun. The
+ * floor catches a caller who reserved nothing. It does not size the stack of a
+ * deep kernel, and no engine can. The caller reserves the span and says how
+ * much of it one worker gets.
+ */
+export declare const KERNEL_STACK_MIN_BYTES = 65536;
+/** What a worker receives before it does anything. `store` is the
+ * `WebAssembly.Memory` on the wasm backing and the `SharedArrayBuffer` on the
+ * shared backing, because the two grow differently: the memory hands back a new
+ * buffer object and freezes the old one at its pre-grow length, while the
+ * shared buffer grows in place. */
+export interface WorkerStart {
+    readonly store: SharedArrayBuffer | WebAssembly.Memory;
+    readonly storeBase: number;
+    readonly control: SharedArrayBuffer;
+    readonly index: number;
+    readonly count: number;
+    /** Bytes of shadow stack one instance of a `wasm` kernel module gets, or 0
+     * when the caller named none. At 0 the worker divides the whole span between
+     * the module's `__heap_base` and the store base, which leaves the module no
+     * heap. */
+    readonly stackBytes: number;
+}
+/** One kernel a worker loads, addressed by its slot for the rest of the run.
+ * A worker cannot receive a closure, which is why a kernel is a module and an
+ * export name. */
+export interface KernelMessage {
+    readonly type: "kernel";
+    readonly slot: number;
+    /** A compiled module, structured-clone safe, shared with every worker. */
+    readonly wasm?: WebAssembly.Module;
+    /** An absolute module URL the worker imports. */
+    readonly js?: string;
+    readonly exportName: string;
+    /** `(component_id, field_id)` pairs, flat, in the kernel's argument order. */
+    readonly specs: Int32Array;
+}
+/** Re-enter the barrier loop. */
+export interface RunMessage {
+    readonly type: "run";
+}
+export type HostMessage = KernelMessage | RunMessage;
+export interface WorkerReply {
+    /** `ready` once at start, `kernel` for one registration, `yielded` when the
+     * worker leaves the barrier loop. */
+    readonly type: "ready" | "kernel" | "yielded";
+    readonly slot?: number;
+    /** The failure text, when a kernel would not load. */
+    readonly error?: string;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/plugins/workers/protocol.d.ts

@@ -0,0 +1,112 @@
+/***
+ * The words a host and a worker share, and the messages that cross once.
+ *
+ * The control buffer is one small `SharedArrayBuffer` beside the store. The
+ * host writes the job, bumps the epoch and wakes every worker. Each worker adds
+ * one to the done word when it finishes, and the worker that completes the
+ * count notifies it. Nothing else crosses during a frame, because `postMessage`
+ * is far slower than an `Atomics` release and a parked worker never runs a
+ * message callback anyway.
+ *
+ * The store buffer never travels here. A worker holds it from its start
+ * message and reads it directly.
+ *
+ * This module imports the ABI constants and nothing else. The worker entry runs
+ * outside the bundler, so every import in its chain names the file with its
+ * extension.
+ ***/
+/** The frame number, and the word every worker sleeps on. */
+export declare const CTL_EPOCH = 0;
+/**
+ * How many workers finished this epoch. The host clears it before it bumps the
+ * epoch, and every worker adds one when its pass ends, whether the kernel ran
+ * or threw.
+ *
+ * One worker notifies this word, and it is the one whose add carried the count
+ * to the worker count. An earlier notify only wakes a host that reads a short
+ * count and parks again. So the host wakes once for each pass and not once for
+ * each worker.
+ */
+export declare const CTL_DONE = 1;
+/** Which kernel slot to run, or one of the control jobs below. */
+export declare const CTL_KERNEL = 2;
+/** The first failing worker's index plus one. Zero means every worker ran. */
+export declare const CTL_FAILED = 3;
+/** The query's include mask, `COMPONENT_MASK_WORDS` little-endian words. */
+export declare const CTL_INCLUDE = 4;
+/** The query's exclude mask, read only when `CTL_HAS_EXCLUDE` is one. */
+export declare const CTL_EXCLUDE: number;
+export declare const CTL_HAS_EXCLUDE: number;
+/** `dt`, as an index into a `Float64Array` over the same bytes. It sits above
+ * every word above, on the next 8-byte boundary. */
+export declare const CTL_DT: number;
+export declare const CONTROL_BYTES: number;
+/** Leave the barrier loop and return to the event loop, so the worker can take
+ * a kernel registration. A parked worker runs no message callback, so the host
+ * has to release it first. */
+export declare const JOB_YIELD = -1;
+/** Leave the barrier loop and stop. */
+export declare const JOB_STOP = -2;
+/**
+ * The frame alignment an LLVM wasm target keeps for its shadow stack. A region
+ * that is a multiple of this needs no rounding at its top.
+ *
+ * The host validates `stackBytes` against it and the worker carves against it,
+ * so both live here rather than in either half.
+ */
+export declare const KERNEL_STACK_ALIGN = 16;
+/**
+ * The smallest stack region a worker accepts, one WASM page.
+ *
+ * A wasm stack has no guard page, so a kernel that runs past the bottom of its
+ * region writes into the region below it and nothing reports the overrun. The
+ * floor catches a caller who reserved nothing. It does not size the stack of a
+ * deep kernel, and no engine can. The caller reserves the span and says how
+ * much of it one worker gets.
+ */
+export declare const KERNEL_STACK_MIN_BYTES = 65536;
+/** What a worker receives before it does anything. `store` is the
+ * `WebAssembly.Memory` on the wasm backing and the `SharedArrayBuffer` on the
+ * shared backing, because the two grow differently: the memory hands back a new
+ * buffer object and freezes the old one at its pre-grow length, while the
+ * shared buffer grows in place. */
+export interface WorkerStart {
+    readonly store: SharedArrayBuffer | WebAssembly.Memory;
+    readonly storeBase: number;
+    readonly control: SharedArrayBuffer;
+    readonly index: number;
+    readonly count: number;
+    /** Bytes of shadow stack one instance of a `wasm` kernel module gets, or 0
+     * when the caller named none. At 0 the worker divides the whole span between
+     * the module's `__heap_base` and the store base, which leaves the module no
+     * heap. */
+    readonly stackBytes: number;
+}
+/** One kernel a worker loads, addressed by its slot for the rest of the run.
+ * A worker cannot receive a closure, which is why a kernel is a module and an
+ * export name. */
+export interface KernelMessage {
+    readonly type: "kernel";
+    readonly slot: number;
+    /** A compiled module, structured-clone safe, shared with every worker. */
+    readonly wasm?: WebAssembly.Module;
+    /** An absolute module URL the worker imports. */
+    readonly js?: string;
+    readonly exportName: string;
+    /** `(component_id, field_id)` pairs, flat, in the kernel's argument order. */
+    readonly specs: Int32Array;
+}
+/** Re-enter the barrier loop. */
+export interface RunMessage {
+    readonly type: "run";
+}
+export type HostMessage = KernelMessage | RunMessage;
+export interface WorkerReply {
+    /** `ready` once at start, `kernel` for one registration, `yielded` when the
+     * worker leaves the barrier loop. */
+    readonly type: "ready" | "kernel" | "yielded";
+    readonly slot?: number;
+    /** The failure text, when a kernel would not load. */
+    readonly error?: string;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/plugins/workers/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../src/plugins/workers/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;KAgBK;AAIL,6DAA6D;AAC7D,eAAO,MAAM,SAAS,IAAI,CAAC;AAC3B;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,IAAI,CAAC;AAC1B,kEAAkE;AAClE,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,8EAA8E;AAC9E,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,4EAA4E;AAC5E,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,yEAAyE;AACzE,eAAO,MAAM,WAAW,QAAqC,CAAC;AAC9D,eAAO,MAAM,eAAe,QAAqC,CAAC;AAIlE;oDACoD;AACpD,eAAO,MAAM,MAAM,QAAuB,CAAC;AAE3C,eAAO,MAAM,aAAa,QAAmB,CAAC;AAE9C;;8BAE8B;AAC9B,eAAO,MAAM,SAAS,KAAK,CAAC;AAC5B,uCAAuC;AACvC,eAAO,MAAM,QAAQ,KAAK,CAAC;AAI3B;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;;;;mCAImC;AACnC,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,WAAW,CAAC,MAAM,CAAC;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;eAGW;IACX,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED;;kBAEkB;AAClB,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC;IACnC,iDAAiD;IACjD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC3B;AAED,iCAAiC;AACjC,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;CACrB;AAED,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;AAErD,MAAM,WAAW,WAAW;IAC3B;yCACqC;IACrC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/plugins/workers/worker_bind.d.cts

@@ -0,0 +1,64 @@
+/***
+ * The worker's whole view of the world: a walk of the store bytes.
+ *
+ * A worker holds the store buffer and the store base, and nothing else. The
+ * archetype graph, the component registry and the query cache are main-thread
+ * objects. The header, the layout descriptor and the columns are bytes, so a
+ * worker resolves a dense query and finds a column from `(component_id,
+ * field_id)` alone. This file is that walk.
+ *
+ * Every offset the store writes is measured from the store base, so each read
+ * here adds the base.
+ *
+ * The walk is linear in the total column count and is not free. Run it when
+ * `view_stamp` moves, and cache what it gives back.
+ *
+ * This module imports the ABI constants and nothing else. The worker entry runs
+ * outside the bundler, so every import in its chain names the file with its
+ * extension.
+ ***/
+type ColumnView = Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array;
+/** One matched archetype, bound for one kernel. */
+export interface BoundArchetype {
+    /** Where this archetype's descriptor starts, so the enabled row count can be
+     * re-read each frame without another walk. */
+    readonly descriptorOff: number;
+    /** A typed array over each declared column, spanning the whole archetype.
+     * Empty for a wasm kernel, which addresses bytes instead. */
+    readonly views: ColumnView[];
+    /** The absolute byte offset of each declared column's first row. Empty for a
+     * js kernel, which indexes a view instead. */
+    readonly offsets: number[];
+}
+export declare function readViewStamp(buffer: ArrayBufferLike, storeBase: number): number;
+/** The enabled row count of one bound archetype, without another walk. The host
+ * republishes it before every dispatch, so a worker that caches its bind still
+ * reads a fresh count each frame. */
+export declare function readEnabledCount(buffer: ArrayBufferLike, descriptorOff: number): number;
+/**
+ * Walk the descriptor region once and bind every archetype the masks match.
+ *
+ * `specs` is a flat list of `(component_id, field_id)` pairs in the kernel's
+ * argument order, so a kernel indexes and never searches. An archetype that
+ * matches the masks but lacks one named column is skipped, which is what keeps
+ * a tag-only archetype out of the list.
+ *
+ * `wantViews` picks the bind form. A js kernel takes typed arrays, a wasm
+ * kernel takes byte offsets. Building both would cost one allocation per column
+ * that no kernel reads.
+ *
+ * Cold path. Call it on a `view_stamp` change.
+ */
+export declare function bindArchetypes(buffer: ArrayBufferLike, storeBase: number, specs: Int32Array, include: Uint32Array, exclude: Uint32Array | null, wantViews: boolean): BoundArchetype[];
+/**
+ * The half-open row range worker `index` owns of an archetype with `rows`
+ * enabled rows.
+ *
+ * Every worker computes this from the same inputs with the same integer
+ * arithmetic, so no plan crosses the wire and no two workers can disagree about
+ * who owns a row. The main thread never computes it, which is what makes the
+ * split deterministic.
+ */
+export declare function rangeBegin(rows: number, index: number, count: number): number;
+export {};
+//# sourceMappingURL=worker_bind.d.ts.map

package/dist/plugins/workers/worker_bind.d.ts

@@ -0,0 +1,64 @@
+/***
+ * The worker's whole view of the world: a walk of the store bytes.
+ *
+ * A worker holds the store buffer and the store base, and nothing else. The
+ * archetype graph, the component registry and the query cache are main-thread
+ * objects. The header, the layout descriptor and the columns are bytes, so a
+ * worker resolves a dense query and finds a column from `(component_id,
+ * field_id)` alone. This file is that walk.
+ *
+ * Every offset the store writes is measured from the store base, so each read
+ * here adds the base.
+ *
+ * The walk is linear in the total column count and is not free. Run it when
+ * `view_stamp` moves, and cache what it gives back.
+ *
+ * This module imports the ABI constants and nothing else. The worker entry runs
+ * outside the bundler, so every import in its chain names the file with its
+ * extension.
+ ***/
+type ColumnView = Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array;
+/** One matched archetype, bound for one kernel. */
+export interface BoundArchetype {
+    /** Where this archetype's descriptor starts, so the enabled row count can be
+     * re-read each frame without another walk. */
+    readonly descriptorOff: number;
+    /** A typed array over each declared column, spanning the whole archetype.
+     * Empty for a wasm kernel, which addresses bytes instead. */
+    readonly views: ColumnView[];
+    /** The absolute byte offset of each declared column's first row. Empty for a
+     * js kernel, which indexes a view instead. */
+    readonly offsets: number[];
+}
+export declare function readViewStamp(buffer: ArrayBufferLike, storeBase: number): number;
+/** The enabled row count of one bound archetype, without another walk. The host
+ * republishes it before every dispatch, so a worker that caches its bind still
+ * reads a fresh count each frame. */
+export declare function readEnabledCount(buffer: ArrayBufferLike, descriptorOff: number): number;
+/**
+ * Walk the descriptor region once and bind every archetype the masks match.
+ *
+ * `specs` is a flat list of `(component_id, field_id)` pairs in the kernel's
+ * argument order, so a kernel indexes and never searches. An archetype that
+ * matches the masks but lacks one named column is skipped, which is what keeps
+ * a tag-only archetype out of the list.
+ *
+ * `wantViews` picks the bind form. A js kernel takes typed arrays, a wasm
+ * kernel takes byte offsets. Building both would cost one allocation per column
+ * that no kernel reads.
+ *
+ * Cold path. Call it on a `view_stamp` change.
+ */
+export declare function bindArchetypes(buffer: ArrayBufferLike, storeBase: number, specs: Int32Array, include: Uint32Array, exclude: Uint32Array | null, wantViews: boolean): BoundArchetype[];
+/**
+ * The half-open row range worker `index` owns of an archetype with `rows`
+ * enabled rows.
+ *
+ * Every worker computes this from the same inputs with the same integer
+ * arithmetic, so no plan crosses the wire and no two workers can disagree about
+ * who owns a row. The main thread never computes it, which is what makes the
+ * split deterministic.
+ */
+export declare function rangeBegin(rows: number, index: number, count: number): number;
+export {};
+//# sourceMappingURL=worker_bind.d.ts.map

package/dist/plugins/workers/worker_bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker_bind.d.ts","sourceRoot":"","sources":["../../../src/plugins/workers/worker_bind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;KAkBK;AAWL,KAAK,UAAU,GACZ,UAAU,GACV,SAAS,GACT,WAAW,GACX,UAAU,GACV,WAAW,GACX,UAAU,GACV,YAAY,GACZ,YAAY,CAAC;AAehB,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC9B;kDAC8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;iEAC6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,CAAC;IAC7B;kDAC8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEhF;AAED;;qCAEqC;AACrC,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAKvF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,SAAS,EAAE,OAAO,GAChB,cAAc,EAAE,CA4DlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7E"}