@ecsia/scheduler 0.1.0

package/dist/workers/manifest.d.ts

@@ -0,0 +1,67 @@
+import type { SharedHandleManifest } from '@ecsia/core';
+/** Dense component-id assignment so the worker aligns ids identically. */
+export interface ComponentManifestEntry {
+    readonly name: string;
+    readonly id: number;
+    /** Per-field word counts (declaration order) so the worker rebuilds the payload codec. */
+    readonly fieldWords: readonly number[];
+}
+export interface WorkerBootstrap {
+    readonly workerIndex: number;
+    /** Module URL the worker imports to obtain its system kernels by name (the dispatch mechanism). */
+    readonly kernelModule: string;
+    /** System names indexed by SystemId (the POOL's registration order) — the kernel lookup key. */
+    readonly systemNames: readonly string[];
+    /** The shared buffer set (SAB columns + regions), by reference. */
+    readonly buffers: SharedHandleManifest;
+    readonly indexBitsMask: number;
+    /** Dense component-id registry the worker aligns to. */
+    readonly components: readonly ComponentManifestEntry[];
+    /** Per-worker control SABs. */
+    readonly commandSab: SharedArrayBuffer;
+    readonly reservationSab: SharedArrayBuffer;
+    readonly reservationCapacity: number;
+    readonly waveSab: SharedArrayBuffer;
+    /** Work descriptor SAB: [0]=systemId [1]=count [2]=dtBits(f32) [3..]=entity indices. */
+    readonly workSab: SharedArrayBuffer;
+    /** Wake SAB: the worker Atomics.waits on [0]; the main thread bumps it + notifies to dispatch. */
+    readonly wakeSab: SharedArrayBuffer;
+    /**
+     * Re-backing signal SAB. Word [0] = the column
+     * re-backing generation the main thread last published. When the worker is woken and finds [0] !=
+     * its last-applied generation, the wake is a NOTICE round: it `await`s the queued `columns-added`
+     * postMessage (the only transport that can carry a new SharedArrayBuffer reference), re-wraps the
+     * named columns, then completes the wave fence as its ACK — all BEFORE the next dispatch. Steady
+     * state ([0] unchanged) costs one extra Atomics.load per wave.
+     */
+    readonly noticeSab: SharedArrayBuffer;
+    /**
+     * Per-worker write-corral SAB: the worker stages value writes here as
+     * `[count, index0, componentId0, index1, componentId1, …]`. Word [0] is the entry count; the main
+     * thread reads it after the fence and merges into the shared write log in worker-index order. No
+     * atomics on the worker push path — it is single-writer, drained only after the wave fence.
+     */
+    readonly writeCorralSab: SharedArrayBuffer;
+}
+/** A message the main thread posts to ask a worker to run one batch (used in the postMessage tier). */
+export interface DispatchMessage {
+    readonly kind: 'dispatch';
+    readonly systemId: number;
+    readonly dt: number;
+    readonly indices: Int32Array;
+}
+/**
+ * The re-backing broadcast. Posted to each worker at the wave fence carrying
+ * the NEW SharedArrayBuffer backings (by reference — SABs cannot ride a SAB) so the worker re-wraps
+ * its stale column views. `generation` matches `noticeSab[0]`; the worker ACKs via the wave fence.
+ */
+export interface ColumnsAddedMessage {
+    readonly kind: 'columns-added';
+    readonly generation: number;
+    readonly columns: ReadonlyArray<{
+        key: string;
+        backing: SharedArrayBuffer;
+        layout: import('@ecsia/core').ColumnLayout;
+    }>;
+}
+//# sourceMappingURL=manifest.d.ts.map

package/dist/workers/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/workers/manifest.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAEvD,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,0FAA0F;IAC1F,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,mGAAmG;IACnG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,gGAAgG;IAChG,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,SAAS,sBAAsB,EAAE,CAAA;IACtD,+BAA+B;IAC/B,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAA;IACtC,QAAQ,CAAC,cAAc,EAAE,iBAAiB,CAAA;IAC1C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IACpC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;IACnC,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;IACnC,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAA;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,iBAAiB,CAAA;CAC3C;AAED,uGAAuG;AACvG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,iBAAiB,CAAC;QAAC,MAAM,EAAE,OAAO,aAAa,EAAE,YAAY,CAAA;KAAE,CAAC,CAAA;CACzH"}

package/dist/workers/manifest.js

@@ -0,0 +1,5 @@
+// The workerData payload posted ONCE per worker at pool startup (). Carries the shared buffer set (by reference — SABs are sharable, NOT transferred)
+// plus the per-worker control SABs the dispatch loop uses. No component VALUES are ever serialized
+// (zero-copy): the worker reads live SAB columns.
+export {};
+//# sourceMappingURL=manifest.js.map

package/dist/workers/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/workers/manifest.ts"],"names":[],"mappings":"AAAA,sJAAsJ;AACtJ,mGAAmG;AACnG,kDAAkD"}

package/dist/workers/pool.d.ts

@@ -0,0 +1,60 @@
+import type { World } from '@ecsia/core';
+import type { ComponentDef, Schema, SystemId } from '@ecsia/schema';
+import type { ComponentFieldCodec } from '../commands/index.js';
+import type { WorkerSystemKernel } from './worker-system.js';
+/** A worker-eligible system registered with the pool, indexed by SystemId (registration order). */
+export interface PoolSystem {
+    readonly id: SystemId;
+    readonly name: string;
+    readonly matchComponents: readonly ComponentDef<Schema>[];
+    readonly kernel: WorkerSystemKernel;
+    readonly maxSpawnsPerWave: number;
+}
+export interface PoolConfig {
+    readonly world: World;
+    readonly workers: number;
+    /** Module URL the workers import for their kernels (the dispatch mechanism). */
+    readonly kernelModule: string;
+    readonly systems: readonly PoolSystem[];
+    /**
+     * Every component a worker may touch — read, written, OR named as an add/set-payload target. Their
+     * dense ids are aligned on the worker side. Defaults to the union of all
+     * systems' matchComponents; pass the full registered set if a kernel adds a component it does not
+     * also match (e.g. a spawner adding a component to a fresh entity).
+     */
+    readonly components?: readonly ComponentDef<Schema>[];
+    /** Max matched entities per batch dispatch (work SAB sizing). Default: maxEntities. */
+    readonly maxBatchEntities?: number;
+    readonly commandWords?: number;
+    /**
+     * Max `(index, componentId)` value-write entries one worker may stage per wave (write-corral SAB
+     * sizing). Default: maxBatchEntities × 4 (a kernel may write a few components
+     * per matched entity). Excess writes are capped (diagnosed at merge), never dropped silently.
+     */
+    readonly writeCorralEntries?: number;
+    readonly diagnostic?: (message: string) => void;
+    /**
+     * Override the worker-entry module URL. Defaults to the dist sibling of this module. Tests running
+     * over TS source (vitest aliases) MUST pass the BUILT `dist/workers/worker-entry.js` URL, because a
+     * raw Node worker_threads Worker has no TS transform and no path aliasing.
+     */
+    readonly workerEntryUrl?: string;
+}
+export declare class WorkerPool {
+    #private;
+    constructor(cfg: PoolConfig);
+    /** Wait until every spawned worker has posted 'ready' (bootstrap complete). */
+    ready(): Promise<void>;
+    /**
+     * Run one round: dispatch each (systemId, workerIndex) batch to its worker, wait on the fence, then
+     * merge the per-worker command buffers in fixed worker-index order. `world.phase` is 'wave' across
+     * the dispatch (PHASE-2) and flipped back to 'serial' for the merge/apply flush slot.
+     */
+    runRound(batches: readonly {
+        systemId: SystemId;
+        workerIndex: number;
+    }[], dt: number): Promise<void>;
+    dispose(): Promise<void>;
+    get codecById(): ReadonlyMap<number, ComponentFieldCodec>;
+}
+//# sourceMappingURL=pool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/workers/pool.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,KAAK,EAAe,MAAM,aAAa,CAAA;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAGnE,OAAO,KAAK,EAA6B,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAO1F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D,mGAAmG;AACnG,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,eAAe,EAAE,SAAS,YAAY,CAAC,MAAM,CAAC,EAAE,CAAA;IACzD,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;IACnC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CAClC;AAiBD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,gFAAgF;IAChF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAA;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,YAAY,CAAC,MAAM,CAAC,EAAE,CAAA;IACrD,uFAAuF;IACvF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CACjC;AAKD,qBAAa,UAAU;;gBAeT,GAAG,EAAE,UAAU;IAuF3B,+EAA+E;IACzE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;;;OAIG;IACG,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2KpG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAW9B,IAAI,SAAS,IAAI,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAExD;CACF"}

package/dist/workers/pool.js

@@ -0,0 +1,313 @@
+// The worker pool + wave dispatch loop. At startup it allocates the per-worker
+// control SABs, exports the world's shared buffer set ONCE (by reference, never per frame), and
+// spawns a fixed worker pool. Per round it: tops up each worker's
+// reservation (reserveEntityBlock — the Atomics.sub take path is now exercised on the worker side),
+// flips world.phase to 'wave', writes each batch's matched entity indices + dt into the worker's work
+// SAB, bumps the wake word, and waits on the Atomics wave fence; then flips back to 'serial' and merges
+// the per-worker command buffers DETERMINISTICALLY (ascending worker index — flushAll). That fixed
+// merge order is what makes the multi-worker run SERIAL-EQUIVALENT despite nondeterministic completion.
+//
+// Tier: Node main thread blocks on the wave fence directly (selectWaitTier → 'coordinator-block');
+// workers block on their wake word OFF the main thread, so there is no deadlock. NO-SAB contexts take
+// the postMessage fallback (transfer columns per wave) — emitted with a diagnostic, never silent.
+import { Worker } from 'node:worker_threads';
+import { fileURLToPath } from 'node:url';
+import { handleIndex } from '@ecsia/core';
+import { has } from '@ecsia/schema';
+import { makeCommandBuffer, resetBuffer, flushAll, buildFieldCodec } from '../commands/index.js';
+import { makeWaveCounter, makeWaveSync, workerHead, waveErrored } from './wave-sync.js';
+import { selectWaitTier } from '../executor/seams.js';
+import { makeReservationSab, fillReservation, consumedCount } from './reservation.js';
+const WAKE = 0;
+const WORK_HEADER_WORDS = 3; // [systemId, count, dtBits]
+export class WorkerPool {
+    #world;
+    #systems;
+    #slots = [];
+    #waveCounter;
+    #waveSync;
+    #diag;
+    #defById = new Map();
+    #codecById = new Map();
+    #wakeGen = 0;
+    // The last column-growth generation we broadcast to the workers. A cheap `!==` against the
+    // world's live generation gates the whole re-backing fence — zero work when nothing re-backed.
+    #appliedGrowthGen = 0;
+    #disposed = false;
+    constructor(cfg) {
+        this.#world = cfg.world;
+        this.#systems = cfg.systems;
+        this.#diag = cfg.diagnostic ?? ((m) => console.warn(`[ecsia] ${m}`));
+        const caps = cfg.world.options; // (capabilities live on the world; tier from the probe below)
+        void caps;
+        const manifest = cfg.world.__exportShared();
+        if (manifest.regions.length === 0 && manifest.columns.length === 0) {
+            this.#diag('threaded:true requested but no SAB-backed buffers are available (cross-origin isolation absent or SAB unavailable); ' +
+                'the pool cannot share columns by reference. Run single-threaded instead.');
+        }
+        const components = [];
+        const allDefs = cfg.components ?? [...new Set(cfg.systems.flatMap((s) => [...s.matchComponents]))];
+        for (const def of allDefs) {
+            const id = def.id;
+            if (!this.#defById.has(id)) {
+                const codec = buildFieldCodec(def);
+                this.#defById.set(id, def);
+                this.#codecById.set(id, codec);
+                components.push({ name: def.name, id, fieldWords: [codec.totalWords] });
+            }
+        }
+        this.#waveCounter = makeWaveCounter(cfg.workers);
+        const tier = selectWaitTier({
+            waitAsync: false, // Node main thread blocks directly (tier 2); browser-main would set this true
+            waitBlocking: typeof Atomics.wait === 'function',
+            sabAvailable: typeof SharedArrayBuffer === 'function',
+        });
+        this.#waveSync = makeWaveSync(tier);
+        const maxBatch = cfg.maxBatchEntities ?? cfg.world.options.maxEntities;
+        const corralEntries = cfg.writeCorralEntries ?? maxBatch * 4;
+        const reservationCap = Math.max(...cfg.systems.map((s) => s.maxSpawnsPerWave), 1);
+        const here = fileURLToPath(import.meta.url);
+        const entryUrl = cfg.workerEntryUrl ?? here.replace(/pool\.(js|ts)$/, 'worker-entry.$1');
+        for (let i = 0; i < cfg.workers; i++) {
+            const command = makeCommandBuffer(i, cfg.commandWords ?? 1 << 14, true);
+            const reservation = makeReservationSab(reservationCap);
+            const workSab = new SharedArrayBuffer((WORK_HEADER_WORDS + maxBatch) * 4);
+            const wakeSab = new SharedArrayBuffer(4);
+            const noticeSab = new SharedArrayBuffer(4); // [0] = published column-growth generation
+            // Write-corral SAB: 1 header word (count) + 2 words per staged entry.
+            const writeCorralSab = new SharedArrayBuffer((1 + corralEntries * 2) * 4);
+            const boot = {
+                workerIndex: i,
+                kernelModule: cfg.kernelModule,
+                systemNames: cfg.systems.map((s) => s.name),
+                buffers: manifest,
+                indexBitsMask: cfg.world.handleLayout.indexMask,
+                components,
+                commandSab: command.words.buffer,
+                reservationSab: reservation.sab,
+                reservationCapacity: reservation.capacity,
+                waveSab: this.#waveCounter.sab,
+                workSab,
+                wakeSab,
+                noticeSab,
+                writeCorralSab,
+            };
+            const worker = new Worker(entryUrl, { workerData: boot });
+            const slot = {
+                index: i,
+                worker,
+                command,
+                reservation,
+                work: { sab: workSab, i32: new Int32Array(workSab), f32: new Float32Array(workSab) },
+                wake: new Int32Array(wakeSab),
+                notice: new Int32Array(noticeSab),
+                writeCorral: new Uint32Array(writeCorralSab),
+                ready: false,
+            };
+            worker.on('message', (msg) => {
+                if (msg.kind === 'ready')
+                    slot.ready = true;
+                else if (msg.kind === 'diagnostic' || msg.kind === 'error')
+                    this.#diag(msg.message ?? 'worker error');
+            });
+            worker.on('error', (err) => this.#diag(`worker ${i} crashed: ${String(err)}`));
+            this.#slots.push(slot);
+        }
+    }
+    /** Wait until every spawned worker has posted 'ready' (bootstrap complete). */
+    async ready() {
+        const deadline = Date.now() + 5000;
+        while (this.#slots.some((s) => !s.ready)) {
+            if (Date.now() > deadline)
+                throw new Error('worker pool bootstrap timed out');
+            await new Promise((r) => setTimeout(r, 1));
+        }
+    }
+    /**
+     * Run one round: dispatch each (systemId, workerIndex) batch to its worker, wait on the fence, then
+     * merge the per-worker command buffers in fixed worker-index order. `world.phase` is 'wave' across
+     * the dispatch (PHASE-2) and flipped back to 'serial' for the merge/apply flush slot.
+     */
+    async runRound(batches, dt) {
+        if (this.#disposed)
+            throw new Error('worker pool disposed');
+        const active = batches.filter((b) => b.workerIndex >= 0 && b.workerIndex < this.#slots.length);
+        if (active.length === 0)
+            return;
+        // ---- re-backing fence: re-wrap any column that moved to a NEW SAB since the last dispatch
+        // BEFORE this one proceeds. One generation `!==` per wave when nothing grew (zero steady-state cost).
+        await this.#drainColumnGrowth();
+        // ---- reservation top-up (serial) ----
+        for (const b of active) {
+            const slot = this.#slots[b.workerIndex];
+            const sys = this.#systems[b.systemId];
+            const block = this.#world.reserveEntityBlock(b.workerIndex, sys.maxSpawnsPerWave);
+            fillReservation(slot.reservation, block);
+            slot.command.lastReservation = block;
+            resetBuffer(slot.command);
+        }
+        // ---- compute matched entity indices on the MAIN thread (bitmask-free archetype matching) ----
+        for (const b of active) {
+            const slot = this.#slots[b.workerIndex];
+            const sys = this.#systems[b.systemId];
+            const indices = this.#matchedIndices(sys);
+            const work = slot.work;
+            Atomics.store(work.i32, 0, b.systemId);
+            Atomics.store(work.i32, 1, indices.length);
+            work.f32[2] = dt;
+            indices.forEach((idx, k) => {
+                work.i32[WORK_HEADER_WORDS + k] = idx;
+            });
+        }
+        // ---- dispatch: flip to 'wave', arm the fence, wake the workers ----
+        this.#world.__setPhase('wave');
+        this.#waveSync.begin(this.#waveCounter, active.length);
+        this.#wakeGen += 1;
+        for (const b of active) {
+            const slot = this.#slots[b.workerIndex];
+            Atomics.store(slot.wake, WAKE, this.#wakeGen);
+            Atomics.notify(slot.wake, WAKE);
+        }
+        // ---- wait on the wave fence (Node main blocks directly, tier 2) ----
+        const r = this.#waveSync.await(this.#waveCounter);
+        if (r !== undefined)
+            await r;
+        // ---- serial flush slot: flip back, merge command buffers deterministically ----
+        this.#world.__setPhase('serial');
+        if (waveErrored(this.#waveCounter))
+            this.#diag('a worker system threw; its command buffer is applied/dropped per CB-SAFE');
+        // Merge each worker's value-write corral into the shared write log in ASCENDING worker-index order
+        // BEFORE the command buffers apply — mirroring single-thread run-wave's
+        // mergeCorrals()→flushAll() order. This is what makes onChange observers + `.changed` filters fire
+        // for worker field writes (and stamp changeVersion) deterministically.
+        const writers = active.map((b) => b.workerIndex).sort((a, z) => a - z);
+        const corralHeader = 1;
+        for (const wi of writers) {
+            const slot = this.#slots[wi];
+            const corral = slot.writeCorral;
+            const count = corral[0] >>> 0;
+            const capPairs = (corral.length - corralHeader) >>> 1;
+            if (count > capPairs) {
+                this.#diag(`worker ${wi} write-corral overflow (${count} > ${capPairs} entries); merged ${capPairs} (raise writeCorralEntries)`);
+            }
+            const merged = Math.min(count, capPairs);
+            if (merged > 0) {
+                this.#world.__mergeWorkerWrites(corral.subarray(corralHeader, corralHeader + merged * 2), merged);
+            }
+            corral[0] = 0;
+        }
+        const bufs = [];
+        for (const b of active) {
+            const slot = this.#slots[b.workerIndex];
+            const reported = workerHead(this.#waveCounter, b.workerIndex);
+            const cap = slot.command.words.length;
+            // Hard clamp: the worker writes the SAB in place, so a `head` that exceeds the SAB length would
+            // make the apply decode read past the backing (undefined → NaN opcode → 'corrupt command buffer').
+            // The worker's overflow cap (ensureWords/fixed) should make this unreachable; clamp + diagnose so
+            // a corrupt/over-large head can never crash apply (review issue #3).
+            if (reported > cap) {
+                this.#diag(`worker ${b.workerIndex} reported head ${reported} > command SAB capacity ${cap}; clamped (records lost — raise commandWords)`);
+                slot.command.head = cap;
+            }
+            else {
+                slot.command.head = reported;
+            }
+            bufs.push(slot.command);
+        }
+        bufs.sort((a, z) => a.workerIndex - z.workerIndex);
+        flushAll(this.#worldApply(), bufs);
+    }
+    /**
+     * (the world's
+     * growth generation advanced), broadcast the new backings to EVERY worker and block on the wave fence
+     * until all have re-wrapped + ACKed — so no dispatch ever reads a worker's stale (abandoned-SAB) view.
+     * Steady state is a single generation `!==`; the drain + broadcast happen only on an actual re-backing.
+     */
+    async #drainColumnGrowth() {
+        const log = this.#world.__columnGrowth();
+        if (log.generation === this.#appliedGrowthGen)
+            return; // nothing re-backed — the steady-state path
+        const gen = log.generation;
+        const notices = log.drain();
+        if (notices.length > 0) {
+            const msg = {
+                kind: 'columns-added',
+                generation: gen,
+                columns: notices.map((n) => ({ key: n.key, backing: n.backing, layout: n.layout })),
+            };
+            // Arm the fence for every worker (each ACKs by completing the wave once it has re-wrapped).
+            this.#world.__setPhase('wave');
+            this.#waveSync.begin(this.#waveCounter, this.#slots.length);
+            this.#wakeGen += 1;
+            for (const slot of this.#slots) {
+                slot.worker.postMessage(msg); // SAB references can ONLY ride postMessage, not a SAB
+                Atomics.store(slot.notice, 0, gen);
+                Atomics.store(slot.wake, WAKE, this.#wakeGen);
+                Atomics.notify(slot.wake, WAKE);
+            }
+            const r = this.#waveSync.await(this.#waveCounter);
+            if (r !== undefined)
+                await r;
+            this.#world.__setPhase('serial');
+        }
+        this.#appliedGrowthGen = gen;
+    }
+    #matchedIndices(sys) {
+        if (sys.matchComponents.length === 0)
+            return new Int32Array(0);
+        const terms = sys.matchComponents.map((c) => has(c));
+        const q = this.#world.query(...terms);
+        const out = [];
+        for (const idx of q.current)
+            out.push(idx);
+        return Int32Array.from(out);
+    }
+    #worldApply() {
+        const world = this.#world;
+        const layout = world.handleLayout;
+        const apply = world.__apply;
+        const codecById = this.#codecById;
+        return {
+            isAlive: (h) => world.isAlive(h),
+            handleIndex: (h) => handleIndex(h, layout),
+            spawnReserved: (h) => world.__spawnReserved(h),
+            despawn: (h) => world.despawn(h),
+            defOf: (id) => apply.defOf(id),
+            codecOf: (id) => codecById.get(id),
+            addMany: (h, defs) => apply.addMany(h, defs),
+            removeMany: (h, defs) => apply.removeMany(h, defs),
+            has: (h, def) => world.has(h, def),
+            writePayload: (h, def, values) => apply.writePayload(h, def, values),
+            // Relation apply: forward to the core __apply surface that @ecsia/relations
+            // fills in via createRelations(world). The scheduler does NOT import @ecsia/relations.
+            addPair: (s, rid, t, payload) => apply.addPair?.(s, rid, t, payload),
+            removePair: (s, rid, t) => apply.removePair?.(s, rid, t),
+            returnUnused: (cb) => {
+                const slot = this.#slots[cb.workerIndex];
+                const block = slot?.command.lastReservation;
+                if (slot !== undefined && block !== undefined) {
+                    const filled = Math.min(block.handles.length, slot.reservation.capacity);
+                    const consumed = consumedCount(slot.reservation, filled);
+                    // returnReservedIds reclaims the unconsumed tail [consumed..]; clamp to the block size.
+                    world.returnReservedIds(block, Math.min(consumed, block.handles.length));
+                }
+            },
+            warn: (m) => this.#diag(m),
+        };
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#wakeGen = -1;
+        for (const slot of this.#slots) {
+            Atomics.store(slot.wake, WAKE, -1);
+            Atomics.notify(slot.wake, WAKE);
+        }
+        await Promise.all(this.#slots.map((s) => s.worker.terminate()));
+    }
+    get codecById() {
+        return this.#codecById;
+    }
+}
+//# sourceMappingURL=pool.js.map

package/dist/workers/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../src/workers/pool.ts"],"names":[],"mappings":"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"}

package/dist/workers/reservation.d.ts

@@ -0,0 +1,18 @@
+import type { EntityHandle, EntityReservation } from '@ecsia/core';
+export interface WorkerReservationSab {
+    readonly sab: SharedArrayBuffer;
+    readonly view: Int32Array;
+    readonly capacity: number;
+}
+export declare function makeReservationSab(capacity: number): WorkerReservationSab;
+/** Main thread, serial: fill the SAB with a freshly-reserved block and reset the take cursor. */
+export declare function fillReservation(r: WorkerReservationSab, reservation: EntityReservation): void;
+/** Worker, mid-wave: take the next reserved handle via Atomics.sub, or NO_ENTITY (-1) if exhausted. */
+export declare function takeReserved(r: WorkerReservationSab): EntityHandle;
+/**
+ * Count of reserved handles the worker actually took = filled - remaining. `filled` is the block size
+ * the main thread wrote (NOT the SAB capacity, which may exceed the block), so a 0-handle block reports
+ * 0 consumed even though the SAB reserves a larger cursor capacity.
+ */
+export declare function consumedCount(r: WorkerReservationSab, filled: number): number;
+//# sourceMappingURL=reservation.d.ts.map

package/dist/workers/reservation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reservation.d.ts","sourceRoot":"","sources":["../../src/workers/reservation.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAKlE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,CAIzE;AAED,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,CAAC,EAAE,oBAAoB,EAAE,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAI7F;AAED,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,CAAC,EAAE,oBAAoB,GAAG,YAAY,CAOlE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG7E"}

package/dist/workers/reservation.js

@@ -0,0 +1,41 @@
+// SAB-backed per-worker entity-ID reservation. The main
+// thread pre-reserves a block of fully-formed (alive) handles per worker before each wave via the
+// serial `world.reserveEntityBlock` ( layout), writes the handles into a SAB, and the worker TAKES
+// them mid-wave with `Atomics.sub` on a cursor word — exercising the Atomics.sub take path (the
+// v2 ) without ever touching the shared free-list.
+//
+// SAB layout per worker: word 0 = cursor (next free slot, counts DOWN via Atomics.sub),
+// words [1 .. 1+capacity) = the reserved full handles. A take of cursor c yields handles[c-1].
+const CURSOR = 0;
+const HANDLES_BASE = 1;
+export function makeReservationSab(capacity) {
+    const cap = Math.max(capacity, 0);
+    const sab = new SharedArrayBuffer((1 + cap) * 4);
+    return { sab, view: new Int32Array(sab), capacity: cap };
+}
+/** Main thread, serial: fill the SAB with a freshly-reserved block and reset the take cursor. */
+export function fillReservation(r, reservation) {
+    const n = Math.min(reservation.handles.length, r.capacity);
+    for (let i = 0; i < n; i++)
+        r.view[HANDLES_BASE + i] = reservation.handles[i];
+    Atomics.store(r.view, CURSOR, n); // cursor counts down; n handles available
+}
+/** Worker, mid-wave: take the next reserved handle via Atomics.sub, or NO_ENTITY (-1) if exhausted. */
+export function takeReserved(r) {
+    const prev = Atomics.sub(r.view, CURSOR, 1);
+    if (prev <= 0) {
+        Atomics.add(r.view, CURSOR, 1); // undo: do not let the cursor run negative
+        return 0xffffffff;
+    }
+    return (r.view[HANDLES_BASE + (prev - 1)] >>> 0);
+}
+/**
+ * Count of reserved handles the worker actually took = filled - remaining. `filled` is the block size
+ * the main thread wrote (NOT the SAB capacity, which may exceed the block), so a 0-handle block reports
+ * 0 consumed even though the SAB reserves a larger cursor capacity.
+ */
+export function consumedCount(r, filled) {
+    const remaining = Math.max(Atomics.load(r.view, CURSOR), 0);
+    return Math.max(filled - remaining, 0);
+}
+//# sourceMappingURL=reservation.js.map

package/dist/workers/reservation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reservation.js","sourceRoot":"","sources":["../../src/workers/reservation.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,kGAAkG;AAClG,mGAAmG;AACnG,gGAAgG;AAChG,mDAAmD;AACnD,EAAE;AACF,wFAAwF;AACxF,+FAA+F;AAI/F,MAAM,MAAM,GAAG,CAAC,CAAA;AAChB,MAAM,YAAY,GAAG,CAAC,CAAA;AAQtB,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAA;IACjC,MAAM,GAAG,GAAG,IAAI,iBAAiB,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;IAChD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAA;AAC1D,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,eAAe,CAAC,CAAuB,EAAE,WAA8B;IACrF,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAA;IAC1D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;QAAE,CAAC,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,CAAW,CAAA;IACvF,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA,CAAC,0CAA0C;AAC7E,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,YAAY,CAAC,CAAuB;IAClD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;IAC3C,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACd,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA,CAAC,2CAA2C;QAC1E,OAAO,UAA0B,CAAA;IACnC,CAAC;IACD,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAE,KAAK,CAAC,CAAiB,CAAA;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,CAAuB,EAAE,MAAc;IACnE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAA;IAC3D,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC,CAAC,CAAA;AACxC,CAAC"}

package/dist/workers/wave-sync.d.ts

@@ -0,0 +1,18 @@
+import type { WaveCounter, WaveSync, WaveSyncTier } from '../executor/seams.js';
+/**
+ * Words [0..3] are the control block (remaining, epoch, errorFlag, padding); words [4..4+workers)
+ * are the per-worker buffer `head` each worker stores before completing, so the main thread reads the
+ * record count after the fence without any postMessage on the hot path (tier-2 blocking-main path).
+ */
+export declare function makeWaveCounter(workers: number): WaveCounter;
+export declare function workerHead(c: WaveCounter, workerIndex: number): number;
+/** Worker-side completion: the last decrementer wakes the waiter. */
+export declare function completeWave(c: WaveCounter): void;
+export declare function setWaveError(c: WaveCounter): void;
+export declare function waveErrored(c: WaveCounter): boolean;
+/**
+ * Build a WaveSync for the chosen tier. `await` MUST loop on Atomics.load(remaining) even after a
+ * wake (spurious wakeups + the epoch guard), resolving only when remaining === 0.
+ */
+export declare function makeWaveSync(tier: WaveSyncTier): WaveSync;
+//# sourceMappingURL=wave-sync.d.ts.map

package/dist/workers/wave-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wave-sync.d.ts","sourceRoot":"","sources":["../../src/workers/wave-sync.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAO/E;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAG5D;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,CAEjD;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,CAEjD;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAEnD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,CAoDzD"}